feat(ops): 总部可按百分比限制接口放行并开关企微通知

线上需要按账户、用户和功能控制登录与加载成功率，同时单独停发订单、核销和账单通知。

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/杜康好客-v3编码手册.md

@@ -68,6 +68,8 @@ C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAd
 
 **合伙人关联与订单佣金（v4.0.1 / v4.0.9）**：规则见 v4-PRD。`user_user.assoc_partner_account_id` 首次扫码锁定；`user_order.partner_account_id_at_pay` 仅关联或代下单显式选择写入（禁止区县解析）。`partner_bill_item` 分酒单 / 核销两段。合伙人备注独立表 `partner_user_note`（勿写 `hq_remark`）。`POST /user/partner-assoc/bind` · `POST /user/partner-assoc/touch`（未登录可计已扫码）· `GET /partner/assoc`（`scanCount` + `userCount`；子账号无 `activityPosterId`）· `GET /partner/assoc/stats`（关联用户 / 当前关联用户已付购酒单，本日/本月）· `GET /partner/assoc/users?keyword&sort`（合伙人侧返回 `partnerRemark`，不返回 `hqRemark`；主账号与子账号均可）· `GET /partner/assoc/users/:userId/orders` · `GET /partner/assoc/orders` · `PUT /partner/assoc/users/:userId/remark` · HQ `GET /admin/users` 支持 `keyword`、`assocPartnerAccountId`（`none` / `any` / 主账号 ID）· `GET /admin/orders` 支持 `assocPartnerAccountId`（筛本单快照，`none`=无快照）· `PUT /admin/users/:id/assoc`（权限 `users_partner_assoc`）改绑/解绑 · 开城合伙人关联用户快链 `/users?assocPartnerAccountId=` · `PUT /admin/partners/:id` 改费率用 `Decimal(toFixed(4))`。子账号创建默认 `ACTIVE`。主账号 `PUT /partner/me/bank` 填收款账户。HQ `GET /admin/partners/:id/assoc/qrcode` 下载裸关联码 PNG（与「下载活动图」合成海报分开）。
 
+**接口访问（v4.0.21）**：规则见 v4-PRD §10 与 [`v4.0.21 开发文档`](./杜康好客-v4.0.21-开发文档.md)。表 `api_access_policy`（common）。HQ `GET/PUT /admin/api-access`、`POST/DELETE /admin/api-access/overrides`、`GET /admin/api-access/actors`（权限 `api_access`）。百分比默认 100；通知开关默认开。总部登录与配置接口不拦截。
+
 **推广码渠道负责人 / 关联合伙人（v4.0.20）**：规则见 v4-PRD §2.1 与 [`v4.0.20 开发文档`](./杜康好客-v4.0.20-开发文档.md)。表 `promo_code_channel_owner`（多对多主合伙人）+ `common_promo_code.assoc_partner_account_id`。HQ `POST/PUT /admin/promo-codes` 字段 `channelOwnerPartnerIds`、`assocPartnerAccountId`（须主账号 ACTIVE）。`POST /promo/touch` 登录后对关联合伙人 `PartnerCityService.tryBindIfUnbound`（已绑他人静默跳过，不回刷历史；Promo 不 import StoreModule）。合伙人主账号 `GET /partner/promo-codes` 仅返回 `scanCount` / `attributionCount` / `orderCount`（已完成订单），禁止用户/事件/订单明细。H5 入口：合伙人中心 → 运营管理 → 推广码数据。验收：只配渠道负责人不绑用户；只配关联合伙人会进「关联用户」且能看三项汇总；已关联他人扫码流程不中断。
 
 **合伙人周结算（v4.0.9）**：每周一 08:00 生成上一自然周账单。`GET /partner/settlement/cycle` 账期与出账日；`GET /partner/settlement/preview` 本周一至今预付款预估。零元账单 HQ 可见待审核、不可发送、合伙人端不可见。历史月账不回刷。

