6.5 KiB
title, aliases, tags, audience, status, sub_feature, last_review, code_version
| title | aliases | tags | audience | status | sub_feature | last_review | code_version | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| prop-acc · prepaid · 场景 - 小程序在线充值(待补) |
|
|
|
草稿 | prepaid | 2026-05-25 | 2026-05-22 |
场景:小程序在线充值(待补)
[!warning] 本场景代码未实现 当前所有充值都是业务人员后台手动触发。业户没有自助充值入口(微信小程序 / 公众号 / H5 都没接入)。本文档描述设计意图,等支付网关对接时一起落地。
issue.md Q4 "待补" 段记录:
小程序在线充值 + 退款 webhook:同保证金模块,等支付网关对接时一起做
为什么这个场景重要
预存款的真正价值是业户自助预存 + 系统自动抵账单。如果业户每次充值都要"跑前台 / 找物业管家",体验跟去前台月月缴费没区别,预存款产品价值大打折扣。
自助充值是产品落地的必备入口。
业务场景(目标态)
业户视角
[!example] 真实情境(目标态) 陈先生(年轻业主)某晚 11 点查看本月物业费账单,看到余额不够,马上在小程序"我的预存款"页面充值:
- 点"立即充值"
- 选金额(500 / 1000 / 3000 / 5000 / 自定义)
- 弹出微信支付确认
- 输入密码 / 指纹 → 付款成功
- 小程序 3 秒后提示"充值成功,余额已到账"
第二天物业费账单自动从余额扣,陈先生收到推送"已抵扣物业费 ¥800"。
业务人员视角
业务人员几乎不感知:
- 不需要在后台手动建账户 / 录充值
- 月底对账时,看 CollectionOrder 列表多了一批
payment_channel=微信、fund_source=external的预存款充值单 - 异常(支付掉单 / 超时未付)由系统自动处理
关键技术挑战
1. 支付网关对接
| 选项 | 优 | 缺 |
|---|---|---|
| 微信支付商户号 | 业户熟悉,转化高 | 资质要求高,手续费 0.6% |
| 支付宝 | 大额支付习惯 | 同上 |
| 银联 / 网银 | 大额转账 | 体验差 |
推荐:微信支付 + 支付宝双通道,与一次性收费 B 流复用(../adhoc/flow-b-miniapp-wechat-pay)。
2. CollectionOrder 状态机
复用与 adhoc B 流相同的 Pending → Completed 流程(../adhoc/flow-a-vs-flow-b):
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
业户在小程序自助申请退款:
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:多一条"业户小程序自助申请"路径,需要审批流
异常分支(未来落地后)
- 支付网关掉单 / 超时 → 系统重试 / 业务介入
- 业户充错金额 → 走退款流程
- 业户重复提交 → 防重检测