# 杜康好客 · v4.0.6 开发文档

> **2026-08-31** · settlement / admin-web  
> **主题**：酒厂 T+3 = 每 3 天出一期；与全部已完成已付订单完全比对（含现场提货）；应付为 0 仍出账（无需打款）；核对补生成

需求事实源：[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md) §7 · V3 财务锚点仍见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) §3.3

---

## 1. 版本目标

| # | 任务 | 类型 | 交付 |
|---|------|------|------|
| 1 | T+3 出账节奏 | 修 | **每 3 天一张账单**（非每日）；纳入上期 3 个自然日全部已付已完成订单 |
| 2 | 含现场提货 | 修 | 不限配送类型 |
| 3 | 零应付 / 无单仍出账 | 修 | 出账日仍生成账单，展示「无需打款」 |
| 4 | 核对补生成 | 需求 | HQ 按区间重算周期出账日；清理旧「每日一账」空账单 |

---

## 2. 规则

对齐起点 `WINERY_BILL_EPOCH_YMD = 2026-08-01`，周期 `WINERY_SETTLEMENT_PERIOD_DAYS = 3`。

| 出账日 | 纳入完成日窗口 |
|--------|----------------|
| 8/4 | [8/1, 8/4) |
| 8/7 | [8/4, 8/7) |
| 8/28 | [8/25, 8/28) |
| 8/31 | [8/28, 8/31) |

- 应付 = `round2(Σ payAmount × 0.3)`
- `wineryAmount === 0` → UI/导出「无需打款」；确认打款拒绝
- 非周期日不生成；每日 cron 仅在出账日真正落账

### 旧逻辑为何对不上

旧实现是「**每天**出账，只收 **3 天前那一天** 的订单」：当天窗口无完成单就 skip → 8/4～8/28 大量空白；8/28、8/29 连着出是因为两天各自都有「D−3」完成单。

---

## 3. 变更面

| 位置 | 说明 |
|------|------|
| `packages/domain` | `isWineryIssueDay` / `shanghaiWineryPeriodWindow` / `wineryIssueDateFromCompletedAt` / `listWineryIssueDays` |
| `shared-types` | `WINERY_SETTLEMENT_PERIOD_DAYS`、`WINERY_BILL_EPOCH_YMD` |
| `settlement.service` | 周期出账；`reconcileWineryBills` 只跑周期日并清理非周期空账单 |
| `settlement.scheduler` | 每日尝试出账（非周期日 skip）+ 近 45 日核对 |
| `admin-web` | 文案 + 核对补生成 |

无 Prisma 迁移。线上历史账单一次性修复：`server/dukang-api/prisma/sql/fix-winery-bills-v406.sql`（补现场提货入账、中间 0 账、迁错期明细）。

---

## 4. 验收

- [ ] 账单日仅为 8/4、8/7、8/10… 这类周期日，不会连续两天各出一张（除非跨期）
- [ ] 核对补生成后，同城配送与现场提货订单均出现在对应期账单明细（历史现场单缺 `completedAt` 会自动用 `paidAt` 补齐）
- [ ] 每张账单明细覆盖上期 3 天全部已付已完成订单（含现场提货/同城/跨城）
- [ ] 出账日无单仍有账单，「无需打款」
- [ ] HQ「核对补生成」可选 8/4～今天，补齐中间漏期并清理误生成的每日账单
- [ ] 已打款账单不回刷