docs/杜康好客-v4-PRD.md

@@ -1,9 +1,8 @@
 # 杜康好客 · V4 PRD
 
-> **v4.0**（2026-08-29）· 关联码与分佣事实源；**v4.0.6** 酒厂对账；**v4.0.7** HQ 活动图快链与勾选导出；**v4.0.9** 合伙人 H5 周结算与用户管理；**v4.0.14** HQ 概览粒度；**v4.0.15** HQ 概览折线图；**v4.0.18** 子账号继承码、财务全部银行账户目录；**v4.0.20** 推广码渠道负责人/关联合伙人  
-> 未改规则仍见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。**冲突时 V4 > V3**（本主题：订单佣金归属、关联码、推广码渠道负责人/关联合伙人、合伙人账单明细、活动图、酒厂对账、合伙人周结算、HQ 概览、财务银行账户）。  
-> 未改规则仍见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。**冲突时 V4 > V3**（本主题：订单佣金归属、关联码、推广码渠道负责人/关联合伙人、合伙人账单明细、活动图、酒厂对账、合伙人周结算、HQ 概览、财务银行账户）。  
-> 实现：[`v4.0.1 开发文档`](./杜康好客-v4.0.1-开发文档.md) · [`v4.0.2 开发文档`](./杜康好客-v4.0.2-开发文档.md) · [`v4.0.6 开发文档`](./杜康好客-v4.0.6-开发文档.md) · [`v4.0.7 开发文档`](./杜康好客-v4.0.7-开发文档.md) · [`v4.0.9 开发文档`](./杜康好客-v4.0.9-开发文档.md) · [`v4.0.14 开发文档`](./杜康好客-v4.0.14-开发文档.md) · [`v4.0.15 开发文档`](./杜康好客-v4.0.15-开发文档.md) · [`v4.0.18 开发文档`](./杜康好客-v4.0.18-开发文档.md) · [`v4.0.20 开发文档`](./杜康好客-v4.0.20-开发文档.md) · 审计：[`v4-现状对照`](./杜康好客-v4-现状对照.md)
+> **v4.0**（2026-08-29）· 关联码与分佣事实源；**v4.0.6** 酒厂对账；**v4.0.7** HQ 活动图快链与勾选导出；**v4.0.9** 合伙人 H5 周结算与用户管理；**v4.0.14** HQ 概览粒度；**v4.0.15** HQ 概览折线图；**v4.0.18** 子账号继承码、财务全部银行账户目录；**v4.0.20** 推广码渠道负责人/关联合伙人；**v4.0.21** 接口访问  
+> 未改规则仍见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。**冲突时 V4 > V3**（本主题：订单佣金归属、关联码、推广码渠道负责人/关联合伙人、合伙人账单明细、活动图、酒厂对账、合伙人周结算、HQ 概览、财务银行账户、接口访问）。  
+> 实现：[`v4.0.1 开发文档`](./杜康好客-v4.0.1-开发文档.md) · [`v4.0.2 开发文档`](./杜康好客-v4.0.2-开发文档.md) · [`v4.0.6 开发文档`](./杜康好客-v4.0.6-开发文档.md) · [`v4.0.7 开发文档`](./杜康好客-v4.0.7-开发文档.md) · [`v4.0.9 开发文档`](./杜康好客-v4.0.9-开发文档.md) · [`v4.0.14 开发文档`](./杜康好客-v4.0.14-开发文档.md) · [`v4.0.15 开发文档`](./杜康好客-v4.0.15-开发文档.md) · [`v4.0.18 开发文档`](./杜康好客-v4.0.18-开发文档.md) · [`v4.0.20 开发文档`](./杜康好客-v4.0.20-开发文档.md) · [`v4.0.21 开发文档`](./杜康好客-v4.0.21-开发文档.md) · 审计：[`v4-现状对照`](./杜康好客-v4-现状对照.md)
 
 ## 0. 版本
 
