timsquad 3.5.0 → 3.7.0

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

@@ -0,0 +1,185 @@
+---
+title: "모니터링 명세서 (Monitoring Specification)"
+version: 1.0.0
+last_updated: {{DATE}}
+author: tsq-architect
+status: draft
+project: {{PROJECT_NAME}}
+---
+
+# 모니터링 명세서 (Monitoring Specification)
+
+> 시스템 관찰 가능성(Observability)을 위한 메트릭, 로그, 트레이스, 알림 정책을 정의합니다.
+> SLI/SLO 기반으로 서비스 신뢰성을 측정하고 관리합니다.
+
+---
+
+## 1. SLI / SLO
+
+### 1.1 서비스 수준 지표 (SLI)
+
+| SLI | 측정 방법 | 계산식 |
+|-----|---------|--------|
+| 가용성 | HTTP 상태 코드 | 성공 응답(2xx) / 전체 요청 |
+| 지연 시간 | 응답 시간 P95 | 전체 요청의 95번째 백분위 |
+| 처리량 | 초당 요청 수 | 1분 윈도우 평균 |
+| 에러율 | 서버 에러 비율 | 5xx / 전체 요청 |
+
+### 1.2 서비스 수준 목표 (SLO)
+
+| SLO | 목표 | 에러 버짓 (월) | 측정 기간 |
+|-----|:----:|:----------:|----------|
+| 가용성 | 99.9% | 43.2분 | 30일 |
+| 지연 시간 (P95) | < 500ms | - | 30일 |
+| 에러율 | < 0.1% | - | 30일 |
+
+---
+
+## 2. 메트릭
+
+### 2.1 인프라 메트릭
+
+| 메트릭 | 소스 | 알림 임계값 | 수집 주기 |
+|-------|------|-----------|----------|
+| CPU 사용률 | 호스트/컨테이너 | > 80% (5분) | 10초 |
+| 메모리 사용률 | 호스트/컨테이너 | > 85% (5분) | 10초 |
+| 디스크 사용률 | 호스트 | > 90% | 1분 |
+| 네트워크 I/O | 호스트 | 이상치 감지 | 10초 |
+
+### 2.2 애플리케이션 메트릭
+
+| 메트릭 | 타입 | 레이블 | 설명 |
+|-------|------|-------|------|
+| `http_requests_total` | Counter | method, path, status | 총 HTTP 요청 수 |
+| `http_request_duration_seconds` | Histogram | method, path | 요청 처리 시간 |
+| `db_query_duration_seconds` | Histogram | query_type | DB 쿼리 시간 |
+| `active_connections` | Gauge | type | 활성 연결 수 |
+| `queue_depth` | Gauge | queue_name | 큐 대기 건수 |
+| `cache_hit_ratio` | Gauge | cache_name | 캐시 적중률 |
+
+### 2.3 비즈니스 메트릭
+
+| 메트릭 | 설명 | 알림 조건 |
+|-------|------|----------|
+| 회원가입 수 | 일간 신규 가입 | 전일 대비 50% 감소 |
+| 주문 성공률 | 주문 완료 / 주문 시도 | < 95% |
+| 결제 실패율 | 결제 실패 / 결제 시도 | > 5% |
+
+---
+
+## 3. 로깅
+
+### 3.1 로그 레벨 정책
+
+| 레벨 | 용도 | 프로덕션 | 보존 |
+|-----|------|:-------:|------|
+| ERROR | 시스템 오류, 예외 | ✅ | 90일 |
+| WARN | 비정상 동작, 재시도 | ✅ | 30일 |
+| INFO | 주요 비즈니스 이벤트 | ✅ | 30일 |
+| DEBUG | 디버깅용 상세 정보 | ❌ | 7일 |
+
+### 3.2 구조화 로그 포맷
+
+```json
+{
+  "timestamp": "2026-01-01T00:00:00.000Z",
+  "level": "INFO",
+  "service": "{{PROJECT_NAME}}",
+  "trace_id": "abc123",
+  "span_id": "def456",
+  "message": "Order created",
+  "context": {
+    "user_id": "user_123",
+    "order_id": "order_456"
+  }
+}
+```
+
+### 3.3 민감 데이터 필터링
+
+| 필드 | 처리 |
+|-----|------|
+| password | 로그 제외 |
+| token | 마스킹 (`***`) |
+| email | 부분 마스킹 |
+| IP | 허용 (감사 목적) |
+
+---
+
+## 4. 분산 트레이싱
+
+### 4.1 트레이스 전파
+
+| 항목 | 설정 |
+|-----|------|
+| 프로토콜 | W3C Trace Context |
+| 헤더 | `traceparent`, `tracestate` |
+| 샘플링 | 1% (프로덕션), 100% (에러) |
+
+### 4.2 스팬 구조
+
+```
+[HTTP Request] ──► [Auth Middleware] ──► [Business Logic] ──► [DB Query]
+                                                           ──► [External API]
+                                                           ──► [Cache]
+```
+
+---
+
+## 5. 알림
+
+### 5.1 알림 정책
+
+| 심각도 | 조건 | 채널 | 응답 시간 |
+|-------|------|------|----------|
+| P1 (Critical) | 서비스 다운, 데이터 손실 | PagerDuty + Slack | 15분 |
+| P2 (High) | 성능 저하, 에러율 상승 | Slack #alerts | 1시간 |
+| P3 (Medium) | 임계값 근접 | Slack #monitoring | 4시간 |
+| P4 (Low) | 비정상 패턴 감지 | 이메일 리포트 | 다음 영업일 |
+
+### 5.2 알림 규칙
+
+| 규칙 | 조건 | 심각도 |
+|-----|------|--------|
+| 서비스 다운 | health check 3회 연속 실패 | P1 |
+| 높은 에러율 | 5xx > 5% (5분) | P1 |
+| 느린 응답 | P95 > 2s (5분) | P2 |
+| 디스크 부족 | 사용률 > 90% | P2 |
+| 에러 버짓 소진 | SLO 에러 버짓 > 80% | P3 |
+
+### 5.3 온콜 체계
+
+| 항목 | 설정 |
+|-----|------|
+| 로테이션 | 주간 교대 |
+| 에스컬레이션 | 15분 미응답 → 다음 담당자 |
+| 사후 분석 | P1/P2 인시던트 필수 |
+
+---
+
+## 6. 대시보드
+
+### 6.1 대시보드 구성
+
+| 대시보드 | 대상 | 주요 패널 |
+|---------|------|----------|
+| Overview | 전체 팀 | SLI/SLO, 에러율, 트래픽 |
+| Infrastructure | DevOps | CPU, 메모리, 디스크, 네트워크 |
+| Application | 개발팀 | 응답 시간, 에러, 쿼리 성능 |
+| Business | PM/리더 | KPI, 전환율, 사용자 수 |
+
+---
+
+## 7. 관련 문서
+
+- [배포 명세](./deployment-spec.md) — 인프라 리소스
+- [성능 예산](./performance-budget.md) — 성능 임계값
+- [보안 명세](./security-spec.md) — 감사 로그
+
+---
+
+## 변경 이력
+
+| 버전 | 날짜 | 작성자 | 변경 내용 |
+|------|------|--------|----------|
+| 1.0.0 | {{DATE}} | tsq-architect | 초기 작성 |

