vault backup: 2026-05-25 22:07:35

prop-acc/concepts/deposit/red-receipt-design.md

@@ -0,0 +1,130 @@
+---
+title: prop-acc · deposit · 红字凭证设计
+aliases:
+  - 红字凭证设计
+  - 退款扣罚的金额正负
+  - 红字 CollectionOrder
+tags:
+  - 概念
+  - prop-acc
+  - 保证金
+  - 架构决策
+audience:
+  - 业务人员
+  - 架构师
+status: 已发布
+sub_feature: deposit
+last_review: 2026-05-25
+code_version: 2026-05-22
+---
+
+# 红字凭证设计
+
+押金的退款和扣罚**也走 `CollectionOrder` + `Receipt` 链路**,通过**金额正负**表达方向 —— 这就是"红字凭证"。本文说明为什么这么设计,以及它对凭证文案、报表、未来扩展的影响。
+
+## 核心结论(一句话)
+
+> [!tip] 本系统采用「金额正负」而非「新增枚举 case」表达退款/扣罚方向。
+> 缴款 `actual_amount = +5000`,退款 `actual_amount = -3000`,扣罚 `actual_amount = -2000`。  
+> `Receipt.amount` 同样可负。
+
+## 设计决策表
+
+| 维度 | 金额正负(已采用) | 加 `CollectionType` 枚举 case |
+|---|---|---|
+| **Schema 改动** | 零迁移 — `actual_amount` 是 `decimal` 无 CHECK 约束 | 改 enum + 改 listener match 分支 |
+| **报表聚合** | `SUM(actual_amount)` 一行算净值(收入 - 退款) | 需 `GROUP BY type` 再相减 |
+| **中国会计实践** | ✅「红字凭证」就是负数,会计师熟悉 | 不通用,需另解释 |
+| **未来扩展** | 同模式可直接复用(账单退款 / 预存款退款) | 枚举持续膨胀,每加一个业务加一个 case |
+| **类型分类细粒度** | `DepositTransaction.type` 已有 3 档 | 双重表达,信息冗余 |
+
+## 资金流示意
+
+```mermaid
+flowchart TD
+  subgraph "缴款(蓝字)"
+    A1[业户缴 5000] --> A2[DepositTransaction<br/>type=deposit, amount=5000]
+    A1 --> A3[CollectionOrder<br/>actual=+5000]
+    A3 --> A4[Receipt<br/>amount=+5000<br/>「装修保证金缴纳 ¥5,000」]
+  end
+
+  subgraph "退款(红字)"
+    B1[业户退 3000] --> B2[DepositTransaction<br/>type=refund, amount=3000]
+    B1 --> B3[CollectionOrder<br/>actual=-3000 红字]
+    B3 --> B4[Receipt<br/>amount=-3000 红字<br/>「装修保证金退还 ¥-3,000」]
+  end
+
+  subgraph "扣罚(红字)"
+    C1[物业扣 2000] --> C2[DepositTransaction<br/>type=forfeiture, amount=2000]
+    C1 --> C3[CollectionOrder<br/>actual=-2000 红字]
+    C3 --> C4[Receipt<br/>amount=-2000 红字<br/>「装修保证金扣罚 ¥-2,000」]
+  end
+```
+
+## 凭证文案如何区分退款/扣罚
+
+`Receipt.amount` 都是负数,但**文案不同**,业户一眼能看明白方向。
+
+| `DepositTransaction.type` | Receipt 文案 | 业户感受 |
+|---|---|---|
+| `refund` | 装修保证金退还 ¥-3,000 | 拿回自己的钱 |
+| `forfeiture` | 装修保证金扣罚 ¥-2,000 | 钱被扣了 |
+
+文案由 Listener `generateDepositReceiptItems` 按 `DepositTransaction.type` 选词,自动注入 Receipt 的 line items。
+
+> [!info] 未来增强:PDF 红色字样
+> Receipt PDF 模板对负数金额**当前是普通样式**,优先级排期低。可加红字效果(中国习惯)等业务方反馈再上。
+
+## CollectionStatus 仍用 `Completed` 而不是 `Disbursed`
+
+退款的 CollectionOrder 同样进入 `Completed` 状态,**不新增**"Disbursed(已支出)"枚举值。
+
+理由:
+
+- `Completed` 语义 = **"事务完成"**,不局限"收到钱"
+- 不加新 case 减少枚举膨胀,符合"最简单实用"
+- 报表里"已完成的 CO" `SUM(actual_amount)` 就是净值,无需关心方向
+
+`refund_status` 字段也**保持 `None`**,因为退款的 CollectionOrder 是**独立的红字单**,不是"原单的退款标记"。这与传统电商"在原订单上挂退款"模式不同 —— 那种模式适合一次性商品交易,不适合押金的"账户 + 流水"长期账本。
+
+## 为什么不在原 CollectionOrder 上挂退款标记?
+
+替代方案:在缴款单上加 `refund_amount` 和 `refund_status`,退款时改这两个字段。
+
+为什么我们没选:
+
+| 问题 | 后果 |
+|---|---|
+| 原单状态会被频繁更新 | 缴款时建立的"已完成快照"被破坏,审计追溯困难 |
+| 多次部分退款怎么办 | 原单要记一个数组?变成事实上的子流水,等于在错位置实现 |
+| 跨期对账 | 4 月缴的 5000 在 6 月退 3000 → 4 月的报表数据会变,跨期数字不稳定 |
+| 与新业务复用 | 账单 / 预存款的退款不能复用此模式,要各自重复实现 |
+
+红字独立单解决以上全部问题:每张单是不可变快照,跨期数字不变,各业务模块通过相同的"红字 CO + Receipt"模式表达退款。
+
+## 与一次性收费(adhoc)的对比
+
+| 维度 | adhoc 一次性收费 | deposit 保证金 |
+|---|---|---|
+| 主对象 | `AdHocEvent` | `DepositAccount` |
+| 流水/凭证 | `CollectionOrder` + `Receipt`(单笔) | `DepositTransaction` + 关联 `CollectionOrder` + `Receipt`(长期账本) |
+| 退款方式 | 走 [[adhoc-void-after-payment]] 作废 + 退款 | **红字 CollectionOrder**(独立单)|
+| 是否进入收入 | ✅ 一次性收入 | ❌ 负债科目(代管款) |
+
+详见 [[deposit-vs-adhoc-vs-prepaid]]。
+
+## 待补 / 已知限制
+
+| 项 | 状态 |
+|---|---|
+| Receipt PDF 红色字体样式 | 待补,优先级低 |
+| 小程序在线申请退款(走支付网关 webhook) | 待补,等业务有需求再加 |
+| `CollectionOrders/Actions/RecordRefundAction`(从原单视角的退款入口) | **已知重叠**,未来要统一为单一退款流程 |
+
+## 相关文档
+
+- [[deposit-account-vs-transaction]]
+- [[transaction-types]]
+- [[collection-order-and-receipt]]
+- [[refund-full-no-damage]]
+- [[forfeit-damage-public-area]]