# 消息与客户互动中台架构设计

> **需求来源**：1333 统一消息中心、1851 企微机器人报备信息、2092 IVR 语音配置  
> **版本**：v0.7  
> **日期**：2026-07-06  
> **状态**：草案（新增项目结构、升级 Spring Boot 4.1）

---

## 变更记录

| 版本 | 日期 | 变更说明 |
|------|------|---------|
| v0.1 | 2026-07-01 | 完成第一节整体架构、第二节核心领域模型与数据表设计 |
| v0.2 | 2026-07-01 | 完成第三节消息编排层详细设计 |
| v0.3 | 2026-07-01 | 完成第四节技术选型 |
| v0.4 | 2026-07-03 | 范围收缩：移除业务事件触发规则，出站发送由业务系统直接调用；保留入站消息处理工作流和 IVR 独立流程 |
| v0.5 | 2026-07-03 | 进一步简化：中台不保存模板和变量；去掉中台调用业务系统能力接口；去掉定时发送；发送任务自带 callback_url；新增账号体系设计 |
| v0.6 | 2026-07-06 | 数据模型修正：合并发送任务/日志；租户=业务系统；企微主体扩展为渠道主体；身份与账号重新定义；账号-群绑定增加收消息主备；会话存档复用消息事件表；角色统一成标签；会话增加标签接口；补充渠道账号初始化 API |
| v0.7 | 2026-07-06 | 新增第五节项目目录结构；技术栈升级为 Spring Boot 4.1.x；明确项目独立于 sa-server 位于平级目录；标签表去掉分类字段；新增入站消息轻量流程编排设计；前端增加入站流程编排页面 |

---

# 第一节：整体架构设计

## 1.1 设计背景与目标

基于三个需求（1333 统一消息中心、1851 企微机器人报备、2092 IVR 语音外呼）和现有 `sa-server` 代码，抽象出一个面向未来的**消息与客户互动中台**。

**核心目标**：
- 把“收发消息、联系客户、企微客户营销”统一成一套平台级能力；
- 首期聚焦 1851 的企微场景；
- 为 1333（内部通知/流转）和 2092（IVR 外呼）预留扩展位；
- 通过事件总线兼容现有业务系统，不强制迁移；
- 实现“客户说话 → 中台识别 → 调用业务系统 → 回写结果 → 回复客户”的闭环。

**范围约束**：
- 中台定位为**消息发送网关 + 渠道资源管理中心**；
- 中台不保存模板和变量，业务系统直接传入已渲染的最终内容；
- 中台不主动调用业务系统能力接口，入站消息通过 webhook/事件推送给业务系统，由业务系统自行处理并回呼中台发送；
- 中台不承载业务系统的“触发条件 + 发送规则”；
- 中台保留的配置：渠道资源、发送策略、发送记录、账号权限、入站消息 webhook、IVR 流程（预留）。

## 1.2 整体架构图

```
┌─────────────────────────────────────────────────────────────┐
│                         业务系统                              │
│  数据服务：合同 / 供应商 / 订单 / 人员 / 组织 / 客户            │
│  业务能力 API：开案 / 咨询 / 查状态 / 审批 / 创建跟进 / 下发 KPI │
│  模板与变量：业务系统自行维护                                 │
└─────────────────────────┬───────────────────────────────────┘
                          │  ① 调发送 API  ② 接收入站 webhook
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                        消息与客户互动中台                      │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                    管理后台                              │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │  │
│  │  │  渠道资源    │  │  账号权限    │  │  发送策略    │    │  │
│  │  │  管理        │  │  管理        │  │  配置        │    │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘    │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │  │
│  │  │  入站 webhook│  │  发送记录    │  │  IVR 流程   │    │  │
│  │  │  配置        │  │  查询        │  │  (2092 预留)│    │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘    │  │
│  └───────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                    消息编排层                            │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │  │
│  │  │  入站处理    │  │  出站调度    │  │  策略执行    │    │  │
│  │  │ 归一化/意图  │  │ 渠道选择     │  │ 频率/重试   │    │  │
│  │  │ 识别/webhook│  │ 精准定位     │  │            │    │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘    │  │
│  └───────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                    渠道适配层                            │  │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  │  │
│  │  │ 微信渠道  │  │ 钉钉适配  │  │ 飞书适配  │  │ IVR 适配  │  │
│  │  │(企微收 + │  │(预留扩展)│  │(预留扩展)│  │(预留扩展)│  │
│  │  │个人号发) │  │          │  │          │  │          │  │
│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘  │  │
│  └───────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  共享服务层                                              │  │
│  │  客户关系中心 + 身份中心 + 标签中心 + 事件总线             │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## 1.3 各层职责

| 层级 | 核心职责 | 首期 1851 范围 |
|------|---------|---------------|
| 业务系统 | 维护合同、供应商、人员、客户等主数据；维护模板和变量；暴露业务能力 API；自行判断触发条件 | 复用现有模块 |
| 管理后台 | 渠道资源、账号权限、发送策略、入站 webhook、发送记录、IVR 流程配置 | 各业务系统独立管理自己的资源 |
| 消息编排层 | 入站消息归一化、LLM 意图识别、webhook 推送；出站目标解析与渠道调度、策略执行 | 实现核心骨架，服务 1851 场景 |
| 渠道适配层 | 封装各渠道的发送/接收/资源管理/回调 | 实现微信渠道（企微收 + 个人号发） |
| 共享服务层 | 客户关系、身份映射、标签、事件总线 | 建最小可用版本 |

## 1.4 渠道适配层详细设计

### 微信渠道（首期实现）

| 方向 | 通道 | 技术方式 | 关键能力 |
|------|------|---------|---------|
| 收消息 | 企业微信 | 会话存档回调通知 + 主动拉取 / 群机器人 / Webhook 回调 | 企微只推 `msgaudit_notify` 通知，中台主动拉取消息内容 |
| 发消息 | 个人微信 | pywechat + PC 微信客户端 | 个人号在群里发消息，需要账号池和调度 |

### 微信渠道需要维护的映射

| 映射 | 内容 | 用途 |
|------|------|------|
| 群 → 企微 chat_id | 会话存档中的群 ID | 收消息时识别群 |
| 群 → 个人微信号 | 哪个个人号在群里、发送主号/发送备用号 | 发消息时选号 |
| 群 → 业务渠道/合同/机构 | 群对应的业务实体 | 上下文匹配和意图识别 |

### 企微会话存档收消息机制

复用 `supplier-manager` 已有技术选型：

- `weixin-java-cp`（me.chanjar.weixin.cp）封装企微 CP API；
- `com.tencent.wework.Finance` SDK（C 库通过 JNI 调用）进行会话存档拉取与解密；
- 动态加载 native 库（Windows `.dll` / Linux `.so`）。

企微不会直接推送消息内容，只推送**有新消息的通知事件** `msgaudit_notify`（回调间隔 15 秒）。中台收到通知后，通过 Finance SDK 的 `GetChatData` 按 seq 游标分页拉取，再调用 `DecryptData` 解密。

```
企微 ──msgaudit_notify──► 中台适配器
                              │
                              ▼
                    Finance.GetChatData(seq, limit)
                              │
                              ▼
                         Finance.DecryptData
                              │
                              ▼
                    归一化为 MessageEvent
                              │
                              ▼
                    message_source = session_archive
```

企微会话存档相关 API：

| API | 用途 |
|-----|------|
| 产生会话回调事件 | 企微推送 `msgaudit_notify` 通知 |
| 获取会话内容 | 拉取实际聊天消息 |
| 获取会话内容存档开启成员列表 | 知道哪些员工已开启存档 |
| 获取会话内容存档内部群信息 | 拉取内部群基本信息 |
| 获取会话同意情况 | 外部联系人是否同意存档 |
| 客户同意进行聊天内容存档事件回调 | 同意/拒绝状态变更回调 |
| 获取媒体文件 | 下载图片/语音/视频/文件等媒体内容 |

### 其他渠道（预留扩展）

| 渠道 | 收发方式 | 备注 |
|------|---------|------|
| 钉钉 | Webhook 收发 | 后期按同样模式接入 |
| 飞书 | Webhook 收发 | 后期按同样模式接入 |
| IVR | 天润 API + 回调 | 2092 阶段接入 |

## 1.5 共享服务层

### 客户关系中心
维护一张**客户关系图谱**：

| 实体 | 说明 |
|------|------|
| 联系人 | 业务人员/客户/司机，含业务身份和渠道身份 |
| 渠道身份 | 企微 external_userid、个人微信号、钉钉 userid、飞书 open_id |
| 群聊 | chat_id、群名、关联业务实体、收发账号绑定 |
| 关系 | 人与群、人与人的关系 |

### 身份中心
维护“业务人员 ID → 各渠道账号”的映射：

```json
{
  "person_id": "P001",
  "wecom_external_userid": "wxf1xxx",
  "wechat_personal_id": "wxid_xxx",
  "dingtalk_userid": "ding1xxx",
  "feishu_open_id": "fei1xxx",
  "phone": "138..."
}
```

### 标签中心
支持两类标签：

| 标签类型 | 示例 |
|---------|------|
| 业务标签 | 销售、区域经理、子公司、华北、合同 C001 |
| 渠道标签 | 企微活跃用户、群管理员、培训未读 |

### 事件总线
- 所有入站/出站事件通过事件总线流转；
- 业务系统可订阅事件。

## 1.6 业务身份模型

每个人在中台都有一个多维业务身份：

```json
{
  "business_identity": {
    "person_id": "P001",
    "type": "internal",
    "org": {
      "institution": "华北分公司",
      "department": "销售一部"
    },
    "tags": ["sales", "华北分公司", "销售一部"],
    "supplier": {
      "supplier_id": "S001",
      "is_subsidiary": true,
      "region": "华北"
    },
    "contract": {
      "contract_id": "C001",
      "contract_tag": "sales"
    }
  }
}
```

## 1.7 编排层核心能力

| 组件 | 职责 |
|------|------|
| 入站处理 | 接收消息 → 归一化 → 上下文匹配 → LLM 意图识别 → 推送到业务系统 webhook |
| 出站调度 | 目标解析 → 渠道选择 → 账号选择 → 发送（由业务系统直接触发） |
| 意图识别引擎 | LLM / 规则识别消息意图和槽位 |
| 精准定位引擎 | 根据业务系统传入的标签/属性/业务条件解析目标接收人 |
| 策略执行 | 频率控制、重试、时间窗、黑名单、主备切换 |

## 1.8 入站消息处理流程

> 示例：服务商在群里发“我要下单，客户张三，地址北京”

1. **收消息**：企微推送 `msgaudit_notify` 回调事件，中台调用「获取会话内容」API 拉取群消息；
2. **归一化**：微信适配器转成标准 `MessageEvent`；
3. **来源绑定**：根据群 ID 找到绑定的 pywechat 发信号；
4. **上下文匹配**：根据群/人找到合同、机构、服务商、角色；
5. **入站流程编排**：按租户配置的入站流程执行，节点包括意图识别、条件分支、webhook 推送、自动回复；
6. **推送业务系统**：将消息内容、上下文、意图识别结果推送到流程节点指定的业务系统 webhook URL；
7. **业务系统处理**：业务系统根据意图调用自身能力（开案、创建咨询、查状态）；
8. **业务系统回呼中台**：业务系统调用中台发送 API，传入最终回复内容；
9. **中台发送回复**：中台选择渠道和发信号，回复群聊。

> 说明：中台做入站消息接收、归一化、上下文绑定、流程编排、LLM 意图识别和 webhook 推送；不主动调用业务系统能力；流程可通过前端轻量画布配置。

### 入站 webhook 推送示例

```json
POST {business_system_inbound_webhook_url}
Headers: X-Msg-Platform-Signature: xxx