@@ -18,6 +17,7 @@
 | 4.0.15 | 09-02 | HQ 概览改为全宽折线图：粒度分桶、总量/增量、维度线条；查看快链只带全局筛选 | [`v4.0.15`](./杜康好客-v4.0.15-开发文档.md) |
 | 4.0.18 | 09-07 / 09-08 | C 端门店列表省+市+区+详细地址（原样拼接、不去重）；子账号独立继承二维码 + 子账号维度统计；HQ 财务全部银行账户（门店行读结算资质）；撤销门店多收款账户 | [`v4.0.18`](./杜康好客-v4.0.18-开发文档.md) |
 | 4.0.20 | 09-16 / 09-17 | 推广码渠道负责人多选主合伙人（H5 只看三项汇总）；关联合伙人扫码 first-lock，不回刷、已关联他人静默跳过 | [`v4.0.20`](./杜康好客-v4.0.20-开发文档.md) |
+| 4.0.21 | 09-26 | HQ 接口访问：登录/商品/门店加载/门店提交按成功百分比放行；审核通知按百分比丢弃；订单/核销/账单/门店审核/套餐修改仅作企微通知总开关 | [`v4.0.21`](./杜康好客-v4.0.21-开发文档.md) |
 
 ## 1. 锚点（沿用 V3，佣金归属改写）
 
@@ -133,6 +133,29 @@ HQ「财务 → 全部银行账户」聚合**有效**银行账户，供财务查
 - 「其他」账户仅登记备查，不进入门店提现、账单打款、酒厂/物流对账。
 - 权限：`finance`。
 
-## 10. 不做
+## 10. 接口访问（v4.0.21）
+
+HQ「接口访问」（权限 `api_access`，危险权限，超管可用，其他角色需单独勾选）。表 `api_access_policy`。默认成功百分比 **100**、通知开关开，与未配置时一致。
+
+成功百分比是放行比例，每次请求独立随机：`0` 全拒，`100` 全放行。命中顺序：用户+功能 → 账户+功能 → 该用户全部功能 → 该账户全部功能 → 功能全局 → 放行。
+
+- **用户**：C 端 `User`。**账户**：总部 `HqAccount`、门店 `StoreAccount`、合伙人 `PartnerAccount`。
+- **登录**：C 端 / 门店 / 合伙人登录。未登录时若 body 有手机号，先匹配该手机号的用户或账户规则。**总部登录不参与**，避免百分比打成 0 后无法改回。配置接口本身不参与。
+- **商品加载**：`GET /catalog/products`、`GET /catalog/products/:id`。**门店加载**：`GET /stores`、`GET /stores/:id`。不含总部后台读接口。
+- **门店提交**：`POST /partner/stores` 新建入驻。
+- **审核通知**：不拦截审核写入；发送 `store.audit_pending` 时按百分比丢弃。
+- 被拒绝的 HTTP 返回 `{ code, message, reason }`，文案为网络加载失败 / 请求异常 / 非法访问 / 微信服务异常（规则可选，默认请求异常）。**不发企微告警**。各端展示 `message`，不改页面。
+
+通知总开关只决定还发不发企微，不拦下单、核销、出账、审核、改套餐。关掉后即使「消息推送」勾了条件也不发；打开后仍走原条件。运营日报/周报/月报不在此列（仍在「企微机器人 → 报告」）。
+
+| 开关 | 事件 |
+|------|------|
+| 订单推送 | `order.paid` |
+| 核销推送 | `redeem.success` |
+| 酒厂 / 城市合伙人 / 门店账单 | `finance.winery_bill` / `finance.partner_bill` / `finance.store_bill` |
+| 门店审核 | `store.audit_pending`（与审核通知百分比叠加：关则不发，开则只成功该百分比） |
+| 套餐修改 | `store.package_audit_pending` |
+
+## 11. 不做
 
 不把推广码改成关联码、不回刷历史绑定；改核销归属；回刷已打款账单；区县佣金双轨；AI 出图/出文案；C 端/门店端活动图；预生成每人缓存图。

