timsquad 3.6.0 → 3.7.0

package/templates/base/timsquad/ssot/prd/_template.md

@@ -0,0 +1,73 @@
+# [Feature Name] — Sub-PRD
+
+**Parent PRD**: [prd.md](../prd.md)
+**Created**: {{DATE}}
+**Status**: Draft
+
+---
+
+## 1. 기능 개요
+
+### 1.1 목적
+이 기능이 해결하는 문제:
+
+### 1.2 사용자 스토리
+> As a [사용자], I want [행동] so that [가치].
+
+---
+
+## 2. 요구사항
+
+### 2.1 Must Have (P0)
+| ID | 요건 | 성공 기준 |
+|----|------|----------|
+| | | |
+
+### 2.2 Should Have (P1)
+| ID | 요건 | 성공 기준 |
+|----|------|----------|
+| | | |
+
+### 2.3 Nice to Have (P2)
+| ID | 요건 |
+|----|------|
+| | |
+
+---
+
+## 3. 설계 결정
+
+| 결정 | 선택지 | 결정 사항 | 이유 |
+|------|--------|----------|------|
+| | | | |
+
+---
+
+## 4. Mapped Artifacts
+
+| Type | ID | Link |
+|------|----|------|
+| Requirement | FR-XXX-001~ | [requirements/xxx](../requirements/xxx.md) |
+| Functional Spec | FS-XXX | [functional-spec/FS-XXX](../functional-spec/FS-XXX.md) |
+| API Spec | xxx-api | [service-spec/xxx-api](../service-spec/xxx-api.md) |
+| Screen | SCR-XXX | [ui-ux-spec/SCR-XXX](../ui-ux-spec/SCR-XXX.md) |
+| Data | xxx tables | [data-design/xxx](../data-design/xxx.md) |
+| Tasks | P?-S???-T???~ | [planning.md](../planning.md) |
+
+---
+
+## 5. 수용 기준 (Acceptance Criteria)
+
+```gherkin
+Feature: [Feature Name]
+
+  Scenario: [Happy Path]
+    Given [전제 조건]
+    When [행동]
+    Then [결과]
+
+  Scenario: [Exception Path]
+    Given [전제 조건]
+    When [예외 행동]
+    Then [에러 처리]
+```

package/templates/base/timsquad/ssot/prd.template.md

@@ -1,7 +1,7 @@
-# {PROJECT_NAME} PRD
+# {{PROJECT_NAME}} PRD
 
 **Version**: 1.0
-**Created**: {DATE}
+**Created**: {{DATE}}
 **Author**:
 
 ---
@@ -38,22 +38,15 @@
 
 ---
 
-## 3. 핵심 기능
+## 3. 기능 인덱스
 
-### 3.1 Must Have (P0)
-| 기능 | 설명 | 성공 기준 |
-|-----|------|----------|
-| | | |
+> 각 기능의 상세는 `prd/` 하위 Sub-PRD에 기술합니다.
+> Level 1-2 프로젝트는 이 테이블에 직접 기술해도 됩니다.
 
-### 3.2 Should Have (P1)
-| 기능 | 설명 | 성공 기준 |
-|-----|------|----------|
-| | | |
-
-### 3.3 Nice to Have (P2)
-| 기능 | 설명 |
-|-----|------|
-| | |
+| Sub-PRD | 기능 | 우선순위 | 상태 | Link |
+|---------|------|:--------:|:----:|------|
+| auth | 인증/인가 | P0 | 🔲 | [prd/auth](./prd/auth.md) |
+| | | | | |
 
 ---
 
@@ -91,12 +84,8 @@
 
 ---
 
-## 7. 참고
-
-### 7.1 관련 문서
--
+## 7. 용어 정의
 
-### 7.2 용어 정의
 | 용어 | 정의 |
 |-----|------|
 | | |

package/templates/base/timsquad/ssot/requirements.template.md

@@ -1,7 +1,7 @@
-# {PROJECT_NAME} 요건 정의서
+# {{PROJECT_NAME}} 요건 정의서
 
 **Version**: 1.0