{
  "event_id": "evt_20260703120000_001",
  "tenant_code": "rescue",
  "channel_type": "wecom",
  "direction": "in",
  "event_type": "message",
  "conversation_id": 1001,
  "person_id": 2001,
  "account_id": 3001,
  "content": {
    "type": "text",
    "body": "我要下单，客户张三，地址北京"
  },
  "intent": {
    "intent": "create_order",
    "confidence": 0.95,
    "slots": {
      "customer_name": "张三",
      "address": "北京"
    },
    "missing_slots": ["phone"],
    "requires_confirmation": true
  },
  "business_context": {
    "contract_id": "C001",
    "supplier_id": "S001",
    "institution_id": "I001",
    "tag": "dispatcher"
  },
  "create_time": "2026-07-03T12:00:00"
}
```

## 1.9 出站消息处理流程

> 示例：业务系统要发培训通知

1. 业务系统自行判断触发时机、业务条件、文案变量，并渲染出最终内容；
2. 业务系统调用中台发送接口，传入目标描述（标签/属性/人员/会话）和最终内容；
3. 中台精准定位引擎解析目标描述；
4. 从客户关系中心查出目标人/会话；
5. 从身份中心查这些人的可用渠道；
6. 编排层按策略选渠道和发信号；
7. 渠道适配器实际发送；
8. 发送结果通过发送记录中的 `callback_url` 回传业务系统。

> **说明**：模板、变量、触发规则、业务条件、变量取值均由业务系统完成；中台只做“接收发送请求 → 解析目标 → 选择渠道 → 执行发送 → 回收结果 → 回调”。

### 发送请求示例

```json
POST /msg-platform/api/v1/send
Headers: X-Tenant-Code: rescue

{
  "target": {
    "type": "rule",
    "rule": {
      "tag": "rescue_dispatcher",
      "contract_id": "C001"
    }
  },
  "content": {
    "type": "text",
    "body": "技师姓名：张师傅\n技师电话：13800138000\n预计到达时间：30分钟"
  },
  "channel_strategy": {
    "priority": ["wechat_personal"]
  },
  "callback_url": "https://rescue.sino.com/api/msg-platform/callback"
}
```

## 1.10 关键设计原则

1. **中台是消息发送网关 + 渠道资源管理中心**；
2. **业务系统自行控制触发时机、发送规则、模板和变量**；
3. **业务系统只按业务语义描述目标**，不感知具体渠道账号；
4. **中台不主动调用业务系统能力接口**，入站消息通过 webhook 推送；
5. **渠道适配器只暴露统一接口**：发送、接收、资源同步、结果回调；
6. **中台沉淀渠道身份和客户关系**：业务身份由业务系统维护；
7. **发送结果通过任务级 callback_url 回传**；
8. **首期聚焦、预留扩展**：1851 企微先行，1333/2092 按相同分层接入。

## 1.11 与现有系统的关系

| 现有模块 | 在新架构中的位置 | 处理方式 |
|---------|----------------|---------|
| `admin/supplier-manage` 企微 CP | 渠道适配层（企微收）+ 客户关系中心数据来源 | 复用并扩展 |
| `api/call-center` | 渠道适配层（短信/IVR） | 复用底层通道能力 |
| `ns/sa-admin` 事件流转 | 业务系统（触发规则由业务系统维护） | 预留接入 |
| `ns/sa-admin` 合同/供应商/订单 | 业务系统 | 提供数据和 API |

---

# 第二节：核心领域模型与数据表设计

## 2.1 核心领域实体

```
```
┌─────────────────────────────────────────────────────────────┐
│                        业务身份域                             │
│  ┌─────────┐                                                │
│  │ Person  │──1:N Tag（业务标签：角色/合同/机构/供应商等）   │
│  │(联系人) │                                                │
│  └────┬────┘                                                │
│       │ 1:N                                                 │
│       ▼                                                     │
│  ┌─────────────────┐                                        │
│  │ ChannelIdentity │  人在渠道上的身份标识                   │
│  │   (渠道身份)     │  如企微 external_userid、个微 wxid    │
│  └─────────────────┘                                        │
└─────────────────────────────────────────────────────────────┘
                          │
                          │ N:M
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                        群聊与消息域                           │
│  ┌─────────────┐  ┌──────────────────┐  ┌─────────────────┐ │
│  │Conversation │──│ ConversationParticipant                │ │
│  │  (会话)     │  │    (会话参与者)   │  │  Tag（群标签）   │ │
│  └──────┬──────┘  └──────────────────┘                     │ │
│         │                                                   │ │
│         │ 1:N                                               │ │
│         ▼                                                   │ │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              MessageEvent (消息事件)                   │  │
│  │  入站 / 出站 / 回调 / 状态变更 / 会话存档                │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                          │
                          │ 触发 / 引用
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                       编排与账号域                            │
│  ┌────────────────┐  ┌─────────────┐  ┌─────────────────┐   │
│  │FlowDefinition  │  │    Tenant    │  │  PlatformUser   │   │
│  │  (流程定义)     │  │  (业务系统)  │  │  (中台用户)      │   │
│  └────────────────┘  └─────────────┘  └─────────────────┘   │
│  ┌────────────────┐  ┌─────────────────────────────────┐    │
│  │ ChannelSubject │  │          SendRecord             │    │
│  │   (渠道主体)    │  │           发送记录               │    │
│  └────────────────┘  └─────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

## 2.2 实体关系说明

| 实体 | 说明 | 关键关系 |
|------|------|---------|
| Person | 统一联系人 | 1 个 Person 有 N 个 ChannelIdentity；N 个 Tag |
| ChannelIdentity | **人在渠道上的身份标识**（如企微 external_userid、个微 wxid、钉钉 userid） | 属于 1 个 Person，关联 1 个 ChannelSubject |
| ChannelAccount | **用于收发消息的载体账号**（如企微内部账号、pywechat 个微、钉钉机器人、飞书机器人） | 属于 1 个 ChannelSubject |
| ChannelSubject | 渠道主体，一个企业在一个渠道下的主体 | 目前支持 wecom / dingtalk / feishu |
| Conversation | 会话（单聊/群聊） | 有 N 个 ConversationParticipant；N 个 Tag |
| ConversationParticipant | 会话参与者 | 关联 Person + ChannelIdentity |
| ChannelAccountConversation | 账号与群的绑定关系（收/发、主/备） | 关联 ChannelAccount + Conversation |
| MessageEvent | 标准化后的消息事件 | 关联 Conversation、Person、ChannelAccount；会话存档消息 source=session_archive |
| FlowDefinition | 流程编排定义 | IVR 等独立流程 |
| Tag | 标签 | 与 Person / Conversation 多对多；可表达角色、合同、机构、供应商等业务属性 |
| SendRecord | 发送任务与发送日志合并表 | 按 task_id 分组，一条目标对应一条记录 |
| Tenant | 业务系统租户，等同于业务系统 | 中台账号和资源顶层隔离 |
| PlatformUser | 中台用户 | 属于某个 Tenant，拥有角色权限 |

> **ChannelIdentity vs ChannelAccount 区分**：
> - `ChannelIdentity` 是“**人是谁**”在渠道上的映射，比如张三是企微用户 `wxf1xxx`、个微 `wxid_abc`。
> - `ChannelAccount` 是“**用哪个号收发**”的载体，比如用企微员工号 `ZhangSan` 收消息、用 pywechat 个微 `wxid_bot01` 发消息、用钉钉机器人发 webhook。
> - 一个 Person 可以有多个 Identity；一个 ChannelAccount 可能被多个人通过会话间接关联，但账号本身属于渠道主体。

## 2.3 首期 1851 核心表设计

### 2.3.1 租户/业务系统表 `mci_tenant`

> **租户即业务系统**，一个业务系统对应一个租户，作为中台资源和账号的顶层隔离单位。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 租户编码，与业务系统编码一致，如 `contract`、`supplier`、`order`、`rescue` |
| tenant_name | varchar | 租户名称 |
| auth_config | json | 业务系统调用中台时的认证配置 |
| inbound_webhook_url | varchar | 入站消息推送地址 |
| status | tinyint | 状态 |
| create_time | datetime | 创建时间 |

### 2.3.2 联系人表 `mci_person`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| person_code | varchar | 业务人员编码 |
| person_name | varchar | 姓名 |
| phone | varchar | 手机号 |
| person_type | tinyint | 类型：1内部人员 2供应商人员 3客户 4司机 |
| institution_id | bigint | 所属机构/公司 |
| supplier_id | bigint | 供应商 ID |
| status | tinyint | 状态 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |

### 2.3.3 渠道主体表 `mci_channel_subject`

> 由 `mci_wecom_subject` 扩展而来，支持企微、钉钉、飞书多个渠道主体。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户，为空表示平台级共享主体 |
| channel_type | varchar | 渠道类型：`wecom` / `dingtalk` / `feishu` |
| subject_code | varchar | 主体编码 |
| subject_name | varchar | 主体名称 |
| corp_id | varchar | 企微 corp_id（企微用） |
| corp_secret | varchar | 通讯录 secret（企微用） |
| agent_id | varchar | 应用 agent_id（企微用） |
| agent_secret | varchar | 应用 secret（企微用） |
| session_archive_enabled | tinyint | 是否开通会话存档能力 |
| session_archive_private_key | text | 会话存档 RSA 私钥 |
| status | tinyint | 状态 |
| create_time | datetime | 创建时间 |

### 2.3.4 渠道身份表 `mci_channel_identity`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户 |
| person_id | bigint | 联系人 ID |
| channel_type | varchar | 渠道：wecom / wechat_personal / dingtalk / feishu |
| channel_user_id | varchar | 渠道用户 ID |
| channel_user_name | varchar | 渠道昵称 |
| subject_id | bigint | 所属渠道主体 `mci_channel_subject` |
| status | tinyint | 状态 |
| ext_info | json | 渠道扩展信息 |
| create_time | datetime | 创建时间 |

> 说明：`subject_id` 对企微、钉钉、飞书都有意义，指向 `mci_channel_subject`；个微无主体概念时可为空。

### 2.3.5 渠道账号表 `mci_channel_account`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户 |
| account_type | tinyint | 1企微内部账号 2企微应用 3pywechat 个人号 4钉钉机器人 5飞书机器人 |
| channel_type | varchar | wecom / wechat_personal / dingtalk / feishu |
| subject_id | bigint | 所属渠道主体 `mci_channel_subject` |
| account_id | varchar | 账号唯一标识：企微员工=userid，企微应用=agent_id，个微=wxid/bot_code，机器人=robot_id |
| account_name | varchar | 账号名称 |
| session_archive_enabled | tinyint | 是否开启会话存档（企微内部账号用） |
| server_host | varchar | 所在服务器（pywechat 用） |
| login_status | tinyint | 登录状态 |
| online_status | tinyint | 在线状态 |
| risk_level | tinyint | 风险等级 |
| ext_info | json | 渠道扩展字段 |
| status | tinyint | 状态 |
| last_heartbeat | datetime | 最后心跳 |
| create_time | datetime | 创建时间 |

`ext_info` 示例：

```json
// 企微内部账号
{
  "userid": "ZhangSan",
  "department": [1, 2]
}

