钱包管理 PRD

文档信息

项目	内容
产品名称	PMForge - 钱包管理
文档版本	v2.0
创建日期	2026-09-20
最后更新	2026-09-24
文档状态	评审中
优先级	P1
所属模块	支付模块（pmforge-module-pay）

修订记录

版本	日期	修订人	修订内容
v1.0	2026-09-24	PMForge 产品团队	初稿
v2.0	2026-09-19	PMForge 产品团队	增强业务场景、验收标准、跨模块联动、名词解释

一、功能概述

1.1 功能定位

钱包管理是 PMForge 支付模块的核心子模块，相当于每个用户在平台里的"零钱账户"。

如果把应用管理（04-01）比作"收银台"，那钱包管理就是用户的"口袋"——用户先把钱装进口袋（充值），然后在平台消费时直接从口袋里掏钱（余额支付），平台给发钱时也是直接往口袋里放（转账/退款）。

核心能力包括：

能力	通俗解释
余额管理	用户的"口袋里有多少钱"，支持查看、调整、冻结
充值	用户从银行卡/微信/支付宝往"口袋"里装钱，充值套餐有赠送
余额消费	用户在平台买东西时直接用"口袋里的钱"付款
交易流水	"口袋"的每一笔进出都有记录，像银行流水一样
充值套餐	运营配置的"充100送20"等促销方案
转账	平台主动给用户打钱（佣金、奖学金等）

钱包模块与应用管理（04-01）深度联动：充值时走应用管理的支付渠道，消费时作为应用管理的一种支付渠道（钱包支付），转账也复用应用管理的渠道配置。

1.2 目标用户

用户角色	核心诉求	使用频率
C端会员用户	便捷充值、安全消费、账单清晰	每日
平台运营人员	快速调账、灵活配置套餐、处理异常	每日
平台财务人员	流水准确、可导出对账、转账可控	每周
企业租户管理员	了解租户内用户钱包状况、管理企业充值	每周
系统管理员	转账渠道配置、资金安全保障	按需

1.3 业务价值

降低交易成本：用户预充值后消费走内部余额扣减，不再每次调用第三方支付，省掉每笔交易的手续费
提升用户留存：用户钱包里有余额，天然增加回访和消费频次；充值赠送进一步刺激充值意愿
资金透明可追溯：每一分钱的变动都有流水记录，用户能查账单，财务能查对账，运营能排查问题
运营工具齐全：后台提供手动调账、冻结钱包、流水导出、套餐管理等工具，减少开发介入
转账打款能力：支持企业向用户打款，覆盖佣金结算、奖学金发放、推广奖励等场景

1.4 功能范围

功能分类	后台管理端	前台用户端
钱包列表与详情	✅	✅（仅本人）
余额调整（调增/调减）	✅	❌
钱包冻结/解冻	✅	❌
钱包流水查询	✅	✅（仅本人）
流水导出	✅	❌
流水按月汇总	❌	✅
充值套餐管理（CRUD）	✅	查看（仅上架套餐）
充值下单	✅（代充）	✅
充值退款	✅	✅（发起退款）
转账订单管理	✅	查看（仅本人）
转账审核	✅	❌
转账渠道配置	✅（复用应用管理）	❌

二、用户场景

2.1 用户角色

角色	典型人物	描述	核心诉求
C端会员	学员小张	平台消费用户	充值方便、到账快、账单看得懂
运营人员	李姐	平台运营管理员	调账高效、套餐灵活、问题定位快
财务人员	老张	资金对账负责人	流水准确、导出规范、转账可控
企业管理员	王总	租户侧管理者	了解企业内用户充值情况
系统管理员	小陈	平台技术管理者	转账渠道配置、资金安全保障

2.2 使用场景

场景1：学员小张充值消费全流程

用户：学员小张（C端会员）

场景：小张在平台学习课程，想充值一些余额方便后续消费。他进入"我的钱包"看到当前余额为 0 元，点击"充值"进入充值页面。页面上展示了几个充值套餐，他选择了"充100送20"套餐。点击"立即充值"后跳转到微信支付，完成支付后页面提示"充值成功，到账120元（含赠送20元）"。回到钱包页面，余额显示 120.00 元。之后小张购买一门课程时选择"余额支付"，系统扣除 50 元，余额变为 70.00 元。他进入"交易记录"页面，能清晰看到充值 120 元和消费 50 元的记录。

期望：充值简单、到账快速、消费记录清晰、月度汇总一目了然。

场景2：运营李姐手动调账

用户：运营李姐

场景：学员反馈充值 100 元但余额只增加了 100 元（应该按套餐赠送 20 元共 120 元）。李姐在后台搜索该用户钱包，查看流水发现确实只有 100 元的充值流水，缺少赠送的 20 元。李姐点击"调整余额"，选择"调增"，输入 20 元，填写原因"充值套餐赠送金额未到账，手动补发"。提交后余额立即增加 20 元，系统自动生成一条"余额调整"流水。李姐通知用户已修复，用户在交易记录中能看到这笔调整。

期望：调账操作简单、有审批痕迹、流水可追溯。

场景3：财务老张月度对账

用户：财务老张

场景：月底老张需要核对钱包资金流水。他进入"钱包流水管理"页面，选择时间范围为本月，流水类型选择"充值"，点击查询。列表展示本月所有充值流水，共 2350 条。老张点击"导出"按钮，下载 Excel 文件。打开 Excel 后核对充值总额与支付渠道账单是否一致，发现差了 0.5 元。通过流水号搜索定位到差异记录，确认是一笔退款导致的时差。核对完成后在报表上签字确认。

期望：数据准确、导出格式规范、支持多维度筛选。

场景4：财务小王发放推广佣金

用户：财务小王

场景：平台推广活动结束，需要给 30 位推广员发放佣金。小王在后台"转账管理"页面批量创建转账订单，选择转账渠道为"微信企业付款"，填写每位推广员的收款账号和金额。提交后订单状态为"等待转账"。小王提交审核，审核通过后系统自动调用微信转账接口。几分钟后陆续收到回调，大部分转账成功，有 1 位推广员因微信账号异常转账失败。小王在转账详情里看到错误信息，联系推广员更新账号后重新发起。

期望：转账可批量、状态可追踪、失败可重试。

场景5：学员小陈查月度账单

用户：学员小陈（C端会员）

