jacy/dukang
1
0
Fork 0
Code Issues Pull Requests Actions 23 Packages Projects Releases Wiki Activity

V4.0.9版本更新合伙人H5端调整

Browse Source
This commit is contained in:
jacy
2026-09-02 09:46:41 +08:00
parent af3c4b6f08
commit c905b3f930
33 changed files with 893 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/杜康好客-v3编码手册.md
+6 -4
View File
@@ -1,7 +1,7 @@
# 杜康好客 · V3 编码手册（交付业务版）
> **事实源**：[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · **审计**：[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)
> **佣金归属 / 关联码 / 合伙人账单明细（v4.0.1）· 活动图（v4.0.2）**：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)，冲突时 **V4 > V3**。
> **佣金归属 / 关联码 / 合伙人账单明细（v4.0.1）· 活动图（v4.0.2）· 周结算与预付款（v4.0.9）**：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)，冲突时 **V4 > V3**。
> V2/preV1 **非需求依据**。总部交付 = **`apps/admin-web`**（非 H5）。
## 1. 交付目标（六条）
@@ -56,16 +56,18 @@ C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAd
**HQ 门店账单打款凭证**：确认打款 / 提现通过可填 `paymentRef`，并可上传照片（`paymentProofUrls`，OSS `PAYMENT_PROOF`，最多 9 张）。详情与 T+1 导出展示。
**活动图（v4.0.2 / v4.0.7）**：规则见 v4-PRD §6。表 `activity_poster`；HQ `GET/POST/PUT/DELETE /admin/activity-posters`（权限 `activity_posters`）；合伙人 `GET /partner/activity-posters` · `GET/PUT /partner/activity-posters/selection`（写入 `partner_account.activity_poster_id`）· `GET /partner/activity-posters/:id/image`（合成本人关联码）。`GET /partner/assoc` 返回 `activityPosterId`。码栏百分比相对图宽。子账号无入口。v4.0.7：HQ `GET /admin/activity-posters/:id/image?partnerId=` 单张合成 PNG；`POST /admin/activity-posters/:id/partner-pack` `{ partnerIds }` 流式 zip（仅勾选，测试号/无码 skip）。城市合伙人快链 `/activity-posters?partnerId=`。不预生成缓存图、不批量调微信补码。
**活动图（v4.0.2 / v4.0.7）**：规则见 v4-PRD §6。表 `activity_poster`；HQ `GET/POST/PUT/DELETE /admin/activity-posters`（权限 `activity_posters`）；合伙人 `GET /partner/activity-posters` · `GET/PUT /partner/activity-posters/selection`（写入 `partner_account.activity_poster_id`）· `GET /partner/activity-posters/:id/image`（合成本人关联码）。`GET /partner/assoc` 返回 `activityPosterId`（**子账号强制为空**）。码栏百分比相对图宽。子账号可进用户管理、下载纯关联码，无活动图入口。v4.0.7：HQ `GET /admin/activity-posters/:id/image?partnerId=` 单张合成 PNG；`POST /admin/activity-posters/:id/partner-pack` `{ partnerIds }` 流式 zip（仅勾选，测试号/无码 skip）。城市合伙人快链 `/activity-posters?partnerId=`。不预生成缓存图、不批量调微信补码。
**合伙人关联与订单佣金（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))`。
**合伙人关联与订单佣金（v4.0.1 / v4.0.9）**：规则见 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` · `POST /user/partner-assoc/touch`（未登录可计已扫码）· `GET /partner/assoc`（`scanCount` + `userCount`；子账号无 `activityPosterId`）· `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))`。子账号创建默认 `ACTIVE`。主账号 `PUT /partner/me/bank` 填收款账户。
**合伙人周结算（v4.0.9）**：每周一 08:00 生成上一自然周账单。`GET /partner/settlement/cycle` 账期与出账日；`GET /partner/settlement/preview` 本周一至今预付款预估。零元账单 HQ 可见待审核、不可发送、合伙人端不可见。历史月账不回刷。
## 5. 验收用例（必过）
**主链路 15 项**：登录、4 SKU、起购、支付+权益、双通道核销、payout、关店不可见、拓店审核、配送完成、退款、T+1/T+30…
**后台 8 项**：商品/门店/订单/权益/核销/工单/日志/财务。
**开发计划任务**：状态 `TODO` 待开发 / `IN_PROGRESS` 开发中 / `DEVELOPED` 已开发 / `RELEASED` 已上线 / `STOPPED` 已停止；版本状态含 `STOPPED` 已停止，关联任务随版本同步（仅当全部关联版本已停止时任务才为已停止）。任务列表「来源工单」链到 `/tickets/support?id=`。
**财务账单日**：出账当天北京日历日（门店/酒厂 `billDate`；合伙人/物流账期按北京自然月）。禁止 `toISOString().slice(0,10)` 或服务器本地 `Date` 午夜当账单日。酒厂应付为 0 仍出账（展示无需打款）。
**财务账单日**：出账当天北京日历日（门店/酒厂 `billDate`；物流账期按北京自然月；合伙人周账按北京自然周，周一 08:00 出上周）。禁止 `toISOString().slice(0,10)` 或服务器本地 `Date` 午夜当账单日。酒厂应付为 0 仍出账（展示无需打款）。合伙人零元账单不同步给合伙人端。
## 6. 技术债（摘要）
docs/杜康好客-v4-PRD.md
+16 -6
View File
@@ -1,8 +1,8 @@
# 杜康好客 · V4 PRD
> **v4.0**（2026-08-29）· 关联码与分佣事实源；**v4.0.6** 酒厂对账；**v4.0.7** HQ 活动图快链与勾选导出
> 未改规则仍见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。**冲突时 V4 > V3**（本主题：订单佣金归属、关联码、合伙人账单明细、活动图、酒厂对账）。
> 实现：[`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-现状对照`](./杜康好客-v4-现状对照.md)
> **v4.0**（2026-08-29）· 关联码与分佣事实源；**v4.0.6** 酒厂对账；**v4.0.7** HQ 活动图快链与勾选导出；**v4.0.9** 合伙人 H5 周结算与用户管理
> 未改规则仍见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。**冲突时 V4 > V3**（本主题：订单佣金归属、关联码、合伙人账单明细、活动图、酒厂对账、合伙人周结算）。
> 实现：[`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-现状对照`](./杜康好客-v4-现状对照.md)
## 0. 版本
@@ -12,6 +12,7 @@
| 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) |
## 1. 锚点（沿用 V3，佣金归属改写）
@@ -30,7 +31,11 @@
- 合伙人 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。
- 主账号底部 Tab：首页 / **用户管理** / 门店管理 / 合伙人中心。用户管理页 = 关联码 + 已关联用户列表（搜索昵称/手机/编号/本合伙人备注；排序关联时间/注册时间/订单数）。点订单数看该用户已付购酒单。
- **子账号**也可进入用户管理：可看关联码、下载二维码、看已关联用户；**不能**看活动图入口与合成主图（只出纯关联码）。
- 用户管理页二维码下方展示「已扫码」与「已关联」人数；为 0 的段不显示。已扫码 = C 端带 `pa_` scene 进入时累加（未登录也计），与已关联人数独立。
- 主账号新建子账号默认 **ACTIVE**（可立即登录），列表中可再禁用。
- 主账号可在合伙人中心填写收款账户：收款人、银行账号、开户行名称（写入主账号 `bank_account_*`）。
- HQ：用户列表综合搜索 + 关联合伙人筛选（`none` 未关联 / `any` 已关联全部 / 指定主合伙人），筛选默认展开；订单列表按本单佣金快照筛关联合伙人；开城城市合伙人提供「关联用户」快链与「全部关联用户」快链，进入用户列表并带上筛选。
## 3. 订单佣金
@@ -55,7 +60,7 @@
## 5. 合伙人账单
月账（T+30）表头：`orderCommission` + `redeemCommission` = `totalAmount`。
**周账**：每周一北京时间 **08:00** 出具上一完整自然周（周一 00:00 ～ 周日 23:59:59.999）账单。表头：`orderCommission` + `redeemCommission` = `totalAmount`。
明细两段：
@@ -66,12 +71,17 @@
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 贴进码栏后返回整图。
- 合伙人 H5（**仅主账号**）可浏览已上架活动图、一键复制文案、下载合成图。下载时服务端把本人关联码 PNG 贴进码栏后返回整图。子账号用户管理页只用纯关联码，不可进活动图。
- 列表第一项「无」= 只用关联码。单选立即写入 `partner_account.activity_poster_id`（空=无）；用户管理主图按该选择展示，下次登录仍有效。下架/删除后回退为关联码。
- 微信内下载失败则预览 + 长按保存（与关联码下载一致）。
- 合伙人只看 `ACTIVE`；下架后列表不再出现。无关联码则不可下载并明确报错。
docs/杜康好客-v4-现状对照.md
+6 -4
View File
@@ -3,14 +3,14 @@
> 基准：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md)
> V3 进度仍见 [`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)，不混表。
## 0. 总览（2026-09-01）
## 0. 总览（2026-09-02）
| 维度 | 结论 |
|------|------|
| 版本线 | **v4.0.7** HQ 活动图快链与勾选导出 |
| 版本线 | **v4.0.9** 合伙人 H5 周结算、预付款、子账号用户管理 |
| 订单佣金 | 区县归属已删除；只认关联 / 代下单选择 |
| 账单 | 酒订单 / 核销订单分列；酒厂含现场提货，零应付仍出账（无需打款） |
| 活动图 | HQ 上传底图/码栏/文案；合伙人选择写入库；HQ 可指定一张图为勾选主合伙人合成下载 |
| 账单 | 酒订单 / 核销订单分列；合伙人改为周账（周一 08:00）；零元不同步合伙人；酒厂含现场提货，零应付仍出账（无需打款） |
| 活动图 | HQ 上传底图/码栏/文案；合伙人选择写入库；HQ 可指定一张图为勾选主合伙人合成下载；子账号不可看活动图 |
## 1. 版本交付
@@ -20,6 +20,7 @@
| 4.0.2 | [`活动图模板与关联码合成`](./杜康好客-v4.0.2-开发文档.md) | ✅ 已实现 |
| 4.0.6 | [`酒厂对账核对`](./杜康好客-v4.0.6-开发文档.md) | ✅ 已实现 |
| 4.0.7 | [`活动图快链与勾选导出`](./杜康好客-v4.0.7-开发文档.md) | ✅ 已实现 |
| 4.0.9 | [`合伙人 H5 周结算与用户管理`](./杜康好客-v4.0.9-开发文档.md) | ✅ 已实现 |
| 日期 | 说明 |
|------|------|
@@ -29,3 +30,4 @@
| 2026-08-30 | v4.0.2：HQ 活动图（底图 + 拖拽码栏 + 文案）；合伙人复制文案、下载合成关联码；选择写入库，用户管理主图下次登录仍显示 |
| 2026-08-31 | v4.0.6：酒厂 T+3=每 3 天出一期（非每日）；含现场提货；零应付仍出账；核对补生成 |
| 2026-09-01 | v4.0.7：HQ 城市合伙人活动图快链；单张/勾选导出合成图（PNG / zip） |
| 2026-09-02 | v4.0.9：子账号默认启用；关联码已扫码；零元账单不同步；银行账号自填；周账周一 08:00；预付款预估；子账号用户管理无活动图 |
docs/杜康好客-v4.0.9-开发文档.md
+70
View File
@@ -0,0 +1,70 @@
# 杜康好客 · v4.0.9 开发文档
> **2026-09-02** · iam / store / settlement / h5-partner / mini-user / admin-web
> **主题**：合伙人 H5 子账号默认启用、关联码已扫码、零元账单过滤、银行账号自填、周结算、预付款预估、子账号用户管理（无活动图）
需求事实源：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md) §2 / §5 / §6
---
## 1. 版本目标
| # | 任务 | 类型 | 交付 |
|---|------|------|------|
| 1 | 子账号默认开启 | 需求 | 创建后 `ACTIVE`，可立即登录 |
| 2 | 已扫码数量 | 需求 | 关联码下展示已扫码 / 已关联；0 不显示 |
| 3 | 零元账单 | 需求 | HQ 可生成待审核；不可发送；合伙人端不可见 |
| 4 | 银行账号 | 需求 | 主账号合伙人中心填写收款人 / 账号 / 开户行 |
| 5 | 周结算 | 需求 | 周一 08:00 出上周账；H5 展示账期与出账日 |
| 6 | 预付款 | 需求 | 本周一至今酒单+核销×费率；首页与中心展示 |
| 7 | 子账号用户管理 | 需求 | 可看用户管理、下载二维码；不可看活动图 |
**不做**：子账号自己的码；回刷历史月账；预付款计入待结算；零元账单删除。
---
## 2. 规则
- 已扫码：C 端带 `pa_{partnerId}` 进入即 +1（未登录也计）；同一进入会话只计一次。已关联仍为 first-lock 用户数。
- 周账窗口：北京自然周 `[周一 00:00, 下周一 00:00)`。出账 cron：`0 8 * * 1` Asia/Shanghai，生成**上一完整周**。
- 预付款窗口：本周一 00:00 ～ now。酒单用支付快照费率；核销用主账号当前核销费率。文案标明预估、以账单为准。
- 零元：`totalAmount <= 0` 保持 `PENDING_REVIEW`，`send` 拒绝；合伙人 `list/get` 过滤。
- 子账号 `GET /partner/assoc` 强制 `activityPosterId = null`。活动图 API 仍仅主账号。
---
## 3. 变更面
- Prisma：`partner_account.assoc_scan_count`
- C 端：`POST /user/partner-assoc/touch`；mini-user 捕获 `pa_` 时调用
- 结算：周生成 / cycle / preview；零元 send 拦截
- 主账号：`PUT /partner/me/bank`；`GET /partner/me` 返回银行字段
- 合伙人 H5：用户管理统计、首页/中心预付款与账期、收款账户页、子账号 Tab
- HQ：合伙人账单生成/筛选改为周
---
## 4. API
| Method | Path | 说明 |
|--------|------|------|
| POST | `/user/partner-assoc/touch` | `{ scene, countScan? }` 未登录可调 |
| GET | `/partner/assoc` | + `scanCount`；子账号无 `activityPosterId` |
| GET | `/partner/settlement/cycle` | 本周账期 + 下次出账时间 |
| GET | `/partner/settlement/preview` | 预付款预估 + 账期 |
| GET | `/partner/settlement/bills` | 过滤 `totalAmount <= 0` |
| PUT | `/partner/me/bank` | 主账号银行三字段 |
| POST | `/admin/partner-bills/generate` | `{ partnerId, weekStartYmd }` |
| POST | `/admin/partner-bills/generate-all` | `{ weekStartYmd }` |
---
## 5. 验收
- [ ] 新建子账号创建后状态为 ACTIVE，可直接登录
- [ ] C 端扫码进入（未登录）已扫码 +1；登录绑定后已关联 +1；用户管理页正确展示，0 不显示
- [ ] 零元账单 HQ 可见 PENDING_REVIEW；发送被拒；合伙人 bills 列表/详情不可见
- [ ] 主账号可填写/编辑银行三字段；HQ 同步可见
- [ ] 首页/中心展示本周账期、下周一 08:00 出账、预付款预估（与手工核算抽样一致）
- [ ] 每周一 08:00 自动生成上周账单（非月账）
- [ ] 子账号 Tab 有用户管理；可下载二维码；无活动图入口/主图；主账号功能不变