-**Created**: {DATE}
+**Created**: {{DATE}}
 **PRD Reference**: [prd.md](./prd.md)
 
 ---
@@ -114,4 +114,4 @@
 
 | 버전 | 날짜 | 변경 내용 | 작성자 |
 |-----|-----|----------|-------|
-| 1.0 | {DATE} | 최초 작성 | |
+| 1.0 | {{DATE}} | 최초 작성 | |

package/templates/base/timsquad/ssot/sdk-spec.template.md

@@ -0,0 +1,223 @@
+---
+title: "SDK 명세서 (SDK Specification)"
+version: 1.0.0
+last_updated: {{DATE}}
+author: tsq-architect
+status: draft
+project: {{PROJECT_NAME}}
+---
+
+# SDK 명세서 (SDK Specification)
+
+> 외부 개발자가 사용하는 SDK/라이브러리의 공개 API, 사용법, 버전 정책을 정의합니다.
+> 플랫폼/프레임워크 프로젝트에서 사용자 경험의 핵심 문서입니다.
+
+---
+
+## 1. 개요
+
+### 1.1 SDK 정보
+
+| 항목 | 값 |
+|-----|-----|
+| 패키지명 | `@{{PROJECT_NAME}}/sdk` |
+| 버전 | 1.0.0 |
+| 지원 런타임 | Node.js 18+, Browser (ESM) |
+| 번들 크기 | < 50KB (gzip) |
+| 라이선스 | MIT |
+
+### 1.2 설치
+
+```bash
+npm install @{{PROJECT_NAME}}/sdk
+# or
+yarn add @{{PROJECT_NAME}}/sdk
+```
+
+### 1.3 빠른 시작
+
+```typescript
+import { Client } from '@{{PROJECT_NAME}}/sdk';
+
+const client = new Client({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.example.com',
+});
+
+const result = await client.resource.list({ limit: 10 });
+console.log(result.data);
+```
+
+---
+
+## 2. 공개 API
+
+### 2.1 Client
+
+| 메서드 | 시그니처 | 설명 |
+|-------|---------|------|
+| `constructor` | `new Client(options: ClientOptions)` | 클라이언트 초기화 |
+
+```typescript
+interface ClientOptions {
+  apiKey: string;
+  baseUrl?: string;          // default: 프로덕션 URL
+  timeout?: number;          // default: 30000 (ms)
+  retries?: number;          // default: 3
+  onError?: (error: SDKError) => void;
+}
+```
+
+### 2.2 [Resource Name]
+
+| 메서드 | 시그니처 | 설명 |
+|-------|---------|------|
+| `list` | `list(params?: ListParams): Promise<PaginatedResponse<T>>` | 목록 조회 |
+| `get` | `get(id: string): Promise<T>` | 단건 조회 |
+| `create` | `create(data: CreateInput): Promise<T>` | 생성 |
+| `update` | `update(id: string, data: UpdateInput): Promise<T>` | 수정 |
+| `delete` | `delete(id: string): Promise<void>` | 삭제 |
+
+#### 사용 예시
+
+```typescript
+// 목록 조회 (페이지네이션)
+const items = await client.resource.list({
+  page: 1,
+  limit: 20,
+  sort: 'createdAt',
+  order: 'desc',
+});
+
+// 단건 조회
+const item = await client.resource.get('item_123');
+
+// 생성
+const newItem = await client.resource.create({
+  name: 'New Item',
+  description: 'Description',
+});
+
+// 수정
+const updated = await client.resource.update('item_123', {
+  name: 'Updated Name',
+});
+
+// 삭제
+await client.resource.delete('item_123');
+```
+
+---
+
+## 3. 타입 정의
+
+### 3.1 공통 타입
+
+```typescript
+interface PaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+}
+
+interface SDKError {
+  code: string;
+  message: string;
+  status: number;
+  details?: Record<string, unknown>;
+}
+```
+
+### 3.2 리소스 타입
+
+```typescript
+interface Resource {
+  id: string;
+  name: string;
+  description: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface CreateResourceInput {
+  name: string;
+  description?: string;
+}
+
+interface UpdateResourceInput {
+  name?: string;
+  description?: string;
+}
+```
+
+---
+
+## 4. 에러 처리
+
+### 4.1 에러 코드
+
+| 코드 | HTTP | 설명 | 대응 |
+|-----|:----:|------|------|
+| `UNAUTHORIZED` | 401 | API 키 무효 | 키 확인 |
+| `FORBIDDEN` | 403 | 권한 없음 | 권한 확인 |
+| `NOT_FOUND` | 404 | 리소스 없음 | ID 확인 |
+| `RATE_LIMITED` | 429 | 요청 제한 초과 | 재시도 (자동) |
+| `SERVER_ERROR` | 500 | 서버 오류 | 재시도 (자동) |
+
+### 4.2 에러 핸들링
+
+```typescript
+import { SDKError } from '@{{PROJECT_NAME}}/sdk';
+
+try {
+  const item = await client.resource.get('invalid_id');
+} catch (error) {
+  if (error instanceof SDKError) {
+    console.error(`[${error.code}] ${error.message}`);
+    // RATE_LIMITED인 경우 자동 재시도됨
+  }
+}
+```
+
+---
+
+## 5. 버전 정책
+
+### 5.1 Semantic Versioning
+
+| 변경 유형 | 버전 | 예시 |
+|---------|------|------|
+| Breaking change | Major (X.0.0) | 메서드 시그니처 변경 |
+| 새 기능 | Minor (0.X.0) | 새 리소스 추가 |
+| 버그 수정 | Patch (0.0.X) | 에러 수정 |
+
+### 5.2 지원 정책
+
+| 버전 | 상태 | 지원 종료 |
+|-----|:----:|----------|
+| v1.x | Active | - |
+| v0.x | Deprecated | v1 출시 후 6개월 |
+
+### 5.3 마이그레이션 가이드
+
+Breaking change 시 마이그레이션 가이드를 `MIGRATION.md`에 제공합니다.
+
+---
+
+## 6. 관련 문서
+
+- [서비스 명세](./service-spec.md) — 내부 API 상세
+- [연동 명세](./integration-spec.md) — 외부 서비스 연동
+- [에러 코드](./error-codes.md) — 전체 에러 코드
+
+---
+
+## 변경 이력
+
+| 버전 | 날짜 | 작성자 | 변경 내용 |
+|------|------|--------|----------|
+| 1.0.0 | {{DATE}} | tsq-architect | 초기 작성 |

