# 杜康好客 · 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` 时间筛选） |
| `dev_plan.read` | `/versions`、`/tasks`（MCP：`query_versions`、`query_tasks`，任务可按 status 筛选） |

---

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