vault backup: 2026-05-25 13:24:32

prop-acc/一次性收费/概念-CollectionOrder与Receipt.md

@@ -0,0 +1,108 @@
+---
+title: CollectionOrder 与 Receipt
+tags:
+  - prop-acc
+  - 一次性收费
+  - 核心概念
+audience:
+  - 业户
+  - 业务人员
+status: stable
+last_reviewed: 2026-05-25
+code_version: 2026-05-22
+---
+
+# CollectionOrder 与 Receipt
+
+您在物业买东西,系统里实际生成的不是一条记录,而是**三件套**。理解了这三件套,就理解了财务系统大部分操作。
+
+## 三件套是什么?
+
+```mermaid
+graph LR
+    A[AdHocEvent<br/>一次性收费事件] --> B[CollectionOrder<br/>收款订单]
+    B --> C[Receipt<br/>收据]
+    C --> D[ReceiptItem<br/>收据明细行]
+
+    classDef event fill:#fef3c7
+    classDef order fill:#dbeafe
+    classDef receipt fill:#dcfce7
+
+    class A event
+    class B order
+    class C,D receipt
+```
+
+| 表 | 是什么 | 业户能看到? |
+|---|---|---|
+| **AdHocEvent** | "您买了什么"的业务记录(IC 卡 / 装修证 / 泳票) | ❌ 内部 |
+| **CollectionOrder** | "怎么付的"的收款记录(微信 / 现金 / POS / 支付宝 / 银行卡) | ✅ 订单号 CO-... |
+| **Receipt** | "您付了钱"的收据 | ✅ 收据号 R-... 可打印/下载 |
+| **ReceiptItem** | 收据上每行细目(例:IC 卡 × 1 = ¥30) | ✅ 在收据里看到 |
+
+## 业户视角
+
+> [!example] 业户视角:您拿到的东西
+>
+> 您去前台买了一张 IC 卡 ¥30,完成后:
+>
+> 1. **物品本身**:工本费一张实物 IC 卡
+> 2. **收据**(PDF 或纸质):
+>    ```
+>    收据 No: R-20260525-001
+>    ─────────────────────────
+>    IC 卡(门禁)        ¥30.00
+>    ─────────────────────────
+>    合计:              ¥30.00
+>    支付方式:现金
+>    收款人:张阿姨(柜台)
+>    ```
+>
+> 这张收据就是您的凭证。月底想对账?有收据号一查就知道。
+
+## 业务人员 / 财务视角
+
+> [!example] 财务对账时
+>
+> 月底财务想知道这个月卖了多少 IC 卡,会查:
+> - `AdHocEvent` 表 → 多少张 IC 卡售出,卖给谁
+> - `CollectionOrder` 表 → 多少张订单是 "现金 / 微信 / 支付宝" 各多少
+> - `Receipt` 表 → 已开收据多少张,作废多少张
+>
+> 三张表通过 ID 互相关联,任一张里查到一笔,都能反查到另外两张对应的行。
+
+## 什么时候生成?
+
+| 操作 | AdHocEvent | CollectionOrder | Receipt |
+|---|---|---|---|
+| **A 流前台买卡**(即收即付)| 立刻建 | 立刻建(Completed) | 立刻自动生成 |
+| **B 流小程序下单**(尚未付款)| 立刻建(Pending) | 立刻建(Pending) | ❌ 还没生成 |
+| **B 流支付回调到达**| 翻为 Completed | 翻为 Completed | 此刻自动生成 |
+| **作废订单** | 翻为 Voided | 翻为 Failed | 翻为 Voided |
+
+> [!info] 收据怎么"自动生成"
+> 系统监听一个叫 `CollectionOrderCompleted` 的事件 —— 任何时候订单状态变为 Completed,系统自动建一张 Receipt 并附明细。业户不用做任何操作。
+
+## 为什么要这么设计?
+
+> [!tip] 为什么不只用一张表?
+> 因为这三件事**关注点不同**:
+>
+> - **AdHocEvent** 关注"卖了什么、卖给谁"(业务面)
+> - **CollectionOrder** 关注"钱怎么进来的、走哪个渠道"(财务/资金面)
+> - **Receipt** 关注"给业户的凭证"(对外面)
+>
+> 同一笔交易,业务/财务/对外三个角度独立看,审计、对账、合规都清楚。
+
+## 退款时的红字收据
+
+> [!warning] 退款也走这套链路
+> 退款时系统会生成一张**负数**的 CollectionOrder + Receipt(金额带负号),叫"红字凭证"。这是中国会计标准做法,详见保证金模块的退款场景文档(待补)。
+>
+> 一次性收费目前**主要走作废**而不是退款 —— 详见 [[场景-已收款作废]]。
+
+## 看完去哪?
+
+- 想了解订单状态怎么变 → [[概念-AdHocEvent状态机]]
+- 想看真实例子 → [[场景-A流-前台购买IC卡]]
+- 想看跨渠道场景 → [[场景-跨渠道补缴]]