공개: KoTalk 최신 기준선
This commit is contained in:
commit
debf62f76e
572 changed files with 41689 additions and 0 deletions
752
문서/13-v0.1-api-and-events-contract.md
Normal file
752
문서/13-v0.1-api-and-events-contract.md
Normal file
|
|
@ -0,0 +1,752 @@
|
|||
# 13. v0.1 API And Events Contract
|
||||
|
||||
## 목적
|
||||
|
||||
이 문서는 `v0.1` 구현 범위에 맞는 최소 계약만 따로 고정한다.
|
||||
|
||||
대상 범위:
|
||||
- Alpha 가입
|
||||
- 세션 갱신
|
||||
- 부트스트랩
|
||||
- 대화 목록
|
||||
- 대화 메시지 목록
|
||||
- 텍스트 메시지 전송
|
||||
- WebSocket 실시간 이벤트
|
||||
|
||||
핵심 원칙:
|
||||
- 서버가 최대한 계산하고, 클라이언트는 최대한 렌더링만 한다.
|
||||
- REST와 WebSocket에서 같은 엔티티 모양을 재사용한다.
|
||||
- 파생값은 클라이언트에서 계산하지 않는다.
|
||||
- `v0.1`에서는 전송도 REST로 처리하고, WebSocket은 서버 푸시 전용으로 둔다.
|
||||
|
||||
## 고정 결정
|
||||
|
||||
### 1. `GET /v1/bootstrap`이 `GET /v1/me`를 대체한다
|
||||
|
||||
`v0.1`에서는 별도 `GET /v1/me`를 두지 않는다.
|
||||
|
||||
이유:
|
||||
- 첫 실행과 재실행의 초기 진입 경로를 하나로 고정할 수 있다.
|
||||
- `me`, 대화 목록, WebSocket 연결 정보를 한 번에 받으면 클라이언트 부팅 분기가 줄어든다.
|
||||
|
||||
### 2. 대화방 제목과 대표 이미지는 서버가 확정한다
|
||||
|
||||
DM인 경우에도 클라이언트가 상대 이름으로 제목을 조합하지 않는다.
|
||||
|
||||
서버는 항상 아래를 내려준다.
|
||||
- `title`
|
||||
- `avatar_url`
|
||||
- `subtitle`
|
||||
|
||||
### 3. 대화 목록 정렬과 안읽음 수는 서버 책임이다
|
||||
|
||||
서버는 항상 최신 활동순으로 `conversations`를 정렬한다.
|
||||
|
||||
클라이언트는 아래를 그대로 쓴다.
|
||||
- `sort_key`
|
||||
- `unread_count`
|
||||
- `last_message`
|
||||
|
||||
### 4. 메시지 전송은 REST만 사용한다
|
||||
|
||||
`POST /v1/conversations/{conversation_id}/messages/text`
|
||||
|
||||
이유:
|
||||
- WinUI 클라이언트의 재연결, ACK, 재전송, 세션 resume 복잡도가 줄어든다.
|
||||
- 서버는 저장 성공 후 응답하고, 실시간 갱신은 WebSocket으로 fan-out 한다.
|
||||
|
||||
### 5. WebSocket은 인증된 푸시 채널이다
|
||||
|
||||
연결 시 `Authorization: Bearer <access_token>` 헤더를 사용한다.
|
||||
|
||||
`v0.1`에서는 `auth.connect`, `session.resume`, `message.send` 이벤트를 만들지 않는다.
|
||||
|
||||
### 6. 목록 응답은 항상 클라이언트가 바로 그릴 수 있는 모양으로 준다
|
||||
|
||||
`ConversationSummary`, `MessageItem`은 요약용 별도 shape를 쓰지 않고 그대로 UI 바인딩 가능한 형태를 유지한다.
|
||||
|
||||
## 공통 규칙
|
||||
|
||||
### ID
|
||||
|
||||
- 모든 ID는 문자열이다.
|
||||
- 형식은 `ULID`를 권장한다.
|
||||
- 클라이언트는 ID 정렬 규칙에 의존하지 않는다.
|
||||
|
||||
### 시간
|
||||
|
||||
- 모든 시간은 UTC ISO-8601 문자열이다.
|
||||
- 예: `2026-04-16T11:42:31Z`
|
||||
|
||||
### REST 응답 envelope
|
||||
|
||||
성공:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
목록:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"items": [],
|
||||
"next_cursor": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
오류:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "invite_invalid",
|
||||
"message": "초대코드가 유효하지 않습니다.",
|
||||
"retryable": false,
|
||||
"field_errors": {
|
||||
"invite_code": "초대코드를 다시 확인해 주세요."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### WebSocket event envelope
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "message.created",
|
||||
"event_id": "01HSX8X4N1Y6C4R1VX9H1F4K98",
|
||||
"occurred_at": "2026-04-16T11:42:31Z",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
## Canonical Shapes
|
||||
|
||||
### AuthTokens
|
||||
|
||||
```json
|
||||
{
|
||||
"access_token": "jwt-or-opaque",
|
||||
"access_token_expires_at": "2026-04-16T12:42:31Z",
|
||||
"refresh_token": "opaque-refresh-token",
|
||||
"refresh_token_expires_at": "2026-05-16T11:42:31Z"
|
||||
}
|
||||
```
|
||||
|
||||
설명:
|
||||
- `refresh_token`은 매 갱신 시 회전한다.
|
||||
- 클라이언트는 새 `refresh_token`을 받으면 기존 값을 즉시 덮어쓴다.
|
||||
|
||||
### SessionInfo
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "01HSX8T8J7CN1J8TJQ3E6V6KPA",
|
||||
"device_id": "01HSX8SZPQZQ4YVE1N9WR6W4KJ",
|
||||
"device_name": "Windows PC",
|
||||
"created_at": "2026-04-16T11:42:31Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Me
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "01HSX8P2QH5Q1REJYQY3QNZ4N6",
|
||||
"display_name": "이안",
|
||||
"profile_image_url": null,
|
||||
"status_message": null
|
||||
}
|
||||
```
|
||||
|
||||
### ConversationSummary
|
||||
|
||||
```json
|
||||
{
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"type": "self",
|
||||
"title": "나에게 메시지",
|
||||
"avatar_url": null,
|
||||
"subtitle": "메모와 파일을 나에게 보관해 보세요.",
|
||||
"member_count": 1,
|
||||
"is_muted": false,
|
||||
"is_pinned": true,
|
||||
"sort_key": "2026-04-16T11:42:31Z",
|
||||
"unread_count": 0,
|
||||
"last_read_message_id": null,
|
||||
"last_message": null
|
||||
}
|
||||
```
|
||||
|
||||
`last_message`가 있을 때:
|
||||
|
||||
```json
|
||||
{
|
||||
"message_id": "01HSX92D44DWFA0KTV6B0T0SE5",
|
||||
"text": "안녕하세요",
|
||||
"created_at": "2026-04-16T11:45:02Z",
|
||||
"sender_user_id": "01HSX8P2QH5Q1REJYQY3QNZ4N6"
|
||||
}
|
||||
```
|
||||
|
||||
### MessageItem
|
||||
|
||||
```json
|
||||
{
|
||||
"message_id": "01HSX92D44DWFA0KTV6B0T0SE5",
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"client_message_id": "d5bf6a88-b6b0-4f1c-b11d-d2d8a9aaf3b8",
|
||||
"kind": "text",
|
||||
"text": "안녕하세요",
|
||||
"created_at": "2026-04-16T11:45:02Z",
|
||||
"edited_at": null,
|
||||
"sender": {
|
||||
"user_id": "01HSX8P2QH5Q1REJYQY3QNZ4N6",
|
||||
"display_name": "이안",
|
||||
"profile_image_url": null
|
||||
},
|
||||
"is_mine": true
|
||||
}
|
||||
```
|
||||
|
||||
설명:
|
||||
- `sender`를 포함해 클라이언트가 별도 사용자 lookup 없이 렌더링 가능하게 한다.
|
||||
- `is_mine`도 서버가 내려준다.
|
||||
|
||||
### BootstrapPayload
|
||||
|
||||
```json
|
||||
{
|
||||
"me": {},
|
||||
"session": {},
|
||||
"tokens": {},
|
||||
"ws": {
|
||||
"url": "wss://ws.example.com/v1/ws"
|
||||
},
|
||||
"conversations": {
|
||||
"items": [],
|
||||
"next_cursor": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
설명:
|
||||
- 가입 직후와 앱 재실행 직후 모두 같은 shape를 쓴다.
|
||||
- `tokens`는 가입/갱신 응답에만 포함되고, 일반 `GET /v1/bootstrap` 응답에는 포함하지 않는다.
|
||||
|
||||
## Endpoint Contract
|
||||
|
||||
### 1. Alpha 가입
|
||||
|
||||
`POST /v1/auth/register/alpha-quick`
|
||||
|
||||
request:
|
||||
|
||||
```json
|
||||
{
|
||||
"display_name": "이안",
|
||||
"invite_code": "ALPHA-SEOUL-1234",
|
||||
"device_name": "Windows PC"
|
||||
}
|
||||
```
|
||||
|
||||
response:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"me": {
|
||||
"user_id": "01HSX8P2QH5Q1REJYQY3QNZ4N6",
|
||||
"display_name": "이안",
|
||||
"profile_image_url": null,
|
||||
"status_message": null
|
||||
},
|
||||
"session": {
|
||||
"session_id": "01HSX8T8J7CN1J8TJQ3E6V6KPA",
|
||||
"device_id": "01HSX8SZPQZQ4YVE1N9WR6W4KJ",
|
||||
"device_name": "Windows PC",
|
||||
"created_at": "2026-04-16T11:42:31Z"
|
||||
},
|
||||
"tokens": {
|
||||
"access_token": "jwt-or-opaque",
|
||||
"access_token_expires_at": "2026-04-16T12:42:31Z",
|
||||
"refresh_token": "opaque-refresh-token",
|
||||
"refresh_token_expires_at": "2026-05-16T11:42:31Z"
|
||||
},
|
||||
"ws": {
|
||||
"url": "wss://ws.example.com/v1/ws"
|
||||
},
|
||||
"conversations": {
|
||||
"items": [
|
||||
{
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"type": "self",
|
||||
"title": "나에게 메시지",
|
||||
"avatar_url": null,
|
||||
"subtitle": "메모와 파일을 나에게 보관해 보세요.",
|
||||
"member_count": 1,
|
||||
"is_muted": false,
|
||||
"is_pinned": true,
|
||||
"sort_key": "2026-04-16T11:42:31Z",
|
||||
"unread_count": 0,
|
||||
"last_read_message_id": null,
|
||||
"last_message": null
|
||||
}
|
||||
],
|
||||
"next_cursor": null
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
계약:
|
||||
- 가입 성공 시 바로 메인 진입 가능한 데이터를 한 번에 반환한다.
|
||||
- 가입 직후 빈 화면을 만들지 않는다.
|
||||
|
||||
### 2. 세션 갱신
|
||||
|
||||
`POST /v1/auth/token/refresh`
|
||||
|
||||
request:
|
||||
|
||||
```json
|
||||
{
|
||||
"refresh_token": "opaque-refresh-token"
|
||||
}
|
||||
```
|
||||
|
||||
response:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"tokens": {
|
||||
"access_token": "new-access-token",
|
||||
"access_token_expires_at": "2026-04-16T13:42:31Z",
|
||||
"refresh_token": "new-refresh-token",
|
||||
"refresh_token_expires_at": "2026-05-16T11:42:31Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
계약:
|
||||
- 성공 시 refresh token도 반드시 회전한다.
|
||||
- 실패 코드는 최소 아래 둘로 제한한다.
|
||||
- `session_expired`
|
||||
- `session_revoked`
|
||||
|
||||
### 3. 부트스트랩
|
||||
|
||||
`GET /v1/bootstrap`
|
||||
|
||||
header:
|
||||
|
||||
```text
|
||||
Authorization: Bearer <access_token>
|
||||
```
|
||||
|
||||
response:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"me": {
|
||||
"user_id": "01HSX8P2QH5Q1REJYQY3QNZ4N6",
|
||||
"display_name": "이안",
|
||||
"profile_image_url": null,
|
||||
"status_message": null
|
||||
},
|
||||
"session": {
|
||||
"session_id": "01HSX8T8J7CN1J8TJQ3E6V6KPA",
|
||||
"device_id": "01HSX8SZPQZQ4YVE1N9WR6W4KJ",
|
||||
"device_name": "Windows PC",
|
||||
"created_at": "2026-04-16T11:42:31Z"
|
||||
},
|
||||
"ws": {
|
||||
"url": "wss://ws.example.com/v1/ws"
|
||||
},
|
||||
"conversations": {
|
||||
"items": [],
|
||||
"next_cursor": null
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
계약:
|
||||
- 앱 시작 시 첫 요청은 항상 이것이다.
|
||||
- 별도 `GET /v1/me` 호출은 하지 않는다.
|
||||
|
||||
### 4. 대화 목록
|
||||
|
||||
`GET /v1/conversations?cursor=<opaque>&limit=30`
|
||||
|
||||
response:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"items": [
|
||||
{
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"type": "dm",
|
||||
"title": "김민지",
|
||||
"avatar_url": "https://files.example.com/avatar/1.jpg",
|
||||
"subtitle": "오후 3시에 볼까요?",
|
||||
"member_count": 2,
|
||||
"is_muted": false,
|
||||
"is_pinned": false,
|
||||
"sort_key": "2026-04-16T12:04:10Z",
|
||||
"unread_count": 2,
|
||||
"last_read_message_id": "01HSX95G8Z3VCP5BNQY53Q8HMT",
|
||||
"last_message": {
|
||||
"message_id": "01HSX97W2NMMN4HMC42NZSE2HC",
|
||||
"text": "오후 3시에 볼까요?",
|
||||
"created_at": "2026-04-16T12:04:10Z",
|
||||
"sender_user_id": "01HSX8V38VG70E2D7XXMX31YHS"
|
||||
}
|
||||
}
|
||||
],
|
||||
"next_cursor": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
계약:
|
||||
- 서버가 최신 활동순으로 정렬해서 내려준다.
|
||||
- DM 타이틀 조합, 안읽음 계산, 최근 메시지 미리보기 생성은 서버 책임이다.
|
||||
|
||||
### 5. 대화 메시지 목록
|
||||
|
||||
`GET /v1/conversations/{conversation_id}/messages?before=<message_id>&limit=50`
|
||||
|
||||
설명:
|
||||
- `before`가 없으면 최신 50개를 준다.
|
||||
- `before`가 있으면 해당 메시지보다 오래된 메시지를 준다.
|
||||
- 응답 `items`는 항상 오래된 순 -> 최신 순으로 정렬한다.
|
||||
|
||||
response:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"conversation": {
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"type": "dm",
|
||||
"title": "김민지",
|
||||
"avatar_url": "https://files.example.com/avatar/1.jpg",
|
||||
"subtitle": "오후 3시에 볼까요?",
|
||||
"member_count": 2,
|
||||
"is_muted": false,
|
||||
"is_pinned": false,
|
||||
"sort_key": "2026-04-16T12:04:10Z",
|
||||
"unread_count": 2,
|
||||
"last_read_message_id": "01HSX95G8Z3VCP5BNQY53Q8HMT",
|
||||
"last_message": {
|
||||
"message_id": "01HSX97W2NMMN4HMC42NZSE2HC",
|
||||
"text": "오후 3시에 볼까요?",
|
||||
"created_at": "2026-04-16T12:04:10Z",
|
||||
"sender_user_id": "01HSX8V38VG70E2D7XXMX31YHS"
|
||||
}
|
||||
},
|
||||
"items": [
|
||||
{
|
||||
"message_id": "01HSX94N3RRC88GWZZJ4VGMMQX",
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"client_message_id": null,
|
||||
"kind": "text",
|
||||
"text": "좋아요",
|
||||
"created_at": "2026-04-16T11:55:00Z",
|
||||
"edited_at": null,
|
||||
"sender": {
|
||||
"user_id": "01HSX8V38VG70E2D7XXMX31YHS",
|
||||
"display_name": "김민지",
|
||||
"profile_image_url": "https://files.example.com/avatar/1.jpg"
|
||||
},
|
||||
"is_mine": false
|
||||
}
|
||||
],
|
||||
"next_cursor": "01HSX94N3RRC88GWZZJ4VGMMQX"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
계약:
|
||||
- 클라이언트는 응답 순서를 뒤집지 않고 그대로 붙인다.
|
||||
- `conversation`을 같이 내려 대화창 헤더를 별도 API 없이 바로 렌더링하게 한다.
|
||||
|
||||
### 6. 텍스트 메시지 전송
|
||||
|
||||
`POST /v1/conversations/{conversation_id}/messages/text`
|
||||
|
||||
request:
|
||||
|
||||
```json
|
||||
{
|
||||
"client_message_id": "d5bf6a88-b6b0-4f1c-b11d-d2d8a9aaf3b8",
|
||||
"text": "안녕하세요"
|
||||
}
|
||||
```
|
||||
|
||||
response:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"message": {
|
||||
"message_id": "01HSX92D44DWFA0KTV6B0T0SE5",
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"client_message_id": "d5bf6a88-b6b0-4f1c-b11d-d2d8a9aaf3b8",
|
||||
"kind": "text",
|
||||
"text": "안녕하세요",
|
||||
"created_at": "2026-04-16T11:45:02Z",
|
||||
"edited_at": null,
|
||||
"sender": {
|
||||
"user_id": "01HSX8P2QH5Q1REJYQY3QNZ4N6",
|
||||
"display_name": "이안",
|
||||
"profile_image_url": null
|
||||
},
|
||||
"is_mine": true
|
||||
},
|
||||
"conversation": {
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"type": "self",
|
||||
"title": "나에게 메시지",
|
||||
"avatar_url": null,
|
||||
"subtitle": "메모와 파일을 나에게 보관해 보세요.",
|
||||
"member_count": 1,
|
||||
"is_muted": false,
|
||||
"is_pinned": true,
|
||||
"sort_key": "2026-04-16T11:45:02Z",
|
||||
"unread_count": 0,
|
||||
"last_read_message_id": "01HSX92D44DWFA0KTV6B0T0SE5",
|
||||
"last_message": {
|
||||
"message_id": "01HSX92D44DWFA0KTV6B0T0SE5",
|
||||
"text": "안녕하세요",
|
||||
"created_at": "2026-04-16T11:45:02Z",
|
||||
"sender_user_id": "01HSX8P2QH5Q1REJYQY3QNZ4N6"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
계약:
|
||||
- `client_message_id`는 멱등 키다.
|
||||
- 같은 세션에서 같은 `client_message_id`를 다시 보내면 서버는 같은 `message`를 재반환한다.
|
||||
- 응답의 `conversation`은 대화 목록 upsert에 그대로 쓴다.
|
||||
|
||||
## WebSocket Contract
|
||||
|
||||
### 연결
|
||||
|
||||
URL:
|
||||
|
||||
```text
|
||||
wss://ws.example.com/v1/ws
|
||||
```
|
||||
|
||||
header:
|
||||
|
||||
```text
|
||||
Authorization: Bearer <access_token>
|
||||
```
|
||||
|
||||
연결 정책:
|
||||
- 인증 성공 시 연결 유지
|
||||
- 토큰 만료 또는 세션 철회 시 서버가 `session.invalidated` 이벤트 후 연결 종료
|
||||
- 클라이언트는 access token refresh 후 재연결한다
|
||||
|
||||
### 서버 -> 클라이언트 이벤트
|
||||
|
||||
#### 1. `conversation.upsert`
|
||||
|
||||
언제:
|
||||
- 새 대화 생성
|
||||
- 새 메시지로 목록 순서 변경
|
||||
- mute/pin/title 변경
|
||||
- unread_count 변경
|
||||
|
||||
payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "conversation.upsert",
|
||||
"event_id": "01HSX9DZ7X7P8E7D7NR0Q6SC2N",
|
||||
"occurred_at": "2026-04-16T12:04:10Z",
|
||||
"data": {
|
||||
"conversation": {
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"type": "dm",
|
||||
"title": "김민지",
|
||||
"avatar_url": "https://files.example.com/avatar/1.jpg",
|
||||
"subtitle": "오후 3시에 볼까요?",
|
||||
"member_count": 2,
|
||||
"is_muted": false,
|
||||
"is_pinned": false,
|
||||
"sort_key": "2026-04-16T12:04:10Z",
|
||||
"unread_count": 2,
|
||||
"last_read_message_id": "01HSX95G8Z3VCP5BNQY53Q8HMT",
|
||||
"last_message": {
|
||||
"message_id": "01HSX97W2NMMN4HMC42NZSE2HC",
|
||||
"text": "오후 3시에 볼까요?",
|
||||
"created_at": "2026-04-16T12:04:10Z",
|
||||
"sender_user_id": "01HSX8V38VG70E2D7XXMX31YHS"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. `message.created`
|
||||
|
||||
언제:
|
||||
- 현재 세션이 열어 둔 대화에 새 메시지가 생김
|
||||
- 같은 사용자의 다른 기기에서 새 메시지가 생김
|
||||
|
||||
payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "message.created",
|
||||
"event_id": "01HSX9FYF5Y1WYP8A7A65M23RY",
|
||||
"occurred_at": "2026-04-16T12:04:10Z",
|
||||
"data": {
|
||||
"message": {
|
||||
"message_id": "01HSX97W2NMMN4HMC42NZSE2HC",
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"client_message_id": null,
|
||||
"kind": "text",
|
||||
"text": "오후 3시에 볼까요?",
|
||||
"created_at": "2026-04-16T12:04:10Z",
|
||||
"edited_at": null,
|
||||
"sender": {
|
||||
"user_id": "01HSX8V38VG70E2D7XXMX31YHS",
|
||||
"display_name": "김민지",
|
||||
"profile_image_url": "https://files.example.com/avatar/1.jpg"
|
||||
},
|
||||
"is_mine": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
정책:
|
||||
- REST 전송을 호출한 동일 세션에는 이 이벤트를 생략할 수 있다.
|
||||
- 다른 기기 세션에는 전송한다.
|
||||
|
||||
#### 3. `conversation.read_updated`
|
||||
|
||||
언제:
|
||||
- 현재 사용자의 읽음 기준 메시지가 바뀜
|
||||
|
||||
payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "conversation.read_updated",
|
||||
"event_id": "01HSX9H9B9ZPVJKK1X8R74SFCY",
|
||||
"occurred_at": "2026-04-16T12:05:11Z",
|
||||
"data": {
|
||||
"conversation_id": "01HSX90M5W7Y0S8DDE6RP9N2PD",
|
||||
"last_read_message_id": "01HSX97W2NMMN4HMC42NZSE2HC",
|
||||
"unread_count": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. `session.invalidated`
|
||||
|
||||
언제:
|
||||
- refresh token family 철회
|
||||
- 원격 로그아웃
|
||||
- 서버 정책상 세션 무효
|
||||
|
||||
payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "session.invalidated",
|
||||
"event_id": "01HSX9K6Y3MJ5D6M8Q10M3ZTTE",
|
||||
"occurred_at": "2026-04-16T12:10:00Z",
|
||||
"data": {
|
||||
"reason": "session_revoked"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. `sync.required`
|
||||
|
||||
언제:
|
||||
- 이벤트 누락 가능성이 생김
|
||||
- 서버 재배포 후 in-memory 라우팅이 끊김
|
||||
- 클라이언트 재연결 후 증분 상태 신뢰가 깨짐
|
||||
|
||||
payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "sync.required",
|
||||
"event_id": "01HSX9MRFFW66R9HKYE7QH1PXN",
|
||||
"occurred_at": "2026-04-16T12:11:30Z",
|
||||
"data": {
|
||||
"scope": "bootstrap"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
정책:
|
||||
- `v0.1`에서는 부분 복구 대신 `GET /v1/bootstrap` 재호출로 단순화한다.
|
||||
|
||||
## Client Flow
|
||||
|
||||
### 첫 가입
|
||||
|
||||
1. `POST /v1/auth/register/alpha-quick`
|
||||
2. 응답의 `tokens` 저장
|
||||
3. 응답의 `conversations.items`로 좌측 목록 즉시 렌더링
|
||||
4. WebSocket 연결
|
||||
|
||||
### 앱 재실행
|
||||
|
||||
1. 저장된 refresh token으로 `POST /v1/auth/token/refresh`
|
||||
2. 성공 시 새 토큰 저장
|
||||
3. `GET /v1/bootstrap`
|
||||
4. WebSocket 연결
|
||||
|
||||
### 대화방 진입
|
||||
|
||||
1. 목록에서 `conversation_id` 선택
|
||||
2. `GET /v1/conversations/{id}/messages`
|
||||
3. 메시지 렌더링
|
||||
4. WebSocket의 `message.created`, `conversation.upsert` 반영
|
||||
|
||||
### 메시지 전송
|
||||
|
||||
1. 로컬에서 `client_message_id` 생성
|
||||
2. 임시 pending UI 추가
|
||||
3. `POST /v1/conversations/{id}/messages/text`
|
||||
4. 성공 시 서버 응답 `message`로 pending 교체
|
||||
5. 응답 `conversation`으로 목록 upsert
|
||||
|
||||
## 구현 메모
|
||||
|
||||
`v0.1`에서 의도적으로 제외:
|
||||
- 메시지 수정/삭제
|
||||
- 첨부파일
|
||||
- typing
|
||||
- presence
|
||||
- 반응
|
||||
- 검색
|
||||
- 멀티 페이지 bootstrap
|
||||
- WebSocket client-to-server command
|
||||
|
||||
이유:
|
||||
- 지금 필요한 것은 `가입 -> 자동 로그인 -> 목록 -> 대화 -> 텍스트 전송 -> 실시간 반영`의 완결된 1차 루프다.
|
||||
- 나머지는 이후 추가해도 contract 파손이 적다.
|
||||
Loading…
Add table
Add a link
Reference in a new issue