场景：小陈想了解自己上个月在平台花了多少钱。他进入"交易记录"页面，选择上个月的时间段。页面顶部显示"本月收入 200.00 元，支出 156.00 元"。下方流水列表展示了每笔交易：充值 100 元、赠送 20 元、购买课程 -50 元、购买课程 -36 元、退款 +30 元……小陈又切换到"只看消费"筛选，清楚看到本月共消费了 3 笔。

期望：数据直观、分类清晰、支持按月份和类型切换。

场景6：运营李姐冻结异常钱包

用户：运营李姐

场景：系统风控告警提示用户 A 的钱包存在异常大额充值。李姐在后台查看该用户钱包，确认存在可疑行为后，点击"冻结"按钮。系统弹出确认框提示"冻结后该用户将无法使用余额消费，但退款仍可入账"。李姐确认后钱包状态变为"冻结"。该用户后续尝试余额支付时，系统提示"钱包已冻结，请联系客服"。调查完毕后，李姐点击"解冻"恢复正常。

期望：冻结操作简单、影响范围明确、解冻即时恢复。

2.3 用户故事与验收标准

US-01：钱包查看

作为 C端会员用户，我希望 在"我的钱包"页面看到我的可用余额、冻结金额、累计充值和累计消费，以便我了解自己的资金状况。

验收标准：

首次访问钱包页面时，系统自动创建钱包，初始余额为 0，页面正常展示
金额展示单位为"元"，保留 2 位小数（如 120.00）
冻结金额单独展示，与可用余额区分
页面加载时间 < 200ms

US-02：充值套餐选择与充值

作为 C端会员用户，我希望 选择充值套餐进行充值并享受赠送，以便获得更多余额。

验收标准：

充值页面仅展示状态为"启用"的套餐，按充值金额从小到大排列
每个套餐展示名称、充值金额、赠送金额（如"充100送20"）
支付成功后，余额增加 = 充值金额 + 赠送金额
充值到账延迟 < 2 秒（从支付成功回调算起）
交易记录中生成一条"充值"流水，金额显示为到账总额

US-03：余额支付

作为 C端会员用户，我希望 在消费时选择余额支付，以便快速完成付款。

验收标准：

余额充足时"余额支付"选项可用，不足时置灰并提示"余额不足"
钱包冻结时"余额支付"不可用，提示"钱包已冻结"
支付成功后余额实时扣减，交易记录中生成一条"消费"流水
同一钱包的并发支付操作通过分布式锁保证不超扣

US-04：后台手动调账

作为运营人员，我希望 手动调整用户钱包余额并记录原因，以便处理充值异常等特殊情况。

验收标准：

支持调增和调减两种操作
调整原因必填，最长 200 字
调减时余额不足则拒绝操作，不允许出现负余额
调整后自动生成"余额调整"类型流水
调整操作记录操作日志（操作人、时间、金额、原因）

US-05：流水查询与导出

作为财务人员，我希望 按条件查询钱包流水并导出 Excel，以便进行月度对账。

验收标准：

支持按用户ID、流水类型、时间范围、金额范围筛选
流水类型包含：充值、充值退款、支付、支付退款、余额调整、转账
导出 Excel 包含：流水号、用户ID、业务类型、变动金额、变动后余额、关联业务ID、说明、创建时间
单次导出不超过 10 万条，超出提示缩小范围
导出文件名格式：钱包流水_YYYYMMDD_HHmmss.xls

US-06：转账管理

作为财务人员，我希望 创建转账订单并跟踪转账状态，以便向用户发放佣金或奖学金。

验收标准：

转账订单创建后状态为"等待转账"
审核通过后系统自动调用渠道发起转账
转账状态实时更新：等待 → 进行中 → 成功/关闭
转账失败时记录错误码和错误信息，支持人工重试
支持导出转账订单 Excel

US-07：月度收支汇总

作为 C端会员用户，我希望 查看每月的收入和支出汇总，以便了解自己的消费情况。

验收标准：

选择月份后展示该月收入合计和支出合计
月份选择范围：最近 12 个月
汇总数据实时计算，与流水明细一致
支持按交易类型筛选（全部/充值/消费/退款/转账/其他）

三、功能需求

3.1 后台管理端 - 钱包管理

3.1.1 钱包列表

描述：展示平台所有用户的钱包信息，支持分页查询和条件筛选。

页面原型：

钱包列表

业务规则：

规则编号	规则描述	设计原因
WAL-001	金额展示单位为"元"，保留 2 位小数；数据库存储单位为"分"	避免浮点精度问题，前端负责转换
WAL-002	用户类型：会员（member）、管理员（admin）	区分不同用户体系的钱包
WAL-003	钱包状态：正常（normal）、冻结（frozen）	支持风控冻结异常钱包
WAL-004	冻结钱包不允许消费，但可以接收退款入账	冻结是限制用户主动消费，不影响平台退款
WAL-005	新用户首次访问钱包页面时自动创建钱包，初始余额为 0	懒加载模式，避免为未使用钱包功能的用户创建无用数据
WAL-006	钱包数据按租户隔离	多租户架构要求

接口列表：

接口名称	请求方式	路径	说明
钱包分页查询	GET	/pay/wallet/page	按条件查询钱包列表
钱包详情查询	GET	/pay/wallet/get	根据用户ID获取钱包详情

3.1.2 钱包详情

描述：查看指定用户的钱包详情，包括余额变动明细和冻结记录。

页面原型：

钱包详情

业务规则：

规则编号	规则描述	设计原因
WAL-007	钱包详情中展示的交易流水按时间倒序排列	最新交易在最前面，便于快速定位
WAL-008	冻结/解冻记录属于流水的一种类型，通过 bizType 区分	统一流水模型，冻结解冻也有据可查

3.1.3 钱包余额调整

描述：后台手动调整用户钱包余额，支持调增和调减，需填写调整原因。

页面原型：

钱包余额调整

业务规则：

规则编号	规则描述	设计原因
WAL-009	调增：余额增加，生成"余额调整"类型流水（bizType=5，price 为正）	调增需有据可查
WAL-010	调减：余额减少，生成"余额调整"类型流水（bizType=5，price 为负）	调减同样需要流水记录
WAL-011	调减时余额不足则拒绝操作，不允许出现负余额	防止资金漏洞
WAL-012	调整操作不可撤销，需通过反向调整实现修正	保留完整操作痕迹，审计需要
WAL-013	所有调整操作记录操作日志，包含操作人、操作时间、调整金额、调整原因	敏感操作必须可追溯
WAL-014	调整金额必须 > 0，单位为元，前端自动转为分	避免 0 元或负数金额的无意义操作