// 企微应用
{
  "agent_id": "1000002",
  "agent_secret": "..."
}

// pywechat 个人号
{
  "windows_client_id": "client-01",
  "wechat_version": "3.9.10",
  "qr_code_url": "...",
  "max_daily_send": 200
}

// 钉钉机器人
{
  "webhook_url": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
  "secret": "SECxxx"
}

// 飞书机器人
{
  "webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxx",
  "secret": "..."
}
```

### 2.3.6 会话表 `mci_conversation`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户 |
| conversation_type | tinyint | 1单聊 2群聊 |
| channel_type | varchar | wecom / wechat_personal / dingtalk / feishu |
| channel_conversation_id | varchar | 渠道会话 ID |
| owner_account_id | bigint | 群主/所有者账号 |
| subject_id | bigint | 所属渠道主体 |
| conversation_name | varchar | 会话名称 |
| create_source | tinyint | 来源：1渠道同步 2API 创建 3手动创建 |
| create_task_id | bigint | 建群任务 ID |
| institution_id | bigint | 关联机构 |
| supplier_id | bigint | 关联供应商 |
| contract_id | bigint | 关联合同 |
| channel_code | varchar | 业务渠道编码 |
| receive_config | json | 收消息配置 |
| status | tinyint | 状态 |
| create_time | datetime | 创建时间 |

### 2.3.7 会话参与者表 `mci_conversation_participant`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| conversation_id | bigint | 会话 ID |
| person_id | bigint | 人员 ID |
| channel_identity_id | bigint | 渠道身份 ID |
| participant_type | tinyint | 1成员 2群主 3管理员 |
| join_time | datetime | 加入时间 |

### 2.3.8 账号-会话绑定表 `mci_channel_account_conversation`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| account_id | bigint | 渠道账号 ID |
| conversation_id | bigint | 会话 ID |
| binding_type | tinyint | 绑定类型：1发送主号 2发送备用号 3接收主号 4接收备用号 |
| sort_order | int | 优先级 |
| status | tinyint | 状态 |

> 单聊约束：同一单聊会话中，收发账号的 `channel_type` 必须一致。

### 2.3.9 建群任务表 `mci_conversation_create_task`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户 |
| task_type | tinyint | 1创建群聊 2邀请成员 |
| channel_type | varchar | 渠道 |
| account_id | bigint | 使用哪个账号创建 |
| conversation_id | bigint | 创建成功后回填 |
| participant_ids | json | 参与者人员 ID 列表 |
| task_status | tinyint | 0待执行 1执行中 2成功 3失败 |
| channel_result | json | 渠道返回结果 |
| retry_count | int | 重试次数 |
| create_time | datetime | 创建时间 |
| finish_time | datetime | 完成时间 |

### 2.3.10 标签表 `mci_tag`

> 标签支持树形层级，可表达角色、合同、机构、供应商、业务自定义等属性，替代原人员角色表。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户 |
| parent_id | bigint | 父标签 ID，0 表示根标签 |
| tag_path | varchar | 标签路径，如 `销售/销售一部/华北组` |
| level | tinyint | 层级 |
| tag_name | varchar | 标签名 |
| tag_source | varchar | 来源：system / business_sync / manual |
| status | tinyint | 状态 |
| create_time | datetime | 创建时间 |

### 2.3.11 人员标签绑定表 `mci_person_tag_binding`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户 |
| tag_id | bigint | 标签 ID |
| person_id | bigint | 联系人 ID |
| create_time | datetime | 创建时间 |

### 2.3.12 消息事件表 `mci_message_event`

> 会话存档消息不进独立表，通过 `message_source=session_archive` 标识。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| event_id | varchar | 事件唯一 ID |
| tenant_code | varchar | 所属租户/业务系统 |
| channel_type | varchar | 渠道 |
| channel_subject_id | bigint | 渠道主体 |
| direction | tinyint | 方向：1入站 2出站 |
| event_type | varchar | 事件类型：message / callback / status / keypress |
| message_source | varchar | 来源：`realtime` / `session_archive` |
| conversation_id | bigint | 会话 ID |
| person_id | bigint | 联系人 ID |
| account_id | bigint | 发送/接收账号 |
| content | json | 内容：`{"type": "text", "body": "..."}` |
| raw_payload | json | 渠道原始报文 |
| business_context | json | 业务上下文 |
| is_processed | tinyint | 是否已处理 |
| status | tinyint | 状态 |
| create_time | datetime | 创建时间 |

**唯一索引**：`event_id` 全局唯一，保证幂等。

**分区方案**：按 `create_time` RANGE 月分区，核心索引：
- `(tenant_code, message_source, create_time)`
- `(conversation_id, create_time)`
- `(person_id, create_time)`
- `(account_id, create_time)`

### 2.3.13 媒体文件表 `mci_message_media`

> 媒体文件存 SeaweedFS，通过 S3 协议访问。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 租户 |
| msgid | varchar | 关联的消息 ID |
| sdkfileid | varchar | 企微媒体文件 ID |
| media_type | varchar | image / voice / video / file / emotion 等 |
| file_name | varchar | 文件名 |
| file_size | bigint | 文件大小 |
| md5sum | varchar | MD5 |
| storage_type | tinyint | 2SeaweedFS |
| bucket | varchar | SeaweedFS bucket |
| object_key | varchar | SeaweedFS object key |
| access_url | varchar | 访问 URL |
| status | tinyint | 0未下载 1下载中 2已下载 3下载失败 |
| create_time | datetime | 创建时间 |

### 2.3.14 发送记录表 `mci_send_record`

> 原发送任务表与发送日志表合并。一次发送请求产生一个 `task_id`，每个目标（人/群）一条记录。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| task_id | varchar | 发送任务 ID，一次 API 调用一个 task_id |
| tenant_code | varchar | 所属租户/业务系统 |
| target_type | varchar | 目标类型：person / person_list / conversation / tag / rule |
| target_value | json | 目标值：当 target_type 为 person/conversation/tag 时，存放具体 ID 列表 |
| audience_rule | json | 受众规则：当 target_type 为 rule 时，存放标签/属性组合条件 |
| conversation_id | bigint | 实际发送到的会话 ID |
| person_id | bigint | 实际发送到的联系人 ID |
| account_id | bigint | 实际使用的发送账号 ID |
| channel_type | varchar | 实际使用的渠道 |
| channel_strategy | json | 渠道策略 |
| content_type | varchar | 内容类型：text / markdown / image / file / voice / video / news / mpnews / textcard / template_card / miniprogram |
| content_body | text | 实际发送内容 |
| callback_url | varchar | 发送结果回调地址（任务级） |
| send_status | tinyint | 发送状态：0待发送 1发送中 2成功 3失败 |
| channel_result | json | 渠道返回结果 |
| send_time | datetime | 实际发送时间 |
| finish_time | datetime | 最终完成时间 |
| create_time | datetime | 创建时间 |

**唯一索引**：`(task_id, conversation_id, person_id)` 保证同一任务对同一目标幂等。

**分区方案**：按 `create_time` RANGE 月分区，索引：
- `(tenant_code, task_id)`
- `(tenant_code, create_time)`
- `(conversation_id, create_time)`

### 2.3.15 会话标签绑定表 `mci_conversation_tag_binding`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户 |
| tag_id | bigint | 标签 ID |
| conversation_id | bigint | 会话 ID |
| create_time | datetime | 创建时间 |

### 2.3.16 中台用户表 `mci_user`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户 |
| username | varchar | 用户名 |
| password | varchar | 密码（加密存储） |
| real_name | varchar | 真实姓名 |
| phone | varchar | 手机号 |
| email | varchar | 邮箱 |
| status | tinyint | 状态 |
| create_time | datetime | 创建时间 |

### 2.3.17 平台角色表 `mci_platform_role`

> 中台自身权限体系，首期只保留 3 个角色。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| role_code | varchar | 角色编码 |
| role_name | varchar | 角色名称 |
| permissions | json | 权限列表 |
| status | tinyint | 状态 |

**首期角色**：

| 角色编码 | 角色名称 | 权限范围 |
|---------|---------|---------|
| admin | 租户管理员 | 渠道资源、账号、策略、发送记录等全部权限 |
| operator | 运营操作员 | 发送、查看发送记录、配置渠道账号 |
| viewer | 只读用户 | 查看发送记录、统计 |

### 2.3.18 用户角色关系表 `mci_user_role`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| user_id | bigint | 用户 ID |
| role_id | bigint | 角色 ID |
| create_time | datetime | 创建时间 |

## 2.4 关键业务规则

| 规则 | 说明 |
|------|------|
| 一人多身份 | 一个 Person 可以有多个 ChannelIdentity，但同一渠道+主体下唯一 |
| 一人多标签 | 一个 Person 可以有多个 Tag，标签支持层级，可表达角色/合同/机构/供应商 |
| 会话唯一 | 同一渠道+主体+channel_conversation_id 唯一 |
| 收发主备 | 一个会话可绑定发送主备号、接收主备号；群聊允许跨渠道收发，单聊要求 channel_type 一致 |
| 标签来源 | 业务标签可由业务系统同步或中台管理；渠道标签由渠道同步 |
| 事件幂等 | MessageEvent 的 event_id 保证幂等，避免重复处理 |
| 群发拆解 | 按人员/标签发送时，拆解为多个单聊/单群发送记录 |
| 会话存档复用 | 会话存档消息不进独立表，`message_source=session_archive` |
| 中台不存模板 | 业务系统直接传入最终发送内容 |
| 发送结果回调 | 通过发送任务中的 callback_url 回传 |
| 租户隔离 | 各业务系统的账号、资源、日志完全隔离 |

## 2.5 与现有表的映射

| 新表 | 可能复用的现有表/模块 |
|------|---------------------|
| mci_person | 业务系统人员表、供应商表、司机表 |
| mci_channel_identity (wecom) | `admin/supplier-manage` 企微 CP 外部联系人表 |
| mci_conversation (wecom) | 企微 CP 群聊相关表 |
| mci_channel_account (wechat_personal) | 新建，pywechat 账号池 |
| mci_message_event | 新建，统一事件 |
| mci_send_record | 参考 `BaseMsgInfo` 短信发送记录 |
| mci_tenant / mci_user / mci_platform_role | 新建，中台账号权限体系 |

## 2.6 数据库选型与分表策略

基于 `sa-server` 现有技术栈，首期统一使用 **MySQL 8 + Redis + RabbitMQ**。

### 2.6.1 存储用途

| 数据类型 | 推荐存储 | 说明 |
|---------|---------|------|
| 关系型配置数据 | MySQL 8 | 人员、会话、账号、标签、策略、流程定义 |
| 消息事件 | MySQL 8 + RANGE 分区 | 单表统一存实时消息 + 会话存档，按时间分区 |
| 发送记录 | MySQL 8 + RANGE 分区 | 发送任务与日志合并，按时间分区 |
| 媒体元数据 | MySQL 8 | `mci_message_media` 存 `sdkfileid`、SeaweedFS key、状态 |
| 媒体文件 | SeaweedFS | 企微会话存档媒体文件下载后存 SeaweedFS，S3 协议访问 |
| 缓存 / 限频 / 状态 | Redis 7 | 账号在线、会话上下文、频率控制 |
| 事件总线 | RabbitMQ | 项目已有 `common-mq` |

### 2.6.2 分区方案

| 表 | 分区键 | 分区方式 | 索引 |
|---|--------|---------|------|
| `mci_message_event` | `create_time` | RANGE 月分区 | `(tenant_code, message_source, create_time)`、`(conversation_id, create_time)`、`(person_id, create_time)`、`(account_id, create_time)` |
| `mci_send_record` | `create_time` | RANGE 月分区 | `(tenant_code, task_id)`、`(tenant_code, create_time)`、`(conversation_id, create_time)` |
| `mci_conversation` | `create_time` | RANGE 月分区（可选） | `(tenant_code, channel_conversation_id)`、`(tenant_code, create_time)` |

### 2.6.3 物理分表边界

首期不分库分表，仅做 MySQL 分区。当满足以下条件时，再考虑物理分表/分库：

| 触发条件 | 方案 |
|---------|------|
| 单表数据过亿 | 按 `tenant_code` 分库分表 |
| 单个租户数据量过大 | 大租户独立实例 |
| 会话存档占满磁盘/拖慢实时查询 | 会话存档独立集群或冷备 |

### 2.6.4 消息来源与表的关系

- `mci_message_event` 统一存所有消息事件；
- `message_source` 区分 `realtime`（实时）和 `session_archive`（会话存档）；
- 不做历史导入表，历史导入按 `session_archive` 处理或首期不支持。

## 2.7 账号体系说明

### 中台账号体系

中台为每个业务系统创建一个租户（`mci_tenant`），租户下可创建多个中台用户（`mci_user`）。

**开通流程**：

```
平台管理员创建租户 rescue
        │
        ▼
