# 通用确认消息方案

本文定义 App 私聊中可操作确认消息的后端方案。首个业务场景是 `host / agency / bd` 身份邀请，后续其他业务只新增 `business_type` 处理器，不改变 Flutter 的通用消息渲染和确认接口。

## 目标

- 腾讯云 IM 私聊里支持通用确认消息，App 可以展示文案和 `Accept / Reject` 等操作按钮。
- App 点击按钮后只提交 `confirm_id` 和动作，不提交业务参数。
- 后端根据 `confirm_id` 查出业务类型、业务主键、发送人、接收人和当前状态，再调用对应 owner service 执行业务。
- 处理成功后确认消息进入终态，App 再次渲染同一条 IM 时按钮置灰。
- 当前用户只能处理发给自己的确认消息，不能替别人确认，也不能枚举别人的消息状态。

## 非目标

- 不用 `confirm` 表替代业务事实表。`role_invitations.status` 仍然是身份邀请的权威状态。
- 不让客户端传 `business_type`、`business_id`、`sender_user_id` 或 `receiver_user_id` 来决定业务行为。
- 不把确认消息做成房间状态、连接态或腾讯云 IM 会话状态的 owner。
- 本方案不包含 `bd_leader` 邀请，当前只覆盖 `host / agency / bd`。

## 服务边界

| 模块 | 职责 |
| --- | --- |
| `gateway-service` | 提供 `/api/v1` HTTP 入口，透传当前登录用户和 `app_code`，不直接写确认表 |
| `message action module` | 确认消息 owner，首版落在 `activity-service/internal/service/message`；负责确认表、状态机、幂等和业务分发 |
| `user-service` | `host / agency / bd` 业务 owner，负责 `role_invitations` 和 `ProcessRoleInvitation` |
| `notice-service` | 只负责把确认消息投递到腾讯云 IM C2C，不执行确认业务 |
| 腾讯云 IM | 私聊消息、离线、漫游和客户端长连接 |

首版物理落点建议：

- 确认表放在 `hyapp_activity`，由 `activity-service` 的 message 模块管理。
- `gateway-service` 新增 action confirm HTTP handler，内部调用 activity-service gRPC。
- `notice-service` 消费 message action outbox，发送腾讯 IM C2C 自定义消息。

## 总流程

```mermaid
sequenceDiagram
  participant A as Sender App
  participant Gateway as gateway-service
  participant User as user-service
  participant UserDB as hyapp_user
  participant Message as activity-service message module
  participant MsgDB as hyapp_activity
  participant Notice as notice-service
  participant TIM as Tencent IM
  participant B as Receiver App

  A->>Gateway: 创建 host/agency/bd 邀请
  Gateway->>User: InviteHost / InviteAgency / InviteBD
  User->>UserDB: tx 写 role_invitations + user_outbox
  User-->>Gateway: invitation
  Gateway-->>A: invitation
  Message->>UserDB: consume RoleInvitationCreated
  Message->>MsgDB: 创建 message_action_confirms + message_action_outbox
  Notice->>MsgDB: consume ConfirmMessageCreated
  Notice->>TIM: C2C TIMCustomElem(type=im_confirm)
  TIM-->>B: IM 确认消息
  B->>Gateway: POST /api/v1/message/action-confirms/{confirm_id}/accept
  Gateway->>Message: AcceptActionConfirm
  Message->>MsgDB: pending -> processing
  Message->>User: ProcessRoleInvitation(action=accept)
  User->>UserDB: tx 推进 role_invitations 终态
  Message->>MsgDB: processing -> accepted
  Gateway-->>B: confirm status accepted
```

## 数据表

### message_action_confirms

确认消息的当前状态表。