接口列表：

接口名称	请求方式	路径	说明
更新钱包余额	PUT	/pay/wallet/update-balance	手动调整用户余额

3.1.4 钱包冻结/解冻

描述：对异常用户钱包进行冻结，阻止其消费行为；支持解冻恢复正常状态。

业务规则：

规则编号	规则描述	设计原因
WAL-015	冻结状态下钱包不允许进行余额消费	风控需要，阻止异常用户继续消费
WAL-016	冻结状态下仍可接收退款入账	冻结是限制用户主动行为，不影响平台退款义务
WAL-017	冻结/解冻操作记录操作日志	敏感操作可追溯
WAL-018	冻结时需记录冻结原因	便于后续审查和追溯

3.2 后台管理端 - 钱包流水管理

3.2.1 流水列表

描述：展示所有用户的钱包交易流水，支持多维度筛选与分页查询。

页面原型：

钱包流水列表

业务规则：

规则编号	规则描述	设计原因
FLO-001	流水类型枚举：充值(1)、充值退款(2)、支付(3)、支付退款(4)、余额调整(5)、转账(6)	覆盖所有余额变动场景
FLO-002	变动金额（price）：正数表示余额增加，负数表示余额减少	统一用正负号表示方向，简化统计
FLO-003	流水号（no）由系统自动生成，全局唯一	作为流水的唯一标识，便于对账引用
FLO-004	导出 Excel 按当前筛选条件导出，不分页	确保导出数据与查询结果一致
FLO-005	单次导出不超过 10 万条，超出需缩小筛选范围	防止大数据量导出导致系统性能问题

接口列表：

接口名称	请求方式	路径	说明
钱包流水分页	GET	/pay/wallet-transaction/page	按条件查询钱包流水列表

3.2.2 流水导出

描述：将筛选后的流水数据导出为 Excel 文件，用于财务对账。

业务规则：

规则编号	规则描述	设计原因
EXP-001	导出文件名格式：钱包流水_YYYYMMDD_HHmmss.xls	文件名包含时间，便于区分和归档
EXP-002	导出字段：流水号、用户ID、业务类型、变动金额、变动后余额、关联业务ID、说明、创建时间	覆盖对账所需的全部关键字段
EXP-003	金额列以"元"为单位，保留 2 位小数	与财务习惯一致

3.3 后台管理端 - 充值套餐管理

3.3.1 套餐列表

描述：管理平台所有充值套餐，支持查看、创建、编辑、删除、上下架操作。

页面原型：

充值套餐列表

业务规则：

规则编号	规则描述	设计原因
PKG-001	充值金额（payPrice）：用户实际支付的金额	明确用户需要掏多少钱
PKG-002	赠送金额（bonusPrice）：用户额外获得的金额，可为 0	赠送是促销手段，可为 0 表示不赠送
PKG-003	套餐状态：启用(0) / 禁用(1)	支持快速上下架
PKG-004	仅启用状态的套餐在前台用户端可见	禁用后立即对用户不可见
PKG-005	套餐列表在前台按充值金额从小到大排序	低价套餐在前，引导用户先看到低门槛选项
PKG-006	赠送比例超过 50% 时系统给出警告提示	防止运营误操作导致平台亏损

3.3.2 创建/编辑套餐

描述：新增或编辑充值套餐，配置套餐名称、充值金额、赠送金额等信息。

业务规则：

规则编号	规则描述	设计原因
PKG-007	套餐名称不可重复，最长 20 字	避免用户混淆相似套餐
PKG-008	充值金额必须 > 0，最小 0.01 元	金额必须有效
PKG-009	赠送金额 >= 0，默认 0	允许不赠送的套餐
PKG-010	编辑已有套餐不影响已产生的充值记录	历史数据保持原样，修改只影响后续

3.3.3 删除与上下架

业务规则：

规则编号	规则描述	设计原因
PKG-011	删除套餐为逻辑删除，不影响已有充值记录	历史数据可追溯
PKG-012	禁用套餐后，前台不再展示该套餐	快速下架不需要删除数据
PKG-013	已提交但未支付的充值订单如果关联了被禁用的套餐，仍按原套餐金额完成支付	保护用户已发起的充值行为

接口列表：

接口名称	请求方式	路径	说明
创建充值套餐	POST	/pay/wallet-recharge-package/create	新增充值套餐
更新充值套餐	PUT	/pay/wallet-recharge-package/update	编辑充值套餐
删除充值套餐	DELETE	/pay/wallet-recharge-package/delete	删除指定套餐
查询充值套餐详情	GET	/pay/wallet-recharge-package/get	获取单个套餐详情
充值套餐分页查询	GET	/pay/wallet-recharge-package/page	按条件分页查询套餐列表

3.4 后台管理端 - 充值订单管理

3.4.1 充值订单列表

描述：查看用户通过充值套餐或自定义金额发起的充值订单。

业务规则：

规则编号	规则描述	设计原因
RCH-001	充值订单关联支付订单（payOrderId），支付成功后余额才入账	确保"钱到了再给余额"，避免资金风险
RCH-002	充值订单支持退款操作	用户有权申请退款
RCH-003	退款时需同时扣除已入账的余额（含赠送部分）	防止用户通过充值-退款套取赠送金额

3.4.2 充值退款

描述：对已支付成功的充值订单发起退款，退款金额包含赠送部分。

充值退款状态机：

充值退款状态机

业务规则：

规则编号	规则描述	设计原因
RCH-004	退款金额 = 原支付金额（payPrice），通过原支付渠道退回	退用户实际支付的钱
RCH-005	退款时需扣回用户余额中的到账总额（totalPrice = payPrice + bonusPrice）	赠送的钱也要扣回，防止套现
RCH-006	如果用户余额不足以扣回（已消费部分），拒绝退款	防止资金亏损
RCH-007	退款状态流转：未退款(0) → 退款中 → 退款成功(10) / 退款失败(20)	与支付模块退款状态机一致

接口列表：

接口名称	请求方式	路径	说明
充值支付回调	POST	/pay/wallet-recharge/update-paid	支付成功后内部回调更新状态
发起充值退款	POST	/pay/wallet-recharge/refund	对指定充值订单发起退款
退款结果回调	POST	/pay/wallet-recharge/update-refunded	退款成功后内部回调更新状态

