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

杜康好客 · v4.0.1 开发文档

2026-08-29 / 08-30 · iam / store / trade / settlement / ops / mini-user / h5-partner / admin-web
主题：合伙人关联码；订单佣金只认关联；财务账单酒单/核销分列；去掉区县酒单佣金；修复 HQ 改订单佣金报错；HQ 用户/订单/开城关联筛选与快链

需求事实源：杜康好客-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；合伙人 API 去掉 hqRemark
• SQL：migrate-partner-assoc-v401.sql · migrate-partner-user-note-v401.sql

---

4. 验收

• 新主合伙人有码；扫码未登录→登录后绑定；二次扫码不换绑
• 未关联用户支付：partnerAccountIdAtPay 空
• 已关联 / 代下单选了合伙人：快照正确
• HQ 只改订单佣金可保存
• 账单酒单 / 核销分列，合计与表头一致
• 合伙人 H5 可下载 PNG（微信内可预览长按保存）
• HQ 用户列表可按搜索/关联合伙人查询；筛选默认展开
• HQ 订单列表可按本单关联合伙人查询
• 开城城市合伙人可点关联用户数进入用户列表，并可查全部已关联用户
• HQ 持 users_partner_assoc 可在用户详情改绑/解绑
• 合伙人 H5 主账号首页两张统计卡可点进用户管理 / 关联用户订单；用户管理可搜排、改备注；子账号无该 Tab / 卡
• 合伙人备注只写 partner_user_note，换绑后下一合伙人看不到；H5 列表不出现 hqRemark