SOP-301：钱包充值工作流测试

支持复制到 Excel 的标准 SOP 模板；每个 任务（Task ID） 表示一个可打卡的子文档，便于人工/机器按照序号完成并记录进度。

文档元数据

• 文档类型：SOP / Checklist
• 适用场景：http://localhost:3000/crm/customer 客户管理界面 + 钱包充值流程
• 工作流：钱包充值（资金池余额转入钱包）
• 创建者：QA / 自动化工程
• 最近更新时间：2025-12-23
• 配置文件：wallet_transfer_prod.yaml
• 相关接口定义：crm.swagger.json 中 WalletService 模块

业务说明

钱包充值流程：钱包充值是将客户资金池的余额转入钱包的过程。充值后，资金池余额减少，钱包余额增加，客户总资金保持不变。钱包充值需要经过财务审批才能生效。

关键概念： - 资金池余额：客户账户中可用于分配的资金总额 - 钱包：与客户关联的独立资金账户，用于广告投放等业务 - 钱包充值：从资金池转移资金到指定钱包的操作 - 政策标签：可选的折扣率标签，影响实际消耗的资金池金额 - 审批流程：媒介审批 → 生效

工作流程图

graph LR
    A[发起申请] --> B[媒介审批]
    B --> C[审批通过]
    C --> D[生效]

审批角色

步骤	审批人	说明
媒介审批	媒介人员	媒介确认充值申请，审批通过后资金从资金池转入钱包

前置条件

条件	检查方式
本地或测试环境可访问 http://localhost:3000/crm/customer	浏览器打开，页面未返回 500/404
已使用有客户管理权限的用户登录	登录接口/前端登录流程成功，能加载左侧导航
测试客户准备就绪	确认客户列表中存在可用的测试客户
客户至少有一个钱包	钱包列表中存在该客户的钱包（通过 /api/v1/wallets?customer_id={customerId} 查询）
客户资金池有余额	客户资金池余额 > 0（充值金额不能超过资金池余额）
媒介审批人可用	媒介人员账号可登录，用于审批工作流

重要说明

钱包充值的核心前提条件：

1. 客户必须已经创建至少一个钱包
2. 代码逻辑：wallet-recharge-button.tsx 调用 loadWalletOptions('name', search, true, customer?.id)
3. API 查询：/api/v1/wallets?customer_id={customerId} 只返回该客户拥有的钱包

4. 如果客户没有钱包，API 返回空数组 []，导致下拉框无选项

5. 钱包必须处于可用状态

6. 钱包ID不能为 0

7. 钱包名称不能为空字符串

8. 如何创建钱包

9. 方式1：访问钱包管理页面 /crm/wallet，为客户创建新钱包
10. 方式2：在广告账户管理中，通过认领钱包的方式关联到客户

钱包政策标签说明

政策标签的作用和逻辑：

1. 政策标签的作用
2. 政策标签用于记录钱包充值时的折扣率

3. 示例：如果政策标签折扣率为10%，充值100元电子币，实际消耗资金池余额为90.91元（100÷1.1）

4. 政策标签数据来源

5. 政策标签来自钱包数据中的 policyLabels 字段（API: /api/v1/wallets）

6. 当用户选择钱包后，系统自动从该钱包的 policyLabels 加载政策标签选项

7. 显示逻辑（代码位置：wallet-recharge-button.tsx 第111-130行） typescript const policyLabels = Array.isArray(walletPolicyLabels) ? walletPolicyLabels.map((x: any) => { const percent = Math.round(x.discount * 10000) / 100; return { label: x.name + '(' + percent.toFixed(2) + '%)', value: x.id, discount: x.discount } }) : [];

8. 如果钱包有政策标签：下拉框显示"选择政策标签"，可选择标签（格式：标签名称(折扣%)）
9. 如果钱包没有政策标签：下拉框显示"暂无政策标签"（灰色不可选）

10. 未选择钱包时：下拉框显示"选择政策标签"

11. 选择要求

12. 政策标签字段是 可选字段（nullable），可以不选择
13. 如果不选择政策标签，充值金额=资金池消耗金额（没有折扣）

14. 如果选择政策标签，充值金额=资金池消耗金额×(1+折扣率)

15. 折扣计算示例

16. 假设选择折扣率10%的政策标签
17. 充值金额：100元
18. 资金池消耗：100 ÷ 1.1 = 90.91元
19. 电子币到账：100元

任务矩阵（Excel Checklist 行模板）

每个任务独立一个表格，依次执行并记录状态；状态列可直接粘贴到 Excel 以打勾 [ ] → [x]。

任务 T1：环境与账号验证