3.5 后台管理端 - 转账管理

3.5.1 转账订单列表

描述：查看平台所有转账订单，支持按状态、应用、渠道、时间等条件筛选。

页面原型：

转账订单列表

转账状态机：

转账状态机

业务规则：

规则编号	规则描述	设计原因
TRF-001	转账状态：等待(0)、进行中(5)、成功(10)、关闭(20)	覆盖转账全生命周期
TRF-002	转账单号由系统自动生成，全局唯一	唯一标识，便于追踪和对账
TRF-003	仅"等待转账"状态的订单可审核	防止重复审核
TRF-004	审核通过后自动调用转账渠道发起转账	审核通过即执行，减少人工操作
TRF-005	审核拒绝后订单状态变为"转账关闭"	明确标记被拒绝的订单
TRF-006	转账渠道复用支付渠道管理模块（pay_channel）	复用已有渠道配置，避免重复建设
TRF-007	转账失败时记录渠道错误码和错误信息	便于排查问题和重试
TRF-008	支持导出 Excel，文件名格式：转账订单_YYYYMMDD_HHmmss.xls	满足财务对账需求

接口列表：

接口名称	请求方式	路径	说明
转账订单详情	GET	/pay/transfer/get	获取指定转账订单详情
转账订单分页	GET	/pay/transfer/page	按条件分页查询转账订单
导出转账订单	GET	/pay/transfer/export-excel	导出转账订单Excel

3.6 用户前台 - 我的钱包

3.6.1 余额展示

描述：用户查看自己的钱包余额、冻结金额、累计充值、累计消费。

页面原型：

我的钱包余额展示

业务规则：

规则编号	规则描述	设计原因
APP-001	首次访问自动创建钱包（懒加载模式）	避免为未使用钱包功能的用户创建无用数据
APP-002	金额展示单位为"元"，保留 2 位小数	用户友好的展示方式
APP-003	冻结金额单独展示，不可用于消费	让用户清楚知道哪些钱不能用

接口列表：

接口名称	请求方式	路径	说明
获取钱包信息	GET	/pay/wallet/get	获取当前登录用户的钱包信息

3.7 用户前台 - 钱包充值

3.7.1 选择充值套餐/自定义金额

描述：用户选择预定义充值套餐或输入自定义充值金额进行充值。

页面原型：

钱包充值页面

业务规则：

规则编号	规则描述	设计原因
APP-004	仅展示状态为"启用"的充值套餐	禁用的套餐不应对用户可见
APP-005	自定义金额最小 0.01 元，最大不超过平台限额（可配置）	防止异常金额
APP-006	自定义金额不享受赠送	赠送是套餐专属权益

3.7.2 选择支付方式与充值结果

描述：用户选择支付方式完成充值付款，支付完成后展示充值结果。

业务规则：

规则编号	规则描述	设计原因
APP-007	充值订单创建后关联统一支付订单（payOrder）	复用支付模块的订单管理能力
APP-008	支付成功后通过回调更新充值订单状态，并增加用户余额	确保"钱到了再给余额"
APP-009	到账金额 = 支付金额 + 赠送金额	用户实际获得的余额
APP-010	充值成功展示到账金额和赠送金额；充值失败展示失败原因	给用户明确的反馈
APP-011	充值结果页提供"查看交易明细"快捷入口	方便用户确认到账

接口列表：

接口名称	请求方式	路径	说明
创建充值订单	POST	/pay/wallet-recharge/create	创建钱包充值记录
充值记录分页	GET	/pay/wallet-recharge/page	获取当前用户的充值记录

3.8 用户前台 - 余额消费

3.8.1 余额支付

描述：用户在平台消费时选择余额支付，直接从钱包扣款。

业务规则：

规则编号	规则描述	设计原因
APP-012	余额充足时方可使用余额支付	防止透支
APP-013	冻结钱包不可进行余额支付	风控要求
APP-014	余额支付通过内部钱包支付客户端（WalletPayClient）实现	内部扣款不走第三方支付渠道
APP-015	支付金额单位为"元"，系统自动转换为"分"处理	前后端统一使用元，内部用分计算
APP-016	支付成功后生成 bizType=PAYMENT(3) 的流水记录	每笔消费有据可查

3.8.2 混合支付

描述：用户消费时可组合使用余额 + 其他支付渠道完成支付。

业务规则：

规则编号	规则描述	设计原因
APP-017	余额部分优先扣减	先扣内部余额，再走外部渠道
APP-018	各渠道支付金额之和等于订单总额	确保金额一致
APP-019	若其他渠道支付失败，余额部分需回退	保证支付一致性，不能出现余额扣了但订单没付成功
APP-020	混合支付的退款需按原路退回	余额部分退回余额，外部渠道部分退回外部渠道

3.9 用户前台 - 交易记录

3.9.1 收支明细

描述：用户查看自己钱包的所有交易流水，按时间倒序展示。

页面原型：

交易记录页面

业务规则：

规则编号	规则描述	设计原因
APP-021	收入类（充值、充值退款、支付退款、余额调增、转账收入）展示为正数，绿色	直观区分收入支出
APP-022	支出类（支付、余额调减）展示为负数，红色	红色代表支出，符合用户习惯
APP-023	默认展示最近一个月的交易明细	用户最常查看的时间范围
APP-024	默认分页大小：20 条	移动端每屏展示合理数量

3.9.2 按类型筛选与按月汇总

描述：用户可按交易类型筛选查看特定类型的流水，并查看指定月份的收入和支出汇总数据。

业务规则：

规则编号	规则描述	设计原因
APP-025	支持筛选的类型：全部、充值、消费、退款、转账、其他	覆盖用户关心的分类维度
APP-026	切换筛选时重置页码	避免筛选后页码越界
APP-027	按月汇总统计收入总额和支出总额	帮助用户了解月度消费情况
APP-028	月份选择范围：最近 12 个月	覆盖一年的查看需求
APP-029	汇总数据实时计算	确保数据准确

接口列表：

接口名称	请求方式	路径	说明
交易流水分页	GET	/pay/wallet-transaction/page	获取当前用户的交易流水
获取流水统计	GET	/pay/wallet-transaction/get-summary	按时间段获取收支汇总
充值套餐列表	GET	/pay/wallet-recharge-package/list	获取所有启用的充值套餐

四、非功能需求

