482 lines
16 KiB
Markdown
482 lines
16 KiB
Markdown
# Dakao NATS Command API
|
|
|
|
dakao는 NATS를 통해 외부 시스템으로부터 command를 받아 LOCO 세션에 반영할 수 있다.
|
|
현재 구현 기준으로 지원하는 command는 아래 2종이다.
|
|
|
|
- `chat.send-text`
|
|
기존 API. `text`와 `extra`를 그대로 받아 전송한다.
|
|
점진적으로 deprecated 예정.
|
|
- `chat.send-message`
|
|
신규 권장 API. `segments` 기반으로 텍스트, 멘션, 카카오톡 이모티콘을 조합해서 전송한다.
|
|
builder를 거치면서 semantic validation까지 수행한다.
|
|
|
|
## 개요
|
|
|
|
### 기본 subject
|
|
|
|
| 용도 | 기본 subject | 비고 |
|
|
| ------------------ | ------------------------------------ | --------------- |
|
|
| 레거시 텍스트 전송 | `dakao.command.chat.send-text.v1` | deprecated 예정 |
|
|
| 신규 메시지 전송 | `dakao.command.chat.send-message.v1` | 권장 |
|
|
|
|
### 관련 환경변수
|
|
|
|
| 키 | 의미 |
|
|
| ---------------------------------------------- | ------------------------------- |
|
|
| `DAKAO_NATS_COMMANDS_ENABLED` | `1`이면 command consumer 활성화 |
|
|
| `DAKAO_NATS_COMMAND_CHAT_SEND_TEXT_SUBJECT` | 레거시 subject override |
|
|
| `DAKAO_NATS_COMMAND_CHAT_SEND_MESSAGE_SUBJECT` | 신규 subject override |
|
|
|
|
### 전송 포맷
|
|
|
|
- NATS payload는 JSON object여야 한다.
|
|
- 내부 구현은 `JSON.stringify(...)`로 publish하고, subscribe 시 `JSON.parse(...)`로 역직렬화한다.
|
|
- 응답은 NATS의 transport-level reply가 아니라, command object 내부의 `replySubject` 필드를 사용해 별도 publish된다.
|
|
|
|
### subject와 `type`의 관계
|
|
|
|
운영 규약상 아래처럼 맞춰서 보내는 것을 권장한다.
|
|
|
|
- `dakao.command.chat.send-text.v1` 에는 `type: "chat.send-text"`
|
|
- `dakao.command.chat.send-message.v1` 에는 `type: "chat.send-message"`
|
|
|
|
현재 구현은 두 subject를 모두 구독한 뒤 `type`으로 실제 처리를 분기한다.
|
|
즉 subject와 type이 어긋나도 처리될 수 있지만, 운영 혼선을 막기 위해 반드시 맞춰서 보내는 것을 권장한다.
|
|
|
|
## 공통 Envelope
|
|
|
|
모든 command는 아래 envelope를 사용한다.
|
|
|
|
```json
|
|
{
|
|
"schema": "dakao.command.v1",
|
|
"id": "cmd-001",
|
|
"type": "chat.send-message",
|
|
"source": "my-service",
|
|
"correlationId": "trace-001",
|
|
"replySubject": "dakao.result.my-service",
|
|
"payload": {}
|
|
}
|
|
```
|
|
|
|
### 공통 필드
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
| --------------- | ------ | ---- | -------------------------------- |
|
|
| `schema` | string | Y | 현재는 반드시 `dakao.command.v1` |
|
|
| `id` | string | Y | command 고유 ID |
|
|
| `type` | string | Y | command 종류 |
|
|
| `source` | string | Y | producer 식별자 |
|
|
| `correlationId` | string | N | 추적용 상관관계 ID |
|
|
| `replySubject` | string | N | 결과를 publish할 subject |
|
|
| `payload` | object | Y | command 본문 |
|
|
|
|
### 공통 검증
|
|
|
|
- 문자열 필드인 `id`, `type`, `source`, `correlationId`, `replySubject`는 trim 후 빈 문자열이면 거부된다.
|
|
- 최상위 object와 payload는 정의되지 않은 필드를 허용하지 않는다.
|
|
- `replySubject`가 없으면 처리 결과는 publish되지 않는다.
|
|
|
|
## Command: `chat.send-text`
|
|
|
|
### 상태
|
|
|
|
- 레거시 API
|
|
- 기존 producer 호환성을 위해 유지 중
|
|
- `text`와 `extra`를 그대로 전달하므로, 멘션/이모티콘 semantic validation은 수행하지 않는다
|
|
|
|
### 권장 subject
|
|
|
|
```text
|
|
dakao.command.chat.send-text.v1
|
|
```
|
|
|
|
### Payload
|
|
|
|
```json
|
|
{
|
|
"chatroomId": "123456789012345678",
|
|
"text": "hello",
|
|
"attachment": {
|
|
"example": true
|
|
},
|
|
"extra": "{}"
|
|
}
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
| ------------ | ---------------- | ---- | ------------------------------------------------------- |
|
|
| `chatroomId` | string | Y | 채팅방 ID. 실운영에서는 decimal string 사용 권장 |
|
|
| `text` | string | Y | 보낼 메시지 본문 |
|
|
| `attachment` | string or object | N | 첨부 payload. object면 전송 직전에 JSON string으로 변환 |
|
|
| `extra` | string | N | LOCO `WRITE.extra` raw 값 |
|
|
|
|
### 동작
|
|
|
|
- 내부적으로 `client.sendMessage(chatroomId, text, { attachment, extra })` 로 전송한다.
|
|
- `extra`를 생략하면 최종 LOCO 전송 시 기본값 `"{}"` 가 사용된다.
|
|
- 이 API는 `extra` 구조를 검증하지 않는다.
|
|
|
|
### 예시
|
|
|
|
```json
|
|
{
|
|
"schema": "dakao.command.v1",
|
|
"id": "cmd-text-001",
|
|
"type": "chat.send-text",
|
|
"source": "admin-panel",
|
|
"replySubject": "dakao.result.admin-panel",
|
|
"payload": {
|
|
"chatroomId": "123456789012345678",
|
|
"text": "plain text message",
|
|
"extra": "{}"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Command: `chat.send-message`
|
|
|
|
### 상태
|
|
|
|
- 신규 권장 API
|
|
- 텍스트, 멘션, 카카오톡 이모티콘을 조합해서 전송할 수 있다
|
|
- `buildLocoMessage(...)` 를 통해 최종 `text`와 `extra`를 생성한다
|
|
- Joi schema validation 이후 builder semantic validation이 한 번 더 수행된다
|
|
|
|
### 권장 subject
|
|
|
|
```text
|
|
dakao.command.chat.send-message.v1
|
|
```
|
|
|
|
### Payload
|
|
|
|
```json
|
|
{
|
|
"chatroomId": "123456789012345678",
|
|
"segments": [
|
|
{ "kind": "text", "text": "안녕하세요 " },
|
|
{
|
|
"kind": "mention",
|
|
"userId": "6215844374579825921",
|
|
"displayText": "날으는꼴뚜기/95/여/D"
|
|
},
|
|
{ "kind": "text", "text": " " },
|
|
{ "kind": "emoticon", "id": "1200281_004", "altText": "플라워" }
|
|
],
|
|
"attachment": {
|
|
"example": true
|
|
},
|
|
"type": 1,
|
|
"noSeen": false,
|
|
"scope": 1,
|
|
"silence": false
|
|
}
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
| ------------ | ---------------- | ---- | ------------------------------------------------------- |
|
|
| `chatroomId` | string | Y | 채팅방 ID. 실운영에서는 decimal string 사용 권장 |
|
|
| `segments` | array | Y | 메시지 세그먼트 배열. 최소 1개 이상 |
|
|
| `attachment` | string or object | N | 첨부 payload. object면 전송 직전에 JSON string으로 변환 |
|
|
| `type` | integer | N | LOCO `WRITE.type`. 기본값 `1` |
|
|
| `noSeen` | boolean | N | LOCO `WRITE.noSeen`. 기본값 `false` |
|
|
| `scope` | integer | N | LOCO `WRITE.scope`. 기본값 `1` |
|
|
| `silence` | boolean | N | LOCO `WRITE.silence`. 기본값 `false` |
|
|
|
|
### Segment 종류
|
|
|
|
#### `text`
|
|
|
|
```json
|
|
{ "kind": "text", "text": "안녕하세요 " }
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
| ------ | ------ | ---- | -------------------------------------- |
|
|
| `kind` | string | Y | 반드시 `text` |
|
|
| `text` | string | Y | 일반 텍스트. 빈 문자열은 허용되지 않음 |
|
|
|
|
#### `mention`
|
|
|
|
```json
|
|
{
|
|
"kind": "mention",
|
|
"userId": "6215844374579825921",
|
|
"displayText": "날으는꼴뚜기/95/여/D"
|
|
}
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
| ------------- | ------ | ---- | --------------------------------------------------------- |
|
|
| `kind` | string | Y | 반드시 `mention` |
|
|
| `userId` | string | Y | 양의 정수 문자열 권장. int64 손실 방지를 위해 문자열 사용 |
|
|
| `displayText` | string | Y | 화면에 표시될 이름. builder가 앞의 `@`를 자동 정리 |
|
|
|
|
멘션은 최종 메시지에서 아래처럼 렌더링된다.
|
|
|
|
```text
|
|
@{displayText}
|
|
```
|
|
|
|
예를 들어 `displayText: "홍길동"` 이면 `@홍길동` 으로 전송된다.
|
|
`displayText`를 `@홍길동`처럼 보내도 builder가 앞의 `@` 하나를 제거한 뒤 다시 렌더링한다.
|
|
|
|
#### `emoticon`
|
|
|
|
```json
|
|
{
|
|
"kind": "emoticon",
|
|
"id": "1200281_004",
|
|
"altText": "플라워"
|
|
}
|
|
```
|
|
|
|
| 필드 | 타입 | 필수 | 설명 |
|
|
| --------- | ------ | ---- | --------------------------------------- |
|
|
| `kind` | string | Y | 반드시 `emoticon` |
|
|
| `id` | string | Y | 카카오톡 이모티콘 item ID |
|
|
| `altText` | string | Y | 대체 텍스트. builder가 괄호를 자동 정리 |
|
|
|
|
이모티콘은 최종 메시지에서 아래처럼 렌더링된다.
|
|
|
|
```text
|
|
({altText})
|
|
```
|
|
|
|
예를 들어 `altText: "플라워"` 이면 `(플라워)` 로 전송된다.
|
|
`altText`를 `(플라워)`처럼 보내도 builder가 바깥 괄호를 제거한 뒤 다시 렌더링한다.
|
|
|
|
### Builder semantic validation
|
|
|
|
`chat.send-message`는 schema validation 외에 아래 규칙도 검사한다.
|
|
|
|
#### 공통
|
|
|
|
- 최종적으로 만들어진 메시지 전체 텍스트는 비어 있으면 안 된다
|
|
- `segments`가 모두 비어 있거나 렌더링 결과가 빈 문자열이면 거부된다
|
|
|
|
#### mention 규칙
|
|
|
|
- `userId`는 양의 정수여야 한다
|
|
- producer에서는 숫자 대신 문자열 사용을 권장한다
|
|
- `displayText`는 비어 있으면 안 된다
|
|
- 같은 `userId`를 여러 번 멘션하면 `extra.mentions[].at` 배열로 합쳐진다
|
|
- 같은 `userId`를 서로 다른 길이의 `displayText`로 섞어 보내면 거부된다
|
|
|
|
#### emoticon 규칙
|
|
|
|
- `id`는 trim 후 비어 있으면 안 된다
|
|
- `altText`는 trim 후 비어 있으면 안 된다
|
|
- `altText` 내부에는 `@`, `(`, `)` 문자가 들어가면 안 된다
|
|
- 같은 `(id, 렌더링 길이)` 조합의 이모티콘은 `extra.emojis.items[].at` 배열로 합쳐진다
|
|
|
|
#### `extra` 생성 규칙
|
|
|
|
producer가 `extra`를 직접 만들지 않는다.
|
|
builder가 최종 텍스트를 기준으로 아래 구조를 자동 생성한다.
|
|
|
|
```json
|
|
{
|
|
"mentions": [
|
|
{
|
|
"user_id": 6215844374579825921,
|
|
"at": [1],
|
|
"len": 13
|
|
}
|
|
],
|
|
"emojis": {
|
|
"total_item": 1,
|
|
"total_len": 5,
|
|
"items": [
|
|
{
|
|
"id": "1200281_004",
|
|
"len": 5,
|
|
"at": [1]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
주의:
|
|
|
|
- `mentions[].at` 는 메시지 안의 `@` anchor 순번이다
|
|
- `emojis.items[].at` 는 메시지 안의 `(` anchor 순번이다
|
|
- `len` 은 렌더링된 문자열 길이 기준이다
|
|
- `total_item` 은 이모티콘 총 출현 횟수다
|
|
- `total_len` 은 각 이모티콘 렌더링 길이의 합이다
|
|
|
|
### 예시: 추천 전송
|
|
|
|
```json
|
|
{
|
|
"schema": "dakao.command.v1",
|
|
"id": "cmd-msg-001",
|
|
"type": "chat.send-message",
|
|
"source": "admin-panel",
|
|
"correlationId": "trace-20260417-001",
|
|
"replySubject": "dakao.result.admin-panel",
|
|
"payload": {
|
|
"chatroomId": "123456789012345678",
|
|
"segments": [
|
|
{ "kind": "text", "text": "😄 " },
|
|
{
|
|
"kind": "mention",
|
|
"userId": "6215844374579825921",
|
|
"displayText": "날으는꼴뚜기/95/여/D"
|
|
},
|
|
{ "kind": "text", "text": " " },
|
|
{ "kind": "emoticon", "id": "1200281_004", "altText": "플라워" },
|
|
{ "kind": "emoticon", "id": "1200281_003", "altText": "네잎클로버" }
|
|
],
|
|
"type": 1,
|
|
"noSeen": false,
|
|
"scope": 1,
|
|
"silence": false
|
|
}
|
|
}
|
|
```
|
|
|
|
위 payload는 내부적으로 대략 아래 LOCO 메시지로 변환된다.
|
|
|
|
```json
|
|
{
|
|
"text": "😄 @날으는꼴뚜기/95/여/D (플라워)(네잎클로버)",
|
|
"extra": "{\"mentions\":[{\"user_id\":6215844374579825921,\"at\":[1],\"len\":13}],\"emojis\":{\"total_item\":2,\"total_len\":12,\"items\":[{\"id\":\"1200281_004\",\"len\":5,\"at\":[1]},{\"id\":\"1200281_003\",\"len\":7,\"at\":[2]}]}}"
|
|
}
|
|
```
|
|
|
|
## Result API
|
|
|
|
응답이 필요한 경우 producer는 command에 `replySubject`를 포함해야 한다.
|
|
consumer는 처리 후 `replySubject`로 결과 object를 publish한다.
|
|
|
|
### 공통 Result envelope
|
|
|
|
```json
|
|
{
|
|
"schema": "dakao.result.v1",
|
|
"id": "cmd-msg-001",
|
|
"type": "chat.send-message",
|
|
"status": "succeeded",
|
|
"handledAt": "2026-04-17T12:34:56.789Z",
|
|
"correlationId": "trace-20260417-001",
|
|
"result": {}
|
|
}
|
|
```
|
|
|
|
### 공통 필드
|
|
|
|
| 필드 | 타입 | 설명 |
|
|
| --------------- | ------ | --------------------------------------- |
|
|
| `schema` | string | 현재는 반드시 `dakao.result.v1` |
|
|
| `id` | string | 원본 command ID |
|
|
| `type` | string | 원본 command type |
|
|
| `status` | string | `succeeded` 또는 `failed` |
|
|
| `handledAt` | string | ISO-8601 timestamp |
|
|
| `correlationId` | string | 원본 correlationId가 있으면 그대로 전달 |
|
|
| `result` | object | 성공 시 포함 |
|
|
| `error` | object | 실패 시 포함 |
|
|
|
|
### Success result
|
|
|
|
`chat.send-text`와 `chat.send-message`의 성공 응답 구조는 동일하다.
|
|
|
|
```json
|
|
{
|
|
"schema": "dakao.result.v1",
|
|
"id": "cmd-msg-001",
|
|
"type": "chat.send-message",
|
|
"status": "succeeded",
|
|
"handledAt": "2026-04-17T12:34:56.789Z",
|
|
"correlationId": "trace-20260417-001",
|
|
"result": {
|
|
"chatroomId": "123456789012345678",
|
|
"messageLength": 31,
|
|
"hasAttachment": true
|
|
}
|
|
}
|
|
```
|
|
|
|
| 필드 | 타입 | 설명 |
|
|
| --------------- | ------- | ---------------------------- |
|
|
| `chatroomId` | string | 대상 채팅방 ID |
|
|
| `messageLength` | number | 실제 전송된 최종 메시지 길이 |
|
|
| `hasAttachment` | boolean | attachment가 있으면 포함 |
|
|
|
|
### Failure result
|
|
|
|
```json
|
|
{
|
|
"schema": "dakao.result.v1",
|
|
"id": "cmd-msg-001",
|
|
"type": "chat.send-message",
|
|
"status": "failed",
|
|
"handledAt": "2026-04-17T12:34:56.789Z",
|
|
"correlationId": "trace-20260417-001",
|
|
"error": {
|
|
"code": "invalid_command",
|
|
"message": "emoticon.altText must not contain '@', '(' or ')': \"(bad@text)\"",
|
|
"retryable": false
|
|
}
|
|
}
|
|
```
|
|
|
|
| 필드 | 타입 | 설명 |
|
|
| ----------- | ------- | ------------------------------- |
|
|
| `code` | string | 오류 코드 |
|
|
| `message` | string | 사람이 읽을 수 있는 오류 메시지 |
|
|
| `retryable` | boolean | 재시도 권장 여부 |
|
|
|
|
### 현재 사용되는 오류 코드
|
|
|
|
| 코드 | retryable | 의미 |
|
|
| -------------------------- | --------- | ----------------------------------------------- |
|
|
| `invalid_command` | `false` | envelope/payload/schema/builder validation 실패 |
|
|
| `command_execution_failed` | `true` | LOCO 전송 등 실행 단계 실패 |
|
|
|
|
## 응답 publish 조건
|
|
|
|
아래 조건이 모두 충족될 때만 실패 응답을 publish할 수 있다.
|
|
|
|
- `replySubject` 존재
|
|
- `id` 존재
|
|
- `type` 존재
|
|
|
|
따라서 malformed payload를 보내더라도 `replySubject`가 없으면 실패 응답은 발행되지 않는다.
|
|
producer가 처리 결과를 반드시 받아야 한다면 `replySubject`를 항상 넣는 것을 권장한다.
|
|
|
|
## 운영 권장사항
|
|
|
|
### 새 producer는 `chat.send-message`만 사용
|
|
|
|
권장 이유:
|
|
|
|
- 멘션과 이모티콘을 구조적으로 표현할 수 있다
|
|
- `extra`를 producer가 직접 조립하지 않아도 된다
|
|
- semantic validation이 추가로 수행된다
|
|
- 향후 레거시 `chat.send-text` 제거 시 마이그레이션 부담이 적다
|
|
|
|
### `chatroomId`와 `userId`는 문자열 사용
|
|
|
|
- `userId`는 int64 범위일 수 있으므로 JSON number 대신 string 사용을 권장한다
|
|
- `chatroomId`도 실운영에서는 decimal string으로 통일하는 것이 안전하다
|
|
|
|
### `replySubject`는 항상 지정
|
|
|
|
- 성공/실패를 추적하려면 `replySubject`를 항상 넣는 것이 좋다
|
|
- `correlationId`도 함께 넣어두면 producer 로그와 결과 로그를 쉽게 연결할 수 있다
|
|
|
|
### `send-text` 사용 시 주의
|
|
|
|
- `extra` 구조를 잘못 만들면 consumer 단계에서는 걸러지지 않는다
|
|
- 멘션, 유니코드 이모지, 카카오톡 이모티콘 혼합 메시지는 `send-message` 사용을 권장한다
|
|
|
|
## 요약
|
|
|
|
- 레거시: `dakao.command.chat.send-text.v1` + `type: "chat.send-text"`
|
|
- 권장: `dakao.command.chat.send-message.v1` + `type: "chat.send-message"`
|
|
- 결과 스키마는 공통으로 `dakao.result.v1`
|
|
- 신규 API는 `segments`를 받아 builder 기반으로 `text`와 `extra`를 안전하게 생성한다
|