271 lines
4.6 KiB
Markdown
271 lines
4.6 KiB
Markdown
# 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
|