jacy
976bde37cc
与 REST/OpenAPI 并存，按实例权限自动 tools/list，免手填工具。 Co-authored-by: Cursor <cursoragent@cursor.com>
97 lines
3.8 KiB
Markdown
97 lines
3.8 KiB
Markdown
# 杜康好客 · 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. 企微侧怎么配
|
||
|
||
详见 **[企微 API 插件 · 配置手册](./企微API插件-配置手册.md)**。v3.5.18 起优先配 MCP 插件；本节 API + 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 / 消息推送 / 报告行为不变
|