one-pipe-system/openspec/changes/add-payment-merchant-pool-management/specs/payment-merchant-pool-management/spec.md

Payment Merchant Pool Management Specification

ADDED Requirements

Requirement: 平台专属的商户池管理入口

系统 SHALL 仅向超级管理员和平台用户开放支付商户、商户池及微信授权配置的管理入口和操作。

Scenario: 超级管理员可见并访问

• GIVEN 当前登录账号的 user_type 为 1
• WHEN 用户加载设置菜单或访问 /settings/payment-merchant-pools
• THEN 系统 MUST 展示商户池管理入口并允许进入页面

Scenario: 平台用户可见并访问

• GIVEN 当前登录账号的 user_type 为 2
• WHEN 用户加载设置菜单或访问 /settings/payment-merchant-pools
• THEN 系统 MUST 展示商户池管理入口并允许进入页面

Scenario: 非平台账号被拒绝

• GIVEN 当前登录账号的 user_type 为 3 或 4
• WHEN 用户加载设置菜单或直接输入 /settings/payment-merchant-pools
• THEN 系统 MUST NOT 展示商户池管理入口
• AND 系统 MUST 拒绝直接访问该页面
• AND 系统 MUST NOT 返回商户、商户池或授权配置数据

Requirement: 支付商户管理接口

系统 SHALL 提供支付商户的分页查询、创建、详情、按需更新和删除接口。

Scenario: 查询和筛选支付商户

• WHEN 管理员请求 GET /api/admin/payment-merchants
• THEN 系统 MUST 支持 page、page_size、payment_method 和 enabled 查询参数
• AND payment_method MUST 支持 wechat 和 alipay
• AND 响应中的每个商户 MUST 包含 id、name、payment_method、provider_type、merchant_identity、enabled、remark、credential_version、created_at 和 updated_at

Scenario: 创建支付商户

• WHEN 管理员向 POST /api/admin/payment-merchants 提交 name、payment_method、provider_type、merchant_identity、credentials、enabled 和 remark
• THEN 系统 MUST 创建支付商户并返回新商户记录
• AND provider_type 为 wechat 时 MUST 只接受 wechat、wechat_v2 或 fuiou
• AND provider_type 为 alipay 时 MUST 只接受 alipay

Scenario: 查询支付商户详情

• WHEN 管理员请求 GET /api/admin/payment-merchants/{id}
• THEN 系统 MUST 返回指定商户的详情
• AND 响应 MUST NOT 包含任何支付凭证明文

Scenario: 按需更新和切换商户状态

• WHEN 管理员请求 PUT /api/admin/payment-merchants/{id} 并只提交 enabled
• THEN 系统 MUST 只更新该商户的 enabled 字段
• AND 系统 MUST 保留未提交字段的原值

Scenario: 确认后删除支付商户

• WHEN 管理员请求 DELETE /api/admin/payment-merchants/{id} 并提交 confirm=true
• THEN 系统 MUST 删除目标商户
• AND 前端 MUST 在发送请求前展示二次确认

Requirement: 支付商户列表与启停交互

后台商户管理页 SHALL 展示支付商户状态，并允许有权限的管理员按接口契约切换启用状态。

Scenario: 列表不展示支付凭证

• GIVEN 支付商户列表已加载
• THEN 表格 MUST 展示商户名称、支付方式、服务商类型、商户标识、启停状态、凭证版本、更新时间和备注
• AND 表格、详情弹层和页面状态 MUST NOT 展示 credentials 原始值

Scenario: 切换商户启停状态

• GIVEN 管理员位于支付商户列表
• WHEN 管理员启用或停用一个商户并确认操作
• THEN 前端 MUST 调用 PUT /api/admin/payment-merchants/{id} 提交新的 enabled 值
• AND 成功后 MUST 使用接口结果刷新该商户状态

Requirement: 支付凭证写入与缓存隔离

系统 SHALL 将支付商户凭证视为只写敏感数据，禁止在读取、展示、缓存或日志中保留原始值。

Scenario: 创建时只写凭证

• GIVEN 管理员正在创建支付商户或显式更换凭证
• WHEN 管理员在密码型输入控件中输入凭证并提交
• THEN 前端 MUST 仅在当前表单生命周期内保留凭证输入值
• AND 提交成功、取消、关闭弹层或组件卸载后 MUST 立即清空该值
• AND 系统 MUST NOT 提供查看、复制、下载或历史明文回显能力

Scenario: 读取时不回填凭证

• GIVEN 商户列表或详情接口已返回数据
• WHEN 前端构建页面模型
• THEN 前端 MUST 丢弃 credentials 原始值
• AND 页面 MUST 只展示“已配置/未配置”状态和 credential_version
• AND 前端 MUST NOT 将 credentials 写入 Pinia persisted state、localStorage、sessionStorage、URL、查询参数、日志、埋点或错误上报

