---
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 小程序微信付]]