创建租户主账号（admin 角色）
        │
        ▼
业务系统通过 API 创建子账号
        │
        ▼
子账号登录中台管理后台
```

**子账号创建接口**：

```json
POST /msg-platform/api/v1/account/user
Headers: X-Tenant-Code: rescue, X-Admin-Token: xxx

{
  "username": "operator01",
  "password": "xxx",
  "real_name": "运营一号",
  "phone": "13800138000",
  "role_codes": ["operator"]
}
```

### 渠道账号初始化

统一初始化接口：

```json
POST /msg-platform/api/v1/channel-account/init
Headers: X-Tenant-Code: rescue

{
  "channel_type": "wecom",
  "subject_id": 1,
  "account_type": 1,
  "config": {
    "userid": "ZhangSan"
  }
}
```

#### 企微内部员工账号 / 应用

| 步骤 | 说明 |
|------|------|
| 1. 创建渠道主体 | 在 `mci_channel_subject` 录入 `corp_id`、`corp_secret`、`agent_id`、`agent_secret` |
| 2. 初始化账号 | 调用 `/v1/channel-account/init`，指定 `channel_type=wecom`、`account_type=1/2` |
| 3. 同步通讯录 | 从企微拉取员工/部门，写入 `mci_person` + `mci_channel_identity` |
| 4. 开启会话存档 | 在企微管理后台操作，中台标记 `session_archive_enabled=1` |
| 5. 入群 | 确保企微员工在需要收消息的群里 |

#### pywechat 个人微信号

| 步骤 | 说明 |
|------|------|
| 1. 录入账号 | 在 `mci_channel_account` 录入微信号、昵称、所属服务器 |
| 2. 触发登录 | 调用 `/v1/channel-account/init`，channel_type=wechat_personal，返回二维码 |
| 3. 扫码授权 | 人工扫码后，pywechat 客户端上线，更新 `online_status=1` |
| 4. 心跳监控 | pywechat 定时上报心跳，超时下线告警 |
| 5. 加群绑定 | 把个人号拉进业务群，维护 `mci_channel_account_conversation` 发送主备 |
| 6. 风控记录 | 记录发送量、加群数、封号状态 |

#### 钉钉 / 飞书机器人

| 步骤 | 说明 |
|------|------|
| 1. 创建机器人 | 在钉钉/飞书群里添加机器人，获取 Webhook URL 和 secret |
| 2. 初始化账号 | 调用 `/v1/channel-account/init`，channel_type=dingtalk/feishu，config 中传 webhook + secret |
| 3. 回调配置 | 在钉钉/飞书开发者后台配置回调 URL，指向中台适配器 |

#### 已有群聊同步

```json
POST /msg-platform/api/v1/channel-account/{account_id}/sync-conversations
```

抓取该账号所在的所有群聊，导入 `mci_conversation` 和 `mci_conversation_participant`，并自动绑定该账号为默认发送/接收账号。

---

*第一节、第二节已按 v0.6 更新。*

---

# 第三节：消息编排层详细设计

## 3.1 编排层定位

消息编排层是中台的核心，承上启下：

- **向上**：为业务系统提供统一的发送接口；
- **向下**：调用渠道适配器完成实际收发；
- **向内**：实现入站消息归一化、LLM 意图识别、webhook 推送、出站目标解析与渠道调度、策略执行；
- **向外**：仅通过 webhook/回调与业务系统交互，不主动调用业务系统能力接口。

它让业务系统**只关心“要做什么”和“发给谁（业务语义）”**，而不关心**“通过哪个渠道、哪个账号发、怎么回收结果”**。

**范围约束**：
- 中台不承载业务系统的“触发条件 + 发送规则”配置；
- 中台不保存模板和变量；
- 出站发送由业务系统直接调用中台 API 触发；
- 入站消息做归一化、上下文匹配、轻量流程编排（意图识别/条件分支/webhook/自动回复），由业务系统自行处理业务逻辑。

## 3.2 整体架构

```
┌─────────────────────────────────────────────────────────────────────────┐
│                              业务系统                                     │
│  supplier-manager   order   contract   crm ...                          │
│  模板/变量/触发规则/业务能力 均由业务系统自行维护                            │
└─────────────────────────────┬───────────────────────────────────────────┘
                              │  ① 调用发送 API  ② 接收中台入站 webhook
                              ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                            消息编排层（Message Orchestration）            │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        入站处理管线                              │   │
│  │                                                                  │   │
│  │   渠道回调/Webhook ──► 接收适配器 ──► 事件归一化 ──► 上下文匹配    │   │
│  │                                                                  │   │
│  │                         ▼                                        │   │
│  │                  ┌─────────────┐                                 │   │
│  │                  │  意图识别引擎  │  ← LLM / 规则                 │   │
│  │                  └──────┬──────┘                                 │   │
│  │                         ▼                                        │   │
│  │              推送业务系统入站 webhook URL                         │   │
│  │              （包含原始消息 + 上下文 + 意图识别结果）               │   │
│  │                                                                  │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        出站调度管线                              │   │
│  │                                                                  │   │
│  │   业务系统调用发送 API                                           │   │
│  │        │                                                         │   │
│  │        ▼                                                         │   │
│  │   目标解析 ──► 精准定位引擎 ──► 渠道选择 ──► 发送节点              │   │
│  │                                                                  │   │
│  │                         ▼                                        │   │
│  │                  策略执行引擎（频率/时间窗/黑名单/重试）            │   │
│  │                                                                  │   │
│  │                         ▼                                        │   │
│  │                  渠道适配器 ──► 实际发送                          │   │
│  │                                                                  │   │
│  │   发送结果：同步返回 / 任务级 callback_url 回调                   │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        共享能力                                  │   │
│  │                                                                  │   │
│  │   统一内容格式  │  事件总线  │  缓存/限流  │  重试/死信            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