Scenario: 接口异常不泄露凭证

• WHEN 创建、更新或删除商户请求失败
• THEN 错误提示和错误上报 MUST NOT 包含请求体中的支付凭证

Requirement: 商户池管理接口

系统 SHALL 提供商户池的分页查询、创建、详情、更新、启用和停用接口。

Scenario: 查询和创建商户池

• WHEN 管理员请求 GET /api/admin/payment-merchant-pools 或创建商户池
• THEN 系统 MUST 返回分页 data 或新建商户池记录
• AND 商户池对象 MUST 支持 id、name、payment_method、member_ids、enabled、strategy、statistic_cycle、threshold_amount、threshold_count、time_period_started_at、time_period_unit、time_period_value、routing_epoch 和 remark
• AND payment_method MUST 支持 wechat 和 alipay

Scenario: 查询和更新商户池详情

• WHEN 管理员请求 GET /api/admin/payment-merchant-pools/{id} 或向同一路径提交 PUT
• THEN 系统 MUST 返回指定商户池详情或保存更新后的商户池
• AND 更新请求 MUST 按创建商户池的字段模型接受可提交字段

Scenario: 启用和停用商户池

• WHEN 管理员请求 POST /api/admin/payment-merchant-pools/{id}/enable
• THEN 系统 MUST 将目标商户池设置为启用状态
• WHEN 管理员请求 POST /api/admin/payment-merchant-pools/{id}/disable
• THEN 系统 MUST 将目标商户池设置为停用状态

Requirement: 商户池成员排序与路由配置

商户池管理页 SHALL 支持可验证的成员排序，并按轮询策略配置对应阈值。

Scenario: 成员顺序按数组顺序保存

• GIVEN 商户池表单中存在多个同支付方式的候选商户
• WHEN 管理员拖拽调整成员顺序并提交
• THEN member_ids MUST 按拖拽后的顺序提交
• AND 系统 MUST 拒绝重复的商户 ID
• AND 更新详情或重新编辑时 MUST 按接口返回的 member_ids 顺序展示

Scenario: 按金额轮换

• GIVEN 管理员选择 strategy=amount
• WHEN 管理员填写金额阈值并提交
• THEN 页面 MUST 使用元作为输入单位并转换为整数分写入 threshold_amount
• AND statistic_cycle MUST 为 round、day 或 month
• AND threshold_amount MUST 为大于零的整数

Scenario: 按笔数轮换

• GIVEN 管理员选择 strategy=count
• WHEN 管理员填写笔数阈值并提交
• THEN 页面 MUST 写入正整数 threshold_count
• AND statistic_cycle MUST 为 round、day 或 month

Scenario: 按时间轮换

• GIVEN 管理员选择 strategy=time
• WHEN 管理员填写时间周期并提交
• THEN time_period_unit MUST 为 minute、hour 或 day
• AND time_period_value MUST 为大于零的整数
• AND 系统 MUST 支持提交 time_period_started_at

Scenario: 路由世代只读

• GIVEN 商户池详情返回 routing_epoch
• THEN 页面 MUST 只读展示该值
• AND 页面 MUST NOT 提供编辑或提交该字段的控件

Requirement: 微信授权配置管理

系统 SHALL 提供当前微信授权配置的读取和保存能力，并允许管理员切换授权配置的启停状态。

Scenario: 读取当前微信授权配置状态

• WHEN 管理员请求 GET /api/admin/wechat-authorizations
• THEN 页面 MUST 展示 enabled、miniapp_app_id、oa_app_id 和 oa_oauth_redirect_url 等非敏感字段
• AND 页面 MUST NOT 回填或展示 miniapp_app_secret、oa_app_secret、oa_token 或 oa_aes_key 的原始值

Scenario: 保存或切换微信授权启停状态

• WHEN 管理员向 PUT /api/admin/wechat-authorizations/current 保存配置
• THEN 请求 MUST 支持 enabled、miniapp_app_id、miniapp_app_secret、oa_app_id、oa_app_secret、oa_token、oa_aes_key 和 oa_oauth_redirect_url
• AND 保存成功后页面 MUST 使用接口结果刷新启停状态
• AND 敏感字段 MUST 只在当前编辑会话内存在，并在保存、取消、关闭或卸载后清空

Scenario: 未更换敏感字段时保留后端原值

• GIVEN 页面只修改 enabled 或其他非敏感字段
• WHEN 管理员提交微信授权配置
• THEN 请求 MUST NOT 使用脱敏占位值覆盖后端已有敏感字段
• AND 页面 MUST NOT 在提交后缓存敏感字段值