first commit

2026-06-16 17:12:08 +09:00
commit e1bc5a1dfc
257 changed files with 49823 additions and 0 deletions
@@ -0,0 +1,231 @@
+# Relay API 계약서 (SSOT)
+
+> 프론트(`frontend/src/mock/relay.mock.ts`) 인터페이스를 기준으로 도출한 **백엔드 ↔ 프론트 공통 계약**.
+> 백엔드 엔티티/DTO와 프론트 타입은 이 문서를 단일 진실 공급원으로 삼아 양쪽이 동일하게 구현한다.
+> 모든 응답은 루트 `CLAUDE.md` 의 표준 응답 래퍼(`{ success, data }` / `{ success, error }`)로 감싸지며,
+> 아래 표의 "응답"은 **언래핑된 `data` 본문**만 기술한다.
+
+## 0. 공통 규약
+
+### 인증 / 토큰
+
+- **이메일 + JWT만 1단계 구현.** 소셜 로그인(Google/Kakao)·이메일 인증은 8단계로 보류.
+- Access / Refresh 토큰 **모두 HttpOnly·Secure 쿠키**로 전달 (웹 `localStorage` 금지).
+  - Access: 짧은 만료(15분), 쿠키명 `access_token`
+  - Refresh: 긴 만료(14일), 쿠키명 `refresh_token`, 경로 `/api/auth`
+- 프론트 axios 는 `withCredentials: true` (이미 적용됨) — 별도 Authorization 헤더 불필요.
+- 보호 라우트는 `JwtAuthGuard`. 미인증 시 401 → `AUTH_001`.
+
+### ID 전략
+
+| 대상 | 타입 | 비고 |
+|---|---|---|
+| User | `uuid` | 외부 노출 식별자 |
+| Repo | `uuid` + `slug` | URL 은 `owner/name` slug, 라우팅 segment 는 `slug` 마지막 토큰 |
+| Task | `number` | **저장소 내 순번**(GitHub 이슈처럼 `#9`). 전역 PK 는 별도 uuid |
+| 그 외 | `uuid` | Comment, Attachment 등 |
+
+### 파생 필드(저장하지 않고 계산)
+
+다음은 **백엔드가 원시값(타임스탬프/카운트)만 내려주고 프론트 `shared/utils/format.ts` 에서 계산**한다.
+
+- `updatedAgo`("2시간 전 업데이트"), `dueLabel`("D-3", "2일 지남", "6월 9일 완료"), `dday`, `ddayLevel`
+- `progressPct`, `progressLevel`, `progressLabel`, `doneCount`/`totalCount`(서버 카운트 응답은 허용)
+- 아바타 `initial`/`color` — 서버는 `name` 만, color 는 userId 해시로 프론트 산출(또는 서버 저장)
+
+따라서 API 응답의 날짜 필드는 모두 **ISO 8601 문자열**(`dueDate`, `updatedAt`, `createdAt` 등)로 내린다.
+
+### 비즈니스 에러 (사용자 노출 문구)
+
+도메인 검증 실패처럼 **사용자에게 구체 문구를 보여줘야 하는 경우** `BusinessException(code, message, status)`
+(`backend/src/common/exceptions/business.exception.ts`)를 던진다. 전역 필터가 `{ code, message }` 를
+status 매핑보다 우선해 그대로 표준 응답으로 내려보내고, 프론트는 `BIZ_001` 코드일 때 서버 `message` 를 그대로 노출한다.
+예: 로그인 실패 → `BusinessException('BIZ_001', '이메일 또는 비밀번호가 올바르지 않습니다.', 401)`.
+
+### 페이지네이션
+
+목록 API 는 오프셋 기반: 쿼리 `?page=1&size=20`, 응답 `{ items: [...], total, page, size }`.
+(1단계에서는 단순 배열 허용, 7단계에서 페이지네이션으로 통일)
+
+---
+
+## 1. 인증 (`/api/auth`) — **1단계**
+
+| 메서드 | 경로 | 요청 | 응답 | 비고 |
+|---|---|---|---|---|
+| POST | `/auth/signup` | `{ email, password, name }` | `{ user }` | 가입 후 자동 로그인(쿠키 set) |
+| POST | `/auth/login` | `{ email, password, keepLogin? }` | `{ user }` | access/refresh 쿠키 set |
+| POST | `/auth/logout` | — | `null` | 쿠키 clear |
+| POST | `/auth/refresh` | — (refresh 쿠키) | `null` | access 쿠키 재발급 |
+| GET | `/auth/me` | — | `User` | 부트스트랩/가드용. 미인증 401 |
+
+`User` 응답 형태:
+
+```jsonc
+{
+  "id": "uuid",
+  "email": "sykim@acme.co",
+  "name": "김서연",
+  "role": "콘텐츠 기획"   // 전사 직무(선택)
+}
+```
+
+> 프론트 매핑: `auth.store.ts`(신규) + `useAuth` composable. 라우터 가드 TODO 를
+> `me` 부트스트랩 + 401→`/login` 리다이렉트로 교체. `LoginPage`/`SignupPage` 의 `router.push` 를 실제 호출로.
+
+---
+
+## 2. 저장소 (`/api/repos`) — **2단계**
+
+| 메서드 | 경로 | 요청 | 응답 |
+|---|---|---|---|
+| GET | `/repos` | `?page&size` | `Repo[]`(요약) — 내가 멤버인 저장소 |
+| POST | `/repos` | `CreateRepoDto` | `Repo` |
+| GET | `/repos/:repoId` | — | `Repo`(상세) |
+| PATCH | `/repos/:repoId` | `UpdateRepoDto` | `Repo` |
+| DELETE | `/repos/:repoId` | — | `null` |
+
+`CreateRepoDto`: `{ name, desc, visibility('private'|'public'), branch? }`
+`Repo` 응답(원시값 중심):
+
+```jsonc
+{
+  "id": "q3-launch-campaign",      // slug 마지막 segment = 라우팅 id
+  "name": "3분기 신제품 런칭 캠페인",
+  "owner": "marketing-team",
+  "slug": "marketing-team/q3-launch-campaign",
+  "desc": "...",
+  "visibility": "private",
+  "branch": "main",
+  "members": [ /* User 요약 배열, 최대 N명 + memberCount */ ],
+  "memberCount": 5,
+  "doneCount": 8,
+  "totalCount": 12,
+  "updatedAt": "2026-06-16T11:00:00Z"
+}
+```
+> `moreCount`, `progressPct/Level/Label`, `updatedAgo` 는 프론트 계산.
+> 매핑 페이지: RepoListPage, RepoCreatePage, RepoDetailPage(헤더), RepoSettingsPage.
+
+---
+
+## 3. 멤버 (`/api/repos/:repoId/members`) — **3단계**
+
+| 메서드 | 경로 | 요청 | 응답 | 권한 |
+|---|---|---|---|---|
+| GET | `.../members` | — | `RepoMember[]` | member+ |
+| POST | `.../members` | `{ email, roleType, subRole? }` | `RepoMember` | admin |
+| PATCH | `.../members/:userId` | `{ roleType?, subRole? }` | `RepoMember` | admin |
+| DELETE | `.../members/:userId` | — | `null` | admin (owner 제거 불가) |
+
+`RepoMember`: `{ user: User, email, subRole, taskCount, roleType('admin'|'member'), owner }`
+(`isYou` 는 프론트가 현재 사용자와 비교해 산출)
+> 매핑 페이지: RepoMembersPage(초대 모달, 역할 변경, 제거).
+
+---
+
+## 4. 업무 (`/api/repos/:repoId/tasks`) — **4단계**
+
+| 메서드 | 경로 | 요청 | 응답 |
+|---|---|---|---|
+| GET | `.../tasks` | `?status&assignee` | `RepoTask[]` |
+| POST | `.../tasks` | `CreateTaskDto` | `TaskDetail` |
+| GET | `.../tasks/:taskId` | — | `TaskDetail` |
+| PATCH | `.../tasks/:taskId` | `UpdateTaskDto` | `TaskDetail` |
+| DELETE | `.../tasks/:taskId` | — | `null` |
+| POST | `.../tasks/:taskId/status` | `{ status }` | `TaskDetail` |
+
+상태(`TaskStatus`): `todo | prog | review | done | changes`. 전이 규칙(상태 머신):
+
+```
+todo ─시작→ prog ─승인요청→ review ─승인→ done
+                 ▲                  └─수정요청→ changes ─재요청→ review
+                 └──────────────────────────────────┘
+```
+
+- `POST .../status` 는 일반 상태 변경.
+- **승인 워크플로우**(5단계와 함께): 담당자 "승인 요청"(prog→review), 지시자 "승인"(review→done) / "수정 요청"(review→changes).
+
+`CreateTaskDto`: `{ title, content?: string[], assigneeIds: uuid[], dueDate?: ISO, checklist?: {text}[] }`
+`RepoTask`(목록 행): `{ id, title, status, dueDate, checklist: [done,total], commentCount, assignees: User[] }`
+`TaskDetail`: mock 의 `TaskDetail` 인터페이스와 동일 — 단 라벨류는 원시값으로:
+`{ id, repoId, repoName, title, status, content[], checklist[], comments[], activities[], assignees[], issuer, dueDate, files[], approval?, createdAt }`
+> 매핑 페이지: RepoDetailPage(목록), TaskCreatePage, TaskDetailPage(지시자), TaskAssigneePage(담당자, state 분기).
+
+---
+
+## 5. 업무 상세 부속 — **5단계**
+
+### 체크리스트
+| 메서드 | 경로 | 요청 | 응답 |
+|---|---|---|---|
+| POST | `.../tasks/:taskId/checklist` | `{ text }` | `ChecklistItem` |
+| PATCH | `.../checklist/:itemId` | `{ text?, done? }` | `ChecklistItem` |
+| DELETE | `.../checklist/:itemId` | — | `null` |
+
+### 댓글 / 답글
+| 메서드 | 경로 | 요청 | 응답 |
+|---|---|---|---|
+| POST | `.../tasks/:taskId/comments` | `{ text, fileId? }` | `Comment` |
+| POST | `.../comments/:commentId/replies` | `{ text }` | `Reply` |
+
+### 파일 첨부
+| 메서드 | 경로 | 요청 | 응답 |
+|---|---|---|---|
+| POST | `.../tasks/:taskId/files` | `multipart/form-data` | `Attachment` |
+| DELETE | `.../files/:fileId` | — | `null` |
+
+> **결정 필요**: 파일 저장소(로컬 볼륨 vs S3/MinIO). `Attachment`: `{ id, name, size, kind('pdf'|'zip'|'doc'|'img'), url }`.
+
+### 승인 워크플로우
+| 메서드 | 경로 | 요청 | 응답 |
+|---|---|---|---|
+| POST | `.../tasks/:taskId/approval/request` | `{ note }` | `TaskDetail` |
+| POST | `.../tasks/:taskId/approval/approve` | — | `TaskDetail` |
+| POST | `.../tasks/:taskId/approval/changes` | `{ note }` | `TaskDetail` |
+
+---
+
+## 6. 활동 피드 — **6단계**
+
+활동은 **2~5단계 행위에서 이벤트로 자동 적재**(쓰기 API 없음, 읽기만).
+
+| 메서드 | 경로 | 응답 |
+|---|---|---|
+| GET | `/repos/:repoId/activity` | `RepoActivityDay[]`(날짜 그룹) |
+| (업무 활동) | `TaskDetail.activities` 에 포함 | `Activity[]` |
+
+`RepoActivityItem`: `{ tone, icon, actor: User, payload, createdAt }`
+> 서버는 이벤트 타입 + 행위자 + 대상만 저장하고, **표시 HTML 문구는 프론트에서 조립**(현재 mock 은 html 통문자열 — 연동 시 구조화 권장). 매핑: RepoActivityPage, TaskDetail 활동 탭.
+
+---
+
+## 7. 내 업무 (`/api/tasks`) — **7단계**
+
+| 메서드 | 경로 | 요청 | 응답 |
+|---|---|---|---|
+| GET | `/tasks/assigned` | — | `MyTaskGroup[]`(상태 그룹) — 내가 담당 |
+| GET | `/tasks/issued` | — | `MyTaskGroup[]` — 내가 지시 |
+
+저장소 횡단 집계. `MyTaskGroup`/`MyTaskRow` 는 mock 인터페이스와 동일하되 라벨류 제외, 원시값(`dueDate`, `status`) 기반.
+> 매핑 페이지: MyTasksPage(담당/지시 탭, 상태 그룹). `countActive` 는 프론트 유지.
+
+---
+
+## 8. 마무리(선택) — **8단계**
+
+소셜 로그인(Google/Kakao OAuth), 이메일 인증, 알림, AI 에이전트 패널, Redis 캐싱, 전체 페이지네이션 통일.
+
+---
+
+## 백엔드 모듈 매핑 (구현 순서)
+
+```
+src/modules/
+  auth/      (1) — User 엔티티, JWT 전략, Guard, 쿠키
+  repo/      (2) — Repo 엔티티
+  member/    (3) — RepoMember 조인 엔티티 (repo 모듈에 흡수 가능)
+  task/      (4,5) — Task / ChecklistItem / Comment / Reply / Attachment
+  activity/  (6) — Activity 이벤트 (다른 모듈에서 emit)
+  my-tasks/  (7) — 집계 전용 (task 모듈에 흡수 가능)
+```