# 杜康好客 · v4.0.21 开发文档

> **2026-09-26** · common / ops / admin-web / domain / shared-types / wecom  
> **主题**：接口访问（成功百分比 + 企微通知总开关）

---

## 1. 版本目标

| # | 任务 | 类型 | 交付 |
|---|------|------|------|
| 1 | 成功百分比 | 需求 | 登录、商品加载、门店加载、门店提交按比例放行；可按用户、账户、功能覆盖 |
| 2 | 审核通知百分比 | 需求 | 不拦审核写入；`store.audit_pending` 按比例丢弃 |
| 3 | 通知总开关 | 需求 | 订单/核销/账单/门店审核/套餐修改只决定发不发企微 |

**不做**：运营日报/周报/月报开关（仍在企微机器人 → 报告）；用开关拦截下单、核销、出账、审核、改套餐；改各端错误页。

---

## 2. 规则

规则事实源：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md) §10。

- 默认百分比 100、通知开。每次请求独立随机。`0` 全拒，`100` 全放行。
- 命中：用户+功能 → 账户+功能 → 用户全部功能 → 账户全部功能 → 功能全局 → 放行。
- 总部 `POST /admin/auth/login/*` 与 `/admin/api-access` 不拦截。
- 拒绝文案四选一，默认「请求异常」；不推企微。
- 表未就绪时拦截失败即放行，避免未 `db push` 时把登录打满。

---

## 3. 数据与接口

表 `api_access_policy`（common OWNER）。

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/admin/api-access` | 五个全局百分比、覆盖规则、七个通知开关 |
| PUT | `/admin/api-access/globals` | 保存全局百分比与失败文案 |
| PUT | `/admin/api-access/notifies` | 保存通知开关 |
| POST | `/admin/api-access/overrides` | 新增账户或用户覆盖 |
| DELETE | `/admin/api-access/overrides/:id` | 删除覆盖 |
| GET | `/admin/api-access/actors?scope=user\|account&q=` | 搜索作用对象 |

权限 `api_access`（危险权限）。超管 bypass；开发者默认集不含该键。

---

## 4. 验收

- [ ] 百分比 100 时登录、商品、门店列表与现网一致
- [ ] 调低后对应请求按比例返回所选文案，且不推企微
- [ ] 总部登录在登录百分比为 0 时仍可用
- [ ] 关掉「订单推送」后支付仍完成，企微不再发 `order.paid`
- [ ] 门店审核开关开、审核通知百分比低于 100 时，审核写入成功，通知按比例丢弃