# 기여하기 (/docs/contributing) > 슈츠의 발전에 함께 참여하세요. import { Callout } from 'fumadocs-ui/components/callout'; 함께 만들어가는 슈츠 [#함께-만들어가는-슈츠] 슈츠는 커뮤니티와 함께 성장합니다. 다양한 방식으로 슈츠의 발전에 기여하고, 새로운 시대의 워크스페이스를 함께 만들어갈 기회를 얻으세요. *** 참여 방법 [#참여-방법] Slack 커뮤니티 참여 [#slack-커뮤니티-참여] [슈츠 Slack 커뮤니티](https://join.slack.com/t/suits-community/shared_invite/zt-3mx9of0jq-M9mO4wO5l5_mO4o~1sYgLQ)에 가입한 후 **#contribution** 채널에서 기여 활동에 참여할 수 있습니다. *** 기여 활동 종류 [#기여-활동-종류] 다양한 방식으로 슈츠에 기여할 수 있습니다: 개발 기여 [#개발-기여] | 활동 | 설명 | | --------------- | ------------------------------- | | **워크플로우 노드 개발** | 오픈소스로 제공될 워크플로우 노드를 개발하고 PR을 제출 | | **버그 수정** | 발견한 버그를 직접 수정하여 기여 | | **기능 구현** | 새로운 기능 아이디어를 직접 구현 | 비개발 기여 [#비개발-기여] | 활동 | 설명 | | ---------- | ----------------------------- | | **버그 제보** | 사용 중 발견한 버그나 문제점 리포트 | | **기능 제안** | 새로운 기능이나 개선 아이디어 제안 | | **디자인 기여** | UI/UX 개선안, 아이콘, 일러스트 등 디자인 기여 | | **기획 기여** | 제품 방향, 사용자 경험 개선 등 기획 아이디어 제안 | | **문서 기여** | 문서 오류 수정, 번역, 가이드 작성 | 커뮤니티 기여 [#커뮤니티-기여] | 활동 | 설명 | | ------------- | ------------------------- | | **커뮤니티 활동** | 다른 사용자의 질문에 답변, 사용 팁 공유 | | **외부 사용자 초대** | 슈츠를 필요로 하는 분들에게 소개 및 초대 | | **사례 공유** | 자신의 활용 사례를 블로그, SNS 등에 공유 | *** 기여자 혜택 [#기여자-혜택] 슈츠에 기여하시는 분들께 다음과 같은 혜택을 제공합니다: | 혜택 | 설명 | | --------------------- | ---------------------------------- | | **새로운 시대의 워크스페이스 참여** | AI 시대의 새로운 업무 방식을 함께 만들어가는 특별한 기회 | | **전용 커뮤니티 및 행사 우선권** | 기여자 전용 커뮤니티 참여 및 오프라인/온라인 행사 우선 초대 | | **워크스페이스 토큰 제공** | 기여도에 따른 워크스페이스 사용 토큰 지급 | | **기여 보상 체계** | 추후 마련될 기여자 보상 프로그램 우선 적용 | 기여는 크기와 상관없이 모두 소중합니다. 작은 버그 제보 하나도 슈츠를 더 나은 제품으로 만드는 데 큰 도움이 됩니다. *** 시작하기 [#시작하기] 1. [슈츠 Slack 커뮤니티](https://join.slack.com/t/suits-community/shared_invite/zt-3mx9of0jq-M9mO4wO5l5_mO4o~1sYgLQ)에 가입 2. **#contribution** 채널 참여 3. 관심 있는 기여 영역 선택 4. 기여 시작! 질문이 있으시면 Slack에서 언제든 물어보세요. --- # 소개 (/docs) > 성장하는 팀을 위한 AI 기반 워크스페이스, 슈츠의 사용 가이드입니다. import { Card, Cards } from 'fumadocs-ui/components/card';

슈츠 문서

슈츠에 오신 것을 환영합니다

AI와 함께 업무하는 단 하나의 워크스페이스, 슈츠를 찾아오신 걸 환영합니다. 슈츠는 AI가 업무시스템 제작, 운영, 자동화까지 함께하여 성장하는 팀과 함께 진화하는 워크스페이스입니다. 여러분의 업무를 더 효율적으로, 더 빠르게 만들어 함께 성장하겠습니다.

가격 안내 →
시작하기 [#시작하기] 콘텐츠 [#콘텐츠] 레퍼런스 [#레퍼런스] --- # Palantir vs Suits vs Notion (/docs/vs-palantir) > 팔란티어 온톨로지, Suits, Notion의 기능별 현황 비교 및 갭 분석 import { Callout } from 'fumadocs-ui/components/callout'; import { Mermaid } from '@/components/docs/Mermaid'; 배경: 왜 이 비교가 의미 있는가 [#배경-왜-이-비교가-의미-있는가] 팔란티어는 20년간 **"물리계산엔진 기반 온톨로지"** 를 구축해왔다. 비정형 현실 세계를 정형화된 계산 가능한 그래프로 변환하기 위해, 수천 개의 규칙 엔진과 전용 알고리즘을 만들었다. 그러나 LLM의 등장으로 게임의 규칙이 바뀌었다: | 전통 방식 (물리엔진) | LLM 파이프라인 방식 | | ------------------------------- | ----------------------- | | Entity Resolution → 규칙 수천 개 수작업 | LLM이 문맥으로 판별 | | 관계 추론 → 그래프 알고리즘 | LLM이 텍스트에서 관계 추출 + 추론 | | 스키마 매핑 → ETL 엔지니어 수개월 | LLM이 비정형 데이터를 구조화 | | 벡터 유사도 → 커스텀 엔진 | Embedding + 벡터DB로 즉시 가능 | | 클러스터링 → 전문 알고리즘 | LLM + 간단한 후처리로 80% 달성 | 팔란티어가 20년 동안 규칙과 알고리즘으로 해결한 것의 상당 부분을, LLM은 "이해"로 대체한다. 정확도 100%는 아니지만, **80–90% 정확도를 1/100의 시간에 달성**할 수 있다는 것이 핵심 변화다. *** 아키텍처 개요 비교 [#아키텍처-개요-비교] 포지셔닝 요약 [#포지셔닝-요약] | | Palantir | Suits | Notion | | ---------- | --------------- | ---------------------- | ----------------- | | **핵심 정체성** | 엔터프라이즈 의사결정 플랫폼 | 업무 자동화 + 협업 플랫폼 | 팀 문서 + 프로젝트 관리 도구 | | **타깃** | 국방/금융/대기업 | 중소-중견 기업 (한국 B2B) | 스타트업/개인/팀 생산성 | | **가격대** | 연 수억\~수십억 원 | SaaS 구독 | $8\~$15/월/인 | | **핵심 강점** | 온톨로지 + 그래프 탐색 | 워크플로우 103+ 노드 + 실시간 협업 | UX 단순성 + 생태계 | *** 핵심 영역별 기능 비교표 [#핵심-영역별-기능-비교표] 온톨로지 / 데이터 모델링 [#온톨로지--데이터-모델링] | 기능 | Palantir | Suits | Notion | 비고 | | -------------- | :----------: | :---: | :----: | ------------------------------------------------------------- | | 객체 타입 정의 | ✅ | ✅ | ✅ | Notion: Database, Suits: DataModel, Palantir: Object Type | | 프로퍼티 타입 | ✅ 20+종 | ✅ 17종 | ✅ 15종 | Notion: Text, Number, Select, Relation, Rollup, Formula 등 | | 관계 선언 | ✅ Link Types | ✅ | ⚠️ | Notion: 단순 Relation만 (카디널리티 제어 없음). Suits: 1:1, 1:N, N:1, N:M | | 파생 속성 | ✅ | ✅ | ✅ | 셋 다 Formula, Rollup 지원 | | 타입 상속 (서브타입) | ✅ | ❌ | ❌ | — | | 동적 스키마 변경 | ✅ | ✅ | ✅ | Notion도 런타임 프로퍼티 추가/변경 가능 | | 뷰 정의 | ✅ | ✅ 5종 | ✅ 8종 | Notion: Table/Board/Calendar/Gallery/Timeline/List/Chart/Map | | 글로벌 온톨로지 그래프 뷰 | ✅ | ⚠️ 부분 | ❌ | Notion에는 DB 간 관계를 그래프로 보는 뷰 없음 | | 버전 관리 | ✅ | ✅ | ⚠️ | Notion: 페이지 히스토리만, DB row 단위 버전 없음 | **달성도 — Palantir: ★★★★★ / Suits: ★★★★☆ (90%) / Notion: ★★★☆☆ (70%)** *** 데이터 통합 / ETL [#데이터-통합--etl] | 기능 | Palantir | Suits | Notion | 비고 | | ------------- | :------: | :----: | :----: | ------------------------------------------ | | 네이티브 커넥터 | ✅ 수백 개 | ✅ 103+ | ❌ | Notion: 자체 커넥터 없음, Zapier/Make 의존 | | 한국 B2B 특화 | ❌ | ✅ | ❌ | Suits: Cafe24, Coupang, 네이버, 다우오피스, 이카운트 등 | | 외부 데이터소스 연결 | ✅ | ✅ | ⚠️ | Notion: CSV import + API만, 직접 DB 연결 불가 | | 스케줄링 | ✅ | ✅ | ⚠️ | Notion: Agents에서 일부 스케줄 가능, cron 수준은 아님 | | Webhook 트리거 | ✅ | ✅ | ✅ | Notion: Automation에서 webhook action 지원 | | 대량 데이터 Import | ✅ | ✅ | ❌ | Notion: CSV import는 있으나 배치/retry 없음 | | 자동 스키마 매핑 | ✅ | ❌ | ❌ | — | | Data Lineage | ✅ | ❌ | ❌ | — | **달성도 — Palantir: ★★★★★ / Suits: ★★★★☆ (85%) / Notion: ★★☆☆☆ (30%)** *** 액션 프레임워크 / 워크플로우 [#액션-프레임워크--워크플로우] | 기능 | Palantir | Suits | Notion | 비고 | | -------------------- | :------: | :---: | :----: | -------------------------------------------- | | 워크플로우 실행 | ✅ | ✅ | ⚠️ | Notion: 단순 자동화 (트리거→액션), 복잡한 DAG 없음 | | 조건 분기 | ✅ | ✅ | ❌ | Notion: if/switch 분기 없음 | | 반복 처리 | ✅ | ✅ | ❌ | Notion: 배치/루프 처리 불가 | | 승인 워크플로우 | ✅ | ✅ | ❌ | Notion: 승인 프레임워크 없음 | | AI 에이전트 액션 | ✅ | ✅ | ✅ | Notion 3.0 Agents: 20분+ 자율 실행, 멀티스텝 | | 에러 핸들링 / 재시도 | ✅ | ✅ | ❌ | — | | 비주얼 워크플로우 편집 | ✅ | ✅ | ❌ | Notion: 노드 그래프 에디터 없음 | | 코드 노드 | ✅ | ✅ | ❌ | — | | Write-back to Source | ✅ | ✅ | ⚠️ | Notion: Zapier/Make를 통해서만 외부 쓰기 가능 | | 네이티브 통합 수 | 수백 | 103+ | \~10 | Notion: Slack, GitHub 등 소수 네이티브만, 나머지 Zapier | **달성도 — Palantir: ★★★★★ / Suits: ★★★★★ (95%) / Notion: ★★☆☆☆ (35%)** *** 지식 그래프 / 관계 탐색 [#지식-그래프--관계-탐색] | 기능 | Palantir | Suits | Notion | 비고 | | ------------ | :------: | :---: | :----: | --------------------------------------------- | | 그래프 시각화 | ✅ | ⚠️ 부분 | ❌ | Suits: ReactFlow + dagre. Notion: 관계 시각화 뷰 없음 | | 다중 홉 관계 순회 | ✅ | ❌ | ❌ | — | | 패턴 탐지 | ✅ | ❌ | ❌ | — | | 시멘틱 검색 | ✅ | ✅ | ⚠️ | Notion AI: 키워드/맥락 검색은 되나 벡터 기반은 아님 | | 타임라인 분석 | ✅ | ❌ | ❌ | — | | 경로 탐색 | ✅ | ❌ | ❌ | — | | LLM 기반 관계 추론 | ⚠️ | ⚠️ 가능 | ⚠️ | Notion Agents도 DB를 순회할 수 있으나 그래프 탐색은 아님 | **달성도 — Palantir: ★★★★★ / Suits: ★★☆☆☆ (40%) / Notion: ★☆☆☆☆ (15%)** 현재 Suits는 RELATION 속성을 `prop_XXX` JSON에 저장하므로, 관계를 탐색하려면 매번 "어떤 prop이 관계인지"를 PropertyMapping에서 동적으로 찾고, JSON을 파싱해야 한다. 이 구조에서는 다중 홉 SQL이 극도로 복잡해진다. | | Palantir (Graph DB) | Suits (RDB) | | ----- | ----------------------- | ------------------------------------------------ | | 관계 저장 | 노드 간 직접 포인터 (엣지) | DataRow\.prop\_XXX에 JSON 배열로 내장 | | 2홉 순회 | 네이티브 연산 (\~1ms) | PropertyMapping 조회 → 동적 prop 파싱 → JSON 풀기 → JOIN | | 3홉 순회 | 선형 증가 (\~5ms) | SQL 복잡도 폭발 | | 엣지 속성 | 자연 지원 (label, weight 등) | 불가 (관계에 메타데이터 부여 불가) | *** Entity Resolution (개체 동일성) [#entity-resolution-개체-동일성] | 기능 | Palantir | Suits | Notion | 비고 | | --------- | :------: | :---: | :----: | --------------------------------- | | 규칙 기반 매칭 | ✅ | ❌ | ❌ | — | | 벡터 유사도 매칭 | ✅ | ✅ | ❌ | Suits: 768D 임베딩 인덱스 보유 | | LLM 기반 판별 | ⚠️ | ⚠️ 가능 | ❌ | — | | 자동 중복 탐지 | ✅ | ❌ | ⚠️ | Notion: "중복 제거" 자동화 액션 있음 (단순 매칭) | | Entity 병합 | ✅ | ❌ | ❌ | — | **달성도 — Palantir: ★★★★★ / Suits: ★★★☆☆ (50%) / Notion: ★☆☆☆☆ (10%)** *** 권한 / 거버넌스 [#권한--거버넌스] | 기능 | Palantir | Suits | Notion | 비고 | | ------------------ | :------: | :---: | :----: | ------------------------------------------------- | | 역할 기반 접근 (RBAC) | ✅ | ✅ | ✅ | Notion: Workspace Owner/Admin/Member/Guest | | 리소스별 세분화 권한 | ✅ | ✅ | ⚠️ | Notion: 페이지/DB 수준만. Suits: CRUD × 7종 리소스 | | 블록/Row 수준 권한 | ✅ | ✅ | ⚠️ | Notion: DB 페이지별 접근 제어 (Business+). Row-level은 부분적 | | 사용자 그룹 | ✅ | ✅ | ✅ | Notion: Teams/Groups | | Row-level Security | ✅ | ❌ | ⚠️ | Notion: 페이지 기반 DB row 접근 제어 (제한적) | | 감사 로그 | ✅ | ⚠️ 부분 | ✅ | Notion Enterprise: 감사 로그 + SIEM/DLP 연동 | | API Rate Limiting | ✅ | ✅ | ✅ | — | **달성도 — Palantir: ★★★★★ / Suits: ★★★☆☆ (70%) / Notion: ★★★☆☆ (60%)** *** 실시간 협업 [#실시간-협업] | 기능 | Palantir | Suits | Notion | 비고 | | ---------------- | :------: | :----: | :----: | ------------------------------------ | | 동시 편집 | ⚠️ | ✅ | ✅ | Suits: Yjs CRDT. Notion: 자체 구현 | | Presence (커서 공유) | ⚠️ | ✅ | ✅ | — | | 오프라인 지원 | ❌ | ✅ | ✅ | Notion: 2025년 오프라인 모드 추가 | | 리치 텍스트 편집기 | ⚠️ | ✅ | ✅ | Suits: Tiptap 40+ 확장. Notion: 자체 에디터 | | 블록 기반 문서 | ❌ | ✅ 35+종 | ✅ 50+종 | Notion이 블록 타입 수에서는 우위 | | 코멘트/멘션 | ⚠️ | ✅ | ✅ | — | | 데이터 + 문서 통합 | ⚠️ | ✅ | ✅ | Suits/Notion 모두 문서 안에 DB 임베드 가능 | **달성도 — Palantir: ★★☆☆☆ / Suits: ★★★★★ (95%) / Notion: ★★★★★ (95%)** *** AI / LLM 통합 [#ai--llm-통합] | 기능 | Palantir | Suits | Notion | 비고 | | ---------------- | :------: | :----: | :----: | -------------------------------------------------------------------- | | AI 에이전트 루프 | ✅ | ✅ | ✅ | Notion 3.0: 20분+ 자율 실행 에이전트 | | 멀티 모델 지원 | ⚠️ | ✅ | ✅ | Notion 3.2: GPT-5.2, Claude Opus 4.5, Gemini 3 + 자동 선택 | | 도구 사용 (Tool Use) | ✅ 40+종 | ✅ 40+종 | ⚠️ | Notion: DB CRUD + 페이지 생성 정도, 외부 액션 제한적 | | 컨텍스트 압축 / 메모리 | ✅ | ✅ | ✅ | Notion 3.0: "state-of-the-art memory system" | | Failover | ✅ | ✅ | ❌ | — | | 벡터 검색 | ✅ | ✅ | ⚠️ | Notion: Enterprise Search 있으나 커스텀 임베딩은 아님 | | 커스텀 AI Skill/지침 | ✅ | ✅ | ⚠️ | Notion: Custom Agents로 지침 정의 가능하나 Skill 테이블 수준은 아님 | | 워크플로우 + AI 결합 | ✅ | ✅ | ⚠️ | Suits: AI가 워크플로우 실행/생성 가능. Notion: Agent가 자동화 트리거 가능하나 복잡한 워크플로우는 아님 | **달성도 — Palantir: ★★★★☆ / Suits: ★★★★☆ (90%) / Notion: ★★★★☆ (75%)** *** 종합 레이더 차트 [#종합-레이더-차트] * **Palantir**(빨강)은 데이터 통합/그래프/거버넌스에서 압도적이지만, 협업과 접근성에서 약함 * **Notion**(주황)은 협업/AI에서 강하지만, 데이터 통합/워크플로우/그래프에서 크게 부족 * **Suits**(네이비)는 Notion보다 거의 모든 영역에서 앞서고, Palantir 대비 그래프 갭만 남음 * **Suits 보강 후**(민트)는 DataEdge + LLM 파이프라인으로 Palantir 갭을 대폭 축소 *** 갭 분석: 무엇을 메워야 하는가 [#갭-분석-무엇을-메워야-하는가] Tier 0 — 구조적 기반 (다른 갭 해소의 전제조건) [#tier-0--구조적-기반-다른-갭-해소의-전제조건] | 갭 | 구현 방향 | 예상 난이도 | 영향 | | ------------------- | ---------------------------------------------- | ------ | --------------------------- | | **DataEdge 테이블 도입** | 엣지를 prop\_XXX에서 독립 테이블로 분리 (Typed + Free Edge) | 중상 | 다중 홉 순회, 엣지 속성, 그래프 뷰의 전제조건 | DataEdge가 없으면 Tier 1의 다중 홉 탐색, Tier 2의 온톨로지 그래프 뷰 모두 SQL 복잡도 문제에 막힌다. 이 테이블이 그래프 기능 전체의 기반이 된다. Tier 1 — LLM 파이프라인으로 빠르게 메울 수 있는 갭 [#tier-1--llm-파이프라인으로-빠르게-메울-수-있는-갭] | 갭 | 구현 방향 | 예상 난이도 | | --------------------- | ------------------------------------------------ | ------ | | **Entity Resolution** | LLM 기반 워크플로우 노드 (중복 탐지 → 유사도 판별 → 병합 제안) | 중 | | **자동 스키마 매핑** | LLM이 외부 데이터 샘플 → DataModel 프로퍼티 매핑 추론 | 중 | | **다중 홉 관계 탐색** | DataEdge + `WITH RECURSIVE` 순회 API + AI Agent 도구 | 중 | | **패턴 탐지** | 워크플로우 노드: 임베딩 클러스터링 → LLM 해석 | 중 | Tier 2 — 시스템 엔지니어링이 필요한 갭 [#tier-2--시스템-엔지니어링이-필요한-갭] | 갭 | 구현 방향 | 예상 난이도 | | ------------------ | --------------------------------------- | ------ | | **글로벌 온톨로지 그래프 뷰** | DataModel 관계 + DataEdge를 ReactFlow로 시각화 | 중 | | **Data Lineage** | 워크플로우 실행 시 소스→타겟 메타데이터 기록 | 중상 | | **타임라인 분석 뷰** | DataEdge.created\_at 기반 관계 변화 시각화 | 중 | | **감사 로그 확장** | 미들웨어 레벨에서 모든 데이터 접근/변경 이벤트 기록 | 중상 | Tier 3 — 엔터프라이즈 고객 시 필요한 갭 [#tier-3--엔터프라이즈-고객-시-필요한-갭] | 갭 | 구현 방향 | 예상 난이도 | | ------------------------- | -------------------------------------- | ------ | | **Row-level Security** | Prisma middleware 또는 PostgreSQL RLS 정책 | 상 | | **Column-level Security** | PropertyMapping별 접근 제어 레이어 | 상 | | **데이터 분류/태깅** | 민감도 등급 자동 분류 시스템 | 상 | | **타입 상속** | DataModel 간 상속 관계 + 프로퍼티 계승 | 중상 | *** 각 플랫폼의 차별적 강점 [#각-플랫폼의-차별적-강점] Suits가 Palantir보다 나은 점 [#suits가-palantir보다-나은-점] | 강점 | 상세 | | -------------- | --------------------------------------------------- | | **실시간 협업 편집** | Yjs/Hocuspocus CRDT — 팔란티어는 대시보드 중심이라 문서 동시 편집이 약함 | | **한국 B2B 생태계** | Cafe24, Coupang, 네이버, 다우오피스, 이카운트, 솔라피 등 10+ 한국 커넥터 | | **가격/접근성** | SaaS 모델 — 팔란티어는 연간 수억\~수십억 원 계약 | | **승인 워크플로우** | parallel / sequential 승인 + 타임아웃 — 한국 기업 문화에 최적화 | Suits가 Notion보다 나은 점 [#suits가-notion보다-나은-점] | 강점 | 상세 | | ------------- | --------------------------------------------------------------- | | **워크플로우 엔진** | 103+ 노드, 조건 분기, 루프, 에러 핸들링, 비주얼 편집기. Notion은 단순 자동화만 | | **SQL 기반 분석** | Stat 블록에서 cross-DataModel SQL 집계 + 다양한 차트. Notion은 단일 DB 기본 차트만 | | **네이티브 커넥터** | 103+ 직접 연동. Notion은 Zapier/Make 의존 (추가 비용 + 지연) | | **관계 카디널리티** | 1:1, 1:N, N:1, N:M 명시적 선언. Notion은 단순 Relation만 | | **벡터 검색** | 768D 임베딩 + FTS 커스텀 인덱스. Notion은 키워드 검색 수준 | | **승인/거버넌스** | 승인 워크플로우, 리소스별 세분화 권한. Notion은 미지원 | | **한국 B2B** | 한국 커넥터 10+. Notion은 한국 특화 없음 | Notion이 Suits보다 나은 점 [#notion이-suits보다-나은-점] | 강점 | 상세 | | --------------------- | ------------------------------------------------------------------ | | **UX 단순성** | 온보딩이 압도적으로 쉬움. 비개발자도 즉시 사용 가능 | | **생태계/템플릿** | 수만 개 커뮤니티 템플릿, 거대한 사용자 베이스 | | **뷰 다양성** | 8종 뷰 (Table, Board, Calendar, Gallery, Timeline, List, Chart, Map) | | **블록 타입 수** | 50+종 — Suits(35+)보다 다양 | | **브랜드 인지도** | 전 세계 수천만 사용자, "팀 도구 = Notion" 인식 | | **Notion 3.0 Agents** | 20분+ 자율 실행, 멀티 모델 자동 선택 — AI Agent 경험이 세련됨 | Palantir만의 독보적 영역 [#palantir만의-독보적-영역] | 강점 | 상세 | | --------------------- | ---------------------------- | | **온톨로지 그래프 엔진** | 20년 축적된 물리계산 기반 관계 탐색 — 유일무이 | | **수십억 노드 스케일** | 국방/금융급 데이터 규모 처리 | | **Data Lineage** | 데이터 계보 전체 추적 | | **Entity Resolution** | 규칙 기반 + ML 기반 개체 동일성 판별 엔진 | *** 업무 시스템의 5단계 성숙도 [#업무-시스템의-5단계-성숙도] 엔터프라이즈 업무 시스템의 진화 단계 [#엔터프라이즈-업무-시스템의-진화-단계] | Level | 이름 | 핵심 질문 | Palantir | Suits | Notion | | :---: | ------------------ | ---------------------- | :------: | :---: | :----: | | **1** | **Record** (기록) | "일어난 일을 저장한다" | ✅ | ✅ | ✅ | | **2** | **Automate** (자동화) | "규칙대로 자동 실행한다" | ✅ | ✅ | ⚠️ | | **3** | **Analyze** (분석) | "숫자를 집계하고 추세를 본다" | ✅ | ✅ | ⚠️ | | **4** | **Connect** (연결) | "관계를 따라가며 맥락을 파악한다" | ✅ | ⚠️ | ❌ | | **5** | **Predict** (예측) | "패턴을 발견하고 다음 행동을 제안한다" | ✅ | ⚠️ | ⚠️ | 팔란티어의 20년은 이 5단계를 순서대로 쌓아온 과정이며, **Level 4(온톨로지)가 핵심 해자**다. **Suits**는 Level 1-3이 탄탄하고 Level 5의 AI Agent도 갖추고 있지만, **Level 4가 빠져있어서 Level 5도 "테이블 안의 정보"로 제한된다.** Level 4가 만드는 차이: "왜?"에 답할 수 있는가 [#level-4가-만드는-차이-왜에-답할-수-있는가] | | 지식 그래프 없음 | 지식 그래프 있음 | | ------------------- | -------------- | -------------------------- | | **"무엇"** (What) | 매출 30% 하락 | 매출 30% 하락 | | **"누가"** (Who) | 고객 A, B가 이탈 | 고객 A, B가 이탈 | | **"왜"** (Why) | 알 수 없음 (수동 조사) | 담당자 교체 → 관계 약화 → 경쟁사 침투 | | **"그래서"** (So what) | 영업팀에 연락해보세요 | A 고객에 미팅 제안 + B 고객은 가격 재협상 | *** 결론 [#결론] 현재 위치 [#현재-위치] Suits는 팔란티어 온톨로지의 **핵심 기능 중 약 75%를 이미 보유**하고 있다. 특히 **액션 프레임워크(워크플로우), 실시간 협업, AI 에이전트** 영역에서는 팔란티어와 대등하거나 우위에 있다. 가장 큰 갭 [#가장-큰-갭] **지식 그래프 탐색 (40%)** 이 최대 갭이다. 이는 단순 기능 부재가 아니라 업무 시스템 성숙도 Level 4 전체가 빠져있다는 의미이며, Level 5(AI 예측)의 효과도 제한한다. 다만 이 영역이야말로: * **DataEdge 테이블**로 구조적 기반을 만들고 * **LLM 파이프라인**으로 추론을 보강하면 가장 효과적으로 메울 수 있는 부분이다. LLM이 바꾸는 공식 [#llm이-바꾸는-공식] 팔란티어의 20년 = 물리계산엔진으로 "세상을 이해시키는" 시간 LLM = 그 "이해" 자체를 우회 남는 과제 = 파이프라인 엔지니어링 + 액션 프레임워크 + 데이터 거버넌스 → 소규모 팀이 충분히 구축 가능한 영역 **"바이브코딩으로 만들 수 없다"는 2020년의 결론이다. 2025년에는 틀렸다.** --- # 인증 (/docs/api-reference/authentication) > 슈츠 API를 안전하게 사용하기 위한 인증 방법을 알아봅니다. import { Callout } from 'fumadocs-ui/components/callout'; API 키 개요 [#api-키-개요] API 키란? [#api-키란] API 키는 외부 애플리케이션이 슈츠 워크스페이스에 접근할 수 있도록 허용하는 인증 수단입니다. 각 API 키는: * 특정 워크스페이스에 연결됩니다 * 설정된 권한 범위 내에서만 동작합니다 * 생성 시 한 번만 표시되며, 이후에는 확인할 수 없습니다 키 형식 [#키-형식] 슈츠 API 키는 다음 형식을 따릅니다: ``` tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (프로덕션) tk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (테스트) ``` *** API 키 생성 [#api-키-생성] 1단계: 개발자 설정 접근 [#1단계-개발자-설정-접근] 1. 워크스페이스 사이드바에서 **설정** 클릭 2. **개발자 설정** 탭 선택 3. **API 키** 섹션으로 이동 2단계: 새 API 키 생성 [#2단계-새-api-키-생성] **+ 새 API 키** 버튼을 클릭합니다. 3단계: 키 설정 [#3단계-키-설정] | 설정 항목 | 설명 | 예시 | | --------- | ------------- | ---------------------- | | **이름** | 키를 식별하는 이름 | "프로덕션 서버", "Zapier 연동" | | **권한 범위** | 허용할 작업 범위 | read, write, admin | | **만료 기간** | 키의 유효 기간 (선택) | 30일, 90일, 무제한 | 4단계: 키 저장 [#4단계-키-저장] 생성된 키는 **한 번만 표시**됩니다. 페이지를 벗어나면 다시 확인할 수 없으니 안전한 곳에 저장하세요. ``` tk_live_abc123def456ghi789jkl012mno345pqr678 ``` *** API 키 사용 [#api-키-사용] 모든 API 요청의 `Authorization` 헤더에 키를 포함합니다. 기본 사용법 [#기본-사용법] ```bash curl -X GET "https://suits.work/api/v1/datamodels" \ -H "Authorization: Bearer tk_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" ``` 언어별 예시 [#언어별-예시] **JavaScript (fetch)** ```javascript const response = await fetch('https://suits.work/api/v1/datamodels', { method: 'GET', headers: { 'Authorization': `Bearer ${process.env.SUITS_API_KEY}`, 'Content-Type': 'application/json', }, }); const data = await response.json(); ``` **Python (requests)** ```python import os import requests response = requests.get( 'https://suits.work/api/v1/datamodels', headers={ 'Authorization': f'Bearer {os.environ["SUITS_API_KEY"]}', 'Content-Type': 'application/json', } ) data = response.json() ``` *** 권한 범위 [#권한-범위] API 키는 필요한 권한만 선택적으로 부여할 수 있습니다. read (읽기) [#read-읽기] **데이터 조회 권한** * 데이터모델 목록 및 구조 조회 * 행(Row) 데이터 조회 * 페이지 내용 조회 * 파일 다운로드 ```http GET /v1/datamodels GET /v1/datamodels/:id/rows GET /v1/pages/:id ``` write (쓰기) [#write-쓰기] **데이터 변경 권한** (read 포함) * 행 생성, 수정, 삭제 * 페이지 생성, 수정, 삭제 * 파일 업로드 ```http POST /v1/datamodels/:id/rows PATCH /v1/datamodels/:id/rows/:rowId DELETE /v1/datamodels/:id/rows/:rowId ``` admin (관리) [#admin-관리] **시스템 관리 권한** (read, write 포함) * 데이터모델 구조 변경 (속성 추가/삭제) * 워크스페이스 설정 변경 * 멤버 관리 * API 키 관리 ```http POST /v1/datamodels PATCH /v1/datamodels/:id/properties DELETE /v1/datamodels/:id ``` *** 보안 권장사항 [#보안-권장사항] API 키 보호 [#api-키-보호] API 키를 코드에 직접 포함하지 마세요. 노출된 키는 즉시 폐기해야 합니다. **✅ 환경 변수 사용** ```bash # .env SUITS_API_KEY=tk_live_xxxxxxxxxxxx ``` ```javascript const apiKey = process.env.SUITS_API_KEY; ``` **✅ 시크릿 관리 서비스** * AWS Secrets Manager * Google Cloud Secret Manager * HashiCorp Vault **❌ 피해야 할 것** ```javascript // ❌ 코드에 직접 포함 const apiKey = 'tk_live_xxxxxxxxxxxx'; // ❌ 클라이언트 사이드 노출 ``` 최소 권한 원칙 [#최소-권한-원칙] 필요한 권한만 부여하세요: | 용도 | 권장 권한 | | -------- | ----- | | 대시보드 표시용 | read | | 폼 데이터 저장 | write | | 자동화 통합 | write | | 백오피스 관리 | admin | 주기적 갱신 [#주기적-갱신] 보안 강화를 위해 API 키를 정기적으로 갱신하세요: 1. 새 키를 먼저 생성 2. 애플리케이션에 새 키 배포 3. 기존 키 비활성화/삭제 *** 에러 처리 [#에러-처리] 401 Unauthorized [#401-unauthorized] **잘못된 API 키** ```json { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key. Expected: Bearer tk_xxx... or Bearer mcp_xxx..." } } ``` **확인사항:** * API 키가 올바른지 확인 * `Authorization: Bearer ` 형식 확인 (Bearer 뒤 공백 필수) * 키가 비활성화되지 않았는지 확인 403 Forbidden [#403-forbidden] **권한 부족** ```json { "error": { "code": "FORBIDDEN", "message": "This API key does not have the required scope: write" } } ``` **확인사항:** * API 키의 권한 범위 확인 * 요청하는 작업에 필요한 권한 확인 * write 작업에 read 권한만 있는지 확인 429 Too Many Requests [#429-too-many-requests] **속도 제한 초과** ```json { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please slow down." } } ``` **확인사항:** * 요청 빈도 줄이기 * 지수 백오프(exponential backoff) 적용 * 대량 작업은 배치 API 사용 *** 속도 제한 (Rate Limiting) [#속도-제한-rate-limiting] API 안정성을 위해 요청 속도를 제한합니다. | 티어 | 제한 | | ---------- | ---------- | | Standard | 60 요청/분 | | Premium | 60 요청/분 | | Enterprise | 1,000 요청/분 | 응답 헤더 [#응답-헤더] ```http X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1609459200 ``` *** 다음 단계 [#다음-단계] * [데이터모델 API](/docs/api-reference/datamodels-api) - 데이터 CRUD 작업 * [웹훅](/docs/api-reference/webhooks) - 실시간 이벤트 수신 --- # CLI (명령줄 도구) (/docs/api-reference/cli) > 터미널에서 슈츠 워크스페이스를 관리하는 CLI 도구. AI 코딩 에이전트(Claude Code, Codex, Moltbot)와의 통합에 최적화. import { Callout } from 'fumadocs-ui/components/callout'; CLI란? [#cli란] 슈츠 CLI(`suits`)는 터미널에서 워크스페이스 데이터를 관리하는 명령줄 도구입니다. * **MCP 설정 없이** Bash 명령어로 바로 슈츠 데이터 접근 * **AI 코딩 에이전트** (Claude Code, Codex, Moltbot 등) 최적화 * `--json` 출력으로 프로그래밍 활용 가능 * `--quiet` 출력으로 쉘 스크립트 파이핑 지원 *** 설치 [#설치] ```bash # npm npm install -g @suits-work/cli # bun bun add -g @suits-work/cli # 설치 없이 바로 실행 npx @suits-work/cli --help ``` 설치 후 `suits` 명령어를 사용할 수 있습니다. *** 인증 설정 [#인증-설정] 방법 1: API Key (추천) [#방법-1-api-key-추천] 워크스페이스 **설정 → 개발자 설정**에서 API 키를 발급받은 후: ```bash suits login --api-key tk_your_api_key --name "마케팅팀" ``` 방법 2: 환경변수 (CI/CD용) [#방법-2-환경변수-cicd용] ```bash export SUITS_API_KEY=tk_your_api_key suits blocks list ``` 방법 3: OAuth 브라우저 로그인 [#방법-3-oauth-브라우저-로그인] ```bash suits login --workspace # → 브라우저가 열리고 Google 로그인 후 자동 완료 ``` 인증 상태 확인 [#인증-상태-확인] ```bash suits whoami ``` 인증 우선순위 [#인증-우선순위] 1. `--api-key` 플래그 (최우선) 2. `SUITS_API_KEY` 환경변수 3. `~/.suits/credentials.json` 저장된 키 멀티 워크스페이스 [#멀티-워크스페이스] 여러 워크스페이스를 등록하고 전환할 수 있습니다: ```bash # 워크스페이스 추가 suits login --api-key tk_key1 --name "마케팅팀" suits login --api-key tk_key2 --name "개발팀" # 워크스페이스 전환 suits use "개발팀" # 일회성으로 다른 워크스페이스 사용 suits blocks list --workspace "마케팅팀" ``` *** 명령어 레퍼런스 [#명령어-레퍼런스] 인증 [#인증] | 명령어 | 설명 | | --------------------------------------------- | -------------- | | `suits login --api-key [--name ]` | API 키로 로그인 | | `suits login --workspace ` | OAuth 브라우저 로그인 | | `suits logout` | 로그아웃 | | `suits whoami` | 현재 인증 상태 | | `suits use ` | 활성 워크스페이스 전환 | 블록 (Blocks) [#블록-blocks] ```bash # 블록 목록 조회 suits blocks list [--parent ] [--type ] [--search ] [--limit ] # 블록 상세 조회 suits blocks get # 블록 생성 suits blocks create --type --title [--parent <id>] # 블록 수정 suits blocks update <blockId> --title <title> # 블록 삭제 suits blocks delete <blockId> --confirm ``` 데이터모델 (DataModels) [#데이터모델-datamodels] ```bash # 목록 조회 suits datamodels list [--search <query>] [--limit <n>] # 상세 조회 suits datamodels get <dataModelId> # 생성 suits datamodels create --title <title> [--description <desc>] # 수정 suits datamodels update <dataModelId> --title <title> # 삭제 suits datamodels delete <dataModelId> --confirm ``` 행 (Rows) [#행-rows] ```bash # 행 목록 suits rows list <dataModelId> [--limit <n>] [--offset <n>] # 행 생성 suits rows create <dataModelId> --data '{"field": "value"}' # 행 수정 suits rows update <dataModelId> <rowId> --data '{"field": "new_value"}' # 행 삭제 suits rows delete <dataModelId> <rowId> --confirm ``` 통계 (Stats) [#통계-stats] ```bash # 통계 목록 suits stats list [--enabled-only] # 통계 상세 suits stats get <statId> # 통계 실행 suits stats run <statId> [--start <date>] [--end <date>] [--timezone <tz>] ``` 워크플로우 (Workflows) [#워크플로우-workflows] ```bash # 워크플로우 목록 suits workflows list [--status <status>] # 워크플로우 상세 suits workflows get <workflowId> # 워크플로우 실행 suits workflows run <workflowId> [--data '{"key": "value"}'] # 워크플로우 배포 suits workflows deploy <workflowId> ``` 워크스페이스 (Workspace) [#워크스페이스-workspace] ```bash # 워크스페이스 요약 suits workspace summary ``` 글로벌 옵션 [#글로벌-옵션] 모든 명령어에 적용 가능한 옵션: | 옵션 | 설명 | | -------------------- | --------------------- | | `--json` | JSON 원본 출력 (AI 에이전트용) | | `-q, --quiet` | 최소 출력 (ID만, 스크립팅용) | | `--workspace <name>` | 활성 워크스페이스 임시 변경 | | `--api-key <key>` | 저장된 키 대신 사용 | *** 출력 형식 [#출력-형식] 기본 (테이블) [#기본-테이블] ``` ID TYPE TITLE UPDATED d5e7d4fa-781e-4d02-a262-6761a4a0f877 page 매출 보고서 2026-02-08 1f8eb0cf-152e-4836-8639-60b6b603a164 page 팀 핸드북 2026-02-07 2 blocks found ``` --json (AI 에이전트용) [#--json-ai-에이전트용] ```json { "data": [...], "meta": { "total": 2, "limit": 20, "offset": 0, "hasMore": false } } ``` --quiet (파이핑용) [#--quiet-파이핑용] ``` d5e7d4fa-781e-4d02-a262-6761a4a0f877 1f8eb0cf-152e-4836-8639-60b6b603a164 ``` *** AI 에이전트 활용 예시 [#ai-에이전트-활용-예시] Claude Code [#claude-code] Claude Code에서 슈츠 데이터를 조회하고 활용하는 시나리오: ```bash # 데이터모델 목록 확인 suits datamodels list --json # 특정 데이터모델의 행 데이터 가져오기 suits rows list <dataModelId> --json --limit 100 # 새 행 추가 suits rows create <dataModelId> --data '{"title": "새 항목", "status": "진행중"}' ``` Codex / Moltbot [#codex--moltbot] ```bash # 워크스페이스 요약 파악 suits workspace summary --json # 블록 검색 suits blocks list --search "매출" --json ``` <Callout type="info"> AI 에이전트에서 사용할 때는 항상 `--json` 플래그를 추가하세요. 구조화된 JSON 응답으로 파싱이 훨씬 쉬워집니다. </Callout> *** CLI vs MCP vs REST API [#cli-vs-mcp-vs-rest-api] | | CLI | MCP | REST API | | ----------- | ----------------- | ---------------------- | ---------- | | **설정** | `suits login` 한 번 | `.mcp.json` + OAuth | HTTP 헤더마다 | | **AI 에이전트** | Bash로 바로 | MCP 클라이언트 필요 | curl/fetch | | **출력 형식** | 테이블/JSON/Quiet | 구조화된 JSON | JSON | | **가장 적합** | 코딩 에이전트, 스크립트 | Claude Desktop, Cursor | 커스텀 앱 개발 | | **인증** | API Key / OAuth | OAuth 자동 | API Key | *** 문제 해결 [#문제-해결] 401 Unauthorized [#401-unauthorized] API 키가 유효하지 않거나 만료되었습니다. ```bash # 인증 상태 확인 suits whoami # 재로그인 suits login --api-key tk_new_key ``` 403 Forbidden [#403-forbidden] API 키의 권한 범위가 부족합니다. 워크스페이스 설정에서 API 키의 스코프를 확인하세요. 429 Rate Limited [#429-rate-limited] 요청 제한을 초과했습니다. 잠시 후 다시 시도하세요. *** 다음 단계 [#다음-단계] * [인증 상세](/docs/api-reference/authentication) — API 키 발급 및 관리 * [MCP 연동](/docs/api-reference/mcp) — Claude Desktop, Cursor에서 슈츠 사용 * [데이터모델 API](/docs/api-reference/datamodels-api) — REST API 상세 문서 --- # 데이터모델 API (/docs/api-reference/datamodels-api) > 데이터모델과 행(Row) 데이터를 조회하고 조작하는 API입니다. import { Callout } from 'fumadocs-ui/components/callout'; 기본 URL [#기본-url] ``` https://suits.work/api/v1 ``` 모든 요청에는 인증 헤더가 필요합니다: ```http Authorization: Bearer tk_live_xxxxxxxxxxxx Content-Type: application/json ``` > **참고**: API 키에 워크스페이스 정보가 포함되어 있으므로, 별도의 workspaceId 파라미터는 필요하지 않습니다. *** 데이터모델 [#데이터모델] 데이터모델 목록 조회 [#데이터모델-목록-조회] 워크스페이스의 모든 데이터모델을 조회합니다. ```http GET /api/v1/datamodels ``` **쿼리 파라미터** | 파라미터 | 타입 | 필수 | 설명 | 기본값 | | ---------------- | ------- | --- | -------------------- | ----- | | search | string | 아니오 | 검색어 (title, id에서 검색) | - | | limit | number | 아니오 | 반환할 최대 개수 | 100 | | includeDetails | boolean | 아니오 | 속성(properties) 포함 | false | | includeRowCounts | boolean | 아니오 | 행 개수 포함 | false | **요청 예시** ```bash curl -X GET "https://suits.work/api/v1/datamodels" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **응답** ```json { "data": [ { "id": "dm_abc123", "title": "고객", "icon": { "type": "emoji", "name": "👤" }, "description": "고객 정보 관리", "createdAt": "2024-01-15T09:00:00Z", "updatedAt": "2024-03-20T14:30:00Z" }, { "id": "dm_def456", "title": "영업기회", "icon": { "type": "emoji", "name": "💰" }, "description": "영업 파이프라인", "createdAt": "2024-01-15T09:05:00Z", "updatedAt": "2024-03-21T10:15:00Z" } ], "meta": { "total": 2 } } ``` *** 데이터모델 상세 조회 [#데이터모델-상세-조회] 특정 데이터모델의 구조를 조회합니다. ```http GET /api/v1/datamodels/:dataModelId ``` **응답** ```json { "data": { "id": "dm_abc123", "title": "고객", "icon": { "type": "emoji", "name": "👤" }, "description": "고객 정보 관리", "properties": [ { "id": "prop_001", "name": "회사명", "type": "TEXT", "order": 1, "visible": true }, { "id": "prop_002", "name": "이메일", "type": "TEXT", "order": 2, "visible": true }, { "id": "prop_003", "name": "계약금액", "type": "CURRENCY", "order": 3, "visible": true }, { "id": "prop_004", "name": "상태", "type": "SELECT", "options": [ { "value": "lead", "label": "리드", "color": "gray" }, { "value": "active", "label": "활성", "color": "green" }, { "value": "churned", "label": "이탈", "color": "red" } ], "order": 4, "visible": true }, { "id": "prop_005", "name": "담당자", "type": "RELATION", "relationConfig": { "targetDataModelId": "dm_members", "relationshipType": "MANY_TO_ONE" }, "order": 5, "visible": true } ], "createdAt": "2024-01-15T09:00:00Z", "updatedAt": "2024-03-20T14:30:00Z" } } ``` *** 행 (Rows) [#행-rows] 행 목록 조회 [#행-목록-조회] 데이터모델의 행 데이터를 조회합니다. ```http GET /api/v1/datamodels/:dataModelId/rows ``` **쿼리 파라미터** | 파라미터 | 타입 | 필수 | 설명 | 기본값 | | ------- | ------ | --- | -------------------------------------------- | --- | | limit | number | 아니오 | 반환할 최대 행 수 (최대 500) | 100 | | offset | number | 아니오 | 페이지네이션 오프셋 | 0 | | orderBy | string | 아니오 | 정렬 기준 (예: `propertyId:asc,propertyId2:desc`) | - | **요청 예시** ```bash curl -X GET "https://suits.work/api/v1/datamodels/dm_abc123/rows?limit=20" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **응답** ```json { "data": [ { "id": "row_111", "data": { "prop_001": "테크스타트", "prop_002": "contact@techstart.co", "prop_003": 50000000, "prop_004": "active", "prop_005": ["member_001"] }, "createdAt": "2024-03-01T10:00:00Z", "updatedAt": "2024-03-15T14:30:00Z" }, { "id": "row_112", "data": { "prop_001": "그로스랩", "prop_002": "hello@growthlab.io", "prop_003": 30000000, "prop_004": "lead", "prop_005": ["member_002"] }, "createdAt": "2024-03-02T11:30:00Z", "updatedAt": "2024-03-02T11:30:00Z" } ], "meta": { "total": 2, "limit": 20, "offset": 0 } } ``` > **참고**: 응답의 `data` 필드 키는 속성의 `id` (prop\_xxx)입니다. 속성 이름이 아닌 ID를 사용하므로, 먼저 데이터모델 상세 조회로 속성 ID와 이름 매핑을 확인하세요. *** 행 생성 [#행-생성] 새로운 행을 생성합니다. 단건 또는 배치 생성이 가능합니다. ```http POST /api/v1/datamodels/:dataModelId/rows ``` **요청 바디 (단건)** ```json { "values": { "prop_001": "뉴컴퍼니", "prop_002": "info@newcompany.com", "prop_003": 25000000, "prop_004": "lead" } } ``` **요청 바디 (배치)** ```json { "rows": [ { "prop_001": "기업A", "prop_002": "a@company.com", "prop_004": "lead" }, { "prop_001": "기업B", "prop_002": "b@company.com", "prop_004": "lead" } ] } ``` **응답 (단건)** ```json { "data": { "id": "row_113", "data": { "prop_001": "뉴컴퍼니", "prop_002": "info@newcompany.com", "prop_003": 25000000, "prop_004": "lead" }, "createdAt": "2024-03-22T09:00:00Z" } } ``` **응답 (배치)** ```json { "data": [ { "id": "row_114", ... }, { "id": "row_115", ... } ], "meta": { "createdCount": 2, "errors": [] } } ``` *** 행 수정 [#행-수정] 기존 행의 데이터를 수정합니다. **변경할 속성만** 포함합니다. ```http PATCH /api/v1/datamodels/:dataModelId/rows/:rowId ``` **요청 바디** ```json { "values": { "prop_004": "active", "prop_003": 35000000 } } ``` **응답** ```json { "data": { "id": "row_113", "data": { "prop_001": "뉴컴퍼니", "prop_002": "info@newcompany.com", "prop_003": 35000000, "prop_004": "active" }, "updatedAt": "2024-03-22T10:30:00Z" } } ``` *** 행 삭제 [#행-삭제] 행을 삭제합니다. ```http DELETE /api/v1/datamodels/:dataModelId/rows/:rowId ``` **응답** ```json { "data": { "id": "row_113", "deleted": true } } ``` *** 필터링 (향후 지원 예정) [#필터링-향후-지원-예정] `filter` 파라미터로 조건에 맞는 행만 조회합니다. 기본 필터 [#기본-필터] ```javascript // 단일 조건 const filter = { "상태": { "equals": "active" } }; // URL 인코딩 const url = `/v1/datamodels/dm_abc/rows?filter=${encodeURIComponent(JSON.stringify(filter))}`; ``` 지원되는 연산자 [#지원되는-연산자] | 연산자 | 설명 | 지원 타입 | 예시 | | ----------------------- | ------- | ------------ | -------------------------------------- | | `equals` | 정확히 일치 | 모든 타입 | `{"상태": {"equals": "active"}}` | | `not_equals` | 일치하지 않음 | 모든 타입 | `{"상태": {"not_equals": "churned"}}` | | `contains` | 포함 | TEXT | `{"회사명": {"contains": "테크"}}` | | `starts_with` | \~로 시작 | TEXT | `{"이름": {"starts_with": "김"}}` | | `ends_with` | \~로 끝남 | TEXT | `{"이메일": {"ends_with": "@gmail.com"}}` | | `greater_than` | 초과 | NUMBER, DATE | `{"금액": {"greater_than": 1000000}}` | | `greater_than_or_equal` | 이상 | NUMBER, DATE | `{"금액": {"gte": 1000000}}` | | `less_than` | 미만 | NUMBER, DATE | `{"금액": {"less_than": 5000000}}` | | `less_than_or_equal` | 이하 | NUMBER, DATE | `{"금액": {"lte": 5000000}}` | | `is_empty` | 비어있음 | 모든 타입 | `{"메모": {"is_empty": true}}` | | `is_not_empty` | 비어있지 않음 | 모든 타입 | `{"이메일": {"is_not_empty": true}}` | 복합 조건 [#복합-조건] **AND 조건** ```json { "and": [ { "상태": { "equals": "active" } }, { "계약금액": { "greater_than": 10000000 } } ] } ``` **OR 조건** ```json { "or": [ { "상태": { "equals": "active" } }, { "상태": { "equals": "lead" } } ] } ``` **중첩 조건** ```json { "and": [ { "상태": { "equals": "active" } }, { "or": [ { "계약금액": { "greater_than": 50000000 } }, { "등급": { "equals": "VIP" } } ] } ] } ``` *** 정렬 [#정렬] `orderBy` 파라미터로 결과를 정렬합니다. 속성 ID와 방향을 콜론으로 구분하며, 여러 기준은 쉼표로 연결합니다. ``` orderBy=<propertyId>:<방향> ``` **예시** ``` orderBy=prop_003:desc # 금액 높은순 orderBy=prop_001:asc # 가나다순 orderBy=prop_004:asc,prop_003:desc # 복합 정렬 ``` *** 페이지네이션 [#페이지네이션] 대량의 데이터는 페이지네이션으로 나눠서 조회합니다. 오프셋 기반 페이지네이션 [#오프셋-기반-페이지네이션] ```javascript // 첫 번째 페이지 const response1 = await fetch('/api/v1/datamodels/dm_abc/rows?limit=20&offset=0'); const data1 = await response1.json(); // 다음 페이지 const response2 = await fetch('/api/v1/datamodels/dm_abc/rows?limit=20&offset=20'); const data2 = await response2.json(); ``` *** 속성별 값 형식 [#속성별-값-형식] TEXT (텍스트) [#text-텍스트] ```json { "회사명": "슈츠" } { "이메일": "hello@suits.work" } { "URL": "https://suits.work" } ``` NUMBER (숫자) [#number-숫자] ```json { "금액": 50000000 } { "수량": 100 } { "비율": 0.85 } ``` DATE (날짜) [#date-날짜] ISO 8601 형식을 사용합니다. ```json { "계약일": "2024-03-15" } { "마감일시": "2024-03-31T18:00:00Z" } ``` SELECT (선택) [#select-선택] 옵션 값(value)을 사용합니다. ```json { "상태": "active" } ``` MULTI_SELECT (다중 선택) [#multi_select-다중-선택] 배열로 전달합니다. ```json { "태그": ["VIP", "기업고객", "장기계약"] } ``` CHECKBOX (체크박스) [#checkbox-체크박스] ```json { "완료여부": true } { "중요": false } ``` RELATION (관계) [#relation-관계] 관계된 행의 ID 배열을 사용합니다. ```json { "담당자": ["member_001", "member_002"] } { "고객사": ["company_abc"] } ``` FILE (파일) [#file-파일] 파일 업로드 후 반환된 URL을 사용합니다. ```json { "첨부파일": [ { "url": "https://...", "name": "계약서.pdf" } ] } ``` *** 에러 응답 [#에러-응답] 공통 에러 형식 [#공통-에러-형식] ```json { "error": { "code": "ERROR_CODE", "message": "상세 에러 메시지" } } ``` 주요 에러 코드 [#주요-에러-코드] | 코드 | HTTP | 설명 | | ------------------ | ---- | --------- | | `UNAUTHORIZED` | 401 | 인증 실패 | | `FORBIDDEN` | 403 | 권한 없음 | | `NOT_FOUND` | 404 | 리소스 없음 | | `VALIDATION_ERROR` | 400 | 요청 데이터 오류 | | `CONFLICT` | 409 | 리소스 충돌 | | `RATE_LIMITED` | 429 | 요청 제한 초과 | *** 다음 단계 [#다음-단계] * [인증](/docs/api-reference/authentication) - API 키 발급 및 관리 * [웹훅](/docs/api-reference/webhooks) - 실시간 이벤트 수신 --- # API 레퍼런스 (/docs/api-reference) > 슈츠 API를 사용하여 외부 시스템과 연동하세요. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] 슈츠 API로 할 수 있는 것 [#슈츠-api로-할-수-있는-것] | 기능 | 설명 | | ------------- | ----------------------------- | | **데이터 조회** | 데이터모델의 행 데이터를 조회하고 검색 | | **데이터 생성/수정** | 외부 시스템에서 슈츠로 데이터 동기화 | | **실시간 알림** | 웹훅으로 데이터 변경 이벤트 수신 | | **자동화 연동** | Zapier, Make 등과 연결하여 워크플로우 확장 | 활용 예시 [#활용-예시] * **CRM 연동**: 웹사이트 폼에서 수집한 리드를 슈츠에 자동 등록 * **대시보드**: 슈츠 데이터를 외부 BI 도구에서 시각화 * **ERP 연동**: 슈츠의 주문 데이터를 ERP 시스템에 동기화 * **모바일 앱**: 슈츠를 백엔드로 사용하는 앱 개발 *** 빠른 시작 [#빠른-시작] 1단계: API 키 발급 [#1단계-api-키-발급] 1. 워크스페이스 **설정** → **개발자 설정** 이동 2. **+ 새 API 키** 클릭 3. 이름과 권한 범위 설정 4. 생성된 키를 안전하게 보관 <Callout type="warn"> API 키는 생성 시에만 전체 키를 확인할 수 있습니다. 분실 시 새로 생성해야 합니다. </Callout> 2단계: 첫 번째 API 호출 [#2단계-첫-번째-api-호출] ```bash curl -X GET "https://suits.work/api/v1/datamodels" \ -H "Authorization: Bearer tk_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" ``` 3단계: 응답 확인 [#3단계-응답-확인] ```json { "data": [ { "id": "dm_abc123", "title": "고객", "icon": { "type": "emoji", "name": "👤" }, "description": "고객 정보 관리" } ], "meta": { "total": 1 } } ``` *** Base URL [#base-url] 모든 API 요청의 기본 URL: ``` https://suits.work/api/v1 ``` *** 인증 [#인증] 모든 API 요청에 `Authorization` 헤더를 포함해야 합니다. ```http Authorization: Bearer tk_live_xxxxxxxxxxxx ``` 인증 예시 [#인증-예시] ```bash curl -X GET "https://suits.work/api/v1/datamodels" \ -H "Authorization: Bearer tk_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" ``` [인증 상세 문서 →](/docs/api-reference/authentication) *** 주요 엔드포인트 [#주요-엔드포인트] 블록 (Blocks) [#블록-blocks] | 메서드 | 엔드포인트 | 설명 | 권한 | | ------ | ------------- | -------- | ----- | | GET | `/blocks` | 블록 목록/검색 | read | | GET | `/blocks/:id` | 블록 상세 조회 | read | | POST | `/blocks` | 새 블록 생성 | write | | PATCH | `/blocks/:id` | 블록 수정 | write | | DELETE | `/blocks/:id` | 블록 삭제 | write | 데이터모델 (DataModels) [#데이터모델-datamodels] | 메서드 | 엔드포인트 | 설명 | 권한 | | ------ | ----------------- | ----------- | ----- | | GET | `/datamodels` | 데이터모델 목록 조회 | read | | GET | `/datamodels/:id` | 데이터모델 구조 조회 | read | | POST | `/datamodels` | 데이터모델 생성 | write | | PATCH | `/datamodels/:id` | 데이터모델 수정 | write | | DELETE | `/datamodels/:id` | 데이터모델 삭제 | write | 행 (Rows) [#행-rows] | 메서드 | 엔드포인트 | 설명 | 권한 | | ------ | ----------------------------- | --------------- | ----- | | GET | `/datamodels/:id/rows` | 행 목록 조회 | read | | POST | `/datamodels/:id/rows` | 행 생성 (단건 또는 배치) | write | | PATCH | `/datamodels/:id/rows/:rowId` | 행 수정 | write | | DELETE | `/datamodels/:id/rows/:rowId` | 행 삭제 | write | 워크플로우 (Workflows) [#워크플로우-workflows] | 메서드 | 엔드포인트 | 설명 | 권한 | | ------ | -------------------- | ----------- | ----- | | GET | `/workflows` | 워크플로우 목록 조회 | read | | GET | `/workflows/:id` | 워크플로우 상세 조회 | read | | POST | `/workflows` | 워크플로우 생성 | write | | PATCH | `/workflows/:id` | 워크플로우 수정 | write | | DELETE | `/workflows/:id` | 워크플로우 삭제 | write | | POST | `/workflows/:id/run` | 워크플로우 실행 | write | 통계 (Stats) [#통계-stats] | 메서드 | 엔드포인트 | 설명 | 권한 | | ------ | ---------------- | ----------- | ----- | | GET | `/stats` | 통계 정의 목록 조회 | read | | GET | `/stats/:id` | 통계 정의 상세 조회 | read | | POST | `/stats` | 통계 정의 생성 | write | | PATCH | `/stats/:id` | 통계 정의 수정 | write | | DELETE | `/stats/:id` | 통계 정의 삭제 | write | | POST | `/stats/:id/run` | 통계 실행 | write | [데이터모델 API 상세 →](/docs/api-reference/datamodels-api) *** 응답 형식 [#응답-형식] 성공 응답 (단일) [#성공-응답-단일] ```json { "data": { ... } } ``` 성공 응답 (목록) [#성공-응답-목록] ```json { "data": [...], "meta": { "total": 100, "limit": 20, "offset": 0, "hasMore": true } } ``` 에러 응답 [#에러-응답] ```json { "error": { "code": "ERROR_CODE", "message": "에러 메시지" } } ``` 주요 에러 코드 [#주요-에러-코드] | HTTP | 코드 | 설명 | | ---- | ------------------ | ------------ | | 400 | `VALIDATION_ERROR` | 요청 데이터 형식 오류 | | 401 | `UNAUTHORIZED` | 인증 실패 | | 403 | `FORBIDDEN` | 권한 부족 | | 404 | `NOT_FOUND` | 리소스 없음 | | 429 | `RATE_LIMITED` | 요청 제한 초과 | | 500 | `INTERNAL_ERROR` | 서버 오류 | *** 속도 제한 (Rate Limiting) [#속도-제한-rate-limiting] API 안정성을 위해 요청 속도를 제한합니다. | 티어 | 요청 제한 | | ---------- | ---------- | | Standard | 60 요청/분 | | Premium | 60 요청/분 | | Enterprise | 1,000 요청/분 | 응답 헤더 [#응답-헤더] ```http X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1609459200 ``` 제한 초과 시 [#제한-초과-시] ```json { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please slow down." } } ``` *** 웹훅 [#웹훅] 데이터 변경 시 실시간으로 알림을 받을 수 있습니다. 지원 이벤트 [#지원-이벤트] * `row.created` - 새 행 생성 * `row.updated` - 행 수정 * `row.deleted` - 행 삭제 * `page.created` - 새 페이지 생성 * `page.updated` - 페이지 수정 * `page.deleted` - 페이지 삭제 [웹훅 상세 문서 →](/docs/api-reference/webhooks) *** SDK 및 도구 [#sdk-및-도구] 공식 도구 [#공식-도구] * **[CLI](/docs/api-reference/cli)**: 터미널 CLI 도구 — AI 코딩 에이전트(Claude Code, Codex)와 통합하여 슈츠 데이터 관리 * **[MCP](/docs/api-reference/mcp)**: Model Context Protocol — Claude Desktop, Cursor에서 슈츠 연동 공식 SDK (예정) [#공식-sdk-예정] * JavaScript/TypeScript * Python * Go 서드파티 연동 [#서드파티-연동] * **Zapier**: 1,000+ 앱과 연동 * **Make (Integromat)**: 비주얼 자동화 * **n8n**: 오픈소스 자동화 *** 이 섹션에서 다루는 내용 [#이-섹션에서-다루는-내용] * [인증](/docs/api-reference/authentication) - API 키 발급 및 인증 방법 * [CLI](/docs/api-reference/cli) - 터미널 CLI 도구 (AI 코딩 에이전트 최적화) * [MCP](/docs/api-reference/mcp) - Model Context Protocol 연동 * [데이터모델 API](/docs/api-reference/datamodels-api) - 데이터 CRUD 작업 * [웹훅](/docs/api-reference/webhooks) - 실시간 이벤트 알림 *** 지원 [#지원] API 관련 문의: * 이메일: [api@suits.work](mailto:api@suits.work) * 개발자 포럼: community.suits.work --- # MCP 연결 (/docs/api-reference/mcp) > AI 도구(Claude Desktop, Cursor 등)에서 슈츠에 직접 연결하여 사용하는 방법을 안내합니다. import { Callout } from 'fumadocs-ui/components/callout'; MCP란? [#mcp란] MCP(Model Context Protocol)는 AI 에이전트가 외부 도구와 상호작용하기 위한 표준 프로토콜입니다. 슈츠 MCP 서버를 연결하면: * AI와 대화하면서 슈츠 데이터를 조회하고 수정 * 블록, 데이터모델, 워크플로우 등 50개 도구 사용 가능 * 별도 코드 작성 없이 자연어로 슈츠 조작 <Callout type="info"> MCP 연결 시 AI 도구(Claude Desktop 등)가 자체 API 키와 토큰을 사용합니다. 슈츠에서 별도 토큰 비용이 발생하지 않습니다. </Callout> *** 인증 방식 [#인증-방식] 슈츠 MCP 서버는 공식 프로토콜에 따라 **OAuth 2.1 인증**을 사용합니다. 워크스페이스별로 고유한 MCP URL을 통해 연결합니다. <Callout type="info"> **간편한 인증**: 처음 연결 시 브라우저를 통해 슈츠 계정으로 로그인만 하면 됩니다. 별도 API Key 설정이 필요 없습니다. </Callout> 설정 방법 [#설정-방법] ```json { "mcpServers": { "suits": { "type": "http", "url": "https://suits.work/api/mcp/{workspaceId}" } } } ``` `{workspaceId}`는 워크스페이스 설정에서 확인할 수 있습니다. 연결 과정 [#연결-과정] 1. 첫 연결 시 브라우저를 통해 **슈츠 계정으로 로그인** 화면이 열림 2. 로그인 완료 후 자동으로 연결됨 3. OAuth 사용자가 해당 워크스페이스의 **멤버인지 검증**됨 4. 모든 작업이 **실제 로그인한 사용자**로 기록됨 *** 사전 준비 [#사전-준비] 1단계: 워크스페이스 ID 확인 [#1단계-워크스페이스-id-확인] 1. 워크스페이스 사이드바 하단의 **설정** (톱니바퀴 아이콘) 클릭 2. 설정 모달에서 **API 키** 탭 선택 3. 상단의 **MCP 연결 URL** 섹션에서 전체 URL 확인 및 복사 <Callout type="info"> **MCP 연결 URL**은 `https://suits.work/api/mcp/{workspaceId}` 형식으로, 복사 버튼을 클릭하면 전체 URL이 클립보드에 복사됩니다. </Callout> 2단계: 서버 URL 구성 [#2단계-서버-url-구성] ``` https://suits.work/api/mcp/{workspaceId} ``` 예시: ``` https://suits.work/api/mcp/d5e7d4fa-781e-4d02-a262-6761a4a0f877 ``` *** Claude Desktop 연결 [#claude-desktop-연결] Claude Desktop 설정 파일을 수정하여 슈츠 MCP 서버를 추가합니다. macOS [#macos] 설정 파일 위치: `~/Library/Application Support/Claude/claude_desktop_config.json` ```json { "mcpServers": { "suits": { "type": "http", "url": "https://suits.work/api/mcp/{workspaceId}" } } } ``` Windows [#windows] 설정 파일 위치: `%APPDATA%\Claude\claude_desktop_config.json` 동일한 JSON 구조를 사용합니다. 연결 확인 [#연결-확인] Claude Desktop을 재시작한 후, 대화창에서 다음과 같이 물어보세요: > "슈츠에서 데이터모델 목록을 보여줘" *** Claude Code 연결 [#claude-code-연결] Claude Code의 MCP 설정 파일을 수정합니다. 설정 방법 [#설정-방법-1] 프로젝트 루트의 `.mcp.json` 또는 CLI 명령어로 설정: ```json { "mcpServers": { "suits": { "type": "http", "url": "https://suits.work/api/mcp/{workspaceId}" } } } ``` 또는 CLI로 추가: ```bash claude mcp add --transport http suits https://suits.work/api/mcp/{workspaceId} ``` 연결 확인 [#연결-확인-1] Claude Code에서 `/mcp` 명령어를 실행하여 연결 상태를 확인합니다: ``` suits: https://suits.work/api/mcp/... (HTTP) - ✓ Connected ``` 처음 연결 시 브라우저에서 Google 로그인 창이 열립니다. *** Cursor 연결 [#cursor-연결] Cursor 설정에서 MCP 서버를 추가합니다. 설정 파일 [#설정-파일] `~/.cursor/mcp.json`: ```json { "servers": { "suits": { "type": "http", "url": "https://suits.work/api/mcp/{workspaceId}" } } } ``` <Callout type="warn"> Cursor의 MCP HTTP + OAuth 지원은 버전에 따라 다를 수 있습니다. 연결이 안 될 경우 Cursor 최신 버전으로 업데이트하세요. </Callout> *** Windsurf 연결 [#windsurf-연결] Windsurf IDE에서 MCP 서버를 설정합니다. 설정 파일 [#설정-파일-1] `.windsurf/mcp.json`: ```json { "mcpServers": { "suits": { "url": "https://suits.work/api/mcp/{workspaceId}" } } } ``` <Callout type="warn"> Windsurf의 MCP HTTP + OAuth 지원은 버전에 따라 다를 수 있습니다. 연결이 안 될 경우 최신 버전으로 업데이트하세요. </Callout> *** 모바일에서 슈츠 연결 (ChatMCP 등) [#모바일에서-슈츠-연결-chatmcp-등] iPhone이나 Android에서 슈츠를 사용하려면 MCP 클라이언트 앱을 설치하세요. 지원 앱 [#지원-앱] * **ChatMCP** (iOS/Android) - MCP 서버 연결을 지원하는 AI 채팅 앱 설정 방법 [#설정-방법-2] 앱의 MCP 서버 추가 화면에서: * **URL**: `https://suits.work/api/mcp/{workspaceId}` * **타입**: HTTP (Streamable) 연결 시 브라우저가 열리며 슈츠 계정 로그인을 진행합니다. <Callout type="warn"> **모바일 앱 사용 시 알아두세요** ChatMCP 등 모바일 앱은 데스크톱 앱(Claude Code, Cursor)과 동작이 다릅니다: * ❌ "슈츠에서 데이터 보여줘" → 인식 안 됨 * ✅ "list\_blocks 도구로 블록 목록 보여줘" → 인식됨 모바일 앱은 MCP 서버 이름("suits")을 인식하지 못하고, **도구 이름을 직접 언급**해야 동작합니다. 또한 여러 워크스페이스를 동시에 연결하면 구분이 어려우므로, **하나의 워크스페이스만 연결**하여 사용하는 것을 권장합니다. </Callout> *** 클라이언트별 기능 비교 [#클라이언트별-기능-비교] | 기능 | Claude Code | Cursor | Claude Desktop | ChatMCP | | --------------- | ----------- | ------ | -------------- | ------- | | OAuth 인증 | ✅ | ✅ | ✅ | ✅ | | 서버 이름 인식 | ✅ | ✅ | ✅ | ❌ | | 다중 워크스페이스 구분 | ✅ | ✅ | ✅ | ⚠️ 제한적 | | instructions 활용 | ✅ | ✅ | ✅ | ❌ | <Callout type="info"> **서버 이름 인식**: "슈츠 워크스페이스에서\~" 같은 자연어 질문으로 MCP 서버를 지정할 수 있는지 여부 **instructions 활용**: 서버가 제공하는 사용 가이드를 AI가 참고하는지 여부 </Callout> *** 여러 워크스페이스 동시 연결 [#여러-워크스페이스-동시-연결] 여러 워크스페이스에서 동시에 작업하려면 각각 별도의 MCP 서버로 등록합니다. 설정 예시 [#설정-예시] ```json { "mcpServers": { "suits-marketing": { "type": "http", "url": "https://suits.work/api/mcp/marketing-workspace-id" }, "suits-dev": { "type": "http", "url": "https://suits.work/api/mcp/dev-workspace-id" }, "suits-personal": { "type": "http", "url": "https://suits.work/api/mcp/personal-workspace-id" } } } ``` 사용 방법 [#사용-방법] AI에게 어떤 워크스페이스에서 작업할지 명시하면 됩니다: > "마케팅팀 워크스페이스에서 캠페인 데이터모델 목록 보여줘" > "개발팀 워크스페이스에 버그 트래커 페이지 만들어줘" Claude가 맥락에 따라 적절한 워크스페이스의 도구를 선택합니다. <Callout type="info"> 각 워크스페이스의 ID는 슈츠 웹에서 해당 워크스페이스 설정에서 확인할 수 있습니다. </Callout> <Callout type="warn"> **클라이언트별 다중 워크스페이스 지원 차이** MCP 클라이언트마다 여러 워크스페이스 연결 시 동작이 다릅니다: * **Claude Code, Cursor**: 서버 이름(예: "suits-marketing")으로 워크스페이스를 구분하여 인식 * **ChatMCP 등 일부 앱**: 서버 이름을 인식하지 못하고 도구 이름만 인식하므로, 여러 워크스페이스 연결 시 혼동 가능 다중 워크스페이스가 필요한 경우 Claude Code나 Cursor 사용을 권장합니다. </Callout> *** 사용 가능한 도구 [#사용-가능한-도구] <Callout type="info"> 슈츠 MCP 서버는 **50개의 도구**를 제공합니다. 자세한 도구 목록은 [Taylor AI 도구](/docs/taylor-ai/tools)를 참고하세요. </Callout> *** 문제 해결 [#문제-해결] 인증 오류 (401) [#인증-오류-401] ``` OAuth authentication required ``` **확인사항:** * OAuth 로그인이 완료되었는지 확인 * 브라우저에서 Google 로그인 팝업이 차단되지 않았는지 확인 * URL에 올바른 workspaceId가 포함되어 있는지 확인 권한 오류 (403) [#권한-오류-403] ``` You are not a member of this workspace. Please login with an account that has access. ``` **확인사항:** * 로그인한 계정이 해당 워크스페이스의 멤버인지 확인 * 다른 계정으로 로그인되어 있을 수 있음 (Google 또는 이메일) * 워크스페이스 설정에서 멤버 초대 필요 속도 제한 (429) [#속도-제한-429] ``` Too many requests ``` **확인사항:** * 요청 빈도 줄이기 * `Retry-After` 헤더 확인 후 재시도 연결 안됨 [#연결-안됨] **확인사항:** * 설정 파일 JSON 문법 오류 여부 * AI 도구 재시작 필요 * 인터넷 연결 상태 * URL의 workspaceId가 올바른지 확인 OAuth 로그인 창이 안 뜨는 경우 [#oauth-로그인-창이-안-뜨는-경우] **확인사항:** * 브라우저 팝업이 차단되어 있지 않은지 확인 * Claude Code에서는 터미널에 표시되는 URL을 직접 복사하여 브라우저에서 열 수 있음 *** 기술 사양 [#기술-사양] 프로토콜 [#프로토콜] | 항목 | 값 | | -------------------- | ------------------------ | | MCP Protocol Version | `2025-03-26` | | Transport | HTTP (Streamable) | | OAuth | RFC 8414, RFC 9728 준수 | | Access Token 유효기간 | **30일** (자동 만료 후 재인증 필요) | <Callout type="info"> **프로토콜 버전 안내**: MCP 최신 버전(2025-11-25)은 일부 클라이언트(Cursor 등)에서 아직 지원되지 않아, 호환성을 위해 2025-03-26 버전을 사용합니다. Streamable HTTP와 OAuth 기능은 동일하게 지원됩니다. </Callout> 엔드포인트 [#엔드포인트] | Method | Path | 설명 | | ------ | ------------------------ | -------------- | | POST | `/api/mcp/{workspaceId}` | JSON-RPC 요청 처리 | | GET | `/api/mcp/{workspaceId}` | SSE 스트림 연결 | | DELETE | `/api/mcp/{workspaceId}` | 세션 종료 | OAuth Discovery 엔드포인트 [#oauth-discovery-엔드포인트] | Path | 설명 | | ----------------------------------------------------------------- | ------------------------- | | `/.well-known/oauth-protected-resource/api/mcp/{workspaceId}` | 보호 리소스 메타데이터 (RFC 9728) | | `/.well-known/oauth-authorization-server/oauth/mcp/{workspaceId}` | OAuth 서버 메타데이터 (RFC 8414) | OAuth 엔드포인트 [#oauth-엔드포인트] | Path | 설명 | | ---------------------------------------- | ----------- | | `/api/oauth/mcp/{workspaceId}/authorize` | 인증 시작 | | `/api/oauth/mcp/{workspaceId}/token` | 토큰 발급 | | `/api/oauth/mcp/{workspaceId}/register` | 동적 클라이언트 등록 | 필수 헤더 [#필수-헤더] ```http Authorization: Bearer mcp_xxx... (OAuth 토큰 - MCP 클라이언트가 자동 관리) Content-Type: application/json ``` <Callout type="info"> OAuth 토큰은 MCP 클라이언트가 자동으로 관리합니다. 사용자는 URL에 workspaceId만 설정하면 됩니다. </Callout> *** 다음 단계 [#다음-단계] * [Taylor AI 도구](/docs/taylor-ai/tools) - 50개 도구 상세 설명 * [인증](/docs/api-reference/authentication) - API 키 발급 및 관리 * [데이터모델 API](/docs/api-reference/datamodels-api) - REST API로 데이터 조작 --- # 웹훅 (/docs/api-reference/webhooks) > 슈츠에서 발생하는 이벤트를 실시간으로 수신합니다. import { Callout } from 'fumadocs-ui/components/callout'; 웹훅 개요 [#웹훅-개요] 동작 방식 [#동작-방식] ``` 슈츠에서 이벤트 발생 (행 생성 등) ↓ 웹훅 시스템이 이벤트 감지 ↓ 등록된 엔드포인트로 HTTP POST 요청 ↓ 외부 시스템에서 이벤트 처리 ``` 활용 예시 [#활용-예시] * **외부 시스템 연동**: 새 주문이 등록되면 ERP에 자동 동기화 * **알림**: 중요 데이터 변경 시 Slack/이메일 알림 * **백업**: 데이터 변경 시 외부 데이터베이스에 백업 * **워크플로우**: 외부 자동화 도구(Zapier, Make) 연동 *** 웹훅 설정 [#웹훅-설정] 1단계: 웹훅 엔드포인트 등록 [#1단계-웹훅-엔드포인트-등록] 1. 워크스페이스 **설정** → **개발자 설정** 2. **웹훅** 탭 선택 3. **+ 새 웹훅 추가** 클릭 2단계: 설정 입력 [#2단계-설정-입력] | 설정 | 설명 | 예시 | | --------- | ----------------- | -------------------------------------- | | **이름** | 웹훅 식별 이름 | "주문 알림" | | **URL** | 이벤트를 수신할 엔드포인트 | `https://api.myapp.com/webhooks/suits` | | **이벤트** | 구독할 이벤트 유형 | row\.created, row\.updated | | **데이터모델** | 특정 데이터모델만 구독 (선택) | 주문, 고객 | 3단계: 시크릿 키 저장 [#3단계-시크릿-키-저장] <Callout type="warn"> 웹훅 시크릿 키는 **한 번만 표시**됩니다. 요청 서명 검증에 필요하니 안전하게 저장하세요. </Callout> ``` whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` *** 이벤트 유형 [#이벤트-유형] 데이터모델 (Row) 이벤트 [#데이터모델-row-이벤트] | 이벤트 | 설명 | 트리거 시점 | | ------------- | ------- | ------------ | | `row.created` | 새 행 생성됨 | 행이 처음 생성될 때 | | `row.updated` | 행 수정됨 | 행의 속성이 변경될 때 | | `row.deleted` | 행 삭제됨 | 행이 삭제될 때 | 페이지 이벤트 [#페이지-이벤트] | 이벤트 | 설명 | 트리거 시점 | | -------------- | --------- | ------------- | | `page.created` | 새 페이지 생성됨 | 페이지가 생성될 때 | | `page.updated` | 페이지 수정됨 | 페이지 내용이 변경될 때 | | `page.deleted` | 페이지 삭제됨 | 페이지가 삭제될 때 | 워크스페이스 이벤트 [#워크스페이스-이벤트] | 이벤트 | 설명 | 트리거 시점 | | ---------------- | ------ | --------- | | `member.invited` | 멤버 초대됨 | 새 멤버 초대 시 | | `member.removed` | 멤버 제거됨 | 멤버 삭제 시 | *** 페이로드 형식 [#페이로드-형식] 웹훅 요청은 HTTP POST로 전송되며, JSON 형식의 페이로드를 포함합니다. row.created [#rowcreated] ```json { "id": "evt_abc123def456", "type": "row.created", "createdAt": "2024-03-22T10:30:00Z", "workspaceId": "ws_xxxxx", "data": { "datamodelId": "dm_abc123", "datamodelName": "고객", "rowId": "row_xyz789", "properties": { "회사명": "테크스타트", "이메일": "contact@techstart.co", "상태": "lead", "계약금액": 50000000 }, "createdBy": { "id": "user_001", "name": "김담당", "email": "kim@company.com" } } } ``` row.updated [#rowupdated] ```json { "id": "evt_def456ghi789", "type": "row.updated", "createdAt": "2024-03-22T11:00:00Z", "workspaceId": "ws_xxxxx", "data": { "datamodelId": "dm_abc123", "datamodelName": "고객", "rowId": "row_xyz789", "changes": { "상태": { "before": "lead", "after": "active" }, "계약금액": { "before": 50000000, "after": 55000000 } }, "updatedBy": { "id": "user_002", "name": "이영업", "email": "lee@company.com" } } } ``` row.deleted [#rowdeleted] ```json { "id": "evt_ghi789jkl012", "type": "row.deleted", "createdAt": "2024-03-22T12:00:00Z", "workspaceId": "ws_xxxxx", "data": { "datamodelId": "dm_abc123", "datamodelName": "고객", "rowId": "row_xyz789", "deletedBy": { "id": "user_001", "name": "김담당" } } } ``` *** 요청 헤더 [#요청-헤더] 웹훅 요청에는 다음 헤더가 포함됩니다: ```http POST /webhooks/suits HTTP/1.1 Host: api.myapp.com Content-Type: application/json User-Agent: Suits-Webhook/1.0 X-Suits-Webhook-Id: wh_xxxxx X-Suits-Event-Id: evt_abc123def456 X-Suits-Event-Type: row.created X-Suits-Signature: sha256=xxxxxxxx X-Suits-Timestamp: 1711101000 ``` *** 서명 검증 [#서명-검증] 모든 웹훅 요청은 서명이 포함됩니다. 서명을 검증하여 요청이 슈츠에서 온 것인지 확인하세요. 서명 생성 방식 [#서명-생성-방식] ``` signature = HMAC-SHA256(timestamp + "." + payload, secret) ``` Node.js 검증 예시 [#nodejs-검증-예시] ```javascript const crypto = require('crypto'); function verifyWebhookSignature(req, secret) { const signature = req.headers['x-suits-signature']; const timestamp = req.headers['x-suits-timestamp']; const payload = JSON.stringify(req.body); // 서명 검증 const signedPayload = `${timestamp}.${payload}`; const expectedSignature = 'sha256=' + crypto.createHmac('sha256', secret) .update(signedPayload) .digest('hex'); // 타이밍 세이프 비교 const isValid = crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expectedSignature) ); // 타임스탬프 검증 (5분 이내) const currentTime = Math.floor(Date.now() / 1000); const isRecent = currentTime - parseInt(timestamp) < 300; return isValid && isRecent; } // Express 미들웨어 예시 app.post('/webhooks/suits', (req, res) => { const isValid = verifyWebhookSignature(req, process.env.WEBHOOK_SECRET); if (!isValid) { return res.status(401).json({ error: 'Invalid signature' }); } // 이벤트 처리 const event = req.body; console.log(`Received ${event.type} event`); // 즉시 200 응답 (처리는 비동기로) res.status(200).json({ received: true }); // 비동기 처리 processEvent(event); }); ``` Python 검증 예시 [#python-검증-예시] ```python import hmac import hashlib import time def verify_webhook_signature(payload, signature, timestamp, secret): # 서명 생성 signed_payload = f"{timestamp}.{payload}" expected_signature = 'sha256=' + hmac.new( secret.encode(), signed_payload.encode(), hashlib.sha256 ).hexdigest() # 비교 is_valid = hmac.compare_digest(signature, expected_signature) # 타임스탬프 검증 is_recent = time.time() - int(timestamp) < 300 return is_valid and is_recent ``` *** 재시도 정책 [#재시도-정책] 웹훅 요청이 실패하면 자동으로 재시도합니다. 재시도 스케줄 [#재시도-스케줄] | 시도 | 대기 시간 | 누적 시간 | | -- | ----- | -------- | | 1차 | 1분 | 1분 | | 2차 | 5분 | 6분 | | 3차 | 30분 | 36분 | | 4차 | 2시간 | 2시간 36분 | | 5차 | 24시간 | 26시간 36분 | 실패 조건 [#실패-조건] 다음 경우 요청이 실패한 것으로 간주합니다: * 5초 이내 응답 없음 (타임아웃) * HTTP 상태 코드가 2xx가 아닌 경우 * 연결 불가 <Callout type="info"> 5회 모두 실패하면 해당 이벤트는 폐기됩니다. 개발자 설정에서 실패 로그를 확인할 수 있습니다. </Callout> *** 베스트 프랙티스 [#베스트-프랙티스] 1. 빠른 응답 [#1-빠른-응답] 웹훅 엔드포인트는 **5초 이내**에 응답해야 합니다. ```javascript // ✅ 좋은 예: 즉시 응답, 비동기 처리 app.post('/webhook', (req, res) => { res.status(200).json({ received: true }); // 비동기로 처리 processEventAsync(req.body); }); // ❌ 나쁜 예: 동기 처리 후 응답 app.post('/webhook', async (req, res) => { await heavyDatabaseOperation(); // 시간이 오래 걸림 res.status(200).json({ done: true }); // 타임아웃 위험 }); ``` 2. 멱등성 보장 [#2-멱등성-보장] 같은 이벤트가 여러 번 전송될 수 있습니다. 이벤트 ID로 중복을 방지하세요. ```javascript const processedEvents = new Set(); app.post('/webhook', (req, res) => { const eventId = req.body.id; // 이미 처리한 이벤트 스킵 if (processedEvents.has(eventId)) { return res.status(200).json({ status: 'already_processed' }); } processedEvents.add(eventId); processEvent(req.body); res.status(200).json({ received: true }); }); ``` 3. 로깅 [#3-로깅] 모든 웹훅 요청을 로깅하여 디버깅에 활용하세요. ```javascript app.post('/webhook', (req, res) => { console.log({ eventId: req.body.id, eventType: req.body.type, timestamp: new Date().toISOString(), payload: req.body }); res.status(200).json({ received: true }); }); ``` 4. 에러 처리 [#4-에러-처리] 처리 중 에러가 발생해도 200을 반환하되, 내부적으로 에러를 기록하세요. ```javascript app.post('/webhook', async (req, res) => { res.status(200).json({ received: true }); try { await processEvent(req.body); } catch (error) { // 에러 로깅 (재시도하지 않음) console.error('Webhook processing error:', error); await alertTeam(error); // 팀에게 알림 } }); ``` *** 테스트 [#테스트] 웹훅 테스트 도구 [#웹훅-테스트-도구] 개발자 설정에서 **테스트 이벤트 전송** 버튼으로 웹훅을 테스트할 수 있습니다. 로컬 개발 테스트 [#로컬-개발-테스트] 로컬 환경에서 테스트하려면 터널링 서비스를 사용하세요: ```bash # ngrok 사용 ngrok http 3000 # 출력된 URL을 웹훅 엔드포인트로 등록 # https://abc123.ngrok.io/webhooks/suits ``` *** 웹훅 로그 [#웹훅-로그] 개발자 설정에서 최근 웹훅 요청 로그를 확인할 수 있습니다: * **이벤트 ID** * **이벤트 유형** * **요청 시간** * **응답 상태** * **재시도 횟수** * **페이로드** (클릭하여 상세 확인) *** 문제 해결 [#문제-해결] 웹훅이 수신되지 않음 [#웹훅이-수신되지-않음] 1. 엔드포인트 URL이 올바른지 확인 2. 서버가 외부에서 접근 가능한지 확인 3. 방화벽/보안 그룹 설정 확인 4. 구독한 이벤트 유형 확인 서명 검증 실패 [#서명-검증-실패] 1. 시크릿 키가 올바른지 확인 2. payload를 raw string으로 사용하는지 확인 3. 타임스탬프 형식 확인 타임아웃 발생 [#타임아웃-발생] 1. 엔드포인트가 5초 이내에 응답하는지 확인 2. 무거운 작업은 비동기로 처리 3. 큐 시스템 도입 고려 (Redis, SQS 등) *** 다음 단계 [#다음-단계] * [인증](/docs/api-reference/authentication) - API 키 발급 * [데이터모델 API](/docs/api-reference/datamodels-api) - 데이터 조회/조작 --- # 사용량 집계 기준 (/docs/billing/usage-policy) > Suits의 리소스별 사용량 측정 및 토큰 환산 기준 사용량 집계 기준 [#사용량-집계-기준] Suits는 **Suits Token**이라는 통합 단위로 모든 리소스 사용량을 측정합니다. 각 리소스 유형별로 다른 기준으로 토큰이 계산됩니다. 리소스 유형별 집계 기준 [#리소스-유형별-집계-기준] 1. AI 사용량 [#1-ai-사용량] Taylor(대화형 AI 에이전트)를 사용할 때 소비되는 토큰입니다. | 항목 | 설명 | | --------- | ---------------------------------- | | **측정 기준** | AI 모델에 전송한 입력 토큰 + 생성된 출력 토큰 | | **가중치** | 출력 토큰은 입력 토큰의 4배로 계산 (생성 비용이 더 높음) | | **집계 시점** | AI 대화 완료 시 즉시 기록 | 모델별 환산율 [#모델별-환산율] | 모델 | 1K AI 토큰당 Suits Token | | ------------- | --------------------- | | Claude Sonnet | 2,250 | | Claude Haiku | 600 | | Gemini Pro | 1,000 | <Callout type="info"> 사용하는 AI 모델에 따라 동일한 대화량이라도 토큰 소비가 달라집니다. 비용 효율이 중요하다면 Claude Haiku 모델을 권장합니다. 긴 대화는 컨텍스트가 누적되어 입력 토큰이 증가하니 참고하세요. </Callout> <Callout type="tip"> 외부 AI 계정 키를 연결하거나, MCP를 통해 외부 AI 도구를 사용하면 AI 토큰이 차감되지 않습니다. </Callout> *** 2. 자동화(워크플로우) 사용량 [#2-자동화워크플로우-사용량] 워크플로우가 실행될 때 소비되는 토큰입니다. | 항목 | 설명 | | --------- | --------------------- | | **측정 기준** | 워크플로우 실행 시간 (초 단위) | | **기본 비율** | 1초당 10 Suits Token | | **최소 토큰** | 실행당 최소 25 Suits Token | | **집계 시점** | 워크플로우 완료(성공/실패) 시 기록 | 계산 예시 [#계산-예시] | 시나리오 | 실행 시간 | 계산 | 결과 | | -------- | ----- | ------------- | ------ | | 단순 워크플로우 | 2초 | max(2×10, 25) | 25 토큰 | | 중간 워크플로우 | 5초 | 5×10 | 50 토큰 | | 긴 워크플로우 | 10초 | 10×10 | 100 토큰 | <Callout type="info"> 외부 AI(MCP 연결, 외부 계정 연동)를 사용하는 워크플로우는 AI 토큰이 별도로 차감되지 않습니다. 실행 시간 기준으로만 토큰이 계산되므로, 외부 AI 응답 대기 시간이 포함됩니다. </Callout> *** 3. 스토리지 사용량 [#3-스토리지-사용량] 워크스페이스에 저장된 데이터 용량입니다. | 항목 | 설명 | | --------- | ----------------------------- | | **측정 기준** | 데이터베이스 + 파일 저장 용량 (GB) | | **비율** | 1GB/월당 5,800 Suits Token | | **포함 항목** | 블록, 데이터모델 행, 워크플로우 정의, 업로드 파일 | | **집계 시점** | 12시간마다 자동 집계 또는 수동 새로고침 시 | 계산 예시 [#계산-예시-1] | 저장 용량 | 월간 토큰 | | ------ | --------- | | 100 MB | 약 580 토큰 | | 1 GB | 5,800 토큰 | | 10 GB | 58,000 토큰 | *** 사용량 확인 및 갱신 [#사용량-확인-및-갱신] 확인 방법 [#확인-방법] 1. 사이드바에서 워크스페이스 이름 클릭 2. **설정** 선택 3. 왼쪽 메뉴에서 **사용량** 클릭 현재 월의 총 사용량과 리소스별 상세 내역, 일별 추이를 확인할 수 있습니다. 갱신 주기 [#갱신-주기] | 리소스 | 데이터 기록 | 대시보드 갱신 | | ---- | ------------- | ------------ | | AI | 대화 완료 시 즉시 | 12시간마다 자동 집계 | | 자동화 | 워크플로우 완료 시 즉시 | 12시간마다 자동 집계 | | 스토리지 | 변경 시 즉시 | 12시간마다 자동 집계 | <Callout type="tip"> 워크스페이스 설정 > 사용량 탭에서 **새로고침** 버튼을 누르면 전체 사용량이 즉시 갱신됩니다. </Callout> *** 자주 묻는 질문 [#자주-묻는-질문] 토큰이 0으로 표시됩니다 [#토큰이-0으로-표시됩니다] * **스토리지**: 새로고침 버튼을 눌러 수동 갱신해보세요. * **자동화**: 워크플로우가 실제로 완료(성공/실패)되었는지 확인하세요. 실행 중인 워크플로우는 집계되지 않습니다. * **AI**: AI 대화가 정상적으로 완료되었는지 확인하세요. --- # Artifact 블록 (/docs/blocks/artifact-block) > AI가 생성한 HTML/CSS/JS 코드를 실행하는 인터랙티브 블록을 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; Artifact 블록이란 [#artifact-블록이란] Artifact 블록은 HTML, CSS, JavaScript 코드를 **sandboxed iframe** 안에서 실행하는 인터랙티브 블록입니다. 일반 블록으로는 표현하기 어려운 커스텀 UI를 자유롭게 구현할 수 있습니다. 주요 활용 사례: * **커스텀 대시보드** -- 여러 데이터소스를 조합한 맞춤형 화면 * **인터랙티브 폼** -- 데이터 입력 후 워크플로우 실행 * **데이터 시각화** -- D3.js, Chart.js 등을 활용한 고급 차트 테일러 AI에게 자연어로 요청하여 생성하거나, 코드 에디터에서 직접 작성할 수 있습니다. *** 생성 방법 [#생성-방법] | 방법 | 입력 | | ------ | ----------------------------------------- | | 테일러 AI | 자연어로 요청 (예: "이번 달 매출 추이를 인터랙티브 차트로 만들어줘") | *** 코드 편집 [#코드-편집] 블록 우측 상단의 드롭다운 메뉴에서 **"코드 편집"** 을 선택하면 에디터가 열립니다. 에디터 구성 [#에디터-구성] * **좌측**: CodeMirror 기반 코드 에디터 * **우측**: 실시간 미리보기 탭 구성 [#탭-구성] | 탭 | 설명 | | -------- | --------------- | | **HTML** | 블록의 마크업 구조 | | **CSS** | 스타일 정의 | | **JS** | 동작 로직 | | **CDN** | 외부 라이브러리 URL 관리 | 저장 [#저장] `Ctrl+S` (Windows/Linux) 또는 `Cmd+S` (Mac)로 저장하면 미리보기에 즉시 반영됩니다. *** 기본 제공 요소 [#기본-제공-요소] Artifact 블록에는 별도 설정 없이 사용할 수 있는 요소들이 포함되어 있습니다. 디자인 토큰 CSS [#디자인-토큰-css] 다크/라이트 모드를 자동으로 지원하는 CSS 변수가 제공됩니다. ```css /* 사용 예시 */ .card { background: var(--background); color: var(--foreground); border: 1px solid var(--border); } .highlight { color: var(--primary); } .subtle-text { color: var(--muted); } ``` 주요 변수: `--primary`, `--foreground`, `--background`, `--border`, `--muted` 등 Basecoat UI [#basecoat-ui] 미리 로드된 UI 컴포넌트 라이브러리입니다. class 기반으로 버튼, 카드, 테이블 등 기본 UI를 빠르게 구성할 수 있습니다. ```html <button class="bc-button">저장</button> <div class="bc-card"> <div class="bc-card-header">제목</div> <div class="bc-card-content">내용</div> </div> ``` Suits SDK [#suits-sdk] `window.suits` 객체를 통해 데이터 접근, 워크플로우 실행 등 플랫폼 기능을 사용할 수 있습니다. 자세한 API는 [Artifact SDK 문서](/docs/blocks/artifact-sdk)를 참고하세요. *** CDN 의존성 [#cdn-의존성] 외부 JavaScript 라이브러리를 CDN으로 추가하여 사용할 수 있습니다. 에디터의 **CDN** 탭에서 URL을 등록합니다. 허용된 CDN 호스트 [#허용된-cdn-호스트] | 호스트 | | ---------------------- | | `cdn.jsdelivr.net` | | `cdnjs.cloudflare.com` | | `unpkg.com` | | `cdn.tailwindcss.com` | | `esm.sh` | | `cdn.skypack.dev` | | `d3js.org` | | `cdn.d3js.org` | 보안을 위해 위 호스트에서 제공되는 라이브러리만 사용할 수 있습니다. *** 데이터소스 연결 [#데이터소스-연결] Artifact에서 데이터모델이나 통계 정의의 데이터에 접근하려면 **데이터소스를 사전에 연결**해야 합니다. 데이터소스 설정 [#데이터소스-설정] | 항목 | 설명 | | -------------- | ------------------------------------------------ | | **타입** | `datamodel` (데이터모델) 또는 `stat_definition` (통계 정의) | | **접근 권한** | `read` (읽기 전용) 또는 `readwrite` (읽기/쓰기) | | **별칭 (alias)** | 코드에서 데이터소스를 참조할 이름 | 사용 예시 [#사용-예시] ```js // 데이터소스에 등록한 데이터모델의 데이터 조회 const { rows } = await suits.fetchRows("dm_orders_id"); ``` *** 워크플로우 연결 [#워크플로우-연결] Artifact에서 워크플로우를 실행하려면 **사전에 허용할 워크플로우를 등록**해야 합니다. 워크플로우 설정 [#워크플로우-설정] | 항목 | 설명 | | -------------- | ------------------ | | **워크플로우** | 실행할 워크플로우 선택 | | **별칭 (alias)** | 코드에서 워크플로우를 참조할 이름 | 사용 예시 [#사용-예시-1] ```js // 별칭 "processOrder"로 등록한 워크플로우 실행 const workflowId = suits.getWorkflowId("processOrder"); await suits.executeWorkflow(workflowId, { orderId: "12345" }); ``` *** 높이 설정 [#높이-설정] | 모드 | 설명 | | ----------- | --------------------------------- | | **자동** (기본) | 콘텐츠 크기에 맞게 자동 조절 (body 크기 변화를 감지) | | **고정** | 지정한 높이로 고정 (최소 32px) | *** 보안 [#보안] Artifact 블록은 다음과 같은 보안 정책으로 안전하게 실행됩니다. | 정책 | 설명 | | ----------------- | ----------------------------------------------------- | | **Sandbox** | `allow-scripts` 권한만 부여된 iframe에서 실행 (페이지 이동, 폼 제출 차단) | | **CDN 화이트리스트** | 허용된 도메인의 라이브러리만 로드 가능 | | **데이터소스 제한** | 사전 등록된 데이터소스만 접근 가능 | | **워크플로우 제한** | 사전 등록된 워크플로우만 실행 가능 | | **Rate Limiting** | API 호출에 속도 제한 적용 | *** 활용 예시 [#활용-예시] 커스텀 대시보드 [#커스텀-대시보드] 여러 데이터소스를 조합하여 맞춤형 대시보드를 구성합니다. ```html <div class="dashboard"> <div class="kpi-row"> <div class="bc-card" id="revenue-card"></div> <div class="bc-card" id="orders-card"></div> <div class="bc-card" id="customers-card"></div> </div> <div class="chart-area"> <canvas id="trend-chart"></canvas> </div> </div> ``` ```js // 매출, 주문 데이터를 각각 조회하여 대시보드 구성 const { rows: revenue } = await suits.fetchRows("dm_monthly_sales_id"); const { rows: orders } = await suits.fetchRows("dm_recent_orders_id"); document.getElementById("revenue-card").textContent = `이번 달 매출: ${revenue[0].data.total.toLocaleString()}원`; ``` 입력 폼 [#입력-폼] 데이터를 입력받아 워크플로우를 실행하는 폼을 만듭니다. ```html <form id="order-form"> <label>상품명</label> <input type="text" name="product" class="bc-input" /> <label>수량</label> <input type="number" name="quantity" class="bc-input" /> <button type="submit" class="bc-button">주문 요청</button> </form> ``` ```js document.getElementById("order-form").addEventListener("submit", async (e) => { e.preventDefault(); const formData = new FormData(e.target); const workflowId = suits.getWorkflowId("createOrder"); await suits.executeWorkflow(workflowId, { product: formData.get("product"), quantity: Number(formData.get("quantity")), }); }); ``` 데이터 시각화 [#데이터-시각화] CDN에서 Chart.js를 로드하여 고급 차트를 만듭니다. ```js // CDN 탭에 https://cdn.jsdelivr.net/npm/chart.js 추가 후 사용 const { rows: salesData } = await suits.fetchRows("dm_monthly_sales_id"); new Chart(document.getElementById("trend-chart"), { type: "line", data: { labels: salesData.map((d) => d.month), datasets: [{ label: "월별 매출", data: salesData.map((d) => d.total), borderColor: "var(--primary)", }], }, }); ``` <Callout type="tip"> 복잡한 인터랙티브 UI가 필요하면 테일러에게 요청하세요. "주문 현황을 실시간으로 보여주는 대시보드를 만들어줘"처럼 자연어로 요청하면 됩니다. </Callout> *** 다음 단계 [#다음-단계] * [Artifact SDK](/docs/blocks/artifact-sdk) -- Suits SDK API 레퍼런스 * [데이터 블록](/docs/blocks/data-blocks) -- 통계 블록, 데이터모델 블록 * [워크플로우](/docs/workflows) -- 워크플로우 가이드 --- # 아티팩트 SDK (/docs/blocks/artifact-sdk) > 아티팩트 블록에서 사용할 수 있는 Suits SDK API를 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] Artifact 블록의 iframe 안에서는 `window.suits` 객체를 통해 Suits SDK를 사용할 수 있습니다. 별도의 import나 설치 없이, 코드 작성 즉시 사용 가능합니다. ```javascript // iframe 내부 어디서든 바로 사용 const rows = await suits.fetchRows("dm_abc123"); suits.toast.success("데이터를 불러왔습니다."); ``` <Callout type="info"> Suits SDK는 Artifact 블록의 iframe에 자동으로 주입됩니다. 별도의 스크립트 로드나 초기화가 필요하지 않습니다. </Callout> *** 초기화 데이터 [#초기화-데이터] `window.suits` 객체에는 블록이 로드될 때 다음 데이터가 자동으로 주입됩니다. | 속성 | 타입 | 설명 | | ------------------------ | ----------------------------------------------------- | ---------------- | | `suits.user` | `{ id: string, name: string \| null }` | 현재 로그인한 사용자 정보 | | `suits.theme` | `{ mode: 'light' \| 'dark' }` | 현재 테마 모드 | | `suits.block` | `{ id: string, workspaceId: string, pageId: string }` | 현재 블록 정보 | | `suits.allowedWorkflows` | `[{ id: string, alias: string }]` | 블록에 등록된 워크플로우 목록 | | `suits.globalFilters` | `[{ id, name, type, value }]` | 페이지의 글로벌 필터 현재 값 | ```javascript // 초기화 데이터 접근 예시 console.log(suits.user.name); // "홍길동" console.log(suits.theme.mode); // "light" 또는 "dark" console.log(suits.block.workspaceId); // "ws_abc123" ``` *** 데이터 읽기 API [#데이터-읽기-api] 데이터를 읽으려면 블록 설정에서 해당 데이터모델 또는 통계 정의를 **데이터소스로 등록**해야 합니다. `read` 이상의 접근 권한이 필요합니다. suits.fetchRows(dataModelId, options?) [#suitsfetchrowsdatamodelid-options] 데이터모델에서 행 데이터를 조회합니다. **매개변수** | 이름 | 타입 | 필수 | 설명 | | ----------- | ------ | --- | -------- | | dataModelId | string | 예 | 데이터모델 ID | | options | object | 아니오 | 조회 옵션 | **반환값** ```javascript Promise<{ rows: [...] }> ``` **예시** ```javascript const result = await suits.fetchRows("dm_abc123"); console.log(result.rows); // [{ id: "row_1", data: { ... } }, ...] ``` *** suits.fetchStatData(statDefId, options?) [#suitsfetchstatdatastatdefid-options] 통계 정의의 실행 결과 데이터를 조회합니다. **매개변수** | 이름 | 타입 | 필수 | 설명 | | --------- | ------ | --- | -------- | | statDefId | string | 예 | 통계 정의 ID | | options | object | 아니오 | 조회 옵션 | **반환값** ```javascript Promise<{ ... }> // 통계 정의에 따른 결과 데이터 ``` **예시** ```javascript const stats = await suits.fetchStatData("stat_monthly_revenue"); console.log(stats); ``` *** suits.fetchDataModelSchema(dataModelId) [#suitsfetchdatamodelschemadatamodelid] 데이터모델의 프로퍼티(컬럼) 정보를 조회합니다. 컬럼 이름, 타입, 옵션 등의 스키마 정보를 확인할 때 사용합니다. **매개변수** | 이름 | 타입 | 필수 | 설명 | | ----------- | ------ | -- | -------- | | dataModelId | string | 예 | 데이터모델 ID | **반환값** ```javascript Promise<{ properties: [{ id, name, type, ... }] }> ``` **예시** ```javascript const schema = await suits.fetchDataModelSchema("dm_abc123"); schema.properties.forEach((prop) => { console.log(`${prop.name} (${prop.type})`); }); // 회사명 (TEXT) // 매출 (CURRENCY) // 상태 (SELECT) ``` *** suits.getGlobalFilters() [#suitsgetglobalfilters] 페이지에 설정된 글로벌 필터의 현재 값을 조회합니다. **반환값** ```javascript Promise<[{ id: string, name: string, type: string, value: any }]> ``` **예시** ```javascript const filters = await suits.getGlobalFilters(); filters.forEach((f) => { console.log(`${f.name}: ${f.value}`); }); // 기간: 2026-03 // 팀: 영업1팀 ``` *** 데이터 쓰기 API [#데이터-쓰기-api] 데이터를 쓰려면 블록 설정에서 해당 데이터모델을 **`readwrite` 권한으로 데이터소스에 등록**해야 합니다. <Callout type="warn"> `read` 권한으로 등록된 데이터소스에 쓰기 API를 호출하면 `"Unauthorized data source"` 에러가 발생합니다. </Callout> suits.addRow(dataModelId, values) [#suitsaddrowdatamodelid-values] 데이터모델에 새 행을 추가합니다. **매개변수** | 이름 | 타입 | 필수 | 설명 | | ----------- | ------ | -- | ------------------- | | dataModelId | string | 예 | 데이터모델 ID | | values | object | 예 | 프로퍼티 ID를 키로 하는 값 객체 | **예시** ```javascript const result = await suits.addRow("dm_abc123", { prop_001: "신규 고객사", prop_002: "contact@example.com", prop_003: 50000000, prop_004: "lead", }); console.log(result.rowId); // 생성된 행 ID ``` *** suits.updateRow(dataModelId, rowId, values) [#suitsupdaterowdatamodelid-rowid-values] 기존 행의 데이터를 수정합니다. 변경할 프로퍼티만 포함하면 됩니다. **매개변수** | 이름 | 타입 | 필수 | 설명 | | ----------- | ------ | -- | -------------- | | dataModelId | string | 예 | 데이터모델 ID | | rowId | string | 예 | 수정할 행 ID | | values | object | 예 | 변경할 프로퍼티 ID와 값 | **예시** ```javascript await suits.updateRow("dm_abc123", "row_111", { prop_004: "active", prop_003: 75000000, }); suits.toast.success("상태가 업데이트되었습니다."); ``` *** suits.deleteRow(dataModelId, rowId) [#suitsdeleterowdatamodelid-rowid] 행을 삭제합니다. **매개변수** | 이름 | 타입 | 필수 | 설명 | | ----------- | ------ | -- | -------- | | dataModelId | string | 예 | 데이터모델 ID | | rowId | string | 예 | 삭제할 행 ID | **예시** ```javascript await suits.deleteRow("dm_abc123", "row_111"); suits.toast("행이 삭제되었습니다."); ``` *** 워크플로우 API [#워크플로우-api] 워크플로우를 실행하려면 블록 설정에서 해당 워크플로우를 **허용 워크플로우(allowedWorkflows)에 등록**해야 합니다. <Callout type="info"> 등록되지 않은 워크플로우를 실행하려 하면 `"Unauthorized workflow"` 에러가 발생합니다. </Callout> suits.executeWorkflow(workflowId, triggerData?) [#suitsexecuteworkflowworkflowid-triggerdata] 워크플로우를 실행합니다. **Fire-and-forget** 방식으로, 실행을 요청한 뒤 결과를 기다리지 않습니다. **매개변수** | 이름 | 타입 | 필수 | 설명 | | ----------- | ------ | --- | -------------- | | workflowId | string | 예 | 워크플로우 ID | | triggerData | object | 아니오 | 워크플로우에 전달할 데이터 | **예시** ```javascript const workflowId = suits.getWorkflowId("sendNotification"); await suits.executeWorkflow(workflowId, { recipient: "user@example.com", message: "주문이 접수되었습니다.", }); suits.toast.info("알림을 발송 중입니다."); ``` *** suits.executeWorkflowAndWait(workflowId, triggerData?, options?) [#suitsexecuteworkflowandwaitworkflowid-triggerdata-options] 워크플로우를 실행하고, **완료될 때까지 대기**합니다. SSE 스트림을 통해 결과를 실시간으로 수신하며, 마지막 노드의 실행 결과가 반환됩니다. **매개변수** | 이름 | 타입 | 필수 | 설명 | | ----------- | ------ | --- | -------------- | | workflowId | string | 예 | 워크플로우 ID | | triggerData | object | 아니오 | 워크플로우에 전달할 데이터 | | options | object | 아니오 | 실행 옵션 | **options 속성** | 이름 | 타입 | 기본값 | 설명 | | ------- | ------ | ----------- | ---------- | | timeout | number | 360000 (6분) | 타임아웃 (밀리초) | **반환값** ```javascript Promise<lastNodeResult> // 워크플로우 마지막 노드의 실행 결과 ``` **예시** ```javascript const workflowId = suits.getWorkflowId("analyzeData"); const result = await suits.executeWorkflowAndWait(workflowId, { dataModelId: "dm_abc123", period: "2026-03", }); console.log(result); // 마지막 노드의 실행 결과 // 타임아웃 지정 const result2 = await suits.executeWorkflowAndWait(workflowId, null, { timeout: 120000, // 2분 }); ``` <Callout type="warn"> 장시간 실행되는 워크플로우의 경우, 기본 타임아웃(6분)을 초과하면 에러가 발생합니다. 필요에 따라 `timeout` 옵션을 조정하세요. </Callout> *** suits.getWorkflowId(alias) [#suitsgetworkflowidalias] 워크플로우의 별칭(alias)으로 ID를 조회합니다. `allowedWorkflows`에 등록된 워크플로우 중에서 검색합니다. **매개변수** | 이름 | 타입 | 필수 | 설명 | | ----- | ------ | -- | -------- | | alias | string | 예 | 워크플로우 별칭 | **반환값** ```javascript string | null // 워크플로우 ID 또는 null (일치하는 별칭이 없을 때) ``` **예시** ```javascript const workflowId = suits.getWorkflowId("processOrder"); if (workflowId) { await suits.executeWorkflow(workflowId, { orderId: "12345" }); } else { suits.toast.error("워크플로우를 찾을 수 없습니다."); } ``` <Callout type="tip"> `getWorkflowId`는 동기 함수입니다. `await` 없이 바로 사용할 수 있습니다. </Callout> *** UI API [#ui-api] suits.toast(message, options?) [#suitstoastmessage-options] 토스트 알림을 표시합니다. 4가지 변형을 제공합니다. | 메서드 | 설명 | | ---------------------------------------- | ------ | | `suits.toast(message, options?)` | 기본 토스트 | | `suits.toast.success(message, options?)` | 성공 토스트 | | `suits.toast.error(message, options?)` | 에러 토스트 | | `suits.toast.info(message, options?)` | 정보 토스트 | | `suits.toast.warning(message, options?)` | 경고 토스트 | **options 속성** | 이름 | 타입 | 설명 | | ----------- | ------ | ----------------- | | description | string | 토스트 하단에 표시할 부가 설명 | **예시** ```javascript suits.toast("저장되었습니다."); suits.toast.success("주문이 완료되었습니다.", { description: "주문번호: ORD-2026-001", }); suits.toast.error("저장에 실패했습니다."); suits.toast.info("데이터를 불러오는 중입니다."); suits.toast.warning("입력값을 확인해주세요."); ``` *** suits.openModal(options) [#suitsopenmodaloptions] 모달 창을 엽니다. 모달 내부도 독립된 iframe으로 실행되며, Suits SDK를 동일하게 사용할 수 있습니다. **options 속성** | 이름 | 타입 | 필수 | 기본값 | 설명 | | --------------- | --------- | --- | ---- | ---------------- | | title | string | 예 | - | 모달 제목 | | html | string | 예 | - | 모달 본문 HTML | | css | string | 아니오 | `""` | 모달 스타일 CSS | | js | string | 아니오 | `""` | 모달 동작 JavaScript | | width | number | 아니오 | 640 | 모달 너비 (px) | | cdnDependencies | string\[] | 아니오 | `[]` | CDN 라이브러리 URL 목록 | **반환값** ```javascript Promise<any> // suits.closeModal(result)로 전달된 값 ``` **예시** ```javascript const result = await suits.openModal({ title: "고객 정보 입력", html: ` <form id="form"> <label>이름</label> <input type="text" id="name" class="bc-input" /> <label>이메일</label> <input type="email" id="email" class="bc-input" /> <button type="submit" class="bc-button">확인</button> </form> `, js: ` document.getElementById("form").addEventListener("submit", (e) => { e.preventDefault(); suits.closeModal({ name: document.getElementById("name").value, email: document.getElementById("email").value, }); }); `, width: 480, }); // result: { name: "홍길동", email: "hong@example.com" } if (result) { await suits.addRow("dm_customers", { prop_001: result.name, prop_002: result.email, }); } ``` <Callout type="warn"> 모달 내에서 `suits.openModal`을 다시 호출할 수 없습니다. 모달 중첩은 지원되지 않습니다. </Callout> *** suits.closeModal(result?) [#suitsclosemodalresult] 현재 열린 모달을 닫습니다. **모달 iframe 내부에서만 호출할 수 있습니다.** **매개변수** | 이름 | 타입 | 필수 | 설명 | | ------ | --- | --- | ----------------------------- | | result | any | 아니오 | `openModal`의 Promise에 전달할 반환값 | **예시** ```javascript // 모달 내부의 JS에서 호출 suits.closeModal({ confirmed: true, selectedId: "row_123" }); // 취소 버튼 document.getElementById("cancel").addEventListener("click", () => { suits.closeModal(null); }); ``` *** 이벤트 리스너 [#이벤트-리스너] suits.onGlobalFiltersChanged [#suitsonglobalfilterschanged] 페이지의 글로벌 필터 값이 변경될 때 호출되는 콜백입니다. 함수를 할당하면 필터가 변경될 때마다 자동으로 호출됩니다. ```javascript suits.onGlobalFiltersChanged = (filters) => { console.log("필터 변경:", filters); // filters: [{ id, name, type, value }, ...] // 필터 값에 따라 데이터를 다시 조회 const periodFilter = filters.find((f) => f.name === "기간"); if (periodFilter) { loadData(periodFilter.value); } }; ``` *** 테마 변경 감지 [#테마-변경-감지] 테마가 변경되면 `suits.theme.mode`가 자동으로 업데이트되고, `<html>` 태그에 `dark` 클래스가 토글됩니다. CSS 변수를 사용하고 있다면 별도 처리 없이 자동으로 테마가 반영됩니다. 커스텀 로직이 필요한 경우에는 CSS의 `.dark` 선택자를 활용하세요. ```css /* 라이트 모드 */ .chart-line { stroke: #333; } /* 다크 모드 */ .dark .chart-line { stroke: #eee; } ``` ```javascript // JavaScript에서 현재 테마 확인 if (suits.theme.mode === "dark") { // 다크 모드 전용 로직 } ``` *** 사용자 정보 [#사용자-정보] suits.getCurrentUser() [#suitsgetcurrentuser] 현재 로그인한 사용자의 정보를 반환합니다. **반환값** ```javascript Promise<{ id: string, name: string | null } | null> ``` **예시** ```javascript const user = await suits.getCurrentUser(); if (user) { console.log(`${user.name}님, 환영합니다.`); } ``` *** Rate Limiting [#rate-limiting] SDK API 호출에는 속도 제한이 적용됩니다. 제한을 초과하면 `"Rate limit exceeded"` 에러가 발생합니다. | 카테고리 | 해당 API | 제한 | | --------- | ------------------------------------------------------------------------------- | -------------- | | **READ** | `fetchRows`, `fetchStatData`, `fetchDataModelSchema`, `getGlobalFilters` | 5초당 최대 10회 | | **WRITE** | `addRow`, `updateRow`, `deleteRow`, `executeWorkflow`, `executeWorkflowAndWait` | 10초당 최대 5회 | | **TOAST** | `toast`, `toast.success`, `toast.error`, `toast.info`, `toast.warning` | 5초당 최대 5회 (전역) | <Callout type="info"> TOAST의 Rate Limit은 **전역**으로 적용됩니다. 같은 페이지의 여러 Artifact 블록이 공유하므로, 한 페이지에 여러 블록이 있을 경우 전체 합산으로 제한됩니다. </Callout> *** 예제: 고객 목록 대시보드 [#예제-고객-목록-대시보드] 데이터모델에서 고객 데이터를 조회하여 테이블로 표시하고, 행 추가 기능을 제공하는 예제입니다. HTML [#html] ```html <div class="container"> <h2>고객 목록</h2> <button id="add-btn" class="bc-button">고객 추가</button> <table class="bc-table"> <thead> <tr> <th>회사명</th> <th>이메일</th> <th>상태</th> </tr> </thead> <tbody id="table-body"></tbody> </table> </div> ``` CSS [#css] ```css .container { max-width: 800px; margin: 0 auto; } h2 { margin-bottom: 12px; } #add-btn { margin-bottom: 16px; } ``` JS [#js] ```javascript const DATA_MODEL_ID = "dm_abc123"; // 데이터 조회 및 테이블 렌더링 async function loadCustomers() { try { const { rows } = await suits.fetchRows(DATA_MODEL_ID); const tbody = document.getElementById("table-body"); tbody.innerHTML = rows .map( (row) => ` <tr> <td>${row.data.prop_001 || ""}</td> <td>${row.data.prop_002 || ""}</td> <td>${row.data.prop_004 || ""}</td> </tr> ` ) .join(""); } catch (err) { suits.toast.error("데이터를 불러오지 못했습니다.", { description: err.message, }); } } // 고객 추가 버튼 document.getElementById("add-btn").addEventListener("click", async () => { const result = await suits.openModal({ title: "고객 추가", html: ` <form id="form" style="display:flex;flex-direction:column;gap:12px;"> <input id="name" class="bc-input" placeholder="회사명" required /> <input id="email" class="bc-input" placeholder="이메일" type="email" required /> <div style="display:flex;gap:8px;justify-content:flex-end;"> <button type="button" id="cancel" class="bc-button bc-button-outline">취소</button> <button type="submit" class="bc-button">추가</button> </div> </form> `, js: ` document.getElementById("form").addEventListener("submit", (e) => { e.preventDefault(); suits.closeModal({ name: document.getElementById("name").value, email: document.getElementById("email").value, }); }); document.getElementById("cancel").addEventListener("click", () => { suits.closeModal(null); }); `, width: 400, }); if (result) { try { await suits.addRow(DATA_MODEL_ID, { prop_001: result.name, prop_002: result.email, prop_004: "lead", }); suits.toast.success("고객이 추가되었습니다."); loadCustomers(); // 테이블 새로고침 } catch (err) { suits.toast.error("고객 추가에 실패했습니다."); } } }); // 글로벌 필터 변경 시 데이터 새로고침 suits.onGlobalFiltersChanged = () => { loadCustomers(); }; // 초기 로드 loadCustomers(); ``` *** 다음 단계 [#다음-단계] * [Artifact 블록](/docs/blocks/artifact-block) -- 블록 생성 및 설정 가이드 * [데이터 블록](/docs/blocks/data-blocks) -- 통계 블록, 데이터모델 블록 * [워크플로우](/docs/workflows) -- 워크플로우 가이드 --- # 데이터 블록 (/docs/blocks/data-blocks) > 구조화된 데이터를 표시하는 블록들을 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; 데이터모델 뷰 블록 [#데이터모델-뷰-블록] 데이터모델을 페이지에 삽입하여 다양한 형태로 표시합니다. 생성 방법 [#생성-방법] | 방법 | 입력 | | ------- | ------------ | | 슬래시 명령어 | `/datamodel` | 삽입 옵션 [#삽입-옵션] 데이터모델 블록을 추가하면 선택 화면이 나타납니다: 1. **기존 데이터모델 선택**: 워크스페이스의 데이터모델 목록에서 선택 2. **새 데이터모델 생성**: 새로운 데이터모델 생성 후 삽입 뷰 종류 [#뷰-종류] 하나의 데이터모델 블록에서 여러 뷰를 생성하고 전환할 수 있습니다. | 뷰 | 용도 | | ----------- | --------------------- | | **테이블** | 스프레드시트 형태로 데이터 표시/편집 | | **칸반 (보드)** | 상태별 카드 그룹화 (드래그 앤 드롭) | | **캘린더** | 날짜 기반 일정 표시 | | **갤러리** | 카드 그리드 형태 (이미지 썸네일) | | **리스트** | 간결한 목록 형태 | 블록 설정 [#블록-설정] 데이터모델 블록에서 설정할 수 있는 옵션: | 설정 | 설명 | | --------- | -------------- | | **뷰 선택** | 기본 표시할 뷰 선택 | | **필터** | 조건에 맞는 데이터만 표시 | | **정렬** | 정렬 기준 설정 | | **표시 속성** | 표시할 속성(열) 선택 | | **행 높이** | 테이블 행 높이 조정 | | **전체 화면** | 전체 너비로 확장 | 인라인 편집 [#인라인-편집] 데이터모델 블록 내에서 직접 데이터를 편집할 수 있습니다: * 셀 클릭 → 값 편집 * 행 추가/삭제 * 드래그로 순서 변경 <Callout type="info"> 데이터모델 블록의 변경 사항은 원본 데이터모델에 즉시 반영됩니다. 같은 데이터모델을 사용하는 다른 블록에서도 변경 사항이 동기화됩니다. </Callout> *** 통계 블록 (Stat Block) [#통계-블록-stat-block] SQL 쿼리 결과를 **테이블, 차트, 카드** 형태로 시각화합니다. 생성 방법 [#생성-방법-1] | 방법 | 입력 | | ------- | -------------------------------- | | 슬래시 명령어 | `/stat` | | 테일러 AI | 자연어로 요청 (예: "월별 매출 추이를 차트로 보여줘") | 시각화 타입 [#시각화-타입] 통계 블록은 3가지 시각화 타입을 지원합니다. | 타입 | 용도 | 설명 | | ------- | --------- | -------------------------- | | **테이블** | 데이터 상세 분석 | 쿼리 결과를 테이블로 표시, 정렬/필터 지원 | | **차트** | 데이터 시각화 | 7가지 차트 유형 지원 | | **카드** | KPI 표시 | 단일/다중 수치를 크게 표시, 비교값 표시 가능 | 차트 유형 [#차트-유형] | 차트 유형 | 설명 | 적합한 데이터 | | ----------- | --------------------------- | -------------------- | | **XY 콤보** | 막대, 선, 영역, 산점도, 박스를 자유롭게 조합 | 시계열, 카테고리별 비교, 다중 지표 | | **도넛** | 파이/도넛 차트 | 비율, 구성비 | | **레이더** | 다차원 지표를 방사형으로 비교 | 역량 비교, 성과 평가 | | **캘린더 히트맵** | 날짜별 활동량을 색상 농도로 표시 | 일별 매출, 접속 빈도 | | **순위 변동** | 시간에 따른 순위 변화를 추적 | 제품 순위, 경쟁사 비교 | | **퍼널** | 단계별 전환율 표시 | 마케팅 퍼널, 영업 파이프라인 | | **네트워크** | 노드와 엣지로 관계를 시각화 | 조직도, 프로세스 흐름, 의존 관계 | XY 콤보 차트 상세 [#xy-콤보-차트-상세] XY 콤보 차트는 가장 다양한 설정을 지원합니다. | 설정 | 설명 | | ----------- | ------------------------------------------------- | | **X축** | 카테고리, 날짜, 숫자 타입 선택 | | **Y축 (다중)** | 여러 시리즈를 추가하고 각각 표시 방식 선택 | | **표시 방식** | 막대(bar), 선(line), 영역(area), 산점도(scatter), 박스(box) | | **막대 설정** | 가로/세로 방향, 스택 여부 | | **선 설정** | 곡선(smooth), 점 표시, 텐션 조절 | 차트 공통 옵션 [#차트-공통-옵션] | 옵션 | 설명 | | ----------- | ---------------------------------------------------------- | | **색상 테마** | rainbow, blue, green, purple, red, orange, cyan, pink 중 선택 | | **커스텀 색상** | 시리즈별 개별 색상 지정 | | **범례** | 범례 표시/숨기기 | | **그리드** | 격자선 표시/숨기기 | | **툴팁** | 호버 시 상세 정보 표시 | | **날짜 형식** | auto, YYYY-MM-DD, MM/DD, MMM DD 등 | | **정렬** | X축 기준 오름차순/내림차순 | | **데이터 테이블** | 차트 아래에 원본 데이터 테이블 함께 표시 | | **높이** | 140\~840px (28px 단위로 조절) | 카드 표시 [#카드-표시] KPI 수치를 크게 표시합니다. 다중 메트릭과 비교값을 지원합니다. ``` ┌─────────────────────────────────────────────────┐ │ 이번 달 매출 신규 고객 전환율 │ │ │ │ ₩1,650만 32명 24.5% │ │ ▲ 12% (MoM) ▲ 8명 ▲ 2.3%p │ └─────────────────────────────────────────────────┘ ``` | 설정 | 설명 | | ---------- | --------------------------------- | | **다중 메트릭** | 여러 KPI를 한 카드에 표시 | | **표시 형식** | 숫자, 통화(₩), 퍼센트, 텍스트 | | **비교값** | 이전 기간 대비 변화량 또는 변화율 표시 | | **레이아웃** | 가로(horizontal) 또는 세로(vertical) 배치 | | **크기** | 일반(normal) 또는 컴팩트(compact) | 테이블 고급 기능 [#테이블-고급-기능] | 기능 | 설명 | | ----------- | -------------------------------- | | **피벗 테이블** | 행/열 기준으로 데이터 피벗 (합계/평균/개수/최소/최대) | | **조건부 포맷팅** | 값에 따라 색상 변경 | | **히트맵** | 숫자 값을 색상 농도로 표시 | | **고정 열** | 스크롤 시 특정 열 고정 | | **합계 행** | 자동 합계/소계 표시 | | **필터** | 열별 필터링 | 자동 새로고침 (스케줄링) [#자동-새로고침-스케줄링] 통계 블록의 데이터를 자동으로 갱신할 수 있습니다. 통계 정의 편집 화면에서 스케줄을 설정합니다. | 스케줄 타입 | 설명 | 예시 | | --------- | ---------------- | ------------------- | | **반복 주기** | 일정 간격으로 자동 실행 | 5분마다, 1시간마다, 12시간마다 | | **매일** | 매일 지정된 시간에 실행 | 매일 오전 9시 | | **매주** | 매주 지정된 요일/시간에 실행 | 매주 월요일 오전 9시 | 반복 주기 프리셋 [#반복-주기-프리셋] | 프리셋 | | ------ | | 5분마다 | | 10분마다 | | 15분마다 | | 30분마다 | | 1시간마다 | | 2시간마다 | | 3시간마다 | | 6시간마다 | | 12시간마다 | <Callout type="info"> 스케줄은 Asia/Seoul 타임존 기준으로 동작합니다. 스케줄이 설정된 통계 블록은 자동으로 최신 데이터를 표시합니다. </Callout> <Callout type="tip"> 복잡한 분석이 필요하면 테일러에게 요청하세요. "이번 분기 카테고리별 매출을 분석해서 차트로 보여줘"처럼 자연어로 요청할 수 있습니다. </Callout> *** 테이블 블록 [#테이블-블록] 간단한 **정적 테이블**을 만듭니다. 데이터모델과 연결되지 않은 단순한 표입니다. 생성 방법 [#생성-방법-2] | 방법 | 입력 | | ------- | -------- | | 슬래시 명령어 | `/table` | 테이블 구조 [#테이블-구조] ``` | 이름 | 역할 | 이메일 | |---------|---------|---------------------| | 김철수 | 개발자 | kim@example.com | | 이영희 | 디자이너 | lee@example.com | | 박지민 | PM | park@example.com | ``` 테이블 편집 [#테이블-편집] | 동작 | 방법 | | ------- | -------------------- | | 셀 편집 | 셀 클릭 후 타이핑 | | 행 추가 | 마지막 행에서 Tab 또는 하단 버튼 | | 열 추가 | 헤더 우측 + 버튼 | | 행/열 삭제 | 우클릭 메뉴 | | 열 너비 조정 | 열 경계 드래그 | 데이터모델 vs 테이블 블록 [#데이터모델-vs-테이블-블록] | 기능 | 데이터모델 블록 | 테이블 블록 | | -------- | :------: | :----: | | 속성 타입 | ✅ 다양한 타입 | ❌ 텍스트만 | | 필터/정렬 | ✅ | ❌ | | 다양한 뷰 | ✅ | ❌ | | 관계/수식 | ✅ | ❌ | | 워크플로우 연동 | ✅ | ❌ | | 단순함 | △ | ✅ | <Callout type="info"> 간단한 표(가격표, 비교표, 사양표)는 테이블 블록을, 실제 데이터 관리가 필요하면 데이터모델 블록을 사용하세요. </Callout> *** 수식 블록 (Math Block) [#수식-블록-math-block] **LaTeX 문법**으로 수학 공식을 삽입합니다. 생성 방법 [#생성-방법-3] | 방법 | 입력 | | ------- | -------- | | 슬래시 명령어 | `/math` | | 인라인 수식 | `$수식$` | | 블록 수식 | `$$수식$$` | 인라인 수식 [#인라인-수식] 문장 내에 수식을 삽입합니다. ``` 피타고라스 정리: $a^2 + b^2 = c^2$ ``` 결과: 피타고라스 정리: `a² + b² = c²` 블록 수식 [#블록-수식] 독립된 수식 블록으로 표시합니다. ```latex $$ E = mc^2 $$ ``` 결과: `E = mc²` LaTeX 문법 예시 [#latex-문법-예시] | 기능 | 문법 | 결과 | | ------ | ----------------------- | ------- | | 지수 | `x^2` | x² | | 아래첨자 | `x_1` | x₁ | | 분수 | `\frac{a}{b}` | a/b | | 제곱근 | `\sqrt{x}` | √x | | 합 | `\sum_{i=1}^{n} x_i` | Σxᵢ | | 적분 | `\int_0^1 f(x) dx` | ∫f(x)dx | | 그리스 문자 | `\alpha, \beta, \gamma` | α, β, γ | 복잡한 수식 예시 [#복잡한-수식-예시] ```latex $$ f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2} $$ ``` 결과 (정규분포 확률밀도함수): ```latex $$ f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2} $$ ``` *** 활용 예시 [#활용-예시] 대시보드 구성 [#대시보드-구성] 여러 데이터 블록을 조합하여 대시보드를 만들 수 있습니다. ``` ┌─────────────────────────────────────────────────────────┐ │ 📊 영업 대시보드 │ ├─────────────────┬─────────────────┬─────────────────────┤ │ 이번 달 매출 │ 신규 고객 수 │ 전환율 │ │ ₩5,200만 │ 32 │ 24.5% │ │ ▲ 15% │ ▲ 8 │ ▲ 2.3p │ ├─────────────────┴─────────────────┴─────────────────────┤ │ [월별 매출 추이 차트] │ │ ████████████████████████████████████ │ ├─────────────────────────────────────────────────────────┤ │ [영업 기회 파이프라인 - 칸반] │ │ 리드 │ 미팅 │ 협상 │ 계약 │ └─────────────────────────────────────────────────────────┘ ``` 보고서 작성 [#보고서-작성] 통계 블록과 텍스트 블록을 조합하여 보고서를 작성합니다. 1. 제목 블록으로 문서 구조 작성 2. 통계 블록으로 주요 지표 표시 3. 데이터모델 블록으로 상세 데이터 첨부 4. 콜아웃으로 핵심 인사이트 강조 *** 다음 단계 [#다음-단계] * [미디어 블록](/docs/blocks/media-blocks) - 이미지, 동영상 삽입 * [임베드 블록](/docs/blocks/embed-blocks) - 외부 콘텐츠 삽입 * [데이터모델](/docs/datamodels) - 데이터모델 상세 가이드 --- # 임베드 블록 (/docs/blocks/embed-blocks) > 외부 콘텐츠를 페이지에 삽입하세요. import { Callout } from 'fumadocs-ui/components/callout'; <Callout type="warn"> 현재 에디터에서 `/embed`, `/bookmark` 등의 임베드 전용 슬래시 명령어는 제공되지 않습니다. 외부 콘텐츠 삽입은 YouTube 블록(`/youtube`)과 아티팩트 블록(`/artifact`)을 통해 가능합니다. 아래 내용은 향후 지원 예정인 기능을 포함합니다. </Callout> *** 코드 블록 [#코드-블록] \*\*구문 강조(Syntax Highlighting)\*\*가 적용된 코드 블록입니다. 생성 방법 [#생성-방법] | 방법 | 설명 | | ------- | ---------------------------- | | 슬래시 명령어 | `/code` | | 마크다운 | ` ``` ` (백틱 3개) 또는 ` ```언어 ` | | 단축키 | `Cmd/Ctrl + Alt + 8` | 코드 입력 [#코드-입력] ```javascript function greet(name) { return `Hello, ${name}!`; } console.log(greet('Suits')); ``` 언어 선택 [#언어-선택] 코드 블록 우상단에서 프로그래밍 언어를 선택합니다 (검색 가능한 드롭다운). 지원 언어 [#지원-언어] | 언어 | 식별자 | | ---------- | ------------ | | Plain Text | `plaintext` | | JavaScript | `javascript` | | TypeScript | `typescript` | | Python | `python` | | Java | `java` | | C | `c` | | C++ | `cpp` | | C# | `csharp` | | Go | `go` | | Rust | `rust` | | Ruby | `ruby` | | PHP | `php` | | Swift | `swift` | | Kotlin | `kotlin` | | HTML | `html` | | XML | `xml` | | CSS | `css` | | SCSS | `scss` | | Less | `less` | | JSON | `json` | | YAML | `yaml` | | Bash | `bash` | | Shell | `shell` | | Dockerfile | `dockerfile` | | Markdown | `markdown` | | SQL | `sql` | | GraphQL | `graphql` | | Mermaid | `mermaid` | Mermaid 다이어그램 [#mermaid-다이어그램] 언어를 **Mermaid**로 선택하면 다이어그램을 코드로 작성하고 시각적으로 미리볼 수 있습니다. | 뷰 모드 | 설명 | | ------ | ----------------- | | **코드** | Mermaid 코드만 표시 | | **분할** | 코드와 다이어그램을 나란히 표시 | | **차트** | 렌더링된 다이어그램만 표시 | 코드 블록 설정 [#코드-블록-설정] | 설정 | 설명 | | ------ | ----------------------------- | | **언어** | 구문 강조를 위한 언어 선택 (검색 가능한 드롭다운) | 마크다운 문법 [#마크다운-문법] 언어를 지정하려면 백틱 뒤에 언어 식별자를 입력합니다. ````markdown ```python def hello(): print("Hello, World!") ``` ```` *** 레이아웃 블록 [#레이아웃-블록] 컬럼 (Columns) [#컬럼-columns] 콘텐츠를 **가로로 분할**하여 배치합니다. 생성 방법 [#생성-방법-1] | 방법 | 설명 | | ------- | -------------------------------------- | | 슬래시 명령어 | `/2컬럼`, `/3컬럼`, `/4컬럼`, `/5컬럼`, `/6컬럼` | | 키워드 검색 | `/columns` 또는 `/column` | 컬럼 구성 [#컬럼-구성] 슬래시 명령어로 2\~6개의 컬럼을 생성할 수 있으며, 리사이즈 핸들의 **+** 버튼으로 컬럼을 추가하면 최대 10개까지 확장 가능합니다. ``` ┌───────────────┬───────────────┬───────────────┐ │ 컬럼 1 │ 컬럼 2 │ 컬럼 3 │ │ │ │ │ │ 텍스트 │ 이미지 │ 데이터 │ │ 콘텐츠 │ 콘텐츠 │ 콘텐츠 │ │ │ │ │ └───────────────┴───────────────┴───────────────┘ ``` 컬럼 설정 [#컬럼-설정] | 설정 | 설명 | | --------- | --------------------------------- | | **컬럼 수** | 2\~6개 (슬래시 명령어), 최대 10개 (+ 버튼) | | **너비 비율** | 컬럼 사이 리사이즈 핸들 드래그로 60그리드 기반 비율 조절 | | **컬럼 추가** | 컬럼 사이 리사이즈 핸들 위의 + 버튼 클릭 | | **컬럼 삭제** | 빈 컬럼에서 Backspace | <Callout type="tip"> 모바일 환경에서는 컬럼이 자동으로 세로 스택(1열)으로 전환됩니다. </Callout> *** 탭 (Tabs) [#탭-tabs] 콘텐츠를 **탭으로 전환**하여 표시합니다. 생성 방법 [#생성-방법-2] | 방법 | 설명 | | ------- | ------- | | 슬래시 명령어 | `/tabs` | 탭 구성 [#탭-구성] ``` ┌─────────────────────────────────────────────────────────┐ │ [탭 1] [탭 2] [탭 3] │ ├─────────────────────────────────────────────────────────┤ │ │ │ 탭 1 콘텐츠 │ │ │ └─────────────────────────────────────────────────────────┘ ``` 적합한 용도 [#적합한-용도] * 여러 플랫폼별 가이드 (iOS / Android / Web) * 언어별 코드 예시 * 단계별 프로세스 *** 버튼 (Button) [#버튼-button] 클릭 시 **다양한 액션을 실행**하는 버튼입니다. 생성 방법 [#생성-방법-3] | 방법 | 설명 | | ------- | --------- | | 슬래시 명령어 | `/button` | 버튼 설정 [#버튼-설정] | 설정 | 설명 | | ----------------- | ----------------------------------------------------- | | **레이블** | 버튼에 표시할 텍스트 | | **스타일 (variant)** | default, destructive, outline, secondary, ghost, link | | **크기** | default, sm, lg, full (전체 너비) | | **아이콘** | 버튼 아이콘 (선택) | 액션 타입 [#액션-타입] | 타입 | 설명 | | ------------ | --------------- | | **URL** | 외부 링크를 새 탭에서 열기 | | **Alert** | 알림 메시지 표시 | | **Workflow** | 워크플로우 실행 | | **API** | 외부 API 호출 | | **Custom** | 커스텀 액션 | 활용 예시 [#활용-예시] ``` ┌─────────────────────────────────────────────────────────┐ │ │ │ 프로젝트 상태 보고서 │ │ │ │ [📊 보고서 생성] [📧 팀에 공유] [📅 미팅 예약] │ │ │ └─────────────────────────────────────────────────────────┘ ``` <Callout type="info"> 워크플로우 액션 사용 시 실행할 워크플로우를 먼저 생성해야 합니다. [워크플로우 가이드](/docs/workflows)를 참고하세요. </Callout> *** 아티팩트 블록 [#아티팩트-블록] **AI가 생성한 커스텀 UI**를 sandboxed iframe에서 렌더링합니다. 생성 방법 [#생성-방법-4] | 방법 | 설명 | | ------- | ----------- | | 슬래시 명령어 | `/artifact` | 아티팩트 구성 [#아티팩트-구성] HTML, CSS, JS를 직접 작성하여 커스텀 위젯을 만들 수 있습니다. | 설정 | 설명 | | ----------- | ---------------------- | | **HTML** | 기본 마크업 | | **CSS** | 스타일링 (선택) | | **JS** | 인터랙션 로직 (선택) | | **CDN 의존성** | 외부 라이브러리 CDN URL | | **데이터 소스** | 데이터모델 또는 통계 정의 연결 | | **워크플로우** | 실행 가능한 워크플로우 설정 | | **높이** | iframe 높이 (숫자 또는 auto) | *** 다음 단계 [#다음-단계] * [텍스트 블록](/docs/blocks/text-blocks) - 텍스트 콘텐츠 작성 * [미디어 블록](/docs/blocks/media-blocks) - 이미지, 동영상 삽입 * [데이터 블록](/docs/blocks/data-blocks) - 데이터 시각화 --- # 블록 (/docs/blocks) > 페이지를 구성하는 기본 단위인 블록을 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; 블록 시스템 개요 [#블록-시스템-개요] 슈츠는 **22가지 이상의 블록 타입**을 제공하며, 크게 5가지 카테고리로 분류됩니다. | 카테고리 | 블록 수 | 용도 | | --------------- | :--: | --------------- | | **텍스트 블록** | 10개 | 문서 작성, 리스트, 인용 | | **미디어 블록** | 4개 | 이미지, 동영상, 파일 | | **데이터 블록** | 5개 | 데이터모델, 차트, 통계 | | **인터랙티브 블록** | 1개 | 커스텀 HTML/CSS/JS | | **레이아웃/임베드 블록** | 5개 | 컬럼, 탭, 외부 콘텐츠 | *** 블록 추가하기 [#블록-추가하기] 페이지 내에서 블록을 추가하는 방법은 여러 가지입니다. 슬래시 명령어 (/) [#슬래시-명령어-] 가장 빠른 방법입니다. 빈 줄에서 `/`를 입력하면 블록 메뉴가 나타납니다. ``` /h1 → 제목 1 /bullet → 불릿 리스트 /todo → 할 일 목록 /image → 이미지 /datamodel → 데이터모델 /code → 코드 블록 ``` <Callout type="tip"> 블록 이름 일부만 입력해도 검색됩니다. `/dat`만 입력해도 `datamodel`이 검색됩니다. </Callout> 더하기 버튼 (+) [#더하기-버튼-] 줄 왼쪽에 마우스를 올리면 나타나는 `+` 버튼을 클릭합니다. 드래그 앤 드롭 [#드래그-앤-드롭] * 파일을 페이지로 드래그하면 자동으로 적절한 블록이 생성됩니다 * 이미지 → 이미지 블록 * PDF/문서 → 파일 블록 * 동영상 → 비디오 블록 붙여넣기 [#붙여넣기] 클립보드의 콘텐츠를 붙여넣으면 자동으로 변환됩니다. * 스크린샷 → 이미지 블록 * URL → 북마크 또는 임베드 블록 * 코드 → 코드 블록 *** 블록 조작 [#블록-조작] 선택 [#선택] * 클릭하여 단일 블록 선택 * `Shift + 클릭`으로 범위 선택 * `Cmd/Ctrl + A`로 전체 선택 이동 [#이동] 블록 왼쪽의 드래그 핸들(⋮⋮)을 잡고 원하는 위치로 드래그합니다. 복제 [#복제] * 선택 후 `Cmd/Ctrl + D` * 또는 블록 메뉴에서 **복제** 선택 삭제 [#삭제] * 선택 후 `Backspace` 또는 `Delete` * 또는 블록 메뉴에서 **삭제** 선택 블록 ID 복사 [#블록-id-복사] 블록 왼쪽의 드래그 핸들을 클릭하면 나타나는 메뉴에서 **블록 ID 복사**를 선택하면 해당 블록의 고유 ID가 클립보드에 복사됩니다. 복사된 ID는 Taylor AI에게 특정 블록을 지정하여 작업을 요청할 때 활용할 수 있습니다. 블록 타입 변환 [#블록-타입-변환] 일부 블록은 다른 타입으로 변환할 수 있습니다. 1. 블록 선택 2. 왼쪽 드래그 핸들 클릭 또는 `/` 입력 3. 변환할 블록 타입 선택 ``` 텍스트 → 제목, 불릿 리스트, 번호 리스트, 할 일 제목 → 텍스트, 다른 레벨 제목 ``` *** 블록 카테고리 [#블록-카테고리] 텍스트 블록 [#텍스트-블록] 문서 작성을 위한 기본 블록들입니다. | 블록 | 슬래시 명령어 | 마크다운 | 설명 | | ------ | ------------------ | ------ | -------- | | 텍스트 | `/text` | - | 일반 단락 | | 제목 1 | `/h1`, `/heading1` | `# ` | 가장 큰 제목 | | 제목 2 | `/h2`, `/heading2` | `## ` | 중간 제목 | | 제목 3 | `/h3`, `/heading3` | `### ` | 작은 제목 | | 불릿 리스트 | `/bullet` | `- ` | 순서 없는 목록 | | 번호 리스트 | `/numbered` | `1. ` | 순서 있는 목록 | | 할 일 목록 | `/todo` | `[] ` | 체크박스 목록 | | 인용문 | `/quote` | `> ` | 인용 블록 | | 콜아웃 | `/callout` | - | 강조 박스 | | 구분선 | `/divider` | `---` | 수평 구분선 | 👉 [텍스트 블록 자세히 보기](/docs/blocks/text-blocks) *** 미디어 블록 [#미디어-블록] 시각적 콘텐츠를 위한 블록들입니다. | 블록 | 슬래시 명령어 | 설명 | | --- | -------- | -------------------- | | 이미지 | `/image` | 이미지 파일 또는 URL | | 동영상 | `/video` | 업로드 또는 YouTube/Vimeo | | 파일 | `/file` | 문서, 압축파일 등 첨부 | | 오디오 | `/audio` | 음성/음악 파일 | 👉 [미디어 블록 자세히 보기](/docs/blocks/media-blocks) *** 데이터 블록 [#데이터-블록] 구조화된 데이터를 표시하는 블록들입니다. | 블록 | 슬래시 명령어 | 설명 | | ----- | ---------------- | ------------- | | 데이터모델 | `/datamodel` | 데이터모델 뷰 삽입 | | 통계 블록 | `/stat` | SQL 쿼리 결과 시각화 | | 선택 처리 | `/selectprocess` | 항목 선택 후 일괄 처리 | | 테이블 | `/table` | 간단한 정적 테이블 | | 수식 | `/math` | LaTeX 수학 공식 | 👉 [데이터 블록 자세히 보기](/docs/blocks/data-blocks) 👉 [선택 처리 블록 자세히 보기](/docs/blocks/select-process-block) *** 인터랙티브 블록 [#인터랙티브-블록] 코드로 자유롭게 구현하는 인터랙티브 블록입니다. | 블록 | 설명 | | -------- | ----------------------------------------- | | Artifact | HTML/CSS/JS로 커스텀 UI 구현 (대시보드, 폼, 데이터 시각화) | 👉 [Artifact 블록 자세히 보기](/docs/blocks/artifact-block) 👉 [Artifact SDK 레퍼런스](/docs/blocks/artifact-sdk) *** 레이아웃/임베드 블록 [#레이아웃임베드-블록] 페이지 구조와 외부 콘텐츠를 위한 블록들입니다. | 블록 | 슬래시 명령어 | 설명 | | --- | ---------- | ------------- | | 컬럼 | `/columns` | 가로 분할 레이아웃 | | 탭 | `/tabs` | 탭으로 전환되는 영역 | | 버튼 | `/button` | 워크플로우 실행 버튼 | | 임베드 | `/embed` | 외부 콘텐츠 삽입 | | 코드 | `/code` | 코드 블록 (구문 강조) | 👉 [임베드 블록 자세히 보기](/docs/blocks/embed-blocks) *** 단축키 모음 [#단축키-모음] 블록 생성 [#블록-생성] | 단축키 | 동작 | | --------------- | ------------ | | `/` | 블록 메뉴 열기 | | `Enter` | 새 줄 (텍스트 블록) | | `Shift + Enter` | 블록 내 줄바꿈 | | `Tab` | 들여쓰기 | | `Shift + Tab` | 내어쓰기 | 블록 조작 [#블록-조작-1] | 단축키 | 동작 | | ------------------------ | ---------- | | `Cmd/Ctrl + D` | 블록 복제 | | `Cmd/Ctrl + Shift + ↑/↓` | 블록 위/아래 이동 | | `Backspace` / `Delete` | 블록 삭제 | | `Cmd/Ctrl + Z` | 실행 취소 | | `Cmd/Ctrl + Shift + Z` | 다시 실행 | 텍스트 서식 [#텍스트-서식] | 단축키 | 동작 | | -------------- | ------ | | `Cmd/Ctrl + B` | 굵게 | | `Cmd/Ctrl + I` | 기울임 | | `Cmd/Ctrl + U` | 밑줄 | | `Cmd/Ctrl + K` | 링크 추가 | | `Cmd/Ctrl + E` | 인라인 코드 | 블록 타입 변환 (마크다운) [#블록-타입-변환-마크다운] | 입력 | 결과 | | ------- | ------ | | `# ` | 제목 1 | | `## ` | 제목 2 | | `### ` | 제목 3 | | `- ` | 불릿 리스트 | | `1. ` | 번호 리스트 | | `[] ` | 할 일 목록 | | `> ` | 인용문 | | `---` | 구분선 | | ` ``` ` | 코드 블록 | *** 블록 설정 [#블록-설정] 대부분의 블록은 추가 설정을 가지고 있습니다. 블록을 선택하고 오른쪽 설정 패널이나 블록 메뉴에서 설정할 수 있습니다. 공통 설정 [#공통-설정] | 설정 | 설명 | | ---------- | ---------- | | **배경색** | 블록 배경 색상 | | **텍스트 색상** | 텍스트 색상 | | **정렬** | 왼쪽/가운데/오른쪽 | 블록별 특수 설정 [#블록별-특수-설정] * **이미지**: 크기, 캡션, 링크 * **코드**: 언어, 줄번호 * **콜아웃**: 아이콘, 색상 * **데이터모델**: 뷰 타입, 필터, 정렬 *** 이 섹션에서 다루는 내용 [#이-섹션에서-다루는-내용] <Cards> <Card title="텍스트 블록" description="제목, 리스트, 인용문 등 텍스트 콘텐츠" href="/docs/blocks/text-blocks" /> <Card title="미디어 블록" description="이미지, 동영상, 파일 첨부" href="/docs/blocks/media-blocks" /> <Card title="데이터 블록" description="데이터모델, 차트, 테이블" href="/docs/blocks/data-blocks" /> <Card title="임베드 블록" description="외부 콘텐츠, 코드, 레이아웃" href="/docs/blocks/embed-blocks" /> <Card title="Artifact 블록" description="HTML/CSS/JS 커스텀 인터랙티브 블록" href="/docs/blocks/artifact-block" /> </Cards> --- # 미디어 블록 (/docs/blocks/media-blocks) > 이미지, 동영상 등 미디어 콘텐츠를 삽입하세요. import { Callout } from 'fumadocs-ui/components/callout'; 이미지 블록 [#이미지-블록] 이미지를 페이지에 삽입합니다. 생성 방법 [#생성-방법] | 방법 | 설명 | | -------- | -------------------------- | | 슬래시 명령어 | `/image` | | 붙여넣기 | 스크린샷 또는 이미지 `Cmd/Ctrl + V` | | 드래그 앤 드롭 | 파일을 페이지로 드래그 | 이미지 업로드 방법 [#이미지-업로드-방법] 1. 파일 업로드 [#1-파일-업로드] * 블록 클릭 → **파일 업로드** 버튼 * 또는 파일을 블록으로 드래그 2. 클립보드에서 붙여넣기 [#2-클립보드에서-붙여넣기] * 스크린샷 캡처 후 `Cmd/Ctrl + V` * 다른 앱에서 복사한 이미지 붙여넣기 3. URL로 삽입 [#3-url로-삽입] * **링크로 추가** 클릭 * 이미지 URL 입력 지원 형식 [#지원-형식] | 형식 | 확장자 | | -------- | --------------- | | **JPEG** | .jpg, .jpeg | | **PNG** | .png | | **GIF** | .gif (애니메이션 지원) | | **WebP** | .webp | | **SVG** | .svg | 이미지 설정 [#이미지-설정] | 설정 | 설명 | | ----------- | ----------------- | | **크기 조절** | 모서리를 드래그하여 크기 변경 | | **정렬** | 왼쪽 / 가운데 / 오른쪽 | | **캡션** | 이미지 아래에 설명 텍스트 추가 | | **Alt 텍스트** | 접근성을 위한 대체 텍스트 | | **링크** | 이미지 클릭 시 URL로 이동 | 크기 조절 [#크기-조절] * **마우스 드래그**: 모서리를 드래그하여 크기 변경 * **전체 너비**: 페이지 너비에 맞춤 * **원본 크기**: 업로드된 원본 크기로 표시 갤러리 레이아웃 [#갤러리-레이아웃] 여러 이미지를 나란히 배치하려면 **컬럼 블록**을 사용하세요. ``` ┌─────────────┬─────────────┬─────────────┐ │ 이미지1 │ 이미지2 │ 이미지3 │ └─────────────┴─────────────┴─────────────┘ ``` <Callout type="tip"> 이미지를 선택하고 캡션을 추가하면 문서의 전문성이 높아집니다. "그림 1: 시스템 아키텍처"처럼 캡션을 작성하세요. </Callout> *** YouTube 블록 [#youtube-블록] YouTube 동영상을 전용 블록으로 삽입합니다. 생성 방법 [#생성-방법-1] | 방법 | 설명 | | ------- | ---------- | | 슬래시 명령어 | `/youtube` | 지원 URL 형식 [#지원-url-형식] ``` https://youtube.com/watch?v=VIDEO_ID https://youtu.be/VIDEO_ID https://youtube.com/embed/VIDEO_ID ``` YouTube 설정 [#youtube-설정] | 설정 | 설명 | | -------------- | -------------------------------- | | **컨트롤 표시** | 재생 컨트롤 표시 (기본 활성화) | | **개인정보 보호 모드** | YouTube nocookie 도메인 사용 (기본 활성화) | <Callout type="info"> 동영상은 현재 YouTube 블록을 통해 삽입합니다. 별도의 동영상 업로드 블록(`/video`)이나 파일 블록(`/file`), 오디오 블록(`/audio`)은 아직 슬래시 명령어로 제공되지 않습니다. 데이터 타입으로는 VIDEO가 정의되어 있으나, 에디터 UI에서의 직접 생성은 YouTube 블록을 사용해 주세요. </Callout> *** 미디어 관리 팁 [#미디어-관리-팁] 1. 파일 크기 최적화 [#1-파일-크기-최적화] 큰 이미지는 업로드 전 압축하세요. 일반적으로: * **웹용 이미지**: 1-2MB 이하 권장 * **스크린샷**: PNG보다 JPEG가 작음 * **동영상**: YouTube/Vimeo 사용 권장 2. 접근성 고려 [#2-접근성-고려] * 이미지에 **Alt 텍스트** 추가 * 동영상에 **자막** 또는 **캡션** 제공 * 오디오에 **텍스트 변환** 첨부 3. 구조화된 미디어 사용 [#3-구조화된-미디어-사용] 관련 미디어는 컬럼 또는 갤러리로 그룹화하세요. 4. 네이밍 규칙 [#4-네이밍-규칙] 파일명을 의미 있게 지정하세요. ``` ❌ IMG_20240115.jpg ✅ 시스템-아키텍처-v2.jpg ❌ 녹음.mp3 ✅ 2024-01-15-주간회의-녹음.mp3 ``` *** 다음 단계 [#다음-단계] * [임베드 블록](/docs/blocks/embed-blocks) - 외부 콘텐츠 삽입 * [텍스트 블록](/docs/blocks/text-blocks) - 텍스트 콘텐츠 작성 * [데이터 블록](/docs/blocks/data-blocks) - 데이터 시각화 --- # 선택 처리 블록 (/docs/blocks/select-process-block) > 데이터를 선택하고 일괄 처리하는 인터랙티브 블록을 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; 활용 예시 [#활용-예시] | 시나리오 | 설명 | | ------------ | ------------------------- | | **POS 판매** | 상품 선택 → 수량 조정 → 결제 처리 | | **PT 세션 정산** | 회원 선택 → 세션 종류 선택 → 정산 완료 | | **재료 발주** | 재료 선택 → 수량 입력 → 발주 요청 | | **이벤트 참가자** | 참가자 선택 → 등록 유형 선택 → 등록 완료 | *** 생성 방법 [#생성-방법] | 방법 | 입력 | | ------- | ---------------------------- | | 슬래시 명령어 | `/select` 또는 `/선택` 또는 `/pos` | *** 화면 구성 [#화면-구성] 선택 처리 블록은 크게 3개 영역으로 구성됩니다. ``` ┌─────────────────────────────────────────────────────────────────┐ │ 판매 처리 [⚙️] │ ├─────────────────────────────────────────────────────────────────┤ │ [대상 선택] 고객: 김철수 ▼ │ ├───────────────────────────────────────┬─────────────────────────┤ │ │ │ │ [상품 선택 영역] │ [선택된 항목] │ │ │ │ │ ┌────────┐ ┌────────┐ ┌────────┐ │ 아메리카노 x1 ₩4,500 │ │ │ 아메리 │ │ 카페라 │ │ 카푸치 │ │ 카페라떼 x2 ₩10,000│ │ │ 카노 │ │ 떼 │ │ 노 │ │ │ │ │ ₩4,500│ │ ₩5,000│ │ ₩5,000│ │ ────────────────── │ │ └────────┘ └────────┘ └────────┘ │ 총계 ₩14,500 │ │ │ │ │ ┌────────┐ ┌────────┐ ┌────────┐ │ [결제하기] │ │ │ 녹차 │ │ 홍차 │ │ 주스 │ │ │ │ │ ₩4,000│ │ ₩4,000│ │ ₩5,500│ │ │ │ └────────┘ └────────┘ └────────┘ │ │ │ │ │ └───────────────────────────────────────┴─────────────────────────┘ ``` | 영역 | 설명 | | ---------- | ------------------------- | | **대상 선택** | 고객, 회원 등 처리 대상을 선택하는 드롭다운 | | **상품 선택** | 상품, 서비스 등 메인 항목을 선택하는 영역 | | **선택된 항목** | 장바구니처럼 선택한 항목과 총계 표시 | *** 설정하기 [#설정하기] 블록 우측 상단의 설정 버튼(⚙️)을 클릭하면 설정 패널이 열립니다. 1. 데이터 선택 [#1-데이터-선택] 선택할 데이터를 단계별로 설정합니다. 단계 추가 [#단계-추가] **+ 데이터 추가** 버튼을 클릭하여 새 선택 단계를 추가합니다. 역할 설정 [#역할-설정] 각 단계의 역할을 지정합니다. | 역할 | 설명 | 표시 방식 | | --------- | ------------------- | -------- | | **상품 선택** | 판매할 상품, 서비스 등 메인 항목 | 카드형/목록형 | | **대상 선택** | 고객, 회원 등 처리 대상 | 드롭다운 | | **추가 옵션** | 할인, 쿠폰 등 부가 설정 | 카드형/드롭다운 | 데이터 연결 [#데이터-연결] 선택 단계를 데이터모델과 연결합니다. 1. **데이터** 항목에서 데이터모델 선택 2. **제목 필드** - 항목 이름으로 표시할 필드 선택 3. **이미지 필드** - 썸네일 이미지 필드 선택 (선택사항) 4. **가격 필드** - 가격 표시 필드 선택 (선택사항) 표시 방식 [#표시-방식] | 방식 | 설명 | 적합한 상황 | | --------------- | ---------- | ------------ | | **카드형** (tile) | 카드 형태로 나열 | 이미지가 있는 상품 | | **목록형** (table) | 테이블 형태로 표시 | 상세 정보가 많은 항목 | <Callout type="tip"> 카드형에서는 열 수(2\~5열)와 카드 크기(작게/보통/크게)를 조정할 수 있습니다. </Callout> <Callout type="info"> 데이터 타입으로는 `tile`, `list`, `dropdown`, `search` 4가지 표시 스타일이 정의되어 있지만, 현재 설정 UI에서는 **카드형**(tile)과 **목록형**(table)을 선택할 수 있습니다. </Callout> *** 2. 합계 계산 [#2-합계-계산] 선택한 항목들의 합계를 자동 계산합니다. | 설정 | 설명 | | ----------- | -------------------- | | **계산할 데이터** | 합계를 계산할 단계 선택 | | **계산할 필드** | 합산할 필드 (예: 가격) | | **계산 방식** | 합계, 평균, 개수, 최소, 최대 | | **표시 단위** | 원(₩), 달러($), 유로(€) 등 | *** 3. 처리 실행 [#3-처리-실행] 선택 완료 후 실행할 동작을 설정합니다. 처리 방식 [#처리-방식] | 방식 | 식별자 | 사용 예시 | | ------------ | ------------- | -------------- | | **워크플로우 실행** | `workflow` | 결제 처리, 알림 발송 | | **API 호출** | `api` | PG사 연동, 외부 서비스 | | **데이터 생성** | `data_create` | 주문 내역 저장 | | **데이터 수정** | `data_update` | 재고 차감, 상태 변경 | | **커스텀** | `custom` | 사용자 정의 액션 | 버튼 설정 [#버튼-설정] | 설정 | 설명 | | ---------- | ------------------------------ | | **버튼 텍스트** | 실행 버튼에 표시할 텍스트 (예: 결제하기, 등록완료) | | **확인 메시지** | 실행 전 확인 팝업 메시지 (비워두면 바로 실행) | *** 사용하기 [#사용하기] 항목 선택 [#항목-선택] 1. **대상 선택**: 드롭다운에서 고객/회원 선택 (설정된 경우) 2. **상품 클릭**: 카드를 클릭하여 항목 추가 3. **반복 클릭**: 같은 항목을 다시 클릭하면 수량 증가 수량 조정 [#수량-조정] 선택된 항목 패널에서: * **+ / - 버튼**: 수량 1씩 증가/감소 * **휴지통 아이콘**: 항목 제거 처리 실행 [#처리-실행] 1. 원하는 항목 모두 선택 2. 총계 확인 3. 처리 버튼(예: 결제하기) 클릭 4. 확인 메시지가 설정된 경우 확인 후 실행 <Callout type="info"> 처리 완료 후 설정에 따라 선택이 자동으로 초기화되거나 특정 페이지로 이동할 수 있습니다. </Callout> *** 워크플로우 연동 [#워크플로우-연동] 선택 처리 블록은 워크플로우와 연동하여 복잡한 업무를 자동화할 수 있습니다. 전달되는 데이터 [#전달되는-데이터] 워크플로우로 전달되는 정보: | 데이터 | 설명 | | ------------------- | -------------------------- | | `selectedItems` | 선택된 항목 배열 (항목ID, 수량, 가격 등) | | `contextSelections` | 대상 선택 정보 (고객, 회원 등) | | `aggregatedTotal` | 계산된 총합계 | 활용 예시 [#활용-예시-1] ``` [선택 처리 블록에서 결제 실행] ↓ [워크플로우 시작] ↓ [주문 데이터 생성] → [재고 차감] → [영수증 이메일 발송] ↓ [PG사 결제 API 호출] ↓ [결제 완료 알림] ``` *** 팁과 주의사항 [#팁과-주의사항] <Callout type="tip"> **검색 기능**: 상품이 많을 경우 상단 검색창에서 이름이나 키워드로 검색할 수 있습니다. </Callout> <Callout type="warning"> **필수 선택**: 단계가 '필수'로 설정된 경우, 해당 단계에서 항목을 선택해야 처리 버튼이 활성화됩니다. </Callout> <Callout type="info"> **실시간 동기화**: 데이터모델의 변경 사항(가격 변경, 신규 상품 등)은 블록에 실시간으로 반영됩니다. </Callout> *** 다음 단계 [#다음-단계] * [워크플로우](/docs/workflows) - 자동화 로직 구성하기 * [데이터모델](/docs/datamodels) - 상품/고객 데이터 관리하기 * [데이터 블록](/docs/blocks/data-blocks) - 다른 데이터 블록 알아보기 --- # 텍스트 블록 (/docs/blocks/text-blocks) > 텍스트 콘텐츠를 위한 다양한 블록들을 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; 일반 텍스트 (Paragraph) [#일반-텍스트-paragraph] 기본 텍스트 블록입니다. 페이지에 처음 글을 쓰면 자동으로 생성됩니다. 생성 방법 [#생성-방법] * 그냥 타이핑 시작 * 단축키 `Cmd/Ctrl + Alt + 0` 텍스트 서식 [#텍스트-서식] 텍스트를 선택하면 서식 도구 모음이 나타납니다. | 서식 | 단축키 | 마크다운 | 결과 | | --------- | -------------- | ------------ | ------------- | | **굵게** | `Cmd/Ctrl + B` | `**텍스트**` | **굵은 텍스트** | | *기울임* | `Cmd/Ctrl + I` | `*텍스트*` | *기울임 텍스트* | | <u>밑줄</u> | `Cmd/Ctrl + U` | - | <u>밑줄 텍스트</u> | | ~~취소선~~ | - | `~~텍스트~~` | ~~취소선 텍스트~~ | | `인라인 코드` | `Cmd/Ctrl + E` | `` `코드` `` | `인라인 코드` | | [링크](/) | `Cmd/Ctrl + K` | `[텍스트](URL)` | [링크 텍스트](/) | 텍스트 색상 [#텍스트-색상] 텍스트를 선택하고 서식 도구에서 색상을 변경할 수 있습니다. * **텍스트 색상**: 글자 색상 변경 * **배경 색상**: 하이라이트 효과 *** 제목 (Heading) [#제목-heading] 문서 구조를 위한 세 단계의 제목을 제공합니다. 제목 1 (H1) [#제목-1-h1] 가장 큰 제목으로, 페이지의 주요 섹션을 나눌 때 사용합니다. | 생성 방법 | 입력 | | ------- | -------------------- | | 슬래시 명령어 | `/h1` 또는 `/제목` | | 마크다운 | `# ` (# 뒤에 공백) | | 단축키 | `Cmd/Ctrl + Alt + 1` | 제목 2 (H2) [#제목-2-h2] 중간 크기의 제목으로, 섹션 내 하위 주제를 나눌 때 사용합니다. | 생성 방법 | 입력 | | ------- | -------------------- | | 슬래시 명령어 | `/h2` 또는 `/제목` | | 마크다운 | `## ` | | 단축키 | `Cmd/Ctrl + Alt + 2` | 제목 3 (H3) [#제목-3-h3] 가장 작은 제목으로, 세부 항목을 구분할 때 사용합니다. | 생성 방법 | 입력 | | ------- | -------------------- | | 슬래시 명령어 | `/h3` 또는 `/제목` | | 마크다운 | `### ` | | 단축키 | `Cmd/Ctrl + Alt + 3` | 제목 타입 변환 [#제목-타입-변환] 제목 블록 앞에서 `/`를 입력하면 다른 레벨의 제목으로 쉽게 변환할 수 있습니다. <Callout type="tip"> 제목은 목차 생성과 내부 링크의 앵커로 사용됩니다. 의미 있는 제목을 사용하세요. </Callout> *** 불릿 리스트 (Bulleted List) [#불릿-리스트-bulleted-list] 순서가 없는 목록입니다. 생성 방법 [#생성-방법-1] | 방법 | 입력 | | ------- | -------------------- | | 슬래시 명령어 | `/bullet` | | 마크다운 | `- ` 또는 `* ` | | 단축키 | `Cmd/Ctrl + Alt + 5` | 예시 [#예시] * 첫 번째 항목 * 두 번째 항목 * 세 번째 항목 중첩 리스트 [#중첩-리스트] `Tab`을 눌러 들여쓰기하면 중첩 리스트가 됩니다. * 상위 항목 * 하위 항목 1 * 하위 항목 2 * 더 깊은 항목 * 하위 항목 3 * 다른 상위 항목 들여쓰기 [#들여쓰기] | 동작 | 단축키 | | ---- | ------------- | | 들여쓰기 | `Tab` | | 내어쓰기 | `Shift + Tab` | *** 번호 리스트 (Numbered List) [#번호-리스트-numbered-list] 순서가 있는 목록입니다. 자동으로 번호가 매겨집니다. 생성 방법 [#생성-방법-2] | 방법 | 입력 | | ------- | -------------------- | | 슬래시 명령어 | `/number` | | 마크다운 | `1. ` | | 단축키 | `Cmd/Ctrl + Alt + 6` | 예시 [#예시-1] 1. 첫 번째 단계 2. 두 번째 단계 3. 세 번째 단계 중첩 리스트 [#중첩-리스트-1] 1. 상위 항목 1. 하위 항목 1 2. 하위 항목 2 2. 다른 상위 항목 1. 하위 항목 번호 자동 갱신 [#번호-자동-갱신] 항목을 추가하거나 삭제하면 번호가 자동으로 재계산됩니다. *** 할 일 목록 (To-Do List) [#할-일-목록-to-do-list] 체크박스가 있는 목록입니다. 태스크 관리에 유용합니다. 생성 방법 [#생성-방법-3] | 방법 | 입력 | | ------- | -------------------- | | 슬래시 명령어 | `/todo` | | 마크다운 | `[] ` 또는 `[ ] ` | | 단축키 | `Cmd/Ctrl + Alt + 4` | 예시 [#예시-2] * [ ] 미완료 항목 * [x] 완료된 항목 * [ ] 또 다른 할 일 체크 토글 [#체크-토글] * 체크박스 클릭 * `Cmd/Ctrl + Enter` 완료 항목 스타일 [#완료-항목-스타일] 완료된 항목은 자동으로 취소선이 적용됩니다. *** 인용문 (Quote) [#인용문-quote] 인용 또는 강조하고 싶은 텍스트를 표시합니다. 생성 방법 [#생성-방법-4] | 방법 | 입력 | | | ------- | -------- | ------------- | | 슬래시 명령어 | `/quote` | | | 마크다운 | \` | \` (파이프 + 공백) | <Callout type="info"> 일반적인 마크다운에서는 `> `로 인용문을 생성하지만, 이 에디터에서는 `| ` (파이프 + 공백)을 사용합니다. `> `는 토글 블록 생성에 사용됩니다. </Callout> 예시 [#예시-3] > 좋은 코드는 그 자체로 최고의 문서다. > — 스티브 맥코넬 여러 줄 인용 [#여러-줄-인용] `Shift + Enter`로 인용문 내에서 줄바꿈할 수 있습니다. > 첫 번째 줄 > 두 번째 줄 > 세 번째 줄 *** 콜아웃 (Callout) [#콜아웃-callout] 중요한 정보를 강조하는 박스입니다. <Callout type="warn"> 콜아웃 블록은 현재 슬래시 명령어로 직접 생성할 수 없습니다. AI 에이전트 또는 API를 통해 생성되며, 데이터 형태로 지원됩니다. </Callout> 콜아웃 구성 [#콜아웃-구성] | 구성 요소 | 설명 | | ------- | ----------------------------------------- | | **아이콘** | 이모지, 외부 이미지, 파일 이미지 중 선택 | | **텍스트** | 서식이 적용된 콜아웃 본문 | | **배경색** | 기본, 회색, 갈색, 주황, 노랑, 초록, 파랑, 보라, 핑크, 빨강 배경 | 아이콘 변경 [#아이콘-변경] 콜아웃의 아이콘을 클릭하여 다른 이모지로 변경할 수 있습니다. *** 구분선 (Divider) [#구분선-divider] 콘텐츠 섹션을 시각적으로 구분합니다. 생성 방법 [#생성-방법-5] | 방법 | 입력 | | ------- | ---------- | | 슬래시 명령어 | `/divider` | | 마크다운 | `---` | 예시 [#예시-4] 위의 내용 *** 아래의 내용 *** 토글 (Toggle) [#토글-toggle] 접고 펼 수 있는 콘텐츠 영역입니다. 생성 방법 [#생성-방법-6] | 방법 | 입력 | | ------- | -------------------- | | 슬래시 명령어 | `/toggle` | | 마크다운 | `> ` | | 단축키 | `Cmd/Ctrl + Alt + 7` | 토글 열기/닫기 [#토글-열기닫기] * `Cmd/Ctrl + Enter` 또는 토글 아이콘 클릭 사용 예시 [#사용-예시] <details> <summary> 클릭하여 펼치기 </summary> 토글 안에는 다른 블록을 넣을 수 있습니다. * 리스트 * 이미지 * 코드 블록 </details> 적합한 용도 [#적합한-용도] * FAQ (자주 묻는 질문) * 상세 설명 (펼쳐서 보기) * 스포일러 * 긴 코드 예시 *** 마크다운 단축키 요약 [#마크다운-단축키-요약] | 입력 | 결과 | | | --------------- | ------ | --- | | `# ` | 제목 1 | | | `## ` | 제목 2 | | | `### ` | 제목 3 | | | `- ` 또는 `* ` | 불릿 리스트 | | | `1. ` | 번호 리스트 | | | `[] ` 또는 `[ ] ` | 할 일 목록 | | | \` | \` | 인용문 | | `> ` | 토글 | | | `---` | 구분선 | | | ` ``` ` | 코드 블록 | | | `**텍스트**` | 굵게 | | | `*텍스트*` | 기울임 | | | `~~텍스트~~` | 취소선 | | | `` `코드` `` | 인라인 코드 | | | `[텍스트](URL)` | 링크 | | 키보드 단축키 요약 [#키보드-단축키-요약] | 단축키 | 결과 | | ---------------------- | ------------------- | | `Cmd/Ctrl + Alt + 0` | 일반 텍스트 | | `Cmd/Ctrl + Alt + 1` | 제목 1 | | `Cmd/Ctrl + Alt + 2` | 제목 2 | | `Cmd/Ctrl + Alt + 3` | 제목 3 | | `Cmd/Ctrl + Alt + 4` | 할 일 목록 | | `Cmd/Ctrl + Alt + 5` | 불릿 리스트 | | `Cmd/Ctrl + Alt + 6` | 번호 리스트 | | `Cmd/Ctrl + Alt + 7` | 토글 | | `Cmd/Ctrl + Alt + 8` | 코드 블록 | | `Cmd/Ctrl + Enter` | 토글 열기/닫기 또는 체크박스 토글 | | `Cmd/Ctrl + Shift + T` | 현재 블록을 토글로 변환 | *** 다음 단계 [#다음-단계] * [미디어 블록](/docs/blocks/media-blocks) - 이미지, 동영상 삽입 * [데이터 블록](/docs/blocks/data-blocks) - 데이터모델, 차트 * [임베드 블록](/docs/blocks/embed-blocks) - 외부 콘텐츠 삽입 --- # 함께 일하기 (/docs/collaboration) > 팀과 함께 실시간으로 협업하세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; 협업 기능 개요 [#협업-기능-개요] | 기능 | 설명 | | ---------- | -------------------- | | **실시간 협업** | 여러 팀원이 동시에 같은 문서를 편집 | | **권한 관리** | 역할별, 페이지별 세밀한 접근 제어 | | **공유** | 외부 사용자에게 특정 콘텐츠만 공유 | | **활동 추적** | 누가 무엇을 변경했는지 기록 | *** 실시간 협업 [#실시간-협업] 동시 편집 [#동시-편집] 여러 사람이 같은 페이지나 데이터모델을 **동시에** 편집할 수 있습니다. 모든 변경 사항이 **실시간으로 동기화**되어 충돌 없이 작업할 수 있습니다. ``` ┌─────────────────────────────────────────────────────────┐ │ 📄 프로젝트 계획서 🔵 김철수 편집중│ ├─────────────────────────────────────────────────────────┤ │ │ │ 여기서 🔵김철수 가 타이핑 중... │ │ │ │ 1. 프로젝트 목표 │ │ - 매출 20% 증가 │ │ - 고객 만족도 향상 🟢이영희 │ │ │ └─────────────────────────────────────────────────────────┘ ``` *** 권한 시스템 [#권한-시스템] 역할 구조 [#역할-구조] 슈츠는 **4단계 역할**로 권한을 관리합니다. ``` 소유자 (Owner) ↓ 관리자 (Admin) ↓ 멤버 (Member) ↓ 게스트 (Guest) ← 외부 사용자 ``` 역할별 권한 요약 [#역할별-권한-요약] | 권한 | 소유자 | 관리자 | 멤버 | 게스트 | | --------- | :-: | :-: | :-: | :--------: | | 콘텐츠 보기 | ✅ | ✅ | ✅ | ✅ (제한) | | 콘텐츠 편집 | ✅ | ✅ | ✅ | △ (권한에 따라) | | 멤버 관리 | ✅ | ✅ | ❌ | ❌ | | 설정 변경 | ✅ | ✅ | ❌ | ❌ | | 결제 관리 | ✅ | ❌ | ❌ | ❌ | | 워크스페이스 삭제 | ✅ | ❌ | ❌ | ❌ | 페이지별 권한 [#페이지별-권한] 개별 페이지에 **별도 권한**을 설정하여 특정 사용자만 접근하게 할 수 있습니다. | 설정 | 설명 | | ------------- | ------------- | | **워크스페이스 기본** | 워크스페이스 역할에 따름 | | **제한됨** | 특정 멤버만 접근 가능 | | **비공개** | 본인만 접근 가능 | *** 공유 방식 [#공유-방식] 내부 공유 [#내부-공유] 워크스페이스 **멤버에게** 특정 페이지를 공유합니다. 1. 페이지 우측 상단 **공유** 버튼 클릭 2. 멤버 검색 및 선택 3. 권한 수준 선택 (보기/편집) 4. **공유** 클릭 게스트 초대 [#게스트-초대] 워크스페이스 멤버가 아닌 **외부 사용자**를 특정 페이지에 초대합니다. | 구분 | 멤버 | 게스트 | | --------- | --------- | --------- | | **접근 범위** | 전체 워크스페이스 | 초대받은 페이지만 | | **사이드바** | 전체 표시 | 초대받은 페이지만 | | **요금** | 플랜에 따라 | 별도 과금 없음 | 공개 링크 [#공개-링크] **누구나 접근**할 수 있는 공개 링크를 생성합니다. <Callout type="warn"> 공개 링크는 URL을 아는 누구나 접근할 수 있습니다. **민감한 정보가 포함된 페이지**에는 사용하지 마세요. </Callout> *** 활동 추적 [#활동-추적] 버전 히스토리 [#버전-히스토리] 페이지와 데이터모델의 **변경 이력**을 추적합니다. * 언제 누가 변경했는지 기록 * 이전 버전으로 되돌리기 가능 * 변경 사항 비교 활동 피드 [#활동-피드] 워크스페이스 전체의 **활동 로그**를 확인합니다. | 이벤트 | 예시 | | ------ | ------------------------------------------------------- | | 페이지 생성 | "김철수님이 '프로젝트 계획서' 생성" | | 페이지 편집 | "이영희님이 '프로젝트 계획서' 편집" | | 데이터 추가 | "박지민님이 '고객' 데이터모델에 3개 행 추가" | | 멤버 초대 | "김철수님이 [team@example.com](mailto:team@example.com)을 초대" | *** 협업 모범 사례 [#협업-모범-사례] 1. 역할에 맞는 권한 부여 [#1-역할에-맞는-권한-부여] 필요한 최소 권한만 부여하세요. * 외부 검토자 → 게스트 (VIEW 권한) * 팀원 → 멤버 * 팀 리더 → 관리자 2. 페이지 구조화 [#2-페이지-구조화] 협업이 원활하도록 페이지를 구조화하세요. * 팀별/프로젝트별 상위 페이지 * 명확한 페이지 이름과 아이콘 * 중요 페이지 즐겨찾기 3. 댓글 활용 [#3-댓글-활용] 직접 편집하기 전에 **댓글**로 의견을 나누세요. * 텍스트 선택 → 댓글 추가 * `@멘션`으로 담당자 지정 * 완료된 댓글 해결 처리 4. 동시 편집 에티켓 [#4-동시-편집-에티켓] 같은 영역을 동시에 편집하면 혼란이 생길 수 있습니다. * 큰 작업 전 팀원에게 알리기 * 담당 영역 나누기 * 충돌 시 소통하기 *** 이 섹션에서 다루는 내용 [#이-섹션에서-다루는-내용] <Cards> <Card title="실시간 협업" description="동시 편집과 실시간 동기화" href="/docs/collaboration/real-time" /> <Card title="권한 관리" description="역할별 권한과 페이지별 설정" href="/docs/collaboration/permissions" /> <Card title="공유" description="외부 공유와 게스트 초대" href="/docs/collaboration/sharing" /> </Cards> --- # 권한 관리 (/docs/collaboration/permissions) > 세밀한 접근 권한을 설정하세요. import { Callout } from 'fumadocs-ui/components/callout'; 권한 구조 [#권한-구조] 슈츠의 권한은 두 가지 레벨로 구성됩니다. ``` 워크스페이스 역할 (기본: OWNER, ADMIN, MEMBER, GUEST) ↓ 리소스 권한 (개별 리소스별 설정 가능: FULL, DATA, VIEW, NONE) ``` 리소스 권한은 페이지, 데이터모델, 워크플로우 등 개별 리소스에 대해 사용자 또는 그룹 단위로 설정할 수 있습니다. *** 워크스페이스 역할 [#워크스페이스-역할] 소유자 (Owner) [#소유자-owner] 워크스페이스의 **최고 권한**을 가진 사용자입니다. | 권한 | 설명 | | ----------- | ------------------- | | ✅ 모든 권한 보유 | 콘텐츠, 설정, 멤버 모든 것 관리 | | ✅ 워크스페이스 삭제 | 워크스페이스 영구 삭제 가능 | | ✅ 소유권 이전 | 다른 관리자에게 소유권 넘기기 | | ✅ 결제/플랜 관리 | 구독, 결제 수단 관리 | <Callout type="info"> 워크스페이스당 **한 명**의 소유자만 있습니다. 소유자를 변경하려면 소유권을 이전해야 합니다. </Callout> 소유권 이전 [#소유권-이전] 1. 설정 → **멤버** 탭 이동 2. 이전할 관리자 선택 3. **소유권 이전** 클릭 4. 비밀번호로 확인 *** 관리자 (Admin) [#관리자-admin] 워크스페이스 **운영을 담당**하는 역할입니다. | 권한 | 설명 | | ------------- | ----------------- | | ✅ 모든 콘텐츠 편집 | 페이지, 데이터모델, 워크플로우 | | ✅ 멤버 관리 | 초대, 역할 변경, 제거 | | ✅ 그룹 관리 | 그룹 생성, 멤버 관리 | | ✅ 워크스페이스 설정 | 기본 설정, 연동 관리 | | ✅ API 키 관리 | 개발자 설정 접근 | | ❌ OWNER 역할 할당 | 소유자만 가능 | | ❌ 결제 관리 | 소유자만 가능 | | ❌ 워크스페이스 삭제 | 소유자만 가능 | *** 멤버 (Member) [#멤버-member] 일반 **팀원** 역할입니다. | 권한 | 설명 | | ----------- | ---------------- | | ✅ 콘텐츠 생성/편집 | 페이지, 데이터 생성 및 수정 | | ✅ 본인 콘텐츠 삭제 | 자신이 만든 콘텐츠만 | | ✅ 워크플로우 관리 | 워크플로우 생성 및 실행 | | ❌ 멤버 관리 | 관리자만 가능 | | ❌ 설정 변경 | 관리자만 가능 | | ❌ 전체 콘텐츠 열람 | 권한 부여된 콘텐츠만 접근 | *** 게스트 (Guest) [#게스트-guest] **외부 사용자**를 위한 제한된 접근입니다. | 특징 | 설명 | | --------- | ----------------- | | **접근 범위** | 초대받은 특정 페이지만 | | **사이드바** | 초대받은 페이지만 표시 | | **권한 선택** | 보기 전용 또는 편집 가능 | | **요금** | 별도 과금 없음 (플랜별 제한) | *** 역할별 권한 비교표 [#역할별-권한-비교표] | 기능 | 소유자 | 관리자 | 멤버 | 게스트 | | ------------- | :-: | :-: | :-: | :----: | | **콘텐츠 보기** | ✅ | ✅ | ✅ | ✅ (제한) | | **페이지 생성** | ✅ | ✅ | ✅ | ❌ | | **페이지 편집** | ✅ | ✅ | ✅ | △ | | **페이지 삭제** | ✅ | ✅ | △ | ❌ | | **데이터 생성** | ✅ | ✅ | ✅ | △ | | **데이터 편집** | ✅ | ✅ | ✅ | △ | | **데이터 삭제** | ✅ | ✅ | △ | ❌ | | **워크플로우 생성** | ✅ | ✅ | ✅ | ❌ | | **멤버 초대** | ✅ | ✅ | ❌ | ❌ | | **역할 변경** | ✅ | ✅ | ❌ | ❌ | | **그룹 관리** | ✅ | ✅ | ❌ | ❌ | | **설정 변경** | ✅ | ✅ | ❌ | ❌ | | **결제 관리** | ✅ | ❌ | ❌ | ❌ | | **워크스페이스 삭제** | ✅ | ❌ | ❌ | ❌ | △ = 조건부 (본인 생성 콘텐츠만 또는 리소스 권한에 따라) *** 리소스 권한 [#리소스-권한] 개별 리소스(페이지, 데이터모델, 워크플로우 등)에 **별도 권한**을 사용자 또는 그룹 단위로 설정할 수 있습니다. 권한 수준 [#권한-수준] | 수준 | 설명 | | -------- | -------------------- | | **FULL** | 전체 권한 (편집 + 공유 + 삭제) | | **DATA** | 데이터 편집 권한 (읽기 + 쓰기) | | **VIEW** | 보기 전용 (읽기만 가능) | | **NONE** | 접근 불가 | 지원 리소스 타입 [#지원-리소스-타입] | 리소스 타입 | 설명 | | -------------------- | ----- | | **PAGE** | 페이지 | | **BLOCK** | 블록 | | **DATAMODEL** | 데이터모델 | | **WORKFLOW** | 워크플로우 | | **STAT\_DEFINITION** | 통계 정의 | | **CREDENTIAL** | 인증 정보 | 권한 부여 대상 [#권한-부여-대상] 권한은 **사용자** 또는 **그룹** 단위로 부여할 수 있습니다. | 대상 | 설명 | | --------- | ------------------------ | | **USER** | 개별 사용자에게 권한 부여 | | **GROUP** | 그룹에 권한 부여 (그룹 멤버 전원에 적용) | 리소스 권한 설정 [#리소스-권한-설정] 1. 리소스의 **공유** 버튼 클릭 2. 사용자 또는 그룹 검색 및 선택 3. 권한 수준 선택 (FULL/DATA/VIEW) 4. 부여 완료 하위 페이지 권한 상속 [#하위-페이지-권한-상속] 하위 페이지는 기본적으로 **상위 페이지의 권한을 상속**합니다. `inheritFromParent` 설정으로 상속을 끊고 별도 권한을 부여할 수 있습니다. ``` 📁 프로젝트 (FULL: 팀 A 그룹) ├── 📄 기획서 (상속: 팀 A FULL) ├── 📄 일정표 (상속: 팀 A FULL) └── 📄 예산 (별도 설정: 관리자만 FULL) ``` *** 권한 관리 모범 사례 [#권한-관리-모범-사례] 1. 최소 권한 원칙 [#1-최소-권한-원칙] 필요한 **최소한의 권한**만 부여하세요. ``` ❌ 모든 팀원을 관리자로 ✅ 실제 관리 업무가 있는 사람만 관리자 ``` 2. 역할 기반 그룹화 [#2-역할-기반-그룹화] 팀이나 프로젝트별로 권한 그룹을 만들어 관리하세요. ``` 마케팅팀 → 마케팅 페이지 편집 권한 개발팀 → 기술 문서 편집 권한 경영진 → 전체 읽기 권한 ``` 3. 정기적 권한 검토 [#3-정기적-권한-검토] 분기별로 멤버 권한을 검토하세요. * 퇴사자 제거 * 역할 변경 반영 * 불필요한 권한 회수 4. 민감한 데이터 분리 [#4-민감한-데이터-분리] 민감한 정보가 포함된 페이지/데이터모델은 별도로 관리하세요. ``` 📁 일반 문서 (전체 공개) 📁 인사 문서 (HR 팀만) 📁 재무 문서 (경영진만) ``` *** 다음 단계 [#다음-단계] * [공유](/docs/collaboration/sharing) - 외부 공유와 게스트 초대 * [실시간 협업](/docs/collaboration/real-time) - 동시 편집과 실시간 동기화 --- # 실시간 협업 (/docs/collaboration/real-time) > 팀원들과 동시에 작업하세요. import { Callout } from 'fumadocs-ui/components/callout'; 실시간 동기화 원리 [#실시간-동기화-원리] 슈츠는 **CRDT(Conflict-free Replicated Data Type)** 기반의 실시간 동기화 기술을 사용합니다. 장점 [#장점] | 특징 | 설명 | | ----------- | ------------------------ | | **충돌 없음** | 여러 사람이 동시에 편집해도 자동으로 병합 | | **즉시 반영** | 변경 사항이 밀리초 단위로 동기화 | | **오프라인 지원** | 오프라인에서 작업 후 재연결 시 자동 동기화 | | **버전 보존** | 모든 변경 이력이 기록되어 되돌리기 가능 | *** 동시 편집 [#동시-편집] 텍스트 편집 [#텍스트-편집] 여러 사용자가 **같은 문서를 동시에 편집**해도 충돌 없이 모든 변경 사항이 병합됩니다. 같은 줄 편집 [#같은-줄-편집] 같은 줄을 동시에 편집하는 경우: * 각자의 변경 사항이 **순서대로 적용**됩니다 * 충돌이 발생하면 **마지막 변경이 우선** 적용됩니다 * 필요시 **버전 히스토리**에서 복원 가능 다른 줄 편집 [#다른-줄-편집] 다른 줄을 편집하는 경우: * 완전히 **독립적으로 동작**합니다 * 서로의 작업에 영향 없음 데이터모델 편집 [#데이터모델-편집] 데이터모델의 행과 속성도 동시에 편집할 수 있습니다. | 시나리오 | 동작 | | -------------- | --------- | | **다른 행 편집** | 완전히 독립적 | | **같은 행, 다른 셀** | 각 셀 독립적 | | **같은 셀** | 마지막 변경 적용 | <Callout type="tip"> 같은 셀을 동시에 편집해야 할 때는 팀원과 소통하세요. 작은 조율로 작업 충돌을 방지할 수 있습니다. </Callout> *** 동기화 상태 [#동기화-상태] 저장 상태 표시 [#저장-상태-표시] 페이지 상단에 현재 **동기화 상태**가 표시됩니다. | 상태 | 표시 | 의미 | | -------- | ---------- | ----------------- | | **저장됨** | ☁️ 저장됨 | 모든 변경 사항이 서버에 저장됨 | | **저장 중** | 🔄 저장 중... | 변경 사항을 저장하는 중 | | **오프라인** | ⚠️ 오프라인 | 네트워크 연결 끊김 | 오프라인 모드 [#오프라인-모드] 네트워크 연결이 끊어져도 계속 작업할 수 있습니다. 1. **오프라인에서 작업** 계속 가능 2. **재연결 시 자동 동기화** 3. **충돌 발생 시 알림**으로 확인 <Callout type="info"> 오프라인 작업 내용은 브라우저에 임시 저장됩니다. 브라우저를 닫기 전에 네트워크에 재연결하는 것이 안전합니다. </Callout> *** 버전 히스토리 [#버전-히스토리] 변경 이력 보기 [#변경-이력-보기] 모든 변경 사항이 **자동으로 기록**됩니다. 1. 페이지 메뉴에서 **버전 히스토리** 클릭 2. 시간대별 변경 이력 확인 3. 특정 버전 선택하여 미리보기 이전 버전 복원 [#이전-버전-복원] 이전 버전으로 되돌릴 수 있습니다. 1. 버전 히스토리에서 복원할 버전 선택 2. **이 버전으로 복원** 클릭 3. 확인 후 복원 완료 <Callout type="warn"> 버전 복원은 현재 내용을 덮어씁니다. 현재 내용도 히스토리에 저장되므로 나중에 다시 복원할 수 있습니다. </Callout> *** 협업 팁 [#협업-팁] 1. 작업 영역 분리 [#1-작업-영역-분리] 큰 문서를 편집할 때는 작업 영역을 미리 나누세요. ``` 김철수: 1. 프로젝트 개요 담당 이영희: 2. 일정 계획 담당 박지민: 3. 예산 계획 담당 ``` 2. 변경 전 알리기 [#2-변경-전-알리기] 큰 변경(섹션 삭제, 구조 변경 등)을 하기 전에 팀원에게 알리세요. 3. 댓글 활용 [#3-댓글-활용] 직접 편집하기 전에 댓글로 의견을 나누세요. *** 문제 해결 [#문제-해결] 변경 사항이 반영되지 않음 [#변경-사항이-반영되지-않음] 1. 페이지 새로고침 (`Cmd/Ctrl + R`) 2. 네트워크 연결 확인 3. 다른 브라우저에서 확인 동기화 충돌 [#동기화-충돌] 1. 충돌 알림이 표시되면 내용 확인 2. 유지할 버전 선택 3. 필요시 버전 히스토리에서 복원 *** 다음 단계 [#다음-단계] * [권한 관리](/docs/collaboration/permissions) - 역할과 권한 설정 * [공유](/docs/collaboration/sharing) - 외부 공유와 게스트 초대 --- # 공유 (/docs/collaboration/sharing) > 콘텐츠를 안전하게 공유하세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Steps, Step } from 'fumadocs-ui/components/steps'; 공유 방식 비교 [#공유-방식-비교] | 방식 | 대상 | 특징 | | ---------- | --------- | ------------------- | | **내부 공유** | 워크스페이스 멤버 | 역할에 따른 권한, 전체 기능 사용 | | **게스트 초대** | 외부 사용자 | 이메일로 초대, 특정 페이지만 접근 | | **공개 링크** | 누구나 | URL만 있으면 접근, 읽기 전용 | *** 내부 공유 [#내부-공유] 워크스페이스 멤버에게 특정 페이지를 공유합니다. <Steps> <Step> 공유 버튼 클릭 [#공유-버튼-클릭] 페이지 우측 상단의 **공유** 버튼을 클릭합니다. </Step> <Step> 멤버 검색 [#멤버-검색] 공유할 멤버의 이름이나 이메일을 검색합니다. </Step> <Step> 권한 선택 [#권한-선택] 멤버별로 권한을 선택합니다. | 권한 | 설명 | | --------- | ------------------ | | **전체 권한** | 편집 및 다른 사람에게 공유 가능 | | **편집 가능** | 내용 편집 가능 | | **보기 가능** | 읽기만 가능 | </Step> <Step> 공유 완료 [#공유-완료] **공유** 버튼을 클릭하여 완료합니다. 멤버에게 알림이 전송됩니다. </Step> </Steps> 그룹에게 공유 [#그룹에게-공유] 여러 멤버를 **그룹으로 묶어** 일괄 공유할 수 있습니다. 1. 설정 → **그룹** 탭에서 그룹 생성 2. 그룹에 멤버 추가 3. 공유 시 그룹 선택 ``` 마케팅팀 그룹: 김마케팅, 이콘텐츠, 박디자인 → 마케팅팀 그룹에 공유 = 3명 모두에게 공유 ``` *** 게스트 초대 [#게스트-초대] 워크스페이스 멤버가 아닌 **외부 사용자**를 특정 페이지에 초대합니다. 게스트와 멤버의 차이 [#게스트와-멤버의-차이] | 구분 | 멤버 | 게스트 | | --------- | --------- | ----------- | | **접근 범위** | 전체 워크스페이스 | 초대받은 페이지만 | | **사이드바** | 전체 표시 | 초대받은 페이지만 | | **비용** | 플랜 요금에 포함 | 무료 (플랜별 제한) | | **기능** | 전체 기능 | 제한된 기능 | 게스트 초대 방법 [#게스트-초대-방법] 게스트 초대 시 **리소스 스코프 초대**를 사용하여 특정 리소스에 대한 권한까지 함께 설정할 수 있습니다. <Steps> <Step> 공유 버튼 클릭 [#공유-버튼-클릭-1] 공유할 페이지에서 **공유** 버튼을 클릭합니다. </Step> <Step> 게스트 초대 탭 선택 [#게스트-초대-탭-선택] **게스트 초대** 탭을 선택합니다. </Step> <Step> 이메일 입력 [#이메일-입력] 초대할 사람의 이메일 주소를 입력합니다. </Step> <Step> 권한 선택 [#권한-선택-1] 리소스 스코프 초대 시 다음 권한 수준을 선택합니다: | 권한 수준 | 설명 | | -------- | --------------- | | **FULL** | 전체 권한 (편집 + 공유) | | **DATA** | 데이터 편집 권한 | | **VIEW** | 보기 전용 | </Step> <Step> 초대 발송 [#초대-발송] **초대 보내기**를 클릭합니다. 게스트는 이메일로 초대 링크를 받습니다. 초대 시 지정한 리소스 권한이 자동으로 적용됩니다. </Step> </Steps> 게스트 관리 [#게스트-관리] 설정 → **멤버** 탭에서 게스트를 관리할 수 있습니다. | 작업 | 방법 | | ------------- | --------------- | | **권한 변경** | 게스트 선택 → 권한 변경 | | **추가 페이지 공유** | 게스트 선택 → 페이지 추가 | | **접근 취소** | 게스트 선택 → 제거 | 게스트 제한 [#게스트-제한] | 플랜 | 게스트 수 | | -------------- | ----- | | **Free** | 3명 | | **Pro** | 10명 | | **Business** | 무제한 | | **Enterprise** | 무제한 | *** 공개 링크 [#공개-링크] **누구나 접근**할 수 있는 링크를 생성합니다. 로그인 없이도 페이지를 볼 수 있습니다. <Callout type="warn"> **주의**: 공개 링크는 URL을 아는 누구나 접근할 수 있습니다. 민감한 정보가 포함된 페이지에는 사용하지 마세요. </Callout> 공개 링크 생성 [#공개-링크-생성] <Steps> <Step> 공유 버튼 클릭 [#공유-버튼-클릭-2] 페이지 우측 상단의 **공유** 버튼을 클릭합니다. </Step> <Step> 공개 링크 활성화 [#공개-링크-활성화] **웹에 공개** 토글을 켭니다. </Step> <Step> 링크 복사 [#링크-복사] 생성된 링크를 복사하여 공유합니다. ``` https://app.suits.work/share/abc123xyz ``` </Step> </Steps> 공개 링크 옵션 [#공개-링크-옵션] | 옵션 | 설명 | | ------------ | ------------------ | | **검색 엔진 허용** | 구글 등 검색 엔진에 노출 허용 | | **댓글 허용** | 방문자가 댓글 작성 가능 | | **편집 허용** | 방문자가 내용 편집 가능 (위험) | 공개 링크 비활성화 [#공개-링크-비활성화] 1. 공유 설정에서 **웹에 공개** 토글 끄기 2. 기존 링크는 즉시 무효화됨 *** 공유 관리 [#공유-관리] 공유 현황 확인 [#공유-현황-확인] 공유 설정 화면에서 현재 페이지에 **접근 가능한 모든 사용자**를 확인할 수 있습니다. ``` ┌─────────────────────────────────────────────────────────┐ │ 📄 프로젝트 계획서 - 공유 설정 │ ├─────────────────────────────────────────────────────────┤ │ │ │ 👤 김철수 (소유자) 전체 권한 │ │ 👤 이영희 편집 가능 │ │ 👤 박지민 보기 가능 │ │ 📧 guest@example.com (게스트) 보기 가능 │ │ │ │ 🔗 공개 링크: 활성화됨 │ │ │ └─────────────────────────────────────────────────────────┘ ``` 권한 변경 [#권한-변경] 1. 공유 설정에서 사용자 선택 2. 권한 드롭다운 클릭 3. 새 권한 선택 접근 취소 [#접근-취소] 1. 공유 설정에서 사용자 선택 2. **접근 취소** 또는 **X** 클릭 3. 즉시 접근 권한 제거됨 *** 하위 페이지 공유 [#하위-페이지-공유] 권한 상속 [#권한-상속] 하위 페이지는 기본적으로 **상위 페이지의 권한을 상속**합니다. ``` 📁 프로젝트 (팀 A에 공유) ├── 📄 기획서 (상속: 팀 A) ├── 📄 디자인 (상속: 팀 A) └── 📄 재무 (별도 설정: 관리자만) ``` 별도 권한 설정 [#별도-권한-설정] 하위 페이지에 **별도 권한**을 설정하면 상속이 끊어집니다. <Callout type="info"> 상위 페이지에 접근 권한이 없어도, 직접 권한이 부여된 하위 페이지에는 접근할 수 있습니다. </Callout> *** 데이터모델 공유 [#데이터모델-공유] 뷰 기반 공유 [#뷰-기반-공유] 데이터모델을 공유할 때 특정 **뷰**만 공유할 수 있습니다. | 뷰 | 접근 권한 | | ------------ | ----- | | 전체 데이터 뷰 | 관리자만 | | 팀 A 뷰 (필터됨) | 팀 A | | 공개 뷰 (일부 열만) | 모든 멤버 | 행 수준 보안 [#행-수준-보안] 조건에 따라 사용자가 볼 수 있는 행을 제한합니다. ``` 조건: 담당자 = 현재 사용자 → 자신이 담당인 행만 볼 수 있음 ``` *** 공유 모범 사례 [#공유-모범-사례] 1. 최소 권한 원칙 [#1-최소-권한-원칙] 필요한 최소한의 권한만 부여하세요. ``` ❌ 모든 사람에게 편집 권한 ✅ 대부분 보기 권한, 필요한 사람만 편집 권한 ``` 2. 공개 링크 주의 [#2-공개-링크-주의] 공개 링크는 신중하게 사용하세요. | 적합 | 부적합 | | ------ | -------- | | 마케팅 자료 | 내부 전략 문서 | | 제품 문서 | 고객 정보 | | 공개 가이드 | 재무 데이터 | 3. 정기적 검토 [#3-정기적-검토] 분기별로 공유 현황을 검토하세요. * 불필요한 게스트 제거 * 공개 링크 비활성화 * 권한 수준 재검토 4. 알림 설정 [#4-알림-설정] 중요한 페이지의 변경 사항을 알림으로 받으세요. *** 다음 단계 [#다음-단계] * [권한 관리](/docs/collaboration/permissions) - 역할과 권한 상세 설정 * [실시간 협업](/docs/collaboration/real-time) - 동시 편집과 실시간 동기화 --- # 수식 (/docs/datamodels/formulas) > 수식을 사용하여 자동 계산을 설정하세요. import { Callout } from 'fumadocs-ui/components/callout'; 수식 기본 사용법 [#수식-기본-사용법] 수식 속성 추가 [#수식-속성-추가] 1. **+ 속성 추가** → **수식(Formula)** 선택 2. 수식 편집기에서 수식 입력 3. 저장 기본 구문 [#기본-구문] ```javascript prop("속성이름") ``` `prop()` 함수로 다른 속성의 값을 가져와 계산합니다. ```javascript // 총 금액 계산 prop("단가") * prop("수량") ``` *** 속성 참조 [#속성-참조] prop() [#prop] 다른 속성의 값을 가져옵니다. ```javascript prop("속성이름") ``` | 속성 타입 | 반환 값 | | ----- | ---------- | | 텍스트 | 문자열 | | 숫자/통화 | 숫자 | | 날짜 | 날짜 객체 | | 체크박스 | true/false | | 선택 | 선택된 값 문자열 | | 다중 선택 | 값 배열 | *** 연산자 [#연산자] 산술 연산자 [#산술-연산자] 기본적인 수학 계산을 수행합니다. | 연산자 | 설명 | 예시 | | --- | --- | ----------------------- | | `+` | 덧셈 | `prop("A") + prop("B")` | | `-` | 뺄셈 | `prop("A") - prop("B")` | | `*` | 곱셈 | `prop("A") * prop("B")` | | `/` | 나눗셈 | `prop("A") / prop("B")` | | `%` | 나머지 | `prop("A") % prop("B")` | ```javascript // 총 금액 prop("단가") * prop("수량") // 할인 적용 가격 prop("정가") * (1 - prop("할인율") / 100) // 세금 포함 가격 prop("금액") * 1.1 ``` *** 비교 연산자 [#비교-연산자] 두 값을 비교하여 true/false를 반환합니다. | 연산자 | 설명 | 예시 | | ---- | ------ | -------------------- | | `==` | 같음 | `prop("상태") == "완료"` | | `!=` | 다름 | `prop("상태") != "취소"` | | `>` | 크다 | `prop("점수") > 80` | | `>=` | 크거나 같다 | `prop("점수") >= 80` | | `<` | 작다 | `prop("재고") < 10` | | `<=` | 작거나 같다 | `prop("재고") <= 10` | *** 논리 연산자 [#논리-연산자] 조건을 조합합니다. | 연산자 | 설명 | 예시 | | ----- | --- | ------------------------- | | `and` | AND | `prop("A") and prop("B")` | | `or` | OR | `prop("A") or prop("B")` | | `not` | NOT | `not prop("완료")` | ```javascript // 두 조건 모두 만족 prop("상태") == "진행중" and prop("우선순위") == "높음" // 둘 중 하나 만족 prop("상태") == "완료" or prop("상태") == "취소" // 조건 부정 not prop("취소됨") ``` *** 조건문 [#조건문] if() [#if] 조건에 따라 다른 값을 반환합니다. ```javascript if(조건, 참일때값, 거짓일때값) ``` ```javascript // 상태 이모지 if(prop("완료"), "✅", "⏳") // 재고 상태 if(prop("재고") <= 10, "⚠️ 저재고", "정상") // 등급 계산 if(prop("점수") >= 90, "A", "B 이하") ``` 중첩 조건 [#중첩-조건] 여러 조건을 순차적으로 검사합니다. ```javascript if(prop("점수") >= 90, "A", if(prop("점수") >= 80, "B", if(prop("점수") >= 70, "C", if(prop("점수") >= 60, "D", "F")))) ``` <Callout type="tip"> 중첩이 깊어지면 가독성이 떨어집니다. 간단한 조건을 먼저 검사하세요. </Callout> *** 텍스트 함수 [#텍스트-함수] concat() [#concat] 텍스트를 연결합니다. ```javascript concat(텍스트1, 텍스트2, ...) ``` ```javascript // 이름 결합 concat(prop("성"), " ", prop("이름")) // 결과: "김 철수" // 주소 조합 concat(prop("시"), " ", prop("구"), " ", prop("동")) // 결과: "서울시 강남구 역삼동" // 라벨 생성 concat("[", prop("카테고리"), "] ", prop("제목")) // 결과: "[버그] 로그인 오류 수정" ``` *** length() [#length] 텍스트의 길이를 반환합니다. ```javascript length(텍스트) ``` ```javascript // 제목 길이 length(prop("제목")) // 글자 수 제한 확인 if(length(prop("설명")) > 100, "⚠️ 너무 김", "✅ 적정") ``` *** contains() [#contains] 텍스트에 특정 문자열이 포함되어 있는지 확인합니다. ```javascript contains(텍스트, 검색어) ``` ```javascript // 이메일 도메인 확인 if(contains(prop("이메일"), "@gmail.com"), "Gmail", "기타") // 키워드 포함 여부 if(contains(prop("제목"), "긴급"), "🚨 긴급", "일반") ``` *** 숫자 함수 [#숫자-함수] round(), floor(), ceil() [#round-floor-ceil] 숫자를 반올림/내림/올림합니다. ```javascript // 반올림 round(prop("평균점수")) // 85.4 → 85 // 내림 floor(prop("평균점수")) // 85.9 → 85 // 올림 ceil(prop("평균점수")) // 85.1 → 86 ``` *** abs() [#abs] 절대값을 반환합니다. ```javascript abs(prop("차이")) // -10 → 10 ``` *** min(), max() [#min-max] 최소값/최대값을 반환합니다. ```javascript // 최소값 min(prop("예산"), prop("실제비용")) // 최대값 max(prop("시작일"), prop("종료일")) ``` *** 날짜 함수 [#날짜-함수] now() [#now] 현재 날짜와 시간을 반환합니다. ```javascript now() // 현재 날짜/시간 ``` *** dateBetween() [#datebetween] 두 날짜 사이의 차이를 계산합니다. ```javascript dateBetween(날짜1, 날짜2, 단위) ``` | 단위 | 설명 | | ----------- | ----- | | `"years"` | 연 단위 | | `"months"` | 월 단위 | | `"days"` | 일 단위 | | `"hours"` | 시간 단위 | | `"minutes"` | 분 단위 | ```javascript // 마감일까지 남은 일수 dateBetween(prop("마감일"), now(), "days") // 근무 기간 (년) dateBetween(now(), prop("입사일"), "years") // 경과 시간 dateBetween(now(), prop("시작시간"), "hours") ``` *** dateAdd() [#dateadd] 날짜에 기간을 더합니다. ```javascript dateAdd(날짜, 숫자, 단위) ``` ```javascript // 7일 후 dateAdd(now(), 7, "days") // 1개월 후 dateAdd(prop("시작일"), 1, "months") ``` *** formatDate() [#formatdate] 날짜를 특정 형식의 문자열로 변환합니다. ```javascript formatDate(날짜, 형식) ``` ```javascript // 년-월-일 formatDate(prop("날짜"), "yyyy-MM-dd") // "2024-01-15" // 월/일 formatDate(prop("날짜"), "MM/dd") // "01/15" // 요일 포함 formatDate(prop("날짜"), "MM월 dd일 (EEE)") // "01월 15일 (월)" ``` *** 빈 값 처리 [#빈-값-처리] empty() [#empty] 값이 비어있는지 확인합니다. ```javascript empty(prop("속성이름")) // 비어있으면 true ``` ```javascript // 담당자 미지정 표시 if(empty(prop("담당자")), "❌ 미지정", prop("담당자")) // 마감일 없으면 "미정" if(empty(prop("마감일")), "미정", formatDate(prop("마감일"), "MM/DD")) ``` *** 실전 예시 [#실전-예시] 기본 계산 [#기본-계산] ```javascript // 총 금액 prop("단가") * prop("수량") // 할인가 prop("정가") * (1 - prop("할인율") / 100) // 부가세 포함 prop("금액") * 1.1 // 수수료 계산 prop("매출") * 0.03 ``` *** 진행률 [#진행률] ```javascript // 백분율 진행률 round(prop("완료 수") / prop("전체 수") * 100) // 진행률 바 (텍스트) concat( "▓".repeat(round(prop("진행률") / 10)), "░".repeat(10 - round(prop("진행률") / 10)), " ", prop("진행률"), "%" ) // 결과: "▓▓▓▓▓▓░░░░ 60%" ``` *** D-Day 표시 [#d-day-표시] ```javascript // 마감일 D-Day if(prop("마감일") < now(), concat("D+", dateBetween(now(), prop("마감일"), "days")), if(prop("마감일") == now(), "D-Day", concat("D-", dateBetween(prop("마감일"), now(), "days")) ) ) // 결과: "D-3" 또는 "D+2" 또는 "D-Day" ``` *** 상태 이모지 [#상태-이모지] ```javascript // 상태별 이모지 if(prop("상태") == "완료", "✅", if(prop("상태") == "진행중", "🔄", if(prop("상태") == "대기", "⏳", if(prop("상태") == "취소", "❌", "📋")))) ``` *** 우선순위 점수 [#우선순위-점수] ```javascript // 긴급도와 중요도로 우선순위 계산 if(prop("긴급") and prop("중요"), "🔴 1순위", if(prop("긴급") or prop("중요"), "🟡 2순위", "🟢 3순위")) ``` *** 재고 상태 [#재고-상태] ```javascript // 재고 상태 자동 표시 if(prop("재고") <= 0, "🔴 품절", if(prop("재고") <= prop("안전재고"), "🟡 저재고", "🟢 정상")) ``` *** 근무일 계산 [#근무일-계산] ```javascript // 근속 연수 concat( dateBetween(now(), prop("입사일"), "years"), "년 ", dateBetween(now(), prop("입사일"), "months") % 12, "개월" ) // 결과: "3년 5개월" ``` *** 이메일 도메인 추출 [#이메일-도메인-추출] ```javascript // @ 이후 도메인 slice(prop("이메일"), indexOf(prop("이메일"), "@") + 1) ``` *** 수식 작성 팁 [#수식-작성-팁] 1. 작게 시작하기 [#1-작게-시작하기] 복잡한 수식은 단계별로 작성하고 테스트하세요. ```javascript // 1단계: 기본 계산 prop("단가") * prop("수량") // 2단계: 할인 적용 prop("단가") * prop("수량") * (1 - prop("할인율") / 100) // 3단계: 최소 금액 적용 max(prop("단가") * prop("수량") * (1 - prop("할인율") / 100), 10000) ``` 2. 빈 값 처리 [#2-빈-값-처리] 속성이 비어있을 수 있으면 항상 처리하세요. ```javascript // ❌ 빈 값 미처리 prop("단가") * prop("수량") // 빈 값이면 에러 // ✅ 빈 값 처리 if(empty(prop("수량")), 0, prop("단가") * prop("수량")) ``` 3. 가독성 유지 [#3-가독성-유지] 긴 수식은 줄바꿈과 들여쓰기로 가독성을 높이세요. ```javascript // 가독성 좋은 중첩 조건 if(prop("점수") >= 90, "A", if(prop("점수") >= 80, "B", if(prop("점수") >= 70, "C", "D"))) ``` 4. 단위 주의 [#4-단위-주의] 숫자 계산 시 단위를 확인하세요. ```javascript // 할인율이 0~100 범위인 경우 prop("정가") * (1 - prop("할인율") / 100) // 할인율이 0~1 범위인 경우 prop("정가") * (1 - prop("할인율")) ``` *** 목록/배열 함수 [#목록배열-함수] count() [#count] 배열의 항목 수를 반환합니다. ```javascript count(배열) ``` ```javascript // 다중 선택 항목 수 count(prop("태그")) // ["버그", "긴급", "UI"] → 3 ``` *** unique() [#unique] 배열에서 중복을 제거한 고유 값 목록을 반환합니다. ```javascript unique(배열) ``` ```javascript // 중복 제거 unique(prop("카테고리")) // ["A", "B", "A", "C"] → ["A", "B", "C"] ``` *** includes() [#includes] 배열에 특정 값이 포함되어 있는지 확인합니다. ```javascript includes(배열, 값) ``` ```javascript // 태그 포함 여부 if(includes(prop("태그"), "긴급"), "🚨 긴급!", "일반") ``` *** join() [#join] 배열의 항목들을 구분자로 연결하여 문자열로 반환합니다. ```javascript join(배열, 구분자) ``` ```javascript // 태그 표시 join(prop("태그"), ", ") // ["버그", "UI"] → "버그, UI" ``` *** slice() [#slice] 배열의 일부분을 추출합니다. ```javascript slice(배열, 시작인덱스, 끝인덱스) ``` ```javascript // 처음 3개만 slice(prop("목록"), 0, 3) ``` *** at() [#at] 특정 인덱스의 요소를 반환합니다. ```javascript at(배열, 인덱스) ``` ```javascript // 첫 번째 항목 at(prop("목록"), 0) // 마지막 항목 (-1은 뒤에서 첫 번째) at(prop("목록"), -1) ``` *** listMin(), listMax() [#listmin-listmax] 배열의 최소값/최대값을 반환합니다. ```javascript listMin(배열) listMax(배열) ``` ```javascript // 점수 배열에서 최저점 listMin(prop("점수들")) // [85, 92, 78, 95] → 78 // 최고점 listMax(prop("점수들")) // [85, 92, 78, 95] → 95 ``` *** 전체 함수 목록 [#전체-함수-목록] 수학 함수 [#수학-함수] | 함수 | 설명 | 예시 | | --------------------- | ------------- | ---------------------------- | | `add(a, b)` | 덧셈 | `add(1, 2)` → `3` | | `subtract(a, b)` | 뺄셈 | `subtract(10, 3)` → `7` | | `multiply(a, b)` | 곱셈 | `multiply(3, 4)` → `12` | | `divide(a, b)` | 나눗셈 | `divide(10, 2)` → `5` | | `mod(a, b)` | 나머지 | `mod(10, 3)` → `1` | | `pow(x, y)` | 거듭제곱 | `pow(2, 3)` → `8` | | `abs(x)` | 절대값 | `abs(-10)` → `10` | | `round(x, decimals?)` | 반올림 | `round(3.14159, 2)` → `3.14` | | `floor(x)` | 내림 | `floor(3.7)` → `3` | | `ceil(x)` | 올림 | `ceil(3.2)` → `4` | | `min(a, b, ...)` | 최소값 | `min(5, 3)` → `3` | | `max(a, b, ...)` | 최대값 | `max(5, 3)` → `5` | | `sqrt(x)` | 제곱근 | `sqrt(9)` → `3` | | `cbrt(x)` | 세제곱근 | `cbrt(27)` → `3` | | `exp(x)` | e의 거듭제곱 | `exp(1)` → `2.718...` | | `ln(x)` | 자연로그 | `ln(e())` → `1` | | `log10(x)` | 상용로그 | `log10(100)` → `2` | | `log2(x)` | 밑이 2인 로그 | `log2(8)` → `3` | | `sign(x)` | 부호 (-1, 0, 1) | `sign(-5)` → `-1` | | `sin(x)` | 사인 (라디안) | `sin(0)` → `0` | | `cos(x)` | 코사인 (라디안) | `cos(0)` → `1` | | `tan(x)` | 탄젠트 (라디안) | `tan(0)` → `0` | | `pi()` | 원주율 | `pi()` → `3.14159...` | | `e()` | 자연상수 | `e()` → `2.71828...` | | `toNumber(x)` | 숫자 변환 | `toNumber("123")` → `123` | 텍스트 함수 [#텍스트-함수-1] | 함수 | 설명 | 예시 | | ------------------------------ | ----------- | ----------------------------------------- | | `concat(a, b, ...)` | 문자열 연결 | `concat("Hello", " ", "World")` | | `join(arr, sep)` | 배열을 구분자로 연결 | `join(["a", "b"], ",")` → `"a,b"` | | `split(text, sep)` | 문자열 분리 | `split("a,b,c", ",")` → `["a", "b", "c"]` | | `contains(text, sub)` | 포함 여부 | `contains("Hello", "ell")` → `true` | | `indexOf(text, sub)` | 위치 찾기 | `indexOf("hello", "l")` → `2` | | `startsWith(text, sub)` | 시작 여부 | `startsWith("hello", "he")` → `true` | | `endsWith(text, sub)` | 끝 여부 | `endsWith("hello", "lo")` → `true` | | `slice(text, start, end?)` | 부분 문자열 | `slice("Hello", 0, 2)` → `"He"` | | `substring(text, start, end?)` | 부분 문자열 | `substring("Hello", 1, 3)` → `"el"` | | `left(text, count)` | 왼쪽에서 추출 | `left("Hello", 2)` → `"He"` | | `right(text, count)` | 오른쪽에서 추출 | `right("Hello", 2)` → `"lo"` | | `length(text)` | 문자열 길이 | `length("Hello")` → `5` | | `upper(text)` | 대문자 변환 | `upper("hello")` → `"HELLO"` | | `lower(text)` | 소문자 변환 | `lower("HELLO")` → `"hello"` | | `capitalize(text)` | 첫 글자 대문자 | `capitalize("hello")` → `"Hello"` | | `trim(text)` | 양쪽 공백 제거 | `trim(" hi ")` → `"hi"` | | `trimStart(text)` | 왼쪽 공백 제거 | `trimStart(" hi")` → `"hi"` | | `trimEnd(text)` | 오른쪽 공백 제거 | `trimEnd("hi ")` → `"hi"` | | `replace(text, old, new)` | 첫 번째 치환 | `replace("abc", "b", "x")` → `"axc"` | | `replaceAll(text, old, new)` | 전체 치환 | `replaceAll("aba", "a", "x")` → `"xbx"` | | `test(text, regex)` | 정규식 검사 | `test("abc123", "[0-9]+")` → `true` | | `match(text, regex)` | 정규식 매치 | `match("abc123", "[0-9]+")` → `"123"` | | `repeat(text, count)` | 문자열 반복 | `repeat("ab", 3)` → `"ababab"` | | `padStart(text, len, char?)` | 왼쪽 패딩 | `padStart("5", 3, "0")` → `"005"` | | `padEnd(text, len, char?)` | 오른쪽 패딩 | `padEnd("5", 3, "0")` → `"500"` | | `format(template, ...)` | 포맷팅 | `format("{0}님", "홍길동")` → `"홍길동님"` | | `toString(value)` | 문자열 변환 | `toString(123)` → `"123"` | 논리 함수 [#논리-함수] | 함수 | 설명 | 예시 | | ------------------------------------ | ----------------- | --------------------------------------- | | `if(cond, then, else)` | 조건문 | `if(true, "A", "B")` → `"A"` | | `ifs(c1, v1, c2, v2, ..., default?)` | 다중 조건 (switch 대용) | `ifs(x=="A", "우수", x=="B", "양호", "보통")` | | `and(a, b, ...)` | 논리 AND | `and(true, false)` → `false` | | `or(a, b, ...)` | 논리 OR | `or(true, false)` → `true` | | `not(x)` | 논리 NOT | `not(true)` → `false` | | `equal(a, b)` | 동등 비교 | `equal(1, 1)` → `true` | | `unequal(a, b)` | 부등 비교 | `unequal(1, 2)` → `true` | | `larger(a, b)` | 크다 | `larger(5, 3)` → `true` | | `largerEq(a, b)` | 크거나 같다 | `largerEq(5, 5)` → `true` | | `smaller(a, b)` | 작다 | `smaller(3, 5)` → `true` | | `smallerEq(a, b)` | 작거나 같다 | `smallerEq(3, 3)` → `true` | | `empty(x)` | 빈 값 확인 | `empty("")` → `true` | | `ifEmpty(value, default)` | 빈 값이면 기본값 반환 | `ifEmpty(prop("메모"), "없음")` | | `isNumber(x)` | 숫자 여부 | `isNumber(123)` → `true` | | `isText(x)` | 텍스트 여부 | `isText("hello")` → `true` | | `isBoolean(x)` | 불리언 여부 | `isBoolean(true)` → `true` | | `isDate(x)` | 날짜 여부 | `isDate(now())` → `true` | | `isArray(x)` | 배열 여부 | `isArray([1, 2])` → `true` | 날짜 함수 [#날짜-함수-1] | 함수 | 설명 | 예시 | | ------------------------------- | --------------------- | ---------------------------------- | | `now()` | 현재 날짜/시간 | `now()` | | `today()` | 오늘 날짜 (시간 00:00) | `today()` | | `date(year, month, day)` | 날짜 생성 | `date(2024, 1, 15)` | | `dateAdd(date, num, unit)` | 날짜 더하기 | `dateAdd(now(), 7, "days")` | | `dateSubtract(date, num, unit)` | 날짜 빼기 | `dateSubtract(now(), 1, "months")` | | `dateBetween(d1, d2, unit)` | 날짜 차이 | `dateBetween(d1, d2, "days")` | | `year(date)` | 연도 추출 | `year(now())` → `2024` | | `month(date)` | 월 추출 (1-12) | `month(now())` → `12` | | `day(date)` | 일 추출 | `day(now())` → `14` | | `weekday(date)` | 요일 추출 (0=일, 1=월, ...) | `weekday(now())` | | `hour(date)` | 시간 추출 | `hour(now())` → `15` | | `minute(date)` | 분 추출 | `minute(now())` → `30` | | `second(date)` | 초 추출 | `second(now())` → `45` | | `startOfDay(date)` | 해당일 시작 (00:00) | `startOfDay(now())` | | `endOfDay(date)` | 해당일 종료 (23:59) | `endOfDay(now())` | | `startOfWeek(date)` | 해당 주 시작 (월요일) | `startOfWeek(now())` | | `endOfWeek(date)` | 해당 주 종료 (일요일) | `endOfWeek(now())` | | `startOfMonth(date)` | 해당 월 시작 | `startOfMonth(now())` | | `endOfMonth(date)` | 해당 월 종료 | `endOfMonth(now())` | | `startOfYear(date)` | 해당 연도 시작 | `startOfYear(now())` | | `endOfYear(date)` | 해당 연도 종료 | `endOfYear(now())` | | `isAfter(d1, d2)` | d1이 d2 이후인지 | `isAfter(prop("마감일"), now())` | | `isBefore(d1, d2)` | d1이 d2 이전인지 | `isBefore(now(), prop("마감일"))` | | `isSameDay(d1, d2)` | 같은 날인지 | `isSameDay(prop("날짜"), today())` | | `formatDate(date, format?)` | 날짜 포맷 | `formatDate(now(), "yyyy-MM-dd")` | | `timestamp(date)` | 타임스탬프 변환 (ms) | `timestamp(now())` | | `fromTimestamp(ts)` | 타임스탬프 → 날짜 | `fromTimestamp(1704067200000)` | | `parseDate(str)` | 문자열 → 날짜 | `parseDate("2024-01-15")` | 목록 함수 [#목록-함수] | 함수 | 설명 | 예시 | | -------------------------- | -------------- | --------------------------------------- | | `map(arr, callback)` | 각 요소에 함수 적용 | `prop("주문").map(current.금액)` | | `filter(arr, callback)` | 조건 만족 요소만 | `prop("주문").filter(current.상태 == "완료")` | | `find(arr, callback)` | 조건 만족 첫 요소 | `prop("담당자").find(current.역할 == "팀장")` | | `findIndex(arr, callback)` | 조건 만족 첫 인덱스 | `prop("태그").findIndex(current == "긴급")` | | `some(arr, callback)` | 하나라도 만족하면 true | `prop("체크리스트").some(current.완료)` | | `every(arr, callback)` | 모두 만족하면 true | `prop("항목").every(current.검토완료)` | | `sort(arr, callback?)` | 정렬 | `prop("점수").sort()` | | `reverse(arr)` | 역순 | `prop("날짜").reverse()` | | `flat(arr)` | 중첩 배열 평탄화 | `prop("태그목록").flat()` | | `unique(arr)` | 중복 제거 | `unique([1, 1, 2])` → `[1, 2]` | | `slice(arr, start, end?)` | 부분 배열 | `slice([1,2,3,4], 0, 2)` → `[1, 2]` | | `concat(arr1, arr2)` | 배열 연결 | `concat(prop("태그1"), prop("태그2"))` | | `at(arr, idx)` | 인덱스 접근 | `at([1, 2, 3], -1)` → `3` | | `first(arr)` | 첫 번째 요소 | `prop("담당자").first()` | | `last(arr)` | 마지막 요소 | `prop("이력").last()` | | `includes(arr, val)` | 포함 여부 | `includes([1, 2], 2)` → `true` | | `listIndexOf(arr, val)` | 값 인덱스 | `listIndexOf([1, 2], 2)` → `1` | | `sum(arr)` | 합계 | `sum([1, 2, 3])` → `6` | | `mean(arr)` | 평균 | `mean([2, 4, 6])` → `4` | | `average(arr)` | 평균 (mean의 별칭) | `average([2, 4, 6])` → `4` | | `count(arr)` | 항목 수 | `count([1, 2, 3])` → `3` | | `listMin(arr)` | 배열 최소값 | `listMin([3, 1, 2])` → `1` | | `listMax(arr)` | 배열 최대값 | `listMax([3, 1, 2])` → `3` | | `listJoin(arr, sep?)` | 배열 → 문자열 | `listJoin(["a", "b"], ", ")` → `"a, b"` | *** 다음 단계 [#다음-단계] * [속성](/docs/datamodels/properties) - 수식에서 사용할 수 있는 속성 타입 * [관계](/docs/datamodels/relations) - 롤업으로 관계 데이터 집계하기 * [워크플로우](/docs/workflows) - 수식 결과 기반 자동화 --- # 데이터모델 (/docs/datamodels) > 구조화된 데이터를 관리하는 데이터모델을 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; 데이터모델이란? [#데이터모델이란] 데이터모델은 \*\*행(Row)\*\*과 \*\*속성(Property)\*\*으로 구성된 데이터 테이블입니다. 엑셀이나 구글 시트와 비슷하지만, 다음과 같은 강력한 기능을 추가로 제공합니다: | 기능 | 스프레드시트 | 데이터모델 | | ---------------------- | :----: | :----: | | 다양한 속성 타입 | △ | ✅ 17가지 | | 데이터 간 관계 설정 | ❌ | ✅ | | 다양한 뷰 (테이블, 보드, 캘린더 등) | △ | ✅ 5가지 | | 수식과 롤업 | ✅ | ✅ | | 워크플로우 자동화 트리거 | ❌ | ✅ | | 실시간 협업 | △ | ✅ | | 버전 히스토리 | △ | ✅ | 기본 구조 [#기본-구조] ``` 데이터모델: 고객 ├── 속성 (Properties) - 열 정의 │ ├── 회사명 (제목) ← 필수 속성 │ ├── 담당자 (텍스트) │ ├── 이메일 (이메일) │ ├── 계약 상태 (단일 선택) │ └── 계약 금액 (통화) └── 행 (Rows) - 개별 데이터 ├── 주식회사 A ├── 주식회사 B └── 주식회사 C ``` *** 데이터모델 생성 [#데이터모델-생성] 데이터모델을 만드는 방법은 여러 가지가 있습니다. 방법 1: 사이드바에서 생성 [#방법-1-사이드바에서-생성] 1. 사이드바에서 **+ 새 데이터모델** 버튼을 클릭합니다 2. 데이터모델 이름을 입력합니다 3. 필요한 속성을 추가합니다 방법 2: 페이지에서 생성 [#방법-2-페이지에서-생성] 페이지 내에서 `/datamodel`을 입력하면 새 데이터모델을 생성하거나 기존 데이터모델을 삽입할 수 있습니다. 방법 3: 테일러 AI에게 요청 [#방법-3-테일러-ai에게-요청] ``` 고객 관리를 위한 데이터모델을 만들어줘. 회사명, 담당자, 이메일, 계약 상태, 계약 금액을 관리하고 싶어. ``` 테일러가 요구사항을 분석하여 적절한 속성 타입과 함께 데이터모델을 자동으로 생성합니다. <Callout type="tip"> 복잡한 업무시스템을 만들 때는 테일러에게 요청하는 것이 가장 빠릅니다. 테일러는 관계 설정과 샘플 데이터까지 자동으로 생성해줍니다. </Callout> *** 핵심 기능 개요 [#핵심-기능-개요] 다양한 속성 타입 [#다양한-속성-타입] 17가지 속성 타입으로 다양한 데이터를 저장할 수 있습니다. | 카테고리 | 속성 타입 | 개수 | | --------- | --------------- | :-: | | **기본** | 제목, 텍스트, 숫자, 통화 | 4 | | **선택** | 단일 선택, 다중 선택 | 2 | | **날짜/체크** | 날짜, 체크박스 | 2 | | **사용자** | 사용자(담당자) | 1 | | **미디어** | 파일 첨부 | 1 | | **연락처** | URL, 이메일, 전화번호 | 3 | | **관계** | 관계, 롤업 | 2 | | **계산** | 수식 | 1 | | **액션** | 버튼(워크플로우 실행) | 1 | 👉 [속성 타입 자세히 보기](/docs/datamodels/properties) 다양한 뷰 [#다양한-뷰] 같은 데이터를 다양한 방식으로 볼 수 있습니다. | 뷰 | 적합한 용도 | | ---------- | ------------------- | | **테이블** | 데이터 입력/편집, 상세 정보 확인 | | **칸반(보드)** | 프로젝트 관리, 영업 파이프라인 | | **캘린더** | 일정 관리, 마감일 추적 | | **갤러리** | 제품 카탈로그, 인물 디렉토리 | | **리스트** | 할 일 목록, 빠른 스캔 | 👉 [뷰 자세히 보기](/docs/datamodels/views) 관계 설정 [#관계-설정] 데이터모델 간의 관계를 설정하여 연결된 데이터를 쉽게 관리합니다. ``` 고객 ─────────────< 주문 │ │ │ ▼ │ 상품 │ └───────────────< 미팅기록 ``` 👉 [관계 설정 자세히 보기](/docs/datamodels/relations) 수식 [#수식] 다른 속성의 값을 기반으로 자동 계산된 값을 표시합니다. ``` 총 금액: prop("단가") * prop("수량") ``` 👉 [수식 자세히 보기](/docs/datamodels/formulas) *** 데이터 관리 [#데이터-관리] 행 추가 [#행-추가] * 테이블 하단의 **+ 새 항목** 버튼 클릭 * 마지막 행에서 `Enter` 키 입력 * `Cmd/Ctrl + Enter`로 빠른 추가 행 편집 [#행-편집] * 셀을 클릭하여 직접 편집 * 행을 클릭하면 상세 패널이 열립니다 행 삭제 [#행-삭제] * 행 선택 후 `Delete` 또는 `Backspace` * 행 우클릭 후 **삭제** 선택 * 여러 행 선택 후 일괄 삭제 가능 일괄 작업 [#일괄-작업] * `Cmd/Ctrl + 클릭`으로 여러 행 선택 * `Shift + 클릭`으로 범위 선택 * 선택 후 일괄 편집, 삭제, 복제 가능 *** 필터와 정렬 [#필터와-정렬] 필터 [#필터] 조건에 맞는 데이터만 표시합니다. 1. 테이블 상단의 **필터** 버튼 클릭 2. 필터 조건 추가 3. 속성, 연산자, 값 선택 ``` 상태 = "진행 중" AND 마감일 < 오늘 ``` 지원되는 연산자 [#지원되는-연산자] | 속성 타입 | 연산자 | | ----------- | ---------------------- | | **텍스트** | 포함, 미포함, 같음, 다름, 비어있음 | | **숫자/통화** | 같음, 다름, 크다, 작다, 이상, 이하 | | **날짜** | 해당일, 기간, 이전, 이후 | | **선택** | 같음, 다름 | | **다중선택/관계** | 포함(any), 비어있음 | | **체크박스** | 참, 거짓 | 정렬 [#정렬] 특정 속성을 기준으로 정렬합니다. 1. 속성 헤더 클릭 → 오름차순/내림차순 선택 2. 또는 **정렬** 버튼으로 다중 정렬 기준 설정 *** 활용 예시 [#활용-예시] CRM (고객 관리) [#crm-고객-관리] ``` 고객사 ├── 회사명 (제목) ├── 담당자 (텍스트) ├── 이메일 (이메일) ├── 전화번호 (전화번호) ├── 업종 (단일 선택) ├── 규모 (단일 선택) ├── 계약 상태 (단일 선택) → 칸반 뷰 ├── 담당 영업사원 (사용자) ├── 미팅기록 (관계) → 미팅기록 데이터모델 └── 예상 매출 (통화) ``` 프로젝트 관리 [#프로젝트-관리] ``` 태스크 ├── 태스크명 (제목) ├── 설명 (텍스트) ├── 상태 (단일 선택) → 칸반 뷰 ├── 우선순위 (단일 선택) ├── 담당자 (사용자) ├── 마감일 (날짜) → 캘린더 뷰 ├── 프로젝트 (관계) → 프로젝트 데이터모델 ├── 스토리포인트 (숫자) └── 완료일 (날짜) ``` 재고 관리 [#재고-관리] ``` 상품 ├── 상품명 (제목) ├── SKU (텍스트) ├── 카테고리 (단일 선택) ├── 가격 (통화) ├── 재고량 (숫자) ├── 최소 재고량 (숫자) ├── 이미지 (파일) → 갤러리 뷰 ├── 재고 상태 (수식) → if(재고량 <= 최소재고량, "⚠️ 저재고", "✅ 정상") └── 입출고 내역 (관계) ``` *** 이 섹션에서 다루는 내용 [#이-섹션에서-다루는-내용] <Cards> <Card title="속성" description="17가지 속성 타입의 상세 사용법" href="/docs/datamodels/properties" /> <Card title="뷰" description="테이블, 보드, 캘린더 등 5가지 뷰" href="/docs/datamodels/views" /> <Card title="관계" description="데이터모델 간 관계 설정과 롤업" href="/docs/datamodels/relations" /> <Card title="수식" description="자동 계산과 조건부 값" href="/docs/datamodels/formulas" /> </Cards> --- # 속성 (/docs/datamodels/properties) > 데이터모델의 다양한 속성 타입을 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; 속성 추가하기 [#속성-추가하기] 데이터모델에 새 속성을 추가하는 방법: 1. 테이블 헤더의 **+** 버튼 클릭 2. 속성 이름 입력 3. 속성 타입 선택 4. 타입별 추가 옵션 설정 <Callout type="tip"> 속성 이름은 나중에 언제든지 변경할 수 있지만, 속성 타입은 데이터 손실을 방지하기 위해 일부 타입 간에만 변환이 가능합니다. </Callout> *** 기본 속성 타입 [#기본-속성-타입] 제목 (Title) [#제목-title] 모든 데이터모델에 **필수**로 존재하는 속성입니다. 각 행을 식별하는 기본 이름으로 사용됩니다. | 특징 | 설명 | | --------- | ---------------- | | **필수 여부** | 필수 (삭제 불가) | | **타입 변경** | 불가 | | **용도** | 행의 기본 식별자, 검색 대상 | ``` 예시: 고객명, 프로젝트명, 상품명 ``` *** 텍스트 (Text) [#텍스트-text] 일반 텍스트를 저장합니다. | 옵션 | 설명 | | ---------- | ------------------- | | **리치 텍스트** | 굵게, 기울임, 링크 등 서식 지원 | | **여러 줄** | 긴 텍스트를 위한 멀티라인 입력 | ``` 예시: 설명, 메모, 주소 ``` *** 숫자 (Number) [#숫자-number] 숫자 값을 저장합니다. | 옵션 | 설명 | 예시 | | ----------- | ----------- | ------------- | | **형식** | 정수/소수점 선택 | 100 또는 100.50 | | **천 단위 구분** | 쉼표로 구분 | 1,000,000 | | **소수점 자릿수** | 표시할 소수점 자릿수 | 0\~8 | | **백분율** | % 형식으로 표시 | 75% | 포맷 옵션 [#포맷-옵션] ```typescript { numberFormat: "number" | "number_no_commas" | "percent", decimalPlaces: 0 ~ 8, useGrouping: true | false } ``` ``` 예시: 수량, 점수, 진행률 ``` *** 통화 (Currency) [#통화-currency] 금액을 저장합니다. 숫자 타입에 통화 형식을 추가한 형태입니다. | 옵션 | 설명 | | --------- | --------------------- | | **통화** | KRW, USD, EUR, JPY 등 | | **표시 형식** | 기호(₩), 코드(KRW), 이름(원) | | **소수점** | 통화별 기본값 자동 적용 | ``` 예시: ₩1,000,000 / $1,500.00 / €2,000.00 ``` *** 선택 속성 [#선택-속성] 단일 선택 (Select) [#단일-선택-select] 미리 정의된 옵션 중 **하나**를 선택합니다. | 옵션 | 설명 | | --------- | --------------- | | **옵션 목록** | 선택 가능한 값들 정의 | | **색상** | 각 옵션에 색상 지정 가능 | | **기본값** | 새 행 생성 시 기본 선택값 | 옵션 정의 예시 [#옵션-정의-예시] ```typescript options: [ { label: "할 일", value: "todo", color: "#E0E0E0" }, { label: "진행 중", value: "in_progress", color: "#FFE082" }, { label: "완료", value: "done", color: "#A5D6A7" }, { label: "보류", value: "on_hold", color: "#EF9A9A" } ] ``` ``` 예시: 상태, 카테고리, 우선순위, 단계 ``` <Callout type="info"> 단일 선택 속성은 **칸반 뷰**의 그룹화 기준으로 사용할 수 있습니다. </Callout> *** 다중 선택 (Multi-select) [#다중-선택-multi-select] 여러 개의 옵션을 **동시에** 선택할 수 있습니다. | 옵션 | 설명 | | ----------- | -------------------- | | **옵션 목록** | 선택 가능한 값들 정의 | | **색상** | 각 옵션에 색상 지정 가능 | | **최대 선택 수** | 선택 가능한 최대 개수 제한 (선택) | ``` 예시: 태그, 라벨, 스킬, 관심사 ``` *** 날짜 및 체크박스 [#날짜-및-체크박스] 날짜 (Date) [#날짜-date] 날짜와 시간을 저장합니다. | 옵션 | 설명 | 예시 | | --------- | ------------ | ------------------------ | | **날짜 형식** | 표시 형식 선택 | YYYY/MM/DD, MM/DD/YYYY | | **시간 포함** | 시간 입력 활성화 | 2024-01-15 14:30 | | **시간 형식** | 24시간/12시간 선택 | 14:30 또는 2:30 PM | | **범위 선택** | 시작일\~종료일 | 2024-01-15 \~ 2024-01-20 | | **시간대** | 타임존 설정 | Asia/Seoul | 포맷 옵션 [#포맷-옵션-1] ```typescript { dateFormat: "YYYY/MM/DD" | "MM/DD/YYYY" | "DD/MM/YYYY" | "LL" | "PPP", timeFormat: "HH:mm" | "hh:mm A" | "none", includeTime: true | false, isRange: true | false, timezone: "Asia/Seoul" } ``` ``` 예시: 마감일, 시작일, 생성일, 미팅 일시 ``` <Callout type="info"> 날짜 속성은 **캘린더 뷰**에서 자동으로 표시됩니다. </Callout> *** 체크박스 (Checkbox) [#체크박스-checkbox] 예/아니오 값을 저장합니다. | 상태 | 표시 | | ------------- | ------- | | **참(True)** | ☑️ 체크됨 | | **거짓(False)** | ☐ 체크 안됨 | ``` 예시: 완료 여부, 활성 상태, 승인 여부 ``` *** 사용자 [#사용자] 사용자 (Person) [#사용자-person] 워크스페이스 멤버를 선택합니다. | 옵션 | 설명 | | --------- | ---------- | | **다중 선택** | 여러 명 선택 허용 | | **알림** | 멘션 시 알림 전송 | ``` 예시: 담당자, 작성자, 참여자, 리뷰어 ``` *** 미디어 [#미디어] 파일 (Files) [#파일-files] 다양한 형식의 파일을 첨부합니다. | 지원 형식 | 예시 | | ------- | ------------------------------------ | | **이미지** | JPG, PNG, GIF, WebP, SVG | | **문서** | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX | | **압축** | ZIP, RAR | | **기타** | 모든 파일 형식 | | 옵션 | 설명 | | --------- | ------------ | | **다중 첨부** | 여러 파일 첨부 허용 | | **최대 용량** | 파일당 최대 크기 제한 | ``` 예시: 첨부파일, 계약서, 이미지 ``` <Callout type="info"> 이미지 파일이 첨부된 속성은 **갤러리 뷰**에서 썸네일로 표시됩니다. </Callout> *** 연락처 [#연락처] URL [#url] 웹 링크를 저장합니다. | 동작 | 설명 | | -------- | ----------------------- | | **클릭** | 새 탭에서 링크 열기 | | **미리보기** | 호버 시 링크 미리보기 (지원되는 사이트) | ``` 예시: 웹사이트, 프로필 링크, 참고 자료 ``` *** 이메일 (Email) [#이메일-email] 이메일 주소를 저장합니다. | 동작 | 설명 | | ---------- | ----------------- | | **클릭** | 기본 메일 앱으로 새 메일 작성 | | **유효성 검사** | 이메일 형식 자동 검증 | ``` 예시: 이메일, 담당자 이메일 ``` *** 전화번호 (Phone) [#전화번호-phone] 전화번호를 저장합니다. | 동작 | 설명 | | ------ | ------------- | | **클릭** | 전화 앱 실행 (모바일) | | **형식** | 국가별 형식 자동 적용 | ``` 예시: 전화번호, 휴대폰, 팩스 ``` *** 관계 [#관계] 관계 (Relation) [#관계-relation] 다른 데이터모델의 행과 연결합니다. | 관계 타입 | 설명 | 예시 | | ------- | ------ | ----------- | | **일대일** | 1:1 연결 | 사용자 ↔ 프로필 | | **일대다** | 1:N 연결 | 프로젝트 → 태스크들 | | **다대일** | N:1 연결 | 태스크들 → 프로젝트 | | **다대다** | N:M 연결 | 태스크 ↔ 태그 | ``` 예시: 담당 프로젝트, 소속 팀, 관련 고객 ``` 👉 [관계 설정 자세히 보기](/docs/datamodels/relations) *** 롤업 (Rollup) [#롤업-rollup] 관계된 데이터의 값을 **집계**하여 표시합니다. | 집계 함수 | 설명 | | ----------- | --- | | **COUNT** | 개수 | | **SUM** | 합계 | | **AVERAGE** | 평균 | | **MIN** | 최소값 | | **MAX** | 최대값 | | **MEDIAN** | 중앙값 | ``` 예시: 총 주문 금액, 태스크 완료율, 평균 점수 ``` *** 계산 [#계산] 수식 (Formula) [#수식-formula] 다른 속성의 값을 기반으로 자동 계산된 값을 표시합니다. ```javascript // 총 금액 계산 prop("단가") * prop("수량") // 마감일까지 남은 일수 dateBetween(prop("마감일"), now(), "days") // 상태 이모지 if(prop("상태") == "완료", "✅", "⏳") ``` 👉 [수식 자세히 보기](/docs/datamodels/formulas) *** 액션 [#액션] 버튼 (Actions) [#버튼-actions] 클릭 시 **워크플로우를 실행**하는 버튼입니다. | 설정 | 설명 | | ---------- | ------------ | | **워크플로우** | 실행할 워크플로우 선택 | | **버튼 레이블** | 버튼에 표시할 텍스트 | | **아이콘** | 버튼 아이콘 (선택) | ``` 예시: "승인" 버튼, "이메일 발송" 버튼, "상태 변경" 버튼 ``` <Callout type="info"> 버튼을 클릭하면 현재 행의 데이터가 워크플로우에 전달됩니다. </Callout> *** 시스템 속성 [#시스템-속성] 자동으로 생성되는 읽기 전용 속성입니다. | 속성 | 설명 | | -------------------- | ------------------ | | **생성일 (Created At)** | 행이 생성된 날짜/시간 | | **수정일 (Updated At)** | 행이 마지막으로 수정된 날짜/시간 | *** 속성 설정 [#속성-설정] 속성 옵션 [#속성-옵션] 모든 속성에 공통으로 적용되는 설정입니다. | 옵션 | 설명 | | -------- | ------------------- | | **이름** | 속성 표시 이름 | | **설명** | 속성에 대한 설명 (툴팁으로 표시) | | **필수** | 값이 필수인지 여부 | | **기본값** | 새 행 생성 시 기본값 | | **숨김** | 기본 테이블 뷰에서 숨김 | | **열 너비** | 테이블에서의 열 너비 | 속성 순서 변경 [#속성-순서-변경] 테이블 헤더를 드래그하여 속성 순서를 변경할 수 있습니다. 속성 삭제 [#속성-삭제] <Callout type="warn"> 속성을 삭제하면 해당 속성의 **모든 데이터가 영구 삭제**됩니다. 이 작업은 되돌릴 수 없습니다. </Callout> 1. 속성 헤더를 클릭하여 메뉴 열기 2. **속성 삭제** 선택 3. 확인 대화상자에서 삭제 확인 *** 속성 타입별 필터 연산자 [#속성-타입별-필터-연산자] | 속성 타입 | 지원 연산자 | | --------- | --------------------------------------------- | | **텍스트** | 포함, 미포함, 같음, 다름, 비어있음, 비어있지 않음 | | **숫자/통화** | 같음, 다름, 크다 (>), 이상 (≥), 작다 (\<), 이하 (≤), 비어있음 | | **날짜** | 해당일, 기간, 같음, 다름, 이전, 이후, 비어있음 | | **선택** | 같음, 다름, 비어있음 | | **다중 선택** | 포함(any), 비어있음 | | **관계** | 포함(any), 같음, 비어있음 | | **체크박스** | 참, 거짓 | | **URL** | 포함, 미포함, 같음, 다름, 비어있음 | *** 다음 단계 [#다음-단계] * [뷰](/docs/datamodels/views) - 데이터를 다양한 방식으로 보기 * [관계](/docs/datamodels/relations) - 데이터모델 간 연결하기 * [수식](/docs/datamodels/formulas) - 자동 계산 설정하기 --- # 관계 (/docs/datamodels/relations) > 데이터모델 간의 관계를 설정하세요. import { Callout } from 'fumadocs-ui/components/callout'; 왜 관계가 필요한가? [#왜-관계가-필요한가] 데이터 간의 연결이 없으면 **중복**과 **불일치** 문제가 발생합니다. 관계 없이 관리하는 경우 [#관계-없이-관리하는-경우] | 주문 ID | 고객명 | 고객 이메일 | 고객 전화번호 | 상품명 | | ----- | --- | ----------------------------------------- | ------------- | --- | | 001 | 김철수 | [kim@example.com](mailto:kim@example.com) | 010-1234-5678 | 노트북 | | 002 | 김철수 | [kim@email.com](mailto:kim@email.com) | 010-1234-5678 | 마우스 | | 003 | 김철수 | [kim@example.com](mailto:kim@example.com) | 010-1234-0000 | 키보드 | ❌ 문제점: * 고객 정보가 중복 입력됨 * 이메일/전화번호가 불일치함 * 고객 정보 수정 시 모든 행을 수정해야 함 관계로 관리하는 경우 [#관계로-관리하는-경우] **고객 데이터모델** | 고객 ID | 고객명 | 이메일 | 전화번호 | | ----- | --- | ----------------------------------------- | ------------- | | C001 | 김철수 | [kim@example.com](mailto:kim@example.com) | 010-1234-5678 | **주문 데이터모델** | 주문 ID | 고객 (관계) | 상품명 | | ----- | ------- | --- | | 001 | → 김철수 | 노트북 | | 002 | → 김철수 | 마우스 | | 003 | → 김철수 | 키보드 | ✅ 장점: * 고객 정보 한 곳에서 관리 * 항상 일관된 정보 표시 * 수정 시 한 번만 변경 *** 관계 타입 [#관계-타입] 슈츠는 네 가지 관계 타입을 지원합니다. 일대일 (One-to-One) [#일대일-one-to-one] 하나의 항목이 **정확히 하나의 항목**과 연결됩니다. ``` 사용자 ←→ 프로필 │ │ A ─────── A의 프로필 B ─────── B의 프로필 ``` **예시:** * 사용자 ↔ 프로필 * 직원 ↔ 급여 정보 * 주문 ↔ 배송 정보 *** 일대다 (One-to-Many) [#일대다-one-to-many] 하나의 항목이 **여러 항목**과 연결됩니다. ``` 프로젝트 ──→ 태스크 │ A ────┬── 태스크 1 ├── 태스크 2 └── 태스크 3 ``` **예시:** * 고객 → 주문 (한 고객이 여러 주문) * 프로젝트 → 태스크 (한 프로젝트에 여러 태스크) * 부서 → 직원 (한 부서에 여러 직원) * 카테고리 → 상품 (한 카테고리에 여러 상품) *** 다대일 (Many-to-One) [#다대일-many-to-one] **여러 항목**이 하나의 항목과 연결됩니다. (일대다의 역방향) ``` 태스크 ──→ 프로젝트 │ 태스크 1 ──┐ 태스크 2 ──┼── 프로젝트 A 태스크 3 ──┘ ``` **예시:** * 주문 → 고객 (여러 주문이 한 고객) * 태스크 → 프로젝트 (여러 태스크가 한 프로젝트) * 직원 → 부서 (여러 직원이 한 부서) *** 다대다 (Many-to-Many) [#다대다-many-to-many] **여러 항목**이 **여러 항목**과 연결됩니다. ``` 태스크 ←→ 태그 │ │ 태스크1 ─┬─ 긴급 ├─ 버그 태스크2 ─┼─ 긴급 └─ 개선 ``` **예시:** * 태스크 ↔ 담당자 (한 태스크에 여러 담당자, 한 담당자가 여러 태스크) * 상품 ↔ 태그 (한 상품에 여러 태그, 한 태그에 여러 상품) * 학생 ↔ 수업 (한 학생이 여러 수업, 한 수업에 여러 학생) *** 관계 설정하기 [#관계-설정하기] 1단계: 관계 속성 추가 [#1단계-관계-속성-추가] 1. 데이터모델에서 **+ 속성 추가** 클릭 2. 속성 타입에서 **관계(Relation)** 선택 3. 속성 이름 입력 (예: "담당 프로젝트", "주문 고객") 2단계: 연결할 데이터모델 선택 [#2단계-연결할-데이터모델-선택] 드롭다운에서 연결할 대상 데이터모델을 선택합니다. 3단계: 관계 타입 설정 [#3단계-관계-타입-설정] | 설정 | 설명 | | --------- | ---------------------- | | **단일 선택** | 하나의 항목만 연결 (다대일, 일대일) | | **다중 선택** | 여러 항목 연결 가능 (다대다, 일대다) | 4단계: 양방향 관계 설정 (선택) [#4단계-양방향-관계-설정-선택] **역방향 관계 속성 생성**을 체크하면 연결된 데이터모델에도 자동으로 관계 속성이 생성됩니다. ``` 태스크 ──→ 프로젝트 (태스크에서 프로젝트 선택) ↓ 프로젝트 ──→ 태스크들 (프로젝트에서 관련 태스크 목록 표시) ``` <Callout type="tip"> 양방향 관계를 설정하면 양쪽 데이터모델에서 모두 관련 데이터를 확인할 수 있어 편리합니다. </Callout> *** 관계 속성 사용하기 [#관계-속성-사용하기] 데이터 연결 [#데이터-연결] 관계 속성 셀을 클릭하면 연결할 수 있는 항목 목록이 표시됩니다. 1. 셀 클릭 2. 검색하거나 목록에서 선택 3. 연결 완료 연결된 데이터 보기 [#연결된-데이터-보기] 관계 셀을 클릭하면 연결된 항목의 미리보기가 표시됩니다. 클릭하여 상세 페이지로 이동할 수 있습니다. 표시 속성 설정 [#표시-속성-설정] 관계 셀에 표시할 대상 데이터모델의 속성을 선택할 수 있습니다. 1. 관계 속성 설정 열기 2. **표시 속성** 선택 3. 셀에 표시할 속성 체크 (예: 이름, 상태) *** 롤업 [#롤업] \*\*롤업(Rollup)\*\*은 관계된 데이터의 값을 **집계**하여 표시하는 속성입니다. 롤업 함수 [#롤업-함수] | 함수 | 설명 | 예시 | | ----------- | --------- | --------------- | | **COUNT** | 연결된 항목 수 | 주문 수: 5 | | **SUM** | 숫자 속성의 합 | 총 주문 금액: ₩500만 | | **AVERAGE** | 숫자 속성의 평균 | 평균 주문 금액: ₩100만 | | **MIN** | 최소값 | 최소 주문 금액: ₩50만 | | **MAX** | 최대값 | 최대 주문 금액: ₩200만 | | **MEDIAN** | 중앙값 | 중앙 주문 금액: ₩100만 | 롤업 설정하기 [#롤업-설정하기] 1. **+ 속성 추가** → **롤업(Rollup)** 선택 2. **관계 속성** 선택: 집계할 관계 속성 3. **대상 속성** 선택: 집계할 속성 (숫자 타입) 4. **집계 함수** 선택: COUNT, SUM, AVERAGE 등 롤업 예시 [#롤업-예시] **고객 데이터모델** | 고객명 | 주문 (관계) | 총 주문 금액 (롤업) | 주문 건수 (롤업) | | --- | ------------- | ------------ | ---------- | | 김철수 | 주문1, 주문2, 주문3 | ₩450만 | 3 | | 이영희 | 주문4, 주문5 | ₩280만 | 2 | 설정: * 총 주문 금액: 관계=주문, 속성=금액, 함수=SUM * 주문 건수: 관계=주문, 속성=-, 함수=COUNT *** 활용 패턴 [#활용-패턴] CRM (고객 관계 관리) [#crm-고객-관계-관리] ``` 고객사 ─────────────< 담당자 │ │ ├───────────────< 영업기회 │ │ └───────────────< 미팅기록 ``` | 데이터모델 | 관계 | 롤업 | | ----- | ----------- | ---------------------------- | | 고객사 | 담당자들, 영업기회들 | 총 예상 매출(SUM), 진행중 딜 수(COUNT) | | 담당자 | 소속 고객사 | - | | 영업기회 | 고객사, 담당자 | - | | 미팅기록 | 고객사, 영업기회 | - | *** 프로젝트 관리 [#프로젝트-관리] ``` 프로젝트 ─────────< 마일스톤 │ │ │ ├────────< 태스크 │ │ └─────────────────┘ 태스크 ←────────→ 담당자 (다대다) ``` | 데이터모델 | 관계 | 롤업 | | ----- | ------------- | ---------------------- | | 프로젝트 | 마일스톤들 | 완료율(COUNT 완료/COUNT 전체) | | 마일스톤 | 소속 프로젝트, 태스크들 | 태스크 완료율 | | 태스크 | 마일스톤, 담당자들 | - | *** 인사 관리 [#인사-관리] ``` 부서 ─────────────< 직원 │ │ └──────────────< 프로젝트 (부서별) │ └───────→ 직원 (프로젝트 멤버, 다대다) ``` | 데이터모델 | 관계 | 롤업 | | ----- | -------------- | ----------- | | 부서 | 소속 직원들 | 직원 수, 평균 연봉 | | 직원 | 소속 부서, 참여 프로젝트 | 참여 프로젝트 수 | | 프로젝트 | 주관 부서, 멤버들 | 멤버 수 | *** 재고 관리 [#재고-관리] ``` 카테고리 ─────────< 상품 │ 입출고 >─────────────┘ ``` | 데이터모델 | 관계 | 롤업 | | ----- | ------------ | -------------------- | | 카테고리 | 상품들 | 상품 수, 총 재고 가치 | | 상품 | 카테고리, 입출고 내역 | 현재 재고(입고SUM - 출고SUM) | | 입출고 | 상품 | - | *** 관계 설계 팁 [#관계-설계-팁] 1. 중복 데이터 피하기 [#1-중복-데이터-피하기] 같은 정보가 여러 곳에 입력되면 관계로 분리하세요. ``` ❌ 잘못된 예: 주문: 고객명, 고객이메일, 고객전화, 상품명, 상품가격... ✅ 좋은 예: 주문 → 고객 (관계) 주문 → 상품 (관계) ``` 2. 양방향 관계 활용 [#2-양방향-관계-활용] 단방향보다 양방향 관계를 설정하면 양쪽에서 모두 데이터를 확인할 수 있습니다. 3. 롤업으로 집계 자동화 [#3-롤업으로-집계-자동화] 수동으로 합계를 계산하는 대신 롤업을 사용하세요. 데이터가 변경되면 자동으로 업데이트됩니다. 4. 명확한 관계명 사용 [#4-명확한-관계명-사용] 관계 속성 이름은 의미가 명확해야 합니다. ``` ❌ 모호한 예: "관련 데이터", "링크" ✅ 명확한 예: "담당 프로젝트", "주문 고객", "할당된 태스크" ``` *** 테일러로 관계 설정하기 [#테일러로-관계-설정하기] 테일러에게 전체 시스템을 요청하면 관계까지 자동으로 설정됩니다. ``` B2B 영업팀을 위한 CRM 시스템을 만들어줘. 고객사, 담당자, 영업기회, 미팅기록을 관리하고 싶어. 각 고객사에는 여러 담당자가 있고, 영업기회는 특정 고객사와 연결되어야 해. ``` 테일러가 생성하는 결과: * 고객사 데이터모델 (담당자, 영업기회 관계 포함) * 담당자 데이터모델 (소속 고객사 관계) * 영업기회 데이터모델 (고객사, 담당자 관계) * 미팅기록 데이터모델 (고객사, 영업기회 관계) *** 다음 단계 [#다음-단계] * [수식](/docs/datamodels/formulas) - 자동 계산 설정하기 * [뷰](/docs/datamodels/views) - 관계 데이터를 다양한 방식으로 보기 * [워크플로우](/docs/workflows) - 관계 데이터 기반 자동화 --- # 뷰 (/docs/datamodels/views) > 데이터를 다양한 방식으로 시각화하세요. import { Callout } from 'fumadocs-ui/components/callout'; 뷰 종류 [#뷰-종류] 슈츠는 5가지 뷰 타입을 제공합니다. | 뷰 | 최적 용도 | 핵심 기능 | | ----------- | ---------------- | -------------- | | **테이블** | 데이터 입력/편집, 상세 분석 | 인라인 편집, 열 조정 | | **칸반 (보드)** | 프로젝트 관리, 파이프라인 | 드래그 앤 드롭 상태 변경 | | **캘린더** | 일정 관리, 마감일 추적 | 날짜 기반 표시 | | **갤러리** | 시각적 카탈로그, 디렉토리 | 이미지 썸네일 | | **리스트** | 빠른 스캔, 할 일 목록 | 간결한 표시 | *** 뷰 추가하기 [#뷰-추가하기] 데이터모델에 새 뷰를 추가하는 방법: 1. 데이터모델 상단의 뷰 탭 영역에서 **+** 버튼 클릭 2. 뷰 타입 선택 3. 뷰 이름 입력 4. 뷰별 설정 구성 <Callout type="info"> 하나의 데이터모델에 여러 개의 뷰를 만들 수 있습니다. 예를 들어, "내 태스크" 테이블 뷰, "팀 진행현황" 칸반 뷰, "마감일" 캘린더 뷰를 각각 만들어 사용하세요. </Callout> *** 테이블 뷰 [#테이블-뷰] 가장 기본적인 **스프레드시트 형태**의 뷰입니다. 모든 속성을 열로 표시하며, 데이터 입력과 편집에 최적화되어 있습니다. 화면 구성 [#화면-구성] ``` ┌─────────────────────────────────────────────────────────────┐ │ 필터 정렬 그룹화 속성 + 새 항목 │ ├──────────┬──────────┬──────────┬──────────┬────────────────┤ │ 고객명 │ 상태 │ 담당자 │ 금액 │ 마감일 │ ├──────────┼──────────┼──────────┼──────────┼────────────────┤ │ 고객 A │ 🔵 진행중 │ 김철수 │ ₩100만 │ 2024-01-15 │ │ 고객 B │ 🟢 완료 │ 이영희 │ ₩200만 │ 2024-01-20 │ │ 고객 C │ 🟡 대기 │ 박지민 │ ₩150만 │ 2024-01-25 │ └──────────┴──────────┴──────────┴──────────┴────────────────┘ ``` 특징 [#특징] | 기능 | 설명 | | ----------- | --------------- | | **인라인 편집** | 셀 클릭 시 바로 편집 가능 | | **열 너비 조정** | 열 경계 드래그로 너비 변경 | | **열 순서 변경** | 헤더 드래그로 순서 변경 | | **열 고정** | 스크롤 시 특정 열 고정 | | **행 높이 설정** | 소형/중형/대형 선택 | | **열 숨기기** | 특정 속성 숨김 처리 | 적합한 용도 [#적합한-용도] * ✅ 대량의 데이터 입력 및 편집 * ✅ 상세 정보 확인 및 비교 * ✅ 데이터 정렬 및 필터링 * ✅ CSV/Excel 내보내기 *** 칸반 (보드) 뷰 [#칸반-보드-뷰] **카드를 열로 그룹화**하여 표시합니다. 프로젝트 관리, 영업 파이프라인 등 상태 기반 워크플로우에 최적화되어 있습니다. 화면 구성 [#화면-구성-1] ``` ┌─────────────────────────────────────────────────────────────────┐ │ 📋 할 일 🔄 진행중 ✅ 완료 │ ├────────────────────┬────────────────────┬──────────────────────┤ │ ┌────────────────┐ │ ┌────────────────┐ │ ┌────────────────┐ │ │ │ 태스크 A │ │ │ 태스크 C │ │ │ 태스크 E │ │ │ │ 👤 김철수 │ │ │ 👤 이영희 │ │ │ 👤 박지민 │ │ │ │ 📅 1월 15일 │ │ │ 📅 1월 20일 │ │ │ 📅 1월 10일 │ │ │ └────────────────┘ │ └────────────────┘ │ └────────────────┘ │ │ ┌────────────────┐ │ ┌────────────────┐ │ │ │ │ 태스크 B │ │ │ 태스크 D │ │ │ │ │ 👤 최민수 │ │ │ 👤 정수진 │ │ │ │ │ 📅 1월 18일 │ │ │ 📅 1월 22일 │ │ │ │ └────────────────┘ │ └────────────────┘ │ │ └────────────────────┴────────────────────┴──────────────────────┘ ``` 특징 [#특징-1] | 기능 | 설명 | | ------------ | --------------------- | | **드래그 앤 드롭** | 카드를 다른 열로 드래그하여 상태 변경 | | **그룹화 기준** | 단일 선택 속성 기준으로 그룹화 | | **카드 속성 선택** | 카드에 표시할 속성 선택 | | **WIP 제한** | 열당 최대 카드 수 제한 (선택) | | **빈 그룹 숨기기** | 카드가 없는 열 숨김 | 설정 방법 [#설정-방법] 1. **그룹화 기준 선택**: 단일 선택 속성 중 하나 선택 (예: 상태) 2. **카드 표시 속성**: 카드에 보여줄 속성들 선택 3. **열 순서**: 옵션 순서대로 열 배치 적합한 용도 [#적합한-용도-1] * ✅ 프로젝트/태스크 관리 * ✅ 영업 파이프라인 * ✅ 컨텐츠 제작 워크플로우 * ✅ 채용 프로세스 * ✅ 버그 트래킹 *** 캘린더 뷰 [#캘린더-뷰] **날짜 속성을 기반**으로 캘린더에 표시합니다. 일정 관리와 마감일 추적에 최적화되어 있습니다. 화면 구성 [#화면-구성-2] ``` ┌─────────────────────────────────────────────────────────────────┐ │ ◀ 2024년 1월 ▶ 월 주 일 │ ├────────┬────────┬────────┬────────┬────────┬────────┬────────┤ │ 일 │ 월 │ 화 │ 수 │ 목 │ 금 │ 토 │ ├────────┼────────┼────────┼────────┼────────┼────────┼────────┤ │ │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ │ │ │ │ 태스크A│ │ │ │ ├────────┼────────┼────────┼────────┼────────┼────────┼────────┤ │ 7 │ 8 │ 9 │ 10 │ 11 │ 12 │ 13 │ │ │ 미팅 │ │ 마감일 │ │ 발표 │ │ ├────────┼────────┼────────┼────────┼────────┼────────┼────────┤ │ 14 │ 15 │ 16 │ 17 │ 18 │ 19 │ 20 │ │ │ 리뷰 │ │ │ 출시 │ │ │ └────────┴────────┴────────┴────────┴────────┴────────┴────────┘ ``` 특징 [#특징-2] | 기능 | 설명 | | -------------- | ---------------- | | **월간/주간/일간** | 세 가지 표시 모드 | | **드래그로 날짜 변경** | 이벤트를 드래그하여 날짜 수정 | | **기간 표시** | 시작일\~종료일 범위 시각화 | | **색상 구분** | 상태나 카테고리별 색상 표시 | 설정 방법 [#설정-방법-1] 1. **날짜 기준 속성**: 캘린더에 표시할 날짜 속성 선택 2. **종료일 속성** (선택): 기간 표시를 위한 종료일 3. **표시 속성**: 이벤트 카드에 보여줄 추가 정보 적합한 용도 [#적합한-용도-2] * ✅ 일정 및 이벤트 관리 * ✅ 마감일 추적 * ✅ 휴가/휴일 관리 * ✅ 콘텐츠 발행 일정 * ✅ 프로젝트 타임라인 *** 갤러리 뷰 [#갤러리-뷰] **카드 그리드 형태**로 시각적으로 표시합니다. 이미지가 포함된 데이터에 최적화되어 있습니다. 화면 구성 [#화면-구성-3] ``` ┌─────────────────────────────────────────────────────────────────┐ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ ┌──────────┐ │ │ ┌──────────┐ │ │ ┌──────────┐ │ │ │ │ │ 이미지 │ │ │ │ 이미지 │ │ │ │ 이미지 │ │ │ │ │ └──────────┘ │ │ └──────────┘ │ │ └──────────┘ │ │ │ │ 상품 A │ │ 상품 B │ │ 상품 C │ │ │ │ ₩25,000 │ │ ₩35,000 │ │ ₩45,000 │ │ │ │ 🏷️ 전자기기 │ │ 🏷️ 가구 │ │ 🏷️ 의류 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ ... │ │ ... │ │ ... │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` 특징 [#특징-3] | 기능 | 설명 | | ------------ | --------------------- | | **이미지 썸네일** | 파일 속성의 이미지를 카드 상단에 표시 | | **카드 크기 조정** | 소형/중형/대형 카드 크기 | | **그리드 열 수** | 한 행에 표시할 카드 수 조정 | | **카드 속성 선택** | 카드에 보여줄 속성 선택 | 설정 방법 [#설정-방법-2] 1. **커버 이미지**: 썸네일로 표시할 파일 속성 선택 2. **제목**: 카드 제목으로 표시할 속성 (기본: Title) 3. **표시 속성**: 카드 본문에 보여줄 속성들 적합한 용도 [#적합한-용도-3] * ✅ 제품 카탈로그 * ✅ 인물 디렉토리 (팀원, 고객) * ✅ 포트폴리오 * ✅ 부동산 매물 * ✅ 레시피 모음 *** 리스트 뷰 [#리스트-뷰] **간결한 목록 형태**로 표시합니다. 빠른 스캔과 간단한 작업에 최적화되어 있습니다. 화면 구성 [#화면-구성-4] ``` ┌─────────────────────────────────────────────────────────────────┐ │ ☐ 태스크 A │ 👤 김철수 │ 🔵 진행중 │ 📅 1월 15일 │ ├─────────────────────────────────────────────────────────────────┤ │ ☑ 태스크 B │ 👤 이영희 │ 🟢 완료 │ 📅 1월 10일 │ ├─────────────────────────────────────────────────────────────────┤ │ ☐ 태스크 C │ 👤 박지민 │ 🟡 대기 │ 📅 1월 20일 │ ├─────────────────────────────────────────────────────────────────┤ │ ☐ 태스크 D │ 👤 최민수 │ 🔵 진행중 │ 📅 1월 18일 │ └─────────────────────────────────────────────────────────────────┘ ``` 특징 [#특징-4] | 기능 | 설명 | | ----------- | ------------------- | | **체크박스 통합** | 체크박스 속성이 있으면 왼쪽에 표시 | | **한 줄 표시** | 각 행이 한 줄로 간결하게 표시 | | **빠른 스캔** | 많은 항목을 한눈에 파악 | | **인라인 편집** | 클릭하여 바로 편집 | 적합한 용도 [#적합한-용도-4] * ✅ 할 일 목록 * ✅ 읽기 목록 * ✅ 간단한 체크리스트 * ✅ 빠른 데이터 스캔 *** 공통 기능 [#공통-기능] 모든 뷰에서 공통으로 사용할 수 있는 기능입니다. 필터 [#필터] 조건에 맞는 데이터만 표시합니다. 필터 추가 [#필터-추가] 1. 뷰 상단의 **필터** 버튼 클릭 2. **+ 필터 추가** 클릭 3. 속성, 연산자, 값 선택 복합 필터 [#복합-필터] 여러 조건을 AND/OR로 조합할 수 있습니다. ``` (상태 = "진행중") AND (담당자 = "나") AND (마감일 < 오늘) ``` 필터 저장 [#필터-저장] 자주 사용하는 필터는 새 뷰로 저장하세요. 예를 들어: * "내 진행중 태스크" 뷰: `담당자 = 나 AND 상태 = 진행중` * "이번 주 마감" 뷰: `마감일 = 이번 주` * "높은 우선순위" 뷰: `우선순위 = 높음` *** 정렬 [#정렬] 특정 속성을 기준으로 정렬합니다. 정렬 방법 [#정렬-방법] 1. **속성 헤더 클릭**: 해당 속성으로 정렬 (클릭할 때마다 오름차순/내림차순 전환) 2. **정렬 버튼**: 다중 정렬 기준 설정 다중 정렬 [#다중-정렬] ``` 1순위: 우선순위 (내림차순) → 높음 > 중간 > 낮음 2순위: 마감일 (오름차순) → 가까운 날짜 먼저 3순위: 생성일 (오름차순) ``` *** 그룹화 [#그룹화] 특정 속성을 기준으로 데이터를 그룹화합니다. 그룹화 가능 속성 [#그룹화-가능-속성] * 단일 선택 * 다중 선택 * 사용자 * 날짜 (일/주/월) 그룹화 예시 [#그룹화-예시] | 기준 | 결과 | | ------ | ---------------- | | 상태 | 할 일, 진행중, 완료 그룹 | | 담당자 | 사용자별 그룹 | | 마감일(월) | 1월, 2월, 3월... 그룹 | *** 뷰 설정 [#뷰-설정] 표시 속성 선택 [#표시-속성-선택] 각 뷰에서 표시할 속성을 선택합니다. 1. 뷰 상단의 **속성** (또는 ⚙️) 버튼 클릭 2. 표시할 속성 체크 3. 드래그하여 순서 변경 뷰 이름 변경 [#뷰-이름-변경] 1. 뷰 탭을 더블클릭 2. 새 이름 입력 3. Enter로 확인 뷰 복제 [#뷰-복제] 1. 뷰 탭 우클릭 2. **뷰 복제** 선택 뷰 삭제 [#뷰-삭제] 1. 뷰 탭 우클릭 2. **뷰 삭제** 선택 <Callout type="warn"> 마지막 뷰는 삭제할 수 없습니다. 데이터모델에는 최소 하나의 뷰가 필요합니다. </Callout> *** 뷰 활용 팁 [#뷰-활용-팁] 업무별 뷰 구성 예시 [#업무별-뷰-구성-예시] **프로젝트 관리** ``` ├── 📊 전체 현황 (테이블) - 모든 데이터 입력/편집 ├── 📋 칸반 보드 (보드) - 상태별 진행 현황 ├── 📅 마감일 캘린더 (캘린더) - 마감일 기준 일정 ├── 🎯 내 태스크 (리스트) - 필터: 담당자=나 └── ⚡ 긴급 (리스트) - 필터: 우선순위=높음 ``` **영업 파이프라인** ``` ├── 🔍 전체 딜 (테이블) - 상세 정보 확인 ├── 📊 파이프라인 (보드) - 단계별 현황 (리드→미팅→협상→계약) ├── 📅 미팅 일정 (캘린더) - 다음 미팅 날짜 ├── 💰 이번 달 예상 (테이블) - 필터: 예상마감=이번달 └── 🏆 계약 완료 (갤러리) - 필터: 상태=계약완료 ``` *** 다음 단계 [#다음-단계] * [관계](/docs/datamodels/relations) - 데이터모델 간 연결하기 * [수식](/docs/datamodels/formulas) - 자동 계산 설정하기 * [워크플로우](/docs/workflows) - 데이터 변경 시 자동화 --- # 핵심 개념 (/docs/getting-started/concepts) > 슈츠의 핵심 개념과 용어를 이해해보세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Mermaid } from '@/components/docs/Mermaid'; 슈츠의 철학 [#슈츠의-철학] 슈츠는 **성장하는 팀을 위한 AI 기반 워크스페이스**입니다. 단순한 노코드 도구가 아니라, AI가 업무시스템 제작부터 운영, 자동화까지 함께하며 팀의 성장에 맞춰 진화합니다. 핵심 가치 [#핵심-가치] * **AI 네이티브**: 테일러 AI가 처음부터 함께하여 복잡한 업무시스템도 대화로 구축 * **유연한 데이터 구조**: 스프레드시트의 쉬움과 데이터베이스의 강력함을 동시에 * **실시간 협업**: 팀원들과 동시에 작업하며 변경 사항이 즉시 동기화 * **자동화**: 워크플로우로 반복 작업을 자동화하여 업무 효율 극대화 *** 개념 간의 관계 [#개념-간의-관계] <Mermaid chart={`flowchart TB subgraph WS["🏢 워크스페이스"] direction LR subgraph P["📄 페이지"] B1["블록"] B2["블록"] B1 ~~~ B2 end subgraph DM["🗃️ 데이터모델"] R1["행"] R2["행"] R1 ~~~ R2 end subgraph WF["⚡ 워크플로우"] A1["액션"] A2["액션"] A1 ~~~ A2 end DM -- "데이터 표시" --> P DM -- "트리거" --> WF WF -- "데이터 변경" --> DM end T["🤖 테일러 AI"] -- "생성/관리" --> WS style WS fill:#f1f5f9,stroke:#334155,stroke-width:2px style P fill:#e2e8f0,stroke:#475569,stroke-width:1px style DM fill:#e2e8f0,stroke:#475569,stroke-width:1px style WF fill:#e2e8f0,stroke:#475569,stroke-width:1px style T fill:#0f172a,stroke:#0f172a,color:#fff style B1 fill:#fff,stroke:#64748b style B2 fill:#fff,stroke:#64748b style R1 fill:#fff,stroke:#64748b style R2 fill:#fff,stroke:#64748b style A1 fill:#fff,stroke:#64748b style A2 fill:#fff,stroke:#64748b `} /> * **페이지**는 **블록**으로 구성되며, **데이터모델 뷰** 블록을 통해 데이터를 표시합니다 * **데이터모델**의 변경은 **워크플로우**의 트리거가 될 수 있습니다 * **워크플로우**는 **데이터모델**의 데이터를 생성/수정/삭제할 수 있습니다 * **테일러**는 이 모든 요소를 자연어로 생성하고 관리합니다 *** 워크스페이스 [#워크스페이스] **워크스페이스**는 팀이 함께 일하는 최상위 공간입니다. 모든 페이지, 데이터모델, 워크플로우, 멤버가 워크스페이스 안에 존재합니다. 워크스페이스의 특징 [#워크스페이스의-특징] | 특징 | 설명 | | ---------- | ---------------------------------- | | **독립된 환경** | 각 워크스페이스는 완전히 독립적으로 운영됩니다 | | **멤버 관리** | 워크스페이스별로 멤버를 초대하고 권한을 관리합니다 | | **공유 데이터** | 워크스페이스 내 모든 데이터모델과 페이지는 멤버들이 공유합니다 | | **설정 분리** | 설정, API 키, 연동 등이 워크스페이스 단위로 관리됩니다 | 워크스페이스 구조 [#워크스페이스-구조] ``` 워크스페이스 ├── 페이지 (콘텐츠와 UI) │ ├── 블록 (콘텐츠 단위) │ └── 데이터모델 뷰 ├── 데이터모델 (구조화된 데이터) │ ├── 속성 정의 │ └── 데이터 행 ├── 워크플로우 (자동화) │ ├── 트리거 │ └── 액션 └── 멤버 (사용자와 권한) ``` <Callout type="info"> 하나의 계정으로 여러 워크스페이스를 생성하거나 참여할 수 있습니다. 회사용, 개인용, 프로젝트용 등 용도에 맞게 분리하세요. </Callout> 홈 화면과 지표 [#홈-화면과-지표] 워크스페이스 홈 화면에서는 팀의 생산성을 한눈에 파악할 수 있는 **메트릭 바**가 제공됩니다. 자동화 시간, 워크플로우 실행 횟수, 효율 점수(Taylor Score) 등을 통해 팀의 자동화 활용도를 측정하고 개선점을 찾아보세요. → [워크스페이스 홈과 지표 알아보기](/docs/getting-started/workspace-home) *** 페이지 [#페이지] **페이지**는 콘텐츠를 담는 기본 단위입니다. 노션의 페이지와 유사하지만 데이터모델, 통계, 워크플로우 등을 활용해 더욱 동적인 대시보드를 구성할 수 있습니다. 페이지의 구성 요소 [#페이지의-구성-요소] * **제목**: 페이지를 식별하는 이름 * **아이콘**: 이모지 또는 커스텀 아이콘 * **커버**: 상단 배경 이미지 (선택) * **본문**: 블록들로 구성된 콘텐츠 영역 블록 기반 구조 [#블록-기반-구조] 페이지의 모든 내용은 **블록**으로 구성됩니다. 일반 에디터처럼 자유롭게 글을 작성해도 모든 본문이 블록 단위로 저장되므로, 언제든 블록을 재배치하거나 다른 페이지로 이동할 수 있습니다. 블록을 자유롭게 조합하여 다양한 용도의 페이지를 만들 수 있습니다: | 용도 | 구성 예시 | | ---------- | ---------------------------- | | **문서** | 텍스트, 제목, 목록, 이미지 블록 조합 | | **대시보드** | 데이터모델 뷰, 통계 블록, 차트 블록 조합 | | **데이터 상세** | 관련 데이터모델 뷰, 활동 기록, 코멘트 블록 조합 | 페이지 계층 구조 [#페이지-계층-구조] 페이지는 다른 페이지 안에 중첩될 수 있어 계층 구조를 만들 수 있습니다: ``` 📁 프로젝트 문서 ├── 📄 프로젝트 개요 ├── 📁 기획 │ ├── 📄 요구사항 정의 │ └── 📄 와이어프레임 └── 📁 개발 ├── 📄 API 설계 └── 📄 기술 스택 ``` *** 블록 [#블록] **블록**은 페이지를 구성하는 최소 단위입니다. 다양한 종류의 블록을 조합하여 풍부한 콘텐츠를 만들 수 있습니다. 블록 추가하기 [#블록-추가하기] 블록을 추가하는 방법은 두 가지입니다: 1. **슬래시 명령어**: 빈 줄에서 `/`를 입력하면 블록 메뉴가 나타납니다. 원하는 블록을 선택하세요. 2. **바로 작성**: 그냥 글을 작성하면 자동으로 텍스트 블록이 됩니다. Enter를 누르면 새 블록이 생성됩니다. <Callout type="tip"> `/제목`으로 제목 블록, `/표`로 테이블 블록, `/데이터`로 데이터모델 뷰 블록을 빠르게 추가할 수 있습니다. </Callout> 블록 카테고리 [#블록-카테고리] 텍스트 블록 [#텍스트-블록] 문서 작성을 위한 기본 블록들입니다. | 블록 | 설명 | | ------------ | --------------------- | | **텍스트** | 일반 단락 텍스트 | | **제목 1/2/3** | 세 단계의 제목 (H1, H2, H3) | | **불릿 리스트** | 순서 없는 목록 | | **번호 리스트** | 순서 있는 목록 | | **할 일 목록** | 체크박스가 있는 목록 | | **토글** | 접기/펼치기 가능한 토글 블록 | | **인용문** | 강조 인용 블록 | | **콜아웃** | 정보 강조 박스 | | **코드** | 문법 강조 지원 코드 블록 | | **구분선** | 수평 구분선 | 미디어 블록 [#미디어-블록] 시각적 콘텐츠를 삽입하는 블록들입니다. | 블록 | 설명 | | ----------- | --------------- | | **이미지** | 이미지 파일 또는 URL | | **YouTube** | YouTube 동영상 임베드 | | **비디오** | 동영상 콘텐츠 | 데이터 블록 [#데이터-블록] 구조화된 데이터를 표시하는 블록들입니다. | 블록 | 설명 | | ----------- | ---------------------------------- | | **데이터모델 뷰** | 데이터모델을 다양한 형태로 표시 (테이블, 보드, 캘린더 등) | | **통계 블록** | SQL 쿼리 결과를 테이블, 차트, 카드로 시각화 | | **테이블** | 간단한 정적 테이블 | | **수식** | LaTeX 수학 공식 (인라인/블록) | | **선택 처리** | 데이터를 선택하고 일괄 처리 (POS, 정산 등) | | **아티팩트** | HTML/CSS/JS로 만드는 커스텀 UI | 레이아웃 블록 [#레이아웃-블록] 콘텐츠 배치를 위한 블록들입니다. | 블록 | 설명 | | ---------- | ---------------------------- | | **컬럼** | 가로로 나란히 배치되는 컬럼 레이아웃 (2\~6개) | | **탭** | 탭으로 전환되는 콘텐츠 영역 | | **버튼** | 클릭 시 워크플로우를 실행하는 버튼 | | **페이지 링크** | 다른 페이지로 연결되는 링크 블록 | *** 데이터모델 [#데이터모델] **데이터모델**은 구조화된 데이터를 저장하고 관리하는 테이블입니다. 스프레드시트처럼 쉽게 사용하면서도 관계형 데이터베이스의 강력함을 갖추고 있습니다. 데이터모델의 구성 [#데이터모델의-구성] ``` 데이터모델: 고객 ├── 속성 (Properties) - 열(Column) 정의 │ ├── 회사명 (텍스트) │ ├── 담당자 (텍스트) │ ├── 이메일 (이메일) │ ├── 계약 상태 (선택) │ ├── 계약 금액 (통화) │ └── 담당 영업사원 (사용자) └── 행 (Rows) - 개별 데이터 ├── 고객 A ├── 고객 B └── 고객 C ``` 속성 타입 [#속성-타입] 슈츠는 17가지 속성 타입을 지원합니다 (시스템 속성 2개 포함 시 19가지): | 카테고리 | 속성 타입 | 설명 | | --------- | ------------------- | ------------------- | | **기본** | 제목(Title) | 행을 식별하는 필수 속성 | | | 텍스트(Text) | 일반 텍스트 입력 | | | 숫자(Number) | 정수, 소수점, 백분율 | | | 통화(Currency) | 금액 (원화, 달러 등) | | **선택** | 단일 선택(Select) | 미리 정의된 옵션 중 하나 선택 | | | 다중 선택(Multi-select) | 여러 옵션 선택 가능 | | **날짜/체크** | 날짜(Date) | 날짜 또는 날짜+시간 | | | 체크박스(Checkbox) | 예/아니오 값 | | **사용자** | 사람(Person) | 워크스페이스 멤버 선택 | | **미디어** | 파일(Files) | 파일 첨부 | | **연락처** | URL | 웹 링크 | | | 이메일(Email) | 이메일 주소 | | | 전화번호(Phone) | 전화번호 | | **관계** | 관계(Relation) | 다른 데이터모델과 연결 | | | 롤업(Rollup) | 관계된 데이터의 집계 값 | | **계산** | 수식(Formula) | 다른 속성 기반 자동 계산 | | **액션** | 액션(Actions) | 워크플로우 실행 버튼 | | **시스템** | 생성일(Created At) | 행 생성 일시 (자동, 읽기 전용) | | | 수정일(Updated At) | 행 수정 일시 (자동, 읽기 전용) | 뷰 [#뷰] 하나의 데이터모델을 다양한 방식으로 볼 수 있습니다: | 뷰 | 설명 | 적합한 용도 | | ---------- | -------------- | ---------------------- | | **테이블** | 스프레드시트 형태 | 데이터 입력/편집, 상세 정보 확인 | | **타일** | 콤팩트한 카드 그리드 형태 | 할 일 목록, 빠른 스캔, 제품 카탈로그 | | **보드(칸반)** | 카드를 열로 그룹화 | 프로젝트 관리, 영업 파이프라인 | | **캘린더** | 날짜 기반 일정 표시 | 일정 관리, 마감일 추적 | *** 워크플로우 [#워크플로우] **워크플로우**는 반복적인 작업을 자동화하는 기능입니다. 특정 조건(트리거)이 충족되면 정해진 작업(액션)을 자동으로 실행합니다. 워크플로우 구성 [#워크플로우-구성] ``` 워크플로우: 새 고객 알림 ├── 트리거: 고객 데이터모델에 새 행 생성 ├── 조건: 계약 금액 >= 1000만원 └── 액션 ├── 슬랙 채널에 메시지 전송 └── 담당자에게 이메일 발송 ``` 트리거 종류 [#트리거-종류] 기본 트리거 외에도 다양한 외부 서비스 트리거를 지원합니다: | 트리거 | 설명 | | ---------- | -------------------------------------- | | **수동** | 버튼 클릭으로 직접 실행 | | **일정** | 특정 시간에 정기적으로 실행 (매일, 매주, CRON) | | **데이터 변경** | 데이터모델 행 생성/수정/삭제 시 실행 | | **웹훅** | 외부에서 HTTP 요청 시 실행 | | **외부 서비스** | GitHub, Slack, Jira, ClickUp 등의 이벤트 감지 | 노드 (액션) [#노드-액션] 워크플로우는 다양한 **노드**를 연결하여 구성합니다. 슬랙, 이메일 같은 알림부터 OpenAI, Google Sheets 등 수십 종의 외부 서비스 연동 노드를 제공하며, 새로운 연동 노드가 지속적으로 추가되고 있습니다. | 카테고리 | 예시 노드 | | ---------- | ------------------------------------------------ | | **알림** | Slack, Email, Discord, 슈츠 내 알림 | | **AI** | OpenAI, Anthropic, AI Agent | | **데이터** | 행 생성/수정/삭제, HTTP 요청 | | **외부 연동** | Google Sheets, Notion, Airtable, GitHub, Asana 등 | | **국내 서비스** | 카페24, 아임웹, 네이버커머스, 볼타, 고위드 등 | | **제어** | 조건 분기, 반복, 병합, 필터, 코드 | <Callout type="info"> 전체 노드 목록과 상세 설정 방법은 [노드 레퍼런스](/docs/node-reference)에서 확인하세요. </Callout> *** 테일러 AI [#테일러-ai] **테일러**는 슈츠의 AI 에이전트입니다. 세계 최초의 경영 컨설턴트인 프레더릭 윈슬로 테일러(Frederick Winslow Taylor)의 이름을 따서, 당신의 업무 효율성을 극대화하는 AI 파트너가 되어드립니다. 테일러가 할 수 있는 일 [#테일러가-할-수-있는-일] | 기능 | 설명 | 도구 수 | | ------------ | ----------------------------- | ---- | | **블록 관리** | 페이지 콘텐츠 생성, 수정, 삭제, 검색, 부분 수정 | 6개 | | **데이터모델 관리** | 테이블 생성, 속성 정의, 데이터 CRUD | 10개 | | **통계 분석** | SQL 쿼리 작성, 데이터 시각화 | 8개 | | **워크플로우 설계** | 자동화 워크플로우 생성, 테스트, 배포 | 17개 | | **스킬 관리** | AI 스킬 생성 및 관리 | 5개 | | **검색 및 탐색** | 워크스페이스 내 정보 검색, 시맨틱 검색 | 2개 | | **워크스페이스** | 워크스페이스 요약, 알림 조회 | 2개 | | **웹 및 메모리** | 웹 검색/조회, 메모리 저장/검색 | 4개 | 테일러 호출 방법 [#테일러-호출-방법] * **단축키**: `Cmd/Ctrl + /` * **상단 메뉴**: 페이지 상단의 **Taylor AI** 버튼 클릭 * **사이드바**: 좌측 사이드바의 **Taylor AI** 메뉴 클릭 <Callout type="tip"> 테일러에게 구체적으로 요청할수록 더 정확한 결과를 얻을 수 있습니다. "CRM 만들어줘"보다 "B2B SaaS 영업팀을 위한 고객 관리 시스템을 만들어줘. 고객사, 담당자, 미팅기록을 관리하고 싶어."처럼 맥락을 제공하세요. </Callout> *** 다음 단계 [#다음-단계] 핵심 개념을 이해하셨다면, 다음 가이드로 넘어가세요: * [워크스페이스 설정](/docs/getting-started/workspace-setup) - 팀 환경 구성하기 * [데이터모델](/docs/datamodels) - 데이터 구조화 자세히 알아보기 * [Taylor AI](/docs/taylor-ai) - AI 기능 활용법 배우기 --- # 얼리액세스 (/docs/getting-started/early-access) > 슈츠 얼리액세스 프로그램에 대해 알아보세요 얼리액세스란? [#얼리액세스란] 슈츠는 현재 **얼리액세스** 단계로 운영되고 있습니다. 얼리액세스는 정식 출시 전 소수의 사용자에게 먼저 서비스를 제공하는 프로그램입니다. 얼리액세스 기간 동안 슈츠 팀은 사용자 피드백을 적극적으로 수집하여 더 나은 제품을 만들어가고 있습니다. 얼리액세스 신청 [#얼리액세스-신청] 현재 슈츠를 처음 사용하시는 분들은 **대기자 명단(Waitlist)** 등록 후 순차적으로 초대를 받으실 수 있습니다. 신청 방법 [#신청-방법] 1. [슈츠 홈페이지](https://suits.work)에서 **시작하기** 버튼을 클릭합니다 2. 이메일 주소와 간단한 정보를 입력합니다 3. 신청이 완료되면 순차적으로 초대 링크가 발송됩니다 <Callout type="info"> 신청자가 많을 경우 초대까지 다소 시간이 소요될 수 있습니다. 양해 부탁드립니다. </Callout> 얼리액세스 혜택 [#얼리액세스-혜택] 얼리액세스 사용자에게는 다음과 같은 혜택이 제공됩니다: | 혜택 | 설명 | | --------- | --------------------- | | 무료 이용 | 얼리액세스 기간 동안 모든 기능 무료 | | 우선 지원 | Slack 커뮤니티를 통한 빠른 피드백 | | 신기능 우선 체험 | 새로운 기능을 가장 먼저 사용 | | 의견 반영 | 제품 방향에 직접 의견 제안 가능 | Slack 커뮤니티 [#slack-커뮤니티] 얼리액세스 사용자는 [슈츠 Slack 커뮤니티](https://join.slack.com/t/suits-community/shared_invite/zt-3mx9of0jq-M9mO4wO5l5_mO4o~1sYgLQ)에 참여하실 수 있습니다. 커뮤니티에서는: * 사용 중 궁금한 점을 질문할 수 있습니다 * 버그나 개선 사항을 제보할 수 있습니다 * 다른 사용자들과 활용 사례를 공유할 수 있습니다 * 슈츠 팀의 업데이트 소식을 가장 먼저 받아볼 수 있습니다 자주 묻는 질문 [#자주-묻는-질문] 초대는 언제 받을 수 있나요? [#초대는-언제-받을-수-있나요] 신청 순서대로 순차적으로 초대드리고 있습니다. 신청자가 많아 정확한 일정을 안내드리기 어려운 점 양해 부탁드립니다. 얼리액세스 기간은 언제까지인가요? [#얼리액세스-기간은-언제까지인가요] 정식 출시 일정은 아직 미정입니다. 얼리액세스 종료 시 충분한 사전 안내를 드릴 예정입니다. 얼리액세스 이후 데이터는 유지되나요? [#얼리액세스-이후-데이터는-유지되나요] 네, 얼리액세스 기간에 만든 워크스페이스와 데이터는 정식 출시 후에도 그대로 유지됩니다. 팀원을 초대할 수 있나요? [#팀원을-초대할-수-있나요] 네, 워크스페이스를 만든 후 팀원을 초대할 수 있습니다. 초대받은 팀원도 별도의 얼리액세스 승인 없이 바로 사용 가능합니다. --- # 데이터 Import (/docs/getting-started/import) > 외부 서비스의 데이터를 워크스페이스로 가져오는 Import 기능을 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Steps, Step } from 'fumadocs-ui/components/steps'; Import 기능이란 [#import-기능이란] Import는 외부 서비스에 저장된 데이터를 슈츠 워크스페이스의 데이터모델로 한 번에 가져오는 기능입니다. 커머스 플랫폼의 주문/상품 데이터, 이메일 데이터 등을 별도의 워크플로우 설계 없이 클릭 몇 번으로 가져올 수 있습니다. Import는 내부적으로 워크플로우를 자동 생성하고 실행하는 방식으로 동작합니다. 사용자는 복잡한 파이프라인을 직접 구성할 필요 없이, 미리 정의된 **Import 레시피**를 선택하기만 하면 됩니다. *** 지원 소스 및 레시피 [#지원-소스-및-레시피] Import는 현재 다음 서비스를 지원합니다. 각 서비스별로 가져올 수 있는 데이터 종류(레시피)가 사전 정의되어 있습니다. 카페24 [#카페24] | 레시피 | 설명 | | -------- | ------------------------ | | **상품** | 카페24 쇼핑몰의 전체 상품을 가져옵니다 | | **주문** | 카페24 쇼핑몰의 전체 주문을 가져옵니다 | | **고객** | 카페24 쇼핑몰의 전체 고객을 가져옵니다 | | **카테고리** | 카페24 쇼핑몰의 전체 카테고리를 가져옵니다 | | **쿠폰** | 카페24 쇼핑몰의 전체 쿠폰을 가져옵니다 | | **브랜드** | 카페24 쇼핑몰의 전체 브랜드를 가져옵니다 | | **공급사** | 카페24 쇼핑몰의 전체 공급사를 가져옵니다 | | **리뷰** | 카페24 쇼핑몰의 전체 리뷰를 가져옵니다 | 네이버 커머스 (스마트스토어) [#네이버-커머스-스마트스토어] | 레시피 | 설명 | | ------- | ------------------------------- | | **주문** | 최근 90일간의 주문을 가져옵니다 (24시간 단위 조회) | | **상품** | 전체 상품을 가져옵니다 | | **클레임** | 취소/반품/교환 클레임을 가져옵니다 | <Callout type="info"> 네이버 커머스의 주문 조회는 API 특성상 최대 24시간 단위로만 조회할 수 있습니다. Import 시 자동으로 90일을 24시간 단위로 분할하여 순차 조회합니다. </Callout> Gmail [#gmail] | 레시피 | 설명 | | ------- | ---------------------- | | **메시지** | 최근 500건의 이메일을 가져옵니다 | | **스레드** | 최근 500건의 대화 스레드를 가져옵니다 | | **라벨** | 모든 Gmail 라벨을 가져옵니다 | *** Import 레시피란 [#import-레시피란] Import 레시피는 특정 서비스의 특정 데이터를 가져오기 위해 미리 정의된 파이프라인 템플릿입니다. 레시피에는 다음 정보가 포함됩니다. * **소스 서비스**: 어떤 외부 서비스에서 가져올지 (카페24, 네이버 커머스, Gmail) * **데이터 종류**: 어떤 리소스를 가져올지 (상품, 주문, 메시지 등) * **파이프라인 구조**: 데이터를 조회하고 데이터모델에 저장하는 워크플로우 노드 구성 레시피를 선택하면 슈츠가 자동으로 워크플로우를 생성하고 실행합니다. 사용자가 직접 워크플로우를 설계할 필요가 없습니다. *** Import 실행 방법 [#import-실행-방법] 워크스페이스 홈에서 진입 [#워크스페이스-홈에서-진입] <Steps> <Step> 워크스페이스 홈으로 이동 [#워크스페이스-홈으로-이동] 워크스페이스 홈 화면 하단에 **데이터 Import** 섹션이 표시됩니다. 이 섹션에는 Import 레시피가 등록된 서비스가 카드 형태로 나열됩니다. </Step> <Step> 인증 상태 확인 [#인증-상태-확인] 각 서비스 카드 하단에 인증 상태가 표시됩니다. | 상태 | 의미 | | -------------- | ---------------- | | **연결됨** (초록) | 인증 완료, Import 가능 | | **미확인** (주황) | 인증 정보가 있으나 테스트 전 | | **인증 오류** (빨강) | 인증 정보가 유효하지 않음 | | **인증 필요** (빨강) | 인증 정보가 등록되지 않음 | <Callout type="warn"> 인증 상태가 **인증 필요** 또는 **인증 오류**인 경우, 먼저 [워크스페이스 설정](/docs/getting-started/workspace-setup)에서 해당 서비스의 인증 정보를 등록해야 합니다. </Callout> </Step> <Step> 서비스 카드 클릭 [#서비스-카드-클릭] Import할 서비스 카드를 클릭하면 Import 대화상자가 열립니다. </Step> <Step> 레시피 선택 [#레시피-선택] 대화상자에 해당 서비스의 모든 레시피가 체크박스와 함께 표시됩니다. 기본적으로 모든 레시피가 선택되어 있습니다. 필요 없는 레시피의 체크를 해제하세요. </Step> <Step> Import 시작 [#import-시작] **Import 시작 (N개)** 버튼을 클릭하면 선택한 레시피가 순차적으로 실행됩니다. </Step> </Steps> *** 다중 레시피 순차 실행 [#다중-레시피-순차-실행] 여러 레시피를 동시에 선택하면 순차적으로 하나씩 실행됩니다. 예를 들어, 카페24에서 상품, 주문, 고객을 동시에 선택하면 상품 Import가 완료된 후 주문 Import가 시작되고, 주문이 완료되면 고객 Import가 시작됩니다. 진행 중에는 현재 몇 번째 레시피가 실행 중인지 표시됩니다 (예: "2/3 레시피 실행 중: 주문"). *** 진행률 확인 [#진행률-확인] Import 실행 중에는 대화상자에서 실시간 진행 상황을 확인할 수 있습니다. | 표시 정보 | 설명 | | ---------- | -------------------------------------------- | | **진행 바** | 현재 레시피의 처리 진행률을 시각적으로 표시 | | **처리 건수** | 현재까지 처리된 항목 수와 전체 항목 수 (예: 150/500 처리 중) | | **레시피 진행** | 다중 레시피 실행 시 전체 레시피 중 현재 순번 (예: 2/3 레시피 실행 중) | Import가 완료되면 완료 메시지가 표시됩니다. 오류가 발생한 경우 오류 메시지와 함께 **다시 시도** 버튼이 제공됩니다. *** Import 카드 Dismiss (숨기기) [#import-카드-dismiss-숨기기] 워크스페이스 홈의 Import 섹션에서 이미 Import를 완료했거나 사용하지 않을 서비스 카드를 숨길 수 있습니다. * 서비스 카드에 마우스를 올리면 우측 상단에 닫기(X) 버튼이 나타납니다 * 닫기 버튼을 클릭하면 해당 서비스 카드가 Import 섹션에서 사라집니다 * 숨김 상태는 워크스페이스별로 브라우저에 저장되므로, 다른 브라우저에서는 다시 표시됩니다 <Callout type="info"> 모든 서비스 카드를 dismiss하면 Import 섹션 자체가 워크스페이스 홈에서 사라집니다. </Callout> *** Import 파이프라인 구조 [#import-파이프라인-구조] Import는 내부적으로 다음과 같은 워크플로우 파이프라인을 자동 생성합니다. 서비스별로 구조가 다릅니다. 카페24 (getCount 지원 리소스) [#카페24-getcount-지원-리소스] 수동 실행 → 건수 조회(getCount) → 페이지 배열 생성(Code) → 목록 조회(eachItem) → 데이터모델 저장 총 건수를 먼저 조회한 뒤 필요한 페이지 수를 계산하여 정확한 범위만 조회합니다. 카페24 (getCount 미지원 리소스: 리뷰) [#카페24-getcount-미지원-리소스-리뷰] 수동 실행 → 페이지 배열 생성(Code, 고정 페이지) → 목록 조회(eachItem) → 데이터모델 저장 getCount API가 없는 리소스는 고정된 최대 페이지 수(20페이지)만큼 조회합니다. 네이버 커머스 (주문) [#네이버-커머스-주문] 수동 실행 → 24시간 슬롯 생성(Code, 90일분) → 주문 상세 조회(eachItem) → 데이터모델 저장 주문 API의 24시간 조회 제한으로 인해 90일을 1일 단위(90개 슬롯)로 분할하여 순차 조회합니다. 네이버 커머스 (상품, 클레임) [#네이버-커머스-상품-클레임] 수동 실행 → 페이지 배열 생성(Code, 고정 50페이지) → 목록 조회(eachItem) → 데이터모델 저장 Gmail [#gmail-1] 수동 실행 → 데이터 조회(getAll, 최대 500건) → 데이터모델 저장 Gmail API는 한 번에 최대 건수까지 반환하므로 별도의 페이지네이션이 필요 없습니다. *** 과거 데이터 일괄 가져오기 [#과거-데이터-일괄-가져오기] Import 기능은 서비스를 처음 연동할 때 기존에 축적된 데이터를 한 번에 가져오는 용도로 설계되었습니다. * **카페24**: 쇼핑몰에 등록된 전체 데이터를 가져옵니다 (상품, 주문, 고객 등) * **네이버 커머스**: 주문은 최근 90일, 상품과 클레임은 전체 데이터를 가져옵니다 * **Gmail**: 최근 500건의 메시지/스레드를 가져옵니다 <Callout type="tip"> Import는 일회성 대량 가져오기에 적합합니다. 이후 실시간으로 신규 데이터를 지속 동기화하려면 워크플로우의 트리거(웹훅, 스케줄 등)를 활용하세요. </Callout> *** 주의 사항 [#주의-사항] * Import를 실행하려면 해당 서비스의 \*\*인증 정보(Credential)\*\*가 워크스페이스에 등록되어 있어야 합니다 * Import가 진행되는 동안 대화상자를 닫지 마세요. 진행 상황 추적이 중단될 수 있습니다 * 대량 데이터 Import 시 소요 시간이 길어질 수 있습니다. 네이버 커머스 주문의 경우 90일분 데이터를 순차 조회하므로 수 분이 소요될 수 있습니다 * Import 완료 후 가져온 데이터는 데이터모델에 자동 저장됩니다. 데이터모델 목록에서 확인할 수 있습니다 *** 다음 단계 [#다음-단계] Import를 완료했다면: * [마이그레이션 가이드](/docs/getting-started/migration) - 다른 도구에서 데이터 옮기기 * [워크플로우](/docs/workflows) - 가져온 데이터를 활용한 자동화 구축 * [데이터모델](/docs/data-models) - Import된 데이터 관리 및 활용 --- # 마이그레이션 가이드 (/docs/getting-started/migration) > 기존 도구에서 Suits로 데이터를 옮기는 방법을 안내합니다. 데이터 가져오기 [#데이터-가져오기] Notion에서 가져오기 [#notion에서-가져오기] Notion에서 Suits로 데이터를 가져오는 방법입니다. <Callout> 현재 Notion 임포터는 준비 중입니다. 아래는 수동 마이그레이션 방법입니다. </Callout> 1단계: Notion 데이터 내보내기 [#1단계-notion-데이터-내보내기] 1. Notion 워크스페이스 설정으로 이동합니다. 2. **Settings & Members** → **Settings** → **Export all workspace content**를 클릭합니다. 3. **Markdown & CSV** 형식으로 내보내기합니다. 2단계: Suits에서 데이터 구조 설계 [#2단계-suits에서-데이터-구조-설계] 1. Suits에서 새 워크스페이스를 생성합니다. 2. Notion 데이터베이스에 해당하는 **데이터모델**을 생성합니다. 3. 필요한 속성(프로퍼티)을 정의합니다. 3단계: 데이터 입력 [#3단계-데이터-입력] 현재는 수동으로 데이터를 입력하거나, CSV 가져오기 기능을 사용할 수 있습니다. *** 스프레드시트에서 가져오기 [#스프레드시트에서-가져오기] Google Sheets, Excel 등 스프레드시트에서 데이터를 가져옵니다. 1단계: 스프레드시트 준비 [#1단계-스프레드시트-준비] 1. 첫 번째 행에 열 제목(속성 이름)이 있는지 확인합니다. 2. 데이터를 정리하고 빈 셀을 처리합니다. 3. CSV 형식으로 내보내기합니다. 2단계: Suits 데이터모델 생성 [#2단계-suits-데이터모델-생성] 1. 워크스페이스에서 새 데이터모델을 생성합니다. 2. 스프레드시트 열에 맞게 속성을 정의합니다. * 텍스트, 숫자, 날짜 등 적절한 타입을 선택합니다. * 관계(Relation)가 필요한 경우 먼저 관련 데이터모델을 생성합니다. 3단계: CSV 가져오기 [#3단계-csv-가져오기] 1. 데이터모델 상단의 **가져오기** 버튼을 클릭합니다. 2. CSV 파일을 업로드합니다. 3. 열과 속성을 매핑합니다. 4. 가져오기를 실행합니다. *** Jira에서 가져오기 [#jira에서-가져오기] <Callout> Jira 임포터는 준비 중입니다. 현재는 CSV 내보내기를 통한 수동 마이그레이션을 권장합니다. </Callout> 1단계: Jira 데이터 내보내기 [#1단계-jira-데이터-내보내기] 1. Jira에서 프로젝트 설정으로 이동합니다. 2. **Export** → **Export to CSV**를 선택합니다. 3. 필요한 필드를 선택하고 내보내기합니다. 2단계: Suits에서 워크플로우 설계 [#2단계-suits에서-워크플로우-설계] Jira의 이슈 타입과 워크플로우를 Suits에서 재현합니다: 1. **데이터모델** 생성: 이슈, 에픽, 스프린트 등 2. **상태 속성** 정의: To Do, In Progress, Done 등 3. **워크플로우** 설계: 상태 변경 시 자동화 *** 새로 시작하기 [#새로-시작하기] 마이그레이션 대신 새로 시작하는 것도 좋은 선택입니다. 새로 시작하면 좋은 경우 [#새로-시작하면-좋은-경우] * 기존 데이터가 정리되지 않았거나 오래된 경우 * 새로운 업무 방식을 도입하려는 경우 * 팀 구조가 변경된 경우 새로 시작하는 방법 [#새로-시작하는-방법] 1. **핵심 데이터만 수동 입력**: 진행 중인 프로젝트, 활성 고객 등 2. **테일러 AI 활용**: "고객 관리 시스템 만들어줘"처럼 대화로 시스템 구축 3. **점진적 확장**: 작게 시작해서 필요에 따라 확장 *** 마이그레이션 체크리스트 [#마이그레이션-체크리스트] 마이그레이션 전후로 확인할 사항입니다. 마이그레이션 전 [#마이그레이션-전] * [ ] 기존 데이터 백업 완료 * [ ] 필요한 데이터 범위 결정 * [ ] Suits 워크스페이스 생성 * [ ] 데이터모델 구조 설계 * [ ] 팀에 마이그레이션 일정 공유 마이그레이션 중 [#마이그레이션-중] * [ ] 데이터모델별 속성 정의 * [ ] 데이터 가져오기 실행 * [ ] 관계(Relation) 연결 * [ ] 워크플로우 설정 마이그레이션 후 [#마이그레이션-후] * [ ] 데이터 정합성 확인 * [ ] 팀원 초대 및 권한 설정 * [ ] 기존 도구 읽기 전용으로 전환 * [ ] 팀 교육 및 온보딩 *** 도움이 필요하신가요? [#도움이-필요하신가요] 마이그레이션 과정에서 도움이 필요하시면: * **문서**: 각 기능별 상세 가이드를 참고하세요. * **테일러 AI**: 워크스페이스에서 테일러에게 질문하세요. * **지원팀**: [support@suits.work](mailto:support@suits.work)로 문의해 주세요. <Callout type="info"> 대규모 마이그레이션이나 엔터프라이즈 고객의 경우, 전담 마이그레이션 지원을 제공합니다. 영업팀에 문의해 주세요. </Callout> --- # 빠른 시작 (/docs/getting-started/quick-start) > 5분 안에 슈츠의 핵심 기능을 경험해보세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Steps, Step } from 'fumadocs-ui/components/steps'; 시작하기 전에 [#시작하기-전에] 슈츠를 시작하려면 계정이 필요합니다. 현재 슈츠는 [얼리액세스](/docs/getting-started/early-access) 단계로 운영되고 있으며, [suits.work](https://suits.work)에서 대기자 등록 후 초대를 받으실 수 있습니다. <Callout type="info"> 얼리액세스 기간 동안 모든 기능을 무료로 사용할 수 있습니다. </Callout> *** 1단계: 워크스페이스 생성 [#1단계-워크스페이스-생성] <Steps> <Step> 로그인하기 [#로그인하기] 슈츠에 로그인하면 워크스페이스 선택 화면이 나타납니다. </Step> <Step> 새 워크스페이스 만들기 [#새-워크스페이스-만들기] **+ 새 워크스페이스** 버튼을 클릭합니다. 워크스페이스 이름과 아이콘을 설정할 수 있습니다. * **워크스페이스 이름**: 팀이나 프로젝트를 구분할 수 있는 이름 (예: "마케팅팀", "프로덕트 개발") * **아이콘**: 이모지나 이미지로 워크스페이스를 시각적으로 구분 </Step> <Step> 워크스페이스 진입 [#워크스페이스-진입] 생성이 완료되면 자동으로 워크스페이스로 이동합니다. 빈 워크스페이스와 왼쪽 사이드바가 보입니다. </Step> </Steps> *** 2단계: 첫 페이지 만들기 [#2단계-첫-페이지-만들기] 페이지는 슈츠에서 콘텐츠를 담는 기본 단위입니다. <Steps> <Step> 페이지 생성 [#페이지-생성] 다음 방법 중 하나로 새 페이지를 만들 수 있습니다: * 사이드바에서 **+ 새 페이지** 버튼 클릭 * 키보드 단축키 `Cmd/Ctrl + N` 사용 * 사이드바의 빈 영역 우클릭 후 "새 페이지" </Step> <Step> 페이지 제목 입력 [#페이지-제목-입력] 새 페이지가 열리면 "제목 없음"이라고 표시됩니다. 클릭하여 원하는 제목을 입력하세요. </Step> <Step> 아이콘과 커버 추가 (선택) [#아이콘과-커버-추가-선택] 페이지 제목 위에 마우스를 올리면 **아이콘 추가**와 **커버 추가** 옵션이 나타납니다. * **아이콘**: 이모지를 선택하여 페이지를 시각적으로 구분 * **커버**: 배경 이미지로 페이지를 꾸밀 수 있음 </Step> </Steps> *** 3단계: 블록 추가하기 [#3단계-블록-추가하기] 슈츠의 모든 콘텐츠는 **블록** 단위로 구성됩니다. 슬래시 명령어(`/`)로 다양한 블록을 추가할 수 있습니다. <Steps> <Step> 슬래시 명령어 사용 [#슬래시-명령어-사용] 페이지 본문에서 `/`를 입력하면 블록 메뉴가 나타납니다. </Step> <Step> 블록 선택 [#블록-선택] 원하는 블록 타입을 클릭하거나 이름을 입력해서 검색할 수 있습니다: | 블록 타입 | 슬래시 명령어 | 설명 | | ----------- | ----------------------- | ------------------ | | **제목 1** | `/h1` 또는 `/heading` | 가장 큰 제목 | | **제목 2** | `/h2` | 중간 크기 제목 | | **제목 3** | `/h3` | 작은 제목 | | **글머리 기호** | `/bullet` | 순서 없는 목록 | | **번호 목록** | `/number` 또는 `/ordered` | 순서 있는 목록 | | **할 일** | `/todo` 또는 `/task` | 체크박스가 있는 목록 | | **토글** | `/toggle` | 접기/펼치기 가능한 블록 | | **인용구** | `/quote` | 강조 인용 블록 | | **코드 블록** | `/code` | 문법 강조 코드 블록 | | **구분선** | `/divider` 또는 `/hr` | 수평 구분선 | | **이미지** | `/image` | 이미지 삽입 | | **표** | `/table` | 정적 테이블 | | **YouTube** | `/youtube` | YouTube 동영상 임베드 | | **수식** | `/math` 또는 `/latex` | LaTeX 수학 공식 | | **버튼** | `/button` | 클릭 가능한 버튼 | | **데이터모델** | `/datamodel` 또는 `/data` | 데이터 테이블 삽입 | | **통계 블록** | `/stat` 또는 `/chart` | 차트/그래프 시각화 | | **아티팩트** | `/artifact` 또는 `/html` | 커스텀 HTML/CSS/JS UI | | **선택 처리** | `/select` 또는 `/pos` | 데이터 선택 일괄 처리 | | **탭** | `/tab` | 탭 전환 콘텐츠 | | **컬럼** | `/column` | 2\~6개 컬럼 레이아웃 | </Step> <Step> 블록 편집 [#블록-편집] 블록을 클릭하여 내용을 편집합니다. 텍스트 선택 시 서식 도구 모음이 나타납니다: * **굵게**: `Cmd/Ctrl + B` * **기울임**: `Cmd/Ctrl + I` * **밑줄**: `Cmd/Ctrl + U` * **링크 추가**: `Cmd/Ctrl + K` </Step> </Steps> <Callout type="tip"> 마크다운 문법도 지원됩니다. `# `으로 제목을, `- `으로 불릿 리스트를 바로 만들 수 있습니다. </Callout> *** 4단계: 테일러에게 도움 요청하기 [#4단계-테일러에게-도움-요청하기] **테일러**는 슈츠의 AI 에이전트입니다. 자연어로 요청하면 데이터모델, 페이지, 워크플로우를 자동으로 생성해드립니다. <Steps> <Step> 테일러 호출 [#테일러-호출] 다음 방법 중 하나로 테일러를 호출할 수 있습니다: * 페이지 상단의 **Taylor AI** 버튼 클릭 * 사이드바의 **Taylor AI** 메뉴 클릭 * 키보드 단축키 `Cmd/Ctrl + /` </Step> <Step> 첫 번째 요청 보내기 [#첫-번째-요청-보내기] 테일러에게 자연어로 요청해보세요. 예를 들어: ``` 프로젝트 관리 시스템을 만들어줘 ``` </Step> <Step> 결과 확인 [#결과-확인] 테일러가 요청을 분석하고 다음을 자동으로 생성합니다: * **데이터모델**: 프로젝트, 태스크, 마일스톤 등의 테이블 * **페이지**: 데이터를 보여주는 대시보드 페이지 * **속성 설정**: 상태, 담당자, 마감일 등의 필드 생성된 내용을 확인하고 필요에 따라 수정할 수 있습니다. </Step> </Steps> *** 5단계: 데이터 추가하기 [#5단계-데이터-추가하기] 테일러가 만든 데이터모델에 실제 데이터를 추가해봅시다. <Steps> <Step> 데이터모델 열기 [#데이터모델-열기] 사이드바에서 생성된 데이터모델을 클릭하거나, 페이지 내 데이터모델 블록을 클릭합니다. </Step> <Step> 새 행 추가 [#새-행-추가] 테이블 하단의 **+ 새 항목** 버튼을 클릭하거나 마지막 행에서 `Enter`를 누릅니다. </Step> <Step> 데이터 입력 [#데이터-입력] 각 셀을 클릭하여 데이터를 입력합니다. 속성 타입에 따라 입력 방식이 다릅니다: * **텍스트**: 직접 입력 * **선택**: 드롭다운에서 선택 * **날짜**: 달력에서 선택 * **담당자**: 워크스페이스 멤버 선택 </Step> </Steps> *** 빠른 단축키 모음 [#빠른-단축키-모음] 효율적인 작업을 위한 핵심 단축키입니다: | 동작 | Mac | Windows | | ------ | --------- | ---------- | | 새 페이지 | `Cmd + N` | `Ctrl + N` | | 테일러 호출 | `Cmd + /` | `Ctrl + /` | | 블록 메뉴 | `/` | `/` | | 검색 | `Cmd + P` | `Ctrl + P` | | 굵게 | `Cmd + B` | `Ctrl + B` | | 기울임 | `Cmd + I` | `Ctrl + I` | | 블록 복제 | `Cmd + D` | `Ctrl + D` | | 실행 취소 | `Cmd + Z` | `Ctrl + Z` | *** 다음 단계 [#다음-단계] 축하합니다! 슈츠의 기본 기능을 경험하셨습니다. 다음 가이드를 통해 더 깊이 알아보세요: * [핵심 개념](/docs/getting-started/concepts) - 슈츠의 핵심 개념과 용어 이해하기 * [워크스페이스 설정](/docs/getting-started/workspace-setup) - 팀에 맞게 환경 구성하기 * [Taylor AI](/docs/taylor-ai) - AI 기능 자세히 알아보기 * [데이터모델](/docs/datamodels) - 데이터 구조화 방법 배우기 <Callout type="tip"> **도움이 필요하신가요?** 언제든 테일러에게 물어보세요. 테일러는 슈츠 사용법부터 복잡한 업무시스템 설계까지 도와드립니다. </Callout> --- # 워크스페이스 홈 (/docs/getting-started/workspace-home) > 워크스페이스 홈 화면과 효율 지표를 이해해보세요. import { Callout } from 'fumadocs-ui/components/callout'; 워크스페이스 홈 개요 [#워크스페이스-홈-개요] 워크스페이스 홈은 슈츠에 접속했을 때 가장 먼저 보이는 화면입니다. 팀의 현재 상태를 한눈에 파악하고, 테일러 AI와 대화를 시작할 수 있는 중심 공간입니다. 홈 화면 구성 [#홈-화면-구성] | 영역 | 설명 | | ----------- | ----------------------------------------------------------------------------------- | | **메트릭 바** | 상단에 위치한 핵심 지표 표시 영역 | | **센터 대시보드** | 테일러 AI와 대화하며 작업을 수행하는 메인 영역. 온보딩 카드(데이터 테이블 만들기, 대시보드 구축, 워크플로우 자동화)와 대화 메시지가 표시됩니다 | *** 메트릭 바 [#메트릭-바] 메트릭 바는 워크스페이스의 핵심 지표를 실시간으로 보여줍니다. 팀의 자동화 활용도, 콘텐츠 생산량, 효율성을 한눈에 확인할 수 있습니다. 표시 가능한 지표 [#표시-가능한-지표] | 지표 | 설명 | 카테고리 | | ---------- | ------------------------------- | ---- | | **자동화 시간** | 이번 주 워크플로우가 자동으로 처리한 총 시간 | 자동화 | | **자동화 실행** | 이번 주 워크플로우 실행 횟수 | 자동화 | | **콘텐츠** | 워크스페이스의 총 콘텐츠 수 (블록 + 데이터 셀) | 콘텐츠 | | **사용일수** | 워크스페이스 생성 후 경과 일수 | 콘텐츠 | | **멤버** | 현재 워크스페이스의 활성 멤버 수 | 팀 | | **효율 점수** | 자동화 중심 효율성 종합 지표 (Taylor Score) | 점수 | | **생산량 점수** | 콘텐츠 생산 중심 종합 지표 | 점수 | 메트릭 커스터마이징 [#메트릭-커스터마이징] 메트릭 바에 표시할 지표를 선택할 수 있습니다: 1. 메트릭 바 상단의 **설정** 아이콘을 클릭합니다 2. 표시할 지표를 선택/해제합니다 3. 드래그하여 순서를 변경합니다 <Callout type="tip"> 팀의 목표에 맞는 지표를 선택하세요. 자동화 도입 초기라면 **자동화 시간**과 **자동화 실행**을, 콘텐츠 중심 팀이라면 **콘텐츠**와 **생산량 점수**를 표시하는 것이 좋습니다. </Callout> *** 효율 점수 (Taylor Score) [#효율-점수-taylor-score] **효율 점수**는 워크스페이스의 자동화 활용도를 종합적으로 평가하는 지표입니다. 프레더릭 윈슬로 테일러(Frederick Winslow Taylor)의 과학적 관리법에서 영감을 받아, 팀이 얼마나 효율적으로 자동화를 활용하고 있는지를 0\~99점으로 나타냅니다. 점수 구성 요소 [#점수-구성-요소] | 요소 | 비중 | 설명 | | -------------- | :-: | -------------------------- | | **1인당 자동화 시간** | 30% | 멤버당 자동화가 처리한 시간 | | **1인당 실행 수** | 30% | 멤버당 워크플로우 실행 횟수 | | **성공률** | 25% | 워크플로우 실행 성공 비율 | | **활용 일관성** | 15% | 이번 주 워크플로우를 사용한 일수 (7일 기준) | 점수 해석 [#점수-해석] | 점수 범위 | 의미 | | ----- | ----------------------------- | | 0-20 | 자동화 시작 단계. 첫 번째 워크플로우를 만들어보세요 | | 21-40 | 자동화 도입 중. 반복 작업을 찾아 자동화해보세요 | | 41-60 | 활발한 활용. 더 복잡한 워크플로우에 도전해보세요 | | 61-80 | 숙련된 활용. 팀 전체로 자동화를 확산해보세요 | | 81-99 | 최적화 단계. 자동화 마스터입니다! | <Callout type="info"> 최고점은 99점입니다. 완벽은 없다는 철학을 담아, 항상 개선의 여지를 남겨둡니다. </Callout> 티어 시스템 [#티어-시스템] 효율 점수에 따라 **8단계 티어**가 부여됩니다. 각 티어는 산업 발전 단계를 상징하며, 워크스페이스의 자동화 성숙도를 직관적으로 보여줍니다. <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4 my-6"> <div className="flex items-center gap-3 p-4 rounded-lg border bg-card"> <div className="flex-shrink-0"> <TaylorTierIcon score={5} size="lg" /> </div> <div className="flex flex-col"> <span className="font-semibold"> Stone </span> <span className="text-xs text-muted-foreground"> 0-13점 </span> <span className="text-xs text-muted-foreground mt-1"> 돌 시대 - 모든 것이 수동인 시작점 </span> </div> </div> <div className="flex items-center gap-3 p-4 rounded-lg border bg-card"> <div className="flex-shrink-0"> <TaylorTierIcon score={20} size="lg" /> </div> <div className="flex flex-col"> <span className="font-semibold"> Bronze </span> <span className="text-xs text-muted-foreground"> 14-27점 </span> <span className="text-xs text-muted-foreground mt-1"> 청동기 - 첫 번째 도구를 사용하기 시작 </span> </div> </div> <div className="flex items-center gap-3 p-4 rounded-lg border bg-card"> <div className="flex-shrink-0"> <TaylorTierIcon score={35} size="lg" /> </div> <div className="flex flex-col"> <span className="font-semibold"> Silver </span> <span className="text-xs text-muted-foreground"> 28-41점 </span> <span className="text-xs text-muted-foreground mt-1"> 은 시대 - 체계적인 시스템 구축 중 </span> </div> </div> <div className="flex items-center gap-3 p-4 rounded-lg border bg-card"> <div className="flex-shrink-0"> <TaylorTierIcon score={48} size="lg" /> </div> <div className="flex flex-col"> <span className="font-semibold"> Gold </span> <span className="text-xs text-muted-foreground"> 42-55점 </span> <span className="text-xs text-muted-foreground mt-1"> 금 시대 - 안정적인 자동화 운영 </span> </div> </div> <div className="flex items-center gap-3 p-4 rounded-lg border bg-card"> <div className="flex-shrink-0"> <TaylorTierIcon score={62} size="lg" /> </div> <div className="flex flex-col"> <span className="font-semibold"> Diamond </span> <span className="text-xs text-muted-foreground"> 56-69점 </span> <span className="text-xs text-muted-foreground mt-1"> 다이아몬드 - 세련된 자동화 활용 </span> </div> </div> <div className="flex items-center gap-3 p-4 rounded-lg border bg-card"> <div className="flex-shrink-0"> <TaylorTierIcon score={76} size="lg" /> </div> <div className="flex flex-col"> <span className="font-semibold"> Mechanic </span> <span className="text-xs text-muted-foreground"> 70-82점 </span> <span className="text-xs text-muted-foreground mt-1"> 기계화 시대 - 산업혁명 수준의 효율 </span> </div> </div> <div className="flex items-center gap-3 p-4 rounded-lg border bg-card"> <div className="flex-shrink-0"> <TaylorTierIcon score={89} size="lg" /> </div> <div className="flex flex-col"> <span className="font-semibold"> Digital </span> <span className="text-xs text-muted-foreground"> 83-95점 </span> <span className="text-xs text-muted-foreground mt-1"> 디지털 시대 - 고도화된 자동화 체계 </span> </div> </div> <div className="flex items-center gap-3 p-4 rounded-lg border bg-card"> <div className="flex-shrink-0"> <TaylorTierIcon score={97} size="lg" /> </div> <div className="flex flex-col"> <span className="font-semibold"> Transcendent </span> <span className="text-xs text-muted-foreground"> 96-99점 </span> <span className="text-xs text-muted-foreground mt-1"> 초월 - 자동화의 정점, AI 네이티브 </span> </div> </div> </div> 티어가 올라갈수록 아이콘에 더 화려한 글로우 효과가 적용됩니다. <Callout type="tip"> 팀원들과 함께 다음 티어 달성을 목표로 삼아보세요. 게이미피케이션 요소가 자동화 도입의 동기부여가 될 수 있습니다. </Callout> *** 생산량 점수 [#생산량-점수] **생산량 점수**는 워크스페이스의 콘텐츠 생산성을 측정하는 지표입니다. 팀이 얼마나 활발하게 콘텐츠를 만들고 있는지를 0\~99점으로 나타냅니다. 점수 구성 요소 [#점수-구성-요소-1] | 요소 | 비중 | 설명 | | ----------- | :-: | -------------------- | | **1인당 콘텐츠** | 50% | 멤버당 생성한 블록 + 데이터 셀 수 | | **사용 기간** | 30% | 워크스페이스를 사용한 총 일수 | | **활용 일관성** | 20% | 이번 주 활동한 일수 (7일 기준) | 효율 점수와의 차이 [#효율-점수와의-차이] | 구분 | 효율 점수 | 생산량 점수 | | --------- | ---------------- | ------------- | | **초점** | 자동화 활용도 | 콘텐츠 생산량 | | **주요 지표** | 워크플로우 실행, 자동화 시간 | 블록 수, 데이터 셀 수 | | **적합한 팀** | 자동화 중심 팀 | 문서/데이터 중심 팀 | *** 지표 활용 팁 [#지표-활용-팁] 팀 목표 설정 [#팀-목표-설정] * **신규 팀**: 먼저 콘텐츠를 충분히 만들어 생산량 점수를 올리세요 * **성장 팀**: 반복 작업을 찾아 자동화하여 효율 점수를 올리세요 * **성숙 팀**: 두 점수의 균형을 맞추며 지속적으로 최적화하세요 주간 리뷰 [#주간-리뷰] 매주 메트릭 변화를 확인하며 팀의 진행 상황을 점검하세요: 1. 자동화 시간이 늘었는가? 2. 워크플로우 성공률은 유지되는가? 3. 팀원들이 꾸준히 활용하고 있는가? *** 다음 단계 [#다음-단계] 워크스페이스 홈을 이해했다면: * [워크스페이스 설정](/docs/getting-started/workspace-setup) - 팀에 맞게 설정하기 * [워크플로우](/docs/workflows) - 첫 번째 자동화 만들기 * [Taylor AI](/docs/taylor-ai) - AI와 함께 업무 효율 높이기 --- # 워크스페이스 오버뷰 (/docs/getting-started/workspace-overview) > 워크스페이스의 모든 엔티티와 관계를 한눈에 파악하는 오버뷰 화면을 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; 워크스페이스 오버뷰란 [#워크스페이스-오버뷰란] 워크스페이스 오버뷰는 워크스페이스에 존재하는 \*\*모든 엔티티(워크플로우, 노드 타입, 데이터모델, 통계, 페이지)\*\*와 그들 간의 **관계**를 한눈에 파악할 수 있는 전체 조감도입니다. 엔티티 수가 늘어나면 전체 구조를 파악하기 어려워집니다. 오버뷰는 이 문제를 해결하기 위해 모든 엔티티를 유형별 컬럼으로 정렬하고, Canvas 위에 관계 연결선을 그려 시각적으로 보여줍니다. *** 5컬럼 엔티티 오버뷰 [#5컬럼-엔티티-오버뷰] 오버뷰는 5개의 컬럼으로 구성되어 워크스페이스의 엔티티를 유형별로 분류합니다. | 컬럼 | 엔티티 | 크기 | 설명 | | --------- | ------------ | -- | ----------------------- | | **워크플로우** | 자동화 워크플로우 | 넓음 | 활성/초안 상태 표시, 참조 데이터모델 수 | | **노드 타입** | 사용된 워크플로우 노드 | 좁음 | 카테고리별 그룹핑, 사용 횟수 표시 | | **데이터모델** | 데이터 테이블 | 넓음 | 아이콘, 연결 수 표시 | | **통계** | 통계 정의 | 좁음 | 실행 모드 표시 | | **페이지** | 문서 페이지 | 넓음 | 아이콘, 연결 수 표시 | <Callout type="info"> 엔티티 총 수가 10개 미만인 경우 **콤팩트 레이아웃**(3컬럼)이 적용되며, 노드 타입과 통계 컬럼이 숨겨집니다. </Callout> 컬럼 정렬 [#컬럼-정렬] 각 컬럼의 제목을 클릭하면 정렬 모드가 순환됩니다. | 정렬 모드 | 설명 | | ------------- | ----------------------------- | | **기본 정렬** | 연결 수 기준 내림차순 (관계가 많은 엔티티가 상단) | | **이름 오름차순** | 가나다순 | | **이름 내림차순** | 역순 | | **순서** (페이지만) | 페이지 트리 순서대로 | Canvas 연결선 [#canvas-연결선] 카드에 마우스를 올리면 해당 엔티티와 연결된 모든 엔티티가 **Canvas 연결선**으로 시각화됩니다. 연결된 엔티티는 하이라이트되고, 관련 없는 엔티티는 흐려집니다. | 연결 타입 | 의미 | 선 스타일 | | --------------- | --------------------- | ------ | | **embed** | 페이지에 데이터모델이 임베드됨 | 실선 | | **relation** | 데이터모델 간 관계 속성 연결 | 점선 | | **automation** | 워크플로우가 데이터모델을 참조 | 짧은 점선 | | **integration** | 워크플로우가 노드 타입을 사용 | 가는 실선 | | **invocation** | 워크플로우 간 호출 관계 | 짧은 점선 | | **source** | 통계가 페이지/데이터모델을 소스로 사용 | 중간 점선 | | **agent** | 프로액티브 에이전트의 트리거 대상 | 보라색 점선 | *** 엔티티 카드 [#엔티티-카드] 각 엔티티는 카드 형태로 표시되며, 타입별로 고유한 색상 코딩이 적용됩니다. | 타입 | 색상 | 추가 정보 | | --------- | --- | ---------------------------- | | **워크플로우** | 주황색 | 활성 상태 도트 (초록: 활성, 노란: 초안) | | **노드 타입** | 보라색 | 사용 중인 워크플로우 수, Credential 상태 | | **데이터모델** | 남색 | 연결된 엔티티 수 | | **통계** | 청록색 | 실행 모드 | | **페이지** | 보라색 | 연결된 엔티티 수 | 카드 상호작용 [#카드-상호작용] * **마우스 오버** - Canvas 연결선 표시 + 호버 프리뷰 팝업 * **클릭** - 해당 엔티티로 이동 (데스크톱 앱: 새 탭, 웹: 새 창) * **노드 타입 클릭** - Credential이 필요한 노드라면 Credential 연결 모달 표시 *** Credential 상태 인디케이터 [#credential-상태-인디케이터] 워크플로우에서 사용하는 외부 서비스(Google, Slack, OpenAI 등)의 인증 상태를 노드 타입 카드에서 바로 확인할 수 있습니다. | 상태 | 표시 | 의미 | | ------------ | ------- | ----------------------- | | **valid** | 표시 없음 | 정상 연결됨 | | **untested** | 노란색 글로우 | Credential은 있지만 검증되지 않음 | | **missing** | 빨간색 글로우 | Credential이 등록되지 않음 | | **invalid** | 빨간색 글로우 | 인증 실패, 재연결 필요 | 오버뷰 헤더 우측에는 **인증 필요** 카운터가 표시되어, 문제가 있는 노드 타입의 수를 한눈에 확인할 수 있습니다. <Callout type="warn"> Credential 문제가 있는 노드 타입이 포함된 워크플로우는 정상적으로 실행되지 않을 수 있습니다. 빨간색 글로우가 보이면 해당 카드를 클릭하여 Credential을 연결하세요. </Callout> *** Credential 일괄 연결 모달 [#credential-일괄-연결-모달] 노드 타입 카드를 클릭하면 해당 서비스의 **Credential 연결 관리 모달**이 열립니다. 이 모달에서 여러 워크플로우에 걸쳐 사용되는 동일 서비스의 Credential을 한 번에 관리할 수 있습니다. 모달 구성 [#모달-구성] | 영역 | 설명 | | ------------------ | ----------------------------------------------------- | | **좌측 패널 - 저장된 연결** | 워크스페이스에 등록된 Credential 목록, 새 연결 추가 (OAuth 또는 API Key) | | **우측 패널 - 노드 목록** | 해당 서비스를 사용하는 워크플로우별 노드 목록, 전체 선택/개별 선택 | 사용 방법 [#사용-방법] 1. 좌측에서 사용할 **Credential을 선택**합니다 2. 우측에서 적용할 **노드를 체크**합니다 (전체 선택 가능) 3. **저장** 버튼으로 선택한 Credential을 선택한 노드에 일괄 적용합니다 <Callout type="tip"> 새로운 외부 서비스를 처음 연결할 때, 오버뷰에서 해당 노드 타입을 클릭하면 OAuth 연결부터 전체 워크플로우 적용까지 한 곳에서 처리할 수 있습니다. </Callout> *** 호버 프리뷰 [#호버-프리뷰] 엔티티 카드에 마우스를 올리면 **플로팅 프리뷰 팝업**이 카드 위에 표시됩니다. 프리뷰에 표시되는 정보 [#프리뷰에-표시되는-정보] | 정보 | 설명 | | ----------------- | ----------------------------- | | **아이콘 + 이름** | 엔티티의 아이콘과 전체 이름 | | **타입 레이블** | 워크플로우, 데이터모델, 페이지, 노드 타입, 통계 | | **메타 정보** | 상태, 참조 DM 수, 카테고리 등 타입별 부가 정보 | | **Credential 상태** | 노드 타입의 경우 인증 문제 메시지 표시 | | **연결 요약** | 연결된 엔티티 수와 연결 타입별 개수 | <Callout type="info"> 에이전트 카드에는 호버 프리뷰가 표시되지 않으며, 연결선만 표시됩니다. 에이전트의 상세 정보는 클릭 시 나타나는 메시지 팝오버에서 확인할 수 있습니다. </Callout> *** 데이터 Import 섹션 [#데이터-import-섹션] 오버뷰 하단에 **데이터 Import** 섹션이 표시됩니다. 워크스페이스에서 사용 중인 외부 서비스 중 Import가 지원되는 서비스를 카드로 보여주며, Credential 연결 상태도 함께 표시합니다. | 상태 | 표시 | | --------- | ------ | | **연결됨** | 초록색 도트 | | **미확인** | 노란색 도트 | | **인증 오류** | 빨간색 도트 | | **인증 필요** | 빨간색 도트 | 서비스 카드를 클릭하면 Import 다이얼로그가 열려 해당 서비스의 데이터를 워크스페이스로 가져올 수 있습니다. 각 카드의 닫기 버튼으로 불필요한 카드를 숨길 수 있으며, 이 설정은 로컬에 저장됩니다. *** AI 에이전트 섹션 [#ai-에이전트-섹션] 오버뷰 하단에 워크스페이스에 등록된 **프로액티브 AI 에이전트** 목록이 표시됩니다. 각 에이전트는 아바타, 뱃지, 이름, 역할과 함께 원형 카드로 표시됩니다. 에이전트 카드 기능 [#에이전트-카드-기능] * **마우스 오버** - 연결된 리소스(트리거 대상)와의 Canvas 연결선 표시 (보라색 점선) * **클릭** - 최근 분석 메시지를 보여주는 팝오버 표시 * **설정 아이콘** - 에이전트 설정 다이얼로그 열기 * **추가 버튼** - 새 커스텀 에이전트 생성 에이전트가 특정 데이터모델, 통계, 워크플로우를 트리거 필터로 지정한 경우, 마우스 오버 시 해당 리소스와의 연결선이 Canvas에 표시됩니다. <Callout type="info"> 에이전트에 대한 자세한 내용은 [프로액티브 AI 인사이트](/docs/taylor-ai/proactive-insights) 문서를 참고하세요. </Callout> *** 오버뷰 헤더 [#오버뷰-헤더] 화면 상단에 워크스페이스 이름과 함께 전체 현황 정보가 표시됩니다. | 정보 | 설명 | | ------------- | ---------------------------------- | | **워크스페이스 이름** | 현재 워크스페이스 이름 | | **인증 필요 카운터** | Credential 문제가 있는 노드 타입 수 (빨간색 뱃지) | | **엔티티 수** | 워크플로우 + 데이터모델 + 페이지 + 통계의 총 수 | | **새로고침 버튼** | 관계 데이터와 Credential 상태를 다시 불러옴 | *** 데이터 소스 [#데이터-소스] 오버뷰의 데이터는 여러 소스에서 실시간으로 수집됩니다. | 데이터 | 소스 | 특성 | | --------------------- | --------------------------- | --------------------------------------------- | | **페이지, 데이터모델, 워크플로우** | YDoc (Yjs) | 실시간 동기화, 엔티티 수 변경 시 관계도 자동 갱신 | | **통계 정의** | React Query API | 캐싱 + 주기적 갱신 | | **엔티티 간 관계** | workspace-relationships API | 1분 stale time, 엔티티 수 변경 시 자동 갱신, 윈도우 포커스 시 갱신 | | **Credential 상태** | credentials API | 1분 stale time, 윈도우 포커스 시 갱신 | | **프로액티브 에이전트** | proactive-agents API | React Query 기반 | *** 다음 단계 [#다음-단계] * [워크스페이스 설정](/docs/getting-started/workspace-setup) - 팀에 맞게 워크스페이스 설정하기 * [프로액티브 AI 인사이트](/docs/taylor-ai/proactive-insights) - AI 에이전트 자동 분석 * [Taylor AI](/docs/taylor-ai) - AI와 함께 업무 효율 높이기 --- # 워크스페이스 설정 (/docs/getting-started/workspace-setup) > 팀에 맞게 워크스페이스를 설정하세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Steps, Step } from 'fumadocs-ui/components/steps'; 워크스페이스 설정 접근하기 [#워크스페이스-설정-접근하기] 워크스페이스 설정은 다음 경로로 접근할 수 있습니다: <Steps> <Step> 사이드바에서 접근 [#사이드바에서-접근] 사이드바 상단의 **워크스페이스 이름**을 클릭합니다. </Step> <Step> 설정 메뉴 선택 [#설정-메뉴-선택] 드롭다운 메뉴에서 **설정**을 선택합니다. </Step> </Steps> *** 기본 설정 [#기본-설정] 워크스페이스 정보 [#워크스페이스-정보] 워크스페이스의 기본 정보를 설정합니다. | 항목 | 설명 | | ------- | --------------------- | | **이름** | 워크스페이스를 식별하는 이름 | | **아이콘** | 이모지 또는 업로드 이미지 | | **설명** | 워크스페이스 용도에 대한 설명 (선택) | 워크스페이스 이름 변경 [#워크스페이스-이름-변경] <Steps> <Step> 워크스페이스 설정 → **일반** 탭으로 이동합니다. </Step> <Step> **워크스페이스 이름** 필드에서 새 이름을 입력합니다. </Step> <Step> **저장** 버튼을 클릭합니다. </Step> </Steps> 워크스페이스 아이콘 변경 [#워크스페이스-아이콘-변경] <Steps> <Step> 현재 아이콘을 클릭합니다. </Step> <Step> 이모지를 선택하거나 **이미지 업로드**를 클릭하여 커스텀 이미지를 사용합니다. </Step> </Steps> <Callout type="tip"> 팀이나 프로젝트를 구분하기 쉽도록 의미 있는 아이콘을 선택하세요. 예: 마케팅팀은 📣, 개발팀은 💻 </Callout> *** 멤버 관리 [#멤버-관리] 워크스페이스에 팀원을 초대하고 역할을 관리합니다. 멤버 초대하기 [#멤버-초대하기] <Steps> <Step> 멤버 관리 페이지 접근 [#멤버-관리-페이지-접근] 설정 → **멤버** 탭으로 이동합니다. </Step> <Step> 초대 버튼 클릭 [#초대-버튼-클릭] **멤버 초대** 버튼을 클릭합니다. </Step> <Step> 이메일 입력 [#이메일-입력] 초대할 사람의 이메일 주소를 입력합니다. 여러 명을 동시에 초대하려면 쉼표로 구분합니다. </Step> <Step> 역할 선택 [#역할-선택] 초대할 멤버의 역할을 선택합니다: | 역할 | 권한 | | -------------- | ------------------------- | | **관리자(Admin)** | 대부분의 권한 (설정 변경, 멤버 관리 포함) | | **멤버(Member)** | 콘텐츠 생성 및 수정 (설정 변경 불가) | | **게스트(Guest)** | 초대받은 페이지만 접근 가능 | </Step> <Step> 초대 발송 [#초대-발송] **초대 보내기** 버튼을 클릭합니다. 초대받은 사람은 이메일로 초대 링크를 받습니다. </Step> </Steps> 역할별 권한 상세 [#역할별-권한-상세] | 기능 | 소유자(Owner) | 관리자(Admin) | 멤버(Member) | 게스트(Guest) | | ------------ | :--------: | :--------: | :--------: | :-----------: | | 콘텐츠 보기 | ✅ | ✅ | ✅ | ✅ (초대받은 페이지만) | | 페이지/블록 편집 | ✅ | ✅ | ✅ | ❌ | | 데이터 생성/수정 | ✅ | ✅ | ✅ | ❌ | | 워크플로우 관리 | ✅ | ✅ | ✅ | ❌ | | 멤버 초대 | ✅ | ✅ | ❌ | ❌ | | 멤버 역할 변경 | ✅ | ✅ | ❌ | ❌ | | 워크스페이스 설정 변경 | ✅ | ✅ | ❌ | ❌ | | 결제/플랜 관리 | ✅ | ❌ | ❌ | ❌ | | 워크스페이스 삭제 | ✅ | ❌ | ❌ | ❌ | 멤버 역할 변경 [#멤버-역할-변경] <Steps> <Step> 멤버 목록에서 변경할 멤버를 찾습니다. </Step> <Step> 멤버 우측의 **역할** 드롭다운을 클릭합니다. </Step> <Step> 새 역할을 선택합니다. </Step> </Steps> 멤버 제거 [#멤버-제거] <Steps> <Step> 멤버 목록에서 제거할 멤버를 찾습니다. </Step> <Step> 멤버 우측의 **더 보기(⋯)** 버튼을 클릭합니다. </Step> <Step> **멤버 제거**를 선택합니다. </Step> <Step> 확인 대화상자에서 **제거**를 클릭합니다. </Step> </Steps> <Callout type="warn"> 멤버를 제거하면 해당 멤버는 더 이상 워크스페이스에 접근할 수 없습니다. 단, 멤버가 생성한 콘텐츠는 삭제되지 않습니다. </Callout> *** 게스트 초대 [#게스트-초대] 워크스페이스 멤버가 아닌 외부 사용자를 특정 페이지에만 초대할 수 있습니다. 게스트와 멤버의 차이 [#게스트와-멤버의-차이] | 구분 | 멤버 | 게스트 | | --------- | ---------- | ---------------- | | **접근 범위** | 전체 워크스페이스 | 초대받은 페이지만 | | **역할** | 관리자/편집자/뷰어 | 보기/편집 | | **사이드바** | 전체 표시 | 초대받은 페이지만 표시 | | **요금** | 플랜에 따라 과금 | 별도 과금 없음 (제한 있음) | 게스트 초대 방법 [#게스트-초대-방법] <Steps> <Step> 공유할 페이지로 이동합니다. </Step> <Step> 페이지 우측 상단의 **공유** 버튼을 클릭합니다. </Step> <Step> **게스트 초대** 탭을 선택합니다. </Step> <Step> 이메일 주소를 입력하고 권한(보기/편집)을 선택합니다. </Step> <Step> **초대 보내기**를 클릭합니다. </Step> </Steps> *** 고급 설정 [#고급-설정] 슬러그 설정 [#슬러그-설정] 워크스페이스 URL의 슬러그를 설정합니다. ``` https://suits.work/{워크스페이스-슬러그}/... ``` <Callout type="info"> 슬러그는 영문, 숫자, 하이픈(-)만 사용할 수 있으며, 고유해야 합니다. </Callout> 기본 권한 설정 [#기본-권한-설정] 새로 생성되는 페이지와 데이터모델의 기본 공개 범위를 설정합니다. | 옵션 | 설명 | | ------------- | --------------------- | | **워크스페이스 전체** | 모든 멤버가 접근 가능 (기본값) | | **제한됨** | 생성자만 접근 가능, 명시적 공유 필요 | *** 개발자 설정 [#개발자-설정] 외부 연동을 위한 API 키와 웹훅을 관리합니다. API 키 관리 [#api-키-관리] <Steps> <Step> 설정 → **개발자** 탭 → **API 키**로 이동합니다. </Step> <Step> **새 API 키 생성** 버튼을 클릭합니다. </Step> <Step> 키 이름을 입력합니다 (예: "프로덕션 서버", "테스트용"). </Step> <Step> 권한 범위를 선택합니다: * **read**: 데이터 읽기만 * **write**: 데이터 읽기/쓰기 * **admin**: 전체 권한 </Step> <Step> **생성**을 클릭하고 키를 안전하게 저장합니다. </Step> </Steps> <Callout type="warn"> **보안 주의**: API 키는 생성 시에만 전체 키를 확인할 수 있습니다. 키를 분실하면 새로 생성해야 합니다. 키가 노출되었다면 즉시 폐기하고 새로 발급받으세요. </Callout> 웹훅 설정 [#웹훅-설정] 외부 시스템에서 슈츠 이벤트를 수신할 수 있습니다. <Steps> <Step> 설정 → **개발자** 탭 → **웹훅**으로 이동합니다. </Step> <Step> **새 웹훅 추가** 버튼을 클릭합니다. </Step> <Step> 다음 정보를 입력합니다: * **URL**: 이벤트를 수신할 엔드포인트 * **이벤트**: 구독할 이벤트 유형 (row\.created, row\.updated 등) </Step> <Step> **저장**을 클릭합니다. </Step> </Steps> *** 연동 설정 [#연동-설정] 외부 서비스와의 연동을 설정합니다. 슬랙 연동 [#슬랙-연동] <Steps> <Step> 설정 → **연동** 탭 → **슬랙**으로 이동합니다. </Step> <Step> **슬랙과 연결** 버튼을 클릭합니다. </Step> <Step> 슬랙 인증 화면에서 워크스페이스를 선택하고 권한을 승인합니다. </Step> <Step> 연결이 완료되면 워크플로우에서 슬랙 알림을 보낼 수 있습니다. </Step> </Steps> 지원되는 연동 [#지원되는-연동] | 서비스 | 용도 | | ----------------- | ------------- | | **Slack** | 알림 전송, 메시지 수신 | | **Google Sheets** | 데이터 내보내기/가져오기 | | **Notion** | 페이지 동기화 | | **GitHub** | 이슈/PR 연동 | | **Jira** | 이슈 연동 | *** 플랜 및 결제 [#플랜-및-결제] 플랜 비교 [#플랜-비교] | 기능 | Free | Pro | Business | Enterprise | | -------- | :---: | :-----: | :------: | :--------: | | 멤버 수 | 5명 | 무제한 | 무제한 | 무제한 | | 게스트 수 | 3명 | 10명 | 무제한 | 무제한 | | 데이터모델 | 5개 | 무제한 | 무제한 | 무제한 | | 워크플로우 실행 | 100/월 | 1,000/월 | 10,000/월 | 무제한 | | API 요청 | 100/분 | 1,000/분 | 10,000/분 | 무제한 | | 파일 저장 | 1GB | 10GB | 100GB | 무제한 | | 커스텀 도메인 | ❌ | ❌ | ✅ | ✅ | | SSO | ❌ | ❌ | ❌ | ✅ | | 전용 지원 | ❌ | ❌ | ❌ | ✅ | 플랜 변경 [#플랜-변경] <Steps> <Step> 설정 → **플랜 및 결제** 탭으로 이동합니다. </Step> <Step> 원하는 플랜의 **업그레이드** 버튼을 클릭합니다. </Step> <Step> 결제 정보를 입력하고 완료합니다. </Step> </Steps> *** 워크스페이스 내보내기 [#워크스페이스-내보내기] 워크스페이스 데이터를 백업하거나 다른 도구로 마이그레이션할 수 있습니다. 내보내기 형식 [#내보내기-형식] | 형식 | 포함 내용 | | ------------ | ---------------------- | | **JSON** | 전체 데이터 구조 (API 호환) | | **CSV** | 데이터모델 데이터만 (스프레드시트 호환) | | **Markdown** | 페이지 콘텐츠만 (문서 호환) | 내보내기 방법 [#내보내기-방법] <Steps> <Step> 설정 → **일반** 탭 → **데이터 내보내기**로 이동합니다. </Step> <Step> 내보낼 형식과 범위를 선택합니다. </Step> <Step> **내보내기**를 클릭하고 파일을 다운로드합니다. </Step> </Steps> *** 워크스페이스 삭제 [#워크스페이스-삭제] <Callout type="error"> **주의**: 워크스페이스 삭제는 되돌릴 수 없습니다. 모든 페이지, 데이터모델, 워크플로우, 파일이 영구 삭제됩니다. </Callout> <Steps> <Step> 설정 → **일반** 탭 하단의 **위험 영역**으로 이동합니다. </Step> <Step> **워크스페이스 삭제** 버튼을 클릭합니다. </Step> <Step> 확인을 위해 워크스페이스 이름을 입력합니다. </Step> <Step> **영구 삭제**를 클릭합니다. </Step> </Steps> *** 다음 단계 [#다음-단계] 워크스페이스 설정이 완료되었다면: * [마이그레이션 가이드](/docs/getting-started/migration) - 기존 도구에서 데이터 옮기기 * [권한 관리](/docs/collaboration/permissions) - 세밀한 권한 설정 방법 * [API 레퍼런스](/docs/api-reference) - 외부 연동 개발하기 --- # 법적 고지 (/docs/legal) > Suits 서비스 이용에 관한 법적 고지사항입니다. import { Card, Cards } from 'fumadocs-ui/components/card'; 법적 고지 [#법적-고지] Suits 서비스 이용과 관련된 정책 문서입니다. <Cards> <Card title="이용약관" description="서비스 이용에 관한 기본 약관" href="/docs/legal/terms" /> <Card title="개인정보처리방침" description="개인정보 수집 및 이용에 관한 정책" href="/docs/legal/privacy" /> </Cards> --- # 개인정보처리방침 (/docs/legal/privacy) > Suits 서비스 개인정보처리방침 제1조 (수집하는 개인정보 항목) [#제1조-수집하는-개인정보-항목] 회사는 서비스 제공을 위해 다음과 같은 개인정보를 수집합니다. 1. 필수 수집 항목 [#1-필수-수집-항목] | 구분 | 수집 항목 | | ------ | ------------------------------ | | 회원가입 | 이메일 주소, 비밀번호, 이름(닉네임) | | 서비스 이용 | 서비스 이용 기록, 접속 로그, IP 주소, 기기 정보 | | 결제 | 결제 수단 정보, 결제 내역 | 2. 선택 수집 항목 [#2-선택-수집-항목] * 프로필 사진 * 회사/팀 정보 * 연락처 3. 자동 수집 항목 [#3-자동-수집-항목] * 서비스 이용 기록, 접속 로그 * 쿠키, 방문 기록 * 기기 정보 (OS, 브라우저 종류) 제2조 (개인정보의 수집 및 이용 목적) [#제2조-개인정보의-수집-및-이용-목적] 회사는 수집한 개인정보를 다음의 목적으로 이용합니다. | 목적 | 상세 내용 | | -------- | ------------------------------ | | 서비스 제공 | 회원 식별, 서비스 제공, 맞춤형 서비스 제공 | | 회원 관리 | 회원제 서비스 이용, 본인 확인, 부정 이용 방지 | | 마케팅 | 신규 서비스 안내, 이벤트 정보 제공 (선택 동의 시) | | 서비스 개선 | 서비스 이용 통계, 서비스 품질 개선 | | 법적 의무 이행 | 관련 법령에 따른 의무 이행 | 제3조 (개인정보의 보유 및 이용 기간) [#제3조-개인정보의-보유-및-이용-기간] 회사는 개인정보 수집 및 이용 목적이 달성된 후에는 해당 정보를 지체 없이 파기합니다. 다만, 관련 법령에 따라 보존이 필요한 경우 아래와 같이 보관합니다. | 보존 항목 | 보존 기간 | 근거 법령 | | ----------------- | ----- | ------- | | 계약 또는 청약철회 기록 | 5년 | 전자상거래법 | | 대금결제 및 재화 공급 기록 | 5년 | 전자상거래법 | | 소비자 불만 또는 분쟁처리 기록 | 3년 | 전자상거래법 | | 접속 기록 | 3개월 | 통신비밀보호법 | 제4조 (개인정보의 제3자 제공) [#제4조-개인정보의-제3자-제공] 회사는 이용자의 동의 없이 개인정보를 제3자에게 제공하지 않습니다. 다만, 다음의 경우는 예외로 합니다. 1. 이용자가 사전에 동의한 경우 2. 법령에 의해 요구되는 경우 3. 서비스 제공을 위해 필요한 경우로서 위탁 계약을 체결한 경우 제5조 (개인정보 처리 위탁) [#제5조-개인정보-처리-위탁] 회사는 서비스 제공을 위해 다음과 같이 개인정보 처리 업무를 위탁하고 있습니다. | 수탁업체 | 위탁 업무 | | ------------------- | ---------- | | Amazon Web Services | 클라우드 서버 운영 | | Stripe / 토스페이먼츠 | 결제 처리 | | 채널톡 | 고객 상담 | 제6조 (이용자의 권리 및 행사 방법) [#제6조-이용자의-권리-및-행사-방법] 이용자는 언제든지 다음의 권리를 행사할 수 있습니다. 1. **개인정보 열람 요청**: 회사가 보유한 본인의 개인정보를 열람할 수 있습니다. 2. **개인정보 정정 요청**: 부정확한 개인정보의 정정을 요청할 수 있습니다. 3. **개인정보 삭제 요청**: 더 이상 필요하지 않은 개인정보의 삭제를 요청할 수 있습니다. 4. **처리 정지 요청**: 개인정보 처리의 정지를 요청할 수 있습니다. 권리 행사는 서비스 내 설정 메뉴 또는 고객센터를 통해 가능합니다. 제7조 (개인정보의 안전성 확보 조치) [#제7조-개인정보의-안전성-확보-조치] 회사는 개인정보의 안전성 확보를 위해 다음과 같은 조치를 취하고 있습니다. 기술적 조치 [#기술적-조치] * 개인정보의 암호화 (전송 시 TLS, 저장 시 AES-256) * 해킹 등에 대비한 보안 시스템 구축 * 접근 권한 관리 및 접근 기록 보관 관리적 조치 [#관리적-조치] * 개인정보 취급 직원의 최소화 * 정기적인 개인정보보호 교육 실시 * 내부 관리계획 수립 및 시행 물리적 조치 [#물리적-조치] * 전산실 및 자료 보관실의 접근 통제 제8조 (쿠키의 사용) [#제8조-쿠키의-사용] 회사는 이용자에게 개인화된 서비스를 제공하기 위해 쿠키를 사용합니다. 쿠키란? [#쿠키란] 웹사이트가 이용자의 브라우저에 저장하는 작은 텍스트 파일로, 이용자의 설정과 선호도를 기억하는 데 사용됩니다. 쿠키 사용 목적 [#쿠키-사용-목적] * 로그인 상태 유지 * 이용자 설정 저장 * 서비스 이용 통계 수집 쿠키 설정 변경 [#쿠키-설정-변경] 이용자는 브라우저 설정을 통해 쿠키 저장을 거부하거나 삭제할 수 있습니다. 다만, 쿠키를 거부할 경우 일부 서비스 이용에 제한이 있을 수 있습니다. 제9조 (개인정보 보호책임자) [#제9조-개인정보-보호책임자] 회사는 개인정보 처리에 관한 업무를 총괄해서 책임지고, 개인정보 처리와 관련한 이용자의 불만처리 및 피해구제 등을 위하여 아래와 같이 개인정보 보호책임자를 지정하고 있습니다. | 구분 | 내용 | | --- | ----------------------------------------------- | | 직책 | 개인정보보호책임자 | | 이메일 | [privacy@suits.work](mailto:privacy@suits.work) | 제10조 (개인정보처리방침의 변경) [#제10조-개인정보처리방침의-변경] 본 개인정보처리방침은 법령, 정책 또는 보안기술의 변경에 따라 내용이 추가, 삭제 및 수정될 수 있습니다. 변경 시에는 시행일 최소 7일 전에 서비스 내 공지사항을 통해 고지합니다. 제11조 (권익침해 구제방법) [#제11조-권익침해-구제방법] 개인정보 침해에 대한 신고나 상담이 필요한 경우 아래 기관에 문의하실 수 있습니다. | 기관 | 연락처 | 웹사이트 | | ----------- | --------- | ------------------------------------------------------------ | | 개인정보침해신고센터 | 118 | [privacy.kisa.or.kr](https://privacy.kisa.or.kr) | | 개인정보분쟁조정위원회 | 1833-6972 | [kopico.go.kr](https://www.kopico.go.kr) | | 대검찰청 사이버수사과 | 1301 | [spo.go.kr](https://www.spo.go.kr) | | 경찰청 사이버안전국 | 182 | [cyberbureau.police.go.kr](https://cyberbureau.police.go.kr) | *** 부칙 [#부칙] 1. 본 개인정보처리방침은 2024년 12월 11일부터 시행됩니다. *** 문의 [#문의] 본 개인정보처리방침에 관한 문의는 아래로 연락해 주시기 바랍니다. * **이메일**: [privacy@suits.work](mailto:privacy@suits.work) * **고객센터**: 서비스 내 채널톡 --- # 이용약관 (/docs/legal/terms) > Suits 서비스 이용약관 제1조 (목적) [#제1조-목적] 본 약관은 회사가 제공하는 Suits 서비스의 이용 조건 및 절차, 회사와 이용자 간의 권리와 의무, 기타 필요한 사항을 규정하는 것을 목적으로 합니다. 제2조 (정의) [#제2조-정의] 1. \*\*"서비스"\*\*란 회사가 제공하는 AI 기반 업무 자동화 플랫폼 Suits 및 관련 부가 서비스를 의미합니다. 2. \*\*"이용자"\*\*란 본 약관에 동의하고 서비스를 이용하는 개인 또는 법인을 의미합니다. 3. \*\*"워크스페이스"\*\*란 이용자가 서비스 내에서 생성하고 관리하는 독립적인 업무 공간을 의미합니다. 4. \*\*"콘텐츠"\*\*란 이용자가 서비스 내에서 생성, 저장, 공유하는 모든 데이터, 문서, 파일 등을 의미합니다. 제3조 (약관의 효력 및 변경) [#제3조-약관의-효력-및-변경] 1. 본 약관은 서비스를 이용하고자 하는 모든 이용자에게 적용됩니다. 2. 회사는 관련 법령에 위배되지 않는 범위 내에서 본 약관을 변경할 수 있으며, 변경된 약관은 서비스 내 공지사항 또는 이메일을 통해 사전 고지합니다. 3. 이용자가 변경된 약관에 동의하지 않는 경우, 서비스 이용을 중단하고 탈퇴할 수 있습니다. 제4조 (서비스의 제공) [#제4조-서비스의-제공] 1. 회사는 다음과 같은 서비스를 제공합니다: * AI 기반 업무 시스템 구축 및 관리 * 데이터 모델링 및 관리 * 워크플로우 자동화 * 팀 협업 기능 * API 연동 서비스 2. 서비스는 연중무휴 24시간 제공함을 원칙으로 하나, 시스템 점검 등 필요한 경우 일시적으로 중단될 수 있습니다. 제5조 (이용자의 의무) [#제5조-이용자의-의무] 이용자는 다음 행위를 하여서는 안 됩니다: 1. 타인의 개인정보를 부정하게 수집, 이용하는 행위 2. 서비스의 안정적 운영을 방해하는 행위 3. 불법적인 목적으로 서비스를 이용하는 행위 4. 회사의 지식재산권을 침해하는 행위 5. 기타 관련 법령에 위반되는 행위 제6조 (콘텐츠의 소유권) [#제6조-콘텐츠의-소유권] 1. 이용자가 서비스 내에서 생성한 콘텐츠의 소유권은 이용자에게 있습니다. 2. 회사는 서비스 제공 목적 외에 이용자의 콘텐츠를 사용하지 않습니다. 3. 이용자는 자신의 콘텐츠에 대해 백업 책임을 부담합니다. 제7조 (요금 및 결제) [#제7조-요금-및-결제] 1. 서비스의 요금은 사용량 기반(토큰)으로 과금됩니다. 2. 무료 플랜 이용자에게는 매월 기본 토큰이 제공됩니다. 3. 유료 서비스 이용 시 결제는 월별 또는 연간 구독 방식으로 진행됩니다. 4. 환불 정책은 별도로 정하는 바에 따릅니다. 제8조 (서비스 이용 제한) [#제8조-서비스-이용-제한] 회사는 다음의 경우 이용자의 서비스 이용을 제한할 수 있습니다: 1. 본 약관을 위반한 경우 2. 서비스의 정상적인 운영을 방해한 경우 3. 불법적인 목적으로 서비스를 이용한 경우 4. 기타 회사가 정한 이용 조건을 위반한 경우 제9조 (면책조항) [#제9조-면책조항] 1. 회사는 천재지변, 전쟁, 테러 등 불가항력적 사유로 인한 서비스 중단에 대해 책임을 지지 않습니다. 2. 회사는 이용자의 귀책사유로 인한 서비스 이용 장애에 대해 책임을 지지 않습니다. 3. 회사는 이용자가 서비스를 통해 얻은 정보의 정확성, 신뢰성에 대해 보증하지 않습니다. 제10조 (분쟁 해결) [#제10조-분쟁-해결] 1. 본 약관과 관련하여 분쟁이 발생한 경우, 회사와 이용자는 상호 협의하여 해결하도록 노력합니다. 2. 협의가 이루어지지 않는 경우, 관할 법원은 회사의 본점 소재지를 관할하는 법원으로 합니다. 제11조 (기타) [#제11조-기타] 1. 본 약관에서 정하지 아니한 사항은 관련 법령 및 상관례에 따릅니다. 2. 본 약관의 일부 조항이 무효인 경우에도 나머지 조항은 유효합니다. *** 부칙 [#부칙] 1. 본 약관은 2024년 12월 11일부터 시행됩니다. *** 문의 [#문의] 본 약관에 관한 문의는 아래로 연락해 주시기 바랍니다. * **이메일**: [support@suits.work](mailto:support@suits.work) * **고객센터**: 서비스 내 채널톡 --- # 노드 레퍼런스 (/docs/node-reference) > 워크플로우에서 사용할 수 있는 모든 트리거와 액션의 상세 스펙을 확인하세요. import { Card, Cards } from 'fumadocs-ui/components/card'; 트리거 [#트리거] 워크플로우가 **시작되는 조건**을 정의하는 노드입니다. <Cards> <Card title="수동 트리거" description="버튼 클릭으로 직접 실행" href="/docs/node-reference/triggers/manual" /> <Card title="일정 트리거" description="CRON 기반 정기 실행" href="/docs/node-reference/triggers/schedule" /> <Card title="데이터 변경 트리거" description="행 생성/수정/삭제 감지" href="/docs/node-reference/triggers/data-change" /> <Card title="날짜 트리거" description="특정 날짜 도달 시 실행" href="/docs/node-reference/triggers/date" /> <Card title="웹훅 트리거" description="외부 HTTP 요청으로 실행" href="/docs/node-reference/triggers/webhook" /> </Cards> *** 액션 [#액션] 트리거 발생 시 **실행되는 작업**을 정의하는 노드입니다. 알림 [#알림] <Cards> <Card title="슬랙 메시지" description="채널/DM으로 메시지 발송" href="/docs/node-reference/actions/notifications/slack" /> <Card title="이메일" description="이메일 발송" href="/docs/node-reference/actions/notifications/email" /> <Card title="슈츠 알림" description="인앱 알림 발송" href="/docs/node-reference/actions/notifications/taylor-notification" /> </Cards> 데이터 [#데이터] <Cards> <Card title="행 생성" description="데이터모델에 새 행 추가" href="/docs/node-reference/actions/data/create-row" /> <Card title="행 수정" description="기존 행의 속성 값 변경" href="/docs/node-reference/actions/data/update-row" /> <Card title="행 삭제" description="조건에 맞는 행 삭제" href="/docs/node-reference/actions/data/delete-row" /> <Card title="행 조회" description="조건 검색으로 행 가져오기" href="/docs/node-reference/actions/data/query-rows" /> </Cards> 연동 [#연동] <Cards> <Card title="HTTP 요청" description="외부 API 호출" href="/docs/node-reference/actions/integrations/http-request" /> <Card title="Google Sheets" description="스프레드시트 연동" href="/docs/node-reference/actions/integrations/google-sheets" /> <Card title="OpenAI" description="AI 처리 실행" href="/docs/node-reference/actions/integrations/openai" /> </Cards> 국내 비즈니스 [#국내-비즈니스] <Cards> <Card title="카페24" description="카페24 쇼핑몰 연동" href="/docs/node-reference/actions/korea-business/cafe24" /> <Card title="아임웹" description="아임웹 쇼핑몰 연동" href="/docs/node-reference/actions/korea-business/imweb" /> <Card title="네이버톡톡" description="네이버톡톡 챗봇 메시지" href="/docs/node-reference/actions/korea-business/naver-talktalk" /> <Card title="네이버 커머스" description="스마트스토어 연동" href="/docs/node-reference/actions/korea-business/naver-commerce" /> <Card title="볼타" description="전자세금계산서 발행" href="/docs/node-reference/actions/korea-business/bolta" /> </Cards> 제어 [#제어] <Cards> <Card title="조건 분기" description="If/Else 분기 처리" href="/docs/node-reference/actions/control/condition" /> <Card title="지연" description="다음 액션까지 대기" href="/docs/node-reference/actions/control/delay" /> <Card title="반복" description="여러 항목에 같은 작업 반복" href="/docs/node-reference/actions/control/loop" /> <Card title="코드" description="JavaScript 코드 실행" href="/docs/node-reference/actions/control/code" /> </Cards> --- # 활용 예시 (/docs/taylor-ai/examples) > 테일러를 활용한 실제 사례들을 살펴보세요. import { Callout } from 'fumadocs-ui/components/callout'; 예시 1: 고객 관계 관리 (CRM) [#예시-1-고객-관계-관리-crm] 사용자 요청 [#사용자-요청] ``` B2B 영업팀을 위한 고객 관리 시스템을 만들어줘. 고객사 정보, 담당자, 영업 기회, 미팅 기록을 관리하고 싶어. ``` 테일러의 실행 [#테일러의-실행] ``` 안녕하세요! B2B 영업팀을 위한 CRM 시스템을 만들어드릴게요. 다음과 같은 구조로 시스템을 구성했습니다: 📊 생성된 데이터모델: 1. 고객사 └─ 회사명, 업종, 규모, 웹사이트, 주소, 담당 영업사원 2. 담당자 └─ 이름, 직책, 이메일, 전화번호, 소속 고객사(관계) 3. 영업기회 └─ 기회명, 예상 매출, 단계, 확률, 예상 마감일, 담당자, 고객사(관계) 4. 미팅기록 └─ 일시, 참석자, 안건, 결과, 다음 액션, 관련 고객사(관계) 🔗 관계 설정: - 고객사 ↔ 담당자 (1:N) - 고객사 ↔ 영업기회 (1:N) - 고객사 ↔ 미팅기록 (1:N) 📋 뷰: - 영업 파이프라인 (칸반): 단계별 영업기회 - 미팅 캘린더: 날짜별 미팅 일정 📝 샘플 데이터도 각 모델에 5개씩 추가했어요. 추가로 필요한 기능이 있으면 말씀해 주세요! ``` 후속 요청 [#후속-요청] ``` 사용자: 영업기회 단계에 "계약완료" 옵션도 추가해줘 테일러: 영업기회의 "단계" 속성에 "계약완료" 옵션을 추가했어요. 색상은 초록색으로 설정했습니다. 사용자: 신규 영업기회가 등록되면 슬랙에 알림 보내줘 테일러: "신규 영업기회 알림" 워크플로우를 생성했어요. 트리거: 영업기회 데이터모델에 새 행 생성 액션: #영업팀 슬랙 채널에 알림 메시지 형식: "🎯 새 영업기회: {{기회명}} 고객사: {{고객사}} 예상 매출: {{예상매출}} 담당: {{담당자}}" ``` *** 예시 2: 프로젝트 관리 [#예시-2-프로젝트-관리] 사용자 요청 [#사용자-요청-1] ``` 소규모 개발팀의 프로젝트 관리 시스템을 만들어줘. 스프린트 단위로 태스크를 관리하고, 각 태스크의 진행 상황을 추적하고 싶어. ``` 테일러의 실행 [#테일러의-실행-1] ``` 개발팀을 위한 프로젝트 관리 시스템을 만들어드릴게요! 📊 생성된 데이터모델: 1. 프로젝트 └─ 프로젝트명, 설명, 상태, 시작일, 목표 종료일 2. 스프린트 └─ 스프린트명, 프로젝트(관계), 시작일, 종료일, 목표 3. 태스크 └─ 제목, 설명, 스프린트(관계), 담당자, 상태, 우선순위, 스토리포인트, 마감일 📋 뷰: - 칸반 보드: 태스크 상태별 (대기, 진행중, 검토중, 완료) - 스프린트 캘린더: 스프린트 기간 표시 - 담당자별 목록: 각 담당자의 태스크 현황 📈 롤업 속성: - 스프린트 → 완료율 (완료 태스크 / 전체 태스크) - 프로젝트 → 진행률 (완료 스프린트 / 전체 스프린트) 각 데이터모델에 샘플 데이터를 추가했어요. 칸반 보드에서 드래그 앤 드롭으로 상태를 변경할 수 있습니다! ``` 후속 요청 [#후속-요청-1] ``` 사용자: 태스크 마감일 하루 전에 담당자에게 알림 보내줘 테일러: "마감 리마인더" 워크플로우를 생성했어요. 트리거: 매일 오전 9시 조건: 마감일 = 내일 AND 상태 ≠ "완료" 액션: 담당자에게 슬랙 DM "⏰ 내일 마감 예정인 태스크가 있어요! {{제목}} 마감일: {{마감일}}" 사용자: 스프린트 번다운 차트도 보고 싶어 테일러: 스프린트 번다운 차트를 생성했어요. 대시보드 페이지에 차트 블록을 추가했습니다. - X축: 날짜 - Y축: 남은 스토리포인트 - 이상선 vs 실제 진행 비교 ``` *** 예시 3: 재고 관리 [#예시-3-재고-관리] 사용자 요청 [#사용자-요청-2] ``` 소규모 쇼핑몰의 재고 관리 시스템을 만들어줘. 상품 정보, 입출고 내역, 현재 재고량을 관리하고 싶어. 재고가 일정 수량 이하로 떨어지면 알림을 받고 싶어. ``` 테일러의 실행 [#테일러의-실행-2] ``` 쇼핑몰 재고 관리 시스템을 만들어드릴게요! 📊 생성된 데이터모델: 1. 상품 └─ 상품명, SKU, 카테고리, 이미지, 판매가, 원가 현재재고, 안전재고, 재고상태(수식) 2. 입출고 └─ 상품(관계), 유형(입고/출고), 수량, 일시, 사유, 담당자 🧮 수식: - 재고상태: if(현재재고 <= 0, "품절", if(현재재고 <= 안전재고, "저재고", "정상")) 📋 뷰: - 상품 갤러리: 이미지와 함께 상품 카탈로그 - 저재고 목록: 재고상태 = "저재고" 필터 - 입출고 내역: 최근순 정렬 ⚡ 워크플로우: 저재고 알림 - 트리거: 상품의 현재재고 변경 - 조건: 현재재고 <= 안전재고 - 액션: - 구매팀 슬랙에 알림 - 상품 담당자에게 이메일 샘플 상품 10개와 입출고 내역 20건을 추가했어요. ``` 후속 요청 [#후속-요청-2] ``` 사용자: 입고 되면 자동으로 현재재고가 업데이트 되게 해줘 테일러: "재고 자동 업데이트" 워크플로우를 생성했어요. 트리거: 입출고 데이터모델에 새 행 생성 액션: - 유형 = "입고": 상품.현재재고 += 수량 - 유형 = "출고": 상품.현재재고 -= 수량 이제 입출고 기록을 추가하면 재고가 자동으로 업데이트됩니다! 사용자: 월별 입출고 현황 리포트도 보고 싶어 테일러: 월별 입출고 리포트를 생성했어요. 대시보드에 추가한 차트: - 월별 입고/출고 수량 비교 (막대 차트) - 카테고리별 재고 현황 (파이 차트) - 저재고 상품 목록 (테이블) ``` *** 예시 4: 채용 관리 [#예시-4-채용-관리] 사용자 요청 [#사용자-요청-3] ``` 채용 프로세스를 관리하는 시스템이 필요해. 지원자, 면접 일정, 평가를 관리하고 싶어. ``` 테일러의 실행 [#테일러의-실행-3] ``` 채용 관리 시스템을 만들어드릴게요! 📊 생성된 데이터모델: 1. 채용공고 └─ 포지션명, 부서, 고용형태, 마감일, 상태, JD 2. 지원자 └─ 이름, 이메일, 전화번호, 지원 포지션(관계), 이력서(파일), 단계, 지원일 3. 면접일정 └─ 지원자(관계), 일시, 면접관, 면접유형, 장소/링크 4. 면접평가 └─ 면접일정(관계), 평가자, 기술역량, 문화적합도, 커뮤니케이션, 총점(수식), 코멘트, 합격여부 📋 뷰: - 채용 파이프라인 (칸반): 지원자 단계별 (서류검토 → 1차면접 → 2차면접 → 최종면접 → 합격/불합격) - 면접 캘린더: 면접 일정 표시 - 포지션별 현황: 채용공고별 지원자 수 🔔 워크플로우: - 면접 하루 전 면접관에게 리마인더 - 지원자 등록 시 서류검토 담당자에게 알림 ``` *** 예시 5: 콘텐츠 캘린더 [#예시-5-콘텐츠-캘린더] 사용자 요청 [#사용자-요청-4] ``` 마케팅팀 콘텐츠 발행 일정을 관리하는 시스템을 만들어줘. 블로그, SNS, 뉴스레터 등 채널별로 관리하고 싶어. ``` 테일러의 실행 [#테일러의-실행-4] ``` 콘텐츠 캘린더 시스템을 만들어드릴게요! 📊 생성된 데이터모델: 1. 콘텐츠 └─ 제목, 유형(블로그/SNS/뉴스레터/영상), 채널, 상태(기획/작성중/검토/발행완료), 담당자, 예정일, 발행일, 썸네일 2. 채널 └─ 채널명, 플랫폼, URL, 담당자 📋 뷰: - 콘텐츠 캘린더: 예정일 기준 월간 캘린더 - 제작 현황 (칸반): 상태별 진행 현황 - 채널별 목록: 채널별 발행 콘텐츠 🔔 워크플로우: - 발행 예정일 3일 전 담당자 리마인더 - 발행 완료 시 팀 슬랙 공유 샘플 콘텐츠 15개를 한 달 일정으로 추가했어요. ``` *** 대화 팁 요약 [#대화-팁-요약] | 상황 | 효과적인 프롬프트 | | ------------- | ------------------------ | | **시스템 처음 요청** | 업종/목적 + 관리할 항목 + 원하는 자동화 | | **구조 수정** | @멘션으로 대상 지정 + 구체적 변경 내용 | | **분석 요청** | 분석 대상 + 기준 + 원하는 시각화 | | **워크플로우 요청** | 트리거 조건 + 액션 목록 | <Callout type="tip"> 처음부터 완벽한 시스템을 요청하지 않아도 됩니다. 기본 구조를 먼저 만들고, 대화를 통해 점진적으로 개선해 나가세요. </Callout> *** 다음 단계 [#다음-단계] * [도구](/docs/taylor-ai/tools) - 50개 도구 상세 * [효과적인 프롬프팅](/docs/taylor-ai/prompting-tips) - 프롬프트 작성법 --- # Taylor 소개 (/docs/taylor-ai) > AI가 당신만을 위한 업무시스템을 만들어드립니다. import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; Taylor의 철학 [#taylor의-철학] 테일러는 산업혁명을 이끈 **세계 최초의 경영 컨설턴트**인 프레더릭 윈슬로 **테일러**(Frederick Winslow Taylor)의 이름을 본따, AI 시대에 걸맞는 단 하나의 워크스페이스를 만들어줄 파트너가 될 수 있도록 만들었습니다. * 업무시스템 구축부터 * 업무 분석 및 자동화 제작 * 더 나아가 의사결정 자동화까지 반복적인 업무와 반복하기 어려운 업무까지 모두 하나의 플랫폼에서 완성할 수 있도록 테일러가 앞장서서 여러분만의 슈츠 워크스페이스를 만들어드릴 겁니다. *** Taylor가 할 수 있는 일 [#taylor가-할-수-있는-일] Taylor는 단순한 AI 챗봇이 아닙니다. **자율적이고 능동적인 에이전트**로서: * 요청을 분석하고 필요한 작업을 **직접 실행**합니다 * 모호한 요청도 맥락을 분석하여 **추론하고 실행**합니다 * 복잡한 시스템도 대화 몇 번으로 **완성**합니다 ``` 사용자: "B2B 영업팀을 위한 CRM 만들어줘" Taylor: ├── 요구사항 분석 (고객, 영업기회, 미팅, 계약) ├── 데이터모델 4개 설계 및 생성 ├── 관계 설정 (고객 ↔ 영업기회, 고객 ↔ 미팅) ├── 칸반 보드 뷰 생성 (영업 파이프라인) ├── 샘플 데이터 10개 생성 └── 대시보드 페이지 구성 ``` Taylor는 **슈츠 내에서도** 사용 가능하고, **MCP를 연결해 다른 AI 도구에서도** 사용할 수 있습니다. <Callout type="info"> 자세한 MCP(Model Context Protocol) 설정 방법은 [MCP 연결 가이드](/docs/api-reference/mcp)를 참고하세요. </Callout> 이 중 어떤 도구에서라도 **58개의 도구**를 사용하여 워크스페이스를 전체를 관리합니다. 도구 요약 [#도구-요약] | 카테고리 | 도구 수 | 기능 | | ---------- | :--: | ----------------------------- | | **검색** | 2개 | 도구 검색, 시맨틱 검색 | | **시스템** | 1개 | 도구 실행 결과 상세 조회 | | **스킬** | 5개 | AI 스킬 관리 | | **블록** | 6개 | 페이지 콘텐츠 생성, 수정, 부분 수정, 삭제, 검색 | | **데이터모델** | 13개 | 테이블 생성, 속성 정의, 데이터 CRUD, 템플릿 | | **통계** | 8개 | SQL 쿼리 작성, 데이터 시각화 | | **워크플로우** | 17개 | 자동화 워크플로우 생성, 테스트, 배포, 실행 | | **워크스페이스** | 2개 | 워크스페이스 구조 요약, 알림 조회 | | **웹** | 2개 | 웹 검색, 웹 페이지 가져오기 | | **메모리** | 2개 | 정보 저장, 메모리 검색 | *** AI 모델 선택 [#ai-모델-선택] Taylor는 다양한 AI 모델을 지원하며, 대화 입력 영역의 모델 선택기에서 원하는 모델로 전환할 수 있습니다. 지원 모델 [#지원-모델] | 모델 | 특징 | 적합한 작업 | | ---------------------- | ----------------- | -------------------- | | **Claude Haiku** | 빠른 응답, 가벼운 처리 | 간단한 질문, 빠른 작업 | | **Claude Sonnet** (기본) | 좋은 성능 | 복잡한 작업, 정밀한 분석 | | **Claude Opus** | 최상위 성능 | 최고 수준의 추론, 복잡한 문제 해결 | | **Gemini Pro** | 안정적 성능, 대용량 컨텍스트 | 긴 문서 분석, 대규모 데이터 처리 | | **Gemini Flash** | 빠른 응답, 저렴한 비용 | 빈번한 요청, 비용 효율적 작업 | | **DeepSeek Chat** | GPT 수준 성능, 매우 저렴 | 가성비 중시 작업 | | **DeepSeek Reasoner** | 추론/분석 특화 | 논리적 분석, 추론이 필요한 작업 | | **Mistral Medium** | Sonnet급 성능, 8배 저렴 | 비용 효율적인 복잡한 작업 | | **Mistral Small** | 빠른 응답, 간단한 작업 | 간단한 질문, 빠른 처리 | <Callout type="tip"> 작업 복잡도에 따라 모델을 전환하면 비용을 절감하면서도 좋은 결과를 얻을 수 있습니다. 간단한 질문은 Haiku나 Flash로, 복잡한 시스템 설계는 Sonnet이나 Opus로 처리하세요. </Callout> *** 멀티세션과 메모리 [#멀티세션과-메모리] 멀티세션 관리 [#멀티세션-관리] Taylor는 여러 대화 세션을 독립적으로 관리합니다. 대화 패널 상단의 세션 선택기에서 다음 작업이 가능합니다: * **새 대화 시작**: 독립적인 새 대화 세션을 생성합니다 * **세션 전환**: 이전 대화로 돌아가 이어서 진행합니다 * **세션 아카이브**: 더 이상 필요 없는 대화를 정리합니다 세션별로 대화 내용과 컨텍스트가 분리되어 있어, 서로 다른 주제의 작업을 동시에 진행할 수 있습니다. AI 메모리 시스템 [#ai-메모리-시스템] Taylor는 대화 세션 간에도 정보를 기억하는 메모리 시스템을 갖추고 있습니다. **자동 기억 대상:** * 사용자 선호 (날짜 형식, 명명 규칙 등) * 비즈니스 규칙 및 도메인 용어 * 반복적인 워크플로우 패턴 * 조직 구조 및 담당자 정보 **메모리 범위:** * **워크스페이스 메모리**: 워크스페이스 내 모든 사용자가 공유하는 정보 * **사용자 메모리**: 개인에게만 적용되는 선호 설정 대화 중 "이것을 기억해줘"라고 말하면 Taylor가 해당 정보를 저장하고, 이후 대화에서 자동으로 참조합니다. *** Taylor 호출하기 [#taylor-호출하기] 단축키 [#단축키] | 단축키 | 동작 | | -------------- | ------------- | | `Cmd/Ctrl + /` | Taylor 대화창 열기 | 패널에서 호출 [#패널에서-호출] 화면 우측 상단의 **Taylor AI** 버튼을 클릭하여 AI 패널을 열 수 있습니다. 멘션으로 컨텍스트 전달 [#멘션으로-컨텍스트-전달] 대화 중 `@`를 입력하여 특정 요소를 멘션할 수 있습니다: ``` @고객 데이터모델의 이메일 속성을 필수로 변경해줘 @프로젝트_진행현황 페이지에 차트 추가해줘 ``` *** 주요 기능 [#주요-기능] 1. 업무시스템 설계 [#1-업무시스템-설계] 자연어로 요청하면 전체 업무시스템을 설계하고 구축합니다. ``` "프로젝트 관리 시스템을 만들어줘. 프로젝트, 마일스톤, 태스크를 관리하고 담당자별 업무 현황을 볼 수 있어야 해." ``` Taylor가 생성하는 것: * 데이터모델 3개 (프로젝트, 마일스톤, 태스크) * 관계 설정 (프로젝트 → 마일스톤 → 태스크) * 칸반 뷰 (상태별) * 대시보드 페이지 2. 워크플로우 자동화 [#2-워크플로우-자동화] 반복 작업을 자동화하는 워크플로우를 설계합니다. ``` "새 고객이 등록되면 환영 이메일 보내고 담당자에게 알려줘" "마감일 하루 전에 담당자에게 리마인더 보내줘" ``` 3. 데이터 분석 [#3-데이터-분석] 데이터모델의 데이터를 분석하고 인사이트를 제공합니다. ``` "이번 달 영업 현황을 분석해줘" "카테고리별 매출 비중을 차트로 보여줘" "저재고 상품 목록을 정리해줘" ``` 4. 콘텐츠 작성 [#4-콘텐츠-작성] 문서 작성, 요약, 번역 등 다양한 텍스트 작업을 수행합니다. ``` "이 회의록을 핵심 내용만 3줄로 요약해줘" "이 문서를 영어로 번역해줘" "프로젝트 개요 문서를 작성해줘" ``` *** Taylor 대화 흐름 [#taylor-대화-흐름] 일반적인 대화 [#일반적인-대화] ``` 사용자: 고객 데이터모델에 등급 속성을 추가해줘 Taylor: └─ [실행] 고객 데이터모델에 "등급" 속성 추가 타입: 단일 선택 옵션: VIP, 일반, 신규 고객 데이터모델에 "등급" 속성을 추가했습니다. 옵션은 VIP, 일반, 신규로 설정했는데, 다른 옵션이 필요하시면 말씀해 주세요. ``` 복잡한 요청 [#복잡한-요청] ``` 사용자: 재고 관리 시스템이 필요해. 상품별 재고를 추적하고, 저재고 시 알림이 갔으면 좋겠어. Taylor: ├─ [분석] 필요한 구성요소 파악 │ └─ 상품 데이터모델, 입출고 내역, 저재고 알림 워크플로우 │ ├─ [실행] 상품 데이터모델 생성 │ └─ 속성: 상품명, SKU, 카테고리, 현재재고, 안전재고 │ ├─ [실행] 입출고 데이터모델 생성 │ └─ 속성: 상품(관계), 유형, 수량, 일시, 사유 │ ├─ [실행] 저재고 알림 워크플로우 생성 │ └─ 트리거: 재고 변경 시 │ 조건: 현재재고 <= 안전재고 │ 액션: 슬랙 알림 │ └─ [완료] 재고 관리 시스템이 준비되었습니다! ``` *** 응답 언어 [#응답-언어] Taylor는 현재 **항상 한국어**로 응답합니다. 주요 기능이 안정적으로 완성되는대로 영어 등 글로벌 서비스 제공이 예정되어 있습니다. *** 보안 및 격리 [#보안-및-격리] 워크스페이스 격리 [#워크스페이스-격리] Taylor는 **현재 워크스페이스 내의 데이터만** 접근할 수 있습니다. * ✅ 현재 워크스페이스의 데이터모델 * ✅ 현재 워크스페이스의 페이지 * ✅ 현재 워크스페이스의 워크플로우 * ❌ 다른 워크스페이스의 데이터 * ❌ 시스템 설정 * ❌ 다른 사용자의 개인 정보 권한 준수 [#권한-준수] Taylor는 현재 사용자의 **권한 범위 내에서만** 동작합니다. * 편집 권한이 없는 페이지는 수정 불가 * 관리자 전용 설정은 변경 불가 *** 이 섹션에서 다루는 내용 [#이-섹션에서-다루는-내용] <Cards> <Card title="도구" description="58개 도구의 상세 설명" href="/docs/taylor-ai/tools" /> <Card title="효과적인 프롬프팅" description="Taylor를 잘 활용하는 방법" href="/docs/taylor-ai/prompting-tips" /> <Card title="활용 예시" description="실제 사용 사례" href="/docs/taylor-ai/examples" /> <Card title="MCP 연결" description="Claude Desktop, Cursor 등에서 연결" href="/docs/api-reference/mcp" /> </Cards> *** 빠른 시작 [#빠른-시작] 지금 바로 Taylor를 시작해보세요: 1. `Cmd/Ctrl + /`를 눌러 Taylor 호출 2. 다음 중 하나를 입력: ``` "안녕, 뭘 도와줄 수 있어?" "고객 관리 시스템을 만들어줘" "현재 워크스페이스 요약해줘" ``` <Callout type="tip"> 복잡한 시스템도 자연어 한 문장으로 시작할 수 있습니다. Taylor가 필요한 질문이 있으면 먼저 물어봅니다. </Callout> --- # 프로액티브 AI 인사이트 (/docs/taylor-ai/proactive-insights) > 사용자가 요청하지 않아도 AI가 자동으로 데이터를 분석하여 인사이트를 제공하는 프로액티브 에이전트를 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; 프로액티브 에이전트란 [#프로액티브-에이전트란] 프로액티브 에이전트는 **사용자가 요청하지 않아도** AI가 워크스페이스의 데이터를 자동으로 모니터링하고 분석하여 인사이트를 제공하는 시스템입니다. 일반적인 AI 대화가 "사용자 질문 → AI 응답"의 흐름이라면, 프로액티브 에이전트는 이벤트나 스케줄에 의해 **자발적으로** 분석을 수행하고, 유의미한 발견이 있을 때 알림으로 전달합니다. 동작 방식 [#동작-방식] 1. **트리거 발동** - 데이터 변경, 통계 실행, 스케줄 등의 이벤트 발생 2. **에이전트 매칭** - 트리거 조건에 맞는 에이전트를 라우팅 3. **자동 분석** - 에이전트가 도구를 사용하여 워크스페이스 데이터를 조회하고 분석 4. **인사이트 생성** - 유의미한 발견을 구조화된 인사이트로 생성 5. **알림 전달** - 관리자에게 알림으로 전달, AI 채팅 패널에도 표시 *** 멀티 프로액티브 에이전트 [#멀티-프로액티브-에이전트] 하나의 워크스페이스에 **여러 프로액티브 에이전트**를 동시에 운영할 수 있습니다. 각 에이전트는 고유한 역할, 트리거 조건, 시스템 프롬프트, 도구 권한을 가지며, 독립적으로 분석을 수행합니다. 에이전트 구성 요소 [#에이전트-구성-요소] | 구성 요소 | 설명 | | ------------ | ------------------------------------------------- | | **이름/역할** | 에이전트의 이름과 담당 역할 (예: "매출 분석", "재고 모니터링") | | **아바타/뱃지** | 에이전트를 시각적으로 구분하는 아이콘 | | **시스템 프롬프트** | 분석 방향, 중요도 기준, 응답 스타일 등을 지정하는 지침 | | **트리거** | 에이전트가 분석을 시작하는 조건 (이벤트/스케줄) | | **도구 권한** | 에이전트가 사용할 수 있는 도구 범위와 쓰기 권한 | | **분석 모델** | 분석에 사용할 AI 모델 (Claude, Gemini, DeepSeek, Mistral) | 시스템 에이전트 vs 커스텀 에이전트 [#시스템-에이전트-vs-커스텀-에이전트] | 구분 | 시스템 에이전트 | 커스텀 에이전트 | | --------- | ---------------- | ----------- | | **생성** | 워크스페이스당 1개 자동 생성 | 사용자가 직접 생성 | | **이름 변경** | 불가 (Taylor 고정) | 자유롭게 변경 가능 | | **삭제** | 불가 (비활성화만 가능) | 삭제 가능 | | **기본 역할** | 워크스페이스 전반 인사이트 | 특정 영역 전문 분석 | <Callout type="tip"> 시스템 에이전트(Taylor)는 워크스페이스 전반을 모니터링합니다. 특정 데이터모델이나 워크플로우에 대한 전문적인 분석이 필요하다면, 해당 역할에 특화된 커스텀 에이전트를 추가하세요. </Callout> *** 트리거 설정 [#트리거-설정] 프로액티브 에이전트는 **이벤트 트리거**와 **스케줄 트리거** 두 가지 방식으로 분석을 시작합니다. 이벤트 트리거 [#이벤트-트리거] 워크스페이스에서 특정 이벤트가 발생할 때 분석을 실행합니다. | 트리거 타입 | 설명 | 필터링 | | ------------- | ------------------- | --------------- | | **데이터 변화 감지** | 데이터모델의 행 추가/수정/삭제 시 | 특정 데이터모델만 감시 가능 | | **통계 실행 분석** | 통계 정의 실행 완료 시 결과 분석 | 특정 통계 정의만 감시 가능 | | **지표 분석** | 워크스페이스 핵심 지표 변동 감지 | 특정 지표 선택 가능 | | **사용량 모니터링** | 토큰 사용량, API 호출 추적 | - | | **워크플로우 패턴** | 워크플로우 실행 패턴 이상 감지 | 특정 워크플로우만 감시 가능 | <Callout type="info"> 이벤트 트리거는 같은 에이전트에 대해 **최소 6시간 간격**으로 실행됩니다. 이는 과도한 분석 실행과 알림 폭주를 방지하기 위한 쿨다운 메커니즘입니다. </Callout> 각 이벤트 트리거에는 **리소스 필터**를 설정할 수 있습니다. 예를 들어, "데이터 변화 감지" 트리거에서 특정 데이터모델만 지정하면, 해당 데이터모델에 변경이 있을 때만 에이전트가 실행됩니다. 필터를 지정하지 않으면 모든 해당 이벤트에 반응합니다. 스케줄 트리거 (정기 분석) [#스케줄-트리거-정기-분석] 설정된 시간에 자동으로 분석을 실행합니다. | 설정 | 설명 | | --------- | ---------------------- | | **주기** | 매일(daily), 매주(weekly) | | **실행 시간** | 0-23시 (UTC 기준) | | **요일** | 주간 스케줄 시 특정 요일 지정 (선택) | <Callout type="info"> 스케줄 분석은 하루에 한 번만 실행됩니다. 이미 당일 분석이 완료된 에이전트는 같은 날 다시 실행되지 않습니다. </Callout> *** Cron 기반 자동 실행 [#cron-기반-자동-실행] 프로액티브 에이전트의 스케줄 트리거는 **Vercel Cron**을 통해 매시간 실행되는 `/api/cron/ai-insight` 엔드포인트에서 처리됩니다. 실행 흐름 [#실행-흐름] 1. 매시간 크론이 실행되어 활성 에이전트가 있는 모든 워크스페이스를 조회 2. 각 워크스페이스의 에이전트 중 현재 시간(UTC)에 스케줄이 매칭되는 에이전트를 필터링 3. 당일 이미 분석을 완료한 에이전트는 건너뜀 4. 매칭된 에이전트별로 분석 요청을 Workflow Worker에 전송 5. Workflow Worker에서 Agent Loop을 실행하여 인사이트를 생성하고 알림을 발송 <Callout type="tip"> 시스템 에이전트의 기본 실행 시간은 워크스페이스 ID를 기반으로 자동 분산됩니다. 이를 통해 서버 부하를 고르게 분배합니다. 에이전트 설정에서 원하는 시간으로 변경할 수 있습니다. </Callout> *** AI 인사이트 알림 [#ai-인사이트-알림] 프로액티브 에이전트가 생성한 인사이트는 다음과 같은 방식으로 표시됩니다. 알림 채널 [#알림-채널] | 채널 | 표시 위치 | 설명 | | -------------- | ---------- | -------------------------------- | | **알림 센터** | 상단 알림 아이콘 | 일반 알림과 함께 표시, 에이전트별 아바타/뱃지 구분 | | **AI 인사이트 패널** | AI 채팅 상단 | 미읽은 인사이트를 카드 형태로 표시 | | **AI 채팅 메시지** | AI 대화 내 | AI 패널이 열려 있을 때 새 인사이트가 대화에 자동 추가 | | **에이전트 팝오버** | 워크스페이스 오버뷰 | 에이전트 클릭 시 최근 메시지 팝오버 | 인사이트 카테고리 [#인사이트-카테고리] | 카테고리 | 아이콘 | 설명 | | ------------ | ------------ | ------------------- | | **데이터 인사이트** | 차트 아이콘 (파란색) | 데이터 변화, 이상치, 트렌드 분석 | | **생산성 제안** | 전구 아이콘 (노란색) | 자동화 기회, 최적화 제안 | 심각도 [#심각도] 각 인사이트에는 심각도가 지정됩니다. | 심각도 | 의미 | | ------------ | ------------- | | **info** | 참고용 정보 | | **warning** | 주의가 필요한 사항 | | **critical** | 즉각 조치가 필요한 사항 | *** 설정 방법 [#설정-방법] 워크스페이스 오버뷰에서 설정 [#워크스페이스-오버뷰에서-설정] 1. 워크스페이스 오버뷰 하단의 **AI 에이전트** 섹션을 확인합니다 2. 기존 에이전트를 클릭하면 메시지 팝오버가 나타나며, 설정(톱니바퀴) 아이콘으로 설정 다이얼로그를 엽니다 3. **추가** 버튼으로 새 커스텀 에이전트를 생성할 수 있습니다 에이전트 설정 다이얼로그 [#에이전트-설정-다이얼로그] 설정 다이얼로그는 좌우 2단 레이아웃으로 구성됩니다. **좌측 - 설정 폼:** | 설정 항목 | 설명 | | ------------ | -------------------------------------------- | | **이름/역할** | 에이전트 식별 정보 | | **아바타/뱃지** | 이모지 선택으로 시각적 구분 | | **활성화** | 비활성화 시 분석 중지 | | **발동조건** | 이벤트 트리거와 스케줄 트리거 설정 | | **쓰기 도구 허용** | 데이터 생성/수정/삭제 도구 사용 허용 여부 | | **분석 모델** | AI 모델 선택 (Claude, Gemini, DeepSeek, Mistral) | **우측 - 프리뷰 + 프롬프트:** | 영역 | 설명 | | ------------ | ------------------------- | | **에이전트 프리뷰** | 설정 중인 아바타/이름/역할의 실시간 미리보기 | | **시스템 프롬프트** | 에이전트의 분석 지침을 마크다운으로 작성 | <Callout type="warn"> 쓰기 도구를 허용하면 에이전트가 데이터를 생성, 수정, 삭제할 수 있습니다. 데이터 변경이 필요하지 않은 모니터링 에이전트에는 비활성화를 권장합니다. </Callout> *** 도구 권한 [#도구-권한] 에이전트가 분석에 사용할 수 있는 도구의 범위를 설정합니다. | 모드 | 설명 | | ------------- | ------------------ | | **all** | 허용된 전체 도구 사용 (기본값) | | **whitelist** | 지정한 도구만 사용 | | **blacklist** | 지정한 도구를 제외하고 사용 | `allowWrite` 설정에 따라 읽기 전용 도구만 사용할지, 쓰기 도구까지 허용할지 결정됩니다. 검색, 시맨틱 검색 등 메타 도구는 모든 모드에서 항상 사용 가능합니다. *** 활용 예시 [#활용-예시] 매출 모니터링 에이전트 [#매출-모니터링-에이전트] ``` 이름: 매출 분석가 역할: 매출/재무 데이터 분석 트리거: 데이터 변화 감지 (매출 데이터모델 필터), 매일 오전 9시 정기 분석 시스템 프롬프트: - 전일 대비 매출 20% 이상 증감 시 알림 - 주간 매출 트렌드 분석 - 이상 거래 패턴 감지 ``` 워크플로우 건강 체크 에이전트 [#워크플로우-건강-체크-에이전트] ``` 이름: 운영 감시자 역할: 워크플로우 실행 모니터링 트리거: 워크플로우 패턴 감지, 매일 오후 6시 정기 분석 시스템 프롬프트: - 실패율 10% 이상 워크플로우 경고 - 장시간 미실행 워크플로우 확인 - 자동화 효율 개선 제안 ``` 데이터 품질 에이전트 [#데이터-품질-에이전트] ``` 이름: 데이터 검수관 역할: 데이터 품질 모니터링 트리거: 데이터 변화 감지 (전체), 통계 실행 분석 시스템 프롬프트: - 필수 필드 누락 건수 추적 - 중복 데이터 감지 - 데이터 정합성 확인 쓰기 도구: 비허용 (읽기 전용) ``` *** 다음 단계 [#다음-단계] * [도구](/docs/taylor-ai/tools) - 에이전트가 사용할 수 있는 도구 목록 * [스킬](/docs/taylor-ai/skills) - 에이전트에 스킬을 연결하여 도메인 지식 제공 * [효과적인 프롬프팅](/docs/taylor-ai/prompting-tips) - 시스템 프롬프트 작성 팁 --- # 효과적인 프롬프팅 팁 (/docs/taylor-ai/prompting-tips) > 테일러를 더 효과적으로 활용하는 방법을 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; 기본 원칙 [#기본-원칙] 1. 구체적으로 요청하기 [#1-구체적으로-요청하기] 모호한 요청보다 **구체적인 요청**이 더 좋은 결과를 가져옵니다. ❌ **비효율적인 요청:** ``` 데이터베이스 만들어줘 ``` ✅ **효율적인 요청:** ``` 고객 정보를 관리할 데이터모델을 만들어줘. 회사명, 담당자, 이메일, 전화번호, 계약상태를 저장해야 해. ``` *** 2. 맥락 제공하기 [#2-맥락-제공하기] **비즈니스 맥락**을 제공하면 테일러가 더 적합한 구조를 설계합니다. ❌ **맥락 없음:** ``` CRM 만들어줘 ``` ✅ **맥락 제공:** ``` 우리는 B2B SaaS 회사야. 현재 50개 고객사가 있고, 각 고객사별로 계약 정보와 사용량을 추적하고 싶어. 담당자는 각 고객사에 여러 명이 있을 수 있어. 이에 맞는 CRM 시스템을 설계해줘. ``` *** 3. 단계별로 요청하기 [#3-단계별로-요청하기] 복잡한 작업은 **여러 단계로 나누어** 요청하세요. ✅ **단계별 접근:** ``` 1단계: "영업 파이프라인을 위한 데이터 구조를 먼저 제안해줘" 2단계: "좋아, 이 구조로 데이터모델을 만들어줘" 3단계: "영업기회 데이터모델에 예상 매출 속성을 추가해줘" 4단계: "월별 예상 매출을 볼 수 있는 차트를 만들어줘" ``` *** 4. 예시 제공하기 [#4-예시-제공하기] 원하는 결과의 **예시**를 제공하면 더 정확합니다. ✅ **예시 제공:** ``` 태스크 상태를 관리하는 선택 속성을 추가해줘. 옵션은 "대기", "진행중", "검토중", "완료", "보류" 이렇게 5개야. 각 옵션에 회색, 파란색, 보라색, 초록색, 빨간색을 지정해줘. ``` *** 효과적인 프롬프트 패턴 [#효과적인-프롬프트-패턴] 시스템 설계 요청 [#시스템-설계-요청] 업무시스템 전체를 설계할 때 사용합니다. ``` [업종/비즈니스 설명]을 위한 업무시스템을 설계해줘. 주요 관리 항목: - [항목1] - [항목2] - [항목3] 주요 워크플로우: - [워크플로우1] - [워크플로우2] ``` **예시:** ``` 온라인 쇼핑몰을 위한 주문관리 시스템을 설계해줘. 주요 관리 항목: - 상품 정보와 재고 - 고객 주문 - 배송 현황 주요 워크플로우: - 재고 부족 시 알림 - 배송 완료 시 고객에게 안내 ``` *** 데이터 구조 설계 요청 [#데이터-구조-설계-요청] 데이터모델 구조를 설계할 때 사용합니다. ``` [목적]을 위한 데이터 구조를 설계해줘. 필요한 정보: - [필드1]: [설명] - [필드2]: [설명] - [필드3]: [설명] 관계: - [관계 설명] ``` **예시:** ``` 프로젝트 관리를 위한 데이터 구조를 설계해줘. 필요한 정보: - 프로젝트: 이름, 설명, 시작일, 종료일, 상태 - 마일스톤: 이름, 목표일, 진행률 - 태스크: 제목, 담당자, 우선순위, 마감일, 상태 관계: - 프로젝트에 여러 마일스톤 - 마일스톤에 여러 태스크 - 태스크에 여러 담당자 가능 ``` *** 데이터 분석 요청 [#데이터-분석-요청] 데이터 분석과 시각화를 요청할 때 사용합니다. ``` [데이터모델 이름]의 데이터를 분석해서 [분석 목적]을 알려줘. 분석 기준: - [기준1] - [기준2] 시각화: - [차트 유형] (선택) ``` **예시:** ``` 영업기회 데이터를 분석해서 이번 분기 실적을 알려줘. 분석 기준: - 담당자별 성과 - 단계별 파이프라인 - 월별 추이 시각화: - 담당자별 막대 차트 - 단계별 파이프라인 퍼널 ``` *** 워크플로우 요청 [#워크플로우-요청] 자동화를 설정할 때 사용합니다. ``` [트리거 조건]일 때 [실행할 작업]을 자동으로 수행하는 워크플로우를 만들어줘. 조건 (있다면): - [조건1] - [조건2] 액션: - [액션1] - [액션2] ``` **예시:** ``` 새 고객이 등록될 때 다음 작업을 자동으로 수행하는 워크플로우를 만들어줘. 조건: - 계약 금액이 500만원 이상 액션: - 담당자에게 슬랙 DM 발송 - 환영 이메일 자동 발송 - VIP 태그 자동 추가 ``` *** 멘션 활용하기 [#멘션-활용하기] `@`를 사용하여 **특정 요소를 참조**하면 더 정확하게 작업할 수 있습니다. 데이터모델 멘션 [#데이터모델-멘션] ``` @고객 데이터모델의 구조를 설명해줘 @태스크 모델에 새 속성을 추가해줘 ``` 페이지 멘션 [#페이지-멘션] ``` @대시보드 페이지에 매출 차트를 추가해줘 @프로젝트_개요 페이지의 제목을 바꿔줘 ``` 워크플로우 멘션 [#워크플로우-멘션] ``` @신규고객알림 워크플로우를 비활성화해줘 @재고알림 워크플로우의 조건을 변경해줘 ``` *** 대화 전략 [#대화-전략] 점진적 상세화 [#점진적-상세화] 큰 그림부터 시작하여 **점점 상세하게** 들어갑니다. ``` 1. "영업팀을 위한 시스템이 필요해" → 테일러가 제안 2. "좋아, 고객사 데이터모델에 업종 속성도 추가해줘" → 세부 수정 3. "업종 옵션은 IT, 제조, 서비스, 기타로 해줘" → 더 세부 수정 ``` 피드백 제공 [#피드백-제공] 테일러의 결과에 **피드백**을 주면 더 나은 결과를 얻습니다. ``` 테일러: [데이터모델 생성 완료] 사용자: "좋은데, 다음을 수정해줘: - 담당자는 여러 명 선택 가능해야 해 - 상태 옵션에 '보류'도 추가해줘 - 우선순위는 상/중/하로 바꿔줘" ``` 확인 요청 [#확인-요청] 중요한 작업 전에 **확인을 요청**할 수 있습니다. ``` "이 구조로 데이터모델을 만들기 전에 한번 확인해줘" "실제로 삭제하기 전에 영향 받는 데이터가 있는지 알려줘" ``` *** 자주 하는 실수 [#자주-하는-실수] ❌ 너무 모호한 요청 [#-너무-모호한-요청] ``` ❌ "뭔가 좋은 거 만들어줘" ❌ "시스템 개선해줘" ``` ❌ 한 번에 너무 많은 요청 [#-한-번에-너무-많은-요청] ``` ❌ "CRM 만들고, 프로젝트 관리도 추가하고, 재고 시스템도 만들고, 전부 연동해줘" ``` → 하나씩 단계별로 요청하세요. ❌ 맥락 없이 속성명만 [#-맥락-없이-속성명만] ``` ❌ "필드 추가해줘" ❌ "이거 바꿔줘" ``` → 어떤 데이터모델에, 어떤 속성을, 어떻게 변경할지 명시하세요. *** 빠른 참조 [#빠른-참조] 자주 사용하는 프롬프트 [#자주-사용하는-프롬프트] | 목적 | 프롬프트 | | ------------- | ---------------------------- | | **워크스페이스 파악** | "현재 워크스페이스 요약해줘" | | **데이터모델 생성** | "\[목적]을 위한 데이터모델을 만들어줘" | | **속성 추가** | "@\[모델명]에 \[속성명] 속성을 추가해줘" | | **샘플 데이터** | "@\[모델명]에 샘플 데이터 10개 넣어줘" | | **분석** | "@\[모델명]의 \[기준]별 현황을 분석해줘" | | **워크플로우** | "\[조건]일 때 \[액션]하는 자동화를 만들어줘" | *** 다음 단계 [#다음-단계] * [활용 예시](/docs/taylor-ai/examples) - 실제 사용 사례 확인 * [도구](/docs/taylor-ai/tools) - 50개 도구 상세 --- # 시맨틱 검색 (/docs/taylor-ai/semantic-search) > AI가 워크스페이스 데이터를 의미 기반으로 검색하는 기능 개요 [#개요] 시맨틱 검색은 Taylor AI가 워크스페이스의 데이터를 **의미 기반으로 검색**할 수 있게 해주는 기능입니다. 기존에는 "오늘 할 일" 같은 질문에 AI가 여러 번의 도구 호출(데이터모델 목록 조회 → 상세 조회 → 행 조회)을 해야 했습니다. 시맨틱 검색을 사용하면 **1-2회의 호출**로 관련 데이터를 바로 찾을 수 있습니다. 작동 방식 [#작동-방식] 1. 자동 인덱싱 [#1-자동-인덱싱] 데이터모델의 행이 변경될 때마다 자동으로 인덱싱됩니다: ``` 데이터 변경 → 벡터 임베딩 생성 → 인덱스 저장 ``` 인덱싱되는 정보: * 행의 제목 * 모든 속성값 (속성명 + 타입 + 값) * 데이터모델 이름 * 메타데이터 (날짜, 담당자 등) 2. 의미 기반 검색 [#2-의미-기반-검색] AI가 `semantic_search` 도구를 사용하여 검색합니다: ``` 사용자: "오늘 마감인 업무 알려줘" ↓ AI: semantic_search("오늘 마감인 업무", { date_gte: "2025-02-05" }) ↓ 벡터 유사도 검색 + 날짜 필터 ↓ 관련 데이터 반환 ``` 사용 예시 [#사용-예시] 기본 검색 [#기본-검색] ``` "고객 피드백 찾아줘" "버그 관련 이슈" "김철수 담당 업무" ``` 필터 조합 [#필터-조합] ``` "이번 주 마감인 업무" → 날짜 필터 자동 적용 "김철수가 담당하는 진행 중인 작업" → 담당자 + 키워드 검색 "지난달 완료된 프로젝트" → 날짜 범위 + 키워드 검색 ``` 인덱싱 대상 [#인덱싱-대상] 현재 지원되는 인덱싱 대상: | 대상 | 설명 | 상태 | | ------- | ----------- | ----- | | 데이터모델 행 | 모든 데이터모델의 행 | ✅ 지원 | | 페이지 본문 | 페이지 내용 | 🔜 예정 | | 블록 콘텐츠 | 개별 블록 내용 | 🔜 예정 | 필터 옵션 [#필터-옵션] `semantic_search` 도구에서 사용 가능한 필터: | 필터 | 설명 | 예시 | | ------------- | -------- | ----------------------- | | `source_type` | 검색 대상 유형 | `datamodel_row`, `page` | | `date_gte` | 시작 날짜 | `2025-02-01` | | `date_lte` | 종료 날짜 | `2025-02-28` | | `assignee_id` | 담당자 ID | 사용자 ID | 성능 개선 [#성능-개선] 시맨틱 검색 도입 전후 비교: | 지표 | Before | After | | ------- | ------ | ----- | | LLM 호출 | 3회 | 1-2회 | | Tool 호출 | 3회 | 1회 | | 토큰 사용량 | \~45K | \~15K | | 응답 시간 | \~8초 | \~3초 | 초기 인덱싱 [#초기-인덱싱] 기존 데이터가 있는 경우, 초기 인덱싱 스크립트를 실행합니다: ```bash # 모든 워크스페이스 인덱싱 bun run scripts/initial-content-indexing.ts # 특정 워크스페이스만 인덱싱 bun run scripts/initial-content-indexing.ts [workspace-id] ``` 기술 스택 [#기술-스택] * **벡터 DB**: Neon PostgreSQL + pgvector * **임베딩 모델**: Google Gemini text-embedding-004 (768차원) * **인덱스 타입**: HNSW (코사인 유사도) * **Queue**: pgboss (비동기 처리) 제한사항 [#제한사항] * 임베딩 생성에 약간의 지연이 있을 수 있음 (비동기 처리) * 초기 인덱싱 시 Gemini API 속도 제한 고려 필요 * 현재 데이터모델 행만 지원 (페이지/블록은 추후 지원 예정) --- # 스킬 (/docs/taylor-ai/skills) > Taylor AI가 사용하는 스킬 시스템에 대해 알아봅니다. import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; 스킬이란? [#스킬이란] **스킬**은 테일러 AI가 특정 업무를 수행할 때 참고하는 전문 지식과 가이드라인입니다. 예를 들어, "CRM 만들어줘"라고 요청하면 테일러는 **CRM 스킬**을 로드하여: * Salesforce The Model 프레임워크 기반 설계 * 리드 스코어링, BANT 프레임워크 적용 * 영업 파이프라인 최적 구조 반영 등 전문적인 CRM 시스템을 구축합니다. *** 스킬 종류 [#스킬-종류] 기본 스킬 [#기본-스킬] 모든 워크스페이스에서 사용할 수 있는 기본 제공 스킬입니다. | 스킬 | 설명 | 활용 예시 | | ----------- | ------------------- | ---------------------- | | **CRM** | CRM/영업 시스템 전문가 | "B2B 영업팀용 CRM 만들어줘" | | **GTM** | Go-To-Market 전략 마스터 | "Outbound 영업 시스템 구축해줘" | | **Finance** | 재무회계 시스템 전문가 | "거래내역 기반 손익계산서 만들어줘" | | **HR** | HR/인사관리 시스템 전문가 | "직원관리 및 급여 시스템 만들어줘" | <Callout type="info"> 기본 스킬은 지속적으로 추가됩니다. 특정 도메인의 스킬이 필요하시면 요청해 주세요. </Callout> 커스텀 스킬 [#커스텀-스킬] 워크스페이스에서 직접 만들 수 있는 맞춤형 스킬입니다. * **워크스페이스 설정 > AI 스킬**에서 관리 * 우리 회사만의 업무 지침, 용어, 프로세스 정의 가능 * 같은 이름의 기본 스킬이 있으면 커스텀 스킬이 우선 적용 *** 기본 스킬 상세 [#기본-스킬-상세] CRM 스킬 [#crm-스킬] CRM/영업 시스템을 전문적으로 설계하고 구축합니다. **주요 기능:** * Salesforce The Model 프레임워크 기반 파이프라인 설계 * 리드 스코어링 모델 (행동 점수 + 인구통계 점수) * BANT 프레임워크 (Budget, Authority, Need, Timeline) * 비즈니스 유형별 최적 CRM 패턴 (B2B SaaS, B2B 서비스, B2C) **활용 예시:** ``` "B2B SaaS 영업팀을 위한 CRM 만들어줘" "리드 관리 시스템 구축해줘" "영업 파이프라인 칸반 보드 만들어줘" ``` **생성되는 구성요소:** * 데이터모델: 리드, 연락처, 회사, 영업기회, 활동 * 자동화: 신규 리드 알림, MQL 전환 알림, 거래 성사 처리 * 대시보드: 파이프라인 퍼널, 담당자별 실적 *** GTM 스킬 [#gtm-스킬] B2B SaaS Go-To-Market 전략의 완전한 가이드입니다. **주요 기능:** * All-Bound GTM 프레임워크 (Outbound + Website) * Outbound 4대 요소 (Right Target, Timing, Message, Engage) * MEDDPICC 프레임워크로 거래 검증 * Clay 기반 GTM 엔진 구축 **활용 예시:** ``` "Outbound 영업 시스템 만들어줘" "정부지원사업 선정 기업 자동 수집 워크플로우 만들어줘" "MEDDPICC 체크리스트 관리 시스템 구축해줘" ``` **생성되는 구성요소:** * 데이터모델: 타겟 어카운트, 연락처, 영업기회, MEDDPICC 체크리스트 * 자동화: 리드 자동 수집, 시퀀스 자동 진행, Forecast 리포트 * 대시보드: 파이프라인 현황, Outbound 성과, Win Rate 분석 *** Finance 스킬 [#finance-스킬] 재무회계 시스템을 전문적으로 설계하고 구축합니다. **주요 기능:** * 복식부기 원칙 기반 거래내역 중심 설계 * 거래내역 단일입력 → 손익계산서/재무제표 자동 생성 * 계정과목 3단계 계층 (대분류 > 중분류 > 계정명) * 기업 규모별 맞춤 설계 (초기 스타트업 → 성장 → Pre-IPO) **활용 예시:** ``` "거래내역 기반 손익계산서 만들어줘" "월별 매출/비용 분석 대시보드 구축해줘" "계정과목 체계 설계해줘" ``` **생성되는 구성요소:** * 데이터모델: 거래내역, 계정과목, 거래처, 은행계좌, 예산 * 자동화: 대금 거래 알림, 예산 초과 경고, 월말 마감 리마인더 * 대시보드: 손익계산서 피벗, 현금흐름 추이, 계정과목별 비율 **한국 특화:** * 부가세 관리 (과세/면세/영세율/불공제) * 세금계산서 연동 * K-GAAP / K-IFRS 기준 지원 *** HR 스킬 [#hr-스킬] HR/인사관리 시스템을 전문적으로 설계하고 구축합니다. **주요 기능:** * Employee Lifecycle 기반 설계 (채용→온보딩→성과→급여→퇴직) * HRM(인사관리) + HRD(인적자원개발) + 성과관리 통합 * OKR/KPI 기반 목표 관리 * 기업 규모별 맞춤 설계 (초기 → 성장 → 대기업) **활용 예시:** ``` "직원관리 시스템 만들어줘" "급여 및 근태 관리 구축해줘" "OKR 기반 성과관리 시스템 만들어줘" "알바 관리 시스템 구축해줘" ``` **생성되는 구성요소:** * 데이터모델: 직원, 근태기록, 급여대장, 휴가, 성과목표, 채용공고, 지원자 * 자동화: 입사 온보딩, 계약만료 알림, 급여 리마인더, 52시간 초과 경고 * 대시보드: 직원 현황, 채용 파이프라인, 근태 현황, 급여 추이 **한국 특화:** * 4대보험 계산 (국민연금, 건강보험, 장기요양, 고용보험) * 주휴수당 자동 계산 (알바/파트타임) * 52시간제 모니터링 * 원천징수 관리 *** 커스텀 스킬 만들기 [#커스텀-스킬-만들기] 스킬 생성 위치 [#스킬-생성-위치] **워크스페이스 설정 > AI 스킬** 탭에서 커스텀 스킬을 관리할 수 있습니다. 스킬 구성 요소 [#스킬-구성-요소] | 필드 | 설명 | 예시 | | --------- | -------------------- | ----------------- | | **스킬 ID** | 고유 식별자 (영문, 숫자, 하이픈) | `sales-playbook` | | **표시 이름** | 사용자에게 보여지는 이름 | 영업 플레이북 | | **설명** | 스킬의 용도 설명 | 우리 회사 영업 프로세스 가이드 | | **내용** | 실제 가이드라인 (마크다운) | 상세 지침 작성 | 좋은 스킬 작성 팁 [#좋은-스킬-작성-팁] <Callout type="tip"> **구체적이고 실행 가능한 지침을 작성하세요.** ❌ "고객 관리를 잘 해라" ✅ "신규 고객 등록 시 24시간 내 환영 이메일 발송, 담당자 지정, Slack #sales-new 알림" </Callout> **포함하면 좋은 내용:** * 우리 회사 용어 정의 * 데이터 모델 구조 권장안 * 필수 속성과 선택 속성 * 자동화 워크플로우 권장안 * 샘플 데이터 형식 *** 스킬 우선순위 [#스킬-우선순위] 같은 이름의 스킬이 여러 개 있을 때: ``` 커스텀 스킬 > 기본 스킬 ``` 예를 들어, 커스텀 `crm` 스킬을 만들면 기본 CRM 스킬 대신 커스텀 스킬이 사용됩니다. *** AI 도구로 스킬 관리 [#ai-도구로-스킬-관리] 테일러 AI에게 직접 스킬 관리를 요청할 수도 있습니다. ``` "현재 사용 가능한 스킬 목록 보여줘" "우리 회사 영업 프로세스를 스킬로 만들어줘" "CRM 스킬 내용 보여줘" ``` <Cards> <Card title="도구" description="50개 도구의 상세 설명" href="/docs/taylor-ai/tools" /> <Card title="효과적인 프롬프팅" description="Taylor를 잘 활용하는 방법" href="/docs/taylor-ai/prompting-tips" /> </Cards> --- # 도구 (/docs/taylor-ai/tools) > Taylor AI가 제공하는 58개 도구를 카테고리별로 알아보세요. import { Callout } from 'fumadocs-ui/components/callout'; Taylor는 **58개의 도구**를 사용하여 워크스페이스를 관리합니다. 도구 요약 [#도구-요약] | 카테고리 | 도구 수 | 기능 | | ---------- | :--: | ----------------------------- | | **검색** | 2개 | 도구 검색, 시맨틱 검색 | | **시스템** | 1개 | 도구 실행 결과 상세 조회 | | **스킬** | 5개 | AI 스킬 관리 | | **블록** | 6개 | 페이지 콘텐츠 생성, 수정, 부분 수정, 삭제, 검색 | | **데이터모델** | 13개 | 테이블 생성, 속성 정의, 데이터 CRUD, 템플릿 | | **통계** | 8개 | SQL 쿼리 작성, 데이터 시각화 | | **워크플로우** | 17개 | 자동화 워크플로우 생성, 테스트, 배포, 실행 | | **워크스페이스** | 2개 | 워크스페이스 구조 요약, 알림 조회 | | **웹** | 2개 | 웹 검색, 웹 페이지 가져오기 | | **메모리** | 2개 | 정보 저장, 메모리 검색 | *** 블록 도구 (6개) [#블록-도구-6개] 페이지의 콘텐츠를 관리합니다. 블록 생성 (create_blocks) [#블록-생성-create_blocks] 페이지에 새로운 블록을 추가합니다. ``` "프로젝트 개요 페이지에 제목과 설명을 추가해줘" "대시보드에 데이터모델 뷰 블록을 넣어줘" ``` **지원 블록 타입:** * 텍스트: 제목, 단락, 리스트, 인용문, 콜아웃 * 미디어: 이미지, 동영상 * 데이터: 데이터모델 뷰, 통계 블록, 테이블 * 레이아웃: 컬럼, 탭, 버튼 블록 수정 (update_blocks) [#블록-수정-update_blocks] 기존 블록의 내용이나 설정을 변경합니다. ``` "첫 번째 제목을 '프로젝트 현황'으로 변경해줘" "콜아웃의 색상을 파란색으로 바꿔줘" ``` 블록 삭제 (delete_blocks) [#블록-삭제-delete_blocks] 페이지에서 블록을 제거합니다. ``` "두 번째 단락을 삭제해줘" "불필요한 구분선들을 정리해줘" ``` 블록 검색 (search_blocks) [#블록-검색-search_blocks] 워크스페이스 내 블록을 검색합니다. ``` "프로젝트라는 제목이 있는 블록을 찾아줘" ``` 블록 상세 조회 (get_block_details) [#블록-상세-조회-get_block_details] 특정 블록의 상세 정보를 조회합니다. 블록 부분 수정 (patch_block_content) [#블록-부분-수정-patch_block_content] 블록의 콘텐츠 중 특정 부분만 교체합니다. Artifact, 데이터모델, 통계 블록, 선택 처리, 커스텀 블록 등 `blockContentJson`을 가진 블록에서 HTML/CSS/JS의 일부분만 변경할 때 사용합니다. ``` "아티팩트 블록의 배경색을 파란색으로 변경해줘" "차트 블록의 제목 텍스트만 수정해줘" ``` 전체 콘텐츠를 교체하려면 `update_blocks`를, 부분 수정이 필요하면 `patch_block_content`를 사용합니다. *** 데이터모델 도구 (13개) [#데이터모델-도구-13개] 데이터 구조를 설계하고 데이터를 관리합니다. 데이터모델 생성 (create_datamodel) [#데이터모델-생성-create_datamodel] 새로운 데이터모델을 만듭니다. ``` "고객 정보를 관리할 데이터모델을 만들어줘" "태스크 관리용 테이블이 필요해" ``` **자동으로 설정하는 것:** * 제목 및 설명 * 아이콘 * 속성 정의 (타입, 옵션) * 샘플 데이터 (요청 시) 데이터모델 수정 (update_datamodel) [#데이터모델-수정-update_datamodel] 데이터모델의 기본 정보를 변경합니다. ``` "고객 데이터모델 이름을 '거래처'로 바꿔줘" "설명을 추가해줘" ``` 데이터모델 삭제 (delete_datamodel) [#데이터모델-삭제-delete_datamodel] 데이터모델을 삭제합니다. <Callout type="warn"> 데이터모델 삭제 시 모든 데이터가 영구 삭제됩니다. Taylor가 확인을 요청합니다. </Callout> 데이터모델 목록 (list_datamodels) [#데이터모델-목록-list_datamodels] 워크스페이스의 데이터모델 목록을 조회합니다. ``` "현재 워크스페이스에 어떤 데이터모델이 있어?" ``` 데이터모델 상세 (get_datamodel_details) [#데이터모델-상세-get_datamodel_details] 특정 데이터모델의 구조를 확인합니다. ``` "고객 데이터모델의 속성들을 알려줘" "태스크 모델의 구조를 설명해줘" ``` 속성 관리 (manage_datamodel_properties) [#속성-관리-manage_datamodel_properties] 데이터모델의 속성을 추가, 수정, 삭제합니다. ``` "고객 데이터모델에 '등급' 선택 속성을 추가해줘" "마감일 속성을 필수로 변경해줘" "불필요한 메모 속성을 삭제해줘" ``` **지원하는 속성 타입 (16가지):** * 기본: 제목, 텍스트, 숫자, 통화 * 선택: 단일 선택, 다중 선택 * 날짜: 날짜, 체크박스 * 사용자: 담당자 * 미디어: 파일 * 연락처: URL, 이메일, 전화번호 * 관계: 관계, 롤업 * 계산: 수식 * 액션: 버튼 행 추가/수정 (upsert_datamodel_rows) [#행-추가수정-upsert_datamodel_rows] 데이터모델에 새 행을 추가하거나 기존 행을 수정합니다. ``` "고객 데이터모델에 샘플 데이터 10개 넣어줘" "테스트용 태스크 5개를 만들어줘" ``` 행 삭제 (delete_datamodel_rows) [#행-삭제-delete_datamodel_rows] 데이터모델에서 행을 삭제합니다. ``` "완료된 태스크들을 삭제해줘" "테스트 데이터를 모두 지워줘" ``` 행 조회 (query_datamodel_rows) [#행-조회-query_datamodel_rows] 조건에 맞는 데이터를 조회합니다. ``` "진행 중인 태스크 목록을 보여줘" "이번 달 신규 고객은 몇 명이야?" ``` 셀 수정 (update_datamodel_cells) [#셀-수정-update_datamodel_cells] 특정 행의 특정 속성 값을 변경합니다. ``` "첫 번째 태스크의 상태를 완료로 바꿔줘" "모든 VIP 고객의 담당자를 김철수로 변경해줘" ``` 템플릿 생성 (create_datarow_template) [#템플릿-생성-create_datarow_template] 데이터 행의 기본 구조를 정의하는 템플릿을 생성합니다. ``` "회의록 템플릿을 만들어줘" "버그 리포트 템플릿이 필요해" ``` 템플릿 수정 (update_datarow_template) [#템플릿-수정-update_datarow_template] 기존 템플릿을 수정합니다. 템플릿 목록 (list_datarow_templates) [#템플릿-목록-list_datarow_templates] 데이터모델의 템플릿 목록을 조회합니다. *** 통계 도구 (8개) [#통계-도구-8개] 데이터 분석과 시각화를 수행합니다. 통계 정의 생성 (create_statdefinition) [#통계-정의-생성-create_statdefinition] SQL 쿼리 기반의 통계를 정의합니다. ``` "카테고리별 매출 합계를 보여주는 차트를 만들어줘" "월별 신규 고객 추이 그래프가 필요해" ``` 통계 실행 (run_statdefinition) [#통계-실행-run_statdefinition] 정의된 통계를 실행하여 결과를 가져옵니다. ``` "매출 통계를 새로 계산해줘" ``` 통계 목록 (list_statdefinitions) [#통계-목록-list_statdefinitions] 워크스페이스의 통계 정의 목록을 조회합니다. 통계 수정 (update_statdefinition) [#통계-수정-update_statdefinition] 기존 통계 정의를 수정합니다. ``` "매출 차트에 전년 대비 비교를 추가해줘" ``` 통계 삭제 (delete_statdefinition) [#통계-삭제-delete_statdefinition] 통계 정의를 삭제합니다. 통계 컨텍스트 (get_stat_context) [#통계-컨텍스트-get_stat_context] 통계 작성을 위한 데이터베이스 스키마 정보를 제공합니다. 통계 상세 (get_statdefinition_details) [#통계-상세-get_statdefinition_details] 특정 통계의 상세 정보를 조회합니다. 통계 데이터 (get_statdefinition_data) [#통계-데이터-get_statdefinition_data] 통계의 실제 데이터를 가져옵니다. *** 워크플로우 도구 (17개) [#워크플로우-도구-17개] 자동화를 설계하고 관리합니다. 초안 관리 [#초안-관리] 워크플로우 초안 생성 (create_workflow_draft) [#워크플로우-초안-생성-create_workflow_draft] 새 워크플로우를 설계합니다. ``` "새 고객 등록 시 환영 이메일 보내는 자동화를 만들어줘" "마감일 하루 전 리마인더 워크플로우가 필요해" ``` **자동 구성:** * 트리거 설정 (데이터 변경, 일정, 웹훅 등) * 조건 설정 * 액션 순서 워크플로우 초안 수정 (update_workflow_draft) [#워크플로우-초안-수정-update_workflow_draft] 기존 워크플로우를 수정합니다. ``` "리마인더 발송 시간을 3일 전으로 바꿔줘" "슬랙 알림도 추가해줘" ``` 워크플로우 초안 조회 (get_workflow_draft) [#워크플로우-초안-조회-get_workflow_draft] 작성 중인 워크플로우의 내용을 확인합니다. 노드/엣지 세분화 수정 [#노드엣지-세분화-수정] 노드 추가 (add_workflow_nodes) [#노드-추가-add_workflow_nodes] 워크플로우에 새 노드를 추가합니다. 노드 삭제 (delete_workflow_nodes) [#노드-삭제-delete_workflow_nodes] 워크플로우에서 노드를 삭제합니다. 노드 부분 수정 (patch_workflow_nodes) [#노드-부분-수정-patch_workflow_nodes] 기존 노드의 특정 속성만 수정합니다. 엣지 추가 (add_workflow_edges) [#엣지-추가-add_workflow_edges] 노드 간 연결을 추가합니다. 엣지 삭제 (delete_workflow_edges) [#엣지-삭제-delete_workflow_edges] 노드 간 연결을 삭제합니다. 실행 및 배포 [#실행-및-배포] 워크플로우 Draft 실행 (run_workflow_draft) [#워크플로우-draft-실행-run_workflow_draft] 워크플로우를 실제 배포 전 테스트합니다. ``` "이 워크플로우를 테스트해봐" ``` 워크플로우 배포 (deploy_workflow) [#워크플로우-배포-deploy_workflow] Draft를 실제 운영 버전으로 배포합니다. ``` "이 워크플로우를 배포해줘" ``` 워크플로우 실행 (run_workflow) [#워크플로우-실행-run_workflow] 배포된 워크플로우를 수동으로 실행합니다. ``` "리마인더 워크플로우를 지금 실행해줘" ``` 조회 및 관리 [#조회-및-관리] 워크플로우 목록 (list_workflows) [#워크플로우-목록-list_workflows] 워크스페이스의 워크플로우 목록을 조회합니다. ``` "현재 활성화된 워크플로우가 뭐가 있어?" ``` 워크플로우 상세 (get_workflow_details) [#워크플로우-상세-get_workflow_details] 특정 워크플로우의 상세 설정을 확인합니다. 워크플로우 삭제 (delete_workflow) [#워크플로우-삭제-delete_workflow] 워크플로우를 삭제합니다. 노드 타입 조회 (list_workflow_node_types) [#노드-타입-조회-list_workflow_node_types] 사용 가능한 워크플로우 노드(트리거, 액션)를 조회합니다. 실행 기록 [#실행-기록] 실행 기록 목록 (list_workflow_runs) [#실행-기록-목록-list_workflow_runs] 워크플로우 실행 이력을 조회합니다. ``` "최근 워크플로우 실행 기록 보여줘" ``` 실행 상세 조회 (get_workflow_run) [#실행-상세-조회-get_workflow_run] 특정 실행의 상세 정보를 조회합니다. 노드별 실행 결과, 에러 정보 등을 확인할 수 있습니다. *** 스킬 도구 (5개) [#스킬-도구-5개] AI 스킬을 관리합니다. 스킬 로드 (read_skill) [#스킬-로드-read_skill] 특정 스킬의 내용을 로드합니다. 스킬 목록 (list_skills) [#스킬-목록-list_skills] 사용 가능한 스킬 목록을 조회합니다. 스킬 생성 (create_skill) [#스킬-생성-create_skill] 새로운 커스텀 스킬을 생성합니다. ``` "우리 회사 영업 프로세스를 스킬로 만들어줘" ``` 스킬 수정 (update_skill) [#스킬-수정-update_skill] 기존 스킬을 수정합니다. 스킬 삭제 (delete_skill) [#스킬-삭제-delete_skill] 스킬을 삭제합니다. *** 워크스페이스 도구 (2개) [#워크스페이스-도구-2개] 워크스페이스 요약 (get_workspace_summary) [#워크스페이스-요약-get_workspace_summary] 현재 워크스페이스의 전체 구조를 요약합니다. ``` "현재 워크스페이스 요약해줘" "어떤 데이터모델과 페이지가 있어?" ``` **응답에 포함되는 정보:** * 데이터모델 목록 (속성, 행 수) * 페이지 목록 * 워크플로우 목록 * 관계 구조 알림 조회 (query_notifications) [#알림-조회-query_notifications] 워크스페이스의 알림을 조회합니다. 소스(시스템/AI/사용자), 카테고리, 시간 범위 등으로 필터링할 수 있습니다. ``` "최근 24시간 알림 보여줘" "워크플로우 실패 알림이 있어?" "AI가 분석한 인사이트를 확인해줘" ``` **지원 필터:** * 소스별: 시스템 이벤트, AI 인사이트, 사용자 멘션/댓글 * 카테고리별: 워크플로우 완료/실패, 데이터 가져오기, AI 제안, 승인 요청 등 * 시간별: 최근 N시간 이내 *** 검색/탐색 도구 (2개) [#검색탐색-도구-2개] 도구 검색 (search_tools) [#도구-검색-search_tools] 사용 가능한 도구를 검색합니다. ``` "데이터모델 관련 도구 찾아줘" ``` 시맨틱 검색 (semantic_search) [#시맨틱-검색-semantic_search] 워크스페이스 내 콘텐츠를 의미 기반으로 검색합니다. *** 웹 도구 (2개) [#웹-도구-2개] 외부 웹 정보를 활용합니다. 웹 검색 (web_search) [#웹-검색-web_search] 인터넷에서 정보를 검색합니다. ``` "최신 Next.js 15 변경사항을 찾아줘" "경쟁사 가격 정보를 조사해줘" ``` 웹 페이지 가져오기 (web_fetch) [#웹-페이지-가져오기-web_fetch] 특정 URL의 웹 페이지 내용을 가져옵니다. ``` "이 URL의 내용을 가져와서 요약해줘" ``` *** 메모리 도구 (2개) [#메모리-도구-2개] 대화 간 정보를 저장하고 검색합니다. 메모리 저장 (save_memory) [#메모리-저장-save_memory] 중요한 정보를 워크스페이스 또는 사용자 메모리에 저장합니다. 사용자 선호, 비즈니스 규칙, 도메인 용어 등을 기억하여 이후 대화에서 활용합니다. ``` "우리 회사 결산일은 매월 25일이라는 걸 기억해줘" "날짜 형식은 항상 YYYY-MM-DD로 해줘" ``` 메모리 검색 (search_memory) [#메모리-검색-search_memory] 저장된 메모리에서 관련 정보를 검색합니다. 이전 대화에서 저장한 선호 설정, 비즈니스 규칙 등을 조회합니다. *** 도구 사용 예시 [#도구-사용-예시] 복합 작업 [#복합-작업] Taylor는 여러 도구를 **조합하여** 복잡한 작업을 수행합니다. ``` 사용자: "재고 관리 시스템을 만들어줘" Taylor의 도구 사용: 1. create_datamodel: 상품 데이터모델 생성 2. manage_datamodel_properties: 재고량, 안전재고 속성 추가 3. create_datamodel: 입출고 데이터모델 생성 4. manage_datamodel_properties: 관계 속성 설정 5. upsert_datamodel_rows: 샘플 데이터 추가 6. create_workflow_draft: 저재고 알림 워크플로우 생성 7. create_blocks: 대시보드 페이지 구성 ``` 맥락 기반 추론 [#맥락-기반-추론] Taylor는 대화 맥락을 이해하여 **암묵적인 요구사항**도 처리합니다. ``` 사용자: "고객 등급을 추가하고 싶어" Taylor가 추론하는 것: - "고객" 데이터모델이 있는지 확인 - "등급"은 선택 타입이 적합 - 일반적인 등급: VIP, 일반, 신규 → 확인 없이 바로 적절한 설정으로 추가 ``` *** 다음 단계 [#다음-단계] * [효과적인 프롬프팅](/docs/taylor-ai/prompting-tips) - Taylor를 잘 활용하는 방법 * [활용 예시](/docs/taylor-ai/examples) - 실제 사용 사례 --- # 액션 (/docs/workflows/actions) > 워크플로우에서 실행할 작업을 설정하세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; 액션 카테고리 [#액션-카테고리] 슈츠는 다양한 종류의 액션을 제공합니다. | 카테고리 | 설명 | 예시 | | ----------- | ----------- | ------------------------------ | | **알림** | 사용자에게 알림 전송 | 슬랙, 이메일, 인앱 알림 | | **데이터** | 데이터모델 조작 | 행 생성/수정/삭제/조회 | | **연동** | 외부 서비스 연동 | HTTP 요청, Google Sheets, OpenAI | | **국내 비즈니스** | 국내 플랫폼 연동 | 카페24, 아임웹, 네이버커머스, 볼타 | | **제어** | 워크플로우 흐름 제어 | 조건 분기, 지연, 반복, 코드 | <Callout type="tip"> 각 액션의 **상세 설정 옵션과 활용 예시**는 [노드 레퍼런스](/docs/node-reference/actions)에서 확인하세요. </Callout> *** 액션 추가하기 [#액션-추가하기] 1. 워크플로우 편집 화면에서 **+ 액션 추가** 클릭 2. 원하는 액션 유형 선택 3. 필요한 설정 입력 4. 테스트 실행으로 동작 확인 *** 액션 연결 [#액션-연결] 액션들은 **순차적으로 실행**됩니다. 이전 액션의 결과를 다음 액션에서 사용할 수 있습니다. ``` 트리거 ↓ 액션 1: 행 조회 ↓ 액션 2: 조건 분기 (조회 결과 확인) ↓ 액션 3: 슬랙 메시지 발송 ``` *** 변수 시스템 [#변수-시스템] 액션에서 **동적 값**을 사용합니다. 트리거 데이터 [#트리거-데이터] ``` {{trigger.row.속성이름}} // 트리거된 행의 속성 값 {{trigger.row.id}} // 트리거된 행의 ID {{trigger.event}} // 트리거 이벤트 타입 ``` 이전 액션 결과 [#이전-액션-결과] ``` {{actions.액션이름.result}} // 이전 액션의 결과 {{actions.http.response}} // HTTP 응답 {{actions.query.rows}} // 조회된 행 목록 ``` 내장 함수 [#내장-함수] | 함수 | 설명 | 예시 | | ---------- | -------- | ------------------------------------ | | `now` | 현재 날짜/시간 | `{{now}}` | | `today` | 오늘 날짜 | `{{today}}` | | `format` | 포맷팅 | `{{format(now, "YYYY-MM-DD")}}` | | `dateDiff` | 날짜 차이 | `{{dateDiff(date1, date2, "days")}}` | *** 에러 처리 [#에러-처리] 재시도 정책 [#재시도-정책] 액션 실패 시 **자동 재시도**합니다. | 설정 | 기본값 | | ---------- | ----------- | | **재시도 횟수** | 3회 | | **재시도 간격** | 1분, 5분, 30분 | 실패 시 알림 [#실패-시-알림] 워크플로우 실패 시 관리자에게 알림을 보낼 수 있습니다. *** 액션 레퍼런스 [#액션-레퍼런스] 각 액션의 상세 설명은 **노드 레퍼런스**에서 확인하세요. <Cards> <Card title="알림 액션" description="슬랙, 이메일, 인앱 알림" href="/docs/node-reference/actions/notifications/slack" /> <Card title="데이터 액션" description="행 생성/수정/삭제/조회" href="/docs/node-reference/actions/data/create-row" /> <Card title="연동 액션" description="HTTP, Google Sheets, OpenAI" href="/docs/node-reference/actions/integrations/http-request" /> <Card title="국내 비즈니스" description="카페24, 아임웹, 네이버, 볼타" href="/docs/node-reference/actions/korea-business/cafe24" /> <Card title="제어 액션" description="조건 분기, 지연, 반복, 코드" href="/docs/node-reference/actions/control/condition" /> </Cards> *** 다음 단계 [#다음-단계] * [트리거](/docs/workflows/triggers) - 워크플로우 시작 조건 * [활용 예시](/docs/workflows/examples) - 실제 사용 사례 * [노드 레퍼런스](/docs/node-reference) - 모든 노드 상세 스펙 --- # 승인 프로세스 (/docs/workflows/approval) > 워크플로우 실행 중 사람의 승인을 거쳐 다음 단계를 진행하세요. import { Callout } from 'fumadocs-ui/components/callout'; 승인 프로세스란 [#승인-프로세스란] 승인 프로세스는 워크플로우 실행 중 **사람의 판단이 필요한 지점에서 실행을 일시정지**하고, 지정된 승인자가 승인 또는 거부한 뒤 결과에 따라 워크플로우를 재개하는 기능입니다. ``` 트리거: 구매 요청 접수 ↓ 액션: 견적 데이터 조회 ↓ 승인 대기: 팀장 승인 요청 ← 워크플로우 일시정지 ↓ (승인됨) 액션: 발주서 생성 + 슬랙 알림 ``` 승인 프로세스를 사용하면 자동화와 사람의 의사결정을 자연스럽게 결합할 수 있습니다. *** 승인 정책 설정 [#승인-정책-설정] 승인 정책은 **누가, 어떤 조건으로 승인하는지**를 미리 정의해두는 템플릿입니다. 한번 만들어두면 여러 워크플로우에서 재사용할 수 있습니다. 승인 정책 관리 위치 [#승인-정책-관리-위치] 워크스페이스 설정 > **승인 정책** 메뉴에서 관리합니다. 정책 생성, 수정, 삭제는 ADMIN 이상 권한이 필요합니다. 승인 방식 [#승인-방식] 승인 정책은 두 가지 방식을 지원합니다. | 방식 | 설명 | 적합한 상황 | | ------------------------ | ---------------------- | ------------- | | **한 번에 승인** (parallel) | 모든 승인자에게 동시에 요청을 보냅니다. | 빠른 처리가 필요할 때 | | **차례대로 승인** (sequential) | 단계별로 순서대로 승인을 진행합니다. | 계층적 결재가 필요할 때 | 승인 조건 [#승인-조건] | 조건 | 설명 | | ----------------------- | -------------------------------------------- | | **1명 이상 승인** (any\_one) | 승인자 중 1명만 승인하면 완료됩니다. 모든 승인자가 거부해야 최종 거부됩니다. | | **전원 승인** (all) | 모든 승인자가 승인해야 완료됩니다. 1명이라도 거부하면 즉시 거부됩니다. | 정책 생성 항목 [#정책-생성-항목] | 항목 | 필수 | 설명 | | ---------- | :-: | ----------------------------------- | | 정책 이름 | O | 예: "팀장 승인", "구매 결재" | | 설명 | X | 정책에 대한 부가 설명 | | 승인 방식 | O | 한 번에 승인 / 차례대로 승인 | | 승인자 | O | 워크스페이스 멤버 중 선택 | | 승인 조건 | O | 1명 이상 승인 / 전원 승인 | | 승인 기한 (시간) | X | 비워두면 기한 없이 대기합니다. 초과 시 자동 만료 처리됩니다. | 차례대로 승인 (sequential) 설정 [#차례대로-승인-sequential-설정] 차례대로 승인 방식을 선택하면 **승인 단계**를 추가할 수 있습니다. 최소 2단계가 필요합니다. 각 단계별로 다음을 설정합니다. | 항목 | 설명 | | ------- | ----------------------------- | | 단계 이름 | 예: "팀장 승인", "부서장 승인", "최종 승인" | | 승인자 | 해당 단계의 승인자 | | 승인 조건 | 해당 단계의 승인 조건 (1명 이상 / 전원) | | 기한 (시간) | 해당 단계의 승인 기한 (선택) | <Callout type="info"> 차례대로 승인에서는 이전 단계가 승인 완료되어야 다음 단계 승인자에게 요청이 전달됩니다. 어느 단계에서든 거부되면 전체 승인 요청이 즉시 거부됩니다. </Callout> *** 승인 대기 노드 사용법 [#승인-대기-노드-사용법] 워크플로우 편집 화면에서 **승인 대기** 노드를 추가하여 승인 프로세스를 구성합니다. 노드 설정 항목 [#노드-설정-항목] | 항목 | 설명 | 기본값 | | ------------- | ------------------------------------------------------- | ----- | | 승인 정책 | 미리 만들어둔 승인 정책을 선택합니다. 선택하지 않으면 승인자를 직접 지정합니다. | (없음) | | 승인자 (userId) | 정책을 선택하지 않았을 때, 승인자 userId를 콤마로 구분하여 입력합니다. 표현식을 지원합니다. | (빈 값) | | 기한 (시간) | 승인 기한입니다. 초과 시 자동 만료 처리됩니다. | 48 | | 승인자에게 전달할 메시지 | 승인 요청과 함께 전달할 메시지입니다. 표현식을 지원합니다. | (빈 값) | | 거부 시 워크플로우 중단 | 승인이 거부되었을 때 워크플로우를 중단할지 여부입니다. | 켜짐 | <Callout type="tip"> 승인 정책을 사용하면 승인자와 조건을 중앙에서 관리할 수 있어 편리합니다. 정책 없이 직접 승인자를 지정할 수도 있습니다. </Callout> 승인 결과 데이터 [#승인-결과-데이터] 승인이 완료되면 다음 노드에서 승인 결과를 사용할 수 있습니다. | 필드 | 설명 | | ------------------- | ------------------------------- | | `decision` | 승인 결과: `APPROVED` 또는 `REJECTED` | | `actorId` | 승인/거부한 사용자 ID | | `comment` | 승인자가 남긴 코멘트 (선택 입력) | | `approvalRequestId` | 승인 요청 고유 ID | *** 승인 요청 알림과 승인 카드 [#승인-요청-알림과-승인-카드] 알림 수신 [#알림-수신] 승인 대기 노드가 실행되면 지정된 승인자에게 **인앱 알림**이 전송됩니다. * 알림 카테고리: `approval_requested` * 알림 제목: "승인 요청: \[노드 이름]" * 차례대로 승인의 경우: "승인 요청 (1/3단계: 팀장 승인): \[노드 이름]" 형태로 현재 단계 정보가 포함됩니다. 승인 카드 UI [#승인-카드-ui] 알림 목록에서 승인 요청 알림을 확인하면, 알림 내부에 **승인 카드**가 인라인으로 표시됩니다. 승인 카드에서 바로 승인 또는 거부를 처리할 수 있습니다. 승인 카드에서 제공하는 기능: | 기능 | 설명 | | ----- | ---------------------------- | | 승인 버튼 | 승인을 처리합니다. | | 거부 버튼 | 거부를 처리합니다. | | 코멘트 | 승인/거부 시 코멘트를 남길 수 있습니다. (선택) | <Callout type="info"> 차례대로 승인의 경우, 승인 카드에 현재 단계 정보(예: "1/3단계")가 표시됩니다. </Callout> *** 승인/거부 처리 후 워크플로우 재개 [#승인거부-처리-후-워크플로우-재개] 승인된 경우 [#승인된-경우] * 워크플로우가 승인 대기 노드의 다음 노드부터 **자동으로 재개**됩니다. * 승인 결과 데이터(`decision`, `actorId`, `comment`)가 다음 노드의 입력 데이터로 전달됩니다. 거부된 경우 [#거부된-경우] * **"거부 시 워크플로우 중단"이 켜져 있으면**: 워크플로우가 실패 상태로 종료됩니다. * **"거부 시 워크플로우 중단"이 꺼져 있으면**: 거부 결과와 함께 워크플로우가 다음 노드로 재개됩니다. 이후 노드에서 `decision` 값을 확인하여 분기 처리할 수 있습니다. 기한 초과 [#기한-초과] 승인 기한이 지나면 해당 승인 요청은 **자동으로 만료(EXPIRED)** 처리됩니다. 워크플로우 실행 상태 [#워크플로우-실행-상태] 승인 대기 중인 워크플로우는 `waiting_approval` 상태로 표시됩니다. 승인 또는 거부가 처리되면 `running` 상태로 전환되어 실행이 재개됩니다. *** 활용 예시 [#활용-예시] 고액 구매 승인 [#고액-구매-승인] ``` 트리거: 구매 요청 데이터 생성 시 ↓ 조건: 금액이 100만원 이상인가? ├─ Yes → 승인 대기 (구매 결재 정책) │ ↓ (승인됨) │ 발주서 자동 생성 + 알림 └─ No → 발주서 자동 생성 + 알림 ``` 콘텐츠 발행 승인 [#콘텐츠-발행-승인] ``` 트리거: 콘텐츠 상태가 "검토 요청"으로 변경 시 ↓ 승인 대기 (편집팀장 승인) ↓ (승인됨) 콘텐츠 상태를 "발행됨"으로 변경 ↓ SNS 자동 공유 + 팀 슬랙 알림 ``` 계층적 결재 (차례대로 승인) [#계층적-결재-차례대로-승인] ``` 트리거: 출장 신청서 제출 시 ↓ 승인 대기 (출장 결재 정책 - 차례대로 승인) 1단계: 팀장 승인 2단계: 부서장 승인 3단계: 경영지원팀 확인 ↓ (전 단계 승인됨) 출장 일정 등록 + 담당자 알림 ``` --- # 활용 예시 (/docs/workflows/examples) > 워크플로우 활용 사례를 살펴보세요. import { Callout } from 'fumadocs-ui/components/callout'; 영업 자동화 [#영업-자동화] 새 리드 알림 및 할당 [#새-리드-알림-및-할당] 새로운 리드가 등록되면 팀에 알리고 자동으로 담당자를 할당합니다. ``` ┌─────────────────────────────────────────────────────────────────┐ │ 🎯 트리거: 리드 데이터모델에 새 행 생성 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 🔀 조건 분기: 리드 소스 확인 │ │ ├── 웹사이트 → 온라인팀 담당자 자동 할당 │ │ ├── 전시회 → 오프라인팀 담당자 자동 할당 │ │ └── 추천 → VIP팀 담당자 자동 할당 │ │ │ │ 📧 이메일: 담당자에게 신규 리드 안내 │ │ │ │ 💬 슬랙: #영업팀 채널에 신규 리드 알림 │ │ "🆕 새 리드: {{회사명}}" │ │ "소스: {{소스}} | 담당: {{담당자}}" │ │ │ │ ⏰ 지연: 24시간 │ │ │ │ 📧 팔로업 리마인더 (담당자 변경 없으면) │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` *** 딜 단계 변경 알림 [#딜-단계-변경-알림] 영업 기회의 단계가 변경되면 관련자에게 알립니다. ``` 트리거: 영업기회의 "단계" 속성 변경 조건: 새 단계 in ["협상", "계약"] 액션: ├── 담당자에게 슈츠 알림 │ "{{고객명}} 딜이 {{새단계}}로 변경되었습니다" │ ├── if 새단계 == "계약": │ ├── 영업팀 슬랙에 🎉 축하 메시지 │ ├── 수주보고서에 행 추가 │ └── 담당자 성과에 반영 │ └── 활동 기록에 단계 변경 로그 추가 ``` *** 견적서 자동 발송 [#견적서-자동-발송] 버튼 클릭으로 견적서를 자동 생성하고 발송합니다. ``` 트리거: [견적서 발송] 버튼 클릭 액션: ├── PDF 생성 │ └── 템플릿에 {{고객명}}, {{품목}}, {{금액}} 삽입 │ ├── 이메일 발송 │ ├── 받는 사람: {{고객이메일}} │ ├── 제목: [{{회사명}}] 견적서 안내 │ └── 첨부: 생성된 PDF │ ├── 견적 상태 → "발송완료" ├── 발송일 → {{now}} │ └── 활동 기록 추가: "견적서 발송" ``` *** 프로젝트 관리 [#프로젝트-관리] 마감일 리마인더 [#마감일-리마인더] 마감일이 다가오는 태스크의 담당자에게 리마인더를 보냅니다. ``` 트리거: 매일 오전 9시 액션: ├── 조회: 마감일이 오늘~3일 이내 AND 상태 ≠ "완료" │ └── 각 태스크에 대해 (반복): │ ├── if 마감일 == 오늘: │ └── 🔴 "오늘 마감입니다!" 긴급 알림 │ ├── if 마감일 == 내일: │ └── 🟡 "내일 마감입니다" 알림 │ └── if 마감일 <= 3일 후: └── 🟢 "곧 마감입니다" 일반 알림 ``` *** 태스크 완료 시 다음 단계 [#태스크-완료-시-다음-단계] 태스크가 완료되면 자동으로 다음 태스크를 시작합니다. ``` 트리거: 태스크 상태가 "완료"로 변경 조건: 다음 태스크가 존재함 액션: ├── 다음 태스크 상태 → "진행 중" │ ├── 다음 담당자에게 알림 │ "{{이전태스크}}가 완료되어 {{현재태스크}}를 시작할 수 있습니다" │ ├── 완료된 태스크에 완료일 기록 │ └── 프로젝트 진행률 자동 업데이트 ``` *** 주간 리포트 자동 생성 [#주간-리포트-자동-생성] 매주 프로젝트 현황을 자동으로 정리하여 공유합니다. ``` 트리거: 매주 금요일 오후 5시 액션: ├── 조회: 이번 주 완료된 태스크 ├── 조회: 이번 주 생성된 태스크 ├── 조회: 지연된 태스크 │ ├── 통계 블록 업데이트 │ ├── 완료율: {{완료수/전체수 * 100}}% │ ├── 신규: {{신규수}}개 │ └── 지연: {{지연수}}개 │ └── 슬랙 #프로젝트 채널에 요약 공유 "📊 주간 리포트 완료: {{완료수}}개 진행중: {{진행중수}}개 지연: {{지연수}}개" ``` *** 고객 관리 [#고객-관리] 신규 고객 온보딩 [#신규-고객-온보딩] 새 고객이 등록되면 온보딩 프로세스를 자동으로 시작합니다. ``` 트리거: 고객 데이터모델에 새 행 생성 액션: ├── 즉시: │ ├── 환영 이메일 발송 │ │ "{{고객명}}님, 환영합니다!" │ │ │ └── 온보딩 체크리스트 생성 (태스크 데이터모델) │ ├── 초기 설정 안내 │ ├── 첫 번째 미팅 예약 │ ├── 교육 자료 전달 │ └── 피드백 수집 │ ├── 담당 CSM에게 알림 │ "새 고객 {{고객명}}이 등록되었습니다" │ ├── 지연 7일: │ └── 진행 상황 체크 이메일 │ "{{고객명}}님, 도움이 필요하신가요?" │ └── 지연 30일: └── 만족도 조사 이메일 ``` *** 계약 만료 알림 [#계약-만료-알림] 계약 만료가 다가오면 담당자에게 알리고 갱신 태스크를 생성합니다. ``` 트리거: 계약 만료일 30일 전 액션: ├── 담당자에게 이메일 │ "{{고객명}} 계약이 30일 후 만료됩니다" │ ├── 갱신 태스크 생성 │ ├── 제목: "{{고객명}} 계약 갱신" │ ├── 담당자: {{현재담당자}} │ └── 마감일: 만료일 7일 전 │ ├── CRM에 활동 기록 │ "계약 만료 30일 전 알림 발송" │ └── if 계약금액 >= 1000만원: └── 관리자에게도 알림 ``` *** 고객 피드백 자동 분류 [#고객-피드백-자동-분류] 고객 피드백이 등록되면 AI로 분류하고 담당 부서에 전달합니다. ``` 트리거: 피드백 데이터모델에 새 행 생성 액션: ├── OpenAI로 피드백 분석 │ ├── 감정: 긍정/부정/중립 │ └── 카테고리: 기능요청/버그/불만/칭찬 │ ├── 분석 결과를 피드백 행에 저장 │ ├── 조건 분기 (카테고리별): │ ├── 버그 → #개발팀 슬랙 + 버그 티켓 생성 │ ├── 기능요청 → #기획팀 슬랙 │ ├── 불만 → #CS팀 슬랙 + 긴급 처리 태스크 │ └── 칭찬 → #전체공유 슬랙 🎉 │ └── if 감정 == "부정": └── CS 담당자에게 즉시 알림 ``` *** 재고 관리 [#재고-관리] 저재고 알림 [#저재고-알림] 재고가 안전 재고량 이하로 떨어지면 알립니다. ``` 트리거: 상품의 "재고량" 속성 변경 조건: 재고량 <= 안전재고량 액션: ├── 재고 상태 → "저재고" │ ├── 구매팀 슬랙 알림 │ "⚠️ {{상품명}} 저재고 알림" │ "현재: {{재고량}}개 / 안전: {{안전재고량}}개" │ ├── 발주 요청 항목 자동 생성 │ ├── 상품: {{상품}} │ ├── 권장 수량: {{안전재고량 * 2 - 재고량}} │ └── 상태: "요청" │ └── 담당자에게 슈츠 알림 ``` *** 입고 완료 처리 [#입고-완료-처리] 입고가 완료되면 재고를 업데이트하고 관련자에게 알립니다. ``` 트리거: 입고의 "상태"가 "완료"로 변경 액션: ├── 상품 재고량 업데이트 │ 재고량 += {{입고수량}} │ ├── 상품 상태 확인 및 업데이트 │ if 재고량 > 안전재고량: │ 상태 → "정상" │ ├── 창고 담당자에게 알림 │ "{{상품명}} {{입고수량}}개 입고 완료" │ ├── 입고 보고서 자동 생성 │ └── 관련 발주 요청 상태 → "완료" ``` *** 이커머스 자동화 [#이커머스-자동화] 카페24 다중 플랫폼 재고 동기화 [#카페24-다중-플랫폼-재고-동기화] 카페24와 다른 플랫폼 간 재고를 실시간 동기화합니다. ``` 트리거: 카페24 웹훅 (주문 완료) 액션: ├── 카페24 재고 조회 │ └── 품목 코드: {{trigger.body.variantCode}} │ ├── 내부 재고 DB 업데이트 │ └── 재고량: {{cafe24.quantity}} │ ├── if 재고량 < 안전재고: │ ├── 카페24 상품 판매 상태 변경 │ │ ├── 상품 번호: {{trigger.body.productNo}} │ │ └── 판매 상태: "품절임박" │ │ │ └── 슬랙 #운영팀 알림 │ "⚠️ {{상품명}} 재고 부족: {{재고량}}개" │ └── 아임웹/스마트스토어 재고도 동기화 ``` *** 스마트스토어 주문 → 배송 알림 [#스마트스토어-주문--배송-알림] 주문이 발송되면 고객에게 네이버톡톡으로 안내합니다. ``` 트리거: 네이버 커머스 주문 상태 변경 (웹훅) 조건: 상태 == "발송완료" 액션: ├── 네이버톡톡 메시지 발송 │ ├── 사용자: {{trigger.body.톡톡사용자ID}} │ ├── 유형: 복합 메시지 │ ├── 제목: "📦 배송이 시작되었습니다!" │ ├── 설명: "{{상품명}}이(가) 출발했습니다." │ └── 버튼: [배송조회 링크] │ ├── 고객 행 수정 │ └── 마지막주문발송일: {{now}} │ └── 슬랙 #CS팀 알림 "{{고객명}}님 주문 발송 완료" ``` *** 아임웹 재고 동기화 [#아임웹-재고-동기화] 재고가 변경되면 자동으로 동기화하고 저재고 알림을 보냅니다. ``` 트리거: 매시간 정각 액션: ├── 아임웹 상품 목록 조회 │ ├── 각 상품에 대해 (반복): │ │ │ ├── 내부 상품 DB와 재고 동기화 │ │ │ └── if 재고 < 10: │ ├── 슬랙 #운영팀 알림 │ │ "⚠️ {{상품명}} 재고 부족: {{재고}}개" │ │ │ └── 아임웹 상품 상태 확인 │ if 재고 == 0: │ 상태 → "품절" ``` *** 월말 세금계산서 자동 발행 [#월말-세금계산서-자동-발행] 매월 정산 후 세금계산서를 자동 발행합니다. ``` 트리거: 매월 1일 오전 10시 액션: ├── 조회: 전월 청구서 (상태 = "발행대기") │ ├── 네이버 커머스 정산 조회 │ └── 전월 정산 내역 가져오기 │ ├── 각 청구서에 대해 (반복): │ │ │ └── 볼타 세금계산서 발행 │ ├── 공급자: {{회사정보}} │ ├── 공급받는자: {{청구서.거래처}} │ ├── 품목: {{청구서.품목목록}} │ └── 작성일자: 전월 말일 │ ├── 청구서 상태 → "발행완료" │ └── 슬랙 #경리팀 알림 "{{발행건수}}건 세금계산서 발행 완료" ``` *** 주문 통합 대시보드 갱신 [#주문-통합-대시보드-갱신] 여러 플랫폼의 주문을 통합하여 대시보드를 갱신합니다. ``` 트리거: 매 30분 액션: ├── 네이버 커머스 신규 주문 조회 ├── 아임웹 신규 주문 조회 │ ├── 각 주문을 통합 주문 DB에 저장 │ ├── 주문번호 │ ├── 플랫폼 (네이버/아임웹) │ ├── 고객정보 │ ├── 상품정보 │ └── 주문일시 │ ├── 통계 블록 업데이트 │ ├── 오늘 총 주문: {{count}} │ ├── 네이버: {{네이버주문수}} │ └── 아임웹: {{아임웹주문수}} │ └── if 신규주문 > 0: └── 슬랙 #영업팀 알림 "📊 신규 주문 {{count}}건 동기화" ``` *** 승인 워크플로우 [#승인-워크플로우] 휴가 승인 프로세스 [#휴가-승인-프로세스] 휴가 신청 시 자동으로 승인 요청을 보내고 결과를 처리합니다. ``` ┌─────────────────────────────────────────────────────────────────┐ │ 🎯 트리거: 휴가신청 데이터모델에 새 행 생성 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 📧 승인자에게 승인 요청 이메일 │ │ "{{신청자}}님의 휴가 신청이 있습니다" │ │ [승인] [반려] 버튼 포함 │ │ │ │ 💬 승인자에게 슬랙 DM │ │ │ │ 휴가신청 상태 → "승인 대기" │ │ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ 🎯 트리거: 휴가신청 "상태"가 "승인됨"으로 변경 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 📧 신청자에게 승인 알림 │ │ "휴가가 승인되었습니다" │ │ │ │ 📅 팀 캘린더에 휴가 일정 추가 │ │ │ │ 📅 본인 캘린더에 휴가 일정 추가 │ │ │ │ 💬 팀 슬랙 채널에 공유 │ │ "{{신청자}}님이 {{시작일}}~{{종료일}} 휴가입니다" │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` *** 비용 승인 [#비용-승인] 일정 금액 이상의 비용은 자동으로 승인 프로세스를 거칩니다. ``` 트리거: 비용신청 데이터모델에 새 행 생성 조건 분기 (금액별): ├── < 10만원: │ └── 자동 승인 + 경비처리팀 알림 │ ├── 10만원 ~ 50만원: │ └── 팀장 승인 요청 │ ├── 50만원 ~ 200만원: │ └── 부서장 승인 요청 │ └── >= 200만원: └── 경영진 승인 요청 + 팀장 참조 ``` *** 워크플로우 작성 팁 [#워크플로우-작성-팁] 1. 작게 시작하기 [#1-작게-시작하기] 복잡한 워크플로우보다 **간단한 것부터** 시작하세요. ``` ❌ 처음부터 복잡한 분기와 10개의 액션 ✅ 트리거 + 알림 1개로 시작 → 점차 확장 ``` 2. 테스트 우선 [#2-테스트-우선] 프로덕션 데이터에 적용하기 전에 **반드시 테스트**하세요. 3. 알림 과부하 주의 [#3-알림-과부하-주의] 너무 많은 알림은 **무시당합니다**. 중요한 것만 알림으로. 4. 문서화 [#4-문서화] 복잡한 워크플로우는 **설명을 추가**해두세요. *** 다음 단계 [#다음-단계] * [트리거](/docs/workflows/triggers) - 더 많은 트리거 옵션 * [액션](/docs/workflows/actions) - 더 많은 액션 옵션 * [Taylor AI](/docs/taylor-ai) - AI로 워크플로우 자동 생성 --- # 표현식 (/docs/workflows/expressions) > 워크플로우에서 동적 값을 사용하는 방법을 알아봅니다. import { Callout } from 'fumadocs-ui/components/callout'; import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; 기본 문법 [#기본-문법] 표현식은 `{{ }}` 중괄호로 감싸서 작성합니다. ```javascript {{ 표현식 }} ``` 이전 노드의 데이터 참조 [#이전-노드의-데이터-참조] ```javascript // 특정 노드의 출력 데이터 참조 {{ $node["노드명"].json.필드명 }} // 예시: "Facebook Graph API" 노드의 campaign_name 필드 {{ $node["Facebook Graph API"].json.campaign_name }} ``` *** 주요 변수 [#주요-변수] | 변수 | 설명 | 예시 | | ------------- | ------------------ | --------------------------- | | `$json` | 현재 입력 데이터의 첫 번째 항목 | `{{ $json.name }}` | | `$input` | 현재 노드의 전체 입력 데이터 | `{{ $input.all() }}` | | `$node["이름"]` | 특정 노드의 출력 데이터 | `{{ $node["Slack"].json }}` | | `$now` | 현재 시간 (ISO 형식) | `{{ $now }}` | | `$today` | 오늘 날짜 (YYYY-MM-DD) | `{{ $today }}` | *** 데이터 접근 패턴 [#데이터-접근-패턴] 단일 필드 접근 [#단일-필드-접근] ```javascript // 이전 노드의 특정 필드 {{ $json.customer_name }} // 중첩된 객체 {{ $json.user.profile.email }} // 배열의 특정 인덱스 {{ $json.items[0].name }} ``` 특정 노드의 데이터 [#특정-노드의-데이터] ```javascript // "데이터 조회" 노드의 결과 {{ $node["데이터 조회"].json.total_count }} // "API 호출" 노드의 응답 {{ $node["API 호출"].json.data.results }} ``` 입력 데이터 전체 [#입력-데이터-전체] ```javascript // 모든 입력 항목 {{ $input.all() }} // 첫 번째 입력 항목 {{ $input.first() }} // 마지막 입력 항목 {{ $input.last() }} // 입력 항목 개수 {{ $input.length }} ``` *** 데이터 변환 (Transform 노드) [#데이터-변환-transform-노드] **Transform 노드**를 사용하면 이전 노드의 데이터를 새로운 형태로 변환할 수 있습니다. 필드 매핑 예시 [#필드-매핑-예시] ```json [ { "source": "campaign_name", "target": "캠페인명" }, { "source": "impressions", "target": "노출수", "type": "toNumber" }, { "source": "date_start", "target": "시작일", "type": "toDate" } ] ``` 지원 타입 변환 [#지원-타입-변환] | 타입 | 설명 | 예시 | | ----------- | ---------- | ------------------------ | | `toString` | 문자열로 변환 | `123` → `"123"` | | `toNumber` | 숫자로 변환 | `"456"` → `456` | | `toBoolean` | 불리언으로 변환 | `"true"` → `true` | | `toDate` | ISO 날짜로 변환 | `"2024-01-01"` → ISO 문자열 | | `parseJson` | JSON 파싱 | `'{"a":1}'` → `{a: 1}` | 중첩 필드 접근 [#중첩-필드-접근] 점(`.`) 표기법으로 중첩된 필드에 접근합니다. ```json [ { "source": "user.name", "target": "사용자명" }, { "source": "data.metrics.clicks", "target": "클릭수" } ] ``` *** 코드 노드에서 표현식 [#코드-노드에서-표현식] **Code 노드**에서는 JavaScript를 직접 작성하여 복잡한 변환을 수행할 수 있습니다. ```javascript // 입력 데이터 가공 const items = $input.all(); return items.map(item => ({ 이름: item.json.name, 금액: Number(item.json.amount) * 1.1, // 10% 추가 생성일: new Date(item.json.created_at).toLocaleDateString('ko-KR') })); ``` 사용 가능한 헬퍼 [#사용-가능한-헬퍼] ```javascript // 현재 입력 데이터 $input.all() // 모든 항목 $input.first() // 첫 번째 항목 $input.last() // 마지막 항목 // 특정 노드 데이터 $node["노드명"].json // 현재 시간 $now // ISO 형식 $today // YYYY-MM-DD ``` *** 활용 예시 [#활용-예시] 슬랙 메시지 작성 [#슬랙-메시지-작성] ```javascript // 메시지 템플릿 "📊 광고 성과 리포트 캠페인: {{ $node["Facebook API"].json.campaign_name }} 노출수: {{ $node["Facebook API"].json.impressions }} 클릭수: {{ $node["Facebook API"].json.clicks }} CTR: {{ $node["Facebook API"].json.ctr }}%" ``` 데이터모델에 저장 [#데이터모델에-저장] ```javascript // 저장할 데이터 { "캠페인명": "{{ $json.campaign_name }}", "노출수": "{{ $json.impressions }}", "비용": "{{ $json.spend }}", "수집일": "{{ $today }}" } ``` 조건 분기 [#조건-분기] ```javascript // If 노드 조건 {{ $json.amount > 10000 }} // 금액이 10000 초과 {{ $json.status === "active" }} // 상태가 active {{ $json.items.length > 0 }} // 항목이 있는 경우 ``` *** 자주 발생하는 오류 [#자주-발생하는-오류] <Callout type="error"> **필드가 없는 경우**: 참조하려는 필드가 없으면 `undefined`가 반환됩니다. 옵셔널 체이닝(`?.`)을 사용하세요. </Callout> ```javascript // ❌ 에러 발생 가능 {{ $json.user.name }} // ✅ 안전한 접근 {{ $json.user?.name }} {{ $json.user?.name ?? "이름 없음" }} ``` <Callout type="warn"> **노드명 오타**: 노드명은 정확히 일치해야 합니다. 공백과 대소문자를 주의하세요. </Callout> ```javascript // ❌ 노드명 오타 {{ $node["facebook api"].json }} // ✅ 정확한 노드명 {{ $node["Facebook Graph API"].json }} ``` *** 관련 문서 [#관련-문서] * [워크플로우 개요](/docs/workflows) * [트리거](/docs/workflows/triggers) * [액션](/docs/workflows/actions) * [활용 예시](/docs/workflows/examples) --- # 워크플로우 (/docs/workflows) > 반복 작업을 자동화하세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; 워크플로우란? [#워크플로우란] 워크플로우는 **"\~하면 \~한다"** 형태의 자동화 규칙입니다. ``` 트리거: 새 고객이 등록되면 ↓ 조건: 계약 금액이 1000만원 이상이면 ↓ 액션: 영업팀 슬랙 채널에 알림 전송 + 담당자에게 이메일 발송 ``` 워크플로우 구성 요소 [#워크플로우-구성-요소] | 구성 요소 | 설명 | 필수 | | ------- | -------------- | :-: | | **트리거** | 워크플로우가 시작되는 조건 | ✅ | | **조건** | 실행 여부를 결정하는 필터 | ❌ | | **액션** | 실제로 수행되는 작업 | ✅ | *** 트리거 종류 [#트리거-종류] 워크플로우를 시작하는 다양한 조건입니다. 내부 트리거 (슈츠 내) [#내부-트리거-슈츠-내] | 트리거 | 설명 | | ---------- | ------------------ | | **수동** | 버튼 클릭으로 직접 실행 | | **일정** | 특정 시간에 정기적으로 실행 | | **데이터 변경** | 데이터모델 행 생성/수정/삭제 시 | | **이벤트** | 특정 이벤트 발생 시 | | **웹훅** | 외부에서 HTTP 요청 시 | 외부 트리거 [#외부-트리거] 100개 이상의 외부 서비스 트리거를 지원합니다. | 서비스 | 예시 | | ------------ | --------------- | | **Slack** | 특정 채널에 메시지가 올 때 | | **GitHub** | PR이 생성/병합될 때 | | **Jira** | 이슈 상태가 변경될 때 | | **Google** | 폼 응답이 제출될 때 | | **Telegram** | 봇에 메시지가 올 때 | 👉 [트리거 자세히 보기](/docs/workflows/triggers) *** 액션 종류 [#액션-종류] 트리거 발생 시 실행할 작업입니다. 알림 액션 [#알림-액션] | 액션 | 설명 | | ---------- | -------------- | | **슬랙 메시지** | 채널/DM으로 메시지 전송 | | **이메일** | 이메일 발송 | | **슈츠 알림** | 슈츠 내 알림 | 데이터 액션 [#데이터-액션] | 액션 | 설명 | | -------- | ------------- | | **행 생성** | 데이터모델에 새 행 추가 | | **행 수정** | 기존 행의 값 변경 | | **행 삭제** | 조건에 맞는 행 삭제 | 연동 액션 [#연동-액션] | 액션 | 설명 | | ----------------- | ---------------- | | **HTTP 요청** | 외부 API 호출 | | **Google Sheets** | 스프레드시트 데이터 추가/수정 | | **Notion** | 페이지/데이터베이스 업데이트 | | **OpenAI** | AI 처리 실행 | 국내 비즈니스 연동 [#국내-비즈니스-연동] | 액션 | 설명 | | ----------- | ------------------ | | **카페24** | 쇼핑몰 주문/상품/고객/재고 관리 | | **아임웹** | 쇼핑몰 주문/상품/회원 관리 | | **네이버톡톡** | 챗봇 메시지 발송 | | **네이버 커머스** | 스마트스토어 주문/상품/정산 | | **볼타** | 전자세금계산서 발행 | 제어 액션 [#제어-액션] | 액션 | 설명 | | --------- | ---------------- | | **조건 분기** | 조건에 따라 다른 액션 실행 | | **지연** | 대기 후 다음 액션 실행 | | **반복** | 조건을 만족하는 동안 반복 | | **코드** | JavaScript 코드 실행 | 👉 [액션 자세히 보기](/docs/workflows/actions) *** 워크플로우 생성 [#워크플로우-생성] 방법 1: 사이드바에서 생성 [#방법-1-사이드바에서-생성] 1. 사이드바에서 **+ 새 워크플로우** 클릭 2. 트리거 선택 3. 조건 설정 (선택) 4. 액션 추가 5. 저장 및 활성화 방법 2: 테일러에게 요청 [#방법-2-테일러에게-요청] 자연어로 워크플로우를 설명하면 테일러가 자동으로 생성합니다. ``` 새 고객이 등록되면 슬랙에 알림을 보내고, 계약 금액이 1000만원 이상이면 관리자에게 이메일도 보내줘 ``` <Callout type="tip"> 복잡한 워크플로우는 테일러에게 요청하는 것이 빠릅니다. 테일러는 조건 분기와 여러 액션을 자동으로 구성해줍니다. </Callout> 방법 3: 데이터모델에서 생성 [#방법-3-데이터모델에서-생성] 데이터모델 설정에서 해당 데이터와 연결된 워크플로우를 바로 만들 수 있습니다. 1. 데이터모델 열기 2. ⚙️ 설정 → **자동화** 탭 3. **워크플로우 추가** 클릭 *** 워크플로우 편집기 [#워크플로우-편집기] ``` ┌─────────────────────────────────────────────────────────────────┐ │ 📄 새 고객 알림 워크플로우 [테스트] [저장] │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ │ │ │ 🎯 트리거 │ │ │ │ 행 생성됨 │ │ │ │ (고객 모델) │ │ │ └──────┬──────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ 🔀 조건 │ │ │ │ 금액≥1000만 │───[ 아니오 ]───→ (종료) │ │ └──────┬──────┘ │ │ │ 예 │ │ ▼ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ 📧 이메일 │──→│ 💬 슬랙 │ │ │ │ 관리자에게 │ │ #영업팀 │ │ │ └─────────────┘ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` 노드 연결 [#노드-연결] * 노드를 드래그하여 연결 * 분기를 통해 조건별 다른 경로 설정 * 병렬 실행 가능 (동시에 여러 액션) 변수 사용 [#변수-사용] 트리거에서 받은 데이터를 액션에서 사용할 수 있습니다. ```javascript // 슬랙 메시지에서 트리거 데이터 사용 "새 고객이 등록되었습니다: {{trigger.row.고객명}}" "계약 금액: {{trigger.row.계약금액}}" ``` *** 워크플로우 관리 [#워크플로우-관리] 목록 뷰 전환 [#목록-뷰-전환] 워크플로우 목록 페이지 상단에서 **리스트 뷰**와 **그리드 뷰**를 전환할 수 있습니다. | 뷰 모드 | 설명 | | --------- | ----------------------------------------------- | | **리스트 뷰** | 워크플로우를 한 줄씩 표시하여 이름, 상태, 실행 이력을 빠르게 확인 | | **그리드 뷰** | 카드 형태로 표시하며, 각 카드에 워크플로우의 노드 구성을 SVG 미니맵으로 미리보기 | 그리드 뷰에서는 각 워크플로우 카드에 노드 배치와 연결 구조가 시각적으로 표시되어, 워크플로우를 열지 않고도 전체 흐름을 파악할 수 있습니다. 카드에는 배포 상태, 버전, 노드 수, 마지막 실행 결과 등의 정보도 함께 표시됩니다. 활성화/비활성화 [#활성화비활성화] 워크플로우를 일시적으로 끄거나 켤 수 있습니다. | 상태 | 설명 | | ------- | ---------------- | | **활성** | 트리거 발생 시 자동 실행 | | **비활성** | 트리거가 발생해도 실행 안 함 | 실행 기록 [#실행-기록] 워크플로우가 실행된 기록과 결과를 확인합니다. ``` ┌─────────────────────────────────────────────────────────────────┐ │ 실행 기록 │ ├──────────┬──────────┬──────────┬──────────────────────────────┤ │ 시간 │ 트리거 │ 상태 │ 결과 │ ├──────────┼──────────┼──────────┼──────────────────────────────┤ │ 10:30:15 │ 행 생성 │ ✅ 성공 │ 슬랙 메시지 전송 완료 │ │ 09:15:42 │ 일정 │ ✅ 성공 │ 3개 행 업데이트 │ │ 08:00:01 │ 일정 │ ❌ 실패 │ API 응답 없음 (재시도 예정) │ └──────────┴──────────┴──────────┴──────────────────────────────┘ ``` 테스트 [#테스트] 실제 트리거 없이 워크플로우를 테스트할 수 있습니다. 1. 워크플로우 편집기에서 **테스트** 버튼 클릭 2. 테스트 데이터 입력 (또는 샘플 데이터 사용) 3. 실행 결과 확인 4. 에러 발생 시 로그 확인 *** 워크플로우 활용 예시 [#워크플로우-활용-예시] 영업 자동화 [#영업-자동화] ``` 트리거: 리드 생성 조건: 소스 = "웹사이트" 액션: ├── 영업팀 슬랙에 알림 ├── 담당자에게 이메일 └── CRM에 활동 기록 ``` 프로젝트 관리 [#프로젝트-관리] ``` 트리거: 마감일 1일 전 조건: 상태 ≠ "완료" 액션: ├── 담당자에게 슬랙 DM └── 상태를 "긴급"으로 변경 ``` 고객 관리 [#고객-관리] ``` 트리거: 고객 생성 액션: ├── 환영 이메일 발송 ├── 온보딩 체크리스트 생성 ├── 담당 CSM에게 알림 └── 7일 후 팔로업 예약 ``` 👉 [더 많은 예시 보기](/docs/workflows/examples) *** 이 섹션에서 다루는 내용 [#이-섹션에서-다루는-내용] <Cards> <Card title="트리거" description="워크플로우 시작 조건 설정" href="/docs/workflows/triggers" /> <Card title="액션" description="실행할 작업들" href="/docs/workflows/actions" /> <Card title="표현식" description="노드 간 데이터 전달 문법" href="/docs/workflows/expressions" /> <Card title="활용 예시" description="실제 사용 사례" href="/docs/workflows/examples" /> </Cards> --- # 트리거 (/docs/workflows/triggers) > 워크플로우가 시작되는 조건을 설정하세요. import { Callout } from 'fumadocs-ui/components/callout'; import { Card, Cards } from 'fumadocs-ui/components/card'; 트리거 종류 [#트리거-종류] | 트리거 | 설명 | 활용 예시 | | ----------------- | --------------------- | --------------------- | | **수동 (Manual)** | 버튼 클릭으로 직접 실행 | 승인 버튼, 발송 버튼 | | **일정 (Schedule)** | 정해진 시간에 자동 실행 | 일일 리포트, 주간 정리 | | **데이터 변경** | 행 생성/수정/삭제 감지 | 신규 가입 알림, 상태 변경 처리 | | **날짜 (Date)** | 특정 날짜 도달 시 실행 | 마감 리마인더, 계약 갱신 알림 | | **웹훅 (Webhook)** | 외부 HTTP 요청으로 실행 | 결제 연동, 외부 폼 연동 | | **Gmail** | 새 이메일 수신 시 실행 | 주문 이메일 처리, 문의 자동 분류 | | **파일 업로드** | CSV/Excel 파일 업로드 시 실행 | 대량 데이터 등록, 재고 일괄 업데이트 | <Callout type="tip"> 각 트리거의 **상세 설정 옵션과 활용 예시**는 [노드 레퍼런스](/docs/node-reference/triggers)에서 확인하세요. </Callout> *** 트리거 설정하기 [#트리거-설정하기] 1. 워크플로우 생성 시 트리거 선택 2. 트리거 유형에 따라 설정 입력 * 수동: 버튼 연결 * 일정: CRON 또는 시간 설정 * 데이터 변경: 데이터모델 및 이벤트 선택 * 날짜: 날짜 속성 및 오프셋 설정 * 웹훅: 웹훅 URL 생성 * Gmail: OAuth2 인증 연결 및 필터 설정 * 파일 업로드: 허용 파일 형식 및 크기 설정 3. 필요시 조건 필터 추가 *** 조건 필터 [#조건-필터] 모든 트리거에는 **조건 필터**를 추가할 수 있습니다. 트리거가 발생해도 조건을 만족하지 않으면 워크플로우가 실행되지 않습니다. 연산자 [#연산자] | 연산자 | 의미 | 예시 | | --------- | ------ | ------------ | | `=` | 같음 | 상태 = "완료" | | `≠` | 다름 | 상태 ≠ "취소" | | `>`, `>=` | 크다, 이상 | 금액 >= 100000 | | `<`, `<=` | 작다, 이하 | 재고 \< 10 | | `포함` | 텍스트 포함 | 제목 포함 "긴급" | | `비어있음` | 값 없음 | 담당자 비어있음 | 복합 조건 [#복합-조건] ``` (상태 = "완료") AND (우선순위 = "높음") (담당자 = "김철수") OR (담당자 = "이영희") ``` *** 트리거 모범 사례 [#트리거-모범-사례] 1. 명확한 조건 설정 [#1-명확한-조건-설정] 불필요한 실행을 줄이기 위해 조건을 명확히 하세요. ``` ❌ 트리거: 모든 행 수정 ✅ 트리거: "상태" 속성 변경, 조건: 새 값 = "완료" ``` 2. 중복 실행 방지 [#2-중복-실행-방지] 같은 이벤트에 여러 워크플로우가 반응하지 않도록 주의하세요. 3. 무한 루프 주의 [#3-무한-루프-주의] 워크플로우 액션이 같은 워크플로우를 다시 트리거하지 않도록 주의하세요. ``` ❌ 트리거: 행 수정 → 액션: 같은 행 수정 (무한 루프!) ``` 4. 테스트 먼저 [#4-테스트-먼저] 프로덕션 데이터에 적용하기 전에 테스트 데이터로 확인하세요. *** 트리거 레퍼런스 [#트리거-레퍼런스] 각 트리거의 상세 설명은 **노드 레퍼런스**에서 확인하세요. <Cards> <Card title="수동 트리거" description="버튼 클릭으로 직접 실행" href="/docs/node-reference/triggers/manual" /> <Card title="일정 트리거" description="CRON 기반 정기 실행" href="/docs/node-reference/triggers/schedule" /> <Card title="데이터 변경 트리거" description="행 생성/수정/삭제 감지" href="/docs/node-reference/triggers/data-change" /> <Card title="날짜 트리거" description="특정 날짜 도달 시 실행" href="/docs/node-reference/triggers/date" /> <Card title="웹훅 트리거" description="외부 HTTP 요청으로 실행" href="/docs/node-reference/triggers/webhook" /> <Card title="Gmail 트리거" description="새 이메일 수신 시 실행" href="/docs/node-reference/triggers/gmail" /> <Card title="파일 업로드 트리거" description="CSV/Excel 파일 업로드로 실행" href="/docs/node-reference/triggers/file-upload" /> </Cards> *** 다음 단계 [#다음-단계] * [액션](/docs/workflows/actions) - 실행할 작업 설정 * [활용 예시](/docs/workflows/examples) - 실제 사용 사례 * [노드 레퍼런스](/docs/node-reference) - 모든 노드 상세 스펙 --- # 액션 (/docs/node-reference/actions) > 트리거 발생 시 실행되는 작업을 정의하는 노드입니다. import { Card, Cards } from 'fumadocs-ui/components/card'; 액션 카테고리 [#액션-카테고리] 알림 [#알림] 사용자에게 알림을 전송합니다. <Cards> <Card title="슬랙 메시지" description="채널/DM으로 메시지 발송" href="/docs/node-reference/actions/notifications/slack" /> <Card title="이메일" description="이메일 발송" href="/docs/node-reference/actions/notifications/email" /> <Card title="슈츠 알림" description="인앱 알림 발송" href="/docs/node-reference/actions/notifications/taylor-notification" /> </Cards> 데이터 [#데이터] 데이터모델의 데이터를 조작합니다. <Cards> <Card title="행 생성" description="데이터모델에 새 행 추가" href="/docs/node-reference/actions/data/create-row" /> <Card title="행 수정" description="기존 행의 속성 값 변경" href="/docs/node-reference/actions/data/update-row" /> <Card title="행 삭제" description="조건에 맞는 행 삭제" href="/docs/node-reference/actions/data/delete-row" /> <Card title="행 조회" description="조건 검색으로 행 가져오기" href="/docs/node-reference/actions/data/query-rows" /> </Cards> 연동 [#연동] 외부 서비스와 연동합니다. <Cards> <Card title="HTTP 요청" description="외부 API 호출" href="/docs/node-reference/actions/integrations/http-request" /> <Card title="Google Sheets" description="스프레드시트 연동" href="/docs/node-reference/actions/integrations/google-sheets" /> <Card title="OpenAI" description="AI 처리 실행" href="/docs/node-reference/actions/integrations/openai" /> </Cards> 국내 비즈니스 [#국내-비즈니스] 국내 주요 이커머스/비즈니스 플랫폼과 연동합니다. <Cards> <Card title="카페24" description="카페24 쇼핑몰 연동" href="/docs/node-reference/actions/korea-business/cafe24" /> <Card title="아임웹" description="아임웹 쇼핑몰 연동" href="/docs/node-reference/actions/korea-business/imweb" /> <Card title="네이버톡톡" description="네이버톡톡 챗봇 메시지" href="/docs/node-reference/actions/korea-business/naver-talktalk" /> <Card title="네이버 커머스" description="스마트스토어 연동" href="/docs/node-reference/actions/korea-business/naver-commerce" /> <Card title="볼타" description="전자세금계산서 발행" href="/docs/node-reference/actions/korea-business/bolta" /> </Cards> 제어 [#제어] 워크플로우의 흐름을 제어합니다. <Cards> <Card title="조건 분기" description="If/Else 분기 처리" href="/docs/node-reference/actions/control/condition" /> <Card title="지연" description="다음 액션까지 대기" href="/docs/node-reference/actions/control/delay" /> <Card title="반복" description="여러 항목에 같은 작업 반복" href="/docs/node-reference/actions/control/loop" /> <Card title="코드" description="JavaScript 코드 실행" href="/docs/node-reference/actions/control/code" /> </Cards> *** 변수 시스템 [#변수-시스템] 액션에서 **동적 값**을 사용합니다. 트리거 데이터 [#트리거-데이터] ``` {{trigger.row.속성이름}} // 트리거된 행의 속성 값 {{trigger.row.id}} // 트리거된 행의 ID {{trigger.event}} // 트리거 이벤트 타입 ``` 이전 액션 결과 [#이전-액션-결과] ``` {{actions.액션이름.result}} // 이전 액션의 결과 {{actions.http.response}} // HTTP 응답 {{actions.query.rows}} // 조회된 행 목록 ``` 내장 함수 [#내장-함수] | 함수 | 설명 | 예시 | | ---------- | -------- | ------------------------------------ | | `now` | 현재 날짜/시간 | `{{now}}` | | `today` | 오늘 날짜 | `{{today}}` | | `format` | 포맷팅 | `{{format(now, "YYYY-MM-DD")}}` | | `dateDiff` | 날짜 차이 | `{{dateDiff(date1, date2, "days")}}` | *** 에러 처리 [#에러-처리] 재시도 정책 [#재시도-정책] 액션 실패 시 **자동 재시도**합니다. | 설정 | 기본값 | | ---------- | ----------- | | **재시도 횟수** | 3회 | | **재시도 간격** | 1분, 5분, 30분 | 실패 시 알림 [#실패-시-알림] 워크플로우 실패 시 관리자에게 알림을 보낼 수 있습니다. --- # 데이터 변경 트리거 (/docs/node-reference/triggers/data-change) > 데이터모델의 행이 생성/수정/삭제될 때 워크플로우를 실행합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ---------- | | **실행 방식** | 데이터 변경 감지 | | **이벤트** | 생성, 수정, 삭제 | | **입력 데이터** | 변경된 행의 데이터 | *** 이벤트 종류 [#이벤트-종류] 행 생성됨 (Row Created) [#행-생성됨-row-created] 새 행이 **추가**될 때 실행됩니다. ``` 트리거: 고객 데이터모델에 새 행 생성 ↓ 액션: 환영 이메일 발송 ``` 출력 데이터 [#출력-데이터] ```javascript {{trigger.row}} // 생성된 행 전체 {{trigger.row.고객명}} // 특정 속성 {{trigger.row.id}} // 행 ID {{trigger.event}} // "created" ``` *** 행 수정됨 (Row Updated) [#행-수정됨-row-updated] 기존 행이 **수정**될 때 실행됩니다. 감지 옵션 [#감지-옵션] | 옵션 | 설명 | | --------- | ----------------- | | **모든 변경** | 어떤 속성이든 변경되면 실행 | | **특정 속성** | 지정한 속성이 변경될 때만 실행 | 출력 데이터 [#출력-데이터-1] ```javascript {{trigger.row}} // 현재 행 데이터 {{trigger.previousRow}} // 변경 전 데이터 {{trigger.changedFields}} // 변경된 속성 목록 {{trigger.event}} // "updated" ``` 예시: 상태 변경 감지 [#예시-상태-변경-감지] ``` 트리거: 태스크 데이터모델 - "상태" 속성 변경 조건: 새 값 = "완료" 액션: ├── 완료일 자동 기록 └── 담당자에게 알림 ``` *** 행 삭제됨 (Row Deleted) [#행-삭제됨-row-deleted] 행이 **삭제**될 때 실행됩니다. 출력 데이터 [#출력-데이터-2] ```javascript {{trigger.row}} // 삭제된 행 데이터 {{trigger.row.id}} // 삭제된 행 ID {{trigger.event}} // "deleted" ``` <Callout type="warn"> 삭제된 행의 데이터는 트리거 실행 시점에만 사용 가능합니다. 이후 조회는 불가능합니다. </Callout> *** 속성 조건 충족 [#속성-조건-충족] 특정 조건을 **만족하게 될 때** 실행됩니다. ``` 트리거: 재고량 속성 변경 조건: 재고량 <= 최소재고량 액션: ├── 구매팀에 알림 └── 발주 요청 항목 생성 ``` *** 활용 예시 [#활용-예시] 신규 고객 온보딩 [#신규-고객-온보딩] ``` 트리거: 고객 데이터모델 - 행 생성 액션: ├── 환영 이메일 발송 ├── 담당자에게 슬랙 알림 └── 온보딩 태스크 자동 생성 ``` 마감일 지연 감지 [#마감일-지연-감지] ``` 트리거: 태스크 - "마감일" 속성 변경 조건: 마감일 < 오늘 AND 상태 ≠ "완료" 액션: ├── 상태를 "지연"으로 변경 └── 담당자에게 리마인더 ``` 승인 프로세스 [#승인-프로세스] ``` 트리거: 결재 - "상태" 속성 변경 조건: 상태 = "승인" 액션: ├── 승인일, 승인자 기록 ├── 요청자에게 알림 └── 다음 단계 생성 ``` *** 모범 사례 [#모범-사례] 무한 루프 방지 [#무한-루프-방지] <Callout type="error"> 워크플로우 액션이 같은 트리거를 다시 발생시키지 않도록 주의하세요. </Callout> ``` ❌ 트리거: 행 수정 → 액션: 같은 행 수정 (무한 루프!) ✅ 트리거: "상태" 변경 → 액션: "완료일" 수정 (다른 속성) ``` 조건 명확히 하기 [#조건-명확히-하기] ``` ❌ 트리거: 모든 행 수정 (불필요한 실행 많음) ✅ 트리거: "상태" 속성 변경, 조건: 새 값 = "완료" ``` 특정 속성만 감지 [#특정-속성만-감지] 자주 변경되는 속성(조회수, 수정일 등)을 제외하고 **핵심 속성만** 감지하세요. --- # 날짜 트리거 (/docs/node-reference/triggers/date) > 데이터의 날짜 속성이 특정 시점에 도달할 때 워크플로우를 실행합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ------------ | | **실행 방식** | 날짜 기반 자동 실행 | | **대상** | 데이터모델의 날짜 속성 | | **입력 데이터** | 해당 행의 데이터 | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 예시 | | --------- | --------- | -------- | | **해당 날짜** | 날짜가 되는 날 | 마감일 당일 | | **N일 전** | 날짜보다 N일 전 | 마감일 3일 전 | | **N일 후** | 날짜보다 N일 후 | 시작일 1일 후 | 실행 시간 [#실행-시간] 날짜 트리거는 지정된 날의 \*\*오전 9시 (워크스페이스 타임존 기준)\*\*에 실행됩니다. *** 출력 데이터 [#출력-데이터] ```javascript {{trigger.row}} // 해당 행 전체 {{trigger.row.마감일}} // 트리거된 날짜 속성 {{trigger.row.담당자}} // 기타 속성 {{trigger.triggerDate}} // 트리거 실행일 ``` *** 활용 예시 [#활용-예시] 마감 리마인더 [#마감-리마인더] ``` 트리거: 마감일 1일 전 조건: 상태 ≠ "완료" 액션: 담당자에게 리마인더 발송 ``` 계약 갱신 알림 [#계약-갱신-알림] ``` 트리거: 계약 만료일 30일 전 액션: ├── 담당자에게 이메일 ├── 갱신 상담 태스크 생성 └── CRM에 갱신 기회 추가 ``` 생일 축하 [#생일-축하] ``` 트리거: 생일 당일 액션: ├── 축하 이메일 자동 발송 └── 쿠폰 코드 생성 및 전송 ``` 정기 점검 [#정기-점검] ``` 트리거: 다음 점검일 7일 전 액션: ├── 점검 예정 알림 발송 └── 점검 예약 페이지 링크 전송 ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 여러 시점에 알림을 보내려면 **여러 워크플로우**를 만드세요. * 30일 전: 첫 번째 알림 * 7일 전: 두 번째 알림 * 당일: 최종 알림 </Callout> 조건 필터 활용 [#조건-필터-활용] 이미 처리된 항목은 제외하세요. ``` 트리거: 마감일 1일 전 조건: 상태 ≠ "완료" AND 상태 ≠ "취소" ``` 날짜 없는 행 처리 [#날짜-없는-행-처리] 날짜 속성이 **비어있는 행**은 트리거되지 않습니다. 필요시 기본값을 설정하세요. --- # 파일 업로드 트리거 (/docs/node-reference/triggers/file-upload) > CSV, Excel 등 파일을 업로드하여 워크플로우를 시작합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | --------- | ----------------------- | | **카테고리** | 트리거 | | **연동 필요** | 없음 | | **동작 방식** | 사용자가 파일을 업로드하면 워크플로우 실행 | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ----------------- | --------------------------- | :-: | | **허용 파일 형식** | 업로드를 허용할 파일 확장자 (콤마 구분) | | | **최대 파일 크기 (MB)** | 업로드 가능한 최대 파일 크기 (1\~100MB) | | | **안내 텍스트** | 파일 업로드 시 사용자에게 보여줄 안내 문구 | | 기본값 [#기본값] * 허용 파일 형식: `.csv, .xlsx, .xls` * 최대 파일 크기: 10MB *** 출력 데이터 [#출력-데이터] 업로드된 파일의 정보가 트리거 출력으로 전달됩니다. | 필드 | 설명 | | ---------- | ------------------ | | `data` | 파일 내용 (Base64 인코딩) | | `fileName` | 파일 이름 | | `fileSize` | 파일 크기 | | `mimeType` | 파일 MIME 타입 | *** 활용 예시 [#활용-예시] CSV 파일 업로드 후 데이터모델에 저장 [#csv-파일-업로드-후-데이터모델에-저장] ``` 트리거: 파일 업로드 ├── 허용 파일 형식: .csv ├── 안내 텍스트: "주문 데이터 CSV 파일을 업로드하세요" 액션 1: CSV 파싱 ├── 소스 필드: data ├── 구분자: 쉼표 ├── 첫 행을 헤더로 사용: 활성 액션 2: 반복 (파싱 결과) 액션 3: 행 생성 (주문 데이터모델) ``` Excel 파일 업로드 후 처리 [#excel-파일-업로드-후-처리] ``` 트리거: 파일 업로드 ├── 허용 파일 형식: .xlsx,.xls ├── 최대 파일 크기: 50 ├── 안내 텍스트: "재고 현황 Excel 파일을 업로드하세요" 액션 1: Excel 파싱 (Excel -> JSON) ├── 소스 필드: data ├── 첫 행을 헤더로 사용: 활성 액션 2: 반복 (파싱 결과) 액션 3: 행 생성 (재고 데이터모델) ``` 대량 데이터 업데이트 [#대량-데이터-업데이트] ``` 트리거: 파일 업로드 ├── 허용 파일 형식: .csv,.xlsx,.xls,.json ├── 안내 텍스트: "가격 변경 데이터를 업로드하세요" 액션 1: 조건 분기 (파일 형식) ├── CSV → CSV 파싱 ├── Excel → Excel 파싱 액션 2: 반복 (파싱 결과) 액션 3: 행 수정 (상품 데이터모델) ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 파일 업로드 트리거는 CSV 파싱 또는 Excel 파싱 노드와 함께 사용하면 효과적입니다. 업로드된 파일의 데이터(Base64)를 파싱 노드의 소스 필드로 연결하세요. </Callout> 파일 형식 제한 [#파일-형식-제한] 허용 파일 형식을 적절히 제한하여 사용자 실수를 방지하세요. 예를 들어 CSV만 허용하려면 `.csv`만 입력합니다. 파일 크기 관리 [#파일-크기-관리] 대용량 파일은 처리 시간이 길어질 수 있으므로 적절한 크기 제한을 설정하세요. --- # Gmail 트리거 (/docs/node-reference/triggers/gmail) > 새 이메일이 도착하면 워크플로우를 자동으로 실행합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | --------- | ---------------------- | | **카테고리** | 트리거 | | **연동 필요** | Gmail OAuth2 인증 | | **동작 방식** | 폴링 (설정된 간격으로 새 이메일 확인) | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ------------ | ---------------------------------------- | :-: | | **이벤트** | 이메일 수신 | ✅ | | **확인 간격** | 새 이메일 확인 주기 (1분, 5분, 10분, 15분, 30분, 1시간) | | | **간소화 출력** | 이메일 정보를 간소화된 형태로 반환 | | | **최대 메시지 수** | 한 번에 가져올 최대 이메일 수 (1\~100) | | *** 필터 옵션 [#필터-옵션] | 필터 | 설명 | | ------------- | ---------------------------------------------- | | **읽음 상태** | 읽지 않은 이메일만, 읽은 이메일만, 모든 이메일 | | **라벨 ID** | 특정 라벨의 이메일만 (쉼표로 구분, 예: INBOX, IMPORTANT) | | **보낸 사람** | 특정 발신자의 이메일만 | | **검색어** | Gmail 검색 문법 사용 (예: has:attachment, subject:주문) | | **스팸/휴지통 포함** | 스팸 및 휴지통 이메일 포함 여부 | | **임시 보관함 포함** | 임시 보관함 이메일 포함 여부 | *** 추가 옵션 [#추가-옵션] 간소화 출력을 비활성화하면 아래 옵션을 사용할 수 있습니다. | 옵션 | 설명 | | ------------- | --------------------------------- | | **첨부파일 다운로드** | 이메일 첨부파일을 다운로드 | | **첨부파일 접두사** | 첨부파일 속성 이름 접두사 (기본: attachment\_) | *** 출력 데이터 [#출력-데이터] | 필드 | 타입 | 설명 | | ---------------- | -------- | ------- | | `id` | string | 메시지 ID | | `threadId` | string | 스레드 ID | | `from` | string | 보낸 사람 | | `to` | string | 받는 사람 | | `cc` | string | 참조 | | `bcc` | string | 숨은 참조 | | `subject` | string | 제목 | | `date` | datetime | 날짜 | | `snippet` | string | 미리보기 | | `body` | string | 본문 | | `labelIds` | array | 라벨 목록 | | `hasAttachments` | boolean | 첨부파일 유무 | | `attachments` | array | 첨부파일 목록 | *** 활용 예시 [#활용-예시] 주문 이메일 자동 처리 [#주문-이메일-자동-처리] ``` 트리거: Gmail 트리거 ├── 확인 간격: 5분 ├── 필터 - 보낸 사람: orders@supplier.com ├── 필터 - 검색어: subject:주문확인 액션 1: OpenAI ├── 입력: {{trigger.body}} └── 프롬프트: "이메일에서 주문번호, 상품명, 수량을 JSON으로 추출" 액션 2: 행 생성 (주문 데이터모델) ``` 첨부파일 자동 저장 [#첨부파일-자동-저장] ``` 트리거: Gmail 트리거 ├── 확인 간격: 10분 ├── 간소화 출력: 비활성 ├── 옵션 - 첨부파일 다운로드: 활성 ├── 필터 - 검색어: has:attachment 액션 1: 조건 분기 (첨부파일 유무) 액션 2: 반복 (첨부파일 목록) 액션 3: Supabase - 파일 업로드 └── 파일 데이터: {{loop.current.data}} ``` 고객 문의 자동 분류 [#고객-문의-자동-분류] ``` 트리거: Gmail 트리거 ├── 확인 간격: 5분 ├── 필터 - 라벨 ID: INBOX ├── 필터 - 읽음 상태: 읽지 않은 이메일만 액션 1: OpenAI ├── 입력: {{trigger.subject}} {{trigger.body}} └── 프롬프트: "문의 유형 분류: 기술지원/결제/배송/기타" 액션 2: 행 생성 (문의 데이터모델) ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> Gmail OAuth2 인증은 Google Cloud Console에서 OAuth2 클라이언트를 생성한 뒤 연결합니다. Gmail API 권한이 필요합니다. </Callout> 폴링 간격 설정 [#폴링-간격-설정] * 긴급한 처리가 필요한 경우: 1분 또는 5분 * 일반적인 업무: 15분 또는 30분 * 일일 배치: 1시간 에러 처리 [#에러-처리] Gmail API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # 트리거 (/docs/node-reference/triggers) > 워크플로우가 시작되는 조건을 정의하는 노드입니다. import { Card, Cards } from 'fumadocs-ui/components/card'; 트리거 종류 [#트리거-종류] <Cards> <Card title="수동 트리거" description="버튼 클릭으로 직접 실행" href="/docs/node-reference/triggers/manual" /> <Card title="일정 트리거" description="CRON 기반 정기 실행" href="/docs/node-reference/triggers/schedule" /> <Card title="데이터 변경 트리거" description="행 생성/수정/삭제 감지" href="/docs/node-reference/triggers/data-change" /> <Card title="날짜 트리거" description="특정 날짜 도달 시 실행" href="/docs/node-reference/triggers/date" /> <Card title="웹훅 트리거" description="외부 HTTP 요청으로 실행" href="/docs/node-reference/triggers/webhook" /> </Cards> *** 조건 필터 [#조건-필터] 모든 트리거에는 **조건 필터**를 추가할 수 있습니다. 트리거 발생 후 조건을 검사하여 실행 여부를 결정합니다. 연산자 [#연산자] | 연산자 | 의미 | 예시 | | ------ | ------ | -------------- | | `=` | 같음 | `상태 = "완료"` | | `≠` | 다름 | `상태 ≠ "취소"` | | `>` | 크다 | `금액 > 100000` | | `>=` | 이상 | `금액 >= 100000` | | `<` | 작다 | `재고 < 10` | | `<=` | 이하 | `재고 <= 10` | | `포함` | 텍스트 포함 | `제목 포함 "긴급"` | | `비어있음` | 값 없음 | `담당자 비어있음` | AND/OR 조합 [#andor-조합] ``` (상태 = "완료") AND (우선순위 = "높음") (담당자 = "김철수") OR (담당자 = "이영희") ``` --- # 수동 트리거 (/docs/node-reference/triggers/manual) > 버튼 클릭으로 워크플로우를 직접 실행합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ------------------------- | | **실행 방식** | 사용자 직접 실행 | | **연결 대상** | 버튼 속성, 버튼 블록 | | **입력 데이터** | 클릭된 행의 데이터 (데이터모델 버튼의 경우) | *** 연결 방법 [#연결-방법] 데이터모델 버튼 속성 [#데이터모델-버튼-속성] 데이터모델에 **버튼 속성**을 추가하고 워크플로우와 연결합니다. 1. 데이터모델에서 `+ 속성 추가` > `버튼` 선택 2. 버튼 이름 입력 (예: "승인", "견적서 발송") 3. 연결할 워크플로우 선택 ``` [📧 견적서 발송] 버튼 클릭 ↓ 워크플로우 실행: 해당 행 데이터로 이메일 발송 ``` 페이지 버튼 블록 [#페이지-버튼-블록] 페이지에 **버튼 블록**을 추가하고 워크플로우와 연결합니다. 1. 페이지에서 `/button` 입력 2. 버튼 텍스트 설정 3. 연결할 워크플로우 선택 *** 출력 데이터 [#출력-데이터] 버튼이 **데이터모델에 연결**된 경우, 클릭된 행의 데이터가 트리거 출력으로 전달됩니다. ```javascript // 후속 액션에서 접근 {{trigger.row.고객명}} {{trigger.row.계약금액}} {{trigger.row.담당자}} ``` *** 활용 예시 [#활용-예시] | 버튼 | 워크플로우 | | ---------- | ----------------------- | | **승인** | 상태 변경 + 승인자 기록 + 담당자 알림 | | **견적서 발송** | PDF 생성 + 이메일 발송 | | **리포트 생성** | 데이터 집계 + 슬랙 공유 | | **다음 단계** | 상태 업데이트 + 담당자 변경 | *** 모범 사례 [#모범-사례] <Callout type="tip"> 버튼 이름에 **이모지**를 추가하면 직관적입니다. `📧 발송`, `✅ 승인`, `📊 리포트` </Callout> 실행 전 확인 [#실행-전-확인] 중요한 작업(삭제, 발송 등)은 **확인 모달**을 추가하는 것이 좋습니다. 실행 결과 피드백 [#실행-결과-피드백] 버튼 클릭 후 사용자에게 **실행 결과를 알려주세요**. * 성공: 토스트 메시지 * 실패: 에러 메시지 --- # 일정 트리거 (/docs/node-reference/triggers/schedule) > 지정한 시간에 정기적으로 워크플로우를 실행합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | --------------- | | **실행 방식** | 시간 기반 자동 실행 | | **설정 방식** | 간격, 특정 시간, CRON | | **입력 데이터** | 실행 시점 정보 | *** 설정 옵션 [#설정-옵션] 간격 실행 [#간격-실행] | 옵션 | 설명 | 예시 | | --------- | -------- | ----- | | **N초마다** | 초 단위 반복 | 매 30초 | | **N분마다** | 분 단위 반복 | 매 30분 | | **N시간마다** | 시간 단위 반복 | 매 2시간 | | **N일마다** | 일 단위 반복 | 매 3일 | 특정 시간 [#특정-시간] | 옵션 | 설명 | 예시 | | ------ | -------------------- | -------- | | **시간** | 매일 특정 시간 (0-23시) | 매일 오전 9시 | | **분** | 특정 분 (0-59분) | 9시 30분 | | **요일** | 실행할 요일 선택 (복수 선택 가능) | 월,수,금 | *** CRON 표현식 [#cron-표현식] 고급 스케줄링을 위해 **CRON 표현식**을 직접 입력할 수 있습니다. 형식 [#형식] ``` ┌───────────── 분 (0-59) │ ┌─────────── 시 (0-23) │ │ ┌───────── 일 (1-31) │ │ │ ┌─────── 월 (1-12) │ │ │ │ ┌───── 요일 (0-6, 일요일=0) │ │ │ │ │ * * * * * ``` 예시 [#예시] | CRON | 의미 | | -------------- | --------------- | | `0 9 * * *` | 매일 오전 9시 | | `0 9 * * 1-5` | 평일(월\~금) 오전 9시 | | `0 0 1 * *` | 매월 1일 자정 | | `*/30 * * * *` | 30분마다 | | `0 9,18 * * *` | 매일 오전 9시, 오후 6시 | | `0 10 * * 1` | 매주 월요일 오전 10시 | 특수 문자 [#특수-문자] | 문자 | 의미 | 예시 | | --- | ---- | ------------------------ | | `*` | 모든 값 | `* * * * *` (매분) | | `,` | 여러 값 | `0,30 * * * *` (0분, 30분) | | `-` | 범위 | `1-5` (월\~금) | | `/` | 간격 | `*/15` (15분마다) | *** 출력 데이터 [#출력-데이터] ```javascript // 실행 시점 정보 {{trigger.timestamp}} // 실행 시각 {{trigger.scheduledTime}} // 예정된 시각 ``` *** 활용 예시 [#활용-예시] 일일 리포트 [#일일-리포트] ``` 트리거: 매일 오전 9시 액션: ├── 전일 매출 데이터 조회 ├── 리포트 생성 └── 팀 채널에 공유 ``` 주간 정리 [#주간-정리] ``` 트리거: 매주 월요일 오전 9시 액션: ├── 미완료 태스크 조회 ├── 담당자별 리마인더 발송 └── 주간 현황 리포트 생성 ``` 월간 청구 [#월간-청구] ``` 트리거: 매월 1일 오전 10시 액션: ├── 청구 대상 고객 조회 ├── 세금계산서 발행 └── 청구 이메일 발송 ``` *** 모범 사례 [#모범-사례] <Callout type="warn"> **타임존 주의**: 타임존을 직접 설정할 수 있습니다. 지원 타임존: 서울 (KST), UTC, 도쿄 (JST), 로스앤젤레스 (PST), 뉴욕 (EST), 런던 (GMT). 기본값은 서울 (KST)입니다. </Callout> 피크 시간 피하기 [#피크-시간-피하기] 많은 스케줄이 정각에 몰리지 않도록 분산하세요. ``` ❌ 0 9 * * * (정각) ✅ 5 9 * * * (9시 5분) ``` 재시도 고려 [#재시도-고려] 일정 트리거는 놓친 실행을 자동 재시도하지 않습니다. 중요한 작업은 실패 알림을 설정하세요. --- # 웹훅 트리거 (/docs/node-reference/triggers/webhook) > 외부에서 HTTP 요청을 보낼 때 워크플로우를 실행합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ----------------------------- | | **실행 방식** | 외부 HTTP 요청 | | **지원 메서드** | GET, POST, PUT, PATCH, DELETE | | **입력 데이터** | 요청 본문, 헤더, 쿼리 파라미터 | *** 설정 방법 [#설정-방법] 1. 웹훅 URL 생성 [#1-웹훅-url-생성] 워크플로우에 웹훅 트리거를 추가하면 **고유한 URL**이 생성됩니다. ``` https://api.suits.work/webhooks/wf_xxxx ``` 2. 외부 시스템에 URL 등록 [#2-외부-시스템에-url-등록] 생성된 URL을 외부 시스템의 웹훅 설정에 등록합니다. 3. 요청 수신 및 워크플로우 실행 [#3-요청-수신-및-워크플로우-실행] 외부 시스템에서 요청을 보내면 워크플로우가 실행됩니다. *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | --------------- | -------------------------------------------- | :-: | | **HTTP Method** | 수신할 HTTP 메서드 (GET, POST, PUT, PATCH, DELETE) | ✅ | | **경로** | Webhook URL 경로 | ✅ | | **인증 방식** | 없음, Basic Auth, Header Auth | | | **응답 모드** | 요청 수신 즉시 또는 워크플로우 완료 후 | | | **응답 코드** | HTTP 응답 상태 코드 (즉시 응답 시) | | 인증 방식 [#인증-방식] | 방식 | 설명 | | --------------- | ------------------------ | | **없음** | 인증 없이 모든 요청 수신 | | **Basic Auth** | 사용자명/비밀번호 기반 인증 | | **Header Auth** | 커스텀 헤더(예: X-API-Key)로 인증 | 응답 모드 [#응답-모드] | 모드 | 설명 | | -------------- | ----------------------------- | | **요청 수신 즉시** | 요청을 받으면 즉시 응답, 워크플로우는 비동기 실행 | | **워크플로우 완료 후** | 워크플로우 실행이 끝난 후 마지막 노드의 결과를 응답 | *** 요청 형식 [#요청-형식] POST 요청 (권장) [#post-요청-권장] ```bash curl -X POST "https://api.suits.work/webhooks/wf_xxxx" \ -H "Content-Type: application/json" \ -d '{ "event": "payment_completed", "orderId": "ORD-12345", "amount": 50000, "customer": { "name": "김철수", "email": "kim@example.com" } }' ``` GET 요청 [#get-요청] ```bash curl "https://api.suits.work/webhooks/wf_xxxx?event=test&id=123" ``` *** 출력 데이터 [#출력-데이터] ```javascript // POST 요청 본문 {{trigger.body}} // 전체 JSON {{trigger.body.event}} // "payment_completed" {{trigger.body.orderId}} // "ORD-12345" {{trigger.body.customer.name}} // "김철수" // 헤더 {{trigger.headers}} // 전체 헤더 {{trigger.headers.authorization}} // Authorization 헤더 // 쿼리 파라미터 {{trigger.query}} // 전체 쿼리 {{trigger.query.id}} // "123" ``` *** 활용 예시 [#활용-예시] 결제 시스템 연동 [#결제-시스템-연동] ``` 외부: 결제 완료 웹훅 전송 ↓ 트리거: 웹훅 수신 액션: ├── 주문 상태 "결제완료"로 변경 ├── 고객에게 확인 이메일 발송 └── 재고 차감 ``` 외부 폼 연동 [#외부-폼-연동] ``` 외부: 폼 제출 웹훅 ↓ 트리거: 웹훅 수신 액션: ├── 문의 데이터모델에 행 생성 ├── 담당자에게 슬랙 알림 └── 자동 응답 이메일 발송 ``` CI/CD 알림 [#cicd-알림] ``` 외부: GitHub Actions 완료 웹훅 ↓ 트리거: 웹훅 수신 액션: ├── 배포 로그 기록 └── 팀 채널에 배포 완료 알림 ``` 물류 시스템 연동 [#물류-시스템-연동] ``` 외부: 송장 생성 웹훅 ↓ 트리거: 웹훅 수신 액션: ├── 주문에 송장번호 업데이트 ├── 쇼핑몰 송장 입력 (카페24/네이버) └── 고객에게 배송 시작 알림 ``` *** 보안 [#보안] <Callout type="warn"> 웹훅 URL은 **외부에 노출**됩니다. 보안을 위해 아래 방법을 사용하세요. </Callout> 시크릿 토큰 검증 [#시크릿-토큰-검증] 요청 헤더에 시크릿 토큰을 포함하고, 워크플로우에서 검증합니다. ```bash curl -X POST "https://api.suits.work/webhooks/wf_xxxx" \ -H "X-Webhook-Secret: your-secret-token" \ -d '{"data": "..."}' ``` ```javascript // 조건 필터에서 검증 {{trigger.headers['x-webhook-secret']}} = "your-secret-token" ``` IP 화이트리스트 [#ip-화이트리스트] 알려진 IP에서만 요청을 허용합니다. (Enterprise 플랜) *** 모범 사례 [#모범-사례] 응답 확인 [#응답-확인] 슈츠 웹훅은 요청을 받으면 **즉시 200 응답**을 반환합니다. 워크플로우 실행 결과는 별도로 확인하세요. 재시도 처리 [#재시도-처리] 외부 시스템이 재시도하는 경우 **중복 실행**될 수 있습니다. 멱등성을 고려하여 설계하세요. ``` // orderId로 중복 체크 조건: 동일한 orderId의 주문이 없을 때만 실행 ``` 페이로드 검증 [#페이로드-검증] 예상된 형식의 데이터만 처리하도록 조건을 설정하세요. ``` 조건: {{trigger.body.event}} = "payment_completed" ``` --- # 코드 (/docs/node-reference/actions/control/code) > JavaScript 코드를 실행합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | -------- | -------------------- | | **카테고리** | 제어 | | **런타임** | JavaScript (Node.js) | | **출력** | return 값 | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ------ | ---------------------------- | :-: | | **모드** | 전체 항목에 대해 1회 실행 또는 각 항목마다 실행 | | | **코드** | 실행할 JavaScript 코드 | ✅ | 실행 모드 [#실행-모드] | 모드 | 설명 | | ------------------- | --------------------------------- | | **전체 항목에 대해 1회 실행** | 모든 입력을 배열로 받아 처리 (`$input.all()`) | | **각 항목마다 실행** | 각 항목에 대해 개별 실행 (`$input.item`) | *** 입력 데이터 접근 [#입력-데이터-접근] ```javascript // 트리거 데이터 const row = trigger.row; const price = trigger.row.단가; const quantity = trigger.row.수량; // 이전 액션 결과 const queryResult = actions.query.rows; const httpResponse = actions.http.response; // 현재 시간 const now = new Date(); ``` *** 출력 (return) [#출력-return] ```javascript // 단일 값 return total; // 객체 return { totalPrice: total, taxIncluded: total * 1.1 }; // 배열 return filteredItems; ``` 후속 액션에서 사용 [#후속-액션에서-사용] ``` {{actions.code.result}} // return 값 {{actions.code.result.totalPrice}} // 객체의 속성 ``` *** 활용 예시 [#활용-예시] 계산 [#계산] ```javascript const price = trigger.row.단가; const quantity = trigger.row.수량; const discount = trigger.row.할인율 || 0; const subtotal = price * quantity; const discountAmount = subtotal * (discount / 100); const total = subtotal - discountAmount; return { subtotal, discountAmount, total, taxIncluded: total * 1.1 }; ``` 데이터 변환 [#데이터-변환] ```javascript // 배열 필터링 const activeItems = actions.query.rows.filter(row => row.status === 'active'); // 합계 계산 const total = actions.query.rows.reduce((sum, row) => sum + row.amount, 0); // 그룹화 const byCategory = actions.query.rows.reduce((acc, row) => { const key = row.category; if (!acc[key]) acc[key] = []; acc[key].push(row); return acc; }, {}); return { activeItems, total, byCategory }; ``` 문자열 처리 [#문자열-처리] ```javascript const name = trigger.row.이름; const phone = trigger.row.전화번호; // 전화번호 마스킹 const maskedPhone = phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2'); // 이름에서 성 추출 const lastName = name.charAt(0); return { maskedPhone, lastName }; ``` 날짜 계산 [#날짜-계산] ```javascript const dueDate = new Date(trigger.row.마감일); const today = new Date(); // 날짜 차이 (일) const diffTime = dueDate - today; const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24)); // D-day 형식 const dDay = diffDays > 0 ? `D-${diffDays}` : diffDays === 0 ? 'D-Day' : `D+${Math.abs(diffDays)}`; return { diffDays, dDay, isOverdue: diffDays < 0 }; ``` JSON 파싱 [#json-파싱] ```javascript // 웹훅 데이터 파싱 const webhookData = trigger.body; // 중첩 데이터 추출 const customerName = webhookData.order?.customer?.name || 'Unknown'; const items = webhookData.order?.items || []; const totalAmount = items.reduce((sum, item) => sum + item.price * item.quantity, 0); return { customerName, itemCount: items.length, totalAmount }; ``` 외부 API 응답 처리 [#외부-api-응답-처리] ```javascript const response = actions.http.response; // 에러 체크 if (!response || response.error) { return { success: false, error: response?.error || 'Unknown error' }; } // 필요한 데이터만 추출 const { id, status, created_at } = response.data; return { success: true, orderId: id, orderStatus: status, createdAt: new Date(created_at).toLocaleDateString('ko-KR') }; ``` *** 제한사항 [#제한사항] <Callout type="warn"> 보안과 성능을 위해 일부 기능이 제한됩니다. </Callout> | 항목 | 제한 | | ---------- | --------------- | | **실행 시간** | 최대 30초 | | **메모리** | 제한됨 | | **외부 요청** | 불가 (HTTP 액션 사용) | | **파일 시스템** | 접근 불가 | *** 모범 사례 [#모범-사례] 에러 처리 [#에러-처리] ```javascript try { const result = someOperation(); return { success: true, data: result }; } catch (error) { return { success: false, error: error.message }; } ``` null/undefined 체크 [#nullundefined-체크] ```javascript const value = trigger.row.optionalField ?? 'default'; const nested = trigger.body?.order?.customer?.name || 'Unknown'; ``` 가독성 [#가독성] 복잡한 로직은 **함수로 분리**하세요. ```javascript function calculateDiscount(price, rate) { return price * (rate / 100); } function formatCurrency(amount) { return amount.toLocaleString('ko-KR') + '원'; } const discount = calculateDiscount(trigger.row.price, trigger.row.discountRate); return { discount: formatCurrency(discount) }; ``` --- # 조건 분기 (/docs/node-reference/actions/control/condition) > 조건에 따라 다른 액션을 실행합니다. 개요 [#개요] | 항목 | 내용 | | -------- | ----------- | | **카테고리** | 제어 | | **용도** | 흐름 분기 | | **출력** | 없음 (분기만 수행) | *** 구조 [#구조] ``` ┌─────────────┐ │ 조건 분기 │ │ 금액>=100만 │ └──────┬──────┘ │ ┌───┴───┐ ▼ ▼ Yes No │ │ ▼ ▼ VIP 처리 일반 처리 ``` *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ------------ | -------------------------------------------- | :-: | | **조건 모드** | 규칙 기반 (UI로 조건 설정) 또는 표현식 (JavaScript 표현식 사용) | ✅ | | **조건 조합** | 모두 만족 (AND) 또는 하나라도 만족 (OR) — 규칙 기반 모드 | | | **조건** | 평가할 조건 배열 (규칙 기반) 또는 JavaScript 표현식 | ✅ | | **True 분기** | 조건이 참일 때 실행할 액션 | | | **False 분기** | 조건이 거짓일 때 실행할 액션 | | 규칙 기반 모드 [#규칙-기반-모드] 지원하는 연산자: `equals`, `notEquals`, `contains`, `gt`, `lt`, `gte`, `lte` 표현식 모드 [#표현식-모드] JavaScript 표현식을 직접 작성합니다. `true`를 반환하면 True 경로, `false`면 False 경로로 진행합니다. ```javascript $json.amount > 1000 && $json.status === 'pending' ``` *** 조건식 [#조건식] 비교 연산자 [#비교-연산자] | 연산자 | 의미 | 예시 | | ---- | -- | ------------------------------ | | `=` | 같음 | `{{trigger.row.상태}} = "완료"` | | `≠` | 다름 | `{{trigger.row.상태}} ≠ "취소"` | | `>` | 크다 | `{{trigger.row.금액}} > 100000` | | `>=` | 이상 | `{{trigger.row.금액}} >= 100000` | | `<` | 작다 | `{{trigger.row.재고}} < 10` | | `<=` | 이하 | `{{trigger.row.재고}} <= 10` | 논리 연산자 [#논리-연산자] | 연산자 | 의미 | 예시 | | ----- | --- | ---------------------------- | | `AND` | 그리고 | `금액 >= 100000 AND 상태 = "확정"` | | `OR` | 또는 | `상태 = "취소" OR 상태 = "환불"` | | `NOT` | 부정 | `NOT (상태 = "완료")` | 기타 조건 [#기타-조건] | 조건 | 설명 | 예시 | | ----------- | ------ | ------------- | | **포함** | 텍스트 포함 | `제목 포함 "긴급"` | | **비어있음** | 값 없음 | `담당자 비어있음` | | **비어있지 않음** | 값 있음 | `담당자 비어있지 않음` | *** 복합 조건 [#복합-조건] If / Else If / Else [#if--else-if--else] ```javascript if (금액 >= 1000000) { // VIP 처리 } else if (금액 >= 500000) { // 우수 고객 처리 } else { // 일반 처리 } ``` 중첩 조건 [#중첩-조건] ``` 조건 1: 상태 = "결제완료" ├── Yes: │ └── 조건 2: 금액 >= 100만 │ ├── Yes: VIP 처리 │ └── No: 일반 처리 └── No: 종료 ``` *** 활용 예시 [#활용-예시] VIP 분기 [#vip-분기] ``` 조건: {{trigger.row.금액}} >= 1000000 ├── True: VIP 환영 이메일 + 담당자 배정 └── False: 일반 환영 이메일 ``` 상태별 처리 [#상태별-처리] ``` 조건: {{trigger.row.상태}} = "승인" ├── True: 승인 처리 (다음 단계 생성, 알림) └── False: └── 조건: {{trigger.row.상태}} = "반려" ├── True: 반려 처리 (요청자 알림) └── False: (대기 상태, 아무것도 안함) ``` 조회 결과 유무 [#조회-결과-유무] ``` 조건: {{actions.query.count}} > 0 ├── True: 기존 데이터 업데이트 └── False: 새 데이터 생성 ``` 영업시간 체크 [#영업시간-체크] ``` 조건: {{hour(now)}} >= 9 AND {{hour(now)}} < 18 ├── True: 즉시 알림 └── False: 다음 영업일 알림 예약 ``` *** 모범 사례 [#모범-사례] 기본값 처리 [#기본값-처리] 조건에 해당하지 않는 경우도 처리하세요. ``` 조건: 상태 = "A" ├── True: A 처리 └── False: └── 조건: 상태 = "B" ├── True: B 처리 └── False: 기타 처리 (로그 남기기) ``` 조건 순서 [#조건-순서] 가장 **빈번한 케이스**를 먼저 체크하면 성능이 좋습니다. 명확한 조건 [#명확한-조건] 복잡한 조건은 **여러 단계**로 나누어 가독성을 높이세요. --- # 지연 (/docs/node-reference/actions/control/delay) > 다음 액션 실행 전 대기합니다. 개요 [#개요] | 항목 | 내용 | | -------- | -------- | | **카테고리** | 제어 | | **용도** | 실행 시점 제어 | | **출력** | 없음 | *** 대기 유형 [#대기-유형] | 유형 | 설명 | 예시 | | --------- | ----------------- | --------- | | **시간** | 지정된 시간만큼 대기 | 30분 후 | | **웹훅** | 외부 웹훅이 호출될 때까지 대기 | 승인 콜백 대기 | | **특정 시각** | 특정 날짜/시간까지 대기 | 다음 월요일 9시 | *** 설정 옵션 [#설정-옵션] 시간 대기 [#시간-대기] | 옵션 | 설명 | | ------- | ------ | | **밀리초** | N밀리초 후 | | **초** | N초 후 | | **분** | N분 후 | | **시간** | N시간 후 | 특정 시각 [#특정-시각] | 옵션 | 설명 | | --------- | ------------- | | **대기 시각** | 특정 날짜/시간까지 대기 | 웹훅 대기 [#웹훅-대기] 외부 웹훅이 호출될 때까지 워크플로우 실행을 일시 정지합니다. *** 활용 예시 [#활용-예시] 드립 이메일 캠페인 [#드립-이메일-캠페인] ``` 트리거: 신규 가입 액션 1: 환영 이메일 발송 지연: 24시간 액션 2: 사용 가이드 이메일 발송 지연: 7일 액션 3: 만족도 조사 이메일 발송 ``` 리마인더 [#리마인더] ``` 트리거: 태스크 생성 액션 1: 담당자에게 알림 지연: 마감일 1일 전 액션 2: 리마인더 발송 (상태 ≠ 완료인 경우) ``` 후속 조치 [#후속-조치] ``` 트리거: 문의 접수 액션 1: 자동 응답 이메일 지연: 30분 액션 2: 담당자 미배정 시 관리자 알림 ``` 결제 확인 [#결제-확인] ``` 트리거: 주문 생성 (입금대기) 지연: 24시간 액션: 입금 미확인 시 주문 취소 + 알림 ``` *** 지연 중 데이터 변경 [#지연-중-데이터-변경] 지연 동안 트리거 데이터가 **변경될 수 있습니다**. ``` 트리거 시점: 상태 = "대기" 지연: 24시간 실행 시점: 상태 = "완료" (이미 변경됨) ``` 해결 방법 [#해결-방법] 실행 시점에 **조건을 다시 체크**하세요. ``` 지연: 24시간 조건 분기: 상태 = "대기"인 경우에만 실행 ``` *** 모범 사례 [#모범-사례] 조건 체크 추가 [#조건-체크-추가] 지연 후에는 **현재 상태를 확인**하는 조건을 추가하세요. ``` 지연: 7일 조건: 상태 = "미완료" └── True: 리마인더 발송 └── False: (이미 완료됨, 스킵) ``` 적절한 지연 시간 [#적절한-지연-시간] * 이메일 드립: 24시간 \~ 7일 * 리마인더: 1일 \~ 3일 전 * 결제 확인: 30분 \~ 24시간 타임존 고려 [#타임존-고려] 특정 시간에 실행하는 경우 **워크스페이스 타임존**을 확인하세요. --- # 반복 (/docs/node-reference/actions/control/loop) > 여러 항목에 대해 같은 액션을 반복합니다. 개요 [#개요] | 항목 | 내용 | | -------- | -------- | | **카테고리** | 제어 | | **용도** | 배열 순회 | | **출력** | 각 반복의 결과 | *** 구조 [#구조] ``` 입력: 미완료 태스크 목록 (5개) 반복: 각 태스크에 대해 └── 담당자에게 리마인더 발송 결과: 5명에게 각각 리마인더 발송 ``` *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ------------ | --------------------------------------- | :-: | | **루프 모드** | Each Item (각 항목 개별 처리) 또는 Batch (배치 처리) | | | **배치 크기** | 한 번에 처리할 항목 수 (Batch 모드) | | | **병렬 처리** | 항목들을 병렬로 처리 (순서 보장 안됨) | | | **최대 동시 실행** | 동시에 처리할 최대 항목 수 (1\~50, 병렬 모드) | | *** 반복 변수 [#반복-변수] | 변수 | 설명 | | ------------------ | ------------ | | `{{loop.current}}` | 현재 항목 | | `{{loop.index}}` | 현재 인덱스 (0부터) | | `{{loop.total}}` | 전체 항목 수 | | `{{loop.isFirst}}` | 첫 번째 항목 여부 | | `{{loop.isLast}}` | 마지막 항목 여부 | *** 활용 예시 [#활용-예시] 일괄 알림 [#일괄-알림] ``` 트리거: 일정 (매일 오전 9시) 액션 1: 행 조회 (마감 오늘인 태스크) 액션 2: 반복 ({{actions.query.rows}}) └── 반복 액션: 슬랙 메시지 └── 메시지: "{{loop.current.담당자}}님, {{loop.current.제목}} 마감입니다." ``` 일괄 상태 변경 [#일괄-상태-변경] ``` 트리거: 버튼 클릭 (일괄 완료) 액션 1: 행 조회 (선택된 항목들) 액션 2: 반복 ({{actions.query.rows}}) └── 반복 액션: 행 수정 └── 상태: "완료" └── 완료일: {{now}} ``` 외부 API 일괄 호출 [#외부-api-일괄-호출] ``` 트리거: 일정 (매시간) 액션 1: 행 조회 (동기화 필요한 항목) 액션 2: 반복 ({{actions.query.rows}}) └── 반복 액션: HTTP 요청 └── URL: https://api.external.com/sync/{{loop.current.id}} ``` 관계 데이터 처리 [#관계-데이터-처리] ``` 트리거: 프로젝트 완료 액션 1: 행 조회 (프로젝트의 모든 태스크) 액션 2: 반복 ({{actions.query.rows}}) └── 반복 액션: 행 수정 └── 상태: "완료" ``` *** 병렬 vs 순차 [#병렬-vs-순차] 순차 실행 (기본) [#순차-실행-기본] * 하나씩 차례대로 실행 * 이전 결과를 다음에서 사용 가능 * 안전하지만 느림 병렬 실행 [#병렬-실행] * 동시에 여러 개 실행 * 빠르지만 순서 보장 안됨 * 외부 API 제한 주의 *** 모범 사례 [#모범-사례] 최대 반복 설정 [#최대-반복-설정] 무한 루프 방지를 위해 **최대 반복 횟수**를 설정하세요. ``` 최대 반복: 100 ``` 에러 처리 [#에러-처리] 반복 중 하나가 실패해도 **다른 항목은 계속 처리**됩니다. 대량 데이터 주의 [#대량-데이터-주의] * 1000개 이상은 **배치 처리**를 고려하세요 * 외부 API는 **요청 제한**을 확인하세요 진행 상황 로깅 [#진행-상황-로깅] 대량 처리 시 진행 상황을 로깅하면 디버깅에 도움됩니다. ``` 조건: {{loop.index}} % 100 = 0 └── 로그: "{{loop.index}} / {{loop.total}} 처리 완료" ``` --- # 행 생성 (/docs/node-reference/actions/data/create-row) > 데이터모델에 새 행을 생성합니다. 개요 [#개요] | 항목 | 내용 | | -------- | --------- | | **카테고리** | 데이터 | | **대상** | 데이터모델 | | **출력** | 생성된 행 데이터 | *** 작업 종류 [#작업-종류] | 작업 | 설명 | | --------------- | ------------------------------- | | **생성 (Create)** | 새 레코드 생성 | | **Upsert** | 있으면 수정, 없으면 생성 (중복 확인 기준 필드 필요) | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ------------ | --------------------- | :---------: | | **데이터모델** | 행을 생성할 데이터모델 | ✅ | | **작업** | 생성 (Create) 또는 Upsert | ✅ | | **데이터** | 저장할 데이터 (JSON 형식) | ✅ | | **중복 확인 기준** | Upsert 시 중복 확인 기준 필드 | Upsert 시 필수 | *** 속성 값 설정 [#속성-값-설정] 고정 값 [#고정-값] ``` 상태: "대기중" 우선순위: "높음" ``` 동적 값 (변수) [#동적-값-변수] ``` 고객: {{trigger.row.고객}} 금액: {{trigger.row.계약금액}} 담당자: {{trigger.row.담당자}} ``` 현재 시간 [#현재-시간] ``` 생성일: {{now}} 발행일: {{today}} ``` *** 출력 데이터 [#출력-데이터] ```javascript {{actions.createRow.row}} // 생성된 행 전체 {{actions.createRow.row.id}} // 생성된 행 ID {{actions.createRow.row.속성명}} // 특정 속성 값 ``` *** 활용 예시 [#활용-예시] 계약 체결 → 청구서 생성 [#계약-체결--청구서-생성] ``` 트리거: 계약 체결 (상태 = "체결완료") 액션: 청구서 데이터모델에 행 생성 ├── 고객: {{trigger.row.고객}} ├── 금액: {{trigger.row.계약금액}} ├── 발행일: {{now}} └── 상태: "발행 대기" ``` 문의 접수 → 태스크 생성 [#문의-접수--태스크-생성] ``` 트리거: 문의 데이터모델에 행 생성 액션: 태스크 데이터모델에 행 생성 ├── 제목: "[문의] {{trigger.row.제목}}" ├── 내용: {{trigger.row.문의내용}} ├── 담당자: {{trigger.row.담당부서_기본담당자}} └── 우선순위: "보통" ``` 주문 → 배송 항목 생성 [#주문--배송-항목-생성] ``` 트리거: 주문 상태 = "결제완료" 액션: 배송 데이터모델에 행 생성 ├── 주문번호: {{trigger.row.주문번호}} ├── 수령인: {{trigger.row.수령인}} ├── 주소: {{trigger.row.배송주소}} └── 상태: "준비중" ``` *** 모범 사례 [#모범-사례] 필수 속성 확인 [#필수-속성-확인] 생성 시 **필수 속성**에 값이 있는지 확인하세요. 값이 없으면 에러가 발생합니다. 관계 설정 [#관계-설정] 다른 데이터모델과의 관계가 있다면 관계 속성도 설정하세요. ``` 관련고객: {{trigger.row.id}} // 트리거 행과 관계 설정 ``` 중복 방지 [#중복-방지] 같은 조건의 행이 이미 있는지 확인 후 생성하는 것이 좋습니다. ``` 1. 행 조회 (조건: 주문번호 = {{trigger.body.orderNo}}) 2. 조건 분기 (조회 결과 없으면) 3. 행 생성 ``` --- # CSV 파싱 (/docs/node-reference/actions/data/csv-parse) > CSV 데이터를 JSON 배열로 변환하거나, JSON 배열을 CSV 문자열로 변환합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | --------- | -------------------------------------------- | | **카테고리** | 데이터 | | **연동 필요** | 없음 | | **지원 작업** | Parse (CSV -> JSON), Stringify (JSON -> CSV) | *** 작업 종류 [#작업-종류] | 작업 | 설명 | | --------------------------- | -------------------- | | **Parse (CSV -> JSON)** | CSV 문자열을 JSON 배열로 변환 | | **Stringify (JSON -> CSV)** | JSON 배열을 CSV 문자열로 변환 | *** 설정 옵션 [#설정-옵션] Parse (CSV -> JSON) [#parse-csv---json] | 옵션 | 설명 | 필수 | | --------------- | ------------------------------------------ | :-: | | **CSV 데이터** | 파싱할 CSV 문자열 직접 입력 | | | **소스 필드** | 이전 노드 데이터에서 CSV 문자열이 담긴 필드명 (CSV 데이터보다 우선) | | | **구분자** | 쉼표, 탭, 세미콜론, 파이프, 직접 입력 | | | **첫 행을 헤더로 사용** | 첫 번째 행을 컬럼명으로 사용 (기본: 활성) | | | **빈 줄 건너뛰기** | 빈 줄을 결과에서 제외 (기본: 활성) | | Stringify (JSON -> CSV) [#stringify-json---csv] | 옵션 | 설명 | 필수 | | --------------- | ------------------- | :-: | | **구분자** | 출력 CSV의 구분자 설정 | | | **첫 행을 헤더로 사용** | 첫 행에 컬럼명 포함 여부 | | | **결과 필드명** | 결과 CSV 문자열을 저장할 필드명 | | *** 활용 예시 [#활용-예시] 업로드된 CSV 파일 처리 [#업로드된-csv-파일-처리] ``` 트리거: 파일 업로드 액션 1: CSV 파싱 ├── 소스 필드: data ├── 구분자: 쉼표 ├── 첫 행을 헤더로 사용: 활성 액션 2: 반복 (파싱 결과) 액션 3: 행 생성 (데이터모델) ``` 데이터모델을 CSV로 내보내기 [#데이터모델을-csv로-내보내기] ``` 트리거: 수동 실행 액션 1: 행 조회 (주문 데이터모델) 액션 2: CSV 파싱 (Stringify) ├── 구분자: 쉼표 ├── 첫 행을 헤더로 사용: 활성 └── 결과 필드명: csvResult 액션 3: 이메일 발송 └── 첨부: {{actions.csvParse.csvResult}} ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 대용량 CSV 처리 시 메모리 사용량에 유의하세요. 파일 크기가 큰 경우 페이지 단위로 나누어 처리하는 것을 권장합니다. </Callout> 인코딩 [#인코딩] 현재 UTF-8 인코딩을 지원합니다. EUC-KR/CP949 등 다른 인코딩은 향후 지원 예정입니다. --- # 행 삭제 (/docs/node-reference/actions/data/delete-row) > 조건에 맞는 행을 삭제합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | -------- | -------- | | **카테고리** | 데이터 | | **대상** | 데이터모델의 행 | | **출력** | 삭제 결과 | <Callout type="error"> **주의**: 삭제는 되돌릴 수 없습니다. 삭제 대신 "보관" 또는 "삭제됨" 상태로 변경하는 것을 권장합니다. </Callout> *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ------------ | ------------------------------- | :-: | | **데이터모델** | 삭제 대상 데이터모델 | ✅ | | **삭제 대상 ID** | 삭제할 레코드 ID (비워두면 필터 조건으로 다건 삭제) | | | **필터 조건** | JSON 형식 필터 (ID 미지정 시 사용) | | | **확인** | 다건 삭제 시 확인 체크 (필터만 사용할 경우 필수) | | *** 대상 행 지정 [#대상-행-지정] 트리거 행 [#트리거-행] ``` 대상: {{trigger.row}} ``` ID로 지정 [#id로-지정] ``` 대상: 특정 행 ID 행 ID: {{actions.query.rows[0].id}} ``` 조회 결과 [#조회-결과] ``` 대상: {{actions.query.rows}} ``` *** 출력 데이터 [#출력-데이터] ```javascript {{actions.deleteRow.deletedId}} // 삭제된 행 ID {{actions.deleteRow.success}} // 성공 여부 ``` *** 활용 예시 [#활용-예시] 오래된 데이터 정리 [#오래된-데이터-정리] ``` 트리거: 일정 (매일 자정) 액션 1: 행 조회 ├── 데이터모델: 로그 └── 조건: 생성일 < (오늘 - 90일) 액션 2: 반복 ({{actions.query.rows}}) 액션 3: 행 삭제 ({{loop.current}}) ``` 취소된 항목 삭제 [#취소된-항목-삭제] ``` 트리거: 상태 변경 → "취소" 조건: 취소 후 30일 경과 액션: 행 삭제 ``` *** 모범 사례 [#모범-사례] 소프트 삭제 권장 [#소프트-삭제-권장] <Callout type="tip"> 실제 삭제 대신 **소프트 삭제**를 권장합니다. </Callout> ``` // 실제 삭제 대신 액션: 행 수정 ├── 상태: "삭제됨" └── 삭제일: {{now}} ``` 삭제 전 백업 [#삭제-전-백업] 중요한 데이터는 삭제 전에 백업하세요. ``` 1. 행 조회 (삭제 대상) 2. 외부 저장소에 백업 (HTTP 요청) 3. 행 삭제 ``` 삭제 로그 [#삭제-로그] 삭제 이력을 별도로 기록하세요. ``` 1. 행 생성 (삭제 로그 데이터모델) ├── 삭제된 데이터: {{JSON.stringify(trigger.row)}} ├── 삭제일: {{now}} └── 삭제자: {{trigger.user.name}} 2. 행 삭제 ``` --- # Excel 파싱 (/docs/node-reference/actions/data/excel-parse) > Excel(XLSX/XLS/CSV) 파일을 JSON으로 변환하거나, JSON 데이터를 Excel/CSV 파일로 생성합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | --------- | -------------------------------------------- | | **카테고리** | 데이터 | | **연동 필요** | 없음 | | **지원 작업** | Excel -> JSON (파일 읽기), JSON -> Excel (파일 생성) | | **지원 형식** | XLSX, XLS, CSV | *** 작업 종류 [#작업-종류] | 작업 | 설명 | | ------------------------- | -------------------------------------- | | **Excel -> JSON (파일 읽기)** | Base64로 인코딩된 Excel/CSV 파일을 JSON 배열로 변환 | | **JSON -> Excel (파일 생성)** | JSON 데이터를 XLSX 또는 CSV 파일로 변환 | *** 설정 옵션 [#설정-옵션] Excel -> JSON (파일 읽기) [#excel---json-파일-읽기] | 옵션 | 설명 | 필수 | | --------------- | --------------------------------- | :-: | | **소스 필드** | 이전 노드 데이터에서 파일 내용(Base64)이 담긴 필드명 | ✅ | | **시트 이름** | 읽을 시트 이름 (비워두면 첫 번째 시트) | | | **첫 행을 헤더로 사용** | 첫 행을 컬럼 헤더로 사용 (비활성 시 인덱스가 키) | | | **읽을 범위** | 읽을 셀 범위, 예: A1:D10 (비워두면 전체) | | | **빈 셀 포함** | 빈 셀도 빈 문자열로 결과에 포함 | | JSON -> Excel (파일 생성) [#json---excel-파일-생성] | 옵션 | 설명 | 필수 | | --------------- | ----------------------- | :-: | | **첫 행을 헤더로 사용** | 첫 행에 컬럼명 포함 여부 | | | **빈 셀 포함** | 빈 값도 포함 여부 | | | **결과 필드명** | 생성된 파일(Base64)을 저장할 필드명 | | | **출력 형식** | XLSX 또는 CSV | | *** 활용 예시 [#활용-예시] 업로드된 Excel 파일 처리 [#업로드된-excel-파일-처리] ``` 트리거: 파일 업로드 액션 1: Excel 파싱 (Excel -> JSON) ├── 소스 필드: data ├── 시트 이름: "Sheet1" ├── 첫 행을 헤더로 사용: 활성 액션 2: 반복 (파싱 결과) 액션 3: 행 생성 (데이터모델) ``` 데이터를 Excel 파일로 내보내기 [#데이터를-excel-파일로-내보내기] ``` 트리거: 수동 실행 액션 1: 행 조회 (매출 데이터모델) 액션 2: Excel 파싱 (JSON -> Excel) ├── 출력 형식: XLSX ├── 첫 행을 헤더로 사용: 활성 └── 결과 필드명: excelData 액션 3: 이메일 발송 └── 첨부: {{actions.excelParse.excelData}} ``` 특정 범위만 읽기 [#특정-범위만-읽기] ``` 트리거: 파일 업로드 액션 1: Excel 파싱 (Excel -> JSON) ├── 소스 필드: data ├── 읽을 범위: "B2:F50" ├── 첫 행을 헤더로 사용: 활성 액션 2: 반복 (필터링된 데이터) ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 파일 형식(XLSX/XLS/CSV)은 자동 감지됩니다. 별도로 형식을 지정할 필요가 없습니다. </Callout> 대용량 파일 처리 [#대용량-파일-처리] 대용량 Excel 파일 처리 시 메모리 사용량에 유의하세요. 필요한 범위만 읽도록 "읽을 범위" 옵션을 활용하면 성능이 향상됩니다. --- # 행 조회 (/docs/node-reference/actions/data/query-rows) > 조건에 맞는 행을 검색하여 후속 액션에서 사용합니다. 개요 [#개요] | 항목 | 내용 | | -------- | -------- | | **카테고리** | 데이터 | | **대상** | 데이터모델 | | **출력** | 조회된 행 목록 | *** 작업 종류 [#작업-종류] | 작업 | 설명 | | ------------------ | -------------------------------------- | | **조회 (Query)** | 조건에 맞는 데이터 조회 | | **단건 조회 (Get)** | ID로 단일 레코드 조회 | | **집계 (Aggregate)** | 집계 쿼리 실행 (sum, count, avg, min, max 등) | | **개수 (Count)** | 조건에 맞는 레코드 수 | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ------------- | -------------------------- | :-: | | **데이터모델** | 조회할 데이터모델 | ✅ | | **작업** | 조회, 단건 조회, 집계, 개수 | ✅ | | **필터 조건** | JSON 형식 필터 | | | **정렬** | 결과 정렬 방식 (- 붙이면 내림차순) | | | **조회 개수** | 최대 조회 개수 (기본 100, 최대 1000) | | | **건너뛰기** | 건너뛸 레코드 수 (페이지네이션용) | | | **조회 필드** | 조회할 필드 (비워두면 전체) | | | **관계 데이터 포함** | 관계된 데이터모델의 데이터도 함께 조회 | | *** 조건 설정 [#조건-설정] 단일 조건 [#단일-조건] ``` 상태 = "진행중" ``` 복합 조건 [#복합-조건] ``` (상태 = "진행중") AND (담당자 = {{trigger.row.담당자}}) ``` 날짜 조건 [#날짜-조건] ``` 마감일 < {{today}} 생성일 >= {{today - 7일}} ``` 관계 조건 [#관계-조건] ``` 고객 = {{trigger.row.고객}} ``` *** 정렬 및 제한 [#정렬-및-제한] 정렬 [#정렬] ``` 정렬: 생성일 DESC (최신순) 정렬: 우선순위 ASC, 마감일 ASC ``` 제한 [#제한] ``` 제한: 10 (최대 10개) 제한: 1 (첫 번째 행만) ``` *** 출력 데이터 [#출력-데이터] ```javascript {{actions.query.rows}} // 조회된 행 배열 {{actions.query.rows[0]}} // 첫 번째 행 {{actions.query.rows[0].id}} // 첫 번째 행의 ID {{actions.query.count}} // 조회된 행 개수 ``` *** 활용 예시 [#활용-예시] 관련 데이터 조회 [#관련-데이터-조회] ``` 트리거: 고객 행 생성 액션 1: 행 조회 ├── 데이터모델: 계약 ├── 조건: 고객 = {{trigger.row.id}} └── 정렬: 계약일 DESC 액션 2: 슬랙 메시지 └── 메시지: "이전 계약 {{actions.query.count}}건" ``` 미완료 항목 리마인더 [#미완료-항목-리마인더] ``` 트리거: 일정 (매일 오전 9시) 액션 1: 행 조회 ├── 데이터모델: 태스크 ├── 조건: 상태 = "진행중" AND 마감일 = {{today}} 액션 2: 반복 ({{actions.query.rows}}) 액션 3: 슬랙 메시지 (담당자에게 리마인더) ``` 리포트 생성 [#리포트-생성] ``` 트리거: 일정 (매주 월요일) 액션 1: 행 조회 ├── 데이터모델: 매출 ├── 조건: 날짜 >= {{지난주 월요일}} AND 날짜 <= {{지난주 일요일}} 액션 2: 코드 (합계 계산) └── return { total: rows.reduce((sum, r) => sum + r.금액, 0) } 액션 3: 슬랙 메시지 └── 메시지: "지난주 매출: {{actions.code.total}}원" ``` 중복 체크 [#중복-체크] ``` 트리거: 웹훅 (외부 주문) 액션 1: 행 조회 ├── 데이터모델: 주문 ├── 조건: 외부주문번호 = {{trigger.body.orderId}} └── 제한: 1 액션 2: 조건 분기 ├── If: {{actions.query.count}} = 0 │ └── 행 생성 (새 주문) └── Else: (이미 존재, 스킵) ``` *** 모범 사례 [#모범-사례] 성능 최적화 [#성능-최적화] * **필요한 조건**만 사용하여 결과를 좁히세요 * **제한**을 설정하여 불필요한 데이터 로드를 피하세요 * 자주 조회하는 조건은 **뷰**로 만들어 두세요 결과 없음 처리 [#결과-없음-처리] 조회 결과가 없을 수 있으므로 **조건 분기**로 처리하세요. ``` If: {{actions.query.count}} > 0 → 후속 액션 실행 Else: → 대체 액션 또는 종료 ``` 대량 데이터 주의 [#대량-데이터-주의] 조회 결과가 많을 경우 **반복(Loop)** 액션과 함께 사용하세요. --- # 행 수정 (/docs/node-reference/actions/data/update-row) > 기존 행의 속성 값을 변경합니다. 개요 [#개요] | 항목 | 내용 | | -------- | --------- | | **카테고리** | 데이터 | | **대상** | 데이터모델의 행 | | **출력** | 수정된 행 데이터 | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | -------- | ------------------- | :-: | | **대상 행** | 수정할 행 (트리거 행 또는 검색) | ✅ | | **속성 값** | 변경할 속성과 새 값 | ✅ | *** 대상 행 지정 [#대상-행-지정] 트리거 행 [#트리거-행] 트리거가 발생한 행을 수정합니다. ``` 대상: {{trigger.row}} ``` ID로 지정 [#id로-지정] ``` 대상: 특정 행 ID 행 ID: {{actions.query.rows[0].id}} ``` 조회 결과 [#조회-결과] 이전 액션에서 조회한 행을 수정합니다. ``` 대상: {{actions.query.rows}} ``` *** 속성 값 설정 [#속성-값-설정] 고정 값 [#고정-값] ``` 상태: "완료" ``` 동적 값 [#동적-값] ``` 완료일: {{now}} 승인자: {{trigger.user.name}} ``` 계산 값 [#계산-값] ``` 지연일수: {{dateDiff(trigger.row.마감일, now, "days")}} ``` *** 출력 데이터 [#출력-데이터] ```javascript {{actions.updateRow.row}} // 수정된 행 전체 {{actions.updateRow.row.id}} // 수정된 행 ID {{actions.updateRow.row.상태}} // 수정된 속성 값 ``` *** 활용 예시 [#활용-예시] 상태 변경 + 완료일 기록 [#상태-변경--완료일-기록] ``` 트리거: 버튼 클릭 (완료 버튼) 액션: 행 수정 ├── 대상: {{trigger.row}} ├── 상태: "완료" └── 완료일: {{now}} ``` 마감 지연 처리 [#마감-지연-처리] ``` 트리거: 마감일 도래 조건: 상태 ≠ "완료" 액션: 행 수정 ├── 대상: {{trigger.row}} ├── 상태: "지연" └── 지연일수: {{dateDiff(trigger.row.마감일, now, "days")}} ``` 승인 처리 [#승인-처리] ``` 트리거: 승인 버튼 클릭 액션: 행 수정 ├── 대상: {{trigger.row}} ├── 상태: "승인" ├── 승인일: {{now}} └── 승인자: {{trigger.user.name}} ``` 일괄 수정 [#일괄-수정] ``` 트리거: 일정 (매일 자정) 액션 1: 행 조회 (조건: 마감일 < 오늘 AND 상태 = "진행중") 액션 2: 반복 ({{actions.query.rows}}) 액션 3: 행 수정 ├── 대상: {{loop.current}} └── 상태: "지연" ``` *** 모범 사례 [#모범-사례] 무한 루프 방지 [#무한-루프-방지] 수정이 같은 트리거를 발생시키지 않도록 주의하세요. ``` ❌ 트리거: 행 수정 → 액션: 같은 행의 같은 속성 수정 ✅ 트리거: "상태" 변경 → 액션: "완료일" 수정 (다른 속성) ``` 조건부 수정 [#조건부-수정] 수정이 필요한 경우에만 실행하세요. ``` 조건: 새 상태 ≠ 현재 상태 ``` 변경 이력 [#변경-이력] 중요한 변경은 이력을 남기는 것이 좋습니다. ``` 1. 행 수정 (상태 변경) 2. 행 생성 (변경 이력 데이터모델에 기록) ``` --- # Amazon SP-API (/docs/node-reference/actions/integrations/amazon) > Amazon Selling Partner API를 통한 주문, 재고, 상품, 리포트, 정산, 피드, 취소, 반품을 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ------------------------------------------ | | **카테고리** | 연동 | | **연동 필요** | Amazon SP-API OAuth2 (LWA 자격 증명) | | **지원 리소스** | 주문, 재고 (FBA), 상품 카탈로그, 리포트, 정산, 피드, 취소, 반품 | | **마켓플레이스** | 미국, 일본, 유럽, 싱가포르 등 글로벌 마켓플레이스 | *** 작업 종류 [#작업-종류] 주문 (Orders) [#주문-orders] | 작업 | 설명 | | ------------- | --------------------------------- | | **주문 목록 조회** | 상태, 이행 채널(FBA/MFN), 기간으로 필터링하여 조회 | | **주문 상세 조회** | Amazon 주문 ID로 상세 조회 | | **주문 아이템 조회** | 특정 주문의 품목 상세 조회 | | **구매자 정보 조회** | 주문의 구매자 정보 조회 | | **배송 주소 조회** | 주문의 배송 주소 조회 | | **배송 확인** | 추적 번호 및 배송사 등록 | 재고 (FBA Inventory) [#재고-fba-inventory] | 작업 | 설명 | | ---------------- | ---------------------------- | | **FBA 재고 요약 조회** | 마켓플레이스 또는 ASIN별 FBA 재고 현황 조회 | 상품 (Catalog Items) [#상품-catalog-items] | 작업 | 설명 | | ------------ | ------------------------------------- | | **상품 검색** | 키워드, ASIN, UPC, EAN, ISBN, SKU로 상품 검색 | | **상품 상세 조회** | ASIN으로 상품 상세 정보 조회 | 리포트 (Reports) [#리포트-reports] | 작업 | 설명 | | --------------- | ----------------------- | | **리포트 목록 조회** | 리포트 유형 및 처리 상태별 목록 조회 | | **리포트 요청 생성** | 새 리포트 생성 요청 (데이터 범위 지정) | | **리포트 상태 조회** | 리포트 처리 상태 확인 | | **리포트 문서 다운로드** | 완료된 리포트 문서 다운로드 | | **리포트 취소** | 진행 중인 리포트 요청 취소 | 정산 (Finances) [#정산-finances] | 작업 | 설명 | | ----------------- | ------------------- | | **정산 이벤트 그룹 조회** | 정산 기간별 이벤트 그룹 조회 | | **정산 이벤트 조회** | 특정 그룹의 정산 이벤트 상세 조회 | | **주문별 정산 이벤트 조회** | 특정 주문의 정산 내역 조회 | 피드 (Feeds) [#피드-feeds] | 작업 | 설명 | | ------------ | -------------------- | | **피드 목록 조회** | 피드 유형 및 처리 상태별 목록 조회 | | **피드 생성** | 대량 데이터 업데이트용 피드 생성 | | **피드 상태 조회** | 피드 처리 상태 확인 | | **피드 문서 생성** | 피드 업로드용 문서 생성 | | **피드 문서 조회** | 피드 처리 결과 문서 조회 | | **피드 취소** | 진행 중인 피드 취소 | 취소 (Cancellations) [#취소-cancellations] | 작업 | 설명 | | ---------------------- | ----------------------------- | | **취소된 주문 목록 조회** | 취소 상태 주문 목록 조회 | | **취소 상세 조회** | 취소된 주문의 아이템 상세 (구매자 취소 요청 포함) | | **이행 주문 취소 (FBA/MCF)** | FBA 또는 MCF 이행 주문의 배송 시도 중지 | 반품 (Returns) [#반품-returns] | 작업 | 설명 | | --------------- | -------------------------- | | **반품 사유 코드 조회** | SKU에 대한 반품 사유 코드 목록 조회 | | **이행 반품 생성** | FBA/MCF 이행 주문에 대한 반품 요청 생성 | *** 활용 예시 [#활용-예시] 주문 자동 동기화 [#주문-자동-동기화] ``` 트리거: 일정 (매 15분) 액션 1: Amazon SP-API - 주문 목록 조회 ├── 마켓플레이스: US ├── 주문 상태: Unshipped ├── 주문 생성일 (이후): {{$now.minus(15, 'minutes')}} 액션 2: 반복 (신규 주문) 액션 3: 행 생성 (주문 데이터모델) ``` FBA 재고 모니터링 [#fba-재고-모니터링] ``` 트리거: 일정 (매일 오전 9시) 액션 1: Amazon SP-API - FBA 재고 요약 조회 ├── SKU 목록: "SKU-001, SKU-002, SKU-003" 액션 2: 반복 (재고 부족 품목) 액션 3: 슬랙 메시지 └── 메시지: "FBA 재고 부족: {{loop.current.sellerSku}} ({{loop.current.totalQuantity}}개)" ``` 배송 확인 자동 처리 [#배송-확인-자동-처리] ``` 트리거: 웹훅 (물류 시스템 출고 완료) 액션: Amazon SP-API - 배송 확인 ├── 주문 ID: {{trigger.body.amazonOrderId}} ├── 배송 추적 번호: {{trigger.body.trackingNumber}} └── 배송사 코드: FEDEX ``` *** 모범 사례 [#모범-사례] <Callout type="info"> Amazon SP-API는 요청 제한(Throttling)이 있습니다. 대량 처리 시 피드를 활용하고, 주문 조회는 `lastUpdatedAfter` 필터로 변경분만 가져오는 것이 효율적입니다. </Callout> 마켓플레이스 설정 [#마켓플레이스-설정] 노드 설정에서 대상 마켓플레이스를 선택하세요. 주요 마켓플레이스: * 미국 (US), 일본 (JP), 영국 (UK), 독일 (DE) 등 이행 채널 구분 [#이행-채널-구분] * **FBA (Fulfillment by Amazon)**: Amazon이 보관, 배송, 고객 서비스 처리 * **MFN (Merchant Fulfilled Network)**: 판매자가 직접 배송 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # Google Sheets (/docs/node-reference/actions/integrations/google-sheets) > Google Sheets에 데이터를 추가하거나 업데이트합니다. 개요 [#개요] | 항목 | 내용 | | --------- | --------------- | | **카테고리** | 연동 | | **연동 필요** | Google OAuth 연결 | | **출력** | 작업 결과 | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ---------- | -------------------------------- | :-: | | **스프레드시트** | 대상 스프레드시트 | ✅ | | **시트** | 대상 시트 (탭) | ✅ | | **작업** | 데이터 읽기, 행 추가, 행 수정, 행 삭제, 시트 비우기 | ✅ | *** 작업 종류 [#작업-종류] 행 추가 (Append Row) [#행-추가-append-row] 새 행을 스프레드시트 **맨 아래에 추가**합니다. ``` 열 매핑: A: {{trigger.row.주문번호}} B: {{trigger.row.고객명}} C: {{trigger.row.금액}} D: {{format(now, "YYYY-MM-DD HH:mm")}} ``` 행 업데이트 (Update Row) [#행-업데이트-update-row] 조건에 맞는 **기존 행을 수정**합니다. ``` 조건: A열 = {{trigger.row.주문번호}} 업데이트: D: {{trigger.row.상태}} E: {{format(now, "YYYY-MM-DD")}} ``` 행 삭제 (Delete Row) [#행-삭제-delete-row] 지정된 행 번호의 **행을 삭제**합니다. ``` 행 번호: 5 ``` 시트 비우기 (Clear) [#시트-비우기-clear] 지정된 범위의 **데이터를 모두 삭제**합니다. ``` 범위: A2:E100 (헤더 제외) ``` 데이터 읽기 (Read Data) [#데이터-읽기-read-data] 스프레드시트 데이터를 **조회**합니다. ``` 범위: A1:E100 조건: B열 = {{trigger.row.고객명}} ``` *** 출력 데이터 [#출력-데이터] ```javascript // 행 추가 {{actions.sheets.rowNumber}} // 추가된 행 번호 // 데이터 읽기 {{actions.sheets.rows}} // 조회된 데이터 {{actions.sheets.rows[0]}} // 첫 번째 행 {{actions.sheets.count}} // 조회된 행 수 ``` *** 활용 예시 [#활용-예시] 주문 기록 [#주문-기록] ``` 트리거: 주문 데이터모델 - 행 생성 액션: Google Sheets - 행 추가 ├── 스프레드시트: "2024년 주문 현황" ├── 시트: "주문목록" └── 데이터: A: {{trigger.row.주문번호}} B: {{trigger.row.고객명}} C: {{trigger.row.금액}} D: {{format(trigger.row.주문일, "YYYY-MM-DD")}} ``` 매출 리포트 업데이트 [#매출-리포트-업데이트] ``` 트리거: 일정 (매일 자정) 액션 1: 행 조회 (오늘 매출 합계) 액션 2: Google Sheets - 행 추가 ├── 스프레드시트: "매출 리포트" ├── 시트: "일별" └── 데이터: A: {{format(today, "YYYY-MM-DD")}} B: {{actions.query.totalAmount}} C: {{actions.query.orderCount}} ``` 기존 데이터 업데이트 [#기존-데이터-업데이트] ``` 트리거: 배송 상태 변경 액션: Google Sheets - 행 업데이트 ├── 조건: A열 (주문번호) = {{trigger.row.주문번호}} └── 업데이트: E: {{trigger.row.배송상태}} F: {{format(now, "YYYY-MM-DD HH:mm")}} ``` *** 모범 사례 [#모범-사례] 헤더 행 유지 [#헤더-행-유지] 첫 번째 행은 **헤더**로 유지하고, 데이터는 2행부터 추가하세요. 날짜 형식 통일 [#날짜-형식-통일] 날짜는 일관된 형식으로 저장하세요. ``` {{format(now, "YYYY-MM-DD HH:mm:ss")}} ``` 대량 데이터 주의 [#대량-데이터-주의] 한 번에 너무 많은 데이터를 처리하면 **API 제한**에 걸릴 수 있습니다. --- # HTTP 요청 (/docs/node-reference/actions/integrations/http-request) > 외부 API를 호출합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | -------- | ----------- | | **카테고리** | 연동 | | **대상** | 외부 REST API | | **출력** | API 응답 | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | -------------- | --------------------------------------------- | :-: | | **URL** | 요청 URL | ✅ | | **메서드** | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS | ✅ | | **헤더** | Authorization, Content-Type 등 | | | **바디** | 요청 본문 (JSON) | | | **인증** | 없음, Basic Auth, Bearer Token, API Key, OAuth2 | | | **응답 형식** | JSON, Text, Binary, 자동 감지 | | | **타임아웃** | 요청 제한 시간 (기본 30초, 최대 5분) | | | **에러 무시** | HTTP 에러 응답(4xx, 5xx)을 에러로 처리하지 않음 | | | **리다이렉트 따라가기** | 리다이렉트 자동 처리 (기본 활성) | | *** 메서드 [#메서드] | 메서드 | 용도 | | ----------- | --------- | | **GET** | 데이터 조회 | | **POST** | 데이터 생성 | | **PUT** | 데이터 전체 수정 | | **PATCH** | 데이터 부분 수정 | | **DELETE** | 데이터 삭제 | | **HEAD** | 헤더만 조회 | | **OPTIONS** | 지원 메서드 확인 | *** 헤더 설정 [#헤더-설정] Content-Type [#content-type] ``` Content-Type: application/json ``` 인증 [#인증] ``` Authorization: Bearer {{credentials.apiKey}} Authorization: Basic {{base64(username:password)}} ``` 커스텀 헤더 [#커스텀-헤더] ``` X-Custom-Header: {{trigger.row.customValue}} ``` *** 바디 (요청 본문) [#바디-요청-본문] JSON [#json] ```json { "customer": "{{trigger.row.고객명}}", "amount": {{trigger.row.금액}}, "items": {{trigger.row.상품목록}} } ``` Form Data [#form-data] ``` name={{trigger.row.이름}}&email={{trigger.row.이메일}} ``` *** 인증 방식 [#인증-방식] Bearer Token [#bearer-token] ``` Authorization: Bearer {{credentials.apiKey}} ``` Basic Auth [#basic-auth] ``` Authorization: Basic {{base64("username:password")}} ``` OAuth 2.0 [#oauth-20] Credentials에 등록된 OAuth 연결을 사용합니다. *** 출력 데이터 [#출력-데이터] ```javascript {{actions.http.status}} // HTTP 상태 코드 {{actions.http.response}} // 응답 본문 (JSON) {{actions.http.response.id}} // 응답의 특정 필드 {{actions.http.headers}} // 응답 헤더 ``` *** 활용 예시 [#활용-예시] 외부 시스템에 데이터 전송 [#외부-시스템에-데이터-전송] ```http POST https://api.external.com/orders Headers: Authorization: Bearer {{credentials.apiKey}} Content-Type: application/json Body: { "customer": "{{trigger.row.고객명}}", "amount": {{trigger.row.금액}}, "items": {{trigger.row.상품목록}} } ``` 외부 데이터 조회 [#외부-데이터-조회] ```http GET https://api.external.com/products/{{trigger.row.productId}} Headers: Authorization: Bearer {{credentials.apiKey}} ``` 슬랙 웹훅 [#슬랙-웹훅] ```http POST https://hooks.slack.com/services/xxx/yyy/zzz Headers: Content-Type: application/json Body: { "text": "새 주문: {{trigger.row.주문번호}}" } ``` *** 에러 처리 [#에러-처리] <Callout type="warn"> API 호출이 실패할 수 있습니다. 에러 처리를 고려하세요. </Callout> 상태 코드 확인 [#상태-코드-확인] ```javascript // 조건 분기에서 {{actions.http.status}} = 200 // 성공 {{actions.http.status}} >= 400 // 에러 ``` 재시도 [#재시도] HTTP 요청은 실패 시 자동으로 재시도합니다 (기본 3회). *** 모범 사례 [#모범-사례] 민감 정보 보호 [#민감-정보-보호] API 키는 **Credentials**에 저장하고 변수로 참조하세요. ``` ❌ Authorization: Bearer sk-1234567890 ✅ Authorization: Bearer {{credentials.openaiKey}} ``` 타임아웃 설정 [#타임아웃-설정] 외부 API 응답이 느릴 수 있으므로 적절한 타임아웃을 설정하세요. 응답 검증 [#응답-검증] 응답 형식이 예상과 다를 수 있으므로 검증 후 사용하세요. --- # Neon (/docs/node-reference/actions/integrations/neon) > Neon Serverless Postgres의 프로젝트, 브랜치, 데이터베이스, 엔드포인트, 역할을 관리하고 SQL 쿼리를 실행합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ------------------------------------------- | | **카테고리** | 연동 | | **연동 필요** | Neon API Key | | **지원 리소스** | 프로젝트, 브랜치, 데이터베이스, 엔드포인트, 역할, 작업 이력, SQL 쿼리 | *** 작업 종류 [#작업-종류] 프로젝트 [#프로젝트] | 작업 | 설명 | | ------------- | ----------------------------------- | | **프로젝트 목록** | 모든 프로젝트 목록 조회 | | **프로젝트 조회** | 특정 프로젝트 상세 조회 | | **프로젝트 생성** | 새 프로젝트 생성 (이름, 리전 지정) | | **프로젝트 업데이트** | 프로젝트 이름 변경 | | **프로젝트 삭제** | 프로젝트 삭제 | | **연결 문자열 조회** | 데이터베이스 연결 문자열(Connection String) 조회 | 브랜치 [#브랜치] | 작업 | 설명 | | ------------- | --------------------------------------- | | **브랜치 목록** | 프로젝트의 브랜치 목록 조회 | | **브랜치 조회** | 특정 브랜치 상세 조회 | | **브랜치 생성** | 부모 브랜치에서 새 브랜치 분기 | | **브랜치 업데이트** | 브랜치 이름 변경 및 보호 설정 | | **브랜치 삭제** | 브랜치 삭제 | | **기본 브랜치 설정** | 기본 브랜치로 설정 | | **브랜치 복원** | 특정 시점으로 브랜치 복원 (Point-in-Time Recovery) | | **부모로 리셋** | 부모 브랜치 상태로 리셋 | 데이터베이스 [#데이터베이스] | 작업 | 설명 | | ------------- | ----------------- | | **데이터베이스 목록** | 브랜치의 데이터베이스 목록 조회 | | **데이터베이스 조회** | 특정 데이터베이스 상세 조회 | | **데이터베이스 생성** | 새 데이터베이스 생성 | | **데이터베이스 삭제** | 데이터베이스 삭제 | 엔드포인트 [#엔드포인트] | 작업 | 설명 | | -------------- | --------------------------- | | **엔드포인트 목록** | 프로젝트의 엔드포인트 목록 조회 | | **엔드포인트 조회** | 특정 엔드포인트 상세 조회 | | **엔드포인트 생성** | 새 엔드포인트 생성 (읽기/쓰기 또는 읽기 전용) | | **엔드포인트 업데이트** | 커넥션 풀링, 타임아웃 등 설정 변경 | | **엔드포인트 삭제** | 엔드포인트 삭제 | | **엔드포인트 시작** | 일시정지된 엔드포인트 시작 | | **엔드포인트 일시정지** | 엔드포인트 일시정지 | | **엔드포인트 재시작** | 엔드포인트 재시작 | 역할 [#역할] | 작업 | 설명 | | ------------ | ------------- | | **역할 목록** | 브랜치의 역할 목록 조회 | | **역할 조회** | 특정 역할 상세 조회 | | **역할 생성** | 새 역할 생성 | | **역할 삭제** | 역할 삭제 | | **비밀번호 조회** | 역할의 비밀번호 조회 | | **비밀번호 재설정** | 역할의 비밀번호 재설정 | 작업 이력 [#작업-이력] | 작업 | 설명 | | ------------ | -------------- | | **작업 이력 목록** | 프로젝트의 작업 이력 조회 | | **작업 상세 조회** | 특정 작업 상세 조회 | SQL 쿼리 [#sql-쿼리] | 작업 | 설명 | | ------------- | ------------------------------------ | | **SQL 쿼리 실행** | SQL 쿼리 실행 (파라미터 바인딩 지원, $1, $2 형식) | | **트랜잭션 실행** | 여러 SQL을 트랜잭션 내에서 순차 실행 (격리 수준 설정 가능) | *** 지원 리전 [#지원-리전] | 리전 | 코드 | | ------- | -------------------- | | 서울 | `aws-ap-northeast-2` | | 도쿄 | `aws-ap-northeast-1` | | 싱가포르 | `aws-ap-southeast-1` | | 미국 동부 | `aws-us-east-1` | | 미국 동부 2 | `aws-us-east-2` | | 미국 서부 | `aws-us-west-2` | | 유럽 중부 | `aws-eu-central-1` | | 유럽 서부 | `aws-eu-west-1` | | 유럽 서부 2 | `aws-eu-west-2` | *** 활용 예시 [#활용-예시] 데이터 조회 후 데이터모델 동기화 [#데이터-조회-후-데이터모델-동기화] ``` 트리거: 일정 (매 시간) 액션 1: Neon - SQL 쿼리 실행 ├── 연결 문자열: postgresql://user:pass@host/db ├── SQL: SELECT * FROM orders WHERE created_at > $1 ├── 파라미터: ["{{$now.minus(1, 'hour')}}"] 액션 2: 반복 (조회 결과) 액션 3: 행 생성 (주문 데이터모델) ``` 개발 환경 자동 생성 [#개발-환경-자동-생성] ``` 트리거: 웹훅 (PR 생성 이벤트) 액션 1: Neon - 브랜치 생성 ├── 프로젝트 ID: "project-abc123" ├── 브랜치 이름: {{trigger.body.branchName}} 액션 2: 슬랙 메시지 └── 메시지: "개발 DB 브랜치 생성 완료: {{actions.neon.branchName}}" ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> Neon API Key는 Neon 콘솔 > Settings > API Keys에서 생성할 수 있습니다. SQL 쿼리 실행 시에는 별도의 연결 문자열이 필요하며, 프로젝트 > Connection Details에서 확인할 수 있습니다. </Callout> SQL 파라미터 바인딩 [#sql-파라미터-바인딩] SQL 인젝션 방지를 위해 반드시 파라미터 바인딩(`$1`, `$2`)을 사용하세요. 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # OpenAI (/docs/node-reference/actions/integrations/openai) > AI 처리를 실행합니다. 개요 [#개요] | 항목 | 내용 | | --------- | ------------ | | **카테고리** | 연동 | | **연동 필요** | OpenAI API 키 | | **출력** | AI 응답 | *** 리소스 [#리소스] | 리소스 | 설명 | | ------------------- | ------------ | | **Chat / GPT** | 대화형 텍스트 생성 | | **이미지 (DALL-E)** | 이미지 생성 | | **텍스트 Embedding** | 텍스트를 벡터로 변환 | | **음성 생성 (TTS)** | 텍스트를 음성으로 변환 | | **음성 인식 (Whisper)** | 음성을 텍스트로 변환 | *** Chat 설정 옵션 [#chat-설정-옵션] | 옵션 | 설명 | 필수 | | --------------- | ----------------------------------------------------------------------- | :-: | | **모델** | GPT-4.1, GPT-4.1 Mini, GPT-4.1 Nano, GPT-4o, GPT-4o Mini, o3, o4-mini 등 | | | **시스템 프롬프트** | AI의 역할과 행동 방식 정의 | | | **메시지** | AI에게 보낼 메시지 (변수 사용 가능) | ✅ | | **Temperature** | 창의성 조절 (0\~2, 기본 0.7) | | | **Max Tokens** | 응답 최대 길이 (기본 4096) | | | **JSON 모드** | 응답을 JSON 형식으로 강제 | | *** 활용 사례 [#활용-사례] 텍스트 요약 [#텍스트-요약] ``` 입력: {{trigger.row.긴문서}} 프롬프트: "다음 문서를 3문장으로 요약해주세요." ``` 감정 분석 [#감정-분석] ``` 입력: {{trigger.row.고객피드백}} 프롬프트: "다음 고객 피드백의 감정을 분석하고 '긍정', '부정', '중립' 중 하나로 분류해주세요." ``` 번역 [#번역] ``` 입력: {{trigger.row.영문텍스트}} 프롬프트: "다음 영문 텍스트를 자연스러운 한국어로 번역해주세요." ``` 분류 [#분류] ``` 입력: {{trigger.row.문의내용}} 프롬프트: "다음 고객 문의를 '기술지원', '결제문의', '배송문의', '기타' 중 하나로 분류해주세요." ``` 데이터 추출 [#데이터-추출] ``` 입력: {{trigger.row.이메일본문}} 프롬프트: "다음 이메일에서 주문번호, 고객명, 요청사항을 JSON 형식으로 추출해주세요." 응답 형식: JSON ``` *** 출력 데이터 [#출력-데이터] ```javascript {{actions.openai.result}} // AI 응답 텍스트 {{actions.openai.result.감정}} // JSON 응답의 특정 필드 {{actions.openai.usage}} // 토큰 사용량 ``` *** 활용 예시 [#활용-예시] 고객 피드백 자동 분류 [#고객-피드백-자동-분류] ``` 트리거: 피드백 데이터모델 - 행 생성 액션 1: OpenAI ├── 입력: {{trigger.row.피드백내용}} ├── 프롬프트: "감정을 분석하고 JSON으로 반환: {sentiment, keywords, summary}" └── 응답 형식: JSON 액션 2: 행 수정 ├── 감정: {{actions.openai.result.sentiment}} ├── 키워드: {{actions.openai.result.keywords}} └── 요약: {{actions.openai.result.summary}} ``` 문의 자동 라우팅 [#문의-자동-라우팅] ``` 트리거: 문의 데이터모델 - 행 생성 액션 1: OpenAI ├── 입력: {{trigger.row.문의내용}} └── 프롬프트: "분류: 기술지원/결제/배송/기타" 액션 2: 조건 분기 ├── 기술지원 → 기술팀 담당자 배정 ├── 결제 → 결제팀 담당자 배정 └── 기타 → 고객지원팀 배정 ``` 자동 답변 초안 생성 [#자동-답변-초안-생성] ``` 트리거: 문의 데이터모델 - 행 생성 액션 1: OpenAI ├── 입력: {{trigger.row.문의내용}} └── 프롬프트: "친절하고 전문적인 답변 초안을 작성해주세요." 액션 2: 행 수정 └── 답변초안: {{actions.openai.result}} ``` *** 모범 사례 [#모범-사례] 프롬프트 명확하게 [#프롬프트-명확하게] * 원하는 **출력 형식**을 명시하세요 * **예시**를 포함하면 더 정확한 결과를 얻습니다 * JSON 출력이 필요하면 응답 형식을 JSON으로 설정하세요 토큰 비용 관리 [#토큰-비용-관리] * 불필요하게 긴 입력은 피하세요 * 요약이나 추출 작업에는 **GPT-4.1 Nano** 또는 **GPT-4o Mini**가 비용 효율적입니다 에러 처리 [#에러-처리] AI 응답이 예상과 다를 수 있으므로 검증 후 사용하세요. --- # 프린터 인쇄 (/docs/node-reference/actions/integrations/printer) > 문서 렌더링과 인쇄 노드를 조합하여 HTML 템플릿 기반 문서를 프린터로 출력합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | --------- | --------------- | | **카테고리** | 연동 | | **연동 필요** | 없음 (브라우저 인쇄 사용) | | **관련 노드** | 문서 렌더링 + 인쇄 | <Callout type="info"> 프린터 인쇄는 **문서 렌더링** 노드와 **인쇄** 노드 두 개를 조합하여 사용합니다. 문서 렌더링 노드로 HTML 문서를 생성하고, 인쇄 노드로 출력합니다. </Callout> *** 문서 렌더링 노드 [#문서-렌더링-노드] HTML 템플릿에 데이터를 적용하여 인쇄용 문서를 생성합니다. 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ------------ | ------------------------------------- | :-: | | **HTML 템플릿** | 워크플로우 표현식으로 데이터를 삽입할 수 있는 HTML | ✅ | | **CSS 스타일** | 인쇄용 CSS 스타일 | | | **용지 크기** | A4, A5, 택배 송장 (100mm x 150mm), 사용자 지정 | | | **용지 방향** | 세로 또는 가로 | | 용지 크기 [#용지-크기] | 옵션 | 설명 | | ---------- | ------------------------- | | **A4** | 표준 A4 용지 | | **A5** | A5 용지 | | **택배 송장** | 100mm x 150mm (택배 라벨 용) | | **사용자 지정** | CSS @page size 형식으로 직접 지정 | *** 인쇄 노드 [#인쇄-노드] 문서 렌더링 노드의 출력을 받아 프린터로 출력합니다. 설정 옵션 [#설정-옵션-1] | 옵션 | 설명 | 필수 | | ------------ | ----------------------------------- | :-: | | **인쇄 방식** | 바로 인쇄 또는 미리보기 후 인쇄 | | | **HTML 콘텐츠** | 인쇄할 HTML (document-render 노드 출력 연결) | ✅ | 인쇄 방식 [#인쇄-방식] | 방식 | 설명 | | ------------- | ----------------------------------- | | **바로 인쇄** | 숨겨진 iframe으로 인쇄 대화상자만 표시 (현재 화면 유지) | | **미리보기 후 인쇄** | 새 탭에서 문서를 확인한 뒤 인쇄 | *** 활용 예시 [#활용-예시] 택배 송장 인쇄 [#택배-송장-인쇄] ``` 트리거: 데이터모델 - 행 생성 (출고 요청) 액션 1: 문서 렌더링 ├── HTML 템플릿: "<div><h2>{{$json.택배사}}</h2><p>수령인: {{$json.고객명}}</p><p>주소: {{$json.주소}}</p></div>" ├── 용지 크기: 택배 송장 (100mm x 150mm) └── 용지 방향: 세로 액션 2: 인쇄 ├── 인쇄 방식: 바로 인쇄 └── HTML 콘텐츠: {{$json.html}} ``` 거래명세서 출력 [#거래명세서-출력] ``` 트리거: 수동 실행 액션 1: 데이터 조회 (거래 내역) 액션 2: 문서 렌더링 ├── HTML 템플릿: 거래명세서 HTML ├── CSS 스타일: "body { font-family: 'Malgun Gothic'; }" ├── 용지 크기: A4 └── 용지 방향: 세로 액션 3: 인쇄 ├── 인쇄 방식: 미리보기 후 인쇄 └── HTML 콘텐츠: {{$json.html}} ``` 대량 라벨 인쇄 [#대량-라벨-인쇄] ``` 트리거: 수동 실행 액션 1: 데이터 조회 (출고 대상 목록) 액션 2: 반복 (출고 목록) 액션 3: 문서 렌더링 ├── HTML 템플릿: 라벨 HTML ├── 용지 크기: 사용자 지정 (60mm 30mm) 액션 4: 인쇄 └── HTML 콘텐츠: {{$json.html}} ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 인쇄 노드는 브라우저의 인쇄 기능을 사용합니다. 서버 사이드에서 자동 인쇄는 지원하지 않으며, 사용자가 인쇄 대화상자에서 최종 확인해야 합니다. </Callout> HTML 템플릿 작성 [#html-템플릿-작성] * 워크플로우 표현식 `{{ $json.필드명 }}`으로 데이터를 삽입합니다 * 인쇄 전용 CSS를 활용하여 화면과 인쇄 결과를 다르게 설정할 수 있습니다 * 한글 폰트 사용 시 `font-family: 'Malgun Gothic', sans-serif;`를 권장합니다 --- # Qoo10 (/docs/node-reference/actions/integrations/qoo10) > Qoo10 QSM API를 통한 주문, 상품, 재고, 배송, CS를 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ---------------------------- | | **카테고리** | 연동 | | **연동 필요** | Qoo10 API Key | | **지원 리소스** | 주문, 상품, 재고, 배송, 문의/CS, 공통 정보 | | **지원 리전** | 일본, 싱가포르, 인도네시아, 말레이시아, 홍콩 | *** 작업 종류 [#작업-종류] 주문 [#주문] | 작업 | 설명 | | ------------ | --------------------------- | | **주문 목록 조회** | 주문 상태, 기간으로 필터링하여 목록 조회 | | **주문 상세 조회** | 주문번호(PackNo/OrderNo)로 상세 조회 | | **주문 확인 처리** | 주문 확인 완료 처리 | | **주문 취소** | 주문 취소 (사유 입력) | | **환불 처리** | 환불 처리 (사유 입력) | 상품 [#상품] | 작업 | 설명 | | ------------ | ----------------------------- | | **상품 목록 조회** | 상품 상태별 목록 조회 | | **상품 상세 조회** | 판매자 상품코드 또는 Qoo10 상품코드로 조회 | | **상품 등록** | 새 상품 등록 (상품명, 가격, 카테고리, 옵션 등) | | **상품 수정** | 기존 상품 정보 수정 | | **가격/재고 수정** | 상품 가격 및 재고 수량 변경 | | **판매 상태 변경** | 판매중/판매대기/판매중지/품절 상태 변경 | 재고 [#재고] | 작업 | 설명 | | --------- | ------------------------ | | **재고 조회** | 판매자 상품코드로 재고 조회 (옵션별 가능) | | **재고 수정** | 재고 수량 변경 (옵션별 가능) | 배송 [#배송] | 작업 | 설명 | | ------------- | --------------------- | | **송장번호 등록** | 묶음 배송번호에 택배사와 송장번호 등록 | | **송장번호 수정** | 기존 등록된 송장번호 변경 | | **택배사 목록 조회** | 사용 가능한 택배사 목록 조회 | 문의/CS [#문의cs] | 작업 | 설명 | | -------------- | ------------------ | | **Q\&A 목록 조회** | 고객 문의(Q\&A) 목록 조회 | | **Q\&A 답변 등록** | 고객 문의에 답변 등록 | | **클레임 목록 조회** | 취소/반품/교환 클레임 목록 조회 | 공통 정보 [#공통-정보] | 작업 | 설명 | | -------------- | ---------------- | | **카테고리 목록 조회** | Qoo10 카테고리 트리 조회 | | **배송 그룹 조회** | 등록된 배송비 설정 그룹 조회 | *** 주요 택배사 코드 [#주요-택배사-코드] | 코드 | 택배사 | | ---------- | --------------- | | `CJGLS` | CJ대한통운 | | `LOTTE` | 롯데택배 | | `HANJIN` | 한진택배 | | `LOGEN` | 로젠택배 | | `EPOST` | 우체국택배 | | `YAMATO` | Yamato (일본) | | `SAGAWA` | Sagawa (일본) | | `JPPOST` | Japan Post | | `SINGPOST` | SingPost (싱가포르) | | `NINJAVAN` | Ninja Van | | `JNT` | J\&T Express | *** 활용 예시 [#활용-예시] 주문 자동 확인 [#주문-자동-확인] ``` 트리거: 일정 (매 10분) 액션 1: Qoo10 - 주문 목록 조회 (신규주문) 액션 2: 반복 (신규 주문) 액션 3: Qoo10 - 주문 확인 처리 ├── 주문번호: {{loop.current.orderId}} └── 메모: "자동 확인 처리" ``` 송장 자동 입력 [#송장-자동-입력] ``` 트리거: 웹훅 (물류 시스템 출고 완료) 액션: Qoo10 - 송장번호 등록 ├── 묶음 배송번호: {{trigger.body.packNo}} ├── 택배사: CJGLS └── 송장번호: {{trigger.body.trackingNo}} ``` 고객 문의 알림 [#고객-문의-알림] ``` 트리거: 일정 (매 30분) 액션 1: Qoo10 - Q&A 목록 조회 (미답변) 액션 2: 반복 (미답변 문의) 액션 3: 슬랙 메시지 └── 메시지: "미답변 Qoo10 문의: {{loop.current.question}}" ``` *** 모범 사례 [#모범-사례] <Callout type="info"> Qoo10 API Key는 판매자 센터에서 담당 매니저에게 문의하여 발급받을 수 있습니다. 리전(일본, 싱가포르 등)에 따라 API 엔드포인트가 다르므로 리전 설정에 유의하세요. </Callout> 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # SAP S/4HANA (/docs/node-reference/actions/integrations/sap) > SAP S/4HANA Cloud OData API를 통한 비즈니스 파트너, 판매/구매 주문, 자재, 송장을 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ----------------------------------------- | | **카테고리** | 연동 | | **연동 필요** | SAP S/4HANA Cloud OAuth2 인증 | | **지원 리소스** | 비즈니스 파트너, 판매 주문, 구매 주문, 자재, 송장, 커스텀 OData | *** 작업 종류 [#작업-종류] 비즈니스 파트너 [#비즈니스-파트너] | 작업 | 설명 | | ----------- | ----------------- | | **목록 조회** | 비즈니스 파트너 목록 조회 | | **상세 조회** | 특정 비즈니스 파트너 정보 조회 | | **생성** | 새 비즈니스 파트너 등록 | | **수정** | 비즈니스 파트너 정보 수정 | | **고객 목록** | 고객 유형 파트너만 조회 | | **공급업체 목록** | 공급업체 유형 파트너만 조회 | | **주소 조회** | 특정 파트너의 주소 정보 조회 | 판매 주문 [#판매-주문] | 작업 | 설명 | | --------- | ---------------- | | **목록 조회** | 판매 주문 목록 조회 | | **상세 조회** | 특정 판매 주문 상세 정보 | | **생성** | 판매 주문 생성 | | **수정** | 판매 주문 수정 | | **항목 조회** | 판매 주문의 라인 아이템 조회 | | **항목 생성** | 판매 주문에 라인 아이템 추가 | 구매 주문 [#구매-주문] | 작업 | 설명 | | --------- | ---------------- | | **목록 조회** | 구매 주문 목록 조회 | | **상세 조회** | 특정 구매 주문 상세 정보 | | **생성** | 구매 주문 생성 | | **수정** | 구매 주문 수정 | | **항목 조회** | 구매 주문의 라인 아이템 조회 | 자재 [#자재] | 작업 | 설명 | | ---------- | ---------------- | | **목록 조회** | 자재 목록 조회 | | **상세 조회** | 특정 자재 상세 정보 | | **재고 조회** | 플랜트/저장 위치별 재고 조회 | | **가용성 확인** | 자재 가용 수량 확인 | 송장 [#송장] | 작업 | 설명 | | --------- | ----------------- | | **목록 조회** | 송장 목록 조회 | | **상세 조회** | 특정 송장 상세 정보 | | **생성** | 송장 생성 | | **전기** | 송장 전기(Posting) 처리 | 커스텀 OData [#커스텀-odata] | 작업 | 설명 | | --------------- | ------------------- | | **조회 (GET)** | 사용자 정의 OData 서비스 조회 | | **생성 (POST)** | 사용자 정의 엔티티 생성 | | **수정 (PUT)** | 사용자 정의 엔티티 수정 | | **삭제 (DELETE)** | 사용자 정의 엔티티 삭제 | *** OData 쿼리 옵션 [#odata-쿼리-옵션] 모든 리소스에서 아래 OData 쿼리 옵션을 사용할 수 있습니다. | 옵션 | 설명 | 예시 | | ------------ | ----------------- | ------------------------------------- | | **$filter** | 필터 조건 | `BusinessPartnerCategory eq '1'` | | **$select** | 반환할 필드 | `BusinessPartner,BusinessPartnerName` | | **$expand** | 관련 엔티티 확장 | `to_SalesOrderItem` | | **$orderby** | 정렬 기준 | `CreationDate desc` | | **$top** | 최대 항목 수 (1\~1000) | `100` | | **$skip** | 건너뛸 항목 수 | `0` | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ------------ | ----------- | :-: | | **OData 버전** | V2 또는 V4 선택 | | | **리소스** | 작업할 리소스 선택 | ✅ | | **작업** | 리소스별 수행할 작업 | ✅ | *** 활용 예시 [#활용-예시] 신규 고객 자동 등록 [#신규-고객-자동-등록] ``` 트리거: 데이터모델 - 행 생성 (고객 등록 요청) 액션 1: SAP S/4HANA - 비즈니스 파트너 생성 ├── 카테고리: 개인 ├── 파트너명: {{trigger.row.고객명}} 액션 2: 행 수정 └── SAP_ID: {{actions.sap.BusinessPartner}} ``` 재고 부족 알림 [#재고-부족-알림] ``` 트리거: 일정 (매일 오전 9시) 액션 1: SAP S/4HANA - 자재 재고 조회 ├── 자재 ID: {{trigger.row.materialId}} ├── 플랜트: "1710" 액션 2: 조건 분기 (재고 < 안전재고) 액션 3: 슬랙 메시지 └── 메시지: "재고 부족: {{actions.sap.Material}} ({{actions.sap.AvailableStock}}개)" ``` 판매 주문 → 송장 자동 생성 [#판매-주문--송장-자동-생성] ``` 트리거: 웹훅 (판매 주문 배송 완료) 액션 1: SAP S/4HANA - 판매 주문 상세 조회 ├── 판매 주문 ID: {{trigger.body.salesOrderId}} 액션 2: SAP S/4HANA - 송장 생성 └── 데이터: {{actions.sap.salesOrder}} ``` *** 모범 사례 [#모범-사례] <Callout type="info"> SAP S/4HANA Cloud는 OData 프로토콜을 사용합니다. API 버전(V2/V4)에 따라 지원되는 기능이 다를 수 있으니 SAP API Business Hub에서 확인하세요. </Callout> OData 버전 선택 [#odata-버전-선택] * **V2**: 기존 API와의 호환성이 높음. 대부분의 표준 API가 V2를 지원 * **V4**: 최신 API. 더 풍부한 쿼리 기능 제공 에러 처리 [#에러-처리] SAP API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # Supabase (/docs/node-reference/actions/integrations/supabase) > Supabase 데이터베이스, 인증(Auth), 스토리지를 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | --------------------------- | | **카테고리** | 연동 | | **연동 필요** | Supabase 프로젝트 URL + API Key | | **지원 리소스** | 데이터베이스, 인증 (Auth), 스토리지 | *** 작업 종류 [#작업-종류] 데이터베이스 [#데이터베이스] | 작업 | 설명 | | ---------------------- | ------------------------------ | | **데이터 조회 (Select)** | 테이블 데이터 조회 (필터, 정렬, 페이지네이션 지원) | | **데이터 삽입 (Insert)** | 테이블에 새 레코드 삽입 | | **데이터 수정 (Update)** | 필터 조건에 맞는 레코드 수정 | | **데이터 삭제 (Delete)** | 필터 조건에 맞는 레코드 삭제 | | **데이터 삽입/수정 (Upsert)** | 충돌 시 수정, 없으면 삽입 | | **RPC 호출 (저장 프로시저)** | Postgres 함수 호출 | 지원 필터 연산자 [#지원-필터-연산자] 기본 비교(`eq`, `neq`, `gt`, `gte`, `lt`, `lte`), 패턴 매칭(`like`, `ilike`), NULL 체크(`is`), 배열 포함(`in`, `cs`, `cd`, `ov`), 범위 연산, 전문 검색(`fts`, `plfts`, `phfts`, `wfts`) 등을 지원합니다. 인증 (Auth) [#인증-auth] | 작업 | 설명 | | ---------------- | ------------------------------ | | **사용자 목록 조회** | 전체 사용자 목록 (페이지네이션) | | **사용자 조회 (ID)** | UUID로 사용자 조회 | | **사용자 조회 (이메일)** | 이메일로 사용자 조회 | | **사용자 생성** | 새 사용자 생성 (이메일, 비밀번호, 메타데이터) | | **사용자 수정** | 사용자 정보 수정 | | **사용자 삭제** | 사용자 삭제 | | **사용자 차단** | 기간 지정하여 사용자 차단 (24h, 7d, 영구 등) | | **사용자 차단 해제** | 차단 해제 | | **사용자 로그아웃** | 모든/다른/현재 세션 로그아웃 | | **링크 생성** | 초대, 회원가입, 매직링크, 비밀번호 복구 링크 생성 | | **MFA 요소 목록 조회** | 사용자의 MFA 요소 조회 | | **MFA 요소 삭제** | MFA 요소 삭제 | 스토리지 [#스토리지] | 작업 | 설명 | | ----------------- | ---------------------------- | | **파일 목록 조회** | 버킷/폴더 내 파일 목록 조회 | | **파일 업로드** | 파일 업로드 (Base64 또는 URL) | | **파일 다운로드** | 파일 다운로드 | | **파일 삭제** | 파일 삭제 | | **파일 이동** | 파일을 다른 경로로 이동 | | **파일 복사** | 파일 복사 | | **공개 URL 생성** | 공개 버킷의 파일 URL 생성 | | **서명된 URL 생성** | 만료 시간이 있는 서명된 URL 생성 | | **서명된 URL 일괄 생성** | 여러 파일의 서명된 URL 한번에 생성 | | **버킷 목록 조회** | 스토리지 버킷 목록 조회 | | **버킷 조회** | 특정 버킷 상세 조회 | | **버킷 생성** | 새 버킷 생성 (공개/비공개, 파일 크기 제한 등) | | **버킷 수정** | 버킷 설정 변경 | | **버킷 삭제** | 버킷 삭제 | | **버킷 비우기** | 버킷 내 모든 파일 삭제 | *** 활용 예시 [#활용-예시] 데이터 조회 및 가공 [#데이터-조회-및-가공] ``` 트리거: 일정 (매일 오전 9시) 액션 1: Supabase - 데이터 조회 ├── 테이블: orders ├── 필터: status eq 'pending' ├── 정렬: created_at DESC ├── 제한: 100 액션 2: 반복 (조회 결과) 액션 3: 행 생성 (주문 데이터모델) ``` 신규 사용자 초대 [#신규-사용자-초대] ``` 트리거: 데이터모델 - 행 생성 (초대 요청) 액션 1: Supabase - 링크 생성 ├── 링크 타입: 초대 ├── 이메일: {{trigger.row.이메일}} └── 리다이렉트 URL: "https://app.example.com/welcome" 액션 2: 이메일 발송 └── 내용: "초대 링크: {{actions.supabase.link}}" ``` 파일 업로드 후 URL 공유 [#파일-업로드-후-url-공유] ``` 트리거: 웹훅 (파일 생성 이벤트) 액션 1: Supabase - 파일 업로드 ├── 버킷: documents ├── 파일 경로: reports/{{trigger.body.fileName}} ├── 파일 데이터: {{trigger.body.fileData}} 액션 2: Supabase - 서명된 URL 생성 ├── 파일 경로: reports/{{trigger.body.fileName}} ├── 만료 시간: 3600 액션 3: 슬랙 메시지 └── 메시지: "새 보고서: {{actions.supabase.signedUrl}}" ``` *** 모범 사례 [#모범-사례] <Callout type="info"> Supabase Realtime 구독은 워크플로우에서 직접 지원하지 않습니다. 실시간 이벤트가 필요한 경우 웹훅 트리거와 Supabase Database Webhook을 조합하여 사용하세요. </Callout> 데이터 보안 [#데이터-보안] * \*\*서비스 역할 키(service\_role)\*\*는 RLS(Row Level Security)를 우회합니다. 필요한 경우에만 사용하세요 * **anon 키**는 RLS 정책에 따라 접근이 제한됩니다 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # 이메일 (/docs/node-reference/actions/notifications/email) > 이메일을 발송합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | --------- | ------------------------ | | **카테고리** | 알림 | | **연동 필요** | SMTP 서버 (인증 정보 등록 필요) | | **출력** | 발송 결과 (메시지 ID, 수락/거부 목록) | 이메일 노드는 **SMTP 프로토콜**(nodemailer 기반)을 통해 이메일을 전송합니다. *** SMTP 설정 [#smtp-설정] 이메일 노드를 사용하려면 먼저 SMTP 인증 정보를 등록해야 합니다. | 항목 | 설명 | 필수 | | ------------------- | --------------------- | :-: | | **호스트 (host)** | SMTP 서버 주소 | ✅ | | **포트 (port)** | SMTP 포트 번호 | ✅ | | **보안 연결 (secure)** | SSL/TLS 사용 여부 | ✅ | | **사용자 (user)** | SMTP 인증 계정 | ✅ | | **비밀번호 (password)** | SMTP 인증 비밀번호 (앱 비밀번호) | ✅ | 주요 SMTP 서버 설정 예시 [#주요-smtp-서버-설정-예시] | 서비스 | 호스트 | 포트 | | ----------- | ------------------ | :-: | | **Gmail** | smtp.gmail.com | 587 | | **Outlook** | smtp.office365.com | 587 | | **네이버** | smtp.naver.com | 587 | <Callout type="info"> Gmail의 경우 2단계 인증을 활성화한 후 **앱 비밀번호**를 생성하여 사용해야 합니다. 일반 비밀번호로는 연결되지 않습니다. </Callout> *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | --------------- | -------------------------- | :-: | | **받는 사람** | 수신자 이메일 주소 (여러 명은 쉼표로 구분) | ✅ | | **제목** | 이메일 제목 | ✅ | | **본문 형식** | HTML 또는 Text 선택 (기본: HTML) | | | **본문** | 이메일 본문 내용 | ✅ | | **발신자 이름** | 발신자 표시 이름 (예: "Taylor 알림") | | | **참조 (CC)** | 참조 수신자 | | | **숨은 참조 (BCC)** | 숨은 참조 수신자 | | | **회신 주소** | 수신자가 답장할 주소 | | 모든 텍스트 옵션은 표현식을 지원합니다. `{{trigger.row.이메일}}` 같은 동적 값을 사용할 수 있습니다. *** 받는 사람 [#받는-사람] 고정 주소 [#고정-주소] ``` sales@company.com ``` 동적 주소 (속성에서) [#동적-주소-속성에서] ``` {{trigger.row.이메일}} {{trigger.row.담당자_이메일}} ``` 여러 수신자 [#여러-수신자] ``` {{trigger.row.이메일}}, admin@company.com ``` *** 본문 작성 [#본문-작성] 텍스트 [#텍스트] ``` 안녕하세요 {{trigger.row.담당자_이름}}님, {{trigger.row.고객명}} 고객의 계약이 완료되었습니다. 계약 금액: {{trigger.row.계약금액}}원 감사합니다. ``` HTML [#html] ```html <h2>계약 완료 안내</h2> <p>안녕하세요 <strong>{{trigger.row.담당자_이름}}</strong>님,</p> <p>{{trigger.row.고객명}} 고객의 계약이 완료되었습니다.</p> <table> <tr> <td>계약 금액</td> <td>{{trigger.row.계약금액}}원</td> </tr> <tr> <td>계약일</td> <td>{{format(trigger.row.계약일, "YYYY-MM-DD")}}</td> </tr> </table> ``` *** 출력 데이터 [#출력-데이터] ```javascript {{actions.email.messageId}} // 발송된 메시지 ID {{actions.email.accepted}} // 수락된 수신자 목록 {{actions.email.rejected}} // 거부된 수신자 목록 {{actions.email.response}} // SMTP 서버 응답 메시지 ``` *** 활용 예시 [#활용-예시] 계약 완료 알림 [#계약-완료-알림] ``` 받는 사람: {{trigger.row.이메일}} 제목: [슈츠] {{trigger.row.고객명}}님, 계약이 완료되었습니다 본문: 안녕하세요 {{trigger.row.담당자_이름}}님, {{trigger.row.고객명}} 고객의 계약이 완료되었습니다. 계약 금액: {{trigger.row.계약금액}}원 감사합니다. ``` 주간 리포트 [#주간-리포트] ``` 받는 사람: team@company.com 제목: [주간 리포트] {{format(today, "MM월 W주")}} 본문: 이번 주 요약: - 신규 계약: {{actions.query.newCount}}건 - 총 매출: {{actions.query.totalRevenue}}원 - 완료 태스크: {{actions.query.completedTasks}}개 ``` 마감 리마인더 [#마감-리마인더] ``` 받는 사람: {{trigger.row.담당자_이메일}} 제목: ⚠️ 마감 D-1: {{trigger.row.제목}} 본문: {{trigger.row.담당자_이름}}님, "{{trigger.row.제목}}" 태스크의 마감이 내일입니다. 마감일: {{format(trigger.row.마감일, "YYYY-MM-DD")}} 확인 부탁드립니다. ``` *** 모범 사례 [#모범-사례] <Callout type="warn"> **스팸 방지**: 발송 빈도와 내용에 주의하세요. 과도한 이메일은 스팸으로 분류될 수 있습니다. </Callout> 제목 작성 [#제목-작성] * 명확하고 구체적인 제목 * 브랜드명을 앞에 포함 `[슈츠]` * 이모지는 절제하여 사용 발신자 설정 [#발신자-설정] 신뢰할 수 있는 발신자 이름과 주소를 사용하세요. ``` 발신자: 슈츠 <noreply@suits.work> ``` 수신 거부 링크 [#수신-거부-링크] 마케팅 이메일에는 수신 거부 링크를 포함하세요. --- # 슬랙 메시지 (/docs/node-reference/actions/notifications/slack) > 슬랙 채널이나 DM으로 메시지를 발송합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | --------- | -------------- | | **카테고리** | 알림 | | **연동 필요** | Slack OAuth 연결 | | **출력** | 메시지 전송 결과 | *** 리소스 [#리소스] | 리소스 | 작업 | | ---------- | ------------------------------ | | **메시지** | 전송, 수정, 삭제, 조회, 스레드 답글 | | **채널** | 목록, 정보, 생성, 아카이브, 멤버 초대 | | **사용자** | 정보 조회, 목록, 프로필 조회/업데이트, 온라인 상태 | | **사용자 그룹** | 목록, 생성, 업데이트, 활성화/비활성화 | | **파일** | 업로드, 목록 | | **리액션** | 추가, 제거 | | **스타** | 목록, 추가, 제거 | *** 메시지 설정 옵션 [#메시지-설정-옵션] | 옵션 | 설명 | 필수 | | ---------------- | ------------------------------------- | :-: | | **채널** | 메시지를 보낼 채널 (목록 선택, ID, 이름, URL 입력 가능) | ✅ | | **메시지 내용** | 본문 텍스트 (마크다운 및 변수 사용 가능) | ✅ | | **Block Kit 사용** | Block Kit JSON으로 리치 메시지 전송 | | | **봇 이름** | 메시지 발신자 이름 (선택) | | | **아이콘 이모지** | 메시지 아이콘 (선택) | | | **실행 모드** | 각 아이템마다 전송 또는 전체 데이터로 1회 전송 | | *** 대상 지정 [#대상-지정] 채널 [#채널] ``` #영업팀 #general #project-alpha ``` DM (Direct Message) [#dm-direct-message] ``` @김철수 @user@example.com ``` 동적 지정 [#동적-지정] ``` {{trigger.row.담당자_슬랙ID}} ``` *** 메시지 작성 [#메시지-작성] 기본 텍스트 [#기본-텍스트] ``` 🎉 새 고객이 등록되었습니다! • 고객명: {{trigger.row.고객명}} • 계약 금액: {{trigger.row.계약금액}} • 담당자: {{trigger.row.담당자}} ``` 멘션 사용 [#멘션-사용] | 멘션 | 설명 | | ---------- | ---------- | | `@channel` | 채널 전체 알림 | | `@here` | 온라인 멤버만 알림 | | `@사용자` | 특정 사용자 멘션 | ``` @channel 긴급 공지! 새로운 대형 계약이 체결되었습니다. 🎊 ``` *** 리치 메시지 (블록) [#리치-메시지-블록] 버튼, 섹션 등을 포함한 **리치 메시지**를 구성할 수 있습니다. 버튼 추가 [#버튼-추가] ```json { "type": "actions", "elements": [ { "type": "button", "text": "상세 보기", "url": "{{trigger.row.url}}" } ] } ``` 섹션 구분 [#섹션-구분] ```json { "type": "section", "text": "📊 **매출 리포트**\n오늘 매출: {{trigger.row.매출}}원" } ``` *** 출력 데이터 [#출력-데이터] ```javascript {{actions.slack.messageId}} // 전송된 메시지 ID {{actions.slack.channel}} // 전송된 채널 {{actions.slack.timestamp}} // 전송 시각 ``` *** 활용 예시 [#활용-예시] 신규 고객 알림 [#신규-고객-알림] ``` 채널: #영업팀 메시지: 🎉 새 고객이 등록되었습니다! • 고객명: {{trigger.row.고객명}} • 계약 금액: {{format(trigger.row.계약금액, "number")}}원 • 담당자: {{trigger.row.담당자}} [고객 상세 보기]({{trigger.row.url}}) ``` 일일 리포트 [#일일-리포트] ``` 채널: #daily-report 메시지: 📊 {{format(today, "MM/DD")}} 일일 리포트 • 신규 문의: {{actions.query.count}}건 • 처리 완료: {{actions.query.completedCount}}건 • 미처리: {{actions.query.pendingCount}}건 ``` 에러 알림 [#에러-알림] ``` 채널: #alerts 메시지: 🚨 워크플로우 에러 발생 • 워크플로우: {{workflow.name}} • 에러: {{error.message}} • 시각: {{format(now, "YYYY-MM-DD HH:mm")}} @channel 확인 부탁드립니다. ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 채널별로 **알림 빈도**를 조절하세요. 너무 많은 알림은 무시될 수 있습니다. </Callout> 이모지 활용 [#이모지-활용] 메시지 시작에 이모지를 추가하면 **시각적 구분**이 쉬워집니다. ``` ✅ 완료, ⚠️ 경고, 🚨 에러, 📊 리포트, 🎉 축하 ``` 멘션 절제 [#멘션-절제] 긴급하지 않은 알림에는 `@channel`을 피하세요. 스레드 활용 [#스레드-활용] 관련 정보가 많을 때는 스레드로 추가 정보를 보내는 것이 좋습니다. --- # 슈츠 알림 (/docs/node-reference/actions/notifications/taylor-notification) > 슈츠 내 알림을 발송합니다. 개요 [#개요] | 항목 | 내용 | | --------- | ---------- | | **카테고리** | 알림 | | **연동 필요** | 없음 (기본 제공) | | **출력** | 알림 전송 결과 | *** 설정 옵션 [#설정-옵션] | 옵션 | 설명 | 필수 | | ---------- | -------------------------- | :-: | | **수신자 유형** | 특정 사용자, 역할, 모든 사용자 | ✅ | | **사용자 ID** | 알림 받을 사용자 ID (특정 사용자 선택 시) | 조건부 | | **역할** | 알림 받을 역할 (쉼표로 구분, 역할 선택 시) | 조건부 | | **제목** | 알림 제목 | ✅ | | **내용** | 알림 본문 (마크다운 지원) | ✅ | | **링크** | 클릭 시 이동할 경로 | | | **알림 유형** | 정보, 성공, 경고, 에러 | | *** 대상 지정 [#대상-지정] 특정 사용자 [#특정-사용자] ``` {{trigger.row.담당자}} ``` 여러 사용자 [#여러-사용자] ``` {{trigger.row.팀원들}} ``` 워크스페이스 멤버 전체 [#워크스페이스-멤버-전체] ``` @all ``` *** 활용 예시 [#활용-예시] 태스크 배정 [#태스크-배정] ``` 대상: {{trigger.row.담당자}} 제목: 새 태스크가 배정되었습니다 내용: "{{trigger.row.제목}}" 태스크가 배정되었습니다. 링크: {{trigger.row.url}} ``` 승인 요청 [#승인-요청] ``` 대상: {{trigger.row.승인자}} 제목: 승인 요청이 있습니다 내용: {{trigger.row.요청자}}님이 승인을 요청했습니다. 링크: {{trigger.row.url}} ``` 마감 리마인더 [#마감-리마인더] ``` 대상: {{trigger.row.담당자}} 제목: ⚠️ 마감 D-1 내용: "{{trigger.row.제목}}" 마감이 내일입니다. 링크: {{trigger.row.url}} ``` *** 출력 데이터 [#출력-데이터] ```javascript {{actions.notification.id}} // 알림 ID {{actions.notification.sentAt}} // 발송 시각 ``` --- # 29CM (/docs/node-reference/actions/korea-business/29cm) > 29CM 패션/라이프스타일 편집샵 API를 통한 상품, 주문, 배송, 카테고리, 재고, 고객, 통계를 관리합니다. (구현 대기 중) import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ------------------------------------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 29CM OAuth2 인증 (파트너센터에서 ClientId/ClientSecret 발급) | | **지원 리소스** | 상품, 주문, 배송, 카테고리, 재고, 고객, 통계 | <Callout type="warn"> 29CM API는 파트너센터 로그인 후에만 접근 가능하며, API 인증키는 **실제 29CM 입점 파트너**만 발급받을 수 있습니다. 현재 API 문서 접근 제한으로 **구현 대기 중**입니다. </Callout> *** 작업 종류 (예상) [#작업-종류-예상] <Callout type="info"> 아래 작업 목록은 파트너센터 API 스펙에 기반한 예상 구조입니다. 실제 API 문서 확인 후 변경될 수 있습니다. </Callout> 상품 [#상품] | 작업 | 설명 | | --------------- | ----------- | | **상품 목록 조회** | 등록된 상품 목록 | | **상품 상세 조회** | 특정 상품 정보 | | **상품 등록** | 신규 상품 등록 | | **상품 수정** | 기존 상품 정보 수정 | | **상품 진열 상태 변경** | 상품 노출 설정 변경 | | **상품 판매 상태 변경** | 판매중/판매중지 전환 | 주문 [#주문] | 작업 | 설명 | | ------------ | ------------ | | **주문 목록 조회** | 조건에 맞는 주문 목록 | | **주문 상세 조회** | 특정 주문의 상세 정보 | | **주문 상태 변경** | 주문 상태 업데이트 | | **송장 입력** | 택배사/송장번호 등록 | | **주문 취소** | 주문 취소 실행 | | **반품 요청 조회** | 반품 요청 목록 | | **교환 요청 조회** | 교환 요청 목록 | *** 대안적 연동 방법 [#대안적-연동-방법] 공식 연동 솔루션 활용 [#공식-연동-솔루션-활용] 29CM와 연동하려면 다음 승인된 솔루션을 활용할 수 있습니다. | 솔루션 | 설명 | | -------------------- | --------------- | | **플레이오토 (PlayAuto)** | 쇼핑몰 통합 자동화 솔루션 | | **사방넷** | 통합 주문/배송 관리 솔루션 | <Callout type="info"> 29CM는 2021년 무신사에 인수되었으며, 무신사 파트너 스테이지를 통해 통합 관리되고 있습니다. </Callout> *** 참고 자료 [#참고-자료] * [무신사 파트너 스테이지 - 29CM 연동 가이드](https://partner-stage.one.musinsa.com/posts/basic-strategy/81) * [29CM 파트너라운지 - API 연동사 소개](https://29cm-partners.oopy.io/49bc9577-ce50-4b0a-b1e8-14eb9db7685b) * [29CM 파트너센터](https://partner.29cm.co.kr/) --- # 에이블리 (/docs/node-reference/actions/korea-business/ably) > 에이블리 패션 커머스 플랫폼 연동 (공개 API 미제공) import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ---------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 공개 API 미제공 (제휴 솔루션 전용) | | **지원 리소스** | - | <Callout type="warn"> 에이블리는 현재 공식적인 외부 개발자용 API를 제공하지 않습니다. 셀러센터에서 API Token 발급은 가능하지만, **승인된 제휴 솔루션(셀러고, 주머니, 플레이오토 등) 전용**입니다. </Callout> *** 현재 상황 [#현재-상황] * 에이블리 셀러센터(my.a-bly.com)에서 API Token 발급 기능 존재 * API Token은 **입점 타입이 '셀러스'인 경우**만 발급 가능 (에이블리 파트너스 계정은 불가) * 일반 개발자를 위한 공식 REST API 문서, 엔드포인트, 스키마 미공개 * 직접적인 API 호출을 위한 인프라 미제공 *** 제휴 솔루션을 통한 간접 연동 [#제휴-솔루션을-통한-간접-연동] 에이블리와 연동하려면 다음 승인된 제휴 솔루션을 활용해야 합니다. | 솔루션 | 설명 | | --------- | --------------- | | **셀러고** | 온라인 셀러 품절관리 솔루션 | | **주머니** | 통합 주문관리 시스템 | | **키위스냅** | 쇼핑몰 통합 솔루션 | | **플레이오토** | 쇼핑몰 자동화 솔루션 | | **올라** | 상품 등록 솔루션 | *** 대안적 연동 방법 [#대안적-연동-방법] 제휴 솔루션 API 활용 [#제휴-솔루션-api-활용] 승인된 제휴 솔루션의 API를 HTTP Request 노드로 호출하여 간접적으로 에이블리 데이터를 관리할 수 있습니다. B2B API 협의 [#b2b-api-협의] 에이블리와의 직접적인 API 연동이 필요한 경우, 비즈니스 파트너십을 협의할 수 있습니다. * 에이블리 셀러스퀘어: [https://square.a-bly.com/](https://square.a-bly.com/) *** 참고 자료 [#참고-자료] * [에이블리 셀러스퀘어](https://square.a-bly.com/) * [에이블리 공식 사이트](https://www.a-bly.com/) --- # 볼타 (/docs/node-reference/actions/korea-business/bolta) > 전자세금계산서를 발행하고 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | --------- | ---------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 볼타 API 키 + 공동인증서 | | **지원 기능** | 세금계산서 발행/조회 | *** 작업 종류 [#작업-종류] 세금계산서 [#세금계산서] | 작업 | 설명 | | ------- | -------------- | | **정발행** | 공급자 → 공급받는자 발행 | | **역발행** | 역발행 요청 | | **조회** | 발행된 계산서 상세 확인 | 고객 [#고객] | 작업 | 설명 | | --------- | --------- | | **목록 조회** | 등록된 고객 목록 | | **고객 생성** | 새 고객 등록 | | **고객 조회** | 특정 고객 정보 | 인증서 [#인증서] | 작업 | 설명 | | ----------------- | -------------- | | **인증서 목록 조회** | 등록된 인증서 목록 | | **인증서 등록 URL 생성** | 인증서 등록용 URL 생성 | | **인증서 삭제** | 공동인증서 삭제 | *** 설정 옵션 [#설정-옵션] 세금계산서 발행 [#세금계산서-발행] | 옵션 | 설명 | 필수 | | --------- | ------------ | :-: | | **공급자** | 공급자 사업자 정보 | ✅ | | **공급받는자** | 공급받는자 사업자 정보 | ✅ | | **작성일자** | 세금계산서 작성일 | ✅ | | **품목** | 품목 목록 | ✅ | | **비고** | 추가 메모 | | *** 품목 형식 [#품목-형식] ```json [ { "name": "컨설팅 서비스", "unitPrice": 1000000, "quantity": 1, "supplyCost": 1000000, "tax": 100000 }, { "name": "월정액 이용료", "unitPrice": 500000, "quantity": 2, "supplyCost": 1000000, "tax": 100000 } ] ``` *** 출력 데이터 [#출력-데이터] ```javascript {{actions.bolta.invoiceId}} // 발행된 세금계산서 ID {{actions.bolta.ntsConfirmNum}} // 국세청 승인번호 {{actions.bolta.success}} // 성공 여부 ``` *** 활용 예시 [#활용-예시] 월 정기 세금계산서 발행 [#월-정기-세금계산서-발행] ``` 트리거: 매월 1일 (일정) 조건: 청구서 상태 = "발행대기" 액션: 볼타 - 세금계산서 발행 ├── 공급자: │ ├── 사업자번호: {{workspace.사업자번호}} │ ├── 상호: {{workspace.상호}} │ └── 대표자: {{workspace.대표자}} ├── 공급받는자: │ ├── 사업자번호: {{trigger.row.고객사업자번호}} │ ├── 상호: {{trigger.row.고객상호}} │ └── 담당자이메일: {{trigger.row.담당자이메일}} ├── 작성일자: {{today}} └── 품목: {{trigger.row.청구품목}} ``` 주문 확정 시 세금계산서 발행 [#주문-확정-시-세금계산서-발행] ``` 트리거: 주문 상태 = "확정" 조건: 결제방식 = "세금계산서" 액션 1: 볼타 - 세금계산서 발행 ├── 공급받는자: {{trigger.row.사업자정보}} └── 품목: └── name: {{trigger.row.상품명}} unitPrice: {{trigger.row.공급가액}} quantity: 1 supplyCost: {{trigger.row.공급가액}} tax: {{trigger.row.세액}} 액션 2: 행 수정 ├── 세금계산서ID: {{actions.bolta.invoiceId}} └── 세금계산서상태: "발행완료" ``` 발행 결과 알림 [#발행-결과-알림] ``` 트리거: 세금계산서 발행 워크플로우 완료 액션: 슬랙 메시지 └── 메시지: | 📄 세금계산서 발행 완료 • 고객: {{trigger.row.고객상호}} • 금액: {{trigger.row.공급가액 + trigger.row.세액}}원 • 승인번호: {{actions.bolta.ntsConfirmNum}} ``` *** 모범 사례 [#모범-사례] <Callout type="warn"> 세금계산서 발행은 **법적 효력**이 있습니다. 발행 전 정보를 꼼꼼히 확인하세요. </Callout> 테스트 환경 [#테스트-환경] 실제 발행 전 **테스트 환경**에서 충분히 검증하세요. 발행 기한 [#발행-기한] 세금계산서는 **재화/용역 공급일이 속하는 달의 다음 달 10일**까지 발행해야 합니다. 수정 세금계산서 [#수정-세금계산서] 발행 후 수정이 필요하면 **수정 세금계산서**를 발행해야 합니다. --- # 카페24 (/docs/node-reference/actions/korea-business/cafe24) > 카페24 쇼핑몰의 주문, 상품, 고객, 재고, 배송, 카테고리, 쿠폰, 리뷰, 스토어 정보, 브랜드, 공급사, 장바구니를 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | -------------------------------------------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 카페24 OAuth 연결 | | **지원 리소스** | 주문, 상품, 고객, 재고, 배송, 카테고리, 쿠폰, 리뷰, 스토어 정보, 브랜드, 공급사, 장바구니 | <Callout type="info"> 각 리소스별 전용 노드(cafe24-order, cafe24-product 등)도 제공됩니다. 단일 리소스만 사용하는 경우 전용 노드 사용을 권장합니다. </Callout> *** 작업 종류 [#작업-종류] 주문 [#주문] | 작업 | 설명 | | ------------ | ------------ | | **주문 목록 조회** | 조건에 맞는 주문 목록 | | **주문 상세 조회** | 특정 주문의 상세 정보 | | **주문 수 조회** | 조건에 맞는 주문 건수 | | **주문 품목 조회** | 특정 주문의 품목 정보 | | **주문 상태 변경** | 주문 상태 업데이트 | | **송장 입력** | 택배사/송장번호 등록 | | **송장 수정** | 등록된 송장 정보 수정 | | **송장 삭제** | 등록된 송장 삭제 | | **주문 취소** | 주문 취소 실행 | | **반품 요청** | 반품 요청 생성 | | **교환 요청** | 교환 요청 생성 | | **반품 요청 조회** | 반품 요청 목록 | | **교환 요청 조회** | 교환 요청 목록 | | **수령인 조회** | 주문 수령인 정보 | | **수령인 수정** | 주문 수령인 정보 수정 | | **메모 조회** | 주문 메모 조회 | | **메모 등록** | 주문 메모 등록 | 상품 [#상품] | 작업 | 설명 | | ---------------- | ------------------- | | **상품 목록 조회** | 상품 목록 | | **상품 상세 조회** | 특정 상품 정보 | | **상품 수 조회** | 등록된 상품 건수 | | **상품 등록** | 신규 상품 등록 | | **상품 수정** | 기존 상품 정보 수정 | | **상품 삭제** | 상품 삭제 | | **상품 진열 상태 변경** | 상품 진열/미진열 설정 | | **상품 판매 상태 변경** | 판매/미판매 설정 | | **상품 옵션(품목) 조회** | 상품의 옵션(variants) 조회 | 고객 [#고객] | 작업 | 설명 | | ------------- | ---------- | | **고객 목록 조회** | 회원 목록 | | **고객 상세 조회** | 회원 정보 | | **고객 검색** | 조건별 고객 검색 | | **고객 수 조회** | 등록된 고객 건수 | | **고객 정보 수정** | 고객 정보 업데이트 | | **적립금 지급** | 적립금 지급/차감 | | **포인트 지급** | 포인트 지급/차감 | | **적립금 내역 조회** | 적립금 변동 내역 | | **포인트 내역 조회** | 포인트 변동 내역 | 재고 [#재고] | 작업 | 설명 | | --------- | -------- | | **재고 조회** | 품목별 재고 | | **재고 수정** | 재고 수량 변경 | 배송 [#배송] | 작업 | 설명 | | ------------- | ------------- | | **배송 목록 조회** | 배송 상태 확인 | | **배송 추적** | 택배 추적 정보 | | **배송사 목록 조회** | 사용 가능한 배송사 목록 | 카테고리 [#카테고리] | 작업 | 설명 | | ----------------- | -------------- | | **카테고리 목록 조회** | 카테고리 목록 | | **카테고리 상세 조회** | 특정 카테고리 정보 | | **카테고리 상품 목록 조회** | 특정 카테고리의 상품 목록 | | **카테고리 상품 수 조회** | 특정 카테고리의 상품 건수 | | **카테고리 수 조회** | 등록된 카테고리 건수 | 쿠폰 [#쿠폰] | 작업 | 설명 | | --------------- | ---------- | | **쿠폰 목록 조회** | 쿠폰 목록 | | **쿠폰 상세 조회** | 특정 쿠폰 정보 | | **쿠폰 발급** | 고객에게 쿠폰 발급 | | **쿠폰 발급 목록 조회** | 발급된 쿠폰 내역 | | **쿠폰 수 조회** | 등록된 쿠폰 건수 | 리뷰 [#리뷰] | 작업 | 설명 | | ------------- | ------------ | | **리뷰 목록 조회** | 리뷰 목록 | | **리뷰 상세 조회** | 특정 리뷰 정보 | | **상품별 리뷰 조회** | 특정 상품의 리뷰 목록 | | **리뷰 답변 작성** | 리뷰에 대한 답변 등록 | 스토어 정보 [#스토어-정보] | 작업 | 설명 | | ------------- | --------- | | **스토어 정보 조회** | 스토어 기본 정보 | | **매출 통계 조회** | 스토어 매출 통계 | 브랜드 [#브랜드] | 작업 | 설명 | | ------------- | ---------- | | **브랜드 목록 조회** | 등록된 브랜드 목록 | | **브랜드 상세 조회** | 특정 브랜드 정보 | | **브랜드 수 조회** | 등록된 브랜드 건수 | 공급사 [#공급사] | 작업 | 설명 | | ------------- | ---------- | | **공급사 목록 조회** | 등록된 공급사 목록 | | **공급사 상세 조회** | 특정 공급사 정보 | | **공급사 수 조회** | 등록된 공급사 건수 | 장바구니 [#장바구니] | 작업 | 설명 | | --------------- | -------------------------------------------- | | **장바구니 목록 조회** | 전체 장바구니 목록 | | **상품별 장바구니 조회** | 특정 상품의 장바구니 데이터 | | **장바구니 설정 조회** | 장바구니 설정 정보 (위시리스트, 바로구매, 보관기간 등) | | **장바구니 설정 수정** | 장바구니 설정 변경 (위시리스트 표시, 바로구매 허용, 아이콘, 할인 표시 등) | *** 택배사 코드 [#택배사-코드] | 코드 | 택배사 | | ------ | ------ | | `0001` | CJ대한통운 | | `0002` | 우체국택배 | | `0003` | 한진택배 | | `0004` | 로젠택배 | | `0005` | 롯데택배 | | `0006` | 대신택배 | | `0008` | 일양로지스 | | `0010` | 경동택배 | *** 설정 옵션 [#설정-옵션] 송장 입력 [#송장-입력] | 옵션 | 설명 | 필수 | | --------- | ---------- | :-: | | **몰 ID** | 카페24 몰 아이디 | ✅ | | **주문 번호** | 주문 번호 | ✅ | | **택배사** | 택배사 코드 | ✅ | | **송장번호** | 운송장 번호 | ✅ | *** 출력 데이터 [#출력-데이터] ```javascript // 주문 조회 {{actions.cafe24.orders}} // 주문 목록 {{actions.cafe24.orders[0].order_id}} {{actions.cafe24.orders[0].buyer_name}} // 송장 입력 {{actions.cafe24.success}} // 성공 여부 {{actions.cafe24.tracking_no}} // 등록된 송장번호 ``` *** 활용 예시 [#활용-예시] 송장 자동 입력 [#송장-자동-입력] ``` 트리거: 물류 시스템 웹훅 (송장 생성) 액션: 카페24 - 송장 입력 ├── 몰 ID: "yourmall" ├── 주문 번호: {{trigger.body.orderNo}} ├── 택배사: "0001" └── 송장번호: {{trigger.body.invoiceNo}} ``` 재고 부족 알림 [#재고-부족-알림] ``` 트리거: 일정 (매일 오전 9시) 액션 1: 카페24 - 재고 조회 (재고 < 10) 액션 2: 반복 ({{actions.cafe24.products}}) 액션 3: 슬랙 메시지 └── 메시지: "재고 부족: {{loop.current.product_name}} ({{loop.current.stock}}개)" ``` VIP 고객 포인트 지급 [#vip-고객-포인트-지급] ``` 트리거: 주문 금액 >= 100만원 액션: 카페24 - 포인트 지급 ├── 고객 ID: {{trigger.row.customer_id}} ├── 포인트: 10000 └── 사유: "VIP 구매 감사 포인트" ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 카페24 API는 **요청 제한**이 있습니다. 대량 처리 시 지연을 두고 호출하세요. </Callout> 주문 상태 흐름 [#주문-상태-흐름] ``` 입금대기 → 결제완료 → 상품준비중 → 배송중 → 배송완료 ``` 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # 쿠팡 로켓그로스 (/docs/node-reference/actions/korea-business/coupang-rocketgrowth) > 쿠팡 로켓그로스 API를 통한 상품, 주문, 송장/배송, 취소/교환, 재고, 정산, 입고, 반품, 매출 리포트를 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | -------------------------------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 쿠팡 로켓그로스 API 인증 (Wing 플랫폼에서 API Key 발급) | | **지원 리소스** | 상품, 주문, 송장/배송, 취소/교환, 재고, 정산, 입고, 반품, 매출 리포트 | *** 작업 종류 [#작업-종류] 상품 [#상품] | 작업 | 설명 | | ------------ | ------------------- | | **상품 목록 조회** | 등록된 상품 목록 조회 | | **상품 상세 조회** | 특정 상품의 상세 정보 | | **상품 등록** | 신규 상품 등록 | | **상품 수정** | 기존 상품 정보 수정 | | **상품 삭제** | 상품 삭제 | | **상품 상태 변경** | 판매중/품절/판매중지 상태 변경 | | **상품 옵션 조회** | 상품의 옵션(variants) 조회 | 주문 [#주문] | 작업 | 설명 | | ------------ | ------------ | | **주문 목록 조회** | 조건에 맞는 주문 목록 | | **주문 상세 조회** | 특정 주문의 상세 정보 | | **주문 수 조회** | 조건에 맞는 주문 건수 | | **주문 품목 조회** | 특정 주문의 품목 정보 | 송장/배송 [#송장배송] | 작업 | 설명 | | ------------------ | ------------------- | | **송장 업로드 (발송처리)** | 택배사/송장번호 등록 및 발송 처리 | | **송장 수정** | 등록된 송장 정보 수정 | | **배송 상태 변경 이력 조회** | 배송 상태 변경 이력 확인 | | **배송완료 처리** | 배송 완료 처리 | 취소/교환 [#취소교환] | 작업 | 설명 | | ------------------ | ------------ | | **반품/취소 요청 목록 조회** | 반품/취소 요청 목록 | | **주문 취소 처리** | 주문 취소 실행 | | **교환 요청 목록 조회** | 교환 요청 목록 | | **교환 거부** | 교환 요청 거부 | | **교환 송장 업로드** | 교환 재배송 송장 등록 | 재고 [#재고] | 작업 | 설명 | | ------------------- | --------------------- | | **재고 목록 조회** | 재고 목록 | | **재고 상세 조회** | 특정 상품의 재고 정보 | | **상품별 재고/가격/상태 조회** | 아이템 단위의 재고, 가격, 상태 조회 | 정산 [#정산] | 작업 | 설명 | | ------------ | ------------ | | **정산 목록 조회** | 정산 내역 목록 | | **정산 상세 조회** | 특정 정산 정보 | | **정산 상세 내역** | 정산 항목별 상세 내역 | 입고 [#입고] | 작업 | 설명 | | ------------ | -------- | | **입고 목록 조회** | 입고 내역 목록 | | **입고 상세 조회** | 특정 입고 정보 | | **입고 요청 생성** | 신규 입고 요청 | | **입고 취소** | 입고 요청 취소 | 반품 [#반품] | 작업 | 설명 | | ------------ | -------- | | **반품 목록 조회** | 반품 내역 목록 | | **반품 상세 조회** | 특정 반품 정보 | | **반품 승인** | 반품 요청 승인 | | **반품 거부** | 반품 요청 거부 | 매출 리포트 [#매출-리포트] | 작업 | 설명 | | ------------- | ----------- | | **매출 내역 조회** | 기간별 매출 내역 | | **상품별 판매 통계** | 상품 단위 판매 통계 | *** 택배사 코드 [#택배사-코드] | 코드 | 택배사 | | ---------- | -------- | | `CJGLS` | CJ대한통운 | | `HANJIN` | 한진택배 | | `LOTTE` | 롯데택배 | | `LOGEN` | 로젠택배 | | `EPOST` | 우체국택배 | | `KDEXP` | 경동택배 | | `DAESIN` | 대신택배 | | `ILYANG` | 일양로지스 | | `KUNYOUNG` | 건영택배 | | `CHUNIL` | 천일택배 | | `HDEXP` | 합동택배 | | `CVSNET` | CVS편의점택배 | | `GTX` | GTX로지스 | | `ETC` | 기타 | *** 주문 상태 [#주문-상태] | 상태 | 설명 | | ---------------- | ---- | | `ACCEPT` | 접수 | | `INSTRUCT` | 출고지시 | | `DEPARTURE` | 출고 | | `DELIVERING` | 배송중 | | `FINAL_DELIVERY` | 배송완료 | | `CANCELED` | 취소 | *** 출력 데이터 [#출력-데이터] ```javascript // 상품 조회 {{actions.coupangRocketGrowth.products}} {{actions.coupangRocketGrowth.products[0].productId}} // 주문 조회 {{actions.coupangRocketGrowth.orders}} {{actions.coupangRocketGrowth.orders[0].orderId}} // 송장 업로드 {{actions.coupangRocketGrowth.success}} ``` *** 활용 예시 [#활용-예시] 송장 자동 업로드 [#송장-자동-업로드] ``` 트리거: 물류 시스템 웹훅 (송장 생성) 액션: 쿠팡 로켓그로스 - 송장 업로드 ├── 배송박스 ID: {{trigger.body.shipmentBoxId}} ├── 주문 ID: {{trigger.body.orderId}} ├── 택배사: "CJGLS" └── 송장번호: {{trigger.body.invoiceNumber}} ``` 재고 부족 알림 [#재고-부족-알림] ``` 트리거: 일정 (매시간) 액션 1: 쿠팡 로켓그로스 - 재고 목록 조회 액션 2: 필터 (재고 < 10) 액션 3: 슬랙 메시지 └── 메시지: "쿠팡 로켓그로스 재고 부족: {{loop.current.productName}}" ``` 정산 데이터 수집 [#정산-데이터-수집] ``` 트리거: 일정 (매일 오전 10시) 액션 1: 쿠팡 로켓그로스 - 정산 목록 조회 ├── 시작일: {{$today.minus(1, 'day')}} └── 종료일: {{$today}} 액션 2: 데이터모델 행 추가 └── 정산 데이터 저장 ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 쿠팡 로켓그로스 API는 **페이지당 최대 500건**까지 조회 가능합니다. 대량 데이터 처리 시 페이지네이션을 활용하세요. </Callout> 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. 특히 송장 업로드 실패는 배송 지연으로 이어질 수 있으므로 즉시 처리가 필요합니다. --- # 다우오피스 (/docs/node-reference/actions/korea-business/daouoffice) > 다우오피스 그룹웨어 API를 통한 조직도, 근태, 전자결재, 알림, 일정, 주소록을 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ----------------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 다우오피스 API 키 | | **지원 리소스** | 조직도, 근태 관리, 전자결재, 알림, 일정, 주소록 | *** 작업 종류 [#작업-종류] 조직도 [#조직도] | 작업 | 설명 | | ------------- | --------------------------- | | **조직 구조 조회** | 전체 조직 구조 트리 조회 | | **부서 목록 조회** | 부서 코드로 하위 부서 목록 조회 | | **사용자 목록 조회** | 전체 사용자 또는 특정 사용자 조회 | | **사용자 검색** | 이름 또는 이메일로 사용자 검색 | | **부서 구성원 조회** | 특정 부서의 구성원 목록 (하위 부서 포함 옵션) | 근태 관리 [#근태-관리] | 작업 | 설명 | | ------------ | ----------------------- | | **근태 기록 조회** | 출근/퇴근/외출/복귀 기록 조회 | | **휴가 정보 조회** | 연차/반차/병가/경조사 등 휴가 정보 조회 | | **근무 통계 조회** | 근무 시간 통계 조회 | | **근태 현황 조회** | 현재 근태 상태 조회 | 전자결재 [#전자결재] | 작업 | 설명 | | ------------ | ----------------- | | **문서 목록 조회** | 결재 상태별 문서 목록 조회 | | **문서 상세 조회** | 문서 번호로 상세 조회 | | **문서 작성** | 양식을 사용하여 결재 문서 생성 | | **결재 승인** | 결재 문서 승인 처리 | | **결재 반려** | 결재 문서 반려 처리 | | **결재 상태 조회** | 결재 진행 상태 확인 | 알림 [#알림] | 작업 | 설명 | | ------------ | --------------- | | **개인 알림 발송** | 특정 사용자에게 알림 발송 | | **그룹 알림 발송** | 부서/그룹 단위로 알림 발송 | 일정 [#일정] | 작업 | 설명 | | ------------ | -------------------------------- | | **일정 목록 조회** | 기간별 일정 목록 조회 | | **일정 상세 조회** | 일정 ID로 상세 조회 | | **일정 등록** | 새 일정 생성 (제목, 내용, 시작/종료 일시, 장소 등) | | **일정 수정** | 기존 일정 수정 | | **일정 삭제** | 일정 삭제 | 주소록 [#주소록] | 작업 | 설명 | | ------------- | ------------- | | **주소록 목록 조회** | 그룹별 주소록 조회 | | **주소록 상세 조회** | 특정 연락처 상세 조회 | | **주소록 검색** | 이름 또는 연락처로 검색 | | **주소록 그룹 조회** | 주소록 그룹 목록 조회 | *** 활용 예시 [#활용-예시] 결재 자동 알림 [#결재-자동-알림] ``` 트리거: 데이터모델 - 행 생성 (결재 요청) 액션 1: 다우오피스 - 문서 작성 ├── 양식 ID: "FORM-001" ├── 문서 제목: {{trigger.row.제목}} ├── 문서 내용: {{trigger.row.내용}} └── 결재 라인: {{trigger.row.결재자목록}} 액션 2: 다우오피스 - 개인 알림 발송 ├── 수신자: {{trigger.row.첫번째결재자}} └── 알림 내용: "새 결재 문서가 접수되었습니다" ``` 출퇴근 시간 관리 [#출퇴근-시간-관리] ``` 트리거: 일정 (매일 오전 10시) 액션 1: 다우오피스 - 근태 현황 조회 액션 2: 반복 (미출근 인원) 액션 3: 슬랙 메시지 └── 메시지: "미출근: {{loop.current.사용자명}}" ``` 휴가 현황 자동 집계 [#휴가-현황-자동-집계] ``` 트리거: 일정 (매주 월요일 오전 9시) 액션 1: 다우오피스 - 휴가 정보 조회 (금주) 액션 2: 행 생성 (휴가 현황 데이터모델) ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 다우오피스 API 키는 관리자 페이지 > 시스템 연동 > API 인증에서 발급받으세요. </Callout> 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # 이카운트ERP (/docs/node-reference/actions/korea-business/ecount) > 이카운트 ERP API를 통한 품목, 거래처, 수주/발주, 매출, 매입, 재고, 회계를 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ------------------------------ | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 이카운트 ERP API 인증 (API 키) | | **지원 리소스** | 품목, 거래처, 수주/발주, 매출, 매입, 재고, 회계 | *** 작업 종류 [#작업-종류] 품목 [#품목] | 작업 | 설명 | | ------------ | --------------------------- | | **품목 목록 조회** | 품목 구분, 검색어로 필터링하여 목록 조회 | | **품목 상세 조회** | 품목 코드로 상세 정보 조회 | | **품목 등록** | 새 품목 등록 (품목명, 규격, 단위, 단가 등) | | **품목 수정** | 기존 품목 정보 수정 | | **품목 삭제** | 품목 삭제 | | **품목 재고 조회** | 특정 품목의 현재 재고 조회 | 거래처 [#거래처] | 작업 | 설명 | | --------------- | ----------------------------------- | | **거래처 목록 조회** | 거래처 구분(매출처/매입처)으로 필터링하여 목록 조회 | | **거래처 상세 조회** | 거래처 코드로 상세 정보 조회 | | **거래처 등록** | 새 거래처 등록 (거래처명, 사업자번호, 대표자명, 연락처 등) | | **거래처 수정** | 기존 거래처 정보 수정 | | **거래처 삭제** | 거래처 삭제 | | **거래처 거래내역 조회** | 특정 거래처의 거래 내역 조회 | 수주/발주 [#수주발주] | 작업 | 설명 | | ------------ | ------------------- | | **발주 목록 조회** | 발주 목록 조회 (상태 필터 가능) | | **수주 목록 조회** | 수주 목록 조회 (상태 필터 가능) | | **상세 조회** | 수주/발주 번호로 상세 조회 | | **발주 등록** | 새 발주 등록 | | **수주 등록** | 새 수주 등록 | | **수정** | 수주/발주 수정 | | **삭제** | 수주/발주 삭제 | | **상태 변경** | 진행중, 완료, 취소 상태 변경 | 매출 [#매출] | 작업 | 설명 | | -------------- | ---------------------------- | | **매출전표 목록 조회** | 매출전표 목록 조회 | | **매출전표 상세 조회** | 전표 번호로 상세 조회 | | **매출전표 등록** | 새 매출전표 등록 (거래처, 공급가액, 부가세 등) | | **매출전표 수정** | 매출전표 수정 | | **매출전표 삭제** | 매출전표 삭제 | | **매출전표 승인** | 매출전표 승인 처리 | 매입 [#매입] | 작업 | 설명 | | -------------- | ---------------------------- | | **매입전표 목록 조회** | 매입전표 목록 조회 | | **매입전표 상세 조회** | 전표 번호로 상세 조회 | | **매입전표 등록** | 새 매입전표 등록 (거래처, 공급가액, 부가세 등) | | **매입전표 수정** | 매입전표 수정 | | **매입전표 삭제** | 매입전표 삭제 | | **매입전표 승인** | 매입전표 승인 처리 | 재고 [#재고] | 작업 | 설명 | | ------------- | ---------------- | | **현재고 조회** | 품목별 현재 재고 조회 | | **입출고 내역 조회** | 품목별 입출고 이력 조회 | | **재고 조정** | 재고 수량 조정 (사유 입력) | | **창고별 재고 조회** | 창고 코드별 재고 현황 조회 | 회계 [#회계] | 작업 | 설명 | | -------------- | -------------- | | **계정과목 목록 조회** | 계정과목 목록 조회 | | **계정과목 상세 조회** | 계정과목 코드로 상세 조회 | | **전표 목록 조회** | 회계 전표 목록 조회 | | **전표 상세 조회** | 전표 번호로 상세 조회 | | **잔액 조회** | 계정과목별 잔액 조회 | *** 공통 필터 옵션 [#공통-필터-옵션] | 옵션 | 설명 | | ------------- | ------- | | **시작일** | 조회 시작일 | | **종료일** | 조회 종료일 | | **페이지** | 페이지 번호 | | **페이지당 항목 수** | 최대 500건 | *** 활용 예시 [#활용-예시] 발주서 자동 생성 [#발주서-자동-생성] ``` 트리거: 데이터모델 - 행 생성 (발주 요청) 액션: 이카운트ERP - 발주 등록 ├── 거래처 코드: {{trigger.row.거래처코드}} ├── 품목 코드: {{trigger.row.품목코드}} ├── 수량: {{trigger.row.수량}} ├── 단가: {{trigger.row.단가}} └── 납기일: {{trigger.row.납기일}} ``` 재고 부족 시 발주 알림 [#재고-부족-시-발주-알림] ``` 트리거: 일정 (매일 오전 8시) 액션 1: 이카운트ERP - 현재고 조회 액션 2: 반복 (재고 < 안전재고인 품목) 액션 3: 슬랙 메시지 └── 메시지: "재고 부족: {{loop.current.품목명}} (현재 {{loop.current.재고}}개)" ``` 매출/매입 자동 집계 [#매출매입-자동-집계] ``` 트리거: 일정 (매월 1일 오전 9시) 액션 1: 이카운트ERP - 매출전표 목록 조회 (전월) 액션 2: 이카운트ERP - 매입전표 목록 조회 (전월) 액션 3: 행 생성 (월별 매출/매입 요약) ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 이카운트 ERP API는 API 키 발급이 필요합니다. 이카운트 관리자 > 사용자정의 > 정보 > API 인증키 발급에서 키를 발급받으세요. </Callout> 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # 이지어드민 (/docs/node-reference/actions/korea-business/ezadmin) > 이지어드민 쇼핑몰 통합관리 API를 통한 주문, 상품, 재고, 공급사, 이력을 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 이지어드민 업체보안코드 | | **지원 리소스** | 주문, 상품, 재고, 공급사, 이력 | *** 작업 종류 [#작업-종류] 주문 [#주문] | 작업 | 설명 | | ------------ | ---------------------------- | | **주문 조회** | 주문 번호로 상세 조회 | | **주문 목록 조회** | 주문 상태, 판매처, 기간으로 필터링하여 목록 조회 | | **주문 취소** | 주문 취소 처리 (사유 입력) | | **배송 정보 입력** | 택배사 코드와 송장번호 등록 | | **주문 보류** | 주문 보류 처리 | | **주문 보류 해제** | 보류 해제 처리 | 상품 [#상품] | 작업 | 설명 | | --------------- | --------------------------- | | **상품 조회** | 상품 코드로 상세 조회 | | **상품 목록 조회** | 공급사, 카테고리, 검색어로 필터링하여 목록 조회 | | **상품 등록** | 새 상품 등록 (상품명, 가격, 설명 등) | | **상품 수정** | 기존 상품 정보 수정 | | **상품 삭제** | 상품 삭제 | | **상품 변경 이력 조회** | 특정 상품의 변경 이력 확인 | 재고 [#재고] | 작업 | 설명 | | --------------- | ---------------------------- | | **재고 조회** | 상품별 재고 조회 | | **재고 목록 조회** | 전체 재고 현황 조회 | | **재고 조정** | 재고 수량 변경 (사유 입력, 안전재고 설정 가능) | | **재고 이력 조회** | 재고 변동 이력 조회 | | **다중 위치 재고 조회** | 여러 위치의 재고 현황 한번에 조회 | | **재고 알림 조회** | 안전재고 미달 등 재고 알림 조회 | 공급사 [#공급사] | 작업 | 설명 | | ------------- | ----------------------------- | | **공급사 조회** | 공급사 코드로 상세 조회 | | **공급사 목록 조회** | 공급사 목록 조회 | | **공급사 등록** | 새 공급사 등록 (공급사명, 연락처, 이메일, 주소) | | **공급사 수정** | 기존 공급사 정보 수정 | 이력 [#이력] | 작업 | 설명 | | ------------ | --------------- | | **CS 이력 조회** | 고객 서비스 관련 이력 조회 | | **재고 이력 조회** | 재고 변동 이력 조회 | | **상품 이력 조회** | 상품 변경 이력 조회 | | **반품 이력 조회** | 반품 처리 이력 조회 | | **매칭 정보 조회** | 매칭 정보 조회 | *** 택배사 코드 [#택배사-코드] | 코드 | 택배사 | | -------- | ------ | | `CJ` | CJ대한통운 | | `EPOST` | 우체국택배 | | `HANJIN` | 한진택배 | | `LOGEN` | 로젠택배 | | `LOTTE` | 롯데택배 | | `KDEXP` | 경동택배 | | `DAESIN` | 대신택배 | *** 활용 예시 [#활용-예시] 송장 자동 입력 [#송장-자동-입력] ``` 트리거: 웹훅 (물류 시스템 송장 생성) 액션: 이지어드민 - 배송 정보 입력 ├── 주문 번호: {{trigger.body.orderNo}} ├── 택배사 코드: CJ └── 송장 번호: {{trigger.body.trackingNo}} ``` 재고 부족 알림 [#재고-부족-알림] ``` 트리거: 일정 (매일 오전 9시) 액션 1: 이지어드민 - 재고 알림 조회 액션 2: 반복 (알림 목록) 액션 3: 슬랙 메시지 └── 메시지: "재고 부족: {{loop.current.상품명}} ({{loop.current.재고}}개)" ``` 반품 처리 자동화 [#반품-처리-자동화] ``` 트리거: 데이터모델 - 행 생성 (반품 요청) 액션 1: 이지어드민 - 주문 조회 ├── 주문 번호: {{trigger.row.주문번호}} 액션 2: 이지어드민 - 재고 조정 ├── 상품 코드: {{actions.ezadmin.productCode}} ├── 재고 수량: +{{trigger.row.수량}} └── 조정 사유: "반품 입고" ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 이지어드민 API 업체보안코드는 고객센터(1668-2343)에 문의하여 발급받으세요. </Callout> 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # 헤메코랩 (/docs/node-reference/actions/korea-business/hemekolab) > 헤메코랩 뷰티 커머스 플랫폼 연동 (공개 API 미제공) import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ---------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 공개 API 미제공 | | **지원 리소스** | - | <Callout type="warn"> 헤메코랩은 현재 **공식 API를 제공하지 않습니다**. 셀러 관리를 위한 웹 기반 관리자 사이트(seller.hemekolab.com)는 존재하지만, 프로그래매틱 API 접근 방식은 제공되지 않습니다. </Callout> *** 서비스 정보 [#서비스-정보] | 항목 | 내용 | | ----------- | ---------------------------------------------------------------------- | | **회사명** | 주식회사 헤메코 (HEMEKO Inc.) | | **서비스 유형** | 뷰티 커머스 플랫폼 | | **주요 특징** | 크리에이터 셀러 샵, 무료배송, 리뷰 기반 뷰티 판매 | | **파트너 사이트** | [https://seller.hemekolab.com/home](https://seller.hemekolab.com/home) | *** 현재 상황 [#현재-상황] * 개발자 포털, API 키 발급, 웹훅 등의 기능 없음 * 파트너 관리자 사이트는 수동 관리(입점샵 관리, 주문 관리, 정산 관리) 위주로 구성 * API 문서, 개발자 가이드, 기술 연동 정보 미제공 *** 대안적 연동 방법 [#대안적-연동-방법] 고객 문의를 통한 맞춤 연동 [#고객-문의를-통한-맞춤-연동] 대규모 셀러나 기업 고객의 경우, 헤메코랩 담당자와 직접 협의하여 맞춤 연동이 가능할 수 있습니다. | 채널 | 정보 | | -------- | ------------------------------------------------------------------------------------------- | | **이메일** | [help@hemeko.com](mailto:help@hemeko.com) / [contact@hemeko.com](mailto:contact@hemeko.com) | | **전화** | 1533-0645 | | **카카오톡** | 평일 10:00-17:00 (점심 12:00-13:00) | 수동 데이터 관리 [#수동-데이터-관리] 셀러 관리자 사이트를 통한 수동 관리 또는 엑셀/CSV 내보내기/가져오기 기능을 활용할 수 있습니다. *** 참고 자료 [#참고-자료] * [헤메코랩 공식 사이트](https://www.hemekolab.com/) * [헤메코랩 셀러 관리자](https://seller.hemekolab.com/home) --- # 화해 (/docs/node-reference/actions/korea-business/hwahae) > 화해 뷰티 플랫폼 연동 (공개 API 미제공) import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ---------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 공개 API 미제공 | | **지원 리소스** | - | <Callout type="warn"> 화해(Hwahae)는 현재 **공식 개발자 API를 제공하지 않습니다**. 브랜드 및 기업과의 협업은 직접적인 B2B 파트너십 방식으로 진행됩니다. </Callout> *** 서비스 정보 [#서비스-정보] | 항목 | 내용 | | ---------- | ------------------------- | | **운영사** | 버드뷰 (Birdview) / 나이스그룹 계열 | | **서비스 유형** | 뷰티 정보/리뷰/커머스 플랫폼 | | **주요 기능** | 화장품 정보, 성분 분석, 리뷰, 랭킹, 쇼핑 | | **데이터 규모** | 20만 건 이상의 제품 데이터베이스 | *** 현재 상황 [#현재-상황] * 공식 개발자 API 문서 부재 * 공개 API 엔드포인트 미공개 * 서드파티 개발자를 위한 API 키 발급 시스템 없음 * B2B 파트너십 중심의 비즈니스 모델 운영 B2B 프로그램 [#b2b-프로그램] | 프로그램 | 설명 | | ------------------------------------ | ---------------- | | **BAP (Brand Acceleration Program)** | 브랜드 성장 지원 프로그램 | | **화해 쇼룸 (Hwahae Showroom)** | 글로벌 리테일러와 브랜드 연결 | *** 대안적 연동 방법 [#대안적-연동-방법] B2B 파트너십 문의 [#b2b-파트너십-문의] 뷰티 브랜드나 리테일러의 경우, 화해와 직접 파트너십을 체결하여 데이터 제공을 협의할 수 있습니다. | 채널 | 정보 | | ----------- | -------------------------------------------------------------- | | **화해 쇼룸** | [https://wholesale.hwahae.com/](https://wholesale.hwahae.com/) | | **글로벌 사이트** | [https://www.hwahaeglobal.com/](https://www.hwahaeglobal.com/) | 공공 데이터 활용 [#공공-데이터-활용] 뷰티/화장품 관련 공공 데이터를 대안으로 활용할 수 있습니다. * 식품의약품안전처 화장품 공공데이터 API (data.go.kr) * 한국소비자원 화장품 안전성 정보 *** 참고 자료 [#참고-자료] * [화해 글로벌 사이트](https://www.hwahaeglobal.com/) * [화해 기술 블로그](https://blog.hwahae.co.kr/) * [화해 쇼룸](https://accelerate.hwahae.com/) --- # 아임웹 (/docs/node-reference/actions/korea-business/imweb) > 아임웹 쇼핑몰의 주문, 상품, 회원을 관리합니다. 개요 [#개요] | 항목 | 내용 | | ---------- | ----------------------------------------------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 아임웹 API 키 | | **지원 리소스** | 주문, 품목 주문, 상품, 회원, 회원 등급, 카테고리, 쿠폰, 구매평, 상품 문의, 입력폼, 사이트 정보 | *** 작업 종류 [#작업-종류] 주문 [#주문] | 작업 | 설명 | | ------------ | ----------------------- | | **주문 목록 조회** | 조건에 맞는 주문 목록 (v1/v2 지원) | | **주문 상세 조회** | 특정 주문의 상세 정보 | | **주문 상태 변경** | 입금대기 → 배송완료 등 | | **송장 입력** | 택배사/송장번호 등록 | | **입금 확인 처리** | 입금 확인 | | **취소 처리** | 주문 취소 | | **반품 처리** | 반품 처리 | | **교환 처리** | 교환 처리 | 품목 주문 [#품목-주문] | 작업 | 설명 | | --------------- | -------------------- | | **품목 주문 목록 조회** | 주문 내 품목별 주문 목록 | | **품목 주문 상세 조회** | 품목 주문 상세 정보 | | **품목 주문 상태 변경** | 입금확인/배송준비/발송/배송완료 처리 | | **품목 주문 송장 입력** | 품목별 송장 입력 | | **품목 주문 송장 조회** | 품목별 송장 조회 | 상품 [#상품] | 작업 | 설명 | | ------------ | ---------- | | **상품 목록 조회** | 상품 목록 | | **상품 상세 조회** | 특정 상품 정보 | | **상품 등록** | 새 상품 등록 | | **상품 수정** | 상품 정보 수정 | | **상품 삭제** | 상품 삭제 | | **재고 수정** | 재고 수량 업데이트 | | **상품 옵션 조회** | 상품 옵션 정보 | | **상품 옵션 수정** | 상품 옵션 수정 | 회원 [#회원] | 작업 | 설명 | | ------------ | -------- | | **회원 목록 조회** | 회원 목록 | | **회원 상세 조회** | 회원 정보 | | **회원 등록** | 새 회원 등록 | | **회원 수정** | 회원 정보 수정 | | **포인트 지급** | 포인트 지급 | | **포인트 차감** | 포인트 차감 | 기타 리소스 [#기타-리소스] | 리소스 | 작업 | | ---------- | ------------------------------- | | **회원 등급** | 목록 조회, 상세 조회 | | **카테고리** | 목록 조회, 네이버 카테고리 조회 | | **쿠폰** | 목록 조회, 상세 조회, 발행 정보 조회, 회원에게 발급 | | **구매평** | 목록 조회, 상세 조회, 수정 (관리자 답변) | | **상품 문의** | 목록 조회, 상세 조회, 답변 | | **입력폼** | 목록 조회, 상세 조회, 제출 데이터 조회 | | **사이트 정보** | 사이트 정보 조회, 쇼핑 설정 조회, 배송 정책 조회 | *** 택배사 코드 [#택배사-코드] | 코드 | 택배사 | | -------- | ------ | | `cj` | CJ대한통운 | | `hanjin` | 한진택배 | | `lotte` | 롯데택배 | | `logen` | 로젠택배 | | `epost` | 우체국택배 | *** 출력 데이터 [#출력-데이터] ```javascript // 주문 조회 {{actions.imweb.orders}} {{actions.imweb.orders[0].order_no}} {{actions.imweb.orders[0].orderer_name}} // 송장 입력 {{actions.imweb.success}} ``` *** 활용 예시 [#활용-예시] 송장 입력 [#송장-입력] ``` 트리거: 주문 상태가 "결제완료"로 변경 액션: 아임웹 - 송장 입력 ├── 주문번호: {{trigger.row.주문번호}} ├── 택배사: "cj" └── 송장번호: {{trigger.row.송장번호}} ``` 재고 동기화 [#재고-동기화] ``` 트리거: 재고 데이터모델 - 행 수정 액션: 아임웹 - 재고 수정 ├── 상품 코드: {{trigger.row.product_code}} └── 재고 수량: {{trigger.row.stock}} ``` 구매 후 포인트 지급 [#구매-후-포인트-지급] ``` 트리거: 주문 상태 = "배송완료" 액션: 아임웹 - 포인트 지급 ├── 회원 ID: {{trigger.row.member_id}} ├── 포인트: {{Math.floor(trigger.row.금액 * 0.01)}} └── 사유: "구매 적립" ``` --- # 카카오선물하기 (/docs/node-reference/actions/korea-business/kakao-gift) > 카카오쇼핑 API를 통한 선물하기/톡스토어 상품, 주문, 문의, 카테고리, 브랜드, 선물 발송, 정산을 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | -------------------------------------------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 카카오쇼핑 Open API 액세스 토큰 (카카오 디벨로퍼스 앱 등록 + 판매자센터 API 권한 신청) | | **지원 리소스** | 상품, 주문, 문의, 카테고리, 브랜드, 선물 발송 (for Biz), 정산 | *** 작업 종류 [#작업-종류] 상품 [#상품] | 작업 | 설명 | | ------------- | ----------------- | | **상품 목록 조회** | 등록된 상품 목록 | | **상품 상세 조회** | 특정 상품 정보 | | **상품 등록** | 신규 상품 등록 | | **상품 수정** | 기존 상품 정보 수정 | | **판매 상태 변경** | 판매중/판매중지/품절 상태 변경 | | **상품 이미지 조회** | 상품 이미지 목록 | | **상품 이미지 수정** | 상품 이미지 업데이트 | 주문 [#주문] | 작업 | 설명 | | ------------ | ------------ | | **주문 목록 조회** | 조건에 맞는 주문 목록 | | **주문 상세 조회** | 특정 주문의 상세 정보 | | **주문 상태 변경** | 주문 상태 업데이트 | | **주문 확인 처리** | 주문 접수 확인 | | **송장 입력** | 택배사/송장번호 등록 | | **송장 수정** | 등록된 송장 정보 수정 | 문의 [#문의] | 작업 | 설명 | | ------------ | ------------ | | **문의 목록 조회** | 고객 문의 목록 | | **문의 상세 조회** | 특정 문의 상세 내용 | | **문의 답변 등록** | 문의에 대한 답변 작성 | 카테고리 [#카테고리] | 작업 | 설명 | | -------------- | ----------------- | | **카테고리 목록 조회** | 카테고리 목록 (뎁스 1\~3) | | **카테고리 상세 조회** | 특정 카테고리 정보 | 브랜드 [#브랜드] | 작업 | 설명 | | ------------- | ---------- | | **브랜드 목록 조회** | 등록된 브랜드 목록 | | **브랜드 상세 조회** | 특정 브랜드 정보 | 선물 발송 (for Biz) [#선물-발송-for-biz] | 작업 | 설명 | | ------------- | ------------- | | **선물 보내기** | 수신자에게 선물 발송 | | **발송 내역 조회** | 선물 발송 이력 | | **템플릿 목록 조회** | 사용 가능한 선물 템플릿 | 정산 [#정산] | 작업 | 설명 | | -------------- | ------------------------- | | **주문단위 정산 조회** | 주문 단위의 정산 내역 (기준일/확정일 기준) | *** 택배사 코드 [#택배사-코드] | 코드 | 택배사 | | -------- | -------- | | `CJ` | CJ대한통운 | | `POST` | 우체국택배 | | `HANJIN` | 한진택배 | | `LOGEN` | 로젠택배 | | `LOTTE` | 롯데택배 | | `KD` | 경동택배 | | `DAESIN` | 대신택배 | | `ILYANG` | 일양로지스 | | `CVS` | CVS편의점택배 | | `DHL` | DHL | | `FEDEX` | FedEx | | `UPS` | UPS | *** 주문 상태 [#주문-상태] | 상태 | 설명 | | ------------------- | ----- | | `PAYMENT_COMPLETE` | 결제완료 | | `PREPARING_PRODUCT` | 상품준비중 | | `DELIVERING` | 배송중 | | `DELIVERY_COMPLETE` | 배송완료 | | `PURCHASE_CONFIRM` | 구매확정 | | `CANCEL` | 취소 | | `EXCHANGE` | 교환 | | `RETURN` | 반품 | *** 설정 옵션 [#설정-옵션] 판매자 코드 [#판매자-코드] 모든 작업에 **판매자 코드**가 필수입니다. 카카오쇼핑 판매자센터에서 확인할 수 있습니다. 정산 조회 [#정산-조회] | 옵션 | 설명 | | --------- | -------------------- | | **기간 유형** | 정산 기준일 또는 정산 확정일 기준 | | **채널** | 선물하기(1) 또는 톡스토어(101) | *** 출력 데이터 [#출력-데이터] ```javascript // 상품 조회 {{actions.kakaoGift.products}} {{actions.kakaoGift.products[0].productId}} {{actions.kakaoGift.products[0].productName}} // 주문 조회 {{actions.kakaoGift.orders}} {{actions.kakaoGift.orders[0].orderId}} // 선물 발송 {{actions.kakaoGift.success}} ``` *** 활용 예시 [#활용-예시] 선물 자동 발송 [#선물-자동-발송] ``` 트리거: 데이터모델 행 변경 (VIP 고객 등록) 액션: 카카오선물하기 - 선물 보내기 ├── 판매자 코드: "SELLER123" ├── 템플릿 ID: "TMPL001" ├── 수신자 전화번호: {{trigger.row.phone}} └── 메시지: "VIP 회원 가입을 축하합니다!" ``` 문의 자동 답변 알림 [#문의-자동-답변-알림] ``` 트리거: 일정 (매 30분) 액션 1: 카카오선물하기 - 문의 목록 조회 (미답변) 액션 2: 반복 ({{actions.kakaoGift.inquiries}}) 액션 3: 슬랙 메시지 └── 메시지: "미답변 문의: {{loop.current.inquiryType}} - {{loop.current.content}}" ``` 정산 데이터 수집 [#정산-데이터-수집] ``` 트리거: 일정 (매일 오전 10시) 액션 1: 카카오선물하기 - 주문단위 정산 조회 ├── 기간 유형: "정산 기준일" ├── 채널: "선물하기" ├── 시작일: {{$today.minus(1, 'day')}} └── 종료일: {{$today}} 액션 2: 데이터모델 행 추가 └── 정산 데이터 저장 ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 카카오쇼핑 API는 **페이지당 최대 100건**까지 조회 가능합니다. 대량 조회 시 페이지네이션을 활용하세요. </Callout> 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. 특히 선물 발송 실패는 고객 경험에 직접 영향을 미치므로 즉시 처리가 필요합니다. --- # 카카오스타일 (/docs/node-reference/actions/korea-business/kakao-style) > 카카오스타일(지그재그, 패션바이카카오, 포스티) API를 통한 주문, 상품, 문의, 리뷰, 스토어 정보, 배송, 정산을 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ------------------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 카카오스타일 파트너센터 API 인증 (접근키 + 비밀키) | | **지원 리소스** | 주문, 상품, 문의, 리뷰, 스토어 정보, 배송, 정산 | <Callout type="info"> 카카오스타일은 **지그재그**, **패션바이카카오**, **포스티** 등 여러 채널을 하나의 파트너센터에서 통합 관리합니다. </Callout> *** 작업 종류 [#작업-종류] 주문 [#주문] | 작업 | 설명 | | ---------------- | ----------------------- | | **주문 목록 조회** | 조건에 맞는 주문 목록 | | **직진배송 주문 조회** | 직진배송(지그재그 자체 물류) 주문 조회 | | **클레임 요청 주문 조회** | 취소/반품/교환 클레임이 접수된 주문 | | **교환 주문 조회** | 교환 요청이 있는 주문 | | **배송준비 상태로 변경** | 선택한 주문 아이템을 배송준비 상태로 변경 | | **송장 입력** | 택배사/송장번호 등록 | | **반품 처리** | 반품 요청 처리 | | **교환 처리** | 교환 요청 처리 | | **주문 취소** | 주문 취소 실행 | | **반품 승인** | 반품 요청 승인 | | **반품 거부** | 반품 요청 거부 | 상품 [#상품] | 작업 | 설명 | | ------------ | ------------ | | **상품 목록 조회** | 등록된 상품 목록 | | **상품 상세 조회** | 특정 상품 정보 | | **상품 등록** | 신규 상품 등록 | | **상품 수정** | 기존 상품 정보 수정 | | **재고 수정** | 상품 재고 수량 변경 | | **판매 상태 변경** | 판매중/판매중지 전환 | | **상품 리뷰 조회** | 특정 상품의 리뷰 목록 | | **상품 문의 조회** | 특정 상품의 문의 목록 | 문의 [#문의] | 작업 | 설명 | | ------------ | ------------ | | **문의 목록 조회** | 고객 문의 목록 | | **문의 상세 조회** | 특정 문의 상세 내용 | | **문의 답변 등록** | 문의에 대한 답변 작성 | 리뷰 [#리뷰] | 작업 | 설명 | | ------------ | ----------------- | | **리뷰 목록 조회** | 리뷰 목록 (상품별 필터 가능) | | **리뷰 상세 조회** | 특정 리뷰 상세 | | **리뷰 답변 등록** | 리뷰에 대한 답변 작성 | 스토어 정보 [#스토어-정보] | 작업 | 설명 | | ------------- | ---------- | | **스토어 정보 조회** | 스토어 기본 정보 | | **배송지 목록 조회** | 등록된 배송지 목록 | | **배송 템플릿 조회** | 배송 템플릿 정보 | 배송 [#배송] | 작업 | 설명 | | ------------- | --------- | | **배송지 목록 조회** | 배송지 목록 | | **배송 템플릿 조회** | 배송 템플릿 정보 | 정산 [#정산] | 작업 | 설명 | | -------------- | ------------ | | **정산 아이템 조회** | 아이템 단위 정산 내역 | | **스토어별 정산 조회** | 스토어 단위 정산 내역 | *** 출력 데이터 [#출력-데이터] ```javascript // 주문 조회 {{actions.kakaoStyle.orders}} {{actions.kakaoStyle.orders[0].orderItemIds}} // 상품 조회 {{actions.kakaoStyle.products}} {{actions.kakaoStyle.products[0].productId}} // 리뷰 조회 {{actions.kakaoStyle.reviews}} {{actions.kakaoStyle.reviews[0].reviewId}} ``` *** 활용 예시 [#활용-예시] 신규 주문 자동 배송준비 전환 [#신규-주문-자동-배송준비-전환] ``` 트리거: 일정 (매 10분) 액션 1: 카카오스타일 - 주문 목록 조회 (결제완료) 액션 2: 반복 ({{actions.kakaoStyle.orders}}) 액션 3: 카카오스타일 - 배송준비 상태로 변경 └── 주문 아이템 ID: {{loop.current.orderItemId}} ``` 리뷰 모니터링 및 알림 [#리뷰-모니터링-및-알림] ``` 트리거: 일정 (매시간) 액션 1: 카카오스타일 - 리뷰 목록 조회 액션 2: 필터 (평점 <= 2) 액션 3: 슬랙 메시지 └── 메시지: "낮은 평점 리뷰: {{loop.current.productName}} - {{loop.current.content}}" ``` 정산 데이터 수집 [#정산-데이터-수집] ``` 트리거: 일정 (매주 월요일) 액션 1: 카카오스타일 - 정산 아이템 조회 ├── 시작일: {{$today.minus(7, 'day')}} └── 종료일: {{$today}} 액션 2: 데이터모델 행 추가 └── 정산 데이터 저장 ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 카카오스타일 API는 **페이지당 최대 100건**까지 조회 가능합니다. 클레임 주문은 별도 조회 API를 사용하므로 주문 유형에 맞는 작업을 선택하세요. </Callout> 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. 송장 입력 실패는 배송 지연으로 이어질 수 있습니다. --- # 네이버 커머스 (/docs/node-reference/actions/korea-business/naver-commerce) > 스마트스토어 주문, 상품, 정산을 관리합니다. 개요 [#개요] | 항목 | 내용 | | ---------- | ----------------------------------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 네이버 커머스 API 연동 | | **지원 리소스** | 주문, 상품, 클레임, 고객 문의, 상품 문의, 정산, 카테고리, 판매자 정보, 채널 | *** 작업 종류 [#작업-종류] 주문 [#주문] | 작업 | 설명 | | ----------------- | --------------------- | | **변경 주문 목록 조회** | 상태별 변경된 주문 ID 조회 (권장) | | **조건형 주문 상세 조회** | 상세 정보를 직접 반환하는 목록 조회 | | **주문 상세 조회** | 특정 주문의 상세 정보 | | **주문 목록 조회 (검색)** | 조건 기반 주문 검색 | | **발주확인 처리** | 발주 확인 | | **발송처리** | 택배사/송장 입력 및 발송 | | **발송 지연 처리** | 발송 지연 사유 등록 | | **배송정보 수정** | 송장 정보 변경 | | **구매확정 요청** | 구매확정 요청 | | **판매자 취소 요청** | 판매자 취소 | | **판매자 반품 요청** | 판매자 반품 | 상품 [#상품] | 작업 | 설명 | | --------------- | ----------- | | **상품 목록 조회** | 원상품 목록 | | **상품 상세 조회** | 원상품 상세 정보 | | **채널 상품 목록 조회** | 채널별 상품 목록 | | **채널 상품 상세 조회** | 채널별 상품 상세 | | **재고 수량 수정** | 재고 수량 업데이트 | | **상품 판매 상태 수정** | 판매중/판매중지 변경 | | **상품 전시 상태 수정** | 전시함/전시안함 변경 | 클레임 (취소/반품/교환) [#클레임-취소반품교환] | 작업 | 설명 | | --------------------- | -------- | | **취소 요청 목록 조회** | 취소 요청 목록 | | **취소 승인/거부** | 취소 요청 처리 | | **반품 요청 목록 조회** | 반품 요청 목록 | | **반품 승인/수거완료/거부/보류** | 반품 요청 처리 | | **교환 요청 목록 조회** | 교환 요청 목록 | | **교환 수거완료/재배송/거부/보류** | 교환 요청 처리 | 고객 문의 [#고객-문의] | 작업 | 설명 | | --------------- | --------------- | | **고객 문의 목록 조회** | 주문 기반 1:1 문의 목록 | | **고객 문의 답변 등록** | 문의에 답변 | | **고객 문의 답변 수정** | 기존 답변 수정 | 상품 문의 [#상품-문의] | 작업 | 설명 | | ------------------ | ---------- | | **상품 문의 목록 조회** | 상품 Q\&A 목록 | | **상품 문의 답변 등록/수정** | 문의에 답변 | | **답변 템플릿 목록 조회** | 답변 템플릿 | 정산 [#정산] | 작업 | 설명 | | ------------ | --------- | | **일별 정산 조회** | 기간별 정산 내역 | | **정산 상세 조회** | 정산 상세 정보 | | **정산 예정 조회** | 정산 예정 내역 | 기타 리소스 [#기타-리소스] | 리소스 | 작업 | | ---------- | --------------------------- | | **카테고리** | 전체 조회, 상세 조회 | | **판매자 정보** | 계정 정보 조회, 스토어 정보 조회, 주소록 조회 | | **채널** | 채널 목록 조회 | *** 택배사 코드 [#택배사-코드] | 코드 | 택배사 | | -------- | ------ | | `CJGLS` | CJ대한통운 | | `LOTTE` | 롯데택배 | | `HANJIN` | 한진택배 | | `LOGEN` | 로젠택배 | | `EPOST` | 우체국택배 | | `KDEXP` | 경동택배 | | `DAESIN` | 대신택배 | *** 설정 옵션 [#설정-옵션] 발송처리 [#발송처리] | 옵션 | 설명 | 필수 | | ---------- | ---------- | :-: | | **상품주문번호** | 네이버 상품주문번호 | ✅ | | **택배사** | 택배사 코드 | ✅ | | **송장번호** | 운송장 번호 | ✅ | *** 출력 데이터 [#출력-데이터] ```javascript // 주문 조회 {{actions.naverCommerce.orders}} {{actions.naverCommerce.orders[0].productOrderId}} {{actions.naverCommerce.orders[0].ordererId}} // 발송처리 {{actions.naverCommerce.success}} ``` *** 활용 예시 [#활용-예시] 발송처리 [#발송처리-1] ``` 트리거: 물류 시스템 웹훅 (송장 생성) 액션: 네이버 커머스 - 발송처리 ├── 상품주문번호: {{trigger.body.productOrderId}} ├── 택배사: "CJGLS" └── 송장번호: {{trigger.body.invoiceNumber}} ``` 신규 주문 동기화 [#신규-주문-동기화] ``` 트리거: 일정 (매 30분) 액션 1: 네이버 커머스 - 주문 조회 ├── 상태: "결제완료" └── 기간: 최근 1시간 액션 2: 반복 ({{actions.naverCommerce.orders}}) 액션 3: 행 생성 (주문 데이터모델) ├── 주문번호: {{loop.current.orderId}} ├── 상품주문번호: {{loop.current.productOrderId}} ├── 상품명: {{loop.current.productName}} └── 수량: {{loop.current.quantity}} ``` 일일 정산 리포트 [#일일-정산-리포트] ``` 트리거: 일정 (매일 오전 10시) 액션 1: 네이버 커머스 - 정산 조회 (어제) 액션 2: 슬랙 메시지 └── 메시지: | 📊 어제 스마트스토어 정산 • 매출: {{actions.naverCommerce.settlement.totalSales}}원 • 수수료: {{actions.naverCommerce.settlement.fee}}원 • 정산금: {{actions.naverCommerce.settlement.settlement}}원 ``` *** 모범 사례 [#모범-사례] 주문 상태 흐름 [#주문-상태-흐름] ``` 결제완료 → 상품준비중 → 배송중 → 배송완료 → 구매확정 ``` API 제한 [#api-제한] 네이버 커머스 API는 **요청 제한**이 있습니다. 대량 처리 시 주의하세요. 송장 입력 타이밍 [#송장-입력-타이밍] 결제완료 후 **48시간 이내** 발송처리를 권장합니다. --- # 네이버톡톡 (/docs/node-reference/actions/korea-business/naver-talktalk) > 네이버톡톡 챗봇을 통해 고객에게 메시지를 보냅니다. 개요 [#개요] | 항목 | 내용 | | --------- | ---------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 네이버톡톡 연동 설정 | | **지원 기능** | 텍스트, 이미지, 복합 메시지 | *** 메시지 유형 [#메시지-유형] | 유형 | 설명 | | ---------- | ------------------------------- | | **텍스트** | 단순 텍스트 메시지 | | **이미지** | 이미지 전송 (jpg, png, gif, 최대 20MB) | | **복합 메시지** | 제목 + 설명 + 이미지 + 버튼 조합 | *** 설정 옵션 [#설정-옵션] 텍스트 메시지 [#텍스트-메시지] | 옵션 | 설명 | 필수 | | ---------- | ---------- | :-: | | **사용자 ID** | 톡톡 사용자 식별자 | ✅ | | **메시지** | 텍스트 내용 | ✅ | 복합 메시지 [#복합-메시지] | 옵션 | 설명 | 필수 | | ----------- | ---------- | :-: | | **사용자 ID** | 톡톡 사용자 식별자 | ✅ | | **제목** | 메시지 제목 | | | **설명** | 메시지 설명 | | | **이미지 URL** | 썸네일 이미지 | | | **버튼** | 액션 버튼 목록 | | *** 버튼 타입 [#버튼-타입] | 타입 | 설명 | | ---------- | ----------- | | **TEXT** | 클릭 시 텍스트 전송 | | **LINK** | 외부 URL로 이동 | | **OPTION** | 하위 버튼 목록 표시 | *** 추가 옵션 [#추가-옵션] | 옵션 | 설명 | | ------------ | ------------------------------- | | **퀵 버튼** | 채팅창 하단에 버튼 표시 (한 번 클릭하면 사라짐) | | **푸시 알림 전송** | 사용자가 채팅창에 없을 때 네이버 앱으로 푸시 알림 전송 | *** 출력 데이터 [#출력-데이터] ```javascript {{actions.talktalk.success}} // 전송 성공 여부 {{actions.talktalk.messageId}} // 메시지 ID ``` *** 활용 예시 [#활용-예시] 배송 시작 알림 [#배송-시작-알림] ``` 트리거: 배송 시작 액션: 네이버톡톡 메시지 발송 ├── 사용자: {{trigger.row.톡톡사용자ID}} ├── 메시지 유형: "복합 메시지" ├── 제목: "배송이 시작되었습니다 🚚" ├── 설명: "{{trigger.row.상품명}}이(가) 출발했습니다." └── 버튼: └── [주문조회] → {{trigger.row.주문조회URL}} ``` 주문 접수 알림 [#주문-접수-알림] ``` 트리거: 주문 생성 액션: 네이버톡톡 메시지 발송 ├── 사용자: {{trigger.row.톡톡사용자ID}} ├── 제목: "주문이 접수되었습니다" ├── 설명: | 주문번호: {{trigger.row.주문번호}} 상품: {{trigger.row.상품명}} 금액: {{trigger.row.결제금액}}원 └── 버튼: └── [주문상세] → {{trigger.row.주문상세URL}} ``` 고객 문의 답변 [#고객-문의-답변] ``` 트리거: 문의 답변 작성 액션: 네이버톡톡 메시지 발송 ├── 사용자: {{trigger.row.고객톡톡ID}} └── 메시지: | 안녕하세요, {{trigger.row.고객명}}님. 문의하신 내용에 답변드립니다: {{trigger.row.답변내용}} 추가 문의사항이 있으시면 말씀해주세요. ``` *** 모범 사례 [#모범-사례] 사용자 동의 [#사용자-동의] 네이버톡톡 메시지는 **사용자가 먼저 대화를 시작**했거나 **수신 동의**한 경우에만 발송 가능합니다. 메시지 빈도 [#메시지-빈도] 너무 잦은 메시지는 사용자 이탈을 유발할 수 있습니다. 꼭 필요한 알림만 보내세요. 이미지 크기 [#이미지-크기] 이미지는 **20MB 이하**로 최적화하세요. --- # 오늘의집 (/docs/node-reference/actions/korea-business/ohouse) > 오늘의집(Ohou) 인테리어/라이프스타일 플랫폼 연동 (공개 API 미제공) import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ---------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 공개 API 미제공 | | **지원 리소스** | - | <Callout type="warn"> 오늘의집은 현재 공개 파트너 API를 제공하지 않습니다. OPEN-API는 \*\*공식 승인된 연동 솔루션 업체(이지어드민 등)\*\*에만 제공됩니다. </Callout> *** 현재 상황 [#현재-상황] 오늘의집 파트너센터(partnerbucketplace.com)가 운영되고 있지만, API 접근은 다음과 같이 제한됩니다. * 공식 승인된 연동 솔루션 업체에만 OPEN-API 제공 * 모든 연동 솔루션 업체는 개인정보 보호 자율규제 협약 동의 필수 * 협약되지 않은 업체는 정보 제공 불가 * 일반 개발자를 위한 API 문서, 키 발급 시스템 없음 *** 대안적 연동 방법 [#대안적-연동-방법] 승인된 솔루션 업체 이용 [#승인된-솔루션-업체-이용] | 솔루션 | 설명 | | -------------- | ------------------------- | | **이지어드민 (핌즈)** | 공식 승인된 주문/상품/배송 통합 관리 솔루션 | 승인된 솔루션의 API를 HTTP Request 노드로 호출하여 간접적으로 오늘의집 데이터를 관리할 수 있습니다. 파트너센터 문의 [#파트너센터-문의] 직접 API 연동이 필요한 경우, 파트너센터에 공식 문의하여 API 제공 가능성을 확인할 수 있습니다. * 카카오톡 채널: 오늘의집 인테리어 파트너센터 * 고객센터: 1660-4161 *** 활용 예시 [#활용-예시] 이지어드민 API를 통한 간접 연동 [#이지어드민-api를-통한-간접-연동] ``` 트리거: 일정 (매일 오전 9시) 액션 1: HTTP Request - 이지어드민 API 주문 조회 액션 2: 반복 ({{actions.httpRequest.orders}}) 액션 3: 데이터모델 행 추가 └── 주문 데이터 저장 ``` *** 참고 자료 [#참고-자료] * [오늘의집 파트너센터](https://www.partnerbucketplace.com/hc/ko) * [오늘의집 연동 솔루션 제한 안내 공지](https://www.partnerbucketplace.com/hc/ko/articles/19574850773529) --- # 올리브영 (/docs/node-reference/actions/korea-business/oliveyoung) > 올리브영 뷰티/헬스 플랫폼 연동 (공개 API 미제공) import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ---------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 공개 API 미제공 | | **지원 리소스** | - | <Callout type="warn"> 올리브영은 외부 개발자/파트너를 위한 **공개 API를 제공하지 않습니다**. 상품/주문/배송/정산 연동은 승인된 쇼핑몰통합관리솔루션(사방넷, 플레이오토, 샵링커 등)을 통해서만 가능합니다. </Callout> *** 현재 상황 [#현재-상황] 올리브영 파트너센터(partner.oliveyoung.co.kr)가 존재하지만, 개발자 문서나 API 레퍼런스는 제공되지 않습니다. 외부 연동은 다음과 같은 아키텍처로 제한됩니다. ``` [쇼핑몰통합관리솔루션] → [외부셀러 서비스] → [올리브영 내부 API] (사방넷, 플레이오토 등) (비동기 Queue 처리) (내부 전용) ``` *** 대안적 연동 방법 [#대안적-연동-방법] 쇼핑몰통합관리솔루션 활용 [#쇼핑몰통합관리솔루션-활용] 올리브영과 통합하려면 다음 승인된 솔루션 중 하나를 사용해야 합니다. | 솔루션 | 주요 기능 | | --------- | ----------------- | | **사방넷** | 상품/주문/배송/정산 통합 관리 | | **플레이오토** | 상품/주문/배송/정산 통합 관리 | | **샵링커** | 상품/주문/배송/정산 통합 관리 | 이들 솔루션의 API를 HTTP Request 노드로 호출하여 간접적으로 올리브영 데이터를 관리할 수 있습니다. 직접 파트너 계약 [#직접-파트너-계약] 올리브영과 직접 입점 파트너 계약을 체결한 경우, 올리브영 담당자를 통해 연동 협의가 가능할 수 있습니다. * 사업 제휴 문의: [https://corp.oliveyoung.com/ko/inquiry/business](https://corp.oliveyoung.com/ko/inquiry/business) *** 활용 예시 [#활용-예시] 사방넷 API를 통한 간접 연동 [#사방넷-api를-통한-간접-연동] ``` 트리거: 일정 (매일 오전 9시) 액션 1: HTTP Request - 사방넷 API 주문 조회 액션 2: 반복 ({{actions.httpRequest.orders}}) 액션 3: 데이터모델 행 추가 └── 주문 데이터 저장 ``` *** 참고 자료 [#참고-자료] * [올리브영 테크블로그](https://oliveyoung.tech/) * [올리브영 파트너센터](https://partner.oliveyoung.co.kr/) * [사방넷](https://www.sabangnet.co.kr/) * [플레이오토](https://www.playauto.io/) --- # 플레이오토 (/docs/node-reference/actions/korea-business/playauto) > 플레이오토 쇼핑몰 통합관리 API를 통한 상품, 주문, 재고, 쇼핑몰, 클레임을 관리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ------------------------------- | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 플레이오토 API 액세스 토큰 | | **지원 리소스** | 상품, 주문, 재고, 쇼핑몰, 클레임 (취소/반품/교환) | *** 작업 종류 [#작업-종류] 상품 [#상품] | 작업 | 설명 | | ------------ | -------------------------------- | | **상품 목록 조회** | 카테고리, 브랜드, 판매 상태 등으로 필터링하여 목록 조회 | | **상품 상세 조회** | 상품 ID로 상세 정보 조회 | | **상품 수 조회** | 조건에 맞는 상품 개수 조회 | | **상품 등록** | 새 상품 등록 (상품명, 가격, 설명, 재고, 코드 등) | | **상품 수정** | 기존 상품 정보 수정 | | **상품 삭제** | 상품 삭제 | 주문 [#주문] | 작업 | 설명 | | ------------ | ------------------------------ | | **주문 목록 조회** | 주문 상태, 주문자/수령자로 필터링하여 목록 조회 | | **주문 상세 조회** | 주문 ID로 상세 정보 조회 | | **주문 수 조회** | 조건에 맞는 주문 개수 조회 | | **주문 품목 조회** | 특정 주문의 품목 목록 조회 | | **주문 상태 변경** | 입금대기/입금확인/배송중/배송완료/취소/반품 상태 변경 | | **배송정보 등록** | 택배사와 송장번호 등록 | | **발주 확인** | 발주 확인 처리 | | **주문 동기화** | 쇼핑몰에서 주문 데이터 동기화 | 재고 [#재고] | 작업 | 설명 | | --------------- | ----------------- | | **재고 목록 조회** | 전체 재고 현황 조회 | | **재고 조회 (상품별)** | 특정 상품의 재고 조회 | | **재고 수정** | 재고 수량 및 안전 재고량 변경 | | **재고 동기화** | 쇼핑몰별 재고 동기화 | 쇼핑몰 [#쇼핑몰] | 작업 | 설명 | | ------------- | --------------- | | **쇼핑몰 목록 조회** | 연결된 쇼핑몰 목록 조회 | | **쇼핑몰 정보 조회** | 특정 쇼핑몰 상세 정보 조회 | | **쇼핑몰 동기화** | 쇼핑몰 데이터 동기화 | 클레임 (취소/반품/교환) [#클레임-취소반품교환] | 작업 | 설명 | | ------------- | ---------------------------- | | **클레임 목록 조회** | 유형(취소/반품/교환) 및 상태별 클레임 목록 조회 | | **클레임 상세 조회** | 클레임 ID로 상세 정보 조회 | | **취소 처리** | 클레임 취소 처리 (사유 입력) | | **반품 처리** | 클레임 반품 처리 (사유 입력) | | **교환 처리** | 클레임 교환 처리 (사유 입력) | | **클레임 동기화** | 쇼핑몰 클레임 데이터 동기화 | *** 활용 예시 [#활용-예시] 다채널 주문 통합 관리 [#다채널-주문-통합-관리] ``` 트리거: 일정 (매 30분) 액션 1: 플레이오토 - 주문 동기화 액션 2: 플레이오토 - 주문 목록 조회 (입금확인 상태) 액션 3: 반복 (신규 주문) 액션 4: 행 생성 (주문 관리 데이터모델) ``` 배송 정보 자동 등록 [#배송-정보-자동-등록] ``` 트리거: 웹훅 (물류 시스템 출고 완료) 액션: 플레이오토 - 배송정보 등록 ├── 주문 ID: {{trigger.body.orderId}} ├── 배송사: cj └── 송장 번호: {{trigger.body.trackingNo}} ``` 클레임 자동 알림 [#클레임-자동-알림] ``` 트리거: 일정 (매 시간) 액션 1: 플레이오토 - 클레임 동기화 액션 2: 플레이오토 - 클레임 목록 조회 (접수 상태) 액션 3: 반복 (신규 클레임) 액션 4: 슬랙 메시지 └── 메시지: "신규 클레임: {{loop.current.claimType}} - 주문 {{loop.current.orderId}}" ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 플레이오토 API 사용은 개발자센터에서 신청 후 액세스 토큰을 발급받아야 합니다. 자세한 내용은 [개발자센터](https://developers.playauto.io/)를 참고하세요. </Callout> 에러 처리 [#에러-처리] API 호출 실패 시 재시도하거나 관리자에게 알림을 보내세요. --- # 팝빌 (/docs/node-reference/actions/korea-business/popbill) > 팝빌 API를 통한 전자세금계산서 발행/조회, 현금영수증 발행/취소, 홈택스 세금계산서 수집을 처리합니다. import { Callout } from 'fumadocs-ui/components/callout'; 개요 [#개요] | 항목 | 내용 | | ---------- | ------------------------------ | | **카테고리** | 국내 비즈니스 | | **연동 필요** | 팝빌 API 인증 (LinkID + SecretKey) | | **지원 리소스** | 전자세금계산서, 현금영수증, 홈택스 세금계산서 수집 | <Callout type="info"> 팝빌은 전자세금계산서, 현금영수증, 홈택스 수집 등 **세금/증빙 관련 API**를 제공하는 서비스입니다. 모든 작업에 **사업자번호**(하이픈 제외 10자리)가 필수입니다. </Callout> *** 작업 종류 [#작업-종류] 전자세금계산서 [#전자세금계산서] | 작업 | 설명 | | --------- | ------------------------------- | | **목록 조회** | 조건별 세금계산서 목록 검색 (날짜/상태/과세형태 필터) | | **상세 조회** | 문서번호로 세금계산서 상세 정보 조회 | | **발행** | 세금계산서 저장 및 즉시 발행 (국세청 전송) | 목록 조회 필터 옵션 [#목록-조회-필터-옵션] | 옵션 | 설명 | | --------- | --------------------------------- | | **문서유형** | 매출 / 매입 / 위수탁 | | **날짜 유형** | 작성일자 / 발행일자 / 전송일자 | | **상태 필터** | 임시저장, 발행대기, 발행완료, 역발행대기, 거부, 취소 등 | | **과세형태** | 과세 / 면세 / 영세 | 발행 필수 입력 [#발행-필수-입력] | 항목 | 설명 | 필수 | | ------------ | ------------------------------ | :-: | | **발행유형** | 매출 / 매입 / 위수탁 | O | | **작성일자** | 세금계산서 작성일 | O | | **과세형태** | 과세 / 면세 / 영세 | O | | **영수/청구** | 영수 또는 청구 | O | | **공급가액** | 공급가액 합계 | O | | **세액** | 세액 합계 | O | | **공급자 정보** | 사업자번호, 상호, 대표자명, 이메일 | O | | **공급받는자 정보** | 사업자번호, 상호, 대표자명, 이메일 | O | | **품목 목록** | JSON 배열 (품명, 단가, 수량, 공급가액, 세액) | - | 현금영수증 [#현금영수증] | 작업 | 설명 | | --------- | ---------------------- | | **목록 조회** | 조건별 현금영수증 목록 검색 | | **상세 조회** | 문서번호로 현금영수증 상세 정보 조회 | | **발행** | 현금영수증 저장 및 즉시 발행 | | **취소 발행** | 기존 현금영수증 취소 (전체/부분 취소) | 발행 필수 입력 [#발행-필수-입력-1] | 항목 | 설명 | 필수 | | ------------ | ---------------------------- | :-: | | **거래구분** | 소득공제용 / 지출증빙용 | O | | **거래일자** | 거래일자 | O | | **공급가액** | 공급가액 | O | | **부가세** | 부가세 | O | | **합계금액** | 공급가액 + 부가세 + 봉사료 | O | | **구매자 식별번호** | 휴대폰, 주민번호, 사업자번호, 카드번호 중 택 1 | O | | **가맹점 정보** | 사업자번호, 상호, 대표자명 | O | 취소 발행 옵션 [#취소-발행-옵션] | 옵션 | 설명 | | ----------- | ------------------------------- | | **당초 승인번호** | 취소할 현금영수증의 국세청 승인번호 (9자리) | | **부분 취소** | 전체 취소 또는 부분 취소 선택 | | **취소 금액** | 부분 취소 시 공급가액, 부가세, 봉사료, 합계금액 입력 | 홈택스 세금계산서 수집 [#홈택스-세금계산서-수집] | 작업 | 설명 | | ------------ | ------------------------- | | **수집 결과 조회** | 수집 완료된 세금계산서 검색 | | **수집 요청** | 홈택스 매입/매출 내역 수집 시작 | | **수집 상태 확인** | 수집 작업의 진행 상태 조회 | | **상세 조회** | 국세청 승인번호로 수집된 세금계산서 상세 조회 | <Callout type="info"> 홈택스 수집은 **비동기 처리**됩니다. 수집 요청 후 작업 ID를 받아 상태를 확인하고, 완료 후 결과를 조회하세요. </Callout> *** 세금계산서 상태 코드 [#세금계산서-상태-코드] | 코드 | 상태 | | ----- | ---------------- | | `100` | 임시저장 | | `200` | 발행대기 | | `300` | 발행완료 | | `303` | 발행완료 (국세청 전송 성공) | | `400` | 역발행대기 | | `500` | 거부 | | `600` | 취소 | *** 출력 데이터 [#출력-데이터] ```javascript // 세금계산서 목록 조회 {{actions.popbill.list}} {{actions.popbill.list[0].invoicerCorpName}} {{actions.popbill.list[0].supplyCostTotal}} {{actions.popbill.total}} // 세금계산서 발행 {{actions.popbill.code}} // 응답 코드 (1: 성공) {{actions.popbill.ntsConfirmNum}} // 국세청 승인번호 // 홈택스 수집 요청 {{actions.popbill.jobID}} // 수집 작업 ID ``` *** 활용 예시 [#활용-예시] 세금계산서 자동 발행 [#세금계산서-자동-발행] ``` 트리거: 데이터모델 행 변경 (주문 확정) 액션: 팝빌 - 세금계산서 발행 ├── 사업자번호: "1234567890" ├── 발행유형: "매출" ├── 공급가액: {{trigger.row.supplyCost}} ├── 세액: {{trigger.row.tax}} ├── 공급자: 자사 정보 ├── 공급받는자: {{trigger.row.buyerInfo}} └── 품목: {{trigger.row.items}} ``` 홈택스 매입 내역 자동 수집 [#홈택스-매입-내역-자동-수집] ``` 트리거: 일정 (매일 오전 8시) 액션 1: 팝빌 - 홈택스 수집 요청 ├── 사업자번호: "1234567890" ├── 수집 유형: "매입" ├── 시작일: {{$today.minus(1, 'day')}} └── 종료일: {{$today}} 액션 2: 대기 (5분) 액션 3: 팝빌 - 수집 상태 확인 └── 작업 ID: {{actions.popbill.jobID}} 액션 4: 팝빌 - 수집 결과 조회 └── 작업 ID: {{actions.popbill.jobID}} 액션 5: 데이터모델 행 추가 └── 수집 데이터 저장 ``` 현금영수증 발행 후 알림 [#현금영수증-발행-후-알림] ``` 트리거: 결제 완료 웹훅 조건: {{trigger.body.paymentMethod}} === "현금" 액션 1: 팝빌 - 현금영수증 발행 ├── 거래구분: "소득공제용" ├── 합계금액: {{trigger.body.totalAmount}} └── 구매자 식별번호: {{trigger.body.customerPhone}} 액션 2: 슬랙 메시지 └── 메시지: "현금영수증 발행 완료: {{trigger.body.totalAmount}}원" ``` *** 모범 사례 [#모범-사례] <Callout type="tip"> 팝빌 세금계산서 검색은 **최대 6개월** 범위까지 조회 가능합니다. 장기 데이터가 필요한 경우 여러 번 나눠서 조회하세요. </Callout> 요금 정보 [#요금-정보] | 항목 | 요금 | | ----------- | ----------------- | | **전자세금계산서** | 건당 200원 (일반회원 기준) | | **홈택스 수집** | 별도 요금 | | **기본료** | 없음 (종량제) | | **연동 개발비** | 무료 | 에러 처리 [#에러-처리] * 세금계산서/현금영수증 발행 실패 시 사유를 확인하고 재시도하세요 * 홈택스 수집은 비동기이므로 반드시 상태 확인 후 결과를 조회하세요 * 인증서 만료 시 홈택스 수집이 실패할 수 있으므로 인증서 만료일을 모니터링하세요 *** 참고 자료 [#참고-자료] * [팝빌 개발자센터](https://developers.popbill.com/) * [Node.js SDK](https://www.npmjs.com/package/popbill) * [세금계산서 API 문서](https://developers.popbill.com/reference/taxinvoice/node/api) * [GitHub](https://github.com/linkhub-sdk/node-popbill)