package/templates/base/timsquad/ssot/navigation-map.template.md

@@ -0,0 +1,154 @@
+---
+title: "네비게이션 맵 (Navigation Map)"
+version: 1.0.0
+last_updated: {{DATE}}
+author: tsq-designer
+status: draft
+project: {{PROJECT_NAME}}
+---
+
+# 네비게이션 맵 (Navigation Map)
+
+> 앱/웹의 화면 구조와 네비게이션 흐름을 정의합니다.
+> 라우트 구조, 화면 간 전환, 딥링크를 일목요연하게 관리합니다.
+
+---
+
+## 1. 네비게이션 구조
+
+### 1.1 전체 구조
+
+```
+App
+├── Auth Routes (비인증)
+│   ├── /welcome
+│   ├── /login
+│   ├── /register
+│   └── /forgot-password
+│
+├── Main Routes (인증됨)
+│   ├── / (Home)
+│   │   ├── /items/:id (Detail)
+│   │   └── /search (Search)
+│   ├── /explore
+│   │   └── /explore/:category
+│   ├── /notifications
+│   └── /profile
+│       ├── /profile/settings
+│       └── /profile/edit
+│
+└── Overlays (모달/다이얼로그)
+    ├── FilterModal
+    ├── ShareModal
+    └── AlertDialog
+
+> 모바일 앱: Tab Navigator, Stack Navigator 구조로 매핑
+> 웹 SPA: React Router, Next.js App Router 등에 매핑
+```
+
+### 1.2 네비게이터 타입
+
+| 네비게이터 | 타입 | 설명 |
+|---------|------|------|
+| RootNavigator | Stack | 인증 상태에 따라 Auth/Main 분기 |
+| AuthStack | Stack | 로그인/회원가입 흐름 |
+| MainTab | Bottom Tab | 메인 4개 탭 |
+| HomeStack | Stack | Home 탭 내부 화면 |
+| ModalStack | Modal | 오버레이 화면 |
+
+---
+
+## 2. 화면 목록
+
+| 화면 ID | 화면명 | 네비게이터 | 인증 필요 | 딥링크 |
+|---------|-------|----------|:--------:|-------|
+| `welcome` | 웰컴 | Auth | ❌ | - |
+| `login` | 로그인 | Auth | ❌ | `/login` |
+| `register` | 회원가입 | Auth | ❌ | `/register` |
+| `home` | 홈 | MainTab > Home | ✅ | `/home` |
+| `detail` | 상세 | MainTab > Home | ✅ | `/items/:id` |
+| `search` | 검색 | MainTab > Home | ✅ | `/search` |
+| `explore` | 탐색 | MainTab > Explore | ✅ | `/explore` |
+| `category` | 카테고리 | MainTab > Explore | ✅ | `/category/:id` |
+| `notifications` | 알림 | MainTab > Notifications | ✅ | `/notifications` |
+| `profile` | 프로필 | MainTab > Profile | ✅ | `/profile` |
+| `settings` | 설정 | MainTab > Profile | ✅ | `/settings` |
+
+---
+
+## 3. 화면 전환 규칙
+
+### 3.1 전환 매트릭스
+
+| From | To | 방식 | 조건 |
+|------|----|------|------|
+| Welcome | Login | push | 버튼 탭 |
+| Welcome | Register | push | 버튼 탭 |
+| Login | Home | replace (root) | 로그인 성공 |
+| Home | Detail | push | 아이템 탭 |
+| Detail | ShareModal | modal | 공유 버튼 |
+| Any | Login | replace (root) | 토큰 만료 |
+
+### 3.2 전환 애니메이션
+
+| 전환 유형 | 애니메이션 | 플랫폼 |
+|---------|----------|--------|
+| Stack push | slide-from-right | iOS/Android |
+| Stack pop | slide-to-right | iOS/Android |
+| Tab switch | none (instant) | 공통 |
+| Modal present | slide-from-bottom | 공통 |
+| Modal dismiss | slide-to-bottom | 공통 |
+
+---
+
+## 4. 딥링크
+
+### 4.1 URL 스킴
+
+| 스킴 | 용도 | 예시 |
+|-----|------|------|
+| `{{PROJECT_NAME}}://` | 앱 스킴 | `{{PROJECT_NAME}}://items/123` |
+| `https://example.com` | 유니버설 링크 | `https://example.com/items/123` |
+
+### 4.2 딥링크 라우팅
+
+| 패턴 | 화면 | 파라미터 |
+|-----|------|---------|
+| `/items/:id` | DetailScreen | `id: string` |
+| `/category/:id` | CategoryScreen | `id: string` |
+| `/search?q=:query` | SearchScreen | `q: string` |
+| `/notifications` | NotificationListScreen | - |
+| `/profile` | ProfileScreen | - |
+
+### 4.3 딥링크 미인증 처리
+
+```
+딥링크 수신 → 인증 확인 → 미인증 → 로그인 → 원래 딥링크로 리다이렉트
+```
+
+---
+
+## 5. 탭 바 설정
+
+| 탭 | 아이콘 | 라벨 | 뱃지 |
+|---|-------|------|:----:|
+| Home | `home` | 홈 | - |
+| Explore | `compass` | 탐색 | - |
+| Notifications | `bell` | 알림 | 미읽은 수 |
+| Profile | `user` | 프로필 | - |
+
+---
+
+## 6. 관련 문서
+
+- [UI/UX 명세](./ui-ux-spec.md) — 화면 상세 디자인
+- [서비스 명세](./service-spec.md) — API 엔드포인트
+- [컴포넌트 맵](./component-map.md) — 공유 컴포넌트
+
+---
+
+## 변경 이력
+
+| 버전 | 날짜 | 작성자 | 변경 내용 |
+|------|------|--------|----------|
+| 1.0.0 | {{DATE}} | tsq-designer | 초기 작성 |

