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

prop-acc/一次性收费/概念-AdHocEvent状态机.md

@@ -0,0 +1,79 @@
+---
+title: AdHocEvent 状态机
+tags:
+  - prop-acc
+  - 一次性收费
+  - 核心概念
+audience:
+  - 业务人员
+status: stable
+last_reviewed: 2026-05-25
+code_version: 2026-05-22
+---
+
+# AdHocEvent 状态机
+
+> [!info] 给谁看
+> 这篇主要给**业务人员**和**财务**。业户只关心"我买完了没",不需要懂状态机。
+
+每张一次性收费记录都有一个 `status` 字段,只有三种状态:
+
+| 状态 | 中文 | 什么时候出现 |
+|---|---|---|
+| `Pending` | 待付款 | B 流下单后未付款 |
+| `Completed` | 已收款 | A 流提交后 / B 流支付回调后 |
+| `Voided` | 已作废 | 走 VoidAction 后 |
+
+## 状态流转图
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending: B 流 小程序下单
+    [*] --> Completed: A 流 前台即收即付
+
+    Pending --> Completed: 业户付款<br/>(回调 或 前台补缴)
+    Pending --> Voided: 业户撤单<br/>或 超时未付
+    Completed --> Voided: 录错作废
+```
+
+## 每种状态下能做什么
+
+| 当前状态 | 编辑(Edit) | 作废(Void) | 删除(Delete) |
+|---|---|---|---|
+| **Pending** | ✅ 可改业户、金额等 | ✅ 跟 Completed 一样级联废 CO | ❌ 已禁用 UI 入口 |
+| **Completed** | ❌ 不可改(审计要求) | ✅ 级联废 CO + Receipt | ❌ 已禁用 UI 入口 |
+| **Voided** | ❌ | ❌ 已经废了 | ❌ |
+
+> [!warning] 为什么禁用 Delete?
+> 删除是无审计的物理操作,B 流的 Pending 单删掉会让关联的 CollectionOrder 变孤儿。所有"取消"统一走 [[场景-已收款作废\|VoidAction]] —— 留 `voided_at` / `voided_reason` / `voided_by` 完整审计。
+
+## 状态与 CollectionOrder / Receipt 的对应关系
+
+```mermaid
+stateDiagram-v2
+    state "Pending<br/>AdHocEvent + CO(Pending)<br/>没收据" as P
+    state "Completed<br/>AdHocEvent + CO(Completed)<br/>+ Receipt(Issued)" as C
+    state "Voided<br/>AdHocEvent + CO(Failed)<br/>+ Receipt(Voided)" as V
+
+    [*] --> P: B 流下单
+    [*] --> C: A 流即收即付
+    P --> C: 支付完成
+    P --> V: 业户撤 或 超时
+    C --> V: 已收款作废
+```
+
+详见 [[概念-CollectionOrder与Receipt]] 关于这三张表的关系。
+
+## 状态相关的几个时间字段
+
+- `created_at` —— 记录何时创建(下单时间)
+- `occurred_at` —— 业务发生时间(可能与 created_at 不同,业务自定义)
+- `meta.voided_at` —— 作废时间(如果走过 VoidAction)
+- `meta.voided_reason` —— 作废原因(运营/财务追溯)
+- `meta.voided_by` —— 谁作废的(责任追溯)
+
+## 看完去哪?
+
+- 想了解 CollectionOrder 和 Receipt 状态如何联动 → [[概念-CollectionOrder与Receipt]]
+- 想了解 A/B 两种流程的区别 → [[概念-A流与B流]]
+- 想看作废的真实例子 → [[场景-已收款作废]]