v4.0.17企业微信API插件优化

2026-09-06 09:36:49 +08:00
parent 0e711be6c6
commit 192a401227
36 changed files with 2416 additions and 103 deletions
@@ -69,9 +69,11 @@
 | 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) | 🔶 开发完成 |
+| 3.5.17 | [`企微 API 插件迁入 HQ 后台`](./杜康好客-v3.5.17-开发文档.md) | 🔶 开发完成 |

 | 日期 | 说明 |
 |------|------|
+| 2026-09-06 | v3.5.17：企微 API 插件迁入 HQ「企微机器人 → API 插件」；多实例 Key + 工具权限；不再依赖 `WECOM_PLUGIN_*` env |
 | 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` |
@@ -0,0 +1,94 @@
+# 杜康好客 · v3.5.17 开发文档
+
+> **2026-09-06** · integrations/wecom · ops · admin-web · domain · shared-types  
+> **主题**：企微 API 插件迁入 HQ 后台（多实例 + 动态工具权限）
+
+---
+
+## 1. 版本目标
+
+把企微 API 插件从 `.env` 单 Key 迁到 HQ「企微机器人 → API 插件」：支持多实例，每实例一把 `X-Api-Key` 与一组工具权限。企微侧仍用同一 Base URL，各插件填不同 Key，第 2 步只配置已授权工具。
+
+**不做**：改长连接 Bot / 消息推送 / 报告；新增 HQ 权限键（继续 `wecom_bots`）；插件写操作；每实例独立 Base Path。
+
+---
+
+## 2. 映射约定
+
+| 项 | 值 |
+|----|-----|
+| 一条 HQ 实例 | 企微里一只「API 插件」 |
+| Base URL | `/api/v1/wecom/plugin`（生产/测试域名不变） |
+| 区分实例 | Header `X-Api-Key` |
+| 未授权工具 | 403 |
+| `GET /openapi.json` | 按当前 Key 的 permissions 过滤 paths |
+
+---
+
+## 3. 表 `wecom_api_plugin`
+
+| 字段 | 说明 |
+|------|------|
+| name | 展示名 |
+| api_key | 明文存库（列表只返 `apiKeyConfigured` / `apiKeyMasked`） |
+| permissions | JSON 字符串数组：`order.read` · `user.read` · `store.read` · `redeem.read` · `promo.read` · `metrics.read` |
+| remark / enabled / sort_order | 备注、启停、排序 |
+
+迁移：`pnpm --filter @dukang/api prisma:migrate-wecom-api-plugin`（或 `db push`）。
+
+启动时若表为空且 env 仍有 `WECOM_PLUGIN_ENABLED=true` + `WECOM_PLUGIN_API_KEY`，一次性 upsert「迁移自 env」（全权限），避免断服。新部署不再依赖这两项 env。
+
+---
+
+## 4. 运行时
+
+- Guard：读 `X-Api-Key`，在 `enabled=true` 实例中常量时间比对，命中则挂 `req.wecomPlugin`
+- 无启用实例 / Key 未命中 → 401
+- 各工具入口 `requirePerm`；无权限 → 403
+- `GET /`：该实例 name + 已授权 tools
+- 审计：`log_wecom_bot.botKey=plugin:{id}`，`action=plugin.order.read` 等
+
+### 工具权限目录（v3.5.17 增补）
+
+| 权限 | 路径 |
+|------|------|
+| `metrics.read` | `/metrics`（含 `newStores` / `storesIncrement` 新增门店） |
+| `store.read` | `/stores`（名称搜索 + 评分/核销/累计核销/合伙人） |
+| `store.audit.read` | `/store-audits`、`/store-info-audits`、`/store-package-audits` 及 `/{id}` 对比详情 |
+| `partner.read` | `/partners`、`/partners/{id}/users|stores|orders`（可选 `from`/`to` 时间筛选） |
+
+---
+
+## 5. Admin API
+
+权限键 `wecom_bots`。列表/详情永不回显完整 Key；创建与 `POST /:id/rotate-key` 一次性返回明文。
+
+| 方法 | 路径 |
+|------|------|
+| GET/POST | `/admin/wecom-api-plugins` |
+| GET/PUT/DELETE | `/admin/wecom-api-plugins/:id` |
+| POST | `/admin/wecom-api-plugins/:id/rotate-key` |
+
+创建时未填 `apiKey` 则服务端生成。更新时 `apiKey` 空=不变。
+
+---
+
+## 6. 企微侧怎么配
+
+1. 插件 URL = HQ 页展示的 Base URL（全实例相同）
+2. Header `X-Api-Key` = 该实例密钥
+3. 第 2 步只添加 HQ 已勾选的工具（GET + Query）；可用带 Key 的 `openapi.json` 对照路径
+
+权限示例：运营勾全量；客服只勾 `order.read` / `user.read` / `store.read`。
+
+---
+
+## 7. 验收
+
+- [ ] HQ 建两个插件不同权限 → 同 URL 不同 Key → 分别能/不能调 `/orders`
+- [ ] 无 Key / 错 Key → 401；无权限工具 → 403
+- [ ] 带 Key 的 `openapi.json` 只含已授权 paths（无信封）
+- [ ] `/metrics` 返回 `newStores`；`/stores` 含经营字段；审核/合伙人工具按权限可用
+- [ ] 创建/轮换后明文 Key 只回显一次；列表为掩码
+- [ ] 企微调试通过；日志 `plugin:{id}`
+- [ ] 长连接 Bot / 消息推送 / 报告行为不变
@@ -48,7 +48,7 @@ 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`。
+**企微 API 插件（v3.5.17）**：实例在 HQ「企微机器人 → API 插件」维护；共用 `GET /api/v1/wecom/plugin/*`，Header `X-Api-Key` 区分实例并按权限放行。经营指标含新增门店（`newStores`）；门店搜索含经营数据；支持门店/信息/套餐审核对照只读查询；支持按合伙人查关联用户/门店/订单（`from`/`to` 时间筛选）。

 **HQ 列表（v3.5.9）**：主表不省略号、可横滑；最左序号；列设置（显隐/顺序）与列宽（拖表头）存 `hq_account.list_column_prefs`。主展示列下划线，点击进编辑或详情。门店列表「累计核销好客权益」= 该店 `RedeemRecord.amount` 合计。用户列表昵称只读（点击进详情）；双击「备注」离开即保存（`hq_remark`）；列表手机号不脱敏。

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