공개: KoTalk 최신 기준선

문서/08-domain-model-and-api-contract.md

@@ -0,0 +1,271 @@
+# 08. Domain Model And API Contract
+
+이 문서는 도메인 범위와 전체 계약 초안을 담는다.
+
+실제 `v0.1` 구현에 바로 쓰는 최소 계약은 아래 문서를 기준으로 한다.
+- [13-v0.1-api-and-events-contract.md](13-v0.1-api-and-events-contract.md)
+
+## 핵심 도메인 엔티티
+
+### User
+
+- `user_id`
+- `display_name`
+- `created_at`
+- `status`
+
+### Profile
+
+- `user_id`
+- `profile_image`
+- `status_message`
+- `locale`
+
+### Device
+
+- `device_id`
+- `user_id`
+- `device_name`
+- `device_public_key`
+- `trust_state`
+
+### DeviceSession
+
+- `session_id`
+- `user_id`
+- `device_id`
+- `refresh_token_hash`
+- `token_family_id`
+- `last_seen_at`
+- `expires_at`
+
+### Invite
+
+- `invite_token`
+- `issued_by_user_id`
+- `target_scope`
+- `expires_at`
+- `max_uses`
+- `used_count`
+
+### AuthMethod
+
+- `auth_method_id`
+- `user_id`
+- `type`
+- `value_hash_or_ref`
+- `verified_at`
+
+### Conversation
+
+- `conversation_id`
+- `type` (`self`, `dm`, `group`)
+- `title`
+- `created_by`
+- `created_at`
+
+### ConversationMember
+
+- `conversation_id`
+- `user_id`
+- `role`
+- `mute`
+- `pin_order`
+- `joined_at`
+
+### Message
+
+- `message_id`
+- `conversation_id`
+- `sender_user_id`
+- `client_request_id`
+- `server_sequence`
+- `message_type`
+- `body`
+- `created_at`
+- `edited_at`
+
+### Attachment
+
+- `attachment_id`
+- `message_id`
+- `object_key`
+- `mime_type`
+- `byte_size`
+- `checksum`
+
+### ReadCursor
+
+- `conversation_id`
+- `user_id`
+- `last_read_sequence`
+- `updated_at`
+
+## REST 초안
+
+### Alpha Auth
+
+- `POST /v1/auth/device/bootstrap`
+- `POST /v1/auth/register/alpha-quick`
+- `POST /v1/auth/token/refresh`
+- `POST /v1/auth/logout`
+- `POST /v1/auth/logout-all`
+
+### Beta Auth
+
+- `POST /v1/auth/email/start`
+- `POST /v1/auth/email/verify`
+- `POST /v1/auth/link-email/request`
+- `POST /v1/auth/link-email/verify`
+- `POST /v1/auth/recovery-codes/issue`
+
+### Session
+
+- `GET /v1/me`
+- `GET /v1/me/devices`
+- `DELETE /v1/me/devices/{deviceId}`
+
+### Invites
+
+- `POST /v1/invites`
+- `GET /v1/invites/{token}/preview`
+- `POST /v1/invites/{token}/accept`
+
+### Conversations
+
+- `GET /v1/conversations`
+- `POST /v1/conversations`
+- `GET /v1/conversations/{id}`
+- `GET /v1/conversations/{id}/messages?cursor=...`
+- `POST /v1/conversations/{id}/members`
+
+### Messages
+
+- `POST /v1/conversations/{id}/messages`
+- `PATCH /v1/messages/{id}`
+- `DELETE /v1/messages/{id}`
+- `POST /v1/messages/{id}/read`
+
+### Attachments
+
+- `POST /v1/attachments/presign`
+- `POST /v1/attachments/complete`
+- `GET /v1/files/{file_id}`
+
+### Search
+
+- `GET /v1/search?q=...`
+
+## WSS 이벤트 초안
+
+### Client -> Server
+
+- `auth.connect`
+- `session.resume`
+- `message.send`
+- `message.read`
+- `typing.start`
+- `typing.stop`
+- `presence.update`
+- `conversation.join`
+- `conversation.leave`
+
+### Server -> Client
+
+- `auth.connected`
+- `session.resumed`
+- `session.invalidated`
+- `account.created`
+- `invite.accepted`
+- `contact.added`
+- `conversation.created`
+- `sync.bootstrap`
+- `message.created`
+- `message.updated`
+- `message.deleted`
+- `message.read_updated`
+- `presence.changed`
+- `typing.changed`
+- `conversation.updated`
+- `sync.required`
+- `error`
+
+## 메시지 상태 머신
+
+- `draft`
+- `queued`
+- `sending`
+- `sent`
+- `delivered`
+- `read`
+- `failed`
+
+재시도는 `failed -> queued -> sending`으로만 허용한다.
+
+## 동기화 원칙
+
+- 모든 메시지는 `client_request_id`로 멱등 처리
+- 서버는 `server_sequence`를 기준으로 정렬 책임
+- 클라이언트는 대화방별 `last_synced_sequence` 저장
+- 재연결 후 `sync.required`를 받으면 증분 동기화 수행
+
+## 가입 단계별 계약
+
+### Alpha 즉시 실행형
+
+- 입력: `display_name`, `invite_token`
+- 서버 처리: 계정, 프로필, 디바이스, 세션, 기본 대화 생성
+- 결과: 바로 메인 진입
+
+### Beta 기본형
+
+- 입력: `email`
+- 서버 처리: 링크 + 코드 발송
+- 다음 입력: `verification_code` 또는 `magic_link`
+- 결과: 계정/기기 세션 생성 후 메인 진입
+
+## MVP 화면별 Definition Of Done
+
+### 가입
+
+- Alpha: 이름 + 초대코드만으로 진입 가능
+- Beta: 이메일 1회 확인으로 진입 가능
+- 세션 저장
+- 재실행 후 자동 로그인
+- 가입 직후 빈 화면 금지
+
+### 대화 목록
+
+- 최근 순 정렬
+- 읽지 않음 표시
+- 고정/음소거 반영
+- 로컬 캐시 우선 렌더링
+
+### 대화창
+
+- 송수신
+- 읽음 반영
+- 실패 시 재시도
+- 새 메시지 배너
+- 긴 대화 스크롤 안정성
+
+### 첨부
+
+- 업로드
+- 진행 상태
+- 실패 복구
+- 다운로드
+
+## 구현 우선순위 백로그
+
+1. Alpha quick register
+2. Conversation list
+3. Message send/receive
+4. Local cache
+5. Read cursor
+6. Reconnect/sync
+7. Attachment pipeline
+8. Search
+9. Beta email verify
+10. Session management
+11. Admin/report tools