wip: baseline changes before channel-conversation-task boundary implementation

2026-07-08 16:23:09 +08:00
parent 89c9e6a066
commit 1298a558e8
139 changed files with 11781 additions and 666 deletions
--- a/docs/superpowers/specs/2026-07-08-channel-conversation-task-boundary-design.md
+++ b/docs/superpowers/specs/2026-07-08-channel-conversation-task-boundary-design.md
@@ -0,0 +1,178 @@
+# 渠道账号、会话与发送任务数据边界设计
+
+> **版本**：v1.0  
+> **日期**：2026-07-08  
+> **状态**：已确认，待实施  
+> **关联文档**：`docs/architecture/2026-07-06-message-customer-interaction-design.md`
+
+---
+
+## 1. 背景与目标
+
+在 `2026-07-06-message-customer-interaction-design.md` 已完成整体架构与数据模型设计的基础上，进一步明确中台与业务系统之间的数据边界，以及“配置 + 选取人员 → 任务发送”的最小可用实现路径。
+
+**本次目标**：
+- 业务系统通过中台 API 维护人员（Person）、渠道身份（ChannelIdentity）、会话（Conversation）、群聊关系；
+- 中台只保存渠道侧最小数据集，业务属性（机构、供应商、合同等）由业务系统写入；
+- 企微官方接口只能拿到有限信息（`userid`、`external_userid`、`chat_id`、群名等），同步接口不得覆盖业务系统写入的字段；
+- 所有出站发送通过 `/api/v1/send` 任务接口驱动，任务与发送日志合并为 `mci_send_record`；
+- 当前阶段不拆分 `openapi` 包，所有修改在现有 `mci-server` 与 `admin-web` 内完成；跑通后下一阶段再独立拆分第三方接入包。
+
+---
+
+## 2. 数据边界设计
+
+### 2.1 中台保存 vs 业务系统维护
+
+| 数据 | 中台保存 | 业务系统维护 | 说明 |
+|------|---------|-------------|------|
+| 人员基础信息 `mci_person` | 是 | 可同步 | 中台保存 `person_code`、`person_name`、`phone`、`person_type`；业务系统可写入或同步，中台不强制唯一来源。 |
+| 业务属性（机构/供应商/合同） | 是字段，业务系统写入 | 是 | `institution_id`、`supplier_id`、`contract_id` 由业务系统赋值，企微同步不覆盖。 |
+| 渠道身份 `mci_channel_identity` | 是 | 可同步 | 中台保存渠道用户 ID（`userid`、`external_userid`、个微 `wxid` 等），属于渠道侧最小数据集。 |
+| 会话 `mci_conversation` | 是 | 可同步/创建 | 中台保存 `channel_conversation_id`、群名、群主等；业务属性由业务系统写入。 |
+| 标签 `mci_tag` | 是 | 可同步 | 标签表达角色、合同、机构、供应商等业务属性，支持层级；业务系统可通过 API 维护。 |
+| 账号-会话绑定 `mci_channel_account_conversation` | 是 | 否 | 发送主备、接收主备属于渠道调度能力，由中台管理。 |
+| 发送内容 | 否（接收最终内容） | 是 | 业务系统渲染最终消息后调用中台发送接口。 |
+| 模板与变量 | 否 | 是 | 中台不保存模板。 |
+
+### 2.2 企微同步的边界
+
+`ChannelAccountService.syncContacts` 与 `syncConversations` 只能写入/更新以下字段：
+
+- `mci_person`：`person_name`（企微返回的昵称/姓名）、`phone`（如有）
+- `mci_channel_identity`：`channel_user_id`、`channel_user_name`、`subject_id`、`channel_type`
+- `mci_conversation`：`conversation_type`、`channel_type`、`channel_conversation_id`、`conversation_name`、`owner_account_id`、`subject_id`、`create_source=1`
+- `mci_conversation_participant`：群成员关系
+
+**禁止行为**：
+- 不得覆盖 `institution_id`、`supplier_id`、`contract_id`；
+- 不得删除业务系统已绑定的标签；
+- 不得修改 `channel_account_conversation` 中业务系统未授权的主备绑定。
+
+---
+
+## 3. 发送任务模型
+
+沿用 `mci_send_record` 单表设计：一次 API 调用产生一个 `task_id`，每个最终目标（人/会话）一条记录。
+
+### 3.1 支持的目标类型
+
+| target_type | 说明 | target_value 示例 |
+|-------------|------|-------------------|
+| `conversation` | 单个会话 | `{"conversation_id": 1001}` |
+| `person` | 单个联系人（单聊） | `{"person_id": 2001}` |
+| `person_list` | 联系人列表 | `{"person_ids": [2001, 2002]}` |
+| `tag` | 标签人群/群聊 | `{"tag_id": 3001, "scope": "all"}` |
+| `rule` | 复合受众规则 | `{"logic": "and", "rules": [...]}` |
+
+### 3.2 渠道策略
+
+`channel_strategy` 描述渠道选择偏好：
+
+```json
+{
+  "channel_type": "wecom",
+  "strategy": "primary",
+  "fallback": true
+}
+```
+
+中台根据目标解析结果选择实际账号：
+- 群聊：从 `mci_channel_account_conversation` 取发送主号，主号不可用 fallback 到备用号；
+- 单聊：取目标人对应的 `ChannelIdentity`，再选择默认 `ChannelAccount`。
+
+### 3.3 结果回调
+
+发送请求可携带 `callback_url`，任务完成后按条或按任务聚合回调业务系统。
+
+---
+
+## 4. 本次实施范围（方案 A）
+
+### 4.1 后端
+
+1. **校验与边界保护**
+   - 在 `ConversationService`、`ChannelAccountService` 的同步方法中增加“业务字段保护”：企微同步不覆盖 `institution_id`、`supplier_id`、`contract_id`。
+   - 在 `SendService.resolveByType` 中增加目标存在性、租户隔离、账号可用性校验。
+
+2. **账号-会话绑定补全**
+   - 确认 `ConversationController.bindAccount` 支持 `binding_type`：1 发送主号、2 发送备用号、3 接收主号、4 接收备用号。
+   - 确认 `SendService.selectSendAccount` 按主备顺序选择。
+
+3. **发送任务端到端**
+   - 验证 `POST /api/v1/send`、`POST /api/v1/send/test` 可正常创建任务、拆解记录、返回 `task_id`。
+   - 验证 `SendMessageConsumer` 可调用 `ChannelAdapter` 实际发送并回写状态。
+
+4. **渠道账号初始化**
+   - 验证 `POST /api/v1/channel-account/init` 支持企微内部账号、企微应用、个微、钉钉/飞书机器人；返回初始化结果或二维码信息。
+
+5. **会话/群聊同步**
+   - 验证 `POST /api/v1/channel-account/{account_id}/sync-conversations` 能拉取账号所在群聊并创建 `Conversation`、`ConversationParticipant`、`ChannelAccountConversation` 默认绑定。
+
+### 4.2 前端
+
+1. **发送页面完善**
+   - `SendRecord.vue` 已支持测试发送和记录查询，补充“选择标签发送”和“选择规则发送”的测试入口。
+   - 在会话/人员列表中提供“发送消息”快捷入口，跳转或填充 `SendRecord.vue` 测试表单。
+
+2. **账号-群绑定页面**
+   - 在 `Conversation.vue` 或新增页面中，支持为会话绑定发送主备号、接收主备号。
+
+3. **标签层级展示**
+   - `Tag.vue` 已支持层级，确认在人员/会话绑定时可以展示多级标签并直接选择。
+
+4. **管理后台权限**
+   - 确认租户管理员、运营操作员、只读用户三类角色已落地，页面按钮按角色显隐。
+
+### 4.3 测试验证
+
+1. **单元/接口测试**
+   - 发送目标解析：conversation、person、tag、rule；
+   - 同步边界：企微同步不覆盖业务字段；
+   - 主备切换：发送主号不可用时启用备用号。
+
+2. **端到端流程**
+   - 使用 mock 渠道适配器或企微测试企业号，完成：
+     1. 创建租户/用户；
+     2. 创建渠道主体；
+     3. 初始化渠道账号；
+     4. 同步/创建会话；
+     5. 绑定发送账号；
+     6. 调用发送任务；
+     7. 查询发送记录与统计。
+
+---
+
+## 5. 验收标准
+
+- [ ] 第三方平台可通过 API 完成：创建 Person、绑定 ChannelIdentity、创建/更新 Conversation、绑定标签、绑定发送账号；
+- [ ] 企微 `sync-contacts` / `sync-conversations` 不覆盖 `institution_id`、`supplier_id`、`contract_id`；
+- [ ] `POST /api/v1/send` 支持 conversation / person / person_list / tag / rule 五种目标类型；
+- [ ] 发送任务按目标拆解为 `mci_send_record` 记录，可查询任务状态、记录列表、统计；
+- [ ] 前端可在“会话/人员/标签”维度完成测试发送，并查看发送记录；
+- [ ] Docker 全栈服务健康，接口可通。
+
+---
+
+## 6. 未来工作
+
+下一阶段（方案 A 验证通过后）将拆分独立的 `openapi` 包：
+- 路径前缀 `/api/v1/open/**`；
+- 面向业务系统的 DTO 更严格，隐藏内部状态字段；
+- 独立的鉴权方式（`X-Tenant-Code` + `X-App-Key`）；
+- 管理后台 API 与第三方 API 代码分离，便于文档生成和权限控制。
+
+---
+
+## 7. 关键文件清单
+
+| 模块 | 文件 |
+|------|------|
+| 发送核心 | `backend/mci-server/src/main/java/com/sino/mci/send/service/SendService.java` |
+| 发送控制器 | `backend/mci-server/src/main/java/com/sino/mci/send/controller/SendController.java` |
+| 会话管理 | `backend/mci-server/src/main/java/com/sino/mci/channel/service/ConversationService.java` |
+| 渠道账号 | `backend/mci-server/src/main/java/com/sino/mci/channel/service/ChannelAccountService.java` |
+| 人员管理 | `backend/mci-server/src/main/java/com/sino/mci/crm/service/PersonService.java` |
+| 发送页面 | `admin-web/src/views/SendRecord.vue` |
+| 会话页面 | `admin-web/src/views/Conversation.vue` |
+| 标签页面 | `admin-web/src/views/Tag.vue` |