入口：http://localhost:3000/crm/customer

Action Steps	Input / Payload	预期结果	验证方式	证据	状态	下游任务
步骤1：打开浏览器	—	浏览器启动成功	浏览器窗口打开	屏幕截图	[ ]	步骤 2
步骤2：输入 URL	http://localhost:3000/crm/customer	页面开始加载	地址栏显示正确 URL	屏幕截图	[ ]	步骤 3
步骤3：登录	账号/密码	登录成功，跳转到主页	左侧导航栏显示	屏幕截图、浏览器日志	[ ]	步骤 4
步骤4：导航到「客户」	点击左侧「客户」菜单或直接访问客户页面	页面成功加载、显示客户列表表格、无 500 错误	UI：存在标题「客户列表」、表格；Console：无错误	屏幕截图、浏览器日志	[ ]	T2

图1：客户列表页面，显示所有客户及其资金状态

任务 T2：打开客户详情并记录初始状态

前置条件：T1 成功且当前在客户列表页面

Action Steps	Input / Payload	预期结果	验证方式	证据	状态	下游任务
步骤1：点击客户简称	点击目标客户（如"ceshi"或"测试"）	客户详情drawer从右侧滑出	drawer成功打开，显示客户基本信息	屏幕截图	[ ]	步骤 2
步骤2：验证drawer内容	查看客户详情信息	显示资金池余额、挂账余额、垫款余额等信息	drawer显示完整资金信息和操作按钮	屏幕截图	[ ]	步骤 3
步骤3：记录初始资金状态	记录：资金池余额、挂账余额、垫款余额	成功记录客户初始资金状态	资金池余额 > 0	文本记录	[ ]	T3

图2：客户列表展开后显示更多资金信息列

图3：客户详情drawer打开，显示资金池信息和操作按钮

初始状态示例： - 资金池：￥300.00 - 挂账：￥0.00 - 垫款：￥0.00

任务 T3：选择钱包并填写充值信息

前置条件：T2 成功，客户详情drawer已打开

Action Steps	Input / Payload	预期结果	验证方式	证据	状态	下游任务
步骤1：点击「钱包充值」按钮	—	钱包充值对话框打开	对话框显示，标题为「钱包充值」，显示客户名称、资金池余额、钱包余额	屏幕截图	[ ]	步骤 2
步骤2：点击钱包下拉框	—	下拉框打开，显示该客户的钱包列表	显示钱包列表，每个钱包显示名称和余额	屏幕截图	[ ]	步骤 3
步骤3：选择目标钱包	选择钱包（如：南京每悦-代运营）	钱包成功选择，下拉框显示所选钱包	钱包信息正确显示	屏幕截图	[ ]	步骤 4
步骤4：填写充值金额	输入充值金额（如：100）	充值金额成功输入	输入框显示金额，金额验证通过	屏幕截图	[ ]	步骤 5
步骤5：选择政策标签（可选）	选择钱包政策标签或跳过	政策标签成功选择或跳过	如有政策标签，下拉框显示标签列表	屏幕截图	[ ]	T4

图4：钱包充值对话框，显示资金池余额和钱包余额

图5：钱包选择下拉框（本例中客户暂无钱包）

注意事项： - 如果显示"没有选项被找到"，说明该客户还没有钱包，需要先创建钱包 - 充值金额必须 ≤ 资金池余额 - 充值金额必须 > 0 - 支持小数点后两位

任务 T4：提交充值申请并查看工作流

前置条件：T3 成功，充值信息已填写

Action Steps	Input / Payload	预期结果	验证方式	证据	状态	下游任务
步骤1：检查填写信息	验证钱包、金额、政策标签	所有必填信息已填写且正确	视觉检查表单完整性	屏幕截图	[ ]	步骤 2
步骤2：点击「充值」按钮	—	提交成功，显示成功提示	显示"提交成功"对话框	屏幕截图	[ ]	步骤 3
步骤3：导航到工作流列表	点击左侧「工作流」菜单	工作流列表页面加载	页面显示工作流列表	屏幕截图	[ ]	步骤 4
步骤4：查找钱包充值工作流	在列表顶部查找刚提交的工作流	找到"钱包充值"工作流	工作流状态显示为"审核中"	屏幕截图	[ ]	步骤 5
步骤5：查看工作流详情	点击工作流行，查看详细信息	显示工作流详情	详情包含：工作流ID、发起人、发起时间、充值金额、客户信息、钱包信息	屏幕截图	[ ]	T5

图6：工作流列表页面，可以看到各种工作流及其状态

任务 T5：媒介审批并验证充值结果