## 3.3 统一事件模型

所有进出编排层的事件都统一为 `MessageEvent`：

```json
{
  "event_id": "evt_20260701120000_001",
  "tenant_code": "order",
  "channel_type": "wecom",
  "channel_subject_id": 1,
  "direction": "in",
  "event_type": "message",
  "message_source": "realtime",
  "conversation_id": 1001,
  "person_id": 2001,
  "account_id": 3001,
  "content": {
    "type": "text",
    "body": "我要下单，客户张三，地址北京"
  },
  "business_context": {
    "contract_id": "C001",
    "supplier_id": "S001",
    "institution_id": "I001",
    "tag": "dispatcher"
  },
  "raw_payload": { },
  "is_processed": 0,
  "status": 1,
  "create_time": "2026-07-01T12:00:00"
}
```

事件类型：

| event_type | 说明 |
|-----------|------|
| message | 普通消息 |
| callback | 渠道回调（加好友、进群、状态变更） |
| status | 消息状态回执（已送达、已读） |
| keypress | IVR 按键事件（预留） |
| command | 业务系统指令（已废弃，触发规则由业务系统自行控制） |

## 3.4 入站处理管线

### 流程图

```
渠道回调 / Webhook
      │
      ▼
┌─────────────┐
│  接收适配器  │  ← 渠道适配层
│  校验/解密   │
└──────┬──────┘
       ▼
┌─────────────┐
│  事件归一化  │  ← 转成标准 MessageEvent
└──────┬──────┘
       ▼
┌─────────────┐
│  上下文匹配  │  ← 会话/人员 → 合同/供应商/机构/角色
└──────┬──────┘
       ▼
┌─────────────────────────────┐
│      入站流程编排            │
│  intent → condition →       │
│  webhook / reply            │
│  （按租户配置的轻量流程）      │
└─────────────────────────────┘
       │
       ▼
   业务系统处理 / 自动回复
       │
       ▼
  业务系统回呼中台 /v1/send 发送回复
```

### 入站 webhook 推送示例

```json
POST {business_system_inbound_webhook_url}
Headers: X-Msg-Platform-Signature: xxx

{
  "event_id": "evt_20260703120000_001",
  "tenant_code": "rescue",
  "channel_type": "wecom",
  "direction": "in",
  "event_type": "message",
  "conversation_id": 1001,
  "person_id": 2001,
  "account_id": 3001,
  "content": {
    "type": "text",
    "body": "我要下单，客户张三，地址北京"
  },
  "business_context": {
    "contract_id": "C001",
    "supplier_id": "S001",
    "institution_id": "I001",
    "tag": "dispatcher"
  },
  "create_time": "2026-07-03T12:00:00"
}
```

## 3.5 出站调度管线

> 说明：出站发送由业务系统直接调用中台 API 触发，中台不维护“业务事件 → 发送”的触发规则。

### 流程图

```
业务系统判断触发条件和业务规则
              │
              ▼
业务系统组装发送请求（目标 + 内容/模板变量）
              │
              ▼
┌─────────────────────────┐
│  调用中台 /send 或 /send/preview │
└─────────────────────────┘
              │
              ▼
┌─────────────┐
│  发送规模预览 │  ← 可选，先估算影响
└──────┬──────┘
       │
   确认发送
       ▼
┌─────────────┐
│  取渠道策略  │
└──────┬──────┘
       ▼
┌─────────────┐
│  目标解析    │  ← person / tag / rule / conversation
└──────┬──────┘
       ▼
┌─────────────┐
│  精准定位    │  ← 解析成具体人员/会话列表
└──────┬──────┘
       ▼
┌─────────────┐
│  渠道选择    │  ← 按策略选渠道
└──────┬──────┘
       ▼
┌─────────────┐
│  策略执行    │  ← 频率/黑名单/时间窗/重试
└──────┬──────┘
       ▼
┌─────────────┐
│  渠道发送    │  ← 调用渠道适配器
└──────┬──────┘
       ▼
┌─────────────┐
│  结果回收    │  ← 记录发送记录
└─────────────┘
```

## 3.6 意图识别引擎

中台对入站消息做 LLM / 规则意图识别，把识别结果随 webhook 一起推送给业务系统。

### 两种方式

| 方式 | 适用场景 | 说明 |
|------|---------|------|
| 规则匹配 | 意图明确、格式固定 | 关键词、正则、模板匹配 |
| LLM 识别 | 意图复杂、口语化 | 调用大模型，输出结构化意图 |

### 意图输出格式

```json
{
  "intent": "create_order",
  "confidence": 0.95,
  "slots": {
    "customer_name": "张三",
    "address": "北京",
    "phone": ""
  },
  "missing_slots": ["phone"],
  "requires_confirmation": true
}
```

**首期 1851 建议**：先用规则匹配覆盖主要场景（下单、查状态、确认、投诉），复杂场景引入 LLM 作为补充。

## 3.7 入站消息与出站发送的边界

| 职责 | 业务系统 | 中台 |
|------|---------|------|
| 模板和变量 | ✅ 自行维护 | ❌ 不参与 |
| 触发条件和业务规则 | ✅ 自行判断 | ❌ 不参与 |
| 内容渲染 | ✅ 传入最终内容 | ❌ 不参与 |
| 意图识别 | 接收识别结果 | ✅ LLM / 规则识别 |
| 目标人群解析 | 提供业务语义 | ✅ 解析成具体渠道账号/群 |
| 渠道选择 | ❌ | ✅ |
| 发送执行 | ❌ | ✅ |
| 入站消息处理 | ✅ 接收 webhook 后自行处理 | ✅ 归一化、意图识别、推送 |
| 发送结果回收 | 接收 callback_url 回调 | ✅ 统一回收并回调 |

> IVR 外呼/呼入流程作为独立流程在中台配置，不依赖业务系统能力调用。2092 阶段详细设计。

## 3.8 精准定位引擎

把业务语义转换成具体接收人：

| 输入类型 | 示例 | 输出 |
|---------|------|------|
| 人员 ID | `person_id=1001` | 该人员的所有可用渠道身份 |
| 标签 | `tag=培训未完成` | 打标签的人员列表 |
| 规则 | `tag=调度 AND contract=C001` | 匹配的人员列表 |
| 会话 | `conversation_id=2001` | 该会话的所有参与者 |

规则表达式示例：

```json
{
  "rule": {
    "and": [
      {"field": "tag", "op": "eq", "value": "dispatcher"},
      {"field": "contract_id", "op": "in", "value": ["C001", "C002"]},
      {"field": "supplier.is_subsidiary", "op": "eq", "value": true}
    ]
  }
}
```

## 3.9 业务系统调用中台

### 3.9.1 发送接口

```json
POST /msg-platform/api/v1/send
Headers: X-Tenant-Code: rescue

{
  "target": {
    "type": "rule",
    "rule": {
      "tag": "dispatcher",
      "contract_id": "C001"
    }
  },
  "content": {
    "type": "text",
    "body": "技师姓名：张师傅\n技师电话：13800138000\n预计到达时间：30分钟"
  },
  "channel_strategy": {
    "priority": ["wechat_personal"]
  },
  "callback_url": "https://rescue.sino.com/api/msg-platform/callback"
}
```

### 3.9.2 发送规模预览接口

```json
POST /msg-platform/api/v1/send/preview
Headers: X-Tenant-Code: rescue

{
  "target": {
    "type": "rule",
    "rule": {
      "tag": "dispatcher",
      "contract_id": "C001"
    }
  },
  "channel_strategy": {
    "priority": ["wechat_personal"]
  }
}
```

返回：

```json
{
  "total_person_count": 156,
  "channel_breakdown": {
    "wechat_personal": 150,
    "unreachable": 6
  },
  "account_usage": {
    "wx_bot_01": 80,
    "wx_bot_02": 70
  },
  "policy_check": {
    "rate_limit_warning": "wx_bot_01 今日已发送 90 条，再发 80 条将接近上限",
    "time_window_ok": true,
    "blacklist_hit": 0
  },
  "estimated_time_seconds": 180,

}
```

## 3.10 发送结果回调

| 方式 | 触发时机 | 说明 |
|------|---------|------|
| 同步返回 | 发送 API 调用后立即返回 | 仅表示中台接收成功 |
| 异步回调 | 渠道返回最终状态后 | 通过发送记录中的 callback_url 回传 |
| 主动查询 | 业务方按需查询 | 通过对账接口查询 |

> 说明：不维护固定 webhook 注册，每次发送记录自带 callback_url。

异步回调示例：

```json
POST https://rescue.sino.com/api/msg-platform/callback

{
  "task_id": "task_001",
  "conversation_id": 1001,
  "person_id": 2001,
  "channel_type": "wechat_personal",
  "event": "delivered",
  "status": 1,
  "channel_result": { },
  "event_time": "2026-07-03T12:01:00"
}
```

## 3.11 策略执行引擎

### 策略类型

| 策略 | 说明 |
|------|------|
| 频率控制 | 单账号/单用户/单群每日/每小时发送上限 |
| 时间窗口 | 只允许在指定时段发送 |
| 黑名单 | 禁止向指定人员/群发送 |
| 免打扰 | 用户设置免打扰时段 |
| 重试 | 发送失败后按策略重试 |
| 主备切换 | 账号掉线时切换备用账号 |
| 优先级 | 重要消息优先发送 |
| 并发控制 | 限制同时发送数量 |

### 策略配置示例

```json
{
  "policy_group_code": "default",
  "tenant_code": "supplier-manager",
  "policies": [
    {
      "type": "rate_limit",
      "scope": "account",
      "limit": 100,
      "window": "1h"
    },
    {
      "type": "time_window",
      "allow": ["09:00-21:00"]
    },
    {
      "type": "blacklist",
      "person_ids": [1001, 1002]
    },
    {
      "type": "retry",
      "max_retry": 3,
      "interval": [5, 10, 30]
    }
  ]
}
```

## 3.12 按租户/业务系统隔离

每个业务系统（租户）在消息中台有独立的策略、渠道配置、账号、发送记录；模板和触发规则由业务系统自行维护，不在中台配置：

