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

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

2026-09-02 · iam / store / settlement / h5-partner / mini-user / admin-web
主题：合伙人 H5 子账号默认启用、关联码已扫码、零元账单过滤、银行账号自填、周结算、预付款预估、子账号用户管理（无活动图）

需求事实源：杜康好客-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 有用户管理；可下载二维码；无活动图入口/主图；主账号功能不变