4.1 性能需求

指标	要求	说明
钱包查询响应时间	单次查询 < 200ms	用户打开钱包页面的等待时间
余额变更操作	单笔操作 < 500ms（含流水记录写入）	充值、消费、调账等操作的响应时间
充值到账延迟	支付回调后 < 2 秒到账	用户支付完成后看到余额增加的时间
流水查询性能	支持单用户 10 万条流水记录的分页查询，响应 < 500ms	长期用户的流水量可能很大
并发处理	同一用户钱包的并发操作通过 Redis 分布式锁保证数据一致性	防止同一钱包同时被多个操作修改导致余额错误
流水导出	10 万条数据导出 < 30 秒	财务月末导出场景
对账统计	按月汇总统计 < 1 秒	用户查看月度汇总的响应时间

4.2 安全需求

安全项	要求	实现方式
余额变更一致性	所有余额变更操作必须在数据库事务内完成	Spring @Transactional，余额更新 + 流水写入在同一事务
并发安全	防止同一钱包并发操作导致余额错误	Redis 分布式锁（PayWalletLockRedisDAO），锁粒度为钱包 ID
金额计算精度	避免浮点精度问题	系统内部以"分"为单位整数计算，展示时转为"元"
操作审计	敏感操作必须记录操作日志	余额调整、冻结/解冻操作写入操作日志表
权限控制	不同操作需对应权限标识	后台接口基于 RBAC 权限模型，前台接口基于登录态
防重放	防止重复提交	充值订单和转账订单均有唯一商户单号
数据隔离	多租户数据隔离	所有数据表包含 tenant_id 字段
转账安全	大额转账需审核	转账操作需审核流程，审核通过后才发起

4.3 兼容性需求

兼容项	要求
数据库兼容	支持 MySQL、PostgreSQL、Oracle、Kingbase、DB2、H2 等数据库
主键策略	通过 @KeySequence 注解适配不同数据库的主键自增策略
多端适配	前台用户端支持 H5、小程序、APP 等多端访问
接口规范	后台接口遵循 RESTful 规范，前台接口兼容移动端调用
金额单位	数据库统一以"分"存储，前端展示以"元"为单位，精度 2 位小数

五、数据设计

5.1 数据模型概览

本模块涉及 5 张数据表，关系如下：

钱包数据模型ER图

5.2 pay_wallet 钱包表

字段名	类型	必填	默认值	说明
id	bigint	是	自增	主键ID
user_id	bigint	是	-	用户ID，关联会员用户或管理员用户
user_type	tinyint	是	-	用户类型：1-会员 2-管理员
balance	int	是	0	可用余额，单位分
freeze_price	int	是	0	冻结金额，单位分
total_expense	int	是	0	累计支出，单位分
total_recharge	int	是	0	累计充值，单位分
creator	varchar(64)	否	NULL	创建者
create_time	datetime	是	CURRENT_TIMESTAMP	创建时间
updater	varchar(64)	否	NULL	更新者
update_time	datetime	是	CURRENT_TIMESTAMP	更新时间
deleted	bit(1)	是	0	逻辑删除：0-未删除 1-已删除
tenant_id	bigint	是	0	租户ID

索引设计：

索引名	类型	字段	说明
PRIMARY	主键	id	自增主键
uk_user_id_type	唯一	user_id, user_type, tenant_id	同一租户下同一用户类型唯一钱包
idx_tenant_id	普通	tenant_id	租户维度查询

5.3 pay_wallet_transaction 钱包流水表

字段名	类型	必填	默认值	说明
id	bigint	是	自增	主键ID
no	varchar(64)	是	-	流水号，全局唯一
wallet_id	bigint	是	-	钱包ID，关联 pay_wallet.id
biz_type	tinyint	是	-	业务类型：1-充值 2-充值退款 3-支付 4-支付退款 5-余额调整 6-转账
biz_id	varchar(64)	是	-	关联业务编号（充值订单ID、支付订单ID等）
title	varchar(256)	否	NULL	流水说明
price	int	是	-	交易金额，单位分；正值为余额增加，负值为余额减少
balance	int	是	-	交易后余额，单位分
creator	varchar(64)	否	NULL	创建者
create_time	datetime	是	CURRENT_TIMESTAMP	创建时间
updater	varchar(64)	否	NULL	更新者
update_time	datetime	是	CURRENT_TIMESTAMP	更新时间
deleted	bit(1)	是	0	逻辑删除
tenant_id	bigint	是	0	租户ID

索引设计：

索引名	类型	字段	说明
PRIMARY	主键	id	自增主键
uk_no	唯一	no	流水号唯一
idx_wallet_id	普通	wallet_id	按钱包查流水
idx_biz_type_id	普通	biz_type, biz_id	按业务类型和编号查流水
idx_create_time	普通	create_time	按时间范围查流水
idx_tenant_id	普通	tenant_id	租户维度查询

5.4 pay_wallet_recharge_package 充值套餐表

字段名	类型	必填	默认值	说明
id	bigint	是	自增	主键ID
name	varchar(64)	是	-	套餐名称
pay_price	int	是	-	支付金额，单位分
bonus_price	int	是	0	赠送金额，单位分
status	tinyint	是	0	状态：0-启用 1-禁用
creator	varchar(64)	否	NULL	创建者
create_time	datetime	是	CURRENT_TIMESTAMP	创建时间
updater	varchar(64)	否	NULL	更新者
update_time	datetime	是	CURRENT_TIMESTAMP	更新时间
deleted	bit(1)	是	0	逻辑删除
tenant_id	bigint	是	0	租户ID

索引设计：

索引名	类型	字段	说明
PRIMARY	主键	id	自增主键
idx_status	普通	status	按状态筛选
idx_tenant_id	普通	tenant_id	租户维度查询

5.5 pay_wallet_recharge 充值订单表