package/templates/base/timsquad/ssot/service-spec.template.md

@@ -1,7 +1,7 @@
-# {PROJECT_NAME} 서비스 명세서
+# {{PROJECT_NAME}} 서비스 명세서
 
 **Version**: 1.0
-**Created**: {DATE}
+**Created**: {{DATE}}
 **Base URL**: `https://api.example.com/v1`
 
 ---
@@ -191,4 +191,4 @@
 
 | 버전 | 날짜 | 변경 내용 | 작성자 |
 |-----|-----|----------|-------|
-| 1.0 | {DATE} | 최초 작성 | |
+| 1.0 | {{DATE}} | 최초 작성 | |

package/templates/base/timsquad/ssot/state-machine.template.md

@@ -0,0 +1,127 @@
+---
+title: "상태 머신 명세서 (State Machine Specification)"
+version: 1.0.0
+last_updated: {{DATE}}
+author: tsq-architect
+status: draft
+project: {{PROJECT_NAME}}
+---
+
+# 상태 머신 명세서 (State Machine Specification)
+
+> 시스템 내 주요 엔티티의 상태 전이(State Transition)를 정의합니다.
+> 상태 전이 규칙, 가드 조건, 부수 효과를 명확히 하여 일관된 비즈니스 로직을 보장합니다.
+
+---
+
+## 1. 개요
+
+### 1.1 적용 대상
+
+| 엔티티 | 상태 수 | 설명 |
+|-------|:------:|------|
+| Order | 6 | 주문 생명주기 |
+| Payment | 5 | 결제 처리 흐름 |
+| User | 4 | 사용자 계정 상태 |
+
+### 1.2 용어
+
+| 용어 | 설명 |
+|-----|------|
+| State | 엔티티가 가질 수 있는 상태 값 |
+| Transition | 한 상태에서 다른 상태로의 전이 |
+| Guard | 전이가 허용되는 조건 (사전 검증) |
+| Action | 전이 시 실행되는 부수 효과 |
+| Event | 전이를 트리거하는 외부/내부 이벤트 |
+
+---
+
+## 2. [Entity Name] 상태 머신
+
+### 2.1 상태 다이어그램
+
+```
+                    ┌──────────┐
+          ┌─────── │  CREATED  │ ───────┐
+          │        └──────────┘        │
+          │ cancel       │ confirm     │ expire
+          ▼              ▼             ▼
+   ┌──────────┐   ┌──────────┐  ┌──────────┐
+   │ CANCELLED│   │ CONFIRMED│  │ EXPIRED  │
+   └──────────┘   └─────┬────┘  └──────────┘
+                        │ process
+                        ▼
+                  ┌──────────┐
+                  │ COMPLETED│
+                  └──────────┘
+```
+
+### 2.2 상태 정의
+
+| 상태 | 코드 | 설명 | 진입 조건 |
+|-----|------|------|----------|
+| CREATED | `created` | 초기 생성 상태 | 생성 시 자동 |
+| CONFIRMED | `confirmed` | 확인됨 | 검증 통과 |
+| COMPLETED | `completed` | 처리 완료 | 모든 작업 완료 |
+| CANCELLED | `cancelled` | 취소됨 | 사용자/시스템 취소 |
+| EXPIRED | `expired` | 만료됨 | TTL 초과 |
+
+### 2.3 전이 규칙
+
+| From | Event | To | Guard | Action |
+|------|-------|----|-------|--------|
+| CREATED | `confirm` | CONFIRMED | 필수 필드 충족 | 알림 발송 |
+| CREATED | `cancel` | CANCELLED | - | 관련 리소스 해제 |
+| CREATED | `expire` | EXPIRED | TTL 초과 | 정리 작업 |
+| CONFIRMED | `process` | COMPLETED | 처리 조건 충족 | 완료 알림 |
+| CONFIRMED | `cancel` | CANCELLED | 취소 가능 기간 | 환불 처리 |
+
+### 2.4 가드 조건 상세
+
+| Guard | 로직 | 실패 시 |
+|-------|------|--------|
+| 필수 필드 충족 | `entity.requiredFields.every(f => !!f)` | 400 Bad Request |
+| TTL 초과 | `now - entity.createdAt > TTL` | 스케줄러가 자동 전이 |
+| 취소 가능 기간 | `now - entity.confirmedAt < CANCEL_WINDOW` | 409 Conflict |
+
+### 2.5 부수 효과
+
+| Action | 트리거 | 처리 | 실패 전략 |
+|--------|-------|------|----------|
+| 알림 발송 | confirm → CONFIRMED | 이메일/푸시 | 재시도 (3회) |
+| 환불 처리 | cancel → CANCELLED | 결제 API 호출 | 수동 처리 큐 |
+| 정리 작업 | expire → EXPIRED | 관련 데이터 정리 | 로그 + 재시도 |
+
+---
+
+## 3. 상태 전이 정합성
+
+### 3.1 불변 규칙 (Invariants)
+
+- [ ] 터미널 상태(COMPLETED, CANCELLED, EXPIRED)에서 다른 상태로 전이 불가
+- [ ] 모든 전이는 감사 로그에 기록
+- [ ] 동시 전이 충돌 시 낙관적 잠금(Optimistic Locking) 적용
+
+### 3.2 동시성 처리
+
+| 시나리오 | 해결 방법 |
+|---------|----------|
+| 동시 상태 변경 | 버전 기반 낙관적 잠금 |
+| 이벤트 순서 역전 | 타임스탬프 검증 |
+| 중복 이벤트 | 멱등성 키(idempotency key) |
+
+---
+
+## 4. 관련 문서
+
+- [서비스 명세](./service-spec.md) — API 엔드포인트별 상태 변경
+- [에러 코드](./error-codes.md) — 상태 전이 실패 에러 코드
+- [데이터 설계](./data-design.md) — 상태 필드 스키마
+
+---
+
+## 변경 이력
+
+| 버전 | 날짜 | 작성자 | 변경 내용 |
+|------|------|--------|----------|
+| 1.0.0 | {{DATE}} | tsq-architect | 초기 작성 |

