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

08. Domain Model And API Contract

이 문서는 도메인 범위와 전체 계약 초안을 담는다.

실제 v0.1 구현에 바로 쓰는 최소 계약은 아래 문서를 기준으로 한다.

• 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