| 资源 | 隔离字段 | 说明 |
|------|---------|------|
| 策略组 | `tenant_code` | 中台页面配置 |
| 渠道配置 | `tenant_code`（可选，为空则平台共享） | 中台页面配置 |
| 中台用户 | `tenant_code` | 中台账号体系 |
| 发送记录 | `tenant_code` | 按租户隔离 |
| 模板 | ❌ 不在中台 | 业务系统自行维护 |
| 触发规则 | ❌ 不在中台 | 业务系统自行维护 |

### 策略组表 `mci_policy_group`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户/业务系统 |
| group_code | varchar | 策略组编码 |
| group_name | varchar | 策略组名称 |
| policies | json | 策略规则 JSON |
| status | tinyint | 状态 |
| create_time | datetime | 创建时间 |

## 3.13 企微应用消息推送

中台支持企微应用消息发送，内容格式对齐企微 API。业务系统直接传入已渲染内容，中台按企微格式组装：

| 企微消息类型 | 说明 |
|------------|------|
| 文本消息 | text |
| Markdown | markdown |
| 图片 | image |
| 图文 | news / mpnews |
| 文件 | file |
| 语音 | voice |
| 视频 | video |
| 文本卡片 | textcard |
| 模板卡片 | template_card |
| 小程序 | miniprogram |

发送对象：指定用户、指定部门、指定标签、群发。

## 3.14 supplier-manager 解耦

| 职责 | supplier-manager | 消息中台 |
|------|-----------------|----------|
| 内容管理 | ✅ | ❌ |
| 模板和变量 | ✅ | ❌ |
| 触发规则 | ✅ | ❌ |
| 发送执行 | ❌ | ✅ |
| 发送记录/统计 | ❌ | ✅ |
| 渠道账号管理 | ❌ | ✅ |

supplier-manager 自行判断触发条件、渲染内容，通过中台发送接口发起发送，中台负责实际执行。

## 3.15 错误处理与重试

### 错误分类

| 错误类型 | 示例 | 处理方式 |
|---------|------|---------|
| 渠道临时错误 | 网络超时、企微频率限制 | 按策略重试 |
| 渠道永久错误 | 账号被封、群不存在 | 标记失败，切备用，告警 |
| 业务系统入站处理错误 | 业务系统 webhook 处理失败 | 记录日志，中台不主动重试入站推送 |
| 中台内部错误 | 数据缺失、规则异常 | 入死信队列，人工处理 |

### 重试队列

```
发送失败
   │
   ▼
┌─────────────┐
│  延迟队列    │  ← 按重试策略等待
└──────┬──────┘
       ▼
┌─────────────┐
│  重试发送    │
└──────┬──────┘
       │
   成功 ←──── 失败
              │
              ▼
        ┌─────────────┐
        │  超过重试次数 │
        └──────┬──────┘
               ▼
        ┌─────────────┐
        │  死信队列    │  ← 人工介入
        └─────────────┘
```

### 幂等保障

- `MessageEvent.event_id` 全局唯一；
- 发送任务使用 `task_id + conversation_id + person_id` 幂等。

## 3.16 第三节补充数据表

### 3.16.1 策略组表

见 3.12 `mci_policy_group`。

### 3.16.2 流程定义表 `mci_flow_definition`

> 用于入站消息处理流程编排、IVR 等独立流程。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| tenant_code | varchar | 所属租户/业务系统 |
| flow_code | varchar | 流程编码 |
| flow_name | varchar | 流程名称 |
| flow_type | tinyint | 流程类型：1入站消息流程 2IVR 流程 3其他独立流程 |
| version | int | 版本号 |
| definition_json | json | 工作流 JSON 定义 |
| status | tinyint | 0草稿 1已发布 2已下线 |
| publish_time | datetime | 发布时间 |
| create_time | datetime | 创建时间 |

## 3.17 入站消息流程编排（轻量画布）

首期 1851 需要在前端通过轻量画布配置入站消息的处理流程。流程节点简单、固定类型，不比 IVR 流程复杂。

### 3.17.1 节点类型

| 节点类型 | 职责 | 配置项 |
|---------|------|--------|
| `receive` | 接收消息事件 | 指定来源渠道/会话标签/账号 |
| `intent` | LLM / 规则意图识别 | 选择识别方式、配置提示词/规则 |
| `condition` | 条件分支 | 基于意图、标签、发送人、会话属性判断 |
| `webhook` | 推送到业务系统 | 选择租户 webhook 或自定义 URL、签名方式 |
| `reply` | 自动回复（可选） | 固定回复内容或调用发送接口 |

### 3.17.2 示例流程

```
[receive: 企微会话存档消息]
        │
        ▼
[intent: LLM 识别意图]
        │
        ▼
[condition: 意图 == "create_order"]
        │ yes
        ▼
[webhook: 推送到 order 业务系统]
        │
        ▼
[reply: "已收到，正在为您处理…"]
```

### 3.17.3 执行方式

- 流程定义以 JSON 形式保存在 `mci_flow_definition.definition_json`；
- 发布时加载到内存，入站消息按租户匹配已发布的流程；
- 流程执行由编排层统一调度，节点按顺序/分支执行；
- 错误节点统一进入死信队列，人工处理。

### 3.17.4 与 IVR 流程的关系

| 对比项 | 入站消息流程 | IVR 流程 |
|--------|-------------|---------|
| 触发源 | 渠道消息事件 | 电话呼入/外呼事件 |
| 节点复杂度 | 低，固定 5 种节点 | 高，支持语音、按键、转人工等 |
| 画布实现 | Vue Flow 轻量画布 | Vue Flow 完整画布 |
| 执行引擎 | 编排层内置轻量执行器 | 自研 Graph-State DAG 执行器 |

---

*第三节已按 v0.7 更新：新增入站消息流程编排设计。*

---

# 第四节：技术选型

## 4.1 选型原则

1. **与现有技术栈兼容**：优先复用 `sa-server` 已有的 Java/Spring Boot/MySQL/Redis/RabbitMQ 能力；
2. **渠道适配灵活**：pywechat 个人微信控制必须走 Python，独立为渠道服务；
3. **轻量流程编排用于入站消息处理**：通过 Vue Flow 画布配置接收 → 意图识别 → 条件分支 → webhook 推送；IVR 等复杂流程使用自研 DAG 工作流引擎；
4. **LLM 可插拔**：通过 Spring AI 统一抽象，兼容 OpenAI 接口及腾讯云混元等国产模型；
5. **数据存储统一**：核心数据用 MySQL 8，消息归档通过分区表扩展，避免过早引入异构数据库；
6. **可观测可运维**：服务拆分清晰，监控、日志、告警配套。

## 4.2 后端技术栈

| 技术 | 用途 |
|------|------|
| **Java 21** | 主开发语言，使用 Virtual Threads 提升并发处理能力 |
| **Spring Boot 4.1.x** | 基础框架 |
| **Spring AI** | LLM 统一接入层，兼容 OpenAI 接口规范及腾讯云混元自定义适配 |
| **MyBatis Plus / JPA** | ORM 框架，持久化工作流、人员、会话、账号等数据 |
| **JGraphT** | DAG 图算法：拓扑排序、环检测、可达性分析 |
| **Spring SpEL** | 工作流条件表达式 |
| **Jackson** | JSON 序列化/反序列化 |
| **Quartz / Spring Scheduler** | 定时触发、超时处理 |
| **CompletableFuture / Virtual Threads** | 节点异步执行 |
| **weixin-java-cp** | 企微 CP API 封装 |
| **com.tencent.wework.Finance SDK** | 企微会话存档拉取与解密（C 库 JNI） |

## 4.3 前端技术栈

| 技术 | 用途 |
|------|------|
| **Vue 3** | 前端框架 |
| **Element Plus** | UI 组件库 |
| **Vue Flow** | 工作流可视化画布（节点拖拽、连线、缩放） |
| **Monaco Editor** | Python/HTTP 脚本编辑 |
| **Ajv / JSON Schema** | 节点配置表单校验 |

## 4.4 数据存储

| 数据 | 存储 | 说明 |
|------|------|------|
| 核心配置数据 | MySQL 8 | 人员、标签、会话、账号、工作流定义、账号权限等 |
| 消息事件 | MySQL 8 + RANGE 分区 | 实时消息 + 会话存档统一单表，按时间分区 |
| 发送记录 | MySQL 8 + RANGE 分区 | 发送任务与日志合并，按时间分区 |
| 媒体元数据 | MySQL 8 | `mci_message_media` 表 |
| 媒体文件 | SeaweedFS | 企微会话存档媒体文件下载后存 SeaweedFS |
| 缓存/状态 | Redis 7 | 账号在线状态、会话上下文、限流、频率控制 |
| 事件总线 | RabbitMQ | 异步事件流转 |

## 4.5 基础设施

| 技术 | 用途 |
|------|------|
| **RabbitMQ** | 事件总线，解耦业务系统与中台 |
| **Redis** | 缓存、分布式锁、限流、状态存储 |
| **Nginx / Gateway** | API 网关、负载均衡 |
| **Prometheus + Grafana** | 监控告警 |
| **ELK / Loki** | 日志收集与分析 |

## 4.6 pywechat 渠道服务

| 技术 | 用途 |
|------|------|
| **Python 3.11** | 开发语言 |
| **FastAPI** | Web 服务框架 |
| **pywechat / pywinauto** | 控制 PC 微信客户端 |
| **WebSocket / HTTP** | 与 Java 中台通信 |
| **PyInstaller** | 打包 Windows 安装包 |
| **原始 HTML + Web Components** | 客户端监控界面 |

pywechat 服务部署在 Windows 服务器上，每台服务器运行多个微信 PC 客户端，由 pywechat 进程统一管理和调度。

## 4.7 工作流引擎自研组件（仅 IVR 等独立流程）

| 组件 | 依赖/实现 |
|------|----------|
| DAG 执行器 | 自研 + JGraphT 图算法 |
| 状态持久化 | MyBatis Plus + Redis 缓存 |
| 节点注册机制 | Spring Bean 自动扫描注册 |
| 条件表达式 | Spring SpEL |
| 异步执行 | CompletableFuture / Virtual Threads |
| 事件唤醒 | RabbitMQ + 信号机制 |
| 前端画布 | Vue Flow |

> 说明：首期 1851 聊天流程不依赖工作流引擎，直接通过 webhook 推送 + LLM 意图识别处理。

