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

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

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

需求事实源：杜康好客-v4-PRD.md §7 · V3 财务锚点仍见 杜康好客-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～今天，补齐中间漏期并清理误生成的每日账单
• 已打款账单不回刷