杜康好客 · 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。

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 行为不变

4.2 KiB Raw Blame History Unescape Escape