## 4.8 部署架构

```
┌─────────────────────────────────────────────────────────────┐
│                         用户 / 管理员                         │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                      Nginx / API 网关                         │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
│  Java 消息中台   │ │  Vue 管理后台 │ │ Python 渠道服务  │
│  (Spring Boot)  │ │             │ │  (FastAPI)      │
└────────┬────────┘ └─────────────┘ └────────┬────────┘
         │                                   │
         │         ┌─────────────┐           │
         └────────►│  RabbitMQ   │◄──────────┘
                   │  Redis      │
                   │  MySQL 8    │
                   └─────────────┘
                          │
                          ▼
              ┌─────────────────────┐
              │   Windows 服务器     │
              │  PC 微信客户端 x N   │
              │  (pywechat 管理)    │
              └─────────────────────┘
```

## 4.9 技术栈总览

| 层级 | 技术 |
|------|------|
| 编排中台 | Java 21 + Spring Boot 4.1.x + Spring AI |
| 工作流引擎 | 自研 Graph-State DAG（JGraphT + SpEL + Vue Flow），首期仅用于 IVR 等独立流程 |
| LLM 接入 | Spring AI，兼容 OpenAI 接口规范，支持腾讯云混元 |
| 前端 | Vue 3 + Element Plus + Vue Flow |
| pywechat 服务 | Python 3.11 + FastAPI + PyInstaller |
| pywechat 客户端监控 | 原始 HTML + Web Components |
| 企微会话存档 | `weixin-java-cp` + `com.tencent.wework.Finance` SDK（C 库 JNI） |
| 媒体文件存储 | SeaweedFS（S3 协议） |
| 数据库 | MySQL 8 + Redis 7 |
| 消息队列 | RabbitMQ |
| 消息归档 | MySQL 8 RANGE 分区表，未来可扩展 PostgreSQL/MongoDB |
| 监控 | Prometheus + Grafana + ELK/Loki |

## 4.10 关键不引入的技术

| 技术 | 不引入原因 |
|------|-----------|
| PostgreSQL（首期） | 团队熟悉 MySQL，避免异构数据库运维成本；消息归档通过 MySQL 分区表先支撑 |
| Dify / n8n / Langflow | 无法同时满足 IVR、渠道发送等需求，异构服务维护成本高 |
| Flowable / Camunda | BPMN 模型与 LLM/聊天流程不够贴合，且 IVR 节点扩展成本高 |
| Netflix Conductor | 维护活跃度下降，社区风险 |
| MongoDB（首期） | 消息量未明确前，先用 MySQL 分区表，避免过度设计 |

---

*第四节已按 v0.6 更新。*

---

# 第五节：中台对外 API 能力

> 范围说明：中台定位为消息发送网关 + 渠道资源管理中心 + 入站消息 LLM 意图识别。
> - 不保存模板和变量；
> - 不主动调用业务系统能力接口；
> - 出站发送由业务系统直接调用 API 触发；
> - 入站消息做归一化、上下文匹配、LLM 意图识别、轻量流程编排，结果通过 webhook 推送给业务系统；
> - 发送结果通过任务级 `callback_url` 回传；
> - 中台页面用于配置渠道资源、账号权限、发送策略、入站 webhook、发送记录、IVR 流程。

## 5.1 API 设计原则

1. **按租户/业务系统隔离**：所有 API 均通过 `X-Tenant-Code` 识别来源；
2. **统一返回结构**：`{ code, message, data, request_id }`；
3. **幂等设计**：写操作支持幂等键；
4. **异步结果通过 callback_url 返回**：同步接口仅表示中台受理成功；
5. **权限分级**：中台用户按角色访问自己被授权的资源。

## 5.2 发送类 API

| API | 用途 |
|-----|------|
| `POST /v1/send` | 通用发送接口（单聊/群聊/按标签/按规则/直接内容） |
| `POST /v1/send/preview` | 发送规模预览 |
| `POST /v1/send/{task_id}/cancel` | 取消发送任务 |
| `GET /v1/send/{task_id}/status` | 查询发送任务状态 |
| `POST /v1/send/{task_id}/records` | 查询发送记录明细 |
| `POST /v1/send/test` | 测试发送（模拟发送，不实际调用渠道） |

### 5.2.1 发送接口示例

```json
POST /msg-platform/api/v1/send
Headers: X-Tenant-Code: rescue

{
  "target": {
    "type": "rule",
    "rule": {
      "tag": "rescue_dispatcher",
      "contract_id": "C001"
    }
  },
  "content": {
    "type": "text",
    "body": "技师姓名：张师傅\n技师电话：13800138000\n预计到达时间：30分钟"
  },
  "channel_strategy": {
    "priority": ["wechat_personal"]
  },
  "callback_url": "https://rescue.sino.com/api/msg-platform/callback"
}
```

### 5.2.2 测试发送接口

```json
POST /msg-platform/api/v1/send/test
Headers: X-Tenant-Code: rescue

{
  "target": {
    "type": "rule",
    "rule": {
      "tag": "rescue_dispatcher",
      "contract_id": "C001"
    }
  },
  "content": {
    "type": "text",
    "body": "测试消息"
  },
  "channel_strategy": {
    "priority": ["wechat_personal"]
  }
}
```

返回模拟的发送记录列表，**不实际调用渠道**，用于业务系统联调测试和发送逻辑验证。

## 5.3 客户关系类 API

| API | 用途 |
|-----|------|
| `POST /v1/person/query` | 按条件查询联系人 |
| `GET /v1/person/{person_id}` | 查询联系人详情 |
| `POST /v1/person/create-or-update` | 创建或更新联系人 |
| `POST /v1/person/{person_id}/identities` | 查询某人的所有渠道身份 |
| `POST /v1/person/batch-bind-tags` | 批量打标签 |
| `POST /v1/person/batch-unbind-tags` | 批量解绑标签 |

## 5.4 渠道资源类 API

| API | 用途 |
|-----|------|
| `POST /v1/channel-account/init` | 初始化渠道账号（企微/个微/钉钉/飞书） |
| `POST /v1/channel-account/{account_id}/sync-conversations` | 同步该账号已有群聊 |
| `POST /v1/channel-account/wecom/qr-code` | 获取企微账号加好友二维码 |
| `POST /v1/channel-account/wechat-personal/qr-code` | 获取 pywechat 个人号登录二维码 |
| `GET /v1/channel-account/{account_id}/status` | 查询账号在线/登录/风控状态 |
| `POST /v1/channel-account/list` | 查询渠道账号列表 |
| `POST /v1/channel-account/{account_id}/refresh-qr-code` | 刷新登录二维码 |
| `POST /v1/channel-account/{account_id}/logout` | 强制下线 |
| `GET /v1/channel-account/{account_id}/groups` | 查询账号已加入的群聊 |

### 5.4.1 初始化渠道账号示例

```json
POST /msg-platform/api/v1/channel-account/init
Headers: X-Tenant-Code: rescue

{
  "channel_type": "wecom",
  "account_type": 1,
  "subject_id": 1,
  "config": {
    "userid": "ZhangSan"
  }
}
```

### 5.4.2 同步已有群聊示例

```json
POST /msg-platform/api/v1/channel-account/1001/sync-conversations
Headers: X-Tenant-Code: rescue
```

## 5.5 会话/群聊类 API

| API | 用途 |
|-----|------|
| `POST /v1/conversation/create` | 创建群聊 |
| `POST /v1/conversation/{conversation_id}/invite` | 邀请成员进群 |
| `GET /v1/conversation/{conversation_id}` | 查询群聊详情 |
| `POST /v1/conversation/list` | 按条件查询群聊 |
| `POST /v1/conversation/{conversation_id}/participants` | 查询群成员 |
| `POST /v1/conversation/{conversation_id}/bind-account` | 绑定收发账号（发送主/备、接收主/备） |
| `POST /v1/conversation/{conversation_id}/unbind-account` | 解绑收发账号 |
| `POST /v1/conversation/{conversation_id}/bind-tags` | 给会话打标签 |
| `POST /v1/conversation/{conversation_id}/unbind-tags` | 解绑会话标签 |
| `POST /v1/conversation/list-by-tags` | 按标签查询会话 |
| `POST /v1/conversation/{conversation_id}/messages` | 查询群聊历史消息 |

### 5.5.1 绑定收发账号示例

```json
POST /msg-platform/api/v1/conversation/1001/bind-account
Headers: X-Tenant-Code: rescue

{
  "account_id": 2001,
  "binding_type": 1,
  "sort_order": 1
}
```

`binding_type`：1发送主号 / 2发送备用号 / 3接收主号 / 4接收备用号

### 5.5.2 会话打标签示例

```json
POST /msg-platform/api/v1/conversation/1001/bind-tags
Headers: X-Tenant-Code: rescue

{
  "tag_ids": [101, 102]
}
```

## 5.6 媒体文件类 API

| API | 用途 |
|-----|------|
| `GET /v1/media/{media_id}` | 下载/获取媒体文件 |
| `POST /v1/media/{media_id}/download` | 触发异步下载媒体文件 |

### 5.6.1 媒体下载示例

```json
GET /msg-platform/api/v1/media/1001
Headers: X-Tenant-Code: rescue
```

- 已下载：从 SeaweedFS 读取并返回文件流，或 302 跳转；
- 未下载：返回 `202 Accepted`，后台异步调用 Finance SDK `GetMediaData` 下载后写入 SeaweedFS。

## 5.7 入站配置类 API

| API | 用途 |
|-----|------|
| `GET /v1/inbound/webhook` | 查询业务系统入站 webhook 配置 |
| `POST /v1/inbound/webhook` | 配置/更新入站 webhook URL |
| `POST /v1/inbound/webhook/test` | 测试入站 webhook 连通性 |
| `POST /v1/intent/recognize` | 对文本做意图识别（调试） |

### 5.7.1 入站流程编排类 API

| API | 用途 |
|-----|------|
| `POST /v1/inbound/flow/list` | 查询入站流程列表 |
| `GET /v1/inbound/flow/{flow_code}` | 查询流程定义 |
| `POST /v1/inbound/flow` | 创建/更新入站流程 |
| `POST /v1/inbound/flow/{flow_code}/publish` | 发布流程 |
| `POST /v1/inbound/flow/{flow_code}/offline` | 下线流程 |

## 5.8 IVR 流程类 API（预留）

