@decencia/ch-cli 1.30.0 → 1.31.0

package/skill/2t-decencia-channel-policy-v2/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: 2t-decencia-channel-policy-v2
+description: |
+  [2t][v2] 소통채널 정책정의서 작성 가이드.
+  여러 Story·영역에 걸치는 프로젝트 정책을 판정 가능한 문장으로 명문화한다.
+  3단계 절차: 수확(유저플로우·로직 플로우의 분기에서 질문 발굴) → 확정(선택지 설계·의사결정) → 명문화.
+  Use when:
+  (1) 정책정의서를 새로 쓰거나 수정할 때,
+  (2) 유저플로우·기능명세를 검토하다 "이건 정해진 게 없다"는 질문이 나왔을 때,
+  (3) 알림 발송 매트릭스·크레딧 지급 기준·타임아웃 처리 같은 횡단 정책을 정리할 때.
+version: 1.31.0
+---
+
+<!-- ch-version-gate -->
+## ⚠️ 시작 전 필수 — 버전 게이트 (생략 금지)
+
+이 스킬로 **어떤 작업이든 수행하기 전에 가장 먼저** 아래를 실행한다:
+
+```bash
+ch check
+```
+
+- exit code 0(통과)이 **아니면 즉시 중단**한다. 출력에 안내된 업데이트 명령(`npm install -g @decencia/ch-cli@latest` 또는 `ch setup-skill`)을 사용자에게 전달하고, 갱신이 끝나기 전까지 **이 스킬의 어떤 단계도 진행하지 않는다.**
+- `ch`가 미설치/미인증이어도 먼저 `ch check`를 시도한다. (네트워크 불가 시 ch check는 통과시키되 경고를 남긴다.)
+
+구버전 스킬·CLI 사용을 막기 위한 게이트다. 건너뛰지 말 것.
+
+
+# 정책정의서 — 작성 표준
+
+정책정의서는 **여러 Story·영역에 걸치는 프로젝트 정책**을 판정 가능한 문장으로 기록하는 문서다. 웹 "정책정의서" 탭에 올린다.
+
+## 0. 경계 — 어디에 적나
+
+| 규칙의 범위 | 적는 곳 |
+|---|---|
+| 한 Story 안에서만 유효한 규칙 | spec의 비즈니스 규칙 ([[2t-decencia-channel-spec-v2]] §8) |
+| 여러 Story·영역에 걸치는 정책 | **정책정의서** (여기) |
+
+- 정책 본문을 spec의 businessRules에 복붙하지 않는다. spec은 `연관 Spec ID` 링크로 잇는다.
+- enum·상태값 정의는 여전히 db-tables가 SSOT다. 정책은 그 값을 *이용한 결정*만 적는다.
+
+## 1. 구성요소
+
+| 항목 | 필드 | 작성 |
+|---|---|---|
+| Policy ID | `id` | 사용자 지정 권장 — `POL-001` (spec ID와 같은 패턴 `PREFIX-숫자`) |
+| 정책명 | `name` | 무엇에 관한 정책인지 한 줄 |
+| 영역/분류 | `category` | 자유 문자열. Epic 도메인 코드(AUTH/ORDER/POINT…)와 맞추면 검색이 편하다 |
+| 본문 | `content` | **마크다운**. 웹 탭이 마크다운 뷰어로 렌더한다 |
+| 연관 Spec ID | `relatedSpecIds[]` | 이 정책이 적용되는 Story들 |
+
+## 2. 작성 절차 (3단계)
+
+### ① 질문을 발굴한다 (수확)
+
+정해진 게 없는 지점을 찾아 질문 목록으로 만든다.
+
+- **유저플로우에서 분기 처리된 부분들**을 검토한다 ([[2t-decencia-channel-userflow-v2]]). 갈림길마다 "이 갈림의 기준은 확정됐나?"
+- **기능명세 로직 플로우의 실패·차단 분기**를 검토한다. 분기마다 "임계값·대기시간·처리방향이 정해졌나?"
+- 산출물: "정책이 필요한 질문" 목록. 예: "결제 대기 중 상대가 응답하지 않으면 언제까지 기다리나?"
+
+### ② 선택지를 설계해 확정을 받아낸다 (확정)
+
+- 질문마다 **선택지 2~4개**를 설계해 의사결정자에게 제시한다. 열린 질문("어떻게 할까요?")으로 묻지 않는다.
+- 각 선택지에 트레이드오프를 한 줄씩 붙인다.
+- 예: "무응답 대기: (A) 24시간 후 자동취소 — 단순, (B) 72시간 + 1회 리마인드 — 전환율 유리".
+- 확정받지 못한 질문은 정책정의서에 넣지 않는다. 질문 목록에 남겨둔다.
+
+### ③ 판정 가능한 문장으로 굳힌다 (명문화)
+
+확정된 결정을 **참/거짓을 판정할 수 있는 문장**으로 적는다.
+
+- 주체·조건·수치·기한이 문장 안에 있어야 한다.
+- ❌ `무응답 시 적절히 처리한다`
+- ❌ `크레딧은 일정 기간 후 만료된다`
+- ⭕ `구매자가 결제 요청 후 24시간 내 응답하지 않으면 시스템이 거래를 자동 취소하고 판매자에게 알림톡을 보낸다`
+- ⭕ `가입 축하 크레딧 3,000원은 가입일로부터 30일 후 자정에 만료된다`
+- 표로 정리되는 정책(이벤트×수신처 매트릭스 등)은 마크다운 표를 쓴다.
+
+## 3. 정책정의서로 작성할 만한 내용
+
+- 알림톡·이메일이 발송되는 **이벤트와 수신처 목록** (이벤트 × 채널 × 수신자 매트릭스)
+- 무료 지급 크레딧의 **지급 기준·지급 액수·만료 기간**
+- 거래 플로우 등에서 **한쪽이 응답하지 않을 때의 대기시간과 처리방향**
+- 환불·취소 가능 조건과 수수료
+- 등급·권한 승격/강등 기준
+- 데이터 보존 기간·삭제 정책
+
+하나의 정책정의서 = 하나의 주제. 전 영역을 한 문서에 몰아넣지 않는다.
+
+## 4. 업로드 — 웹 탭 · CLI
+
+```bash
+ch policies list                                    # 표: id | category | name | specs
+ch policies get POL-001                             # 상세 (--json 이면 순수 JSON)
+ch policies create --id POL-001 --name "거래 무응답 처리" \
+  --category ORDER --file ./policy.md --related-specs ORDER-003,ORDER-007
+ch policies update POL-001 --file ./policy.md
+ch policies delete POL-001
+```
+
+- `--file`은 마크다운 본문. CRLF는 자동 정제된다. `--related-specs`는 쉼표 구분 spec ID.
+- 웹 "정책정의서" 탭: 목록에서 클릭하면 사이드 패널에서 열람·수정한다 (상세기획과 같은 UI).
+- Read-before-Write: 수정 전 `get`으로 현재 본문을 받아 편집한다.
+
+## 5. 흔한 함정
+
+- **확정 없이 명문화** — ②를 건너뛰고 에이전트가 임의로 정책을 정하지 않는다. 선택지를 만들어 확정을 받는다.
+- **판정 불가능한 문장** — "적절히", "일정 기간", "빠르게"가 들어가면 정책이 아니다. 수치로.
+- **spec businessRules와 중복** — 한 Story 규칙은 spec에, 횡단 정책은 여기에. 복붙 금지 (§0).
+- **질문 없이 백지에서 쓰기** — 정책은 유저플로우·로직 플로우의 분기에서 수확한 질문에서 나온다 (①).
+- **한 문서에 전 영역 몰아넣기** — 주제별로 나눈다.
+- 확정 안 된 질문을 본문에 "TBD"로 남기기 — 본문에는 확정된 것만. 미확정은 질문 목록으로 관리.

