vault backup: 2026-05-25 23:22:55

prop-acc/scenarios/prepaid/deposit-via-miniapp-pending.md

@@ -0,0 +1,180 @@
+---
+title: prop-acc · prepaid · 场景 - 小程序在线充值(待补)
+aliases:
+  - 小程序充值预存款
+  - 线上充值预存款
+  - deposit-via-miniapp-pending
+  - 场景-小程序充值预存款
+tags:
+  - 场景
+  - prop-acc
+  - 预存款
+  - 充值
+  - 待补
+audience:
+  - 业户
+  - 产品
+  - 架构师
+status: 草稿
+sub_feature: prepaid
+last_review: 2026-05-25
+code_version: 2026-05-22
+---
+
+# 场景:小程序在线充值(待补)
+
+> [!warning] 本场景**代码未实现**
+> 当前所有充值都是**业务人员后台手动触发**。业户**没有自助充值入口**(微信小程序 / 公众号 / H5 都没接入)。本文档描述设计意图,等支付网关对接时一起落地。
+>
+> issue.md Q4 "待补" 段记录:
+> > 小程序在线充值 + 退款 webhook:同保证金模块,等支付网关对接时一起做
+
+## 为什么这个场景重要
+
+预存款的**真正价值**是业户**自助**预存 + 系统自动抵账单。如果业户每次充值都要"跑前台 / 找物业管家",体验跟去前台月月缴费没区别,预存款产品价值大打折扣。
+
+**自助充值是产品落地的必备入口**。
+
+## 业务场景(目标态)
+
+### 业户视角
+
+> [!example] 真实情境(目标态)
+> 陈先生(年轻业主)某晚 11 点查看本月物业费账单,看到余额不够,马上在小程序"我的预存款"页面充值:
+>
+> 1. 点"立即充值"
+> 2. 选金额(500 / 1000 / 3000 / 5000 / 自定义)
+> 3. 弹出微信支付确认
+> 4. 输入密码 / 指纹 → 付款成功
+> 5. 小程序 3 秒后提示"充值成功,余额已到账"
+>
+> 第二天物业费账单自动从余额扣,陈先生收到推送"已抵扣物业费 ¥800"。
+
+### 业务人员视角
+
+业务人员**几乎不感知**:
+
+- 不需要在后台手动建账户 / 录充值
+- 月底对账时,看 CollectionOrder 列表多了一批 `payment_channel=微信`、`fund_source=external` 的预存款充值单
+- 异常(支付掉单 / 超时未付)由系统自动处理
+
+## 关键技术挑战
+
+### 1. 支付网关对接
+
+| 选项 | 优 | 缺 |
+|---|---|---|
+| 微信支付商户号 | 业户熟悉,转化高 | 资质要求高,手续费 0.6% |
+| 支付宝 | 大额支付习惯 | 同上 |
+| 银联 / 网银 | 大额转账 | 体验差 |
+
+**推荐**:微信支付 + 支付宝双通道,与一次性收费 B 流复用([[../adhoc/flow-b-miniapp-wechat-pay|adhoc B 流]])。
+
+### 2. CollectionOrder 状态机
+
+复用与 adhoc B 流相同的 Pending → Completed 流程([[../adhoc/flow-a-vs-flow-b|A 流与 B 流]]):
+
+```mermaid
+sequenceDiagram
+    participant 业户
+    participant 小程序
+    participant 系统
+    participant 支付网关
+
+    业户->>小程序: 选 5000 充值
+    小程序->>系统: 建 CollectionOrder(type=Prepaid, +5000, **status=Pending**)
+    系统-->>小程序: 返回订单号 + 锁定金额
+    小程序->>支付网关: 调起微信支付
+    业户->>支付网关: 输入密码 / 指纹付款
+    支付网关->>系统: 支付回调 webhook
+    系统->>系统: 校验签名 + 金额
+    系统->>系统: CO.status = Completed
+    系统->>系统: 调 PrepaidAccount::deposit(5000)
+    系统->>系统: 触发 CollectionOrderCompleted → Receipt
+    系统-->>业户: 推送"充值成功"
+```
+
+### 3. 自动开户
+
+如果业户在小程序充值时**还没有预存款账户**:
+
+| 方案 A:必须先开户 | 方案 B:充值时自动开户 |
+|---|---|
+| 业户去前台开户 → 小程序充值 | 小程序充值流程内自动建账户 |
+| 体验割裂(为啥要去前台?) | 体验顺畅 |
+| 业务人员必须介入 | 全程自动 |
+
+**推荐方案 B**:充值时若 `PrepaidAccount` 不存在,自动建 Active 账户(`opened_at` = 充值时间)。
+
+### 4. 失败处理
+
+| 失败场景 | 处理 |
+|---|---|
+| 业户付了款,回调延迟 | CO 仍 Pending → 业户重复点充值 → 防重(检查 24h 内同业户同金额 Pending CO)|
+| 业户付了款,回调丢失 | 定时任务扫描 Pending > 30 min 的 CO,主动查询支付网关 |
+| 业户取消支付 | CO 翻 Failed,余额不变 |
+| 业户付款金额与订单不符(异常)| 拒绝,告警,人工介入 |
+
+### 5. 退款 webhook
+
+业户在小程序自助申请退款:
+
+```mermaid
+sequenceDiagram
+    业户->>小程序: 申请退余 3000
+    小程序->>系统: 建退款申请单(待业务审批)
+    Note over 系统: 业务审批通过后:
+    系统->>支付网关: 调退款 API
+    支付网关->>系统: 退款回调 webhook
+    系统->>系统: 建红字 CO + PrepaidTransaction(refund)
+    系统-->>业户: 推送"退款成功"
+```
+
+**关键**:不像后台手动退款是"业务人员决定退多少",小程序自助退款必须**先建审批工单**,业务方审核(防止业户恶意大额退款),通过后才走支付网关退款。
+
+## 待讨论 / 决策
+
+| 问题 | 选项 |
+|---|---|
+| **支付通道** | 微信支付 / 支付宝 / 银联 / 全部都开 |
+| **充值起步** | 最低 100 / 500 / 1000 |
+| **充值上限** | 单笔 5000 / 10000 / 不限 |
+| **自动开户** | 充值时自动建 Active 账户 vs 业户必须先去前台 |
+| **退款审批** | 业户提交即退 vs 业务审批后退 / 大额(>5000)需审批 |
+| **超时未付** | 30 分钟自动取消 / 24 小时 / 不取消(避免业户晚付被取消)|
+
+业务方拍板前,以上问题需明确。
+
+## 当前替代方案(等代码就位前)
+
+业户想自助充值的,目前只能:
+
+| 方法 | 体验 |
+|---|---|
+| 联系物业管家微信 → 转账给物业财务 → 财务后台录入 | 还行,但有时延 |
+| 到前台缴 → 现金 / POS | 慢、要跑 |
+| 银行直接对公转账 → 备注业户姓名房号 → 财务认领 | 慢 + 复杂 |
+
+**所有路径都需要业务人员介入** —— 体验远不如小程序自助。这就是为什么这个场景"产品价值高、紧迫性强"。
+
+## 关联场景
+
+实现后,以下场景的设计会发生关联变化:
+
+- [[deposit-first-time]] / [[deposit-additional-topup]]:多一条"业户自助充值"路径,业务人员手动充值场景变少(但仍需保留,给老业主用)
+- [[consume-batch-auto-monthly]]:小程序充值后自动到账,月初批量自动抵扣 job 可立即用上新余额
+- [[refund-full-resident-moveout]] / [[refund-partial-after-consume]]:多一条"业户小程序自助申请"路径,需要审批流
+
+## 异常分支(未来落地后)
+
+- 支付网关掉单 / 超时 → 系统重试 / 业务介入
+- 业户充错金额 → 走退款流程
+- 业户重复提交 → 防重检测
+
+## 相关文档
+
+- [[auto-deduction-design]]
+- [[deposit-first-time]]
+- [[deposit-additional-topup]]
+- [[../adhoc/flow-a-vs-flow-b|A 流与 B 流]](adhoc 的小程序在线模式,参考实现)
+- [[../adhoc/flow-b-miniapp-wechat-pay|adhoc 小程序微信付]]