package/templates/base/timsquad/ssot/performance-budget.template.md

@@ -0,0 +1,132 @@
+---
+title: "성능 예산 명세서 (Performance Budget)"
+version: 1.0.0
+last_updated: {{DATE}}
+author: tsq-architect
+status: draft
+project: {{PROJECT_NAME}}
+---
+
+# 성능 예산 명세서 (Performance Budget)
+
+> 서비스의 성능 목표, 측정 기준, 허용 임계값을 정의합니다.
+> 모든 성능 관련 의사결정의 기준점(baseline)으로 사용됩니다.
+
+---
+
+## 1. 성능 목표
+
+### 1.1 Core Web Vitals
+
+| 메트릭 | 설명 | 목표 (Good) | 허용 (Needs Improvement) | 불가 (Poor) |
+|-------|------|:-----------:|:----------------------:|:-----------:|
+| LCP | Largest Contentful Paint | < 2.5s | < 4.0s | > 4.0s |
+| INP | Interaction to Next Paint | < 200ms | < 500ms | > 500ms |
+| CLS | Cumulative Layout Shift | < 0.1 | < 0.25 | > 0.25 |
+
+### 1.2 서버 성능
+
+| 메트릭 | 목표 | 임계값 | 측정 방법 |
+|-------|------|--------|----------|
+| TTFB | < 200ms | < 600ms | P95 기준 |
+| API 응답 시간 | < 100ms | < 500ms | P95 기준 |
+| DB 쿼리 시간 | < 50ms | < 200ms | P99 기준 |
+| Throughput | > 1000 RPS | > 500 RPS | 피크 시간대 |
+
+### 1.3 리소스 예산
+
+| 리소스 | 예산 | 현재 | 비고 |
+|-------|:----:|:----:|------|
+| JS 번들 (gzip) | < 200KB | - | 초기 로드 |
+| CSS (gzip) | < 50KB | - | 초기 로드 |
+| 이미지 (페이지당) | < 500KB | - | 최적화 후 |
+| 폰트 | < 100KB | - | woff2 |
+| 전체 페이지 | < 1MB | - | 초기 로드 합계 |
+
+---
+
+## 2. 페이지별 예산
+
+| 페이지 | LCP 목표 | JS 예산 | 이미지 예산 |
+|-------|:--------:|:------:|:---------:|
+| 랜딩 | < 1.5s | < 100KB | < 300KB |
+| 대시보드 | < 2.5s | < 200KB | < 200KB |
+| 상세 페이지 | < 2.0s | < 150KB | < 500KB |
+| 검색 결과 | < 2.0s | < 150KB | < 400KB |
+
+---
+
+## 3. API 성능 예산
+
+### 3.1 엔드포인트별 목표
+
+| 엔드포인트 | P50 | P95 | P99 | 비고 |
+|-----------|:---:|:---:|:---:|------|
+| `GET /api/health` | 5ms | 10ms | 50ms | 모니터링용 |
+| `POST /api/auth/login` | 50ms | 200ms | 500ms | bcrypt 포함 |
+| `GET /api/items` | 30ms | 100ms | 300ms | 페이지네이션 |
+| `GET /api/items/:id` | 10ms | 50ms | 150ms | 단건 조회 |
+
+### 3.2 데이터베이스
+
+| 쿼리 유형 | P50 | P95 | 최대 허용 |
+|---------|:---:|:---:|:--------:|
+| 단순 조회 (PK) | 1ms | 5ms | 20ms |
+| 인덱스 조회 | 5ms | 20ms | 100ms |
+| 집계 쿼리 | 20ms | 100ms | 500ms |
+| 풀 스캔 | 금지 | 금지 | 금지 |
+
+---
+
+## 4. 측정 및 모니터링
+
+### 4.1 측정 도구
+
+| 도구 | 용도 | 주기 |
+|-----|------|------|
+| Lighthouse CI | 빌드 시 성능 검증 | PR마다 |
+| Web Vitals (RUM) | 실제 사용자 측정 | 실시간 |
+| k6 / Artillery | 부하 테스트 | 릴리스 전 |
+| APM (선택) | 서버 트레이싱 | 실시간 |
+
+### 4.2 예산 위반 대응
+
+| 위반 수준 | 대응 | 담당 |
+|---------|------|------|
+| Warning (90%) | Slack 알림 | 자동 |
+| Error (100%) | PR 블로킹 | CI |
+| Critical (150%) | 핫픽스 | 개발팀 |
+
+---
+
+## 5. 최적화 전략
+
+### 5.1 프론트엔드
+
+- [ ] 코드 스플리팅 (라우트 기반)
+- [ ] 이미지 최적화 (WebP/AVIF, lazy loading)
+- [ ] 폰트 최적화 (subset, display: swap)
+- [ ] 프리로드/프리페치 전략
+
+### 5.2 백엔드
+
+- [ ] 쿼리 최적화 (인덱스, 페이지네이션)
+- [ ] 캐싱 전략 (Redis, HTTP Cache)
+- [ ] Connection pooling
+- [ ] N+1 쿼리 방지
+
+---
+
+## 6. 관련 문서
+
+- [서비스 명세](./service-spec.md) — API 엔드포인트
+- [배포 명세](./deployment-spec.md) — 인프라 스케일링
+- [모니터링 명세](./monitoring-spec.md) — 메트릭 수집
+
+---
+
+## 변경 이력
+
+| 버전 | 날짜 | 작성자 | 변경 내용 |
+|------|------|--------|----------|
+| 1.0.0 | {{DATE}} | tsq-architect | 초기 작성 |

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

@@ -1,7 +1,7 @@
-# {PROJECT_NAME} 기획서
+# {{PROJECT_NAME}} 기획서
 
 **Version**: 1.0
-**Created**: {DATE}
+**Created**: {{DATE}}
 **PRD Reference**: [prd.md](./prd.md)
 
 ---
@@ -91,4 +91,4 @@ PRD에서 정의한 목표를 달성하기 위한 실행 계획.
 
 | 버전 | 날짜 | 변경 내용 | 작성자 |
 |-----|-----|----------|-------|
-| 1.0 | {DATE} | 최초 작성 | |
+| 1.0 | {{DATE}} | 최초 작성 | |

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}} | 최초 작성 | |