```sql
CREATE TABLE message_action_confirms (
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  confirm_id VARCHAR(96) NOT NULL,
  business_type VARCHAR(64) NOT NULL,
  business_subtype VARCHAR(64) NOT NULL DEFAULT '',
  business_id VARCHAR(96) NOT NULL,
  sender_user_id BIGINT NOT NULL,
  receiver_user_id BIGINT NOT NULL,
  status VARCHAR(32) NOT NULL,
  message_text VARCHAR(1024) NOT NULL,
  actions_json JSON NOT NULL,
  payload_json JSON NULL,
  source_name VARCHAR(64) NOT NULL,
  source_event_id VARCHAR(128) NOT NULL,
  processing_action VARCHAR(32) NOT NULL DEFAULT '',
  processing_command_id VARCHAR(96) NOT NULL DEFAULT '',
  locked_by VARCHAR(128) NOT NULL DEFAULT '',
  lock_until_ms BIGINT NOT NULL DEFAULT 0,
  processed_action VARCHAR(32) NOT NULL DEFAULT '',
  processed_command_id VARCHAR(96) NOT NULL DEFAULT '',
  processed_by_user_id BIGINT NULL,
  processed_at_ms BIGINT NULL,
  expire_at_ms BIGINT NULL,
  created_at_ms BIGINT NOT NULL,
  updated_at_ms BIGINT NOT NULL,
  PRIMARY KEY (app_code, confirm_id),
  UNIQUE KEY uk_confirm_source_event (app_code, source_name, source_event_id),
  KEY idx_confirm_receiver_status (app_code, receiver_user_id, status, created_at_ms),
  KEY idx_confirm_peer (app_code, receiver_user_id, sender_user_id, created_at_ms),
  KEY idx_confirm_business (app_code, business_type, business_id)
);
```

字段规则：

- `confirm_id` 由服务端生成，例如 `cfm_xxx`。
- `business_type` 首版支持 `role_invitation`。
- `business_subtype` 首版支持 `host`、`agency`、`bd`。
- `business_id` 对 `role_invitation` 来说就是 `role_invitations.invitation_id`。
- `sender_user_id` 是邀请发起人，`receiver_user_id` 是目标用户。
- `message_text` 是 IM 展示快照，业务判断不能依赖它。
- `actions_json` 首版为 `["accept","reject"]`。
- `payload_json` 只放展示扩展，例如邀请人昵称、公会名、头像等。
- `source_name + source_event_id` 用于从 owner outbox 重试时幂等创建确认消息。

### message_action_outbox

确认消息投递事件表，由 `notice-service` 消费后发腾讯 IM。

```sql
CREATE TABLE message_action_outbox (
  app_code VARCHAR(32) NOT NULL DEFAULT 'lalu',
  event_id VARCHAR(128) NOT NULL,
  event_type VARCHAR(64) NOT NULL,
  confirm_id VARCHAR(96) NOT NULL,
  receiver_user_id BIGINT NOT NULL,
  status VARCHAR(32) NOT NULL,
  payload_json JSON NOT NULL,
  created_at_ms BIGINT NOT NULL,
  retry_count INT NOT NULL DEFAULT 0,
  last_error VARCHAR(512) NOT NULL DEFAULT '',
  PRIMARY KEY (app_code, event_id),
  KEY idx_message_action_outbox_status (app_code, status, created_at_ms)
);
```

首版事件：

- `ConfirmMessageCreated`：发送一条新的 `im_confirm`。
- 后续如果需要跨设备实时置灰，可新增 `ConfirmMessageProcessed`，投递状态变更 IM。首版可以通过状态接口刷新。

## 状态机

| 状态 | 说明 |
| --- | --- |
| `pending` | 待处理，App 展示可点击按钮 |
| `processing` | 后端正在执行，App 按钮置灰并显示处理中 |
| `accepted` | 已接受，终态 |
| `rejected` | 已拒绝，终态 |
| `cancelled` | 业务方取消，终态 |
| `expired` | 超时未处理，终态 |
| `failed` | 后端处理失败且需要人工排查，终态 |

状态推进规则：

