docs(docs): 문서 샘플과 리뷰 규칙을 갱신한다

docs/sample/sample-prd.md

@@ -0,0 +1,271 @@
+# 제품 요구사항 문서(PRD) 샘플
+
+> 이 문서는 요구사항을 API Contract와 goal 실행형 `plan-task.md`로 연결하기 위한 템플릿이다. 실제 `prd.md`를 만들 때 `<...>` placeholder와 예시 ID를 모두 제품의 구체적인 값으로 교체한다.
+
+## 문서 정보
+
+| 항목 | 내용 |
+|---|---|
+| 문서 상태 | 초안 / 검토 중 / 구현 기준 확정 / 구현 완료 |
+| 작성일 | `YYYY-MM-DD` |
+| 최종 수정일 | `YYYY-MM-DD` |
+| 대상 제품 | `<제품 또는 기능 이름>` |
+| 작성자·결정권자 | `<이름 또는 역할>` |
+| 관련 API Contract | `<대상 api-contract.md 경로>` |
+| 관련 구현 계획 | `<대상 plan-task.md 경로>` |
+| 관련 review | `<없음 또는 같은 작업 디렉터리의 reviews/ 아래 문서 링크>` |
+
+### 요구사항 상태
+
+| 상태 | 의미 | 구현 처리 |
+|---|---|---|
+| 확정 | 제품·기술 결정이 완료되어 구현 기준으로 사용 | `plan-task.md`의 Task와 완료 증거로 추적 |
+| 미결 | 제품·UX·운영 결정이 더 필요함 | 권고안과 결정 주체·기한을 기록하고 임의 구현 금지 |
+| 외부 의존 | 프론트엔드 밖의 계약·권한·환경 제공이 필요함 | 담당 주체·영향·재개 조건을 기록하고 추정 구현 금지 |
+| 권고 | 미결 항목에 대한 현재 추천안 | 확정되기 전 계약이나 수용 기준으로 사용하지 않음 |
+| 제외 | 현재 릴리스에서 구현하지 않기로 결정 | 제외 이유와 후속 조건을 Decision Log에 기록 |
+
+### 문서 우선순위와 갱신 순서
+
+1. 사용자·제품 결정은 이 PRD에 기록한다.
+2. request/response/error 계약은 `api-contract.md`에 정규화한다.
+3. 구현 범위·순서·완료 증거는 `plan-task.md`에 반영한다.
+4. 요구사항이 바뀌면 Decision Log → 관련 요구사항·수용 기준 → API Contract → plan 순서로 갱신한다.
+5. 기존 결정과 검증 기록은 삭제하거나 덮어쓰지 않고 정정 기록을 누적한다.
+
+## 1. Overview
+
+`<누가 어떤 상황에서 어떤 가치를 얻는 제품인지 2~4문장으로 설명한다.>`
+
+## 2. Problem Statement
+
+현재 사용자는 다음 문제를 겪는다.
+
+- `<관찰 가능한 현재 문제>`
+- `<기존 방식의 비용·위험·제약>`
+- `<해결하지 않을 때의 사용자 또는 사업 영향>`
+
+문제를 해결했다는 판단은 `<측정하거나 직접 확인할 결과>`로 한다.
+
+## 3. Goals
+
+### 3.1 제품 목표
+
+- `<사용자가 완료할 수 있어야 하는 핵심 결과>`
+- `<안전성·운영 효율·데이터 품질 목표>`
+- `<릴리스 후 측정 가능한 성공 목표>`
+
+### 3.2 UX 목표
+
+- `<핵심 흐름의 명확성·속도 목표>`
+- `<오류·loading·empty·success feedback 목표>`
+- `<반응형·keyboard·접근성 목표>`
+
+## 4. Non-Goals
+
+- `<명시적으로 구현하지 않을 기능>`
+- `<다음 릴리스 또는 외부 시스템 소유 범위>`
+- `<복원, hard delete, 자동 갱신처럼 금지할 동작>`
+
+Non-Goal을 변경하려면 Decision Log와 `plan-task.md` 범위를 먼저 갱신한다.
+
+## 5. Target Users and Permissions
+
+### 5.1 사용자
+
+| 사용자 | 목표 | 주요 작업 | 사용 환경 |
+|---|---|---|---|
+| `<역할>` | `<달성 목표>` | `<조회·생성·수정 등>` | `<desktop/mobile 등>` |
+
+### 5.2 권한
+
+- 인증 주체: `<사용자 또는 시스템>`
+- 허용 역할: `<role 목록>`
+- 거부 조건: `<401/403 또는 제품 정책>`
+- 리소스 소유권: `<tenant, characterId, ownerId 등 격리 기준>`
+- read-only 조건: `<비활성·권한 부족·외부 상태 등>`
+
+## 6. 핵심 사용자 흐름
+
+1. `<시작 조건과 진입점>`
+2. `<대상 탐색·선택>`
+3. `<핵심 생성·조회·수정 동작>`
+4. `<성공 feedback과 다음 화면>`
+5. `<오류·권한·session 만료 복구>`
+
+각 흐름은 `plan-task.md`의 최소 하나의 Phase 결과와 E2E 완료 증거로 연결한다.
+
+## 7. 정보 구조와 라우팅
+
+```text
+/<entry>
+/<resource>
+/<resource>/:resourceId
+  /<child-resource>
+```
+
+- 전역 화면과 선택된 리소스 문맥의 경계를 명시한다.
+- URL path와 query에 보존할 식별자·검색·filter·page 상태를 명시한다.
+- 직접 링크·새로고침이 가능한 화면과 collection modal/Sheet처럼 별도 route가 없는 화면을 구분한다.
+- 존재하지 않음, 다른 소유자, 비활성 리소스의 처리는 서버 계약과 공통 오류 정책을 따른다.
+
+## 8. 기능 요구사항
+
+요구사항 ID는 `<DOMAIN>-NNN` 형식을 사용한다. 하나의 행에는 독립적으로 판정 가능한 요구사항 하나만 작성한다.
+
+### 8.1 `<도메인 A>`
+
+| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
+|---|---|---|---|---|
+| `DOMAINA-001` | 확정 | `<사용자가 할 수 있어야 하는 동작>` | `<관찰 가능한 성공·오류 결과>` | `api-contract.md §<번호>`, `P1-T1` |
+| `DOMAINA-002` | 확정 | `<payload·상태·권한 불변식>` | `<보내야/보내지 말아야 할 값과 test>` | `P1-T2` |
+| `DOMAINA-003` | 외부 의존 | `<외부 제공이 필요한 계약>` | `<제공 전 network integration 0건>` | `EXT-001`, `P1-T1` |
+
+### 8.2 `<도메인 B>`
+
+| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
+|---|---|---|---|---|
+| `DOMAINB-001` | 확정 | `<목록·상세·mutation 흐름>` | `<loading·empty·error·success 포함>` | `api-contract.md §<번호>`, `P2-T2` |
+| `DOMAINB-002` | 미결 | `<제품 결정이 필요한 항목>` | `<확정 전 최대값·동작 추정 금지>` | `OQ-001` |
+
+### 8.3 공통 파일·데이터 정책
+
+| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
+|---|---|---|---|---|
+| `FILE-001` | 확정 | `<허용 확장자·MIME·크기>` | `<정확한 byte 경계 test>` | `api-contract.md §<번호>`, `<Goal ID>` |
+| `DATA-001` | 확정 | `<날짜·가격·enum·pagination 규칙>` | `<formatter/schema/contract test>` | `<Goal ID>` |
+
+## 9. 반응형 기능 범위
+
+| 기능 | Desktop | Tablet | Mobile | 비고 |
+|---|---:|---:|---:|---|
+| 조회 | 전체 | 전체 | 전체 | `<예외>` |
+| 생성·수정 | 허용 | 허용 | 허용 / 조회 전용 | `<직접 route 차단 정책>` |
+| 파일 upload | 허용 | 허용 | 허용 / 미지원 | `<이유>` |
+
+- 화면에서 action을 숨기는 것뿐 아니라 직접 route와 mutation capability도 같은 정책으로 차단한다.
+- 최소 viewport, zoom, touch target과 virtual keyboard 조건을 수용 기준에 연결한다.
+
+## 10. UI/UX Expectations
+
+### 10.1 디자인과 component 원칙
+
+- `<브랜드 token, theme 범위, typography>`
+- Page는 route·query·permission·component 조합을 담당한다.
+- 도메인 표시·입력·상호작용은 feature component가 담당한다.
+- 두 개 이상 Phase에서 같은 의미·동작으로 재사용할 때만 shared component로 올린다.
+
+### 10.2 화면 상태
+
+- 모든 비동기 화면에 loading·empty·error·success 상태를 정의한다.
+- mutation에는 진행 중·성공·실패·재시도·중복 제출 정책을 정의한다.
+- destructive action에는 대상·영향·복구 여부를 알리는 확인 절차를 둔다.
+
+### 10.3 접근성
+
+- 모든 input은 visible label과 연결된 오류를 가진다.
+- keyboard-only 흐름, focus 표시·복귀, skip link와 live region 기준을 명시한다.
+- 색상만으로 상태를 전달하지 않고 목표 대비와 touch target을 명시한다.
+- `<지원 viewport>`, 200% zoom과 axe critical·serious 0건을 수용 기준으로 사용한다.
+
+## 11. API 계약
+
+### 11.1 공통 규칙
+
+- base URL과 인증 header: `<값>`
+- locale: `<header와 값>`
+- 성공 envelope: `<type 또는 예시>`
+- 오류 envelope와 status: `<type 또는 예시>`
+- pagination: `<page/size/total/hasNext 규칙>`
+- multipart JSON part: `<이름>`
+
+### 11.2 Endpoint 추적
+
+| 요구사항 | Method | Path | 계약 상태 | API Contract | 소유 Goal |
+|---|---|---|---|---|---|
+| `DOMAINA-001` | `<METHOD>` | `<path>` | 제공됨 / 보정 필요 / 제공 대기 | `§<번호>` | `<Goal ID>` |
+
+### 11.3 외부 제공 대기 계약
+
+| ID | 우선순위 | 제공 필요 계약 | 담당 주체 | 구현 영향 | 재개 조건 |
+|---|---:|---|---|---|---|
+| `EXT-001` | P0 / P1 | `<endpoint·DTO·오류 규칙>` | `<팀/역할>` | `<차단되는 흐름>` | `<문서와 fixture 제공>` |
+
+- P0 계약이 없으면 영향을 받는 network flow를 완료로 표시하지 않는다.
+- 계약에 의존하지 않는 UI shell·상태 inventory·문서화는 독립적으로 진행할 수 있다.
+
+## 12. 보안과 데이터 취급
+
+- 인증 정보 저장 위치와 lifecycle: `<정확한 정책>`
+- log·분석·오류 리포트 금지 값: `<token, password, signed URL 등>`
+- 업로드 파일명·MIME·본문 취급: `<정책>`
+- 리소스 격리와 ownership 검증: `<정책>`
+- 401·403·동시 실패 처리: `<정책>`
+- 감사 로그: `<포함, 외부 의존 또는 후속 범위>`
+
+## 13. 성능과 품질 요구사항
+
+- 목록 pagination과 전체 로드 예외: `<정책>`
+- 검색 debounce와 기존 데이터 유지: `<정책>`
+- image layout shift와 lazy loading: `<정책>`
+- mutation 중복 제출·upload 취소/재시도: `<정책>`
+- 지원 runtime·browser: `<정확한 범위>`
+- test stack과 필수 Gate: `<unit/integration/E2E/typecheck/lint/build>`
+- backend 구현 전 UI 확인: `<불필요 또는 explicit mock mode, production 금지, no-auto-fallback, mock/server 완료 상태 분리>`
+
+## 14. 성공 기준
+
+### 14.1 기능 수용 기준
+
+- [ ] `<핵심 사용자 journey가 성공한다.>` (`DOMAINA-001`, `P1-GATE`)
+- [ ] `<권한·오류·payload 불변식이 검증된다.>` (`DOMAINA-002`, `<test>`)
+- [ ] `<외부 의존의 구현 또는 제외 결정이 문서화된다.>` (`EXT-001`)
+
+### 14.2 UI/UX 수용 기준
+
+- [ ] loading·empty·error·success 상태가 있다.
+- [ ] keyboard-only로 핵심 흐름을 완료한다.
+- [ ] `<최소 viewport>`와 200% zoom에서 핵심 control이 가려지지 않는다.
+- [ ] axe critical·serious 위반이 0건이다.
+
+### 14.3 추적성 완료 기준
+
+- [ ] 모든 `확정` 요구사항이 API Contract와 하나 이상의 Task/Goal 완료 증거로 연결된다.
+- [ ] 모든 `미결` 항목에 결정 주체와 다음 행동이 있다.
+- [ ] 모든 `외부 의존` 항목에 담당 주체·영향·재개 조건이 있다.
+- [ ] `제외` 항목에 Decision Log와 후속 조건이 있다.
+
+## 15. Open Questions
+
+| ID | 상태 | 결정 필요 사항 | 현재 권고 | 결정 주체 | 결정 기한/시점 | 영향 Goal |
+|---|---|---|---|---|---|---|
+| `OQ-001` | 미결 | `<질문>` | `<권고안 또는 없음>` | `<역할>` | `<날짜 또는 UI 작성 후>` | `<Goal ID>` |
+
+- Open Question과 외부 의존을 혼합하지 않는다. 제품이 결정할 수 없는 backend 계약은 `EXT-*`로 관리한다.
+- 미결 값을 임의의 상수·enum·endpoint로 구현하지 않는다.
+
+## 16. 요구사항 추적표
+
+| 요구사항 범위 | API Contract | 계획 Phase | Goal | 자동 검증 | 수동 검증 |
+|---|---|---:|---|---|---|
+| `DOMAINA-001~003` | `§<번호>` | 1 | `P1-T1`, `P1-T2`, `P1-GATE` | `<test 경로>` | `<흐름>` |
+| `DOMAINB-001~002` | `§<번호 또는 제공 대기>` | 2 | `P2-T1`, `P2-T2`, `P2-GATE` | `<test 경로>` | `<흐름>` |
+
+## 17. Decision Log
+
+| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·계약·Goal |
+|---|---|---|---|---|---|
+| `YYYY-MM-DD` | `DEC-001` | 확정 / 정정 / 폐기 | `<결정 내용>` | `<인터뷰·계약·검증 근거>` | `<ID와 문서 section>` |
+
+- 기존 결정을 수정할 때 원문을 지우지 않고 `정정` 행을 추가한다.
+- 범위 변경, Non-Goal 변경, 외부 의존 제외, 안전한 기본값과 주요 기술 선택을 기록한다.
+
+## 18. 변경 관리
+
+요구사항 변경 시 다음을 확인한다.
+
+- [ ] Decision Log에 변경 이유와 날짜를 기록했다.
+- [ ] 관련 요구사항 상태·본문·수용 기준을 갱신했다.
+- [ ] API Contract의 request/response/error와 fixture를 갱신했다.
+- [ ] `plan-task.md`의 범위·Files·Interfaces·체크박스·완료 증거를 코드 변경 전에 갱신했다.
+- [ ] 기존 Progress·review·검증 기록을 삭제하거나 덮어쓰지 않았다.