package/skill/2t-decencia-channel-prd-v2/SKILL.md

@@ -2,12 +2,12 @@
 name: 2t-decencia-channel-prd-v2
 description: |
   [2t][v2] 소통채널 PRD 작성/수정 가이드.
-  Epic-Story 체계와의 연결성에 초점 (PRD의 Epic 절 → spec의 --epic).
+  Epic-Story 체계와의 연결성에 초점 (PRD 기능 요구사항의 카테고리 → spec의 --epic).
   Use when:
   (1) PRD를 작성하거나 갱신할 때,
   (2) PRD 구성에서 Epic/스토리 구조를 후속 spec 작성에 매핑할 때,
   (3) Read-before-Write 규칙으로 PRD content를 안전하게 수정해야 할 때.
-version: 1.30.0
+version: 1.31.0
 ---
 
 <!-- ch-version-gate -->
@@ -37,7 +37,7 @@ PRD는 **무엇을 왜 만드는가(기능·가치·범위)의 개요**만 다
 - 같은 설명을 PRD와 spec 양쪽에 적으면 변경 시 어긋난다. **상세 설명은 spec 한 곳에만** 둔다.
 - 독자가 동작 상세를 보고 싶으면 spec으로, 데이터 모델을 보고 싶으면 DB 스키마 문서(웹 "DB 스키마" 탭)로 간다 — PRD가 그 사본을 들고 있지 않는다.
 