前置条件：T4 成功，钱包充值工作流已创建

注意：此任务需要切换到媒介人员账号进行审批操作。

Action Steps	Input / Payload	预期结果	验证方式	证据	状态	下游任务
步骤1：切换媒介账号	使用媒介人员账号登录	登录成功	左侧导航显示，能看到"与我有关"选项	屏幕截图	[ ]	步骤 2
步骤2：进入待审批工作流	工作流 -> 与我有关	显示待审批的钱包充值工作流	列表中显示待审批工作流	屏幕截图	[ ]	步骤 3
步骤3：查看充值申请详情	点击工作流，审查充值信息	显示完整充值信息：客户、钱包、金额	信息完整且正确	屏幕截图	[ ]	步骤 4
步骤4：点击「通过」按钮	点击审批通过，可选填写审批意见	审批成功，工作流状态更新为"已完成"	显示"审批成功"提示	屏幕截图	[ ]	步骤 5
步骤5：验证资金池余额变化	回到客户列表，查看客户资金池余额	资金池余额 = 初始余额 - 充值金额	客户详情显示更新后的资金池余额	屏幕截图	[ ]	步骤 6
步骤6：验证钱包余额变化	导航到钱包模块，查看目标钱包余额	钱包余额 = 初始余额 + 充值金额	钱包列表显示更新后的钱包余额	屏幕截图	[ ]	—

图7：钱包列表页面，显示所有钱包及其余额信息

余额验证公式：

充值前资金池余额 - 充值金额 = 充值后资金池余额
充值前钱包余额 + 充值金额 = 充值后钱包余额

示例数据： - 充值前资金池：￥300.00 - 充值前钱包：￥0.00 - 充值金额：￥100.00 - 充值后资金池：￥200.00 - 充值后钱包：￥100.00

进度采集模板（机器辅助/人手填报）

Task ID	Status	Evidence	Operator	Timestamp	Notes
T1	[ ] / [x]	screen-T1.png	qa-bot	2025-12-22T09:00:00	"登录成功，客户列表加载"
T2	[ ] / [x]	screen-T2.png	qa-zhang	2025-12-22T09:02:00	"客户详情打开，初始资金状态已记录"
T3	[ ] / [x]	screen-T3.png	qa-zhang	2025-12-22T09:04:00	"钱包已选择，充值金额已填写"
T4	[ ] / [x]	screen-T4.png	qa-zhang	2025-12-22T09:06:00	"充值申请已提交，工作流已创建"
T5	[ ] / [x]	screen-T5.png	qa-media	2025-12-22T09:10:00	"媒介审批通过，余额已验证"

Tip：监控系统可定时读取 Task ID + Status 列；每次 status 变更都写入对应 Evidence 和 Timestamp 以供追踪。

关键验证点

1. 权限检查
2. 只有具有客户管理权限的用户可以发起充值申请

3. 只有媒介人员可以审批充值申请

4. 金额验证

5. 充值金额必须大于0
6. 充值金额不能超过资金池余额

7. 支持小数点后两位

8. 工作流状态

9. 提交后：等待审批
10. 审批通过后：已完成

11. 审批拒绝后：已拒绝

12. 余额一致性

13. 资金池余额减少 = 钱包余额增加

14. 客户总资金保持不变

15. 钱包匹配性

16. 钱包必须属于该客户
17. 钱包的所属公司必须与客户的主体公司匹配

测试数据示例

成功案例

钱包充值请求：

{
  "customerId": 123,
  "walletId": 56624775,
  "amount": 100.00,
  "policyLabelId": null
}

预期响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "flowId": 12345,
    "flowUrl": "/crm/workflow/12345"
  }
}

余额变化： | 项目 | 充值前 | 充值后 | 变化 | |------|--------|--------|------| | 资金池余额 | ￥300.00 | ￥200.00 | -￥100.00 | | 钱包余额 | ￥0.00 | ￥100.00 | +￥100.00 | | 客户总资金 | ￥300.00 | ￥300.00 | ￥0.00 |

失败案例

案例一：客户无钱包 - 前置条件：客户没有创建任何钱包 - 操作：尝试打开钱包充值对话框并选择钱包 - 预期：钱包下拉框显示"没有选项被找到"，无法继续操作 - 解决方案：先在钱包模块为客户创建钱包

案例二：充值金额超过资金池余额

{
  "customerId": 123,
  "walletId": 56624775,
  "amount": 500.00
}

• 前置条件：客户资金池余额为￥300.00
• 预期：API 返回 400 错误，提示"充值金额不能超过资金池余额"

案例三：无效的钱包ID

