v4.0.20版本迭代推广码增加渠道负责人

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

@@ -1,7 +1,7 @@
 # 杜康好客 · V3 编码手册（交付业务版）
 
 > **事实源**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · **审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)  
-> **佣金归属 / 关联码 / 合伙人账单明细（v4.0.1）· 活动图（v4.0.2）· 周结算与预付款（v4.0.9）· HQ 概览（v4.0.14 / v4.0.15）**：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)，冲突时 **V4 > V3**。  
+> **佣金归属 / 关联码 / 合伙人账单明细（v4.0.1）· 活动图（v4.0.2）· 周结算与预付款（v4.0.9）· HQ 概览（v4.0.14 / v4.0.15）· 推广码渠道负责人/关联合伙人（v4.0.20）**：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)，冲突时 **V4 > V3**。  
 > V2/preV1 **非需求依据**。总部交付 = **`apps/admin-web`**（非 H5）。
 
 ## 1. 交付目标（六条）
@@ -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.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 可见待审核、不可发送、合伙人端不可见。历史月账不回刷。
 
 ## 5. 验收用例（必过）

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

@@ -1,9 +1,9 @@
 # 杜康好客 · 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** 子账号继承码、财务全部银行账户目录  
-> 未改规则仍见 [`杜康好客-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-现状对照`](./杜康好客-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** 推广码渠道负责人/关联合伙人  
+> 未改规则仍见 [`杜康好客-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)
 
 ## 0. 版本
 
@@ -17,6 +17,7 @@
 | 4.0.14 | 09-02 | HQ 概览：日/周/月/季/年、环比、全局城市/时间 + 五板块筛；订单/核销笔数与金额 | [`v4.0.14`](./杜康好客-v4.0.14-开发文档.md) |
 | 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) |
 
 ## 1. 锚点（沿用 V3，佣金归属改写）
 
@@ -43,6 +44,15 @@
 - 主账号可在合伙人中心填写收款账户：收款人、银行账号、开户行名称（写入主账号 `bank_account_*`）。
 - HQ：用户列表综合搜索 + 关联合伙人筛选（`none` 未关联 / `any` 已关联全部 / 指定主合伙人），筛选默认展开；订单列表按本单佣金快照筛关联合伙人；开城城市合伙人提供「关联用户」快链与「全部关联用户」快链，进入用户列表并带上筛选。
 
+### 2.1 推广码 × 合伙人（v4.0.20）
+
+推广码仍是独立小程序码（数字 scene），**不复用**关联码 `pa_` / `sa_`。
+
+- **渠道负责人**（可空、多选主合伙人）：HQ 创建/编辑推广码可指定。被指定的**主账号**可在合伙人 H5「推广码数据」查看该码的**扫码人数、归因人数、订单数量**；不得查看用户明细、订单列表、核销或手机号等。
+- **关联合伙人**（可空、单选主合伙人）：登录用户扫该码且尚未关联任何人时，**first-lock** 到该主合伙人（写入 `assoc_partner_account_id` + `assocBoundAt`，不写子账号）。已关联他人不换绑、不报错。只绑以后扫进来的用户，**不回刷**历史归因用户。不增加关联码 `assoc_scan_count`。用户来源仍按推广码规则（ORGANIC 才标 `PROMO_CODE`）。
+- 两字段独立：只配渠道负责人不会绑用户；只配关联合伙人也会把用户写入该合伙人「关联用户」，并允许该合伙人看上述三项汇总。
+- 子账号不展示推广码数据入口。HQ 原 `ownerUserId`（C 端用户）不再编辑。
+
 ## 3. 订单佣金
 
 支付快照字段：`user_order.partner_account_id_at_pay`、`order_commission_rate_at_pay`。
@@ -125,4 +135,4 @@ HQ「财务 → 全部银行账户」聚合**有效**银行账户，供财务查
 
 ## 10. 不做
 
-改推广码体系；改核销归属；回刷已打款账单；区县佣金双轨；AI 出图/出文案；C 端/门店端活动图；预生成每人缓存图。
+不把推广码改成关联码、不回刷历史绑定；改核销归属；回刷已打款账单；区县佣金双轨；AI 出图/出文案；C 端/门店端活动图；预生成每人缓存图。

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

@@ -3,11 +3,11 @@
 > 基准：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)  
 > V3 进度仍见 [`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)，不混表。
 
-## 0. 总览（2026-09-07）
+## 0. 总览（2026-09-17）
 
 | 维度 | 结论 |
 |------|------|
-| 版本线 | **v4.0.18** 子账号继承二维码 + HQ 财务全部银行账户（门店行读结算资质；含 v4.0.15 HQ 概览折线图） |
+| 版本线 | **v4.0.20** 推广码渠道负责人 + 关联合伙人（含 v4.0.18 子账号继承码 / 财务全部银行账户） |
 | 订单佣金 | 区县归属已删除；只认关联 / 代下单选择 |
 | 账单 | 酒订单 / 核销订单分列；合伙人改为周账（周一 08:00）；零元不同步合伙人；酒厂含现场提货，零应付仍出账（无需打款） |
 | 活动图 | HQ 上传底图/码栏/文案；**v4.0.15 上传超限自动压缩并提示尺寸**；合伙人选择写入库；HQ 可指定一张图为勾选主合伙人合成下载；子账号不可看活动图 |
@@ -25,6 +25,7 @@
 | 4.0.14 | [`HQ 概览粒度与环比`](./杜康好客-v4.0.14-开发文档.md) | ✅ 已实现 |
 | 4.0.15 | [`HQ 概览折线图`](./杜康好客-v4.0.15-开发文档.md) | ✅ 已实现 |
 | 4.0.18 | [`子账号继承二维码 + 财务全部银行账户（结算资质）`](./杜康好客-v4.0.18-开发文档.md) | ✅ 已实现 |
+| 4.0.20 | [`推广码渠道负责人 + 关联合伙人`](./杜康好客-v4.0.20-开发文档.md) | ✅ 已实现 |
 
 | 日期 | 说明 |
 |------|------|
@@ -42,4 +43,5 @@
 | 2026-09-08 | v4.0.18 修订：C 端门店地址「省+市+区+详细地址」原样拼接，详细地址已含省市区时不去重 |
 | 2026-09-08 | v4.0.18 追加：HQ 财务全部银行账户（聚合门店结算资质/酒厂/合伙人/物流有效账户；可新增不挂门店账户；筛选与 Excel/PDF 导出） |
 | 2026-09-08 | v4.0.18 再修订：撤销门店多收款账户；打款与财务门店行改读结算资质（结算户名/银行账号/开户银行） |
-| 2026-09-08 | HQ 合伙人详情关联码可下载裸二维码（与「下载活动图」分开）；C 端门店核销次数由系统设置开关控制 |
+| 2026-09-16 | v4.0.20：推广码渠道负责人改为可多选主合伙人（H5 只看扫码/归因/订单数）；关联合伙人扫码 first-lock，不回刷、已关联他人静默跳过 |
+| 2026-09-17 | v4.0.20：PromoModule 改走 CityScope 避免 Nest 循环依赖；本地 Vite 代理默认 `127.0.0.1:3010` |

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

@@ -0,0 +1,98 @@
+# 杜康好客 · v4.0.20 开发文档
+
+> **2026-09-16 / 09-17** · promo / city-scope / store / admin-web / h5-partner / shared-types  
+> **主题**：推广码渠道负责人（多选主合伙人）+ 关联合伙人（扫码 first-lock）
+
+---
+
+## 1. 版本目标
+
+| # | 任务 | 类型 | 交付 |
+|---|------|------|------|
+| 1 | 渠道负责人 | 需求 | HQ 创建/编辑推广码可多选主合伙人；被指定主账号在合伙人 H5 只看扫码人数、归因人数、订单数量 |
+| 2 | 关联合伙人 | 需求 | HQ 可单选绑定主合伙人；登录用户扫该码且尚未关联任何人时 first-lock；已关联他人静默跳过；不回刷历史 |
+
+**不做**：把推广码改成关联码（仍用数字 scene，不复用 `pa_` / `sa_`）；回刷历史归因用户；已关联他人换绑；合伙人 H5 开放用户/订单/核销/手机号明细；历史 `ownerUserId`（C 端用户）迁成合伙人；子账号推广码数据入口。
+
+---
+
+## 2. 规则
+
+规则事实源：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md) §2.1。
+
+```mermaid
+flowchart TD
+  scan[C端扫推广码] --> touch["POST /promo/touch"]
+  touch --> scanInc[scanCount++ 未登录也计]
+  touch --> login{已登录?}
+  login -->|否| done[结束]
+  login -->|是| attr[首次归因 UserPromoAttribution]
+  attr --> src[ORGANIC 才标 PROMO_CODE 来源]
+  src --> hasAssoc{码上有关联合伙人?}
+  hasAssoc -->|否| done
+  hasAssoc -->|是| bound{用户已有 assoc?}
+  bound -->|无| lock["PartnerCityService.tryBindIfUnbound"]
+  bound -->|已是同一人| skipSame[noop]
+  bound -->|已是他人| skipOther[静默跳过]
+  lock --> users[合伙人H5 关联用户可见]
+```
+
+- **渠道负责人**：可空、多选 **ACTIVE 主合伙人**（`isPrimary=1`）。只授权看三项汇总，不绑用户。
+- **关联合伙人**：可空、单选 ACTIVE 主合伙人。登录 touch 后 `tryBindIfUnbound`：无关联则写 `assoc_partner_account_id` + `assoc_bound_at`（不写 `assoc_sub_account_id`、不改 `sourceType`、不增加关联码 `assoc_scan_count`）；已是同一人 noop；已是他人不抛错。只绑以后扫进来的用户。
+- 两字段独立：只配渠道负责人 ≠ 绑用户；只配关联合伙人也会把用户写入该合伙人「关联用户」，并允许看三项汇总。
+- HQ 原 `ownerUserId` 列保留、创建/编辑不再暴露。
+
+---
+
+## 3. API
+
+### 3.1 HQ（promo 模块）
+
+`POST /admin/promo-codes`、`PUT /admin/promo-codes/:id` 增加：
+
+- `channelOwnerPartnerIds: string[]`（可空）
+- `assocPartnerAccountId: string | null`（可空；空串/null 解绑）
+
+列表/详情返回 `channelOwners[]`、`assocPartner`（`id` / `companyName` / `name` / `phone`）。列表筛：`channelOwnerPartnerId`、`assocPartnerAccountId`。
+
+### 3.2 C 端扫码
+
+`POST /promo/touch`：登录后、归因与来源标记之后，若码上有 `assocPartnerAccountId`，调用 `PartnerCityService.tryBindIfUnbound`（**不** import `StoreModule`，避免 Nest 循环依赖）。
+
+### 3.3 合伙人 H5（仅主账号，`PartnerPrimaryGuard`）
+
+| 方法 | 路径 | 返回 |
+|------|------|------|
+| GET | `/partner/promo-codes` | `{ items: [{ id, name, code, status, scanCount, attributionCount, orderCount }] }` |
+
+可见范围：当前主账号是渠道负责人 **或** 关联合伙人。订单数 = `status=COMPLETED`。禁止 HQ 的 users / metrics / timeline / 订单快链。
+
+---
+
+## 4. 变更面
+
+| 层 | 路径 |
+|----|------|
+| Prisma | `CommonPromoCode.assocPartnerAccountId`；`PromoCodeChannelOwner`（`promo_code_channel_owner`） |
+| 迁移 | `server/dukang-api/prisma/migrate-promo-partner-fields.sql`（**Review 后生产执行**） |
+| shared-types | `promo.ts`：`PromoCodePartnerBrief`、`PromoCodeItem.channelOwners/assocPartner`、`PartnerPromoCodeItem` |
+| API promo | `promo-code.service.ts`、`dto/promo-code.dto.ts`、`partner-promo-code.controller.ts`；`PromoModule` import `CityScopeModule` |
+| API city-scope | `PartnerCityService.tryBindIfUnbound` |
+| API store | `PartnerAssocService.tryBindIfUnbound` 转调 city-scope |
+| admin-web | `PromoCodesPage.tsx`、`promo/PromoCodeDetailPage.tsx`：渠道负责人多选 / 关联合伙人单选；去掉关联用户 ID |
+| h5-partner | `CenterPage.tsx` 运营管理「推广码数据」；`/center/promo-codes`；`PromoCodesPage.tsx` |
+| 本地代理 | admin/partner/shop Vite 默认 `VITE_API_TARGET` → `http://127.0.0.1:3010`（Windows 上 `localhost` 可能打到占用 `::3010` 的其他进程） |
+
+---
+
+## 5. 验收
+
+- [ ] HQ 创建/编辑推广码可多选渠道负责人、可清空单选关联合伙人；列表/详情展示公司名；可按两字段筛选
+- [ ] 只配渠道负责人：扫码不写用户关联；该主账号 H5「推广码数据」能看到三项数字，点不开用户/订单/核销
+- [ ] 只配关联合伙人：未关联的登录用户扫码后出现在该合伙人「关联用户」；该主账号也能看三项汇总
+- [ ] 用户已关联他人：扫带关联合伙人的码不换绑、流程不中断、不报「无法更换」
+- [ ] 为已有码补关联合伙人：**不**回刷历史归因用户
+- [ ] 子账号中心无「推广码数据」入口
+- [ ] 关联码 `pa_` / `sa_` 行为不变；已付佣金快照不回刷
+- [ ] 执行迁移后 API 可启动（`PromoModule` 不得再 import `StoreModule`）
+- [ ] shared-types 构建通过；相关 lint 过

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

@@ -103,7 +103,7 @@ HQ 创建商品：名称/价格/权益额/箱规/香型/城市上架；详情模
 
 ## 7. 活动 / 推广码
 
-HQ 推广码：场景/合伙人绑定/上下线；touch 归因；metrics 四指标+事件日志(v3.4.13)。
+HQ 推广码：场景/渠道负责人(主合伙人多选)/关联合伙人/上下线；touch 归因 + 关联合伙人 first-lock；metrics 四指标+事件日志(v3.4.13)。
 
 ## 8. 开城