| API | 用途 |
|-----|------|
| `POST /v1/flow/list` | 查询 IVR 流程列表 |
| `GET /v1/flow/{flow_code}` | 查询 IVR 流程定义 |
| `POST /v1/flow/create` | 创建 IVR 流程 |
| `POST /v1/flow/{flow_code}/publish` | 发布 IVR 流程 |

## 5.9 账号权限类 API

中台自维护账号体系，开通租户时创建主账号，业务系统可通过接口创建子账号。

| API | 用途 |
|-----|------|
| `POST /v1/account/tenant` | 创建租户（平台管理员） |
| `POST /v1/account/user` | 创建中台用户（租户管理员） |
| `POST /v1/account/user/{user_id}/reset-password` | 重置密码 |
| `POST /v1/account/user/{user_id}/bind-role` | 绑定角色 |
| `POST /v1/account/login` | 中台用户登录 |
| `POST /v1/account/sso-token` | 业务系统申请跳转 token |

### 5.9.1 创建子账号示例

```json
POST /msg-platform/api/v1/account/user
Headers: X-Tenant-Code: rescue, X-Admin-Token: xxx

{
  "username": "operator01",
  "password": "xxx",
  "real_name": "运营一号",
  "phone": "13800138000",
  "role_codes": ["operator"]
}
```

## 5.10 页面跳转入口

业务系统通过带 token 的 URL 跳转到中台页面：

```
https://msg-platform.sino.com/msg-platform/channel-account?tenant=rescue&token=JWT
https://msg-platform.sino.com/msg-platform/inbound-webhook?tenant=rescue&token=JWT
https://msg-platform.sino.com/msg-platform/send-record?tenant=rescue&token=JWT
https://msg-platform.sino.com/msg-platform/flow?tenant=rescue&token=JWT
```

中台页面通过 JWT 识别用户身份、所属 tenant 和权限。

## 5.11 中台保留的页面 vs 业务系统自行维护的页面

| 页面 | 归属 | 说明 |
|------|------|------|
| 渠道资源管理 | 中台 | 业务系统跳转使用 |
| 入站 webhook 配置 | 中台 | 业务系统跳转使用 |
| 入站流程编排 | 中台 | 业务系统跳转使用；轻量画布配置接收 → 意图识别 → 分支 → webhook/自动回复 |
| 发送策略配置 | 中台 | 业务系统跳转使用 |
| 发送记录/统计 | 中台 | 业务系统跳转使用 |
| IVR 流程编排 | 中台 | 业务系统跳转使用（2092 阶段） |
| 账号权限管理 | 中台 | 租户管理员使用 |
| 模板管理 | ❌ 不在中台 | 业务系统自行维护 |
| 业务触发规则配置 | ❌ 不在中台 | 业务系统自行维护 |
| 变量取值逻辑 | ❌ 不在中台 | 业务系统自行维护 |

---

*第五节随 v0.6 数据模型修正更新。*

---

# 第六节：项目目录结构

## 6.1 仓库定位

`sino-mci` 是**独立于 `sa-server` 的仓库/项目**，位于 `sa-server` 的平级目录：

```
/sino-project
├── sa-server/                # 现有业务系统
├── sino-mci/                 # 消息与客户互动中台（本项目）
│   ├── backend/
│   ├── admin-web/
│   ├── channel-service/
│   ├── infrastructure/
│   └── docs/
```

## 6.2 目录结构（按技术栈分层）

```text
sino-mci/
├── README.md
├── docs/
│   ├── architecture/
│   │   └── 2026-07-06-message-customer-interaction-design.md
│   ├── api/
│   │   ├── openapi-send.yaml
│   │   ├── openapi-channel.yaml
│   │   └── openapi-account.yaml
│   └── deployment/
│       └── deployment-guide.md
│
├── backend/                                # Java 21 + Spring Boot 4.1.x 主中台
│   ├── mci-server/                        # 主服务：编排层、对外 API、管理后台接口
│   │   ├── src/main/java/com/sino/mci/
│   │   │   ├── MciServerApplication.java
│   │   │   ├── api/                       # REST / Webhook 入口
│   │   │   ├── orchestration/             # 入站/出站管线、意图识别、策略执行
│   │   │   ├── admin/                     # 租户、用户、角色权限
│   │   │   ├── config/
│   │   │   └── channel/                   # 渠道适配 SPI 注册（可选）
│   │   ├── src/main/resources/
│   │   │   ├── application.yml
│   │   │   ├── application-dev.yml
│   │   │   └── db/migration/              # Flyway 脚本
│   │   ├── src/test/java/com/sino/mci/
│   │   └── pom.xml
│   │
│   ├── mci-channel-common/                # 渠道适配公共接口与模型
│   │   └── src/main/java/com/sino/mci/channel/
│   │       ├── ChannelAdapter.java
│   │       ├── ChannelSender.java
│   │       ├── ChannelReceiver.java
│   │       └── dto/
│   │
│   ├── mci-channel-wecom/                 # 企微渠道适配（首期实现）
│   │   └── src/main/java/com/sino/mci/channel/wecom/
│   │       ├── WecomChannelAdapter.java
│   │       ├── WecomMessageReceiver.java
│   │       ├── WecomMessageSender.java
│   │       ├── finance/                   # com.tencent.wework.Finance SDK 封装
│   │       └── callback/                  # 企微回调 Controller
│   │
│   ├── mci-channel-dingtalk/              # 钉钉适配（预留）
│   ├── mci-channel-feishu/                # 飞书适配（预留）
│   ├── mci-channel-ivr/                   # IVR 适配（2092 预留）
│   │
│   ├── mci-shared/                        # 公共实体、工具、MQ/Redis 封装
│   │   └── src/main/java/com/sino/mci/shared/
│   │
│   └── pom.xml                            # Maven 4 多模块 parent
│
├── admin-web/                              # Vue 3 + Element Plus 管理后台
│   ├── src/
│   │   ├── api/                           # 中台 API 调用
│   │   ├── views/
│   │   │   ├── channel-account/           # 渠道账号管理
│   │   │   ├── channel-subject/           # 渠道主体管理
│   │   │   ├── conversation/              # 会话/群聊管理
│   │   │   ├── send-record/               # 发送记录
│   │   │   ├── send-policy/               # 发送策略
│   │   │   ├── inbound-webhook/           # 入站配置
│   │   │   ├── inbound-flow/              # 入站流程编排（轻量画布）
│   │   │   ├── tag/                       # 标签管理
│   │   │   └── tenant-user/               # 租户/用户/角色
│   │   ├── components/
│   │   ├── router/
│   │   ├── stores/
│   │   └── App.vue
│   ├── package.json
│   ├── vite.config.ts
│   └── Dockerfile
│
├── channel-service/                        # Python 3.11 + FastAPI 渠道服务
│   ├── app/
│   │   ├── main.py
│   │   ├── api/
│   │   │   ├── wechat_personal.py         # pywechat 个人号 API
│   │   │   ├── health.py
│   │   │   └── monitor.py                 # 状态/心跳上报
│   │   ├── adapters/
│   │   │   ├── wechat_personal_adapter.py
│   │   │   └── base.py
│   │   ├── clients/
│   │   │   └── pywechat_client.py
│   │   ├── services/
│   │   │   ├── login_service.py
│   │   │   ├── send_service.py
│   │   │   └── heartbeat_service.py
│   │   └── models/
│   ├── monitor/                           # 原始 HTML + Web Components 监控界面
│   │   ├── index.html
│   │   ├── client-status.js
│   │   └── send-log.js
│   ├── requirements.txt
│   ├── Dockerfile
│   └── pyproject.toml
│
├── infrastructure/                         # 基础设施与部署
│   ├── docker-compose.yml                 # MySQL + Redis + RabbitMQ + SeaweedFS
│   ├── docker/
│   │   ├── Dockerfile.backend
│   │   ├── Dockerfile.admin-web
│   │   └── Dockerfile.channel-service
│   ├── k8s/
│   │   ├── backend/
│   │   ├── admin-web/
│   │   ├── channel-service/
│   │   └── infra/
│   └── sql/
│       ├── init/                          # 初始数据：角色、平台管理员
│       └── migration/                     # 按版本号组织的 DDL（Flyway 备份）
│
└── scripts/                               # 构建/部署/本地启动脚本
    ├── local-up.sh                        # 一键启动本地环境
    ├── build-backend.sh
    ├── build-admin-web.sh
    ├── build-channel-service.sh
    └── deploy-k8s.sh
```

## 6.3 关键目录设计决策

| 决策 | 说明 |
|------|------|
| **单仓库 monorepo** | 后端、前端、Python 服务、文档、基础设施统一版本管理，降低联调成本。 |
| **Maven 4 多模块** | `backend/pom.xml` 作为 parent，各渠道适配器独立模块；首期只实现 `mci-channel-wecom`，其余预留。 |
| **`mci-server` 合并 admin** | 中台用户、租户、角色权限直接放在 `mci-server` 的 `admin` 包下，不单独拆 `mci-admin` 模块。 |
| **渠道适配 SPI** | `mci-channel-common` 定义统一接口，主服务通过 Spring 自动扫描加载适配器。 |
| **Flyway 脚本放在 `mci-server`** | 数据库迁移由主服务启动时执行，脚本按 `V{版本}__{描述}.sql` 命名。 |
| **Python 服务独立目录** | pywechat 依赖 Windows + Python 环境，与 Java 中台通过 HTTP/WebSocket 通信；监控页用原始 HTML + Web Components。 |
| **基础设施即代码** | `docker-compose.yml` 统一拉起 MySQL、Redis、RabbitMQ、SeaweedFS，降低本地开发和测试成本。 |
| **文档集中** | 设计文档、API 文档、部署文档全部进 `docs/`，不再散落在各模块中。 |

## 6.4 与 `sa-server` 的关系

| 项目 | 职责 | 交互方式 |
|------|------|---------|
| `sa-server` | 业务系统（合同、供应商、订单、人员等） | 调用 `sino-mci` 发送 API；接收 `sino-mci` 入站 webhook |
| `sino-mci` | 消息中台（发送网关 + 渠道资源管理） | 提供 REST API；向业务系统推送入站消息事件 |

`sino-mci` 不依赖 `sa-server` 的业务代码，只通过 HTTP API 与业务系统交互。

---

*第六节为 v0.7 新增。*