jacy
cb63d382ad
线上需要按账户、用户和功能控制登录与加载成功率，同时单独停发订单、核销和账单通知。 Co-authored-by: Cursor <cursoragent@cursor.com>
162 lines
16 KiB
Markdown
162 lines
16 KiB
Markdown
# 杜康好客 · 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** 子账号继承码、财务全部银行账户目录；**v4.0.20** 推广码渠道负责人/关联合伙人；**v4.0.21** 接口访问
|
||
> 未改规则仍见 [`杜康好客-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.0.21 开发文档`](./杜康好客-v4.0.21-开发文档.md) · 审计：[`v4-现状对照`](./杜康好客-v4-现状对照.md)
|
||
|
||
## 0. 版本
|
||
|
||
| 版 | 日期 | 要点 | 开发文档 |
|
||
|----|------|------|----------|
|
||
| 4.0.1 | 08-29 / 08-30 | 合伙人关联码；订单佣金只认关联；账单酒单/核销分列；去掉区县酒单佣金；HQ 关联筛选与快链；合伙人 H5 用户管理与首页统计 | [`v4.0.1`](./杜康好客-v4.0.1-开发文档.md) |
|
||
| 4.0.2 | 08-30 | HQ 活动图模板（底图 + 方形码栏 + 文案）；合伙人下载合成关联码；所选图写入库并作为用户管理主图 | [`v4.0.2`](./杜康好客-v4.0.2-开发文档.md) |
|
||
| 4.0.6 | 08-31 | 酒厂 T+3=每 3 天出一期；全部已完成已付订单（含现场提货）；应付为 0 仍出账；核对补生成 | [`v4.0.6`](./杜康好客-v4.0.6-开发文档.md) |
|
||
| 4.0.7 | 09-01 | HQ 城市合伙人活动图快链；指定一张活动图为单个或勾选主合伙人合成下载（PNG / zip） | [`v4.0.7`](./杜康好客-v4.0.7-开发文档.md) |
|
||
| 4.0.9 | 09-02 | 子账号默认启用；关联码已扫码计数；零元账单不同步；主账号自填银行账号；周账周一 08:00 出账；预付款预估；子账号用户管理（无活动图） | [`v4.0.9`](./杜康好客-v4.0.9-开发文档.md) |
|
||
| 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) |
|
||
| 4.0.21 | 09-26 | HQ 接口访问：登录/商品/门店加载/门店提交按成功百分比放行；审核通知按百分比丢弃；订单/核销/账单/门店审核/套餐修改仅作企微通知总开关 | [`v4.0.21`](./杜康好客-v4.0.21-开发文档.md) |
|
||
|
||
## 1. 锚点（沿用 V3，佣金归属改写）
|
||
|
||
| 锚点 | 值 |
|
||
|------|-----|
|
||
| 门店结算 | 核销额 × **60%** |
|
||
| 合伙人佣金池 | 订单 + 核销 ≤ 订单额 **5%**（默认 **0% + 3%**） |
|
||
| 订单佣金归属 | **仅关联用户**（或代下单显式选择的合伙人） |
|
||
| 核销佣金归属 | 门店拓店合伙人（不变） |
|
||
|
||
## 2. 关联码
|
||
|
||
- 每个**主合伙人**自动一张微信小程序码（`getwxacodeunlimit`，scene=`pa_{partnerId}`）。不复用推广码。
|
||
- C 端登录后**首次扫码锁定**；已绑定再扫任意码提示「已关联」，不更新。
|
||
- 用户不可自换绑；HQ 持权限 `users_partner_assoc`（修改用户关联合伙人）可解绑或改绑，解绑后可再绑。已支付订单佣金快照不回刷。
|
||
- 合伙人 H5 可展示并**下载** PNG；微信内下载失败则预览 + 长按保存。HQ 合伙人账号/开城合伙人详情同样可下载**裸二维码**（「下载二维码」），与「下载活动图」合成海报分开。
|
||
- 主合伙人备注写独立表 `partner_user_note`（`partner_account_id` + `user_id` 唯一），与 HQ `user_user.hq_remark` 隔离；换绑后不跟随、不泄漏给下一个合伙人。合伙人 H5 **不返回** `hqRemark`。
|
||
- 主账号首页两张卡：「关联用户」（按 `assocBoundAt` 拆本日/本月）、「关联用户订单」（已付购酒单且用户**当前**关联本合伙人，按 `paidAt` 拆本日/本月）。文案不用「佣金订单」——与账单快照 `partner_account_id_at_pay` 可能不完全重合。子账号不展示。
|
||
- 主账号底部 Tab：首页 / **用户管理** / 门店管理 / 合伙人中心。用户管理页 = 关联码 + 已关联用户列表（搜索昵称/手机/编号/本合伙人备注；排序关联时间/注册时间/订单数）。点订单数看该用户已付购酒单。
|
||
- **子账号**也可进入用户管理：可看关联码、下载二维码、看已关联用户；**不能**看活动图入口与合成主图（只出纯关联码）。
|
||
- **子账号继承二维码**（v4.0.18）：子账号有**自己的**小程序码（`getwxacodeunlimit`，scene=`sa_{subAccountId}`），与主账号 `pa_{partnerId}` 前缀、id 均不同，不冲突。扫码**仍锁定主账号**（佣金归主账号，first-lock 校验主账号），额外写入 `user_user.assoc_sub_account_id` 记录子账号归属，形成**新增一级子账号维度统计**。子账号在用户管理/关联码页展示并下载**自己的**码、看**自己维度**的已扫码/已关联/订单；主账号已扫码在读取时聚合 own+children，主账号行为不变。
|
||
- 用户管理页二维码下方展示「已扫码」与「已关联」人数；为 0 的段不显示。已扫码 = C 端带 `pa_` scene 进入时累加（未登录也计），与已关联人数独立。
|
||
- 主账号新建子账号默认 **ACTIVE**（可立即登录），列表中可再禁用。
|
||
- 主账号可在合伙人中心填写收款账户：收款人、银行账号、开户行名称（写入主账号 `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`。
|
||
|
||
| 场景 | 写入 |
|
||
|------|------|
|
||
| C 端自助下单 | 用户已关联 → 关联合伙人 + 其订单费率；未关联 → 皆空 |
|
||
| 代下单选了合伙人 | 本单快照归该合伙人；用户尚未关联则 first-lock；已关联他人不换绑 |
|
||
| 代下单未选合伙人 | 本单不写佣金快照、不改用户关联 |
|
||
|
||
**删除**：按收货区县解析城市合伙人并写入订单佣金；代下单操作人回落填佣金快照。
|
||
|
||
管辖类型 / 区县仅作开城标识，不再参与订单佣金。
|
||
|
||
已支付订单不回刷。重算「待审核」账单只认快照字段（上线后仅关联/代下单选择会写入）。
|
||
|
||
## 4. 核销佣金
|
||
|
||
不变：核销发生在合伙人名下门店时，出账按该主合伙人当时核销费率 × 核销额。
|
||
|
||
## 5. 合伙人账单
|
||
|
||
**周账**：每周一北京时间 **08:00** 出具上一完整自然周（周一 00:00 ～ 周日 23:59:59.999）账单。表头：`orderCommission` + `redeemCommission` = `totalAmount`。
|
||
|
||
明细两段：
|
||
|
||
| 段 | 来源 | 佣金 |
|
||
|----|------|------|
|
||
| 酒订单 | 账期内已付且 `partner_account_id_at_pay` = 本主合伙人 | 实付 × 支付快照费率 |
|
||
| 核销订单 | 账期内名下门店核销 | 核销额 × 出账时核销费率 |
|
||
|
||
HQ 财务详情与合伙人确认页均展示两段列表。不再「无快照则全城已付单 × 当前费率」。
|
||
|
||
- **零元账单**：佣金合计为 0 时 HQ 仍可生成并留在待审核，**不得发送**给合伙人；合伙人端列表/详情不可见。
|
||
- 合伙人 H5 展示当前账期（本周一～本周日）与下次出账时间（下周一 08:00，若尚未过本周一 08:00 则为当日 08:00）。
|
||
- **预付款**：当前未出账周期（本周一 00:00 至今）酒单 + 核销按佣金比例算出的预估合计。展示在首页与合伙人中心。与实际打款无关，实际以账单为准。
|
||
- 上线前已生成的月账保留，不回刷。
|
||
|
||
## 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. 门店打款账户（v4.0.18）
|
||
|
||
- 打款/核销结算/提现/账单导出读取门店详情「结算资质」：结算户名、银行账号、开户银行（主账号 `StoreAccount.bank_account_*`）。
|
||
- **不**再维护独立「收款账户」列表或 `store_bank_account`；一门店一行。
|
||
- 改结算资质后无需重启，下次打款即时生效。
|
||
|
||
## 9. 财务全部银行账户（v4.0.18）
|
||
|
||
HQ「财务 → 全部银行账户」聚合**有效**银行账户，供财务查阅、筛选、导出；**不替代**各业务源的维护入口，也不作为打款主数据。
|
||
|
||
| 类型 | 来源 | 有效 | 本页可写 |
|
||
|------|------|------|----------|
|
||
| 门店 | 门店详情结算资质（主账号 `bank_account_*`） | 户名+账号非空；一店一行 | 仅备注 |
|
||
| 酒厂 | `WINERY_BANK_*` | 户名+账号已填 | 仅备注 |
|
||
| 合伙人 | 主账号 `bank_account_*` | ACTIVE 且户名+账号非空 | 仅备注 |
|
||
| 物流 | 承运商 `common_fulfillment_provider` | ACTIVE 且户名+账号非空 | 仅备注 |
|
||
| 其他 | `finance_bank_account` | ACTIVE | 增删改（不挂门店，不进入打款） |
|
||
|
||
- 列表字段：类型、归属（快链到源页面）、城市、结算户名、银行账号、开户银行、备注。
|
||
- 筛选：类型、城市、关键字（户名/账号/开户银行/归属/备注）。可导出 Excel 与 PDF。
|
||
- 「其他」账户仅登记备查，不进入门店提现、账单打款、酒厂/物流对账。
|
||
- 权限：`finance`。
|
||
|
||
## 10. 接口访问（v4.0.21）
|
||
|
||
HQ「接口访问」（权限 `api_access`，危险权限，超管可用，其他角色需单独勾选）。表 `api_access_policy`。默认成功百分比 **100**、通知开关开，与未配置时一致。
|
||
|
||
成功百分比是放行比例，每次请求独立随机：`0` 全拒，`100` 全放行。命中顺序：用户+功能 → 账户+功能 → 该用户全部功能 → 该账户全部功能 → 功能全局 → 放行。
|
||
|
||
- **用户**：C 端 `User`。**账户**：总部 `HqAccount`、门店 `StoreAccount`、合伙人 `PartnerAccount`。
|
||
- **登录**：C 端 / 门店 / 合伙人登录。未登录时若 body 有手机号，先匹配该手机号的用户或账户规则。**总部登录不参与**，避免百分比打成 0 后无法改回。配置接口本身不参与。
|
||
- **商品加载**：`GET /catalog/products`、`GET /catalog/products/:id`。**门店加载**：`GET /stores`、`GET /stores/:id`。不含总部后台读接口。
|
||
- **门店提交**：`POST /partner/stores` 新建入驻。
|
||
- **审核通知**：不拦截审核写入；发送 `store.audit_pending` 时按百分比丢弃。
|
||
- 被拒绝的 HTTP 返回 `{ code, message, reason }`，文案为网络加载失败 / 请求异常 / 非法访问 / 微信服务异常（规则可选，默认请求异常）。**不发企微告警**。各端展示 `message`，不改页面。
|
||
|
||
通知总开关只决定还发不发企微，不拦下单、核销、出账、审核、改套餐。关掉后即使「消息推送」勾了条件也不发；打开后仍走原条件。运营日报/周报/月报不在此列（仍在「企微机器人 → 报告」）。
|
||
|
||
| 开关 | 事件 |
|
||
|------|------|
|
||
| 订单推送 | `order.paid` |
|
||
| 核销推送 | `redeem.success` |
|
||
| 酒厂 / 城市合伙人 / 门店账单 | `finance.winery_bill` / `finance.partner_bill` / `finance.store_bill` |
|
||
| 门店审核 | `store.audit_pending`（与审核通知百分比叠加：关则不发，开则只成功该百分比） |
|
||
| 套餐修改 | `store.package_audit_pending` |
|
||
|
||
## 11. 不做
|
||
|
||
不把推广码改成关联码、不回刷历史绑定；改核销归属；回刷已打款账单；区县佣金双轨；AI 出图/出文案；C 端/门店端活动图；预生成每人缓存图。
|