124 lines
4.2 KiB
Markdown
124 lines
4.2 KiB
Markdown
# 杜康好客 · 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 行为不变
|