字段名	类型	必填	默认值	说明
id	bigint	是	自增	主键ID
wallet_id	bigint	是	-	钱包ID，关联 pay_wallet.id
package_id	bigint	否	NULL	充值套餐ID，自定义充值时为 NULL
pay_price	int	是	-	实际支付金额，单位分
bonus_price	int	是	0	赠送金额，单位分
total_price	int	是	-	用户实际到账金额（pay_price + bonus_price），单位分
pay_order_id	bigint	否	NULL	支付订单ID，关联 pay_order.id
pay_channel_code	varchar(32)	否	NULL	支付成功的支付渠道编码
pay_status	bit(1)	是	0	是否已支付：0-未支付 1-已支付
pay_time	datetime	否	NULL	支付成功时间
pay_refund_id	bigint	否	NULL	退款单ID，关联 pay_refund.id
refund_total_price	int	否	0	退款总金额（含赠送），单位分
refund_pay_price	int	否	0	退款支付金额，单位分
refund_bonus_price	int	否	0	退款赠送金额，单位分
refund_time	datetime	否	NULL	退款时间
refund_status	tinyint	否	0	退款状态
creator	varchar(64)	否	NULL	创建者
create_time	datetime	是	CURRENT_TIMESTAMP	创建时间
updater	varchar(64)	否	NULL	更新者
update_time	datetime	是	CURRENT_TIMESTAMP	更新时间
deleted	bit(1)	是	0	逻辑删除
tenant_id	bigint	是	0	租户ID

索引设计：

索引名	类型	字段	说明
PRIMARY	主键	id	自增主键
idx_wallet_id	普通	wallet_id	按钱包查充值记录
idx_pay_order_id	普通	pay_order_id	按支付订单查充值
idx_pay_status	普通	pay_status	按支付状态筛选
idx_tenant_id	普通	tenant_id	租户维度查询

5.6 pay_transfer 转账订单表

字段名	类型	必填	默认值	说明
id	bigint	是	自增	主键ID
no	varchar(64)	是	-	转账单号，全局唯一
app_id	bigint	是	-	应用编号，关联 pay_app.id
channel_id	bigint	否	NULL	转账渠道编号，关联 pay_channel.id
channel_code	varchar(32)	否	NULL	转账渠道编码
user_id	bigint	否	NULL	用户编号
user_type	tinyint	否	NULL	用户类型
merchant_transfer_id	varchar(64)	是	-	商户转账单编号，应用内唯一
subject	varchar(128)	否	NULL	转账标题
price	int	是	-	转账金额，单位分
user_account	varchar(128)	否	NULL	收款人账号
user_name	varchar(64)	否	NULL	收款人姓名
status	tinyint	是	0	转账状态：0-等待 5-进行中 10-成功 20-关闭
success_time	datetime	否	NULL	转账成功时间
notify_url	varchar(1024)	否	NULL	异步通知地址
user_ip	varchar(64)	否	NULL	用户IP
channel_extras	json	否	NULL	渠道额外参数
channel_transfer_no	varchar(128)	否	NULL	渠道转账单号
channel_error_code	varchar(64)	否	NULL	渠道错误码
channel_error_msg	varchar(512)	否	NULL	渠道错误信息
channel_notify_data	text	否	NULL	渠道通知内容
channel_package_info	text	否	NULL	渠道package信息（微信专用）
creator	varchar(64)	否	NULL	创建者
create_time	datetime	是	CURRENT_TIMESTAMP	创建时间
updater	varchar(64)	否	NULL	更新者
update_time	datetime	是	CURRENT_TIMESTAMP	更新时间
deleted	bit(1)	是	0	逻辑删除
tenant_id	bigint	是	0	租户ID

索引设计：

索引名	类型	字段	说明
PRIMARY	主键	id	自增主键
uk_no	唯一	no	转账单号唯一
uk_app_merchant	唯一	app_id, merchant_transfer_id	应用内商户单号唯一，防重复提交
idx_channel_id	普通	channel_id	按渠道查转账
idx_status	普通	status	按状态筛选
idx_create_time	普通	create_time	按时间范围查
idx_tenant_id	普通	tenant_id	租户维度查询

5.7 数据字典

5.7.1 钱包流水业务类型

枚举值	编号	说明	金额方向
RECHARGE	1	充值 - 用户通过支付渠道充值到账	正（余额增加）
RECHARGE_REFUND	2	充值退款 - 充值订单退款后扣回余额	负（余额减少）
PAYMENT	3	支付 - 用户使用余额进行消费	负（余额减少）
PAYMENT_REFUND	4	支付退款 - 消费退款后余额回退	正（余额增加）
UPDATE_BALANCE	5	余额调整 - 后台手动调增/调减	正或负
TRANSFER	6	转账 - 通过转账入账	正（余额增加）

5.7.2 转账状态

枚举值	编号	说明	后续流转
WAITING	0	等待转账 - 订单已创建，等待审核或发起	→ 进行中 / 关闭
PROCESSING	5	转账进行中 - 已调用渠道接口，等待结果	→ 成功 / 关闭
SUCCESS	10	转账成功 - 渠道确认转账完成	终态
CLOSED	20	转账关闭 - 转账失败或审核拒绝	终态

5.7.3 充值退款状态

枚举值	编号	说明	后续流转
未退款	0	退款单已创建，等待处理	→ 退款成功 / 退款失败
退款成功	10	渠道已确认退款到账	终态
退款失败	20	渠道退款处理失败	可重试 → 退款成功

六、跨模块联动

6.1 联动模块一览

联动模块	联动方式	数据流向	说明
应用管理（04-01）	充值走支付渠道	钱包 → 应用管理	充值时创建支付订单，通过应用管理的支付渠道收款
应用管理（04-01）	钱包支付作为渠道	应用管理 ← 钱包	用户消费选择余额支付时，钱包模块作为 WalletPayClient 扣减余额
应用管理（04-01）	转账走支付渠道	钱包 → 应用管理	转账时复用应用管理的渠道配置发起转账
会员管理（05-01）	钱包归属用户	钱包 → 会员	钱包通过 user_id + user_type 关联会员用户
会员积分（05-02）	充值送积分	钱包 → 会员积分	充值成功后可触发赠送积分/经验值（通过事件机制）
通知模块	充值/转账通知	钱包 → 通知	充值到账、转账成功等关键节点发送站内通知
日志审计（01-08）	操作日志	钱包 → 日志	余额调整、冻结/解冻等敏感操作写入操作日志
定时任务	回调补偿	定时任务 → 钱包	定时任务（PayNotifyJob）主动查询未确认的支付/转账结果

6.2 关键联动流程

6.2.1 充值到账全流程

充值到账全流程

6.2.2 余额消费全流程

余额消费全流程

6.2.3 充值退款全流程

充值退款全流程

6.3 数据一致性要求