-> spec의 상세 설명은 **완결 문장**으로 쓴다(필드명·단어 나열 금지) — [[2t-decencia-channel-spec-v2]] §5. PRD는 그 상세를 옮겨 적지 않고 한 줄 개요로만 가리킨다.
+> spec의 상세 설명은 **완결 문장**으로 쓴다(필드명·단어 나열 금지) — [[2t-decencia-channel-spec-v2]] §7. PRD는 그 상세를 옮겨 적지 않고 한 줄 개요로만 가리킨다.
 
 ## 0. Read-before-Write
 
@@ -55,23 +55,48 @@ ch prd set --content /tmp/prd-edited.md            # 2) 통째 교체 (버전
 # 프로젝트명 PRD
 
 ## 1. 개요
+### 1.1 제품 한줄 정의
+### 1.2 문제 정의
+### 1.3 해결 방식(핵심가치)
+### 1.4 핵심 업무 흐름
+
 ## 2. 사용자 페르소나 / 시나리오
 
-## 3. Epic 목록
-### 3.1 [Epic: 인증]
-- 목적, KPI
-- 포함 Story: 로그인, 회원가입, 비밀번호 재설정
-### 3.2 [Epic: 결제]
+## 3. 용어정의
+- 프로젝트에서 쓰는 단어의 확정 의미
+
+## 4. 전제조건/의존성
+- 개발 팀에서 통제하지 못하는 것들
+- 예) PG 가맹 심사는 고객사가 진행하며, 심사 완료 전까지 결제 연동 검증 불가
+- 예) 서버 인프라는 고객사 기존 AWS 계정을 사용하며, 접근 권한은 착수 시 발급
+- 예) 콘텐츠(상품 정보, 이미지)는 고객사가 입력
+
+## 5. 기술스택
+
+## 6. 외부연동목록
+
+## 7. 기능 요구사항
+### 7.1 [AUTH — 회원·인증]
+| 기능 | 설명 |
+|---|---|
+| 로그인 | 이메일/비밀번호로 로그인한다 |
+| 회원가입 | ... |
+### 7.2 [ORDER — 주문·결제]
 - ...
 
