feat(assoc): v4.0.1 合伙人关联码、分佣账单与 H5 用户管理

订单佣金只认关联用户；合伙人备注写入独立表；H5 增加用户管理与首页统计。

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

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

@@ -1,6 +1,7 @@
 # 杜康好客 · V3.0 PRD
 
-> **v3.0**（2026-07-10）· 产品事实源 · 冲突时 **V3 > V2**  
+> **v3.0**（2026-07-10）· 3.x 产品事实源 · 冲突时 **V3 > V2**  
+> **4.0 起**（关联码 / 订单佣金归属 / 合伙人账单明细）见 [`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)，冲突时 **V4 > V3**。  
 > 实现：[`v3编码手册`](./杜康好客-v3编码手册.md) · 审计：[`v3-现状对照`](./杜康好客-v3-现状对照.md)
 
 ## 0. 说明
@@ -34,6 +35,8 @@
 | 3.5.12 | 08-26 | 发布会订单大屏循环 BGM；HQ 日志/订单状态流转/用户行为时间线展示中文；修复删除门店分类被默认树回种；HQ 侧栏顺序（业务前 11 项，系统设置置底） | [`v3.5.12`](./杜康好客-v3.5.12-开发文档.md) |
 | 3.5.14 | 08-26 | 修复 C 端提交订单/支付成功日志误标 H5；线上 `order_submit`/`pay_success` 回填为小程序 | [`v3.5.14`](./杜康好客-v3.5.14-开发文档.md) |
 
+**4.0 起**不再写入本表，见 [`v4-PRD`](./杜康好客-v4-PRD.md)。
+
 ---
 
 ## 1. 背景与目标

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

@@ -1,6 +1,7 @@
 # 杜康好客 · V3 编码手册（交付业务版）
 
 > **事实源**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · **审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)  
+> **佣金归属 / 关联码 / 合伙人账单明细（v4.0.1）**：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)，冲突时 **V4 > V3**。  
 > V2/preV1 **非需求依据**。总部交付 = **`apps/admin-web`**（非 H5）。
 
 ## 1. 交付目标（六条）
@@ -53,6 +54,8 @@ C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAd
 
 **用户日志端（v3.5.14）**：`order_submit` / `pay_success` 的 `clientApp` 取 JWT（小程序 `USER_MINI`）；微信支付回调沿用该订单已有埋点，缺省小程序。禁止再写死 `USER_H5`。
 
+**合伙人关联与订单佣金（v4.0.1）**：规则见 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` · `GET /partner/assoc` · `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))`。
+
 ## 5. 验收用例（必过）
 
 **主链路 15 项**：登录、4 SKU、起购、支付+权益、双通道核销、payout、关店不可见、拓店审核、配送完成、退款、T+1/T+30…  

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

@@ -0,0 +1,68 @@
+# 杜康好客 · V4 PRD
+
+> **v4.0**（2026-08-29）· 关联码与分佣事实源  
+> 未改规则仍见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。**冲突时 V4 > V3**（仅本主题：订单佣金归属、关联码、合伙人账单明细）。  
+> 实现：[`v4.0.1 开发文档`](./杜康好客-v4.0.1-开发文档.md) · 审计：[`v4-现状对照`](./杜康好客-v4-现状对照.md)
+
+## 0. 版本
+
+| 版 | 日期 | 要点 | 开发文档 |
+|----|------|------|----------|
+| 4.0.1 | 08-29 / 08-30 | 合伙人关联码；订单佣金只认关联；账单酒单/核销分列；去掉区县酒单佣金；HQ 关联筛选与快链；合伙人 H5 用户管理与首页统计 | [`v4.0.1`](./杜康好客-v4.0.1-开发文档.md) |
+
+## 1. 锚点（沿用 V3，佣金归属改写）
+
+| 锚点 | 值 |
+|------|-----|
+| 门店结算 | 核销额 × **60%** |
+| 合伙人佣金池 | 订单 + 核销 ≤ 订单额 **5%**（默认 **0% + 3%**） |
+| 订单佣金归属 | **仅关联用户**（或代下单显式选择的合伙人） |
+| 核销佣金归属 | 门店拓店合伙人（不变） |
+
+## 2. 关联码
+
+- 每个**主合伙人**自动一张微信小程序码（`getwxacodeunlimit`，scene=`pa_{partnerId}`）。不复用推广码。
+- C 端登录后**首次扫码锁定**；已绑定再扫任意码提示「已关联」，不更新。
+- 用户不可自换绑；HQ 持权限 `users_partner_assoc`（修改用户关联合伙人）可解绑或改绑，解绑后可再绑。已支付订单佣金快照不回刷。
+- 合伙人 H5 可展示并**下载** PNG；微信内下载失败则预览 + 长按保存。
+- 主合伙人备注写独立表 `partner_user_note`（`partner_account_id` + `user_id` 唯一），与 HQ `user_user.hq_remark` 隔离；换绑后不跟随、不泄漏给下一个合伙人。合伙人 H5 **不返回** `hqRemark`。
+- 主账号首页两张卡：「关联用户」（按 `assocBoundAt` 拆本日/本月）、「关联用户订单」（已付购酒单且用户**当前**关联本合伙人，按 `paidAt` 拆本日/本月）。文案不用「佣金订单」——与账单快照 `partner_account_id_at_pay` 可能不完全重合。子账号不展示。
+- 主账号底部 Tab：首页 / **用户管理** / 门店管理 / 合伙人中心。用户管理页 = 关联码 + 已关联用户列表（搜索昵称/手机/编号/本合伙人备注；排序关联时间/注册时间/订单数）。点订单数看该用户已付购酒单。子账号无此 Tab。
+- HQ：用户列表综合搜索 + 关联合伙人筛选（`none` 未关联 / `any` 已关联全部 / 指定主合伙人），筛选默认展开；订单列表按本单佣金快照筛关联合伙人；开城城市合伙人提供「关联用户」快链与「全部关联用户」快链，进入用户列表并带上筛选。
+
+## 3. 订单佣金
+
+支付快照字段：`user_order.partner_account_id_at_pay`、`order_commission_rate_at_pay`。
+
+| 场景 | 写入 |
+|------|------|
+| C 端自助下单 | 用户已关联 → 关联合伙人 + 其订单费率；未关联 → 皆空 |
+| 代下单选了合伙人 | 本单快照归该合伙人；用户尚未关联则 first-lock；已关联他人不换绑 |
+| 代下单未选合伙人 | 本单不写佣金快照、不改用户关联 |
+
+**删除**：按收货区县解析城市合伙人并写入订单佣金；代下单操作人回落填佣金快照。
+
+管辖类型 / 区县仅作开城标识，不再参与订单佣金。
+
+已支付订单不回刷。重算「待审核」账单只认快照字段（上线后仅关联/代下单选择会写入）。
+
+## 4. 核销佣金
+
+不变：核销发生在合伙人名下门店时，出账按该主合伙人当时核销费率 × 核销额。
+
+## 5. 合伙人账单
+
+月账（T+30）表头：`orderCommission` + `redeemCommission` = `totalAmount`。
+
+明细两段：
+
+| 段 | 来源 | 佣金 |
+|----|------|------|
+| 酒订单 | 账期内已付且 `partner_account_id_at_pay` = 本主合伙人 | 实付 × 支付快照费率 |
+| 核销订单 | 账期内名下门店核销 | 核销额 × 出账时核销费率 |
+
+HQ 财务详情与合伙人确认页均展示两段列表。不再「无快照则全城已付单 × 当前费率」。
+
+## 6. 不做
+
+改推广码体系；改核销归属；子账号自己的码；回刷已打款账单；区县佣金双轨。

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

@@ -0,0 +1,24 @@
+# 杜康好客 · V4 现状对照
+
+> 基准：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)  
+> V3 进度仍见 [`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)，不混表。
+
+## 0. 总览（2026-08-29）
+
+| 维度 | 结论 |
+|------|------|
+| 版本线 | **v4.0.1** 关联码 + 分佣账单 |
+| 订单佣金 | 区县归属已删除；只认关联 / 代下单选择 |
+| 账单 | 酒订单 / 核销订单分列 |
+
+## 1. 版本交付
+
+| 版本 | 文档 | 状态 |
+|------|------|------|
+| 4.0.1 | [`关联码与分佣账单`](./杜康好客-v4.0.1-开发文档.md) | ✅ 已实现 |
+
+| 日期 | 说明 |
+|------|------|
+| 2026-08-29 | v4.0.1：合伙人关联码、订单佣金只认关联、账单两段明细、去掉区县酒单佣金、HQ 改费率修复 |
+| 2026-08-30 | HQ 订单/用户详情展示关联合伙人；改绑权限 `users_partner_assoc`；用户/订单筛选关联合伙人；开城关联用户快链 |
+| 2026-08-30 | 合伙人 H5：首页关联用户/关联用户订单统计；用户管理 Tab（关联码+列表+备注）；`partner_user_note` 与 HQ `hqRemark` 隔离 |

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

@@ -0,0 +1,62 @@
+# 杜康好客 · v4.0.1 开发文档
+
+> **2026-08-29 / 08-30** · iam / store / trade / settlement / ops / mini-user / h5-partner / admin-web  
+> **主题**：合伙人关联码；订单佣金只认关联；财务账单酒单/核销分列；去掉区县酒单佣金；修复 HQ 改订单佣金报错；HQ 用户/订单/开城关联筛选与快链
+
+需求事实源：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)
+
+---
+
+## 1. 版本目标
+
+| # | 任务 | 类型 | 交付 |
+|---|------|------|------|
+| 1 | 关联码 | 需求 | 主合伙人自动小程序码；C 端首次扫码锁定；HQ 持 `users_partner_assoc` 可解绑/改绑 |
+| 2 | 订单佣金 | 需求 | 只认关联 / 代下单显式选择；删除区县解析 |
+| 3 | 代下单 | 需求 | HQ / 合伙人可选关联合伙人，可不选 |
+| 4 | 账单 | 需求 | 酒订单 + 核销订单明细，分别汇总 |
+| 5 | 合伙人 H5 | 需求 | 码/下载、用户管理 Tab（码+列表+备注）、首页关联统计、订单佣金列表、账单两段 |
+| 6 | HQ 改费率 | 修复 | Decimal 写入 + 改费率不跑区县绑定校验 |
+| 7 | HQ 关联运营 | 需求 | 用户/订单详情展示关联合伙人；改绑权限 `users_partner_assoc`；用户列表搜索+关联合伙人筛选（默认展开）；订单列表按本单快照筛关联合伙人；开城合伙人关联用户快链 |
+
+**不做**：改推广码；改核销归属；子账号码；回刷已打款账单。
+
+---
+
+## 2. 规则
+
+见 v4-PRD §2–§5。费率默认仍 **0% + 3%**，合计 ≤ 城市上限 5%。
+
+---
+
+## 3. 变更面
+
+- Domain：删除 `resolveOrderCityPartner`
+- Trade：支付快照只读用户关联或代下单 `assocPartnerAccountId`
+- Settlement：`PartnerBillItem`；去掉全城回落
+- Store / IAM：补码、绑定、解绑
+- mini-user：scene `pa_*` 绑定
+- h5-partner / admin-web：码、列表、代下单可选合伙人、账单两 Tab
+- HQ 用户列表：`keyword`、`assocPartnerAccountId`（`none` / `any` / 主账号 ID）；筛选默认展开；去掉 deviceKey / 过滤测试账号
+- HQ 订单列表：`assocPartnerAccountId` 筛 `partner_account_id_at_pay`（`none`=无快照）
+- HQ 开城城市合伙人：列表/详情「关联用户」快链 → `/users?assocPartnerAccountId=`；顶栏「全部关联用户」→ `=any`；关联码用户列表展示「昵称（备注）」并快链 `/users?userId=`
+- 合伙人 H5 主账号：首页「关联用户 / 关联用户订单」卡（`GET /partner/assoc/stats`）；底部「用户管理」Tab（`/users`，原 `/center/assoc*` 跳转）；列表 `GET /partner/assoc/users?keyword&sort`；用户已付单 `GET /partner/assoc/users/:id/orders`；备注 `PUT /partner/assoc/users/:id/remark`（空串删除）
+- 合伙人备注表 [`partner_user_note`](../server/dukang-api/prisma/schema.prisma)；合伙人 API 去掉 `hqRemark`
+- SQL：[`migrate-partner-assoc-v401.sql`](../server/dukang-api/prisma/migrate-partner-assoc-v401.sql) · [`migrate-partner-user-note-v401.sql`](../server/dukang-api/prisma/migrate-partner-user-note-v401.sql)
+
+---
+
+## 4. 验收
+
+- 新主合伙人有码；扫码未登录→登录后绑定；二次扫码不换绑
+- 未关联用户支付：`partnerAccountIdAtPay` 空
+- 已关联 / 代下单选了合伙人：快照正确
+- HQ 只改订单佣金可保存
+- 账单酒单 / 核销分列，合计与表头一致
+- 合伙人 H5 可下载 PNG（微信内可预览长按保存）
+- HQ 用户列表可按搜索/关联合伙人查询；筛选默认展开
+- HQ 订单列表可按本单关联合伙人查询
+- 开城城市合伙人可点关联用户数进入用户列表，并可查全部已关联用户
+- HQ 持 `users_partner_assoc` 可在用户详情改绑/解绑
+- 合伙人 H5 主账号首页两张统计卡可点进用户管理 / 关联用户订单；用户管理可搜排、改备注；子账号无该 Tab / 卡
+- 合伙人备注只写 `partner_user_note`，换绑后下一合伙人看不到；H5 列表不出现 `hqRemark`