# 杜康好客 · v3.5.16 开发文档

> **2026-09-03** · integrations/wecom · admin-web · domain · shared-types  
> **主题**：企微智能机器人 **API 插件**只读数据面

---

## 1. 版本目标

企微后台「添加 API 插件」对接本系统：企微托管大模型 HTTP 调公网接口拉数。与 HQ「企微机器人」长连接 Bot **独立**，不改指令/审批/短信验身。

**不做**：写操作、明文手机/地址、把 `/admin/*` JWT 接口暴露给企微。

---

## 2. 与长连接 Bot 的分工

| | 长连接智能机器人 | API 插件 |
|--|------------------|----------|
| 对话 | 我们收消息并回复 | 企微自带模型组织回复 |
| 入口 | HQ 企微机器人 + `@wecom/aibot-node-sdk` | 企微「添加 API 插件」 |
| 鉴权 | BotID / Secret | Header `X-Api-Key` |
| 能力 | 指令 + 工单/审批等 | 第一期只读查询 |

建议：客服/技术支持继续走长连接；另建一只「运营查询」机器人只挂本插件。

---

## 3. 环境变量

```
WECOM_PLUGIN_ENABLED=true
WECOM_PLUGIN_API_KEY=<随机长密钥>
```

只放 `.env` / `.env.staging` / `.env.production`，不进 HQ 系统设置、不进 Git。

---

## 4. 接口

前缀：`/api/v1/wecom/plugin`  
鉴权：Header `X-Api-Key`（未启用 / 无 Key / 错 Key 一律 401）  
响应：`{ code, message, data }`（`GET .../openapi.json` **除外**，原样 OpenAPI 3.0）  
列表 `pageSize` 默认 5、最大 10。手机号 `maskContactPhone`。

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 插件说明 |
| GET | `/openapi.json` | 供第 2 步导入工具 |
| GET | `/orders?q=` | 订单号 |
| GET | `/users?q=` | 用户号或 11 位手机 |
| GET | `/stores?q=` | 门店名 |
| GET | `/redeems?q=` | 核销单号或门店名 |
| GET | `/promo-codes?q=` | 推广码 / 名称 |
| GET | `/promo-codes/:code/stats` | 推广码统计 |
| GET | `/metrics?kind=` | `today` \| `daily` \| `weekly` \| `monthly` |

经营指标口径与 v3.5.15 报告一致：用户=有效未合并；订单金额=已付 `payAmount`（`paidAt`）；核销=`RedeemRecord`。`today` 期末为当前时刻。

审计：`log_wecom_bot.botKey=plugin`。

---

## 5. 企微表单（上线后）

| 字段 | 值 |
|------|-----|
| 插件 URL | 生产 `https://api.dukanghaoke.com/api/v1/wecom/plugin`；测试 `https://api-test.dukanghaoke.com/api/v1/wecom/plugin` |
| 授权 | Service token / API key |
| 位置 | Header |
| Parameter name | `X-Api-Key` |
| Service token | 与 `WECOM_PLUGIN_API_KEY` 相同 |
| 第 2 步导入 | `…/wecom/plugin/openapi.json`（同一把 Key） |

---

## 6. 联调清单（staging curl）

先在 `api-test` 的 `.env.staging` 打开开关并写入 Key，重启 `dukang-api`。

```bash
BASE=https://api-test.dukanghaoke.com/api/v1/wecom/plugin
KEY='<WECOM_PLUGIN_API_KEY>'

# 无 Key → 401
curl -sS -o /dev/null -w '%{http_code}\n' "$BASE/metrics"

# 错 Key → 401
curl -sS -o /dev/null -w '%{http_code}\n' -H "X-Api-Key: wrong" "$BASE/metrics"

# 经营指标 / OpenAPI / 订单 / 门店 / 推广码
curl -sS -H "X-Api-Key: $KEY" "$BASE/metrics?kind=today"
curl -sS -H "X-Api-Key: $KEY" "$BASE/openapi.json" | head -c 200
curl -sS -H "X-Api-Key: $KEY" "$BASE/orders?q=DK"
curl -sS -H "X-Api-Key: $KEY" "$BASE/stores?q=店"
curl -sS -H "X-Api-Key: $KEY" "$BASE/promo-codes?q=DK"
```

企微：导入 OpenAPI → 白名单会话用自然语言问订单/门店 → HQ「企微机器人 → 日志」出现 `plugin`。

---

## 7. 变更面

| 层 | 路径 |
|----|------|
| domain | `wecom-plugin.ts` |
| shared-types | `wecom-plugin.ts` |
| API | `integrations/wecom/wecom-plugin.*`；`WecomModule` 注册 Controller |
| HQ | `WecomBotsPage.tsx` 插件 URL / Header 提示（不展示 Key） |
| env | `.env*.example`：`WECOM_PLUGIN_ENABLED` / `WECOM_PLUGIN_API_KEY` |

---

## 8. 验收

- [ ] 无 Key / 错 Key → 401
- [ ] curl 带 Key 查订单 / 门店 / 推广码 / 今日指标，`{ code:0, data }` 且手机脱敏
- [ ] `openapi.json` 为 OpenAPI 文档（无信封）
- [ ] 企微第 2 步可导入工具；白名单会话能问到真实数据
- [ ] HQ 企微机器人日志可见 `plugin`
- [ ] 现有长连接 Bot 行为不变