uniprop-manual/prop-acc/scenarios/adhoc-void-after-payment.md

title, aliases, tags, audience, status, last_review, code_version

title	aliases	tags	audience	status	last_review	code_version
prop-acc · 场景 - 已收款作废	场景 - 已收款作废 场景-已收款作废	场景 prop-acc 一次性收费 业务场景 取消退款	业户 业务人员	已发布	2026-05-25	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 / 微信退款已发起 / 待退)
• 是否同一笔后续会重做(是 → 重新下单单号 / 否 → 完全取消)

系统流程

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 单的撤单,业户在小程序操作)
• 场景-取消-录错金额作废重做(更详细的"作废+重做"组合流程)