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

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

---

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. 企微侧怎么配

详见 企微 API 插件 · 配置手册（第 1 步插件、第 2 步工具/OpenAPI 导入、全接口参数表）。

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 / 消息推送 / 报告行为不变