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>
This commit is contained in:
Willie
153
prop-acc/scenarios/adhoc/void-after-payment.md
Normal file
153
prop-acc/scenarios/adhoc/void-after-payment.md
Normal file
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: prop-acc · adhoc · 场景 - 已收款作废
|
||||
aliases:
|
||||
- prop-acc · 场景 - 已收款作废
|
||||
- 场景 - 已收款作废
|
||||
- 场景-已收款作废
|
||||
tags:
|
||||
- 场景
|
||||
- prop-acc
|
||||
- 一次性收费
|
||||
- 业务场景
|
||||
- 取消退款
|
||||
audience:
|
||||
- 业户
|
||||
- 业务人员
|
||||
status: 已发布
|
||||
sub_feature: adhoc
|
||||
last_review: 2026-05-25
|
||||
code_version: 2026-05-22
|
||||
---
|
||||
|
||||
# 场景:已收款作废
|
||||
|
||||
业户**已经付了钱**,但因为各种原因(录错、反悔、退货)需要作废这笔交易。**走 VoidAction 路径**,系统级联废订单 + 收据,留完整审计。
|
||||
|
||||
## 典型情境
|
||||
|
||||
> [!example] 情境 1:职员录错金额
|
||||
> 张阿姨买 IC 卡 ¥30,职员手滑录成 ¥300,业户付完发现不对。
|
||||
>
|
||||
> → 立刻作废 → 退还 ¥300 现金 → 重新录入正确金额 ¥30 → 业户重新付 ¥30。
|
||||
|
||||
> [!example] 情境 2:业户反悔
|
||||
> 李先生买了张游泳卡 ¥200,出门走两步觉得不想要了。
|
||||
>
|
||||
> → 当场作废 → 退还 ¥200 现金。
|
||||
|
||||
> [!example] 情境 3:实物缺货
|
||||
> 业户付了 IC 卡的钱,但当天工本卡库存为 0 制不了卡。
|
||||
>
|
||||
> → 作废订单 → 退还现金 → 等到货后业户再来。
|
||||
|
||||
## 业户视角
|
||||
|
||||
### 您看到什么
|
||||
|
||||
- 您付完钱后告诉职员要作废
|
||||
- 职员当场操作,系统**几秒内完成**
|
||||
- 现金当场退还(或微信原路退回)
|
||||
- 您能收到**新的"作废收据"**或在小程序"我的订单"看到状态变 `已作废`
|
||||
|
||||
> [!success] 没有"二次扣款"风险
|
||||
> 作废操作是**原子的**(整体成功或整体回滚)。不会出现"系统已退钱、但订单还显示已收款"的半成品状态。
|
||||
|
||||
## 业务人员视角
|
||||
|
||||
### 操作步骤
|
||||
|
||||
```
|
||||
Filament 后台 → 一次性收费列表
|
||||
├── 找到该订单(状态 Completed)
|
||||
├── 点击行操作菜单
|
||||
└── "作废"(红色危险按钮)
|
||||
├── Modal 弹出
|
||||
├── 必填:作废原因(详细文字,后续审计要看)
|
||||
│ 例:"客户取消订单,现金已退还"
|
||||
│ 例:"录入金额错误,客户付款后发现"
|
||||
│ 例:"工本卡缺货,客户无法当场拿货"
|
||||
├── 提交
|
||||
└── 系统瞬间完成:
|
||||
├── AdHocEvent → Voided
|
||||
├── CollectionOrder → Failed
|
||||
├── Receipt → Voided
|
||||
└── meta 记 voided_at / voided_reason / voided_by
|
||||
```
|
||||
|
||||
### 然后业务人员手动处理资金
|
||||
|
||||
> [!warning] 关键:**资金不会自动退**
|
||||
> VoidAction 只更新数据库记录,**不会自动调用退款接口**。需要业务人员:
|
||||
>
|
||||
> - **现金支付**:从收银抽屉拿出对应金额还给业户
|
||||
> - **微信支付**:在物业商户后台手动发起退款(微信会几小时内退到业户原账户)
|
||||
> - **POS 刷卡**:在 POS 机上做"撤销"操作(只能当天)
|
||||
>
|
||||
> 如果业务方将来需要"作废 = 自动退款"的一体化,可以补 RefundAction。当前不做。
|
||||
|
||||
### 业务人员必须填的"作废原因"
|
||||
|
||||
> [!tip] 写清楚 = 自救
|
||||
> 半年后审计来抽查,问"这笔为啥作废"。如果 voided_reason 只写"作废了" → 业务人员说不清。
|
||||
>
|
||||
> 推荐写法:
|
||||
> - **谁要求作废**(客户主动 / 物业发现 / 系统异常)
|
||||
> - **作废后资金处理**(已退现金 ¥X / 微信退款已发起 / 待退)
|
||||
> - **是否同一笔后续会重做**(是 → 重新下单单号 / 否 → 完全取消)
|
||||
|
||||
## 系统流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant 业务人员
|
||||
participant Filament
|
||||
participant 数据库
|
||||
|
||||
业务人员->>Filament: 选择已收款订单,点"作废"
|
||||
Filament->>业务人员: 弹出 Modal,要求填作废原因
|
||||
业务人员->>Filament: 提交(含原因)
|
||||
Filament->>数据库: 开启事务
|
||||
Filament->>数据库: 1. Receipt.void(reason) 翻 Voided
|
||||
Filament->>数据库: 2. CollectionOrder.update(status=Failed, meta+voided_*)
|
||||
Filament->>数据库: 3. AdHocEvent.update(status=Voided, meta+voided_*)
|
||||
Filament->>数据库: 提交事务
|
||||
Filament-->>业务人员: 作废成功通知
|
||||
```
|
||||
|
||||
> [!info] 三表级联,一处失败全回滚
|
||||
> Receipt 失败 → CollectionOrder 不动、AdHocEvent 不动。三张表要么全成功要么全回到原状,不会出现"事件作废了但收据还显示有效"的脏数据。
|
||||
|
||||
## 与 Pending 单作废的区别
|
||||
|
||||
| 维度 | Pending 单作废 | Completed 单作废(本场景) |
|
||||
|---|---|---|
|
||||
| 触发场景 | 业户撤单 / 超时 | 业户已付款后反悔 / 录错 |
|
||||
| 是否级联废收据 | ❌ Pending 单没收据 | ✅ 收据翻 Voided |
|
||||
| 资金 | 没收过,不用退 | **需手动退还**(系统不自动)|
|
||||
| 操作复杂度 | 一键 | 一键 + 业务人员手动处理资金 |
|
||||
|
||||
## 常见问题
|
||||
|
||||
> [!question] 作废后还能"再恢复"成已收款吗?
|
||||
> **不能**。Voided 是终态。要重做,**新建一单**即可(订单号会不同,审计独立)。
|
||||
|
||||
> [!question] 业务人员忘了写作废原因怎么办?
|
||||
> Modal 表单**强制必填**,空着提交会被拒绝。
|
||||
|
||||
> [!question] 业户已经走了,我能事后作废吗?
|
||||
> 技术上**可以**,但要**联系业户协调资金**(打电话叫人来拿钱、或微信转账)。原则上**当场处理最干净**。
|
||||
|
||||
> [!question] 这跟"退款"有什么区别?
|
||||
> 作废 = "这笔交易不存在了,数据库标记废除"。退款 = "交易存在,但钱退回去了"。当前一次性收费**只做作废**,没有独立的退款流程。如果未来业务方需要"红字凭证 + 保留原单"的退款,会按保证金/预存款模块同款方式实现。
|
||||
|
||||
## 相关概念
|
||||
|
||||
- [[概念-AdHocEvent状态机]] — Completed → Voided 流转
|
||||
- [[概念-CollectionOrder与Receipt]] — 三件套同步翻状态
|
||||
- [[场景-A流-前台购买IC卡]] — 正向流程
|
||||
- [[场景-B流-小程序下单+微信支付]] — 线上交易也可作废
|
||||
|
||||
## 待补场景
|
||||
|
||||
- 场景-取消-业户改主意主动撤单(Pending 单的撤单,业户在小程序操作)
|
||||
- 场景-取消-录错金额作废重做(更详细的"作废+重做"组合流程)
|
||||
Reference in New Issue
Block a user