# 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 모듈에 흡수 가능)
```