- 只有 `receiver_user_id == 当前登录用户` 才能接受或拒绝。
- `pending` 才能进入 `processing`。
- `processing` 通过 `locked_by + lock_until_ms` 防止重复点击并发执行。
- owner service 成功后，`processing` 进入 `accepted` 或 `rejected`。
- 如果服务在 owner service 成功后、confirm 状态更新前崩溃，下一次同 `confirm_id` 请求必须用 `business_type + business_id` 查询 owner 当前事实，修复 confirm 状态。

## 业务类型

### role_invitation

首版处理 `host / agency / bd`。

| subtype | business_id | accept 动作 | reject 动作 |
| --- | --- | --- | --- |
| `host` | `role_invitations.invitation_id` | 调 user-service `ProcessRoleInvitation(action=accept)` | 调 user-service `ProcessRoleInvitation(action=reject)` |
| `agency` | `role_invitations.invitation_id` | 调 user-service `ProcessRoleInvitation(action=accept)` | 调 user-service `ProcessRoleInvitation(action=reject)` |
| `bd` | `role_invitations.invitation_id` | 调 user-service `ProcessRoleInvitation(action=accept)` | 调 user-service `ProcessRoleInvitation(action=reject)` |

`role_invitation` 的最终状态以 user-service 为准。confirm 模块只保存按钮状态和业务路由。

## HTTP 接口

所有接口都走 `/api/v1` envelope。

### 接受确认消息

地址：

```text
POST /api/v1/message/action-confirms/{confirm_id}/accept
```

参数：

```json
{
  "command_id": "cfm_123_accept_001"
}
```

返回值：

```json
{
  "confirm_id": "cfm_123",
  "business_type": "role_invitation",
  "business_subtype": "host",
  "business_id": "987",
  "status": "accepted",
  "processed_action": "accept",
  "processed_at_ms": 1710000001000
}
```

相关 IM：收到 `type=im_confirm` 且 `confirm_id=cfm_123` 的消息后，点击 `accept` 调此接口。

### 拒绝确认消息

地址：

```text
POST /api/v1/message/action-confirms/{confirm_id}/reject
```

参数：

```json
{
  "command_id": "cfm_123_reject_001",
  "reason": ""
}
```

返回值：

```json
{
  "confirm_id": "cfm_123",
  "business_type": "role_invitation",
  "business_subtype": "host",
  "business_id": "987",
  "status": "rejected",
  "processed_action": "reject",
  "processed_at_ms": 1710000001000
}
```

相关 IM：收到 `type=im_confirm` 且 `confirm_id=cfm_123` 的消息后，点击 `reject` 调此接口。

### 批量查询确认状态

地址：

```text
POST /api/v1/message/action-confirms/status
```

参数：

```json
{
  "confirm_ids": ["cfm_123", "cfm_456"]
}
```

返回值：

```json
{
  "items": [
    {
      "confirm_id": "cfm_123",
      "business_type": "role_invitation",
      "business_subtype": "host",
      "business_id": "987",
      "status": "accepted",
      "processed_action": "accept",
      "processed_at_ms": 1710000001000
    }
  ]
}
```

相关 IM：App 打开会话或回到前台时，收集当前页面内的 `confirm_id` 后调用该接口刷新按钮状态。

### 按会话查询确认状态

地址：

```text
GET /api/v1/message/action-confirms?peer_user_id=10001&page_size=50
```

参数：

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `peer_user_id` | 是 | 对方用户 ID；当前用户从 token 取，不能由客户端传 |
| `page_size` | 否 | 默认 50，最大 100 |
| `page_token` | 否 | 分页游标 |

返回值：

```json
{
  "items": [
    {
      "confirm_id": "cfm_123",
      "sender_user_id": "10001",
      "receiver_user_id": "10002",
      "business_type": "role_invitation",
      "business_subtype": "host",
      "business_id": "987",
      "status": "pending",
      "processed_action": "",
      "processed_at_ms": 0,
      "created_at_ms": 1710000000000
    }
  ],
  "next_page_token": ""
}
```

相关 IM：App 如果无法从本地消息列表快速收集 `confirm_id`，可以按当前会话刷新最近确认消息状态。

