feat: message-api for mission via wecomm agent

docs/WECOM_APP_INTEGRATION_GUIDE.md

@@ -0,0 +1,412 @@
+# 企业微信应用接入说明
+
+本文档面向企业微信自建应用开发组，说明当前 AI Agent 的接入方式、适合的消息入口、菜单和提问引导建议、能力边界，以及消息处理侧需要注意的事项。
+
+## 1. 目标
+
+当前 Agent 不是通用对话机器人，而是一个“受约束的业务查询助手”。
+
+它适合处理以下两类问题：
+
+1. MES / 出货 / 运输车辆等业务数据查询。
+2. 指定客户的财务记录查询。
+
+它不适合承担以下职责：
+
+1. 开放式闲聊。
+2. 多轮澄清式对话。
+3. 写入、审批、修改业务数据。
+4. 复杂统计分析和自定义报表。
+
+因此，企业微信侧的入口设计应尽量采用“菜单驱动 + 明确提问”的方式，而不是把它当成一个无限制聊天窗口。
+
+## 2. 当前调用入口
+
+当前服务对外提供的 Agent 入口为：
+
+- `POST /agent`
+
+健康检查：
+
+- `GET /health`
+
+当前请求体：
+
+```json
+{
+  "message": "查询华东未出货出货单",
+  "merchant_id": 1
+}
+```
+
+当前响应体：
+
+```json
+{
+  "reply": "目前查询到华东区域没有未出货的出货单（结果为0条）。"
+}
+```
+
+说明：
+
+- `message` 为发送给 Agent 的自然语言问题。
+- `merchant_id` 目前只对商户隔离型业务 API 生效。
+- 财务查询当前不依赖 `merchant_id`。
+- 返回值是自然语言文本，面向企业微信 markdown 消息渲染。
+
+## 3. 当前能力范围
+
+### 3.1 商户业务查询
+
+当前已接入以下业务能力：
+
+1. 查询 MES 设备列表。
+2. 查询指定日期范围内的 MES 生产安排。
+3. 查询运输车辆详情。
+4. 查询未进入送货单的出货单。
+
+这些能力依赖：
+
+- `merchant_id`
+
+因此企业微信应用侧如果要接这类查询，建议在进入 Agent 前就明确当前商户身份，或由调用方稳定注入 `merchant_id`。
+
+### 3.2 财务查询
+
+当前已接入以下财务记录类型：
+
+1. 销售记录
+2. 销退记录
+3. 收款记录
+4. 退款记录
+
+财务查询支持：
+
+- 单选一种记录类型
+- 多选多种记录类型
+- 宽泛的“财务记录”查询
+
+财务查询还能区分：
+
+1. 真实资金变动
+2. 挂账 / 冲减 / 欠款调整
+
+## 4. 当前明确不支持的能力
+
+企业微信应用开发组应优先在入口侧理解这些边界，因为这些能力不应引导给 Agent。
+
+### 4.1 不支持写操作
+
+当前不支持：
+
+1. 写入财务数据
+2. 修改财务数据
+3. 删除财务数据
+4. 审批财务数据
+5. 纠正财务数据
+6. 写入业务单据
+
+如果用户发起这类请求，推荐在企业微信应用侧直接拦截，或允许 Agent 返回标准拒绝说明。
+
+### 4.2 不支持复杂统计
+
+当前财务接口只支持“查记录”，不支持复杂统计分析。
+
+允许的上限只有：
+
+1. 对返回记录做直接计数。
+2. 对返回记录做直接累计。
+
+当前不支持：
+
+1. 按季度汇总
+2. 按月汇总
+3. 按年汇总
+4. 环比
+5. 同比
+6. 趋势分析
+7. 占比分析
+8. 分组统计
+9. 筛选后再累计
+10. 小计、分类汇总、派生统计口径
+
+如果企业微信应用已经能判断是这类诉求，建议不要直接把这类问题送给 Agent。
+
+## 5. 企业微信消息渲染约束
+
+当前 Agent 的回复是按企业微信应用消息中的 markdown 消息来约束的。
+
+已知约束如下：
+
+1. 企业微信 markdown 只支持 markdown 子集。
+2. `content` 最长不超过 `2048` 字节，UTF-8 编码。
+3. 当前 Agent 会尽量把回复压缩在约 `1200` 字节以内。
+4. 不应使用表格。
+5. 不应使用 fenced code block。
+6. 不应使用复杂嵌套列表。
+7. 不应依赖复杂 HTML 排版。
+
+当前更适合的展示形式：
+
+1. 一段简洁结论。
+2. 2 到 5 条短列表。
+3. 必要时附少量关键字段。
+
+因此，企业微信应用侧不应期待 Agent 返回：
+
+1. 表格型结果
+2. 长篇报告
+3. 大批量明细完整铺开
+
+## 6. 入口设计建议
+
+### 6.1 推荐采用单入口调用，多菜单引导
+
+当前技术上只需要一个 Agent 接口入口：
+
+- `POST /agent`
+
+但在企业微信应用层，建议不要只给一个“自由提问”入口。更合适的是：
+
+1. 菜单项负责限定业务范围。
+2. 菜单点击后，用明确提示语引导用户输入必要字段。
+3. 应用层把整理后的自然语言问题发送给 `/agent`。
+
+换句话说，推荐是“多个菜单入口，共用一个 Agent API”。
+
+### 6.2 推荐菜单分组
+
+建议至少拆成两大类：
+
+1. 生产/物流类查询
+2. 财务类查询
+
+财务类再细分为：
+
+1. 查询客户销售记录
+2. 查询客户销退记录
+3. 查询客户收款记录
+4. 查询客户退款记录
+5. 查询客户全部财务记录
+
+生产/物流类可拆为：
+
+1. 查询 MES 设备
+2. 查询生产安排
+3. 查询车辆信息
+4. 查询未出货出货单
+
+## 7. 提问引导建议
+
+### 7.1 总原则
+
+企业微信侧不应引导用户输入过于自由的问题，而应尽量引导输入“Agent 已支持的字段”。
+
+推荐原则：
+
+1. 一次只问一类问题。
+2. 提示词里直接说明需要提供什么。
+3. 对关键参数给示例。
+4. 不要让用户猜系统支持哪些写法。
+
+### 7.2 财务类推荐引导文案
+
+#### 查询客户销售记录
+
+推荐引导：
+
+```text
+请输入客户名称，例如：查询杭州某客户的销售记录
+```
+
+#### 查询客户销退记录
+
+推荐引导：
+
+```text
+请输入客户名称，例如：查询杭州某客户的销退记录
+```
+
+#### 查询客户收款记录
+
+推荐引导：
+
+```text
+请输入客户名称，例如：查询杭州某客户的收款记录
+```
+
+#### 查询客户退款记录
+
+推荐引导：
+
+```text
+请输入客户名称，例如：查询杭州某客户的退款记录
+```
+
+#### 查询客户全部财务记录
+
+推荐引导：
+
+```text
+请输入客户名称，例如：查询杭州某客户的财务记录
+```
+
+#### 查询挂账或冲减
+
+推荐引导：
+
+```text
+请输入客户名称，并明确说明挂账或冲减，例如：查询杭州某客户的收款挂账调整记录
+```
+
+### 7.3 生产/物流类推荐引导文案
+
+#### 查询 MES 设备
+
+推荐引导：
+
+```text
+请输入查询需求，例如：查询当前商户的 MES 设备
+```
+
+#### 查询生产安排
+
+推荐引导：
+
+```text
+请输入日期范围，例如：查询 2026-05-01 到 2026-05-07 的生产安排
+```
+
+#### 查询车辆信息
+
+推荐引导：
+
+```text
+请输入车牌号，例如：查询车牌 粤A12345 的车辆信息
+```
+
+#### 查询未出货出货单
+
+推荐引导：
+
+```text
+请输入地区，例如：查询华东未出货出货单
+```
+
+## 8. 建议的应用层预处理
+
+企业微信应用侧建议做以下最小预处理：
+
+1. 注入 `merchant_id`，如果当前入口属于商户业务场景。
+2. 保留用户原始问题，不要做过度改写。
+3. 可以在菜单点击后，补一个简短上下文前缀，例如：
+   - `当前是财务查询场景：查询杭州某客户的销退记录`
+   - `当前是生产安排查询场景：查询 2026-05-01 到 2026-05-07 的生产安排`
+4. 不要在应用层生成复杂长提示词，避免和 Agent 提示词互相冲突。
+
+## 9. 建议的应用层拦截规则
+
+以下问题建议在企业微信应用层直接拦截，或者至少标记为“超出当前 Agent 支持范围”：
+
+1. `帮我新增一条财务记录`
+2. `把这个客户的退款改掉`
+3. `审批这笔收款`
+4. `按季度汇总这个客户的销售和回款`
+5. `统计今年每个月的销退趋势`
+6. `按地区筛选后累计某客户收款`
+
+推荐返回说明：
+
+```text
+当前入口只支持记录查询，不支持写入、修改、审批或复杂统计分析。
+```
+
+## 10. 建议的调用方式
+
+### 10.1 财务查询示例
+
+```json
+{
+  "message": "查询杭州某客户的销退记录"
+}
+```
+
+### 10.2 商户业务查询示例
+
+```json
+{
+  "message": "查询华东未出货出货单",
+  "merchant_id": 1
+}
+```
+
+### 10.3 财务能力说明类示例
+
+```json
+{
+  "message": "你可以查询哪些财务数据？是否可以多选？"
+}
+```
+
+期望回答方向：
+
+1. 支持销售、销退、收款、退款。
+2. 可以单选，也可以多选。
+3. 如果问“财务记录”，可以查全部四类。
+
+## 11. 推荐的消息处理流程
+
+推荐流程如下：
+
+1. 用户点击菜单。
+2. 企业微信应用展示该菜单对应的引导语。
+3. 用户输入问题。
+4. 应用层判断是否需要补 `merchant_id`。
+5. 应用层判断是否属于明显超范围请求。
+6. 如果在支持范围内，则调用 `/agent`。
+7. 将 `reply` 直接作为企业微信 markdown 消息发送。
+
+## 12. 入口选择建议
+
+如果开发组需要判断“应该做几个入口”，建议如下：
+
+### 方案 A：一个统一输入入口
+
+优点：
+
+1. 技术实现最简单。
+2. 前端交互最少。
+
+缺点：
+
+1. 用户容易提超范围问题。
+2. 参数缺失率会更高。
+3. 结果稳定性较弱。
+
+### 方案 B：按业务域拆菜单，共用一个 Agent API
+
+优点：
+
+1. 更符合当前 Agent 的能力边界。
+2. 更容易做提问引导。
+3. 回复稳定性更高。
+4. 更适合企业微信菜单场景。
+
+缺点：
+
+1. 菜单设计需要更多前期整理。
+
+当前更推荐：
+
+- 采用方案 B。
+
+## 13. 当前接入结论
+
+对于企业微信应用开发组，当前最合适的接入方式不是“开放聊天入口”，而是：
+
+1. 用菜单限制问题范围。
+2. 用引导语约束用户输入。
+3. 用一个统一的 `/agent` 入口承接调用。
+4. 在应用层提前拦截写操作和复杂统计类请求。
+
+这样能最大程度发挥当前 Agent 的查询能力，同时避免把不支持的能力暴露成错误体验。