# 杜康好客 · 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`