## IM 负载

腾讯 IM 使用 C2C `TIMCustomElem`。

```json
{
  "type": "im_confirm",
  "version": 1,
  "confirm_id": "cfm_123",
  "business_type": "role_invitation",
  "business_subtype": "host",
  "msg": "Alice has invited you to join ABC guild",
  "status": "pending",
  "actions": [
    {
      "action": "reject",
      "label": "Reject",
      "style": "secondary"
    },
    {
      "action": "accept",
      "label": "Accept",
      "style": "primary"
    }
  ],
  "created_at_ms": 1710000000000,
  "expire_at_ms": 1710604800000
}
```

腾讯 IM 字段建议：

| TIM 字段 | 值 |
| --- | --- |
| `Desc` | `im_confirm` |
| `Ext` | `im_confirm` |
| `Data` | 上面的 JSON 字符串 |

App 只依赖 `type`、`confirm_id`、`msg`、`status` 和 `actions`。`business_type` 只用于日志和埋点，不用于 App 决定业务接口。

## 创建消息规则

`host / agency / bd` 邀请创建成功后，user-service 写 `RoleInvitationCreated` outbox。payload 必须包含：

```json
{
  "event_type": "RoleInvitationCreated",
  "invitation_id": "987",
  "invitation_type": "host",
  "status": "pending",
  "inviter_user_id": "10001",
  "target_user_id": "10002",
  "agency_name": "ABC guild",
  "created_at_ms": 1710000000000
}
```

message action worker 根据该 payload 创建：

- `business_type = role_invitation`
- `business_subtype = invitation_type`
- `business_id = invitation_id`
- `sender_user_id = inviter_user_id`
- `receiver_user_id = target_user_id`
- `actions_json = ["accept","reject"]`

## 错误码

| HTTP | code | 场景 |
| --- | --- | --- |
| 400 | `INVALID_ARGUMENT` | `confirm_id`、`command_id` 或 action 参数非法 |
| 401 | `UNAUTHORIZED` | 未登录或 token 无效 |
| 403 | `PERMISSION_DENIED` | 当前用户不是接收人 |
| 404 | `NOT_FOUND` | `confirm_id` 不存在 |
| 409 | `CONFLICT` | 已处理、已过期、处理中或业务状态不允许操作 |
| 502 | `UPSTREAM_ERROR` | owner service 不可用 |

## 开发顺序

1. 在 activity-service message 模块新增 `message_action_confirms` 和 `message_action_outbox`。
2. 新增 `ActionConfirmService` gRPC：`AcceptActionConfirm`、`RejectActionConfirm`、`BatchGetActionConfirmStatus`、`ListConversationActionConfirms`。
3. gateway 新增 HTTP 接口并调用 action confirm gRPC。
4. user-service 邀请创建事务写 `RoleInvitationCreated` outbox。
5. activity-service 增加 user outbox consumer，创建 confirm row 和 message action outbox。
6. notice-service 增加 message action outbox consumer，发送 `im_confirm`。
7. 补 `role_invitation` business handler，接受/拒绝时调用 user-service `ProcessRoleInvitation`。
8. 补状态修复逻辑：confirm 仍 pending/processing 但 user-service 邀请已经终态时，以 user-service 状态回写 confirm。

## 验证

- 创建 Host 邀请后，能查到 `role_invitations.pending`、`message_action_confirms.pending` 和一条待投递 outbox。
- notice-service 投递后，App 收到 `type=im_confirm`。
- 接收人接受后，`role_invitations.status=accepted`，confirm 状态为 `accepted`。
- 接收人拒绝后，`role_invitations.status=rejected`，confirm 状态为 `rejected`。
- 非接收人调用接受/拒绝接口返回 `PERMISSION_DENIED`。
- 重复点击同一个动作返回同一个终态，不重复创建业务事实。
- 已接受后再拒绝返回 `CONFLICT`，状态接口返回 `accepted`。