docs/杜康好客-v4-现状对照.md

@@ -3,11 +3,11 @@
 > 基准：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)  
 > V3 进度仍见 [`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)，不混表。
 
-## 0. 总览（2026-09-17）
+## 0. 总览（2026-09-26）
 
 | 维度 | 结论 |
 |------|------|
-| 版本线 | **v4.0.20** 推广码渠道负责人 + 关联合伙人（含 v4.0.18 子账号继承码 / 财务全部银行账户） |
+| 版本线 | **v4.0.21** 接口访问（含 v4.0.20 推广码渠道负责人 + 关联合伙人） |
 | 订单佣金 | 区县归属已删除；只认关联 / 代下单选择 |
 | 账单 | 酒订单 / 核销订单分列；合伙人改为周账（周一 08:00）；零元不同步合伙人；酒厂含现场提货，零应付仍出账（无需打款） |
 | 活动图 | HQ 上传底图/码栏/文案；**v4.0.15 上传超限自动压缩并提示尺寸**；合伙人选择写入库；HQ 可指定一张图为勾选主合伙人合成下载；子账号不可看活动图 |
@@ -26,6 +26,7 @@
 | 4.0.15 | [`HQ 概览折线图`](./杜康好客-v4.0.15-开发文档.md) | ✅ 已实现 |
 | 4.0.18 | [`子账号继承二维码 + 财务全部银行账户（结算资质）`](./杜康好客-v4.0.18-开发文档.md) | ✅ 已实现 |
 | 4.0.20 | [`推广码渠道负责人 + 关联合伙人`](./杜康好客-v4.0.20-开发文档.md) | ✅ 已实现 |
+| 4.0.21 | [`接口访问`](./杜康好客-v4.0.21-开发文档.md) | ✅ 已实现 |
 
 | 日期 | 说明 |
 |------|------|
@@ -45,3 +46,4 @@
 | 2026-09-08 | v4.0.18 再修订：撤销门店多收款账户；打款与财务门店行改读结算资质（结算户名/银行账号/开户银行） |
 | 2026-09-16 | v4.0.20：推广码渠道负责人改为可多选主合伙人（H5 只看扫码/归因/订单数）；关联合伙人扫码 first-lock，不回刷、已关联他人静默跳过 |
 | 2026-09-17 | v4.0.20：PromoModule 改走 CityScope 避免 Nest 循环依赖；本地 Vite 代理默认 `127.0.0.1:3010` |
+| 2026-09-26 | v4.0.21：HQ 接口访问。登录/商品加载/门店加载/门店提交按成功百分比放行；审核通知按百分比丢弃企微；订单/核销/账单/门店审核/套餐修改只做通知总开关。总部登录不参与 |

docs/杜康好客-v4.0.21-开发文档.md

@@ -0,0 +1,55 @@
+# 杜康好客 · 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 时，审核写入成功，通知按比例丢弃

docs/杜康好客-知识库.md

@@ -143,7 +143,7 @@ HQ 推广码：场景/渠道负责人(主合伙人多选)/关联合伙人/上下
 
 ## 16. 系统设置
 
-HQ 账号/角色(`hq-permissions`，生效=(角色∪追加)−撤销；可绑城市；城市门店服务可增分类不可删，概览按权限/城市) · 客户端 `minClientVersion` · 运营告警走企微消息推送(DB Webhook)。
+HQ 账号/角色(`hq-permissions`，生效=(角色∪追加)−撤销；可绑城市；城市门店服务可增分类不可删，概览按权限/城市) · 客户端 `minClientVersion` · 运营告警走企微消息推送(DB Webhook)。接口访问（`/api-access`，权限 `api_access`）：按功能/账户/用户设成功百分比；订单/核销/账单/门店审核/套餐修改只关企微通知。
 
 ## 17. 企业微信