timsquad 2.0.0

package/templates/common/timsquad/ssot/integration-spec.template.md

@@ -0,0 +1,391 @@
+---
+title: "외부 연동 명세서 (Integration Specification)"
+version: 1.0.0
+last_updated: {{DATE}}
+author: tsq-planner
+status: draft
+project: {{PROJECT_NAME}}
+required_level: 3
+---
+
+# 외부 연동 명세서 (Integration Specification)
+
+> 외부 API, 서드파티 서비스, Webhook 연동을 정의합니다.
+> Level 3 (Enterprise) 또는 platform 타입 프로젝트 필수 문서입니다.
+
+---
+
+## 1. 연동 개요
+
+### 1.1 연동 서비스 목록
+
+| 서비스 | 용도 | 제공사 | 우선순위 | 상태 |
+|-------|------|--------|:--------:|:----:|
+| 결제 | 카드/계좌 결제 | Stripe/Toss | P0 | 📋 |
+| 인증 | OAuth 로그인 | Google/Kakao | P1 | 📋 |
+| 이메일 | 알림/마케팅 | SendGrid | P1 | 📋 |
+| SMS | 인증/알림 | Twilio | P2 | 📋 |
+| 스토리지 | 파일 업로드 | AWS S3 | P1 | 📋 |
+| 모니터링 | 에러 추적 | Sentry | P1 | 📋 |
+| 분석 | 사용자 행동 | Amplitude | P2 | 📋 |
+
+> 상태: 📋 계획 / 🚧 개발 중 / ✅ 완료 / ⏸️ 보류
+
+### 1.2 연동 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     {{PROJECT_NAME}}                         │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                Integration Layer                     │   │
+│  │                                                       │   │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │   │
+│  │  │ Payment  │ │  Auth    │ │ Storage  │ ...        │   │
+│  │  │ Adapter  │ │ Adapter  │ │ Adapter  │            │   │
+│  │  └────┬─────┘ └────┬─────┘ └────┬─────┘            │   │
+│  └───────┼────────────┼────────────┼────────────────────┘   │
+│          │            │            │                         │
+└──────────┼────────────┼────────────┼─────────────────────────┘
+           │            │            │
+           ▼            ▼            ▼
+    ┌──────────┐ ┌──────────┐ ┌──────────┐
+    │  Stripe  │ │  Google  │ │  AWS S3  │
+    │  Toss    │ │  Kakao   │ │          │
+    └──────────┘ └──────────┘ └──────────┘
+```
+
+---
+
+## 2. 결제 연동
+
+### 2.1 서비스 정보
+
+| 항목 | 값 |
+|-----|---|
+| **제공사** | Stripe / Toss Payments |
+| **API 버전** | 2023-10-16 |
+| **환경** | Sandbox (Dev/Staging) / Live (Prod) |
+| **문서** | https://stripe.com/docs/api |
+
+### 2.2 지원 결제 수단
+
+| 결제 수단 | 지원 | 비고 |
+|---------|:----:|------|
+| 신용카드 | ✅ | Visa, Master, Amex |
+| 체크카드 | ✅ | |
+| 계좌이체 | ✅ | 실시간 |
+| 가상계좌 | ✅ | 무통장입금 |
+| 간편결제 | ⚪ | 카카오페이, 네이버페이 |
+
+### 2.3 API 엔드포인트
+
+| 기능 | Method | Endpoint | 설명 |
+|-----|--------|----------|------|
+| 결제 생성 | POST | `/v1/payments` | 결제 의도 생성 |
+| 결제 확인 | POST | `/v1/payments/{id}/confirm` | 결제 승인 |
+| 결제 취소 | POST | `/v1/payments/{id}/cancel` | 전체/부분 취소 |
+| 결제 조회 | GET | `/v1/payments/{id}` | 상태 조회 |
+| 환불 요청 | POST | `/v1/refunds` | 환불 처리 |
+
+### 2.4 Webhook 이벤트
+
+| 이벤트 | 트리거 | 처리 |
+|-------|-------|------|
+| `payment.success` | 결제 성공 | 주문 상태 업데이트 |
+| `payment.failed` | 결제 실패 | 알림 발송, 재시도 |
+| `payment.refunded` | 환불 완료 | 재고 복원 |
+| `payment.disputed` | 분쟁 발생 | 관리자 알림 |
+
+### 2.5 에러 처리
+
+| 에러 코드 | 설명 | 대응 |
+|----------|------|------|
+| `card_declined` | 카드 거절 | 다른 결제 수단 안내 |
+| `insufficient_funds` | 잔액 부족 | 금액 확인 안내 |
+| `expired_card` | 만료된 카드 | 카드 정보 업데이트 |
+| `processing_error` | 처리 오류 | 재시도 (3회) |
+
+---
+
+## 3. 인증 연동 (OAuth)
+
+### 3.1 지원 제공자
+
+| 제공자 | Client ID | Scope | Callback URL |
+|-------|-----------|-------|--------------|
+| Google | `GOOGLE_CLIENT_ID` | email, profile | `/auth/google/callback` |
+| Kakao | `KAKAO_CLIENT_ID` | profile, email | `/auth/kakao/callback` |
+| Naver | `NAVER_CLIENT_ID` | name, email | `/auth/naver/callback` |
+| Apple | `APPLE_CLIENT_ID` | name, email | `/auth/apple/callback` |
+
+### 3.2 OAuth 플로우
+
+```
+┌──────┐     ┌─────────┐     ┌──────────┐     ┌──────────┐
+│Client│     │  Server │     │ Provider │     │    DB    │
+└──┬───┘     └────┬────┘     └────┬─────┘     └────┬─────┘
+   │              │               │                │
+   │  1. Login    │               │                │
+   │─────────────>│               │                │
+   │              │               │                │
+   │  2. Redirect │               │                │
+   │<─────────────│               │                │
+   │              │               │                │
+   │  3. Auth Request             │                │
+   │─────────────────────────────>│                │
+   │              │               │                │
+   │  4. Auth Code│               │                │
+   │<─────────────────────────────│                │
+   │              │               │                │
+   │  5. Callback │               │                │
+   │─────────────>│               │                │
+   │              │  6. Token Exchange             │
+   │              │──────────────>│                │
+   │              │               │                │
+   │              │  7. User Info │                │
+   │              │<──────────────│                │
+   │              │               │                │
+   │              │  8. Create/Update User         │
+   │              │────────────────────────────────>
+   │              │               │                │
+   │  9. JWT      │               │                │
+   │<─────────────│               │                │
+```
+
+### 3.3 사용자 매핑
+
+| Provider 필드 | 내부 필드 | 비고 |
+|--------------|----------|------|
+| `sub` / `id` | `provider_id` | 고유 식별자 |
+| `email` | `email` | 이메일 검증 필요 |
+| `name` / `nickname` | `name` | |
+| `picture` / `profile_image` | `avatar_url` | 선택적 |
+
+---
+
+## 4. 이메일 연동
+
+### 4.1 서비스 정보
+
+| 항목 | 값 |
+|-----|---|
+| **제공사** | SendGrid |
+| **API 버전** | v3 |
+| **일일 한도** | 10,000 (Free), Unlimited (Paid) |
+
+### 4.2 이메일 템플릿
+
+| 템플릿 ID | 용도 | 트리거 |
+|----------|------|--------|
+| `welcome` | 회원가입 환영 | 가입 완료 |
+| `verify-email` | 이메일 인증 | 가입/변경 요청 |
+| `reset-password` | 비밀번호 재설정 | 재설정 요청 |
+| `order-confirm` | 주문 확인 | 결제 완료 |
+| `order-shipped` | 배송 알림 | 배송 시작 |
+
+### 4.3 API 사용
+
+```typescript
+// 이메일 발송
+interface SendEmailRequest {
+  to: string;
+  template_id: string;
+  dynamic_template_data: Record<string, any>;
+}
+
+// POST /v3/mail/send
+```
+
+---
+
+## 5. 파일 스토리지 연동
+
+### 5.1 서비스 정보
+
+| 항목 | 값 |
+|-----|---|
+| **제공사** | AWS S3 |
+| **리전** | ap-northeast-2 |
+| **버킷** | `{{PROJECT_NAME}}-{env}` |
+
+### 5.2 폴더 구조
+
+```
+s3://{{PROJECT_NAME}}-prod/
+├── uploads/              # 사용자 업로드
+│   ├── images/
+│   ├── documents/
+│   └── temp/
+├── assets/               # 정적 자산
+│   ├── images/
+│   └── fonts/
+└── backups/              # 백업
+```
+
+### 5.3 업로드 정책
+
+| 항목 | 값 |
+|-----|---|
+| 최대 파일 크기 | 10MB (이미지), 50MB (문서) |
+| 허용 형식 | jpg, png, gif, pdf, docx, xlsx |
+| 업로드 방식 | Pre-signed URL |
+| 만료 시간 | 15분 |
+
+### 5.4 Pre-signed URL 플로우
+
+```
+┌──────┐     ┌─────────┐     ┌─────────┐
+│Client│     │  Server │     │   S3    │
+└──┬───┘     └────┬────┘     └────┬────┘
+   │              │               │
+   │ 1. Request URL               │
+   │─────────────>│               │
+   │              │               │
+   │              │ 2. Generate   │
+   │              │   Pre-signed  │
+   │              │               │
+   │ 3. Return URL│               │
+   │<─────────────│               │
+   │              │               │
+   │ 4. Direct Upload             │
+   │─────────────────────────────>│
+   │              │               │
+   │ 5. Upload Complete           │
+   │<─────────────────────────────│
+   │              │               │
+   │ 6. Confirm   │               │
+   │─────────────>│               │
+```
+
+---
+
+## 6. Webhook 수신
+
+### 6.1 공통 설정
+
+| 항목 | 값 |
+|-----|---|
+| 엔드포인트 | `/webhooks/{provider}` |
+| 인증 | Signature 검증 |
+| 재시도 | 3회 (exponential backoff) |
+| 타임아웃 | 30초 |
+
+### 6.2 Webhook 보안
+
+```typescript
+// Signature 검증 예시 (Stripe)
+function verifyWebhook(payload: string, signature: string): boolean {
+  const expectedSig = crypto
+    .createHmac('sha256', process.env.WEBHOOK_SECRET)
+    .update(payload)
+    .digest('hex');
+
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expectedSig)
+  );
+}
+```
+
+### 6.3 멱등성 처리
+
+| 처리 | 설명 |
+|-----|------|
+| Event ID 저장 | DB에 처리된 이벤트 기록 |
+| 중복 체크 | 동일 ID 재수신 시 무시 |
+| 순서 보장 | timestamp 기반 처리 |
+
+---
+
+## 7. 모니터링/분석 연동
+
+### 7.1 에러 추적 (Sentry)
+
+```typescript
+// 초기화
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  environment: process.env.NODE_ENV,
+  tracesSampleRate: 0.1,
+});
+
+// 에러 캡처
+Sentry.captureException(error, {
+  tags: { module: 'payment' },
+  extra: { orderId: order.id },
+});
+```
+
+### 7.2 분석 (Amplitude)
+
+```typescript
+// 이벤트 추적
+amplitude.track('purchase_completed', {
+  order_id: order.id,
+  amount: order.total,
+  items: order.items.length,
+});
+```
+
+---
+
+## 8. Rate Limiting & 재시도
+
+### 8.1 제공사별 한도
+
+| 서비스 | Rate Limit | 초과 시 |
+|-------|-----------|---------|
+| Stripe | 100 req/s | 429 + Retry-After |
+| SendGrid | 600 req/min | 429 |
+| S3 | 3,500 PUT/s | 503 |
+
+### 8.2 재시도 전략
+
+```typescript
+const retryConfig = {
+  maxRetries: 3,
+  baseDelay: 1000,      // 1초
+  maxDelay: 30000,      // 30초
+  factor: 2,            // exponential
+  retryableErrors: [429, 500, 502, 503, 504],
+};
+```
+
+---
+
+## 9. 테스트 전략
+
+### 9.1 환경별 설정
+
+| 환경 | 연동 방식 |
+|-----|----------|
+| Unit Test | Mock 사용 |
+| Integration | Sandbox API |
+| Staging | Sandbox API |
+| Production | Live API |
+
+### 9.2 테스트 데이터
+
+| 서비스 | 테스트 데이터 |
+|-------|-------------|
+| Stripe | `4242 4242 4242 4242` (성공) |
+| Stripe | `4000 0000 0000 0002` (거절) |
+| OAuth | 테스트 계정 사용 |
+
+---
+
+## 10. 관련 문서
+
+- [API 명세](./service-spec.md) - 내부 API
+- [환경 설정](./env-config.md) - API 키 관리
+- [에러 코드](./error-codes.md) - 에러 정의
+- [보안 명세](./security-spec.md) - 인증/암호화
+
+---
+
+## 변경 이력
+
+| 버전 | 날짜 | 작성자 | 변경 내용 |
+|------|------|--------|----------|
+| 1.0.0 | {{DATE}} | tsq-planner | 초기 작성 |

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

@@ -0,0 +1,94 @@
+# {PROJECT_NAME} 기획서
+
+**Version**: 1.0
+**Created**: {DATE}
+**PRD Reference**: [prd.md](./prd.md)
+
+---
+
+## 1. 프로젝트 개요
+
+### 1.1 요약
+PRD에서 정의한 목표를 달성하기 위한 실행 계획.
+
+### 1.2 범위
+- **In Scope**:
+- **Out of Scope**:
+
+---
+
+## 2. 마일스톤
+
+| Phase | 목표 | 산출물 | 완료 기준 |
+|-------|-----|--------|----------|
+| Phase 1 | | | |
+| Phase 2 | | | |
+| Phase 3 | | | |
+
+---
+
+## 3. 기술 스택
+
+### 3.1 Frontend
+| 기술 | 용도 | 선택 이유 |
+|-----|------|----------|
+| | | |
+
+### 3.2 Backend
+| 기술 | 용도 | 선택 이유 |
+|-----|------|----------|
+| | | |
+
+### 3.3 Infrastructure
+| 기술 | 용도 | 선택 이유 |
+|-----|------|----------|
+| | | |
+
+---
+
+## 4. 아키텍처 개요
+
+```
+[아키텍처 다이어그램]
+```
+
+### 4.1 주요 컴포넌트
+| 컴포넌트 | 역할 | 기술 |
+|---------|-----|-----|
+| | | |
+
+---
+
+## 5. 팀 구성
+
+| 역할 | 담당 | 책임 |
+|-----|-----|-----|
+| | | |
+
+---
+
+## 6. 의존성
+
+### 6.1 외부 의존성
+| 서비스/API | 용도 | 대안 |
+|-----------|-----|-----|
+| | | |
+
+### 6.2 내부 의존성
+-
+
+---
+
+## 7. 리스크 관리
+
+| 리스크 | 확률 | 영향 | 대응 계획 |
+|-------|-----|-----|----------|
+| | | | |
+
+---
+
+## 8. 변경 이력
+
+| 버전 | 날짜 | 변경 내용 | 작성자 |
+|-----|-----|----------|-------|
+| 1.0 | {DATE} | 최초 작성 | |

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

@@ -0,0 +1,102 @@
+# {PROJECT_NAME} PRD
+
+**Version**: 1.0
+**Created**: {DATE}
+**Author**:
+
+---
+
+## 1. 개요
+
+### 1.1 한 줄 정의
+>
+
+### 1.2 배경
+왜 이 프로젝트가 필요한가?
+
+### 1.3 목표
+- **Primary**:
+- **Secondary**:
+
+### 1.4 비목표 (Non-Goals)
+이 프로젝트에서 하지 않을 것:
+-
+
+---
+
+## 2. 타겟 사용자
+
+### 2.1 Primary User
+- **Who**:
+- **Pain Point**:
+- **Need**:
+
+### 2.2 Secondary User
+- **Who**:
+- **Pain Point**:
+- **Need**:
+
+---
+
+## 3. 핵심 기능
+
+### 3.1 Must Have (P0)
+| 기능 | 설명 | 성공 기준 |
+|-----|------|----------|
+| | | |
+
+### 3.2 Should Have (P1)
+| 기능 | 설명 | 성공 기준 |
+|-----|------|----------|
+| | | |
+
+### 3.3 Nice to Have (P2)
+| 기능 | 설명 |
+|-----|------|
+| | |
+
+---
+
+## 4. 성공 지표
+
+### 4.1 정량적 지표
+| 지표 | 목표 | 측정 방법 |
+|-----|------|----------|
+| | | |
+
+### 4.2 정성적 지표
+-
+
+---
+
+## 5. 제약사항
+
+### 5.1 기술적 제약
+-
+
+### 5.2 비즈니스 제약
+-
+
+### 5.3 일정
+- **시작**:
+- **목표 완료**:
+
+---
+
+## 6. 리스크
+
+| 리스크 | 영향 | 대응 |
+|-------|-----|-----|
+| | | |
+
+---
+
+## 7. 참고
+
+### 7.1 관련 문서
+-
+
+### 7.2 용어 정의
+| 용어 | 정의 |
+|-----|------|
+| | |

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

@@ -0,0 +1,117 @@
+# {PROJECT_NAME} 요건 정의서
+
+**Version**: 1.0
+**Created**: {DATE}
+**PRD Reference**: [prd.md](./prd.md)
+
+---
+
+## 1. 기능 요건 (Functional Requirements)
+
+### 1.1 사용자 인증
+
+| ID | 요건 | 우선순위 | 상태 |
+|----|-----|:--------:|:----:|
+| FR-AUTH-001 | | P0 | 🔲 |
+| FR-AUTH-002 | | P0 | 🔲 |
+
+### 1.2 핵심 기능
+
+| ID | 요건 | 우선순위 | 상태 |
+|----|-----|:--------:|:----:|
+| FR-CORE-001 | | P0 | 🔲 |
+| FR-CORE-002 | | P1 | 🔲 |
+
+### 1.3 관리 기능
+
+| ID | 요건 | 우선순위 | 상태 |
+|----|-----|:--------:|:----:|
+| FR-ADMIN-001 | | P1 | 🔲 |
+
+---
+
+## 2. 비기능 요건 (Non-Functional Requirements)
+
+### 2.1 성능
+
+| ID | 요건 | 목표치 | 측정 방법 |
+|----|-----|-------|----------|
+| NFR-PERF-001 | API 응답 시간 | < 200ms (p95) | APM |
+| NFR-PERF-002 | 동시 사용자 | 1,000명 | 부하 테스트 |
+
+### 2.2 가용성
+
+| ID | 요건 | 목표치 |
+|----|-----|-------|
+| NFR-AVAIL-001 | 서비스 가용성 | 99.9% |
+| NFR-AVAIL-002 | RTO (복구 시간) | < 1시간 |
+
+### 2.3 보안
+
+| ID | 요건 | 상세 |
+|----|-----|-----|
+| NFR-SEC-001 | 인증 | JWT/세션 기반 |
+| NFR-SEC-002 | 암호화 | TLS 1.3, AES-256 |
+| NFR-SEC-003 | 데이터 보호 | 개인정보 암호화 저장 |
+
+### 2.4 확장성
+
+| ID | 요건 | 상세 |
+|----|-----|-----|
+| NFR-SCALE-001 | 수평 확장 | 컨테이너 기반 오토스케일 |
+
+---
+
+## 3. 제약 조건
+
+### 3.1 기술적 제약
+-
+
+### 3.2 환경 제약
+-
+
+### 3.3 규제/컴플라이언스
+-
+
+---
+
+## 4. 인터페이스 요건
+
+### 4.1 사용자 인터페이스
+-
+
+### 4.2 외부 시스템 인터페이스
+| 시스템 | 연동 방식 | 목적 |
+|-------|---------|-----|
+| | | |
+
+---
+
+## 5. 데이터 요건
+
+### 5.1 데이터 저장
+-
+
+### 5.2 데이터 보존
+| 데이터 유형 | 보존 기간 | 삭제 정책 |
+|-----------|---------|----------|
+| | | |
+
+---
+
+## 6. 상태 범례
+
+| 상태 | 의미 |
+|-----|------|
+| 🔲 | 미착수 |
+| 🔄 | 진행중 |
+| ✅ | 완료 |
+| ❌ | 취소/제외 |
+
+---
+
+## 7. 변경 이력
+
+| 버전 | 날짜 | 변경 내용 | 작성자 |
+|-----|-----|----------|-------|
+| 1.0 | {DATE} | 최초 작성 | |