-## 4. 비기능 요구사항
-## 5. 마일스톤 / 일정
+## 8. 범위 제외
+- 해당 프로젝트에서 포함되지 않는 개발 범위
 ```
 
 > ⚠️ **데이터 모델 절은 두지 않는다.** 테이블/컬럼/스키마는 PRD의 책임이 아니다 — DB 스키마는 [[2t-decencia-channel-db-schema-v2]](db-schema/db-tables)가 SSOT. PRD는 Epic/Story가 다루는 *기능*만 서술한다.
 
-PRD의 각 Epic 절 → spec 작성 시 `--epic` 값으로 그대로 사용.
-PRD의 각 Story 항목 → 1개 spec(=Story)으로 생성.
+기능 요구사항(§7)의 각 카테고리 → spec 작성 시 `--epic` 값으로 그대로 사용.
+기능 목록표의 각 기능 행 → 1개 spec(=Story)으로 생성.
+
+**카테고리 = Epic = 도메인 단위 코드**다. 기능 묶음이 아니라 도메인으로 나눈다.
+표준 코드: `AUTH`(회원·인증) `PROD`(상품·탐색) `ORDER`(주문·결제) `POINT`(포인트·쿠폰) `ADMIN`(관리자) `SYS`(공통·시스템).
+프로젝트 성격에 맞게 추가한다. 코드 규칙·Spec ID 연계는 [[2t-decencia-channel-spec-v2]] §3.
+각 기능 행은 Story로 쪼갤 수 있어야 한다 — INVEST·수직 분할은 [[2t-decencia-channel-spec-v2]] §2.
 
 ## 2. 마크다운 작성 규칙
 

package/skill/2t-decencia-channel-project-bootstrap/SKILL.md

@@ -2,7 +2,7 @@
 name: 2t-decencia-channel-project-bootstrap
 description: 신규 기획을 사용자와 대화하며 step-by-step으로 소통채널 프로젝트로 만드는 오케스트레이터 스킬. (1)대화로 PRD 완성 → (2)기능명세(spec) 내용 확정 → (3)DB 스키마 → (4)spec 업로드 → (5)화면 구성·연결 → (6)SQA 시트. 각 단계 사용자 승인 게이트, 작성 디테일은 기존 2t-decencia-channel-*-v2 스킬을 적극 재사용. "새 기획 만들어줘"·"프로젝트 처음부터 세팅" 류 요청 시.
 allowed-tools: Bash(ch:*) Bash(git:*) Read Write
-version: 1.30.0
+version: 1.31.0
 ---
 
 <!-- ch-version-gate -->
@@ -52,8 +52,9 @@ ch check
   - **schema 설정**(⚠️ 빠지면 웹 UI가 빈 칼럼으로 보임) + **specVersion=2**(Epic-Story·Story Point).
   - cwd에 `.ch-project`(`{"projectId":"..."}`) 기록 → 이후 issue-coder/머저가 사용.
 
-### 0-1. 화면 모드 확인 (screensEnabled)
-- **신규 프로젝트는 서버가 `screensEnabled: true`로 만든다.** 화면 정보의 SSOT는 screens 리소스다. **신규 프로젝트 spec에는 `ui.route`를 쓰지 않는다.**
+### 0-1. 모드 확인 (screensEnabled · storySpecsEnabled)
+- **신규 프로젝트는 서버가 `screensEnabled: true` + `storySpecsEnabled: true`로 만든다.** 화면 정보의 SSOT는 screens 리소스다. **신규 프로젝트 spec에는 `ui.route`를 쓰지 않는다.**
+- `storySpecsEnabled=true`면 spec은 **스토리 명세 구조**다(스토리문장·사전 조건·로직 플로우·비즈니스 규칙 — [[2t-decencia-channel-spec-v2]] §1). 기존 프로젝트(플래그 없음)는 종전 ui/logic 구조 그대로다.
 - 기존 프로젝트를 이어 쓰면 `ch projects info --json`으로 `screensEnabled`를 본다. **키가 아예 없거나 false면 레거시다.** (레거시 프로젝트 응답에는 이 키가 없다. 없음 = false로 읽는다.)
 - **레거시는 route 방식을 그대로 유지한다.** §5(화면 구성)를 건너뛰고 spec의 `ui.route`를 계속 쓴다.
 
@@ -72,10 +73,13 @@ ch check
 ## 2. 기능명세(spec) — 내용 확정
 *(PRD 승인 후에만)*
 - `2t-decencia-channel-spec-v2` 규칙대로 PRD의 Epic/Story → spec 본문을 짠다.
-- ui 필드는 화면 모드 기준으로 채운다: `interactionMap`·`primaryActions`·`keyInformation`. **`route`·`access`·`figmaNodeId`·`file`은 쓰지 않는다.** 이 4개는 화면(screens) 소유다.
-  - `screenRefs`(화면 연결)도 spec.ui 소유지만 지금은 비워둔다. 화면이 아직 없다 — §5에서 연결한다.
-  - 레거시 프로젝트(§0-1)는 예외다. 종전대로 `route`·`access`·`figmaNodeId`·`file`을 spec에 쓴다.
-- 이 단계의 산출물은 **기능 목록 + spec 본문 초안**이다. 항목: 이름 · epic · points · 핵심 액션 · 필요 테이블 후보.
+- **Story 분해부터 검증한다** — INVEST·수직 분할([[2t-decencia-channel-spec-v2]] §2). 기술 레이어("주문 테이블 생성")로 자르지 않고, 경로가 여럿이면 경로별로 쪼갠다.
+- Epic은 도메인 단위 코드로 (AUTH/PROD/ORDER/POINT/ADMIN/SYS … — [[2t-decencia-channel-spec-v2]] §3). PRD 기능 요구사항의 카테고리와 같은 코드다.
+- spec 본문은 스토리 명세 구조로 짠다: 스토리문장(As a/I want/So that 줄글) · 사전 조건 · 로직 플로우 · 비즈니스 규칙.
+  - interactionMap·primaryActions·keyInformation·stateTransitions는 쓰지 않는다 — 스토리 명세에 없다.
+  - 화면 연결(`screenRefs`)은 지금은 비워둔다. 화면이 아직 없다 — §5에서 연결한다.
+  - 레거시 프로젝트(§0-1)는 예외다. 종전 ui/logic 구조([[2t-decencia-channel-spec-v2]] §L)로 쓴다.
+- 이 단계의 산출물은 **기능 목록 + spec 본문 초안**이다. 항목: 이름 · Spec ID(EPIC-NNN) · epic · points · 스토리문장 · 필요 테이블 후보.
 - ⚠️ **서버 업로드는 여기서 하지 않는다.** 테이블을 먼저 만들고 §4에서 `dbTableRefs`와 함께 생성한다.
 - → **[게이트] 사용자 확인.** OK면 3단계.
 
@@ -83,7 +87,7 @@ ch check
 *(기능명세 승인 후에만)*
 - `2t-decencia-channel-db-schema-v2`로 db-schema(ERD/정책) + db-tables(컬럼·인덱스·보안규칙) 작성.
 - `spec.dbTableRefs` ↔ `dbTable.relatedSpecIds` 양방향.
-- **spec 업로드보다 앞선다.** spec 생성 시 `--db-tables`에 실제 tableId가 필요하기 때문이다([[2t-decencia-channel-spec-v2]] §6-3 — 테이블 먼저, spec 연결은 그 다음).
+- **spec 업로드보다 앞선다.** spec 생성 시 `--db-tables`에 실제 tableId가 필요하기 때문이다([[2t-decencia-channel-spec-v2]] §10-3 — 테이블 먼저, spec 연결은 그 다음).
 - → **[게이트] 사용자 확인.** OK면 4단계.
 
 ## 4. spec 업로드
@@ -93,32 +97,25 @@ ch check
 
 ```bash
 ch specs create --id PROJ-001 --name "프로젝트 목록" \
