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

杜康好客 · V4 PRD

v4.0（2026-08-29）· 关联码与分佣事实源；v4.0.6 酒厂对账；v4.0.7 HQ 活动图快链与勾选导出
未改规则仍见 杜康好客-v3-PRD.md。冲突时 V4 > V3（本主题：订单佣金归属、关联码、合伙人账单明细、活动图、酒厂对账）。
实现：v4.0.1 开发文档 · v4.0.2 开发文档 · v4.0.6 开发文档 · v4.0.7 开发文档 · 审计：v4-现状对照

0. 版本

版	日期	要点	开发文档
4.0.1	08-29 / 08-30	合伙人关联码；订单佣金只认关联；账单酒单/核销分列；去掉区县酒单佣金；HQ 关联筛选与快链；合伙人 H5 用户管理与首页统计	v4.0.1
4.0.2	08-30	HQ 活动图模板（底图 + 方形码栏 + 文案）；合伙人下载合成关联码；所选图写入库并作为用户管理主图	v4.0.2
4.0.6	08-31	酒厂 T+3=每 3 天出一期；全部已完成已付订单（含现场提货）；应付为 0 仍出账；核对补生成	v4.0.6
4.0.7	09-01	HQ 城市合伙人活动图快链；指定一张活动图为单个或勾选主合伙人合成下载（PNG / zip）	v4.0.7

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. 活动图

• 一套活动图 = 底图 + 方形码栏（相对坐标）+ 标题 + 推广文案 + 排序 + 上架状态。文案由 HQ 手填，不自动生成。
• 码栏用相对百分比存储，与底图像素无关：qrXPct / qrYPct 为左上角，qrSizePct 为边长（相对图宽，保证正方形）。HQ 上传后在预览图上拖拽定位、拉角改尺寸。
• 合入的码固定为 主合伙人关联码（v4.0.1，getwxacodeunlimit，scene=pa_{partnerId}）。不复用推广码。
• 合伙人 H5（仅主账号）可浏览已上架活动图、一键复制文案、下载合成图。下载时服务端把本人关联码 PNG 贴进码栏后返回整图。
• 列表第一项「无」= 只用关联码。单选立即写入 partner_account.activity_poster_id（空=无）；用户管理主图按该选择展示，下次登录仍有效。下架/删除后回退为关联码。
• 微信内下载失败则预览 + 长按保存（与关联码下载一致）。
• 合伙人只看 ACTIVE；下架后列表不再出现。无关联码则不可下载并明确报错。
• HQ 持权限 activity_posters（默认超管 + 运营）可增删改、上下架。
• HQ 城市合伙人页提供活动图快链（列表列 / 详情 / 顶栏，进入 /activity-posters?partnerId=）。可指定一张已上架活动图：单个下载合成 PNG，或 勾选主合伙人导出 zip（仅已勾选，不做隐式全量）。合入码为已有 OSS 关联码；无码则单张报错、zip 记入跳过清单。不在本路径批量调微信补码，不预生成每人缓存图。

7. 酒厂对账（v4.0.6）

• 口径：T+3 = 每 3 个自然日出具一张账单（对齐起点 2026-08-01，出账日如 8/4、8/7、8/10…）；纳入窗口为上一期 3 天 [出账日−3, 出账日) 内全部 COMPLETED + PAID 订单（含现场提货）；billDate = 出账当天北京日历日；应付 = 实付合计 × 30%。
• 与订单完全比对：上述订单均须进入对应出账日账单明细；漏账可通过 HQ「核对补生成」或每日任务回扫补齐。
• 应付为 0 仍出账：出账日无订单或应付为 0 仍生成账单；业务状态展示「无需打款」（DB 仍为 UNPAID，不可确认打款）。
• 已打款不回刷；未打款账单可重算；明细 orderId 冲突时从其他未打款账单迁入。

8. 不做

改推广码体系；改核销归属；子账号自己的码；回刷已打款账单；区县佣金双轨；AI 出图/出文案；C 端/门店端活动图；预生成每人缓存图。