P3.5: prop-acc 启用子模块嵌套(adhoc/),应对大型业务域扩展

背景: 单纯按 UDAS 严格扁平,prop-acc/scenarios/ 装齐 7 子模块后预计 100-150 篇 .md 单一文件夹,Explorer 无法浏览、Quartz folder page 无法阅读。扩展规则(已写入 SKILL.md 多域章节 + multi-domain.md 第 10 节): - 单类型文件夹文件数 > 30 且能按业务子模块分组时,启用嵌套 - 路径:<domain>/<type>/<sub-feature>/<file>.md - 文件名去 <sub-feature>- 前缀(路径已表达) - title 三段式:<domain> · <sub-feature> · <名> - frontmatter 新增 sub_feature 字段(便于 RAG 过滤) - 跨子模块文档落在 <domain>/<type>/(不进子文件夹),与"跨域→cross/"对称本次迁移: - prop-acc/concepts/adhoc-*.md (3) → prop-acc/concepts/adhoc/*.md - prop-acc/scenarios/adhoc-*.md (25) → prop-acc/scenarios/adhoc/*.md - 每个文件:title 加 adhoc 段、aliases 追加旧 prop-acc · 前缀形式(兼容)、新增 sub_feature: adhoc 字段 WikiLink 解析未受影响: - 既有 [[场景-A流-...]] 等 200+ 引用通过 aliases (含旧 basename) 解析 - 新引用可用 [[adhoc · 前台购买 IC 卡]] 或 [[prop-acc · adhoc · 前台购买 IC 卡]] - 各域 knowledge-map.md 内 WikiLink 全部仍有效 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-25 20:55:59 +08:00
parent e9ed756fc4
commit 35c0147a7b
28 changed files with 84 additions and 28 deletions
--- a/prop-acc/concepts/adhoc/collection-order-and-receipt.md
+++ b/prop-acc/concepts/adhoc/collection-order-and-receipt.md
@@ -0,0 +1,114 @@
+---
+title: prop-acc · adhoc · CollectionOrder 与 Receipt
+aliases:
+  - prop-acc · CollectionOrder 与 Receipt
+  - CollectionOrder 与 Receipt
+  - 概念-CollectionOrder与Receipt
+tags:
+  - 概念
+  - prop-acc
+  - 一次性收费
+  - 核心概念
+audience:
+  - 业户
+  - 业务人员
+status: 已发布
+sub_feature: adhoc
+last_review: 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卡]]
+- 想看跨渠道场景 → [[场景-跨渠道补缴]]
--- a/prop-acc/concepts/adhoc/event-state-machine.md
+++ b/prop-acc/concepts/adhoc/event-state-machine.md
@@ -0,0 +1,85 @@
+---
+title: prop-acc · adhoc · AdHocEvent 状态机
+aliases:
+  - prop-acc · AdHocEvent 状态机
+  - AdHocEvent 状态机
+  - 概念-AdHocEvent状态机
+tags:
+  - 概念
+  - prop-acc
+  - 一次性收费
+  - 核心概念
+audience:
+  - 业务人员
+status: 已发布
+sub_feature: adhoc
+last_review: 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流]]
+- 想看作废的真实例子 → [[场景-已收款作废]]
--- a/prop-acc/concepts/adhoc/flow-a-vs-flow-b.md
+++ b/prop-acc/concepts/adhoc/flow-a-vs-flow-b.md
@@ -0,0 +1,86 @@
+---
+title: prop-acc · adhoc · A 流与 B 流
+aliases:
+  - prop-acc · A 流与 B 流
+  - A 流与 B 流
+  - 概念-A流与B流
+tags:
+  - 概念
+  - prop-acc
+  - 一次性收费
+  - 核心概念
+audience:
+  - 业户
+  - 业务人员
+status: 已发布
+sub_feature: adhoc
+last_review: 2026-05-25
+code_version: 2026-05-22
+---
+
+# A 流与 B 流
+
+一次性收费支持两条独立购买路径,**底层用同一套数据表**,差别只在用户怎么发起。
+
+## 一句话区别
+
+> [!tip] 通俗版
+> - **A 流**:您**到柜台**找物业阿姨,付了钱当场出货
+> - **B 流**:您**自己在小程序**下单,微信付完,过来取(或者送到家)
+
+## 对照表
+
+| 维度 | A 流(线下即收即付) | B 流(线上订单—支付分离) |
+|---|---|---|
+| **典型用户** | 老人、不会用手机的业户 | 年轻业户、工作日没空到前台的人 |
+| **触发动作** | 业户走到前台 | 小程序下单 |
+| **付款时机** | 当场付(现金 / POS / 微信扫码) | 下单时锁定金额、付款分离 |
+| **生效时机** | 即时 — 一笔操作完成所有 | 两步:下单 → 支付回调 |
+| **失败模式** | 几乎不可能(人在柜台) | 可能超时未付、可能支付掉单 |
+| **取消方式** | 走 [[场景-已收款作废\|作废]] 流程 | 改主意可主动撤;或超时自动作废 |
+
+## 系统视角(流程图)
+
+```mermaid
+sequenceDiagram
+    participant 业户
+    participant 前台
+    participant 小程序
+    participant 系统
+    participant 支付网关
+
+    Note over 业户,系统: A 流(线下即收即付)
+    业户->>前台: 我要买 IC 卡
+    前台->>系统: 录入业户、项目、金额、付现金
+    系统->>系统: 一气呵成:建事件 + 建订单 + 建收据
+    系统-->>业户: 打印 / 微信收据立马拿到
+
+    Note over 业户,支付网关: B 流(订单—支付分离)
+    业户->>小程序: 下单 IC 卡
+    小程序->>系统: 建事件(Pending) + 建订单(Pending)
+    系统-->>业户: 锁价格、给您订单号
+    业户->>支付网关: 微信付款
+    支付网关->>系统: 支付回调
+    系统->>系统: 更新订单(Completed) + 自动出收据
+    系统-->>业户: 小程序通知:已付款,可来取货
+```
+
+## 为什么要两套?
+
+> [!info] 业户视角
+> - 老人不会用小程序 → A 流照顾他们
+> - 年轻人不想跑前台 → B 流方便
+> - **同一项业务两种付款方式都能用**
+
+> [!info] 系统视角
+> 两套**共用同一张 `AdHocEvent` 表 + 同一张 `CollectionOrder` 表**。差别只在:
+> - A 流一气呵成创建后,状态直接 `Completed`
+> - B 流先创建为 `Pending`,等支付回调才翻 `Completed`
+>
+> 这种设计的好处是**跨渠道补缴**天然支持 —— 详见 [[场景-跨渠道补缴]]。
+
+## 看完去哪?
+
+- 想了解购买后系统记了什么 → [[概念-CollectionOrder与Receipt]]
+- 想了解订单的几种状态 → [[概念-AdHocEvent状态机]]
+- 想看真实例子 → [[场景-A流-前台购买IC卡]] 或 [[场景-B流-小程序下单+微信支付]]