场景	一致性要求	实现方式
充值到账	余额增加 + 流水写入 + 充值订单更新必须同时成功	数据库事务 + 分布式锁
余额消费	余额扣减 + 流水写入必须同时成功	数据库事务 + 分布式锁
充值退款	余额扣回 + 流水写入 + 退款状态更新必须同时成功	数据库事务 + 分布式锁
手动调账	余额变更 + 流水写入 + 操作日志必须同时成功	数据库事务
转账	转账状态更新 + 流水写入必须同时成功	数据库事务

七、附录

7.1 名词解释

名词	通俗解释
钱包（Wallet）	用户在平台里的"零钱账户"，类似微信零钱或支付宝余额
钱包流水（Wallet Transaction）	钱包的"银行流水"，每一笔进出都有记录，方便查账
充值套餐（Recharge Package）	运营配置的"充X送Y"促销方案，类似"充100送20"
充值订单（Wallet Recharge）	用户充值时生成的订单，记录充了多少钱、赠送多少、用什么方式付的
转账订单（Transfer）	平台给用户打钱的记录，类似公司给你发工资的转账记录
冻结金额（Freeze Price）	被"冻住"的钱，看得到但用不了，类似银行冻结账户
赠送金额（Bonus Price）	充值套餐额外送的钱，类似"买100送20"里的那个20
业务类型（Biz Type）	流水的"分类标签"，告诉你这笔钱是因为充值、消费还是调账产生的
分布式锁	防止"两个人同时操作同一个钱包"导致数据出错的机制，类似排队叫号
逻辑删除	数据不真正删掉，只是标记为"已删除"，保证历史记录可追溯
余额调整	运营人员手动给用户加钱或扣钱，处理异常情况用的
混合支付	一部分用余额、一部分用微信/支付宝的支付方式组合
懒加载	用户第一次打开钱包页面时才创建钱包，而不是注册时就创建
对账	财务核对平台流水和第三方支付渠道账单是否一致的过程
回调（Callback）	第三方支付渠道（微信/支付宝）在支付完成后主动通知平台的方式
租户隔离	不同企业（租户）的数据互相看不到，保证数据安全

7.2 权限标识

权限标识	说明	所属功能
pay:wallet:query	查看钱包（含钱包列表、详情、流水查询）	钱包管理
pay:wallet:update-balance	调整钱包余额	钱包管理
pay:wallet-recharge-package:create	创建充值套餐	充值套餐
pay:wallet-recharge-package:update	编辑充值套餐	充值套餐
pay:wallet-recharge-package:delete	删除充值套餐	充值套餐
pay:wallet-recharge-package:query	查看充值套餐	充值套餐
pay:transfer:query	查看转账订单	转账管理
pay:transfer:export	导出转账订单	转账管理

7.3 接口汇总

7.3.1 后台管理端接口

序号	接口名称	请求方式	路径	权限标识	说明
1	钱包详情	GET	/pay/wallet/get	pay:wallet:query	按用户ID获取钱包信息
2	钱包分页	GET	/pay/wallet/page	pay:wallet:query	分页查询钱包列表
3	调整余额	PUT	/pay/wallet/update-balance	pay:wallet:update-balance	手动调增/调减用户余额
4	流水分页	GET	/pay/wallet-transaction/page	pay:wallet:query	分页查询钱包流水
5	充值回调	POST	/pay/wallet-recharge/update-paid	PermitAll（内部调用）	支付成功回调更新充值状态
6	充值退款	POST	/pay/wallet-recharge/refund	pay:wallet:update-balance	对充值订单发起退款
7	退款回调	POST	/pay/wallet-recharge/update-refunded	PermitAll（内部调用）	退款成功回调更新状态
8	创建充值套餐	POST	/pay/wallet-recharge-package/create	pay:wallet-recharge-package:create	新增充值套餐
9	更新充值套餐	PUT	/pay/wallet-recharge-package/update	pay:wallet-recharge-package:update	编辑充值套餐
10	删除充值套餐	DELETE	/pay/wallet-recharge-package/delete	pay:wallet-recharge-package:delete	删除充值套餐
11	充值套餐详情	GET	/pay/wallet-recharge-package/get	pay:wallet-recharge-package:query	获取单个充值套餐
12	充值套餐分页	GET	/pay/wallet-recharge-package/page	pay:wallet-recharge-package:query	分页查询充值套餐
13	转账订单详情	GET	/pay/transfer/get	pay:transfer:query	获取指定转账订单
14	转账订单分页	GET	/pay/transfer/page	pay:transfer:query	分页查询转账订单
15	导出转账订单	GET	/pay/transfer/export-excel	pay:transfer:export	导出转账订单Excel

7.3.2 前台用户端接口

序号	接口名称	请求方式	路径	鉴权	说明
1	获取钱包	GET	/pay/wallet/get	登录态	获取当前用户钱包信息
2	创建充值订单	POST	/pay/wallet-recharge/create	登录态	发起钱包充值
3	充值记录分页	GET	/pay/wallet-recharge/page	登录态	查询当前用户充值记录
4	充值套餐列表	GET	/pay/wallet-recharge-package/list	登录态	获取所有启用的充值套餐
5	交易流水分页	GET	/pay/wallet-transaction/page	登录态	查询当前用户交易流水
6	交易流水统计	GET	/pay/wallet-transaction/get-summary	登录态	按时间段获取收支汇总

7.4 错误码

错误码	说明	处理建议
WALLET_NOT_EXISTS	钱包不存在	首次访问时自动创建钱包
WALLET_FROZEN	钱包已冻结	提示用户联系客服解冻
WALLET_BALANCE_NOT_ENOUGH	余额不足	提示用户充值或选择其他支付方式
WALLET_BALANCE_NEGATIVE	余额不能为负	调减操作被拒绝，提示余额不足
WALLET_LOCK_FAILED	获取钱包锁失败	系统繁忙，请稍后重试
RECHARGE_ORDER_NOT_FOUND	充值订单不存在	检查订单ID是否正确
RECHARGE_ORDER_PAID	充值订单已支付	不允许重复支付
RECHARGE_ORDER_REFUNDED	充值订单已退款	不允许重复退款
RECHARGE_REFUND_BALANCE_NOT_ENOUGH	退款时用户余额不足	用户已消费部分金额，无法全额退款
TRANSFER_ORDER_NOT_FOUND	转账订单不存在	检查转账单号是否正确
TRANSFER_STATUS_ERROR	转账状态异常	仅等待状态的订单可审核
PACKAGE_NAME_DUPLICATE	套餐名称重复	修改套餐名称后重试
PACKAGE_PRICE_INVALID	套餐金额无效	充值金额必须 > 0，赠送金额 >= 0