package/templates/base/timsquad/ssot/ui-ux-spec.template.md

@@ -2,7 +2,7 @@
 title: "UI/UX 명세서"
 version: 1.0.0
 last_updated: {{DATE}}
-author: tsq-planner
+author: tsq-architect
 status: draft
 project: {{PROJECT_NAME}}
 ---
@@ -151,7 +151,47 @@ project: {{PROJECT_NAME}}
 
 ### SCR-002: [화면명]
 
-(위와 동일한 형식으로 작성)
+#### 3.2.1 개요
+
+| 항목 | 내용 |
+|-----|------|
+| **ID** | SCR-002 |
+| **화면명** | |
+| **경로** | |
+| **관련 기능** | [FS-002](./functional-spec.md#FS-002) |
+
+#### 3.2.2 와이어프레임
+
+```
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│              [와이어프레임 작성]                 │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+#### 3.2.3 UI 요소
+
+| 요소 | 타입 | 설명 | 필수 |
+|-----|------|------|:----:|
+| | | | |
+
+#### 3.2.4 상태별 UI
+
+| 상태 | 설명 | UI 변화 |
+|-----|------|--------|
+| 기본 | | |
+| 로딩 | | |
+| 에러 | | |
+| 성공 | | |
+
+#### 3.2.5 반응형
+
+| 브레이크포인트 | 레이아웃 변경 |
+|--------------|-------------|
+| Desktop (≥1024px) | |
+| Tablet (768-1023px) | |
+| Mobile (<768px) | |
 
 ---
 
@@ -259,4 +299,4 @@ graph LR
 
 | 버전 | 날짜 | 작성자 | 변경 내용 |
 |------|------|--------|----------|
-| 1.0.0 | {{DATE}} | tsq-planner | 초기 작성 |
+| 1.0.0 | {{DATE}} | tsq-architect | 초기 작성 |

package/templates/base/timsquad/ssot-map.template.yaml

@@ -3,6 +3,7 @@
 # Tier 1: Phase 시작 시 Controller가 주입
 # Tier 2: Sequence 범위 문서 (Controller가 선택 주입)
 # Tier 3: 개별 Task에 필요한 구체 spec (Controller가 선택 주입)
+# optional: true → 타입별 선택 배포 문서 (미존재 시 건너뜀)
 
 tier-0-always:
   description: "모든 작업에 항상 주입되는 제약 문서"
@@ -21,6 +22,12 @@ tier-1-phase:
       source: prd.md
     - compiled: references/architecture.spec.md
       source: planning.md
+    - compiled: references/compliance-matrix.spec.md
+      source: compliance-matrix.md
+      optional: true
+    - compiled: references/infra-topology.spec.md
+      source: infra-topology.md
+      optional: true
 
 tier-2-sequence:
   description: "Sequence 범위의 기능별 문서"
@@ -30,6 +37,21 @@ tier-2-sequence:
       source: service-spec.md
     - compiled: references/data-design.spec.md
       source: data-design.md
+    - compiled: references/state-machine.spec.md
+      source: state-machine.md
+      optional: true
+    - compiled: references/performance-budget.spec.md
+      source: performance-budget.md
+      optional: true
+    - compiled: references/component-map.spec.md
+      source: component-map.md
+      optional: true
+    - compiled: references/navigation-map.spec.md
+      source: navigation-map.md
+      optional: true
+    - compiled: references/monitoring-spec.spec.md
+      source: monitoring-spec.md
+      optional: true
 
 tier-3-task:
   description: "개별 Task에 필요한 구체 spec"
@@ -39,3 +61,9 @@ tier-3-task:
       source: error-codes.md
     - compiled: references/functional.spec.md
       source: functional-spec.md
+    - compiled: references/sdk-spec.spec.md
+      source: sdk-spec.md
+      optional: true
+    - compiled: references/audit-trail-spec.spec.md
+      source: audit-trail-spec.md
+      optional: true