vault backup: 2026-05-25 23:27:56

2026-05-25 23:27:56 +08:00
parent f407569771
commit ae134c321d
5 changed files with 793 additions and 4 deletions
--- a/prop-acc/scenarios/prepaid/consume-batch-auto-monthly.md
+++ b/prop-acc/scenarios/prepaid/consume-batch-auto-monthly.md
@@ -0,0 +1,224 @@
+---
+title: prop-acc · prepaid · 场景 - 月初批量自动抵扣 job(待补)
+aliases:
+  - 月初自动抵扣
+  - 批量预存款抵账单
+  - consume-batch-auto-monthly
+  - 场景-月初自动抵扣
+tags:
+  - 场景
+  - prop-acc
+  - 预存款
+  - 消费
+  - 待补
+audience:
+  - 业务人员
+  - 财务
+  - 产品
+status: 草稿
+sub_feature: prepaid
+last_review: 2026-05-25
+code_version: 2026-05-22
+---
+
+# 场景:月初批量自动抵扣 job(待补)
+
+> [!warning] 本场景**代码未实现**
+> 当前所有 consume 操作都需要业务人员**手动后台触发**。本文档描述自动 job 落地后的目标态。设计意图详见 [[auto-deduction-design]]。
+
+预存款的**产品价值核心**。月初 1 日凌晨,Scheduled job 扫所有 Active + 余额>0 的预存款账户,对每个账户找未付账单,按优先级 ([[consume-multiple-bills-priority]]) 自动抵扣。
+
+## 典型情境(目标态)
+
+> [!example] 真实情境(目标态)
+> 2026 年 6 月 1 日 00:30,系统自动跑 `PrepaidAutoDeductionJob`:
+>
+> - 扫描全平台 5 个社区,共 500 个 Active 预存款账户(余额 > 0)
+> - 对每个账户找该业户的未付账单(物业费 + 水电费 + ...)
+> - 按 due_at 升序抵扣
+> - 全部完成耗时 ~5 分钟
+>
+> 早上 8 点,500 个业户陆续收到推送:
+>
+> | 业户场景 | 推送内容 |
+> |---|---|
+> | 余额充足,全抵 | "5 月账单已自动抵扣 ¥1,000,余额 ¥4,000" |
+> | 余额部分够 | "已抵 ¥800,水电费 ¥200 余额不足,请充值" |
+> | 账户冻结 | (不推送)|
+
+## 业户视角(目标态)
+
+### 您会感受到什么
+
+- 月初某个早晨突然收到推送
+- 小程序"我的账单"批量翻为 ✅ Paid
+- 小程序"我的预存款"流水里多几笔 consume
+- 收到对应数量的 Receipt(每张账单一张)
+- **完全无感**(理想状态),不需要任何操作
+
+### 您要做什么
+
+只在以下情况要做:
+
+| 推送内容 | 您要做 |
+|---|---|
+| "余额不足,X 账单未付" | 充值 → 业务人员手动补抵 / 等下月自动 job |
+| "账户冻结无法抵" | 联系物业了解冻结原因 |
+| "所有账单已抵,余额还剩 ¥X" | 不用做 |
+
+## 业务人员视角
+
+### Job 执行前
+
+业务人员**不需要任何操作**。Scheduled 配置在系统层,运行无需介入。
+
+### Job 执行过程
+
+后台监控面板(待开发):
+
+- 实时进度:已处理 N / 总共 M 账户
+- 实时统计:已抵账单数、抵扣总额、失败数、跳过数
+- 失败告警:任何异常立即推送给 ops
+
+### Job 执行后
+
+业务人员看汇总报告(后台 / 邮件):
+
+```markdown
+# 2026 年 6 月 1 日 PrepaidAutoDeductionJob 报告
+
+## 统计
+- 候选账户:500
+- 全抵成功:380(76%)
+- 部分抵 / 跳过:80(16%)
+- 跨社区拦截:0
+- 账户冻结跳过:8(2%)
+- 失败(异常):0(0%)
+- 其余(余额=0、无未付账单):32(6%)
+
+## 资金动作
+- 抵扣总额:¥412,300
+- 涉及账单数:835(平均每户 1.6 张)
+- 平均抵扣金额:¥513
+- 最大单户抵扣:¥3,200(陈先生家,水电+物业+电梯)
+
+## 失败明细
+(无)
+
+## 跳过明细(需关注)
+- 80 户余额不足,合计欠款 ¥45,000
+  - 已发推送
+  - 业务人员可后续手动追缴
+
+## 冻结跳过
+- 8 户冻结中
+  - 需业务人员核实是否解冻
+```
+
+### 异常介入
+
+| 场景 | 业务人员动作 |
+|---|---|
+| 跳过的余额不足业户 | 联系业户充值 + 后续手动 ConsumeAction |
+| 冻结跳过业户 | 核实纠纷 / 风控状态 → [[unfreeze-after-verification|解冻]] |
+| Job 失败(系统异常) | 立即联系运维查日志 |
+| 某账户重复抵扣(理论上不应该) | 查 transactions 表是否有同一 Bill 被抵两次 → 立即停 job 排查 |
+
+## 系统流程(目标态)
+
+```mermaid
+sequenceDiagram
+    participant Scheduler
+    participant Job[PrepaidAutoDeductionJob]
+    participant Account[PrepaidAccount]
+    participant Bill
+    participant Consume[ConsumeFromPrepaidAccountAction]
+    participant 监听器
+    participant 数据库
+    participant 业户
+
+    Note over Scheduler: 2026-06-01 00:30 触发
+
+    Scheduler->>Job: dispatch
+    Job->>数据库: SELECT prepaid_accounts WHERE status=Active AND balance>0
+
+    loop 每个 account
+      Job->>数据库: SELECT bills WHERE community_id=? AND resident_id=? AND status='unpaid' ORDER BY due_at, amount
+
+      loop 每个 bill
+        alt balance >= bill.amount
+          Job->>Consume: handle(account, bill, bill.amount)
+          Consume->>Account: consume()
+          Consume->>Bill: recordPayment() → Paid
+          Consume->>监听器: 触发 CollectionOrderCompleted
+          监听器->>数据库: 建 Receipt
+          Consume->>数据库: 提交事务
+        else 余额不够
+          Job->>Job: 跳过,记日志
+        end
+      end
+    end
+
+    Job->>数据库: 写汇总报告
+    Job-->>Scheduler: 完成
+    Job->>业户: 批量推送通知
+```
+
+## Job 的安全设计(目标态)
+
+| 风险 | 防御 |
+|---|---|
+| 同一账户被抵两次(job 重跑) | 每笔 consume 关联 Bill,Bill.status=Paid 后跳过 |
+| 跨社区误抵 | `ConsumeFromPrepaidAccountAction` 内置守护(consume 模型方法层) |
+| Frozen 账户被抵 | `canOperate()` 守护(模型层) |
+| 余额为负 | 事务回滚 + amount ≤ balance 守护 |
+| Job 长时间运行影响业务 | 分批 chunk(100 / 批);限制最大并发 |
+| Job 半夜失败无人发现 | 失败告警(Slack / 钉钉 / 短信)|
+| 业户充值后想立即抵(月中)| 业务人员手动 ConsumeAction(不等下月 job)|
+
+## 与手动 ConsumeAction 的关系
+
+| 维度 | 手动 ConsumeAction | 自动 Job |
+|---|---|---|
+| 触发 | 业务人员后台点击 | Scheduled(月初)|
+| 单次范围 | 1 账户 × 1 账单 | 全平台 × 全部账户 × 全部账单 |
+| 业务场景 | 个案、运维、补抵 | 月度默认流程 |
+| 通知 | 单笔 Receipt | 批量 Receipt + 汇总推送 |
+| 复用代码 | `ConsumeFromPrepaidAccountAction` | **同上**(复用,不重写)|
+
+## 实施前已记录的待讨论项
+
+详见 [[auto-deduction-design]] "待讨论 / 决策" 段。简略列表:
+
+- 触发频率(月度 / 周度 / 实时)
+- 触发时点(月初固定 / 账单生成事件触发)
+- 优先级排序(due_at / amount / bill_type 组合)
+- 部分抵扣支持
+- 失败通知策略
+- 监控指标
+
+## 未来扩展
+
+job 落地后,后续可演化:
+
+| 演化方向 | 价值 |
+|---|---|
+| **小程序"我的账单"显示"将于 X 月 1 日自动扣"** | 业户预期管理,避免临时余额不足惊讶 |
+| **预扣预警**:月底前 7 天扫描"下月账单 > 当前余额"的业户 → 主动提醒充值 | 减少跳过率,提升用户体验 |
+| **零余额自动通知**:月初 job 后,余额 = 0 的账户主动推送"请充值" | 提升复购率 |
+| **跨账户均衡**(若同业户多社区):未来若放开跨社区抵扣 | 提升资金利用率 |
+
+## 当前替代(job 实现前)
+
+- 业务人员**月初批量手动**逐户处理(见 [[consume-monthly-property-bill]] + [[consume-multiple-bills-priority]])
+- 工作量大,容易遗漏 / 顺序错乱
+- **这就是 job 紧迫性的来源**
+
+## 相关文档
+
+- [[auto-deduction-design]]
+- [[consume-monthly-property-bill]]
+- [[consume-multiple-bills-priority]]
+- [[consume-meter-bill]]
+- [[consume-via-bill-collection-type]]
+- [[audit-low-balance-and-overdue]]