7.5 异常处理策略

异常场景	处理策略
充值回调丢失	定时任务（PayNotifyJob）主动查询支付结果
并发余额操作	Redis 分布式锁串行执行，避免超卖/超扣
退款时余额不足	拒绝退款操作，提示用户余额不足（已消费部分无法退款）
转账渠道超时	转账订单保持"进行中"状态，定时任务同步结果
转账渠道失败	记录错误信息，订单状态变为"转账关闭"，支持人工重试
流水与余额不一致	对账任务定期检查，发现差异时告警

钱包管理 PRD ​

文档信息 ​

修订记录 ​

一、功能概述 ​

1.1 功能定位 ​

1.2 目标用户 ​

1.3 业务价值 ​

1.4 功能范围 ​

二、用户场景 ​

2.1 用户角色 ​

2.2 使用场景 ​

场景1：学员小张充值消费全流程 ​

场景2：运营李姐手动调账 ​

场景3：财务老张月度对账 ​

场景4：财务小王发放推广佣金 ​

场景5：学员小陈查月度账单 ​

场景6：运营李姐冻结异常钱包 ​

2.3 用户故事与验收标准 ​

US-01：钱包查看 ​

US-02：充值套餐选择与充值 ​

US-03：余额支付 ​

US-04：后台手动调账 ​

US-05：流水查询与导出 ​

US-06：转账管理 ​

US-07：月度收支汇总 ​

三、功能需求 ​

3.1 后台管理端 - 钱包管理 ​

3.1.1 钱包列表 ​

3.1.2 钱包详情 ​

3.1.3 钱包余额调整 ​

3.1.4 钱包冻结/解冻 ​

3.2 后台管理端 - 钱包流水管理 ​

3.2.1 流水列表 ​

3.2.2 流水导出 ​

3.3 后台管理端 - 充值套餐管理 ​

3.3.1 套餐列表 ​

3.3.2 创建/编辑套餐 ​

3.3.3 删除与上下架 ​

3.4 后台管理端 - 充值订单管理 ​

3.4.1 充值订单列表 ​

3.4.2 充值退款 ​

3.5 后台管理端 - 转账管理 ​

3.5.1 转账订单列表 ​

3.6 用户前台 - 我的钱包 ​

3.6.1 余额展示 ​

3.7 用户前台 - 钱包充值 ​

3.7.1 选择充值套餐/自定义金额 ​

3.7.2 选择支付方式与充值结果 ​

3.8 用户前台 - 余额消费 ​

3.8.1 余额支付 ​

3.8.2 混合支付 ​

3.9 用户前台 - 交易记录 ​

3.9.1 收支明细 ​

3.9.2 按类型筛选与按月汇总 ​

四、非功能需求 ​

4.1 性能需求 ​

4.2 安全需求 ​

4.3 兼容性需求 ​

五、数据设计 ​

5.1 数据模型概览 ​

5.2 pay_wallet 钱包表 ​

5.3 pay_wallet_transaction 钱包流水表 ​

5.4 pay_wallet_recharge_package 充值套餐表 ​

5.5 pay_wallet_recharge 充值订单表 ​

5.6 pay_transfer 转账订单表 ​

5.7 数据字典 ​

5.7.1 钱包流水业务类型 ​

5.7.2 转账状态 ​

5.7.3 充值退款状态 ​

六、跨模块联动 ​

6.1 联动模块一览 ​

6.2 关键联动流程 ​

6.2.1 充值到账全流程 ​

6.2.2 余额消费全流程 ​

6.2.3 充值退款全流程 ​

6.3 数据一致性要求 ​

七、附录 ​

7.1 名词解释 ​

7.2 权限标识 ​

7.3 接口汇总 ​

钱包管理 PRD

文档信息

修订记录

一、功能概述

1.1 功能定位

1.2 目标用户

1.3 业务价值

1.4 功能范围

二、用户场景

2.1 用户角色

2.2 使用场景

场景1：学员小张充值消费全流程

场景2：运营李姐手动调账

场景3：财务老张月度对账

场景4：财务小王发放推广佣金

场景5：学员小陈查月度账单

场景6：运营李姐冻结异常钱包

2.3 用户故事与验收标准

US-01：钱包查看

US-02：充值套餐选择与充值

US-03：余额支付

US-04：后台手动调账

US-05：流水查询与导出

US-06：转账管理

US-07：月度收支汇总

三、功能需求

3.1 后台管理端 - 钱包管理

3.1.1 钱包列表

3.1.2 钱包详情

3.1.3 钱包余额调整

3.1.4 钱包冻结/解冻

3.2 后台管理端 - 钱包流水管理

3.2.1 流水列表

3.2.2 流水导出

3.3 后台管理端 - 充值套餐管理

3.3.1 套餐列表

3.3.2 创建/编辑套餐

3.3.3 删除与上下架

3.4 后台管理端 - 充值订单管理

3.4.1 充值订单列表

3.4.2 充值退款

3.5 后台管理端 - 转账管理

3.5.1 转账订单列表

3.6 用户前台 - 我的钱包

3.6.1 余额展示

3.7 用户前台 - 钱包充值

3.7.1 选择充值套餐/自定义金额

3.7.2 选择支付方式与充值结果

3.8 用户前台 - 余额消费

3.8.1 余额支付

3.8.2 混合支付

3.9 用户前台 - 交易记录

3.9.1 收支明细

3.9.2 按类型筛选与按月汇总

四、非功能需求

4.1 性能需求

4.2 安全需求

4.3 兼容性需求

五、数据设计

5.1 数据模型概览

5.2 pay_wallet 钱包表

5.3 pay_wallet_transaction 钱包流水表

5.4 pay_wallet_recharge_package 充值套餐表

5.5 pay_wallet_recharge 充值订单表

5.6 pay_transfer 转账订单表

5.7 数据字典

5.7.1 钱包流水业务类型

5.7.2 转账状态

5.7.3 充值退款状态

六、跨模块联动

6.1 联动模块一览

6.2 关键联动流程

6.2.1 充值到账全流程

6.2.2 余额消费全流程

6.2.3 充值退款全流程

6.3 数据一致性要求

七、附录

7.1 名词解释

7.2 权限标识

7.3 接口汇总