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