{
  "customerId": 123,
  "walletId": 99999999,
  "amount": 100.00
}

• 预期：API 返回 404 错误，提示"钱包不存在"或"钱包不属于该客户"

案例四：媒介审批拒绝 - 操作：媒介人员查看充值申请后点击"拒绝" - 预期：工作流状态更新为"已拒绝"，资金池和钱包余额均不变

相关 SOP 文档

• SOP-201：资金池充值
• SOP-203：垫款充值
• SOP-302：钱包退款
• SOP-401：广告账户充值
• CRM 操作手册 - 客户模块
• 工作流全流程调整
• 配置文件：wallet_transfer_prod.yaml

异常与恢复

• 页面未加载：确认后端服务运行 gateway + core；查看浏览器 Console、Network 500/401；记录 Request ID 并换账号重试。
• 客户详情drawer无法打开：检查客户ID是否有效；刷新页面重试；查看Console错误日志。
• 钱包下拉框显示"没有选项被找到"：说明该客户还没有钱包，需要先在钱包模块为客户创建钱包；或在广告账户管理中认领钱包到该客户。
• 充值金额验证失败：检查充值金额是否超过资金池余额；确认充值金额大于0；检查金额格式（最多两位小数）。
• 提交充值申请失败：记录 toast 错误、截图；检查钱包ID是否有效；查看API响应错误信息；确认客户资金池余额充足。
• 政策标签无法选择：确认钱包是否配置了政策标签；政策标签字段为可选，可以不选择。
• 工作流未创建：检查后端工作流服务是否正常；确认配置文件 wallet_transfer_prod.yaml 是否正确部署；查看后端日志。
• 媒介审批异常：检查媒介账号和权限；确认工作流状态正确；查看工作流日志和错误信息。
• 余额未更新：确认审批流程已完成；刷新页面重新查看；检查后端余额更新逻辑和事务是否正常执行。

API 参考（必须遵循的接口）

接口	方法	说明	关键字段 & 数据格式
/api/v1/wallet/transfer	POST	发起钱包充值申请	body 需要包含： - customerId（integer）：客户 ID - walletId（integer）：钱包 ID - amount（number）：充值金额 - policyLabelId（integer，可选）：政策标签 ID
/api/v1/wallets	GET	获取钱包列表	可通过 customer_id 参数筛选客户的钱包 返回：钱包ID、名称、余额、政策标签列表等
/api/v1/customer/{customerId}	GET	获取客户详情	返回客户信息，包含资金池余额、挂账余额、垫款余额等
/api/v1/workflows	GET	工作流列表	获取工作流列表，可通过 type 参数筛选钱包充值工作流
/api/v1/workflows/{workflowId}	GET	工作流详情	获取工作流详细信息，包含审批历史、当前状态等
/api/v1/workflows/{workflowId}/approve	POST	审批工作流	body 需要包含： - action（string）：approve/reject - comment（string，可选）：审批意见

参见完整定义：crm.swagger.json 中 WalletService 模块

钱包充值请求字段说明

字段名	类型	必填	说明
customerId	integer	是	客户 ID
walletId	integer	是	钱包 ID（必须属于该客户）
amount	number	是	充值金额（必须 > 0 且 ≤ 资金池余额）
policyLabelId	integer	否	政策标签 ID（可选，用于折扣计算）

钱包充值响应示例

成功响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "flowId": 12345,
    "flowUrl": "/crm/workflow/12345"
  }
}

失败响应：

{
  "code": 400,
  "message": "充值金额不能超过资金池余额",
  "data": null
}

附录：Checklist 导出格式

Task ID,Task Name,Status,Evidence,Operator,Notes
T1,环境与账号验证,[ ],screen-T1.png,qa-bot,"login ok, customer list loaded"
T2,打开客户详情并记录初始状态,[ ],screen-T2.png,qa-zhang,"customer drawer opened, initial balance recorded"
T3,选择钱包并填写充值信息,[ ],screen-T3.png,qa-zhang,"wallet selected, amount filled"
T4,提交充值申请并查看工作流,[ ],screen-T4.png,qa-zhang,"transfer request submitted, workflow created"
T5,媒介审批并验证充值结果,[ ],screen-T5.png,qa-media,"media approved, balance verified"

直接复制上述 CSV/Excel 内容可实现标准化追踪。

修订历史

版本	日期	修改人	修改内容
1.0	2025-12-22	QA Team	初始版本
1.1	2025-12-23	QA Team	按照 SOP-101 格式添加任务矩阵、进度采集模板、API 参考、CSV 导出格式

---

文档状态: ✅ 已完成 最后更新: 2025-12-23