-  --device 웹 --domain 프로젝트 --type 화면 \
-  --epic "프로젝트" --points 5 \
-  --ui ui.json --logic logic.json --db-tables tbl_projects,tbl_members
+  --device 웹 --domain 프로젝트 --permission 관리자 \
+  --epic PROJ --points 5 \
+  --story "관리자는 진행 중인 프로젝트를 한눈에 보고, 원하는 프로젝트로 바로 들어가고 싶다." \
+  --preconditions ./preconditions.md \
+  --logic logic.json --db-tables tbl_projects,tbl_members
 ```
 
-⚠️ `--device`·`--domain`·`--type`은 **필수 플래그**다. 빼면 CLI가 실행 즉시 실패한다. 값은 `ch specs meta --json`이 준 스키마 안에서 고른다.
+⚠️ `--device`·`--domain`은 **필수 플래그**다. 값은 `ch specs meta --json`이 준 스키마 안에서 고른다. `--domain`은 쉼표로 복수 지정 가능하다.
 
-`ui.json` (화면 모드):
-
-```json
-{
-  "interactionMap": "## 인터랙션\n...",
-  "primaryActions": "- 프로젝트를 만든다",
-  "keyInformation": "- 진행 중 프로젝트 수"
-}
-```
-
-- `route`·`access`·`figmaNodeId`·`file`은 화면(screens)에 있다. spec.ui에 넣지 않는다.
-- `interactionMap`은 기능이 소유한다. 화면 모드에서도 계속 쓴다.
-- `screenRefs`도 여기에 넣지 않는다. 화면이 아직 없다 — 연결은 §5에서 `ch specs screen-refs`로 건다.
+- `logic.json`은 로직 플로우 시나리오(실패·차단 분기 포함) + businessRules — [[2t-decencia-channel-spec-v2]] §7·§8.
+- `--ui`는 생성 시점에 넣지 않는다. 화면이 아직 없다 — 연결은 §5에서 `ch specs screen-refs`로 건다.
+- 레거시 프로젝트(§0-1)는 종전 플래그(`--type`·`--content`·`--ui ui.json`)를 그대로 쓴다 — [[2t-decencia-channel-cli-v2]] §1.
 - → **[게이트] 사용자 확인.** OK면 5단계.
 
 ## 5. 화면 구성·연결
 *(spec 업로드 후에만. 레거시 프로젝트는 건너뛴다 — §0-1)*
 
 기능들을 **화면에 배치**한다. 화면은 사용자가 실제로 마주하는 단위다.
+화면마다 적을 내용(필수 기재항목 6종·디스크립션 작성규칙·예외상태 4종)은 [[2t-decencia-channel-screen-v2]]를 따른다.
 
 **입력**: §2의 기능 목록 + §4에서 만든 spec ID.
 

package/skill/2t-decencia-channel-screen-v2/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: 2t-decencia-channel-screen-v2
+description: |
+  [2t][v2] 소통채널 화면설계서 작성 가이드.
+  화면당 필수 기재항목 6종(ID·화면명·접근권한 / 영역별 표시 데이터 / 액션별 동작·이동 /
+  입력 검증 규칙 / 예외상태 4종 / 연결 기획 ID)과 디스크립션 작성규칙(출처까지·결과까지·검증까지·정책은 참조만).
+  IA 트리 뷰(zoom/pan)·와이어프레임+디스크립션 좌우 분할 뷰 기준.
+  Use when:
+  (1) 화면(screens) 문서를 작성·수정할 때,
+  (2) 화면의 표시 데이터·액션·입력 검증·예외상태를 기재할 때,
+  (3) 웹 "화면" 탭의 IA 트리·화면 상세에 올릴 내용을 쓸 때.
+version: 1.31.0
+---
+
+<!-- ch-version-gate -->
+## ⚠️ 시작 전 필수 — 버전 게이트 (생략 금지)
+
+이 스킬로 **어떤 작업이든 수행하기 전에 가장 먼저** 아래를 실행한다:
+
+```bash
+ch check
+```
+
+- exit code 0(통과)이 **아니면 즉시 중단**한다. 출력에 안내된 업데이트 명령(`npm install -g @decencia/ch-cli@latest` 또는 `ch setup-skill`)을 사용자에게 전달하고, 갱신이 끝나기 전까지 **이 스킬의 어떤 단계도 진행하지 않는다.**
+- `ch`가 미설치/미인증이어도 먼저 `ch check`를 시도한다. (네트워크 불가 시 ch check는 통과시키되 경고를 남긴다.)
+
+구버전 스킬·CLI 사용을 막기 위한 게이트다. 건너뛰지 말 것.
+
+
+# 화면설계서 — 작성 표준
+
+화면설계서는 화면(screen) 하나가 **무엇을 보여주고, 눌리면 어떻게 되고, 어떤 입력을 어떻게 검증하는지**를 적는 문서다. 웹 "화면" 탭의 IA 트리에서 노드를 클릭하면 보인다.
+
+역할 분담: 흐름(시나리오)은 spec([[2t-decencia-channel-spec-v2]] §7), 여정 갈림길은 유저플로우([[2t-decencia-channel-userflow-v2]]), 횡단 정책은 정책정의서([[2t-decencia-channel-policy-v2]]). 화면설계서는 **그 화면 안에서 보이는 것·눌리는 것**만 적는다.
+
+## 1. 필수 기재항목
+
+| 항목 | 내용 |
+|---|---|
+| 화면 ID + 화면명 + 접근권한 | `id`(슬러그, 예: `STORE-ORDER-DETAIL`) · `name` · `access` |
+| 영역별 표시 데이터 | 화면을 영역(헤더/목록/요약 카드…)으로 나누고, 각 영역에 표시되는 데이터를 **출처까지** 적는다 |
+| 액션별 동작 및 이동화면 | 버튼·링크·제스처마다 동작과 **결과**(이동 화면 ID·성공/실패 갈림)를 적는다 |
+| 입력 검증 규칙 | 입력마다 **필수/형식/길이/중복** + 실패 시 노출 문구 |
+| 예외상태 4종 | **빈상태 · 로딩 · 에러 · 권한 없음** — 4종 전부, 각각 무엇을 보여주는지 |
+| 연결된 기획 ID | 이 화면에 걸린 spec ID들 (`relatedSpecIds` — 서버 관리, `ch specs screen-refs`로 연결) |
+
+## 2. 디스크립션 작성규칙
+
+| 규칙 | 나쁜 예 | 좋은 예 |
+|---|---|---|
+| **데이터는 출처까지** | 주문 정보 표시 | `ORDERS.주문번호, 상품명, 결제금액` |
+| **버튼은 결과까지** | 취소 버튼 | 취소 확정 → PG 취소 요청, 성공 시 `SCR-08` 이동, 실패 시 `E-02` |
+| **입력은 검증까지** | 사유 입력 | 필수, 선택형+기타(200자), 미선택 시 '사유를 선택해주세요' 노출 |
+| **정책은 참조만** | 취소 규칙 본문을 복사해 기재 | `POL-007` 적용 |
+
+- 데이터 출처는 `테이블.컬럼` 이름 참조다. 컬럼 정의(type·nullable)는 적지 않는다 — db-tables가 SSOT.
+- 이동 화면은 화면 ID로 가리킨다. "다음 화면으로" 같은 서술 금지.
+- 정책 본문을 복사하지 않는다. Policy ID로 참조만 한다.
+
+## 3. 예외상태 4종 — 빠짐없이
+
+모든 화면은 4종을 전부 적는다. "해당 없음"이면 그렇게 적는 것도 기재다.
+
+| 상태 | 적을 것 |
+|---|---|
+| 빈상태 | 데이터 0건일 때 무엇을 보여주나 (안내 문구 + 유도 액션) |
+| 로딩 | 스피너/스켈레톤 어느 쪽인지, 어디에 |
+| 에러 | 실패 안내 + 재시도 수단 |
+| 권한 없음 | 차단 화면인지 리다이렉트인지, 안내 문구 |
+
+## 4. IA 트리 뷰
+
+- 웹 "화면" 탭은 화면들을 **IA 트리**(route 계층)로 보여준다. 유저플로우와 같은 zoom in/out·pan 뷰어다.
+- 노드를 클릭하면 화면 상세가 열린다: **좌측 와이어프레임 뷰 · 우측 디스크립션**(§1 항목들).
+- 트리가 읽히려면 route를 계층적으로 짓는다 (`/store/orders` → `/store/orders/[id]`). 화면 ID 슬러그도 계층을 반영한다.
+
+## 5. 업로드 — CLI
+
+화면 생성·수정의 기본 명령은 [[2t-decencia-channel-cli-v2]] §3. 구조 확장 필드는 JSON 파일로 준다.
+
+```bash
+ch screens update SCR-ORDER-DETAIL \
+  --areas ./areas.json --actions ./actions.json --input-rules ./input-rules.json \
+  --states ./states.json
+```
+
+`areas.json` — 영역별 표시 데이터 (출처까지):
+
+```json
+[
+  { "name": "주문 요약", "description": "ORDERS.주문번호, 상품명, 결제금액" },
+  { "name": "배송 정보", "description": "SHIPMENTS.송장번호, 택배사, 배송상태" }
+]
+```
+
+`actions.json` — 액션별 동작·이동 (결과까지):
+
+```json
+[
+  { "name": "취소 확정", "description": "PG 취소 요청. 성공 시 이동, 실패 시 E-02 노출", "targetScreenId": "SCR-ORDER-CANCELED" },
+  { "name": "뒤로가기", "description": "목록으로 복귀 (변경사항 없음)", "targetScreenId": "SCR-ORDER-LIST" }
+]
+```
+
+`input-rules.json` — 입력 검증 규칙:
+
+```json
+[
+  { "name": "취소 사유", "rules": "필수, 선택형+기타(200자), 미선택 시 '사유를 선택해주세요' 노출" }
+]
+```
+
+`states.json` — 예외상태 4종 필수 (추가 상태 허용):
+
+```json
+[
+  { "name": "빈상태", "description": "주문 내역이 없습니다 + [상품 보러가기]" },
+  { "name": "로딩", "description": "스켈레톤 3행" },
+  { "name": "에러", "description": "불러오지 못했습니다 + [재시도]" },
+  { "name": "권한 없음", "description": "본인 주문만 열람 가능 안내 후 목록으로 리다이렉트" }
+]
+```
+
+- 배열 JSON은 **통째 교체**다. 수정 전 `ch screens get <id> --json`으로 받아 편집한다 (Read-before-Write).
+- `targetScreenId`는 실존 화면 ID여야 한다 (서버 검증).
+
+## 6. 흔한 함정
+
+- **출처 없는 데이터 서술** — "주문 정보 표시"는 기재가 아니다. `테이블.컬럼`까지.
+- **결과 없는 버튼 서술** — "취소 버튼"은 기재가 아니다. 성공/실패 뒤에 무엇이 오는지까지.
+- **검증 없는 입력 서술** — 필수/형식/길이/중복 + 실패 문구까지.
+- **정책 본문 복붙** — Policy ID 참조만 (§2). 정책이 바뀌면 화면설계서가 낡는다.
+- **예외상태 일부 생략** — 4종 전부. 해당 없으면 "해당 없음"이라고 적는다.
+- **흐름 서술** — 여러 화면에 걸친 시나리오는 spec·유저플로우의 몫이다. 이 화면 안의 것만.
+- 화면과 spec은 N:1이다. spec 수만큼 화면을 만들지 않는다 ([[2t-decencia-channel-spec-v2]] §9).