企业微信智能机器人API插件

docs/杜康好客-v3-现状对照.md

@@ -68,9 +68,11 @@
 | 3.5.11 | [`城市履约起购 + 企微通知字段与结算通知`](./杜康好客-v3.5.11-开发文档.md) | 🔶 开发完成 |
 | 3.5.12 | [`订单大屏 BGM + HQ 中文展示 + 修复删除门店分类 + HQ 侧栏顺序`](./杜康好客-v3.5.12-开发文档.md) | 🔶 开发完成 |
 | 3.5.14 | [`提交订单/支付成功日志端回填 USER_MINI`](./杜康好客-v3.5.14-开发文档.md) | 🔶 开发完成 |
+| 3.5.16 | [`企微智能机器人 API 插件`](./杜康好客-v3.5.16-开发文档.md) | 🔶 开发完成 |
 
 | 日期 | 说明 |
 |------|------|
+| 2026-09-03 | v3.5.16：企微 API 插件只读数据面 `GET /api/v1/wecom/plugin/*`（X-Api-Key）；与长连接 Bot 独立 |
 | 2026-08-30 | HQ 门店账单确认打款支持上传凭证照片（`payment_proof_urls`） |
 | 2026-08-26 | v3.5.14：`order_submit`/`pay_success` 埋点改用真实 `clientApp`；线上这两类 `USER_H5` 回填为 `USER_MINI` |
 | 2026-08-26 | v3.5.12：订单大屏循环 BGM；HQ 日志/订单状态流转/用户行为时间线英文码改中文；修复删除门店分类后被 `ensureDefaults` 回种；HQ 侧栏按业务前 11 项重排、系统设置置底 |

docs/杜康好客-v3.5.16-开发文档.md

@@ -0,0 +1,123 @@
+# 杜康好客 · 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 行为不变

docs/杜康好客-v3编码手册.md

@@ -48,6 +48,8 @@ C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAd
 
 **HQ 企微报告（v3.5.15）**：企微机器人下「报告」与「消息推送」分开。日报/周报/月报各配 Webhook 与发送时刻；走群机器人 markdown。账期截在发送日北京 0 点（前一天 24 点），不含发送当天：日报=昨日存量+当日新增；周报/月报=上一自然周/月期末存量+本期新增。用户=有效未合并；合伙人=主账号；订单金额=已付 `payAmount`（`paidAt`）；核销=`RedeemRecord`。
 
+**企微 API 插件（v3.5.16）**：`GET /api/v1/wecom/plugin/*`，Header `X-Api-Key`；只读订单/用户/门店/核销/推广码/经营指标。与长连接 Bot 独立。OpenAPI：`GET /api/v1/wecom/plugin/openapi.json`。
+
 **HQ 列表（v3.5.9）**：主表不省略号、可横滑；最左序号；列设置（显隐/顺序）与列宽（拖表头）存 `hq_account.list_column_prefs`。主展示列下划线，点击进编辑或详情。门店列表「累计核销好客权益」= 该店 `RedeemRecord.amount` 合计。用户列表昵称只读（点击进详情）；双击「备注」离开即保存（`hq_remark`）；列表手机号不脱敏。
 
 **C 端（v3.5.10）**：门店详情无顶栏分享按钮。同城送提示取开城仓库绑定承运商的 `delivery_hint_html`（`GET /catalog/local-deliveries`，按收货市是否开城）；空则回退「同城配送，预计24小时内送到」。在线客服优先 `wx.openCustomerServiceChat`（`CUSTOMER_SERVICE_WECOM_URL` + `WECOM_CORP_ID`）；未配 CorpID 回退小程序原生客服。

docs/杜康好客-知识库.md

@@ -150,6 +150,7 @@ HQ 账号/角色(`hq-permissions`，生效=(角色∪追加)−撤销；可绑
 | 能力 | 入口 |
 |------|------|
 | 智能机器人 | `/wecom/bots` 长连接指令 |
+| API 插件 | `/api/v1/wecom/plugin` Header `X-Api-Key` 只读查询（与长连接独立） |
 | 消息推送 | `/wecom/pushes` Webhook+eventKey |
 | 日志 | `/logs/wecom-bots` |
 | C 端微信客服 | 系统设置 `CUSTOMER_SERVICE_WECOM_URL` + `WECOM_CORP_ID`；小程序须已关联该企业微信客服 |