erpnew/docs/WECOM_APP_INTEGRATION_GUIDE.md

# 企业微信应用接入说明

本文档面向企业微信自建应用开发组，说明当前 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 的查询能力，同时避免把不支持的能力暴露成错误体验。