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

ADDED Requirements

Requirement: 商户池详情入口

系统 SHALL 与支付商户保持一致，以点击列表中商户池名称的方式进入独立详情页，并且不再在行操作中提供“详情”入口。

Scenario: 点击商户池名称进入详情页

• GIVEN 管理员位于支付商户与商户池管理页的“商户池”页签
• WHEN 管理员点击列表中某个商户池名称
• THEN 系统 MUST 跳转到该商户池的详情页
• AND 详情页 MUST 通过 GET /api/admin/payment-merchant-pools/{id} 加载数据
• AND 列表行操作 MUST NOT 再提供“详情”操作

Scenario: 商户池名称以可点击样式展示

• GIVEN 商户池列表加载成功
• WHEN 页面渲染商户池名称列
• THEN 商户池名称 MUST 以可点击样式展示
• AND 点击名称 MUST NOT 触发表格行选中或其他行操作

Scenario: 非平台账号不能查看商户池详情

• GIVEN 当前登录账号的 user_type 不是 1 或 2
• WHEN 用户点击商户池名称或直接访问商户池详情页地址
• THEN 系统 MUST NOT 展示商户池详情数据
• AND 路由 MUST 按平台账号限制拦截该访问

Requirement: 商户池详情信息完整

系统 SHALL 在商户池详情页展示详情接口返回的全部业务字段，并 SHALL 以支付商户名称展示成员商户，不得展示 id 或 member_ids 原始标识。

Scenario: 展示轮询策略与阈值字段

• GIVEN 管理员进入某个商户池详情页
• WHEN 详情数据加载成功
• THEN 详情 MUST 展示商户池名称、支付方式、启停状态、轮询策略、路由世代和备注
• AND strategy 为 amount 或 count 时 MUST 展示统计周期和对应阈值
• AND strategy 为 time 时 MUST 展示时间单位、时间长度和时间起点

Scenario: 成员商户按名称展示

• GIVEN 商户池详情返回 member_ids
• WHEN 页面展示成员信息
• THEN 页面 MUST 展示成员商户名称和成员数量
• AND 页面 MUST NOT 展示 member_ids 原始 ID
• AND 成员名称无法解析时 MUST 展示“未知商户”而不是 ID

Scenario: 未返回的字段不渲染

• GIVEN 商户池详情接口未返回创建时间或更新时间
• WHEN 页面展示商户池详情
• THEN 页面 MUST NOT 渲染对应字段的空白行

Requirement: 商户池成员顺序单一数据源

系统 SHALL 使用单一数据源维护商户池成员顺序，保证新增、编辑和拖拽排序成员时不会出现递归更新错误，并且提交顺序与页面展示顺序一致。

Scenario: 新增商户池不再递归更新

• WHEN 管理员点击“新增商户池”
• THEN 系统 MUST NOT 抛出 Maximum recursive updates exceeded
• AND 表单 MUST 正常打开并允许选择成员

Scenario: 拖拽后按展示顺序提交

• GIVEN 商户池表单中存在多个成员商户
• WHEN 管理员拖拽调整成员顺序并提交
• THEN member_ids MUST 按拖拽后的顺序提交
• AND 再次编辑该商户池时 MUST 按提交顺序展示成员

Requirement: 商户凭证字段枚举契约

系统 SHALL 按 payment_method 与 provider_type 组合枚举商户凭证的必填键与可选键，并在提交前校验字段枚举、必填键、值类型与商户标识一致性。

字段枚举以后端契约为准（键名与渠道配置字段一致），前端必须与后端保持一致，后端新增或调整字段时需同步更新前端枚举。credentials MUST 为扁平 JSON 对象，必填键为：

• payment_method=wechat、provider_type=wechat：wx_mch_id、wx_api_v3_key、wx_cert_content、wx_key_content、wx_serial_no、wx_notify_url
• payment_method=wechat、provider_type=wechat_v2：wx_mch_id、wx_api_v2_key、wx_notify_url
• payment_method=wechat、provider_type=fuiou：fy_mchnt_cd、fy_ins_cd、fy_term_id、fy_private_key、fy_public_key、fy_api_url、fy_notify_url
• payment_method=alipay、provider_type=alipay：ali_app_id、ali_private_key、ali_public_key、ali_notify_url、ali_return_url

可选键为：wechat 可附 wx_api_v2_key；alipay 可附 ali_production（布尔，是否生产环境）与 ali_pay_expire_minutes（整数，支付过期分钟数）。除 ali_production 与 ali_pay_expire_minutes 外，凭证值 MUST 为字符串。merchant_identity MUST 分别等于 wx_mch_id、fy_mchnt_cd 或 ali_app_id。

Scenario: 提交微信直连凭证

• GIVEN 管理员提交 payment_method=wechat、provider_type=wechat 的商户凭证
• THEN 请求 MUST 包含 wx_mch_id、wx_api_v3_key、wx_cert_content、wx_key_content、wx_serial_no、wx_notify_url
• AND 请求 MAY 附带 wx_api_v2_key
• AND merchant_identity MUST 等于 wx_mch_id

Scenario: 提交微信直连 V2 凭证

• GIVEN 管理员提交 payment_method=wechat、provider_type=wechat_v2 的商户凭证
• THEN 请求 MUST 包含 wx_mch_id、wx_api_v2_key、wx_notify_url
• AND merchant_identity MUST 等于 wx_mch_id

Scenario: 提交富友凭证

• GIVEN 管理员提交 payment_method=wechat、provider_type=fuiou 的商户凭证
• THEN 请求 MUST 包含 fy_mchnt_cd、fy_ins_cd、fy_term_id、fy_private_key、fy_public_key、fy_api_url、fy_notify_url
• AND merchant_identity MUST 等于 fy_mchnt_cd

Scenario: 提交支付宝凭证

• GIVEN 管理员提交 payment_method=alipay、provider_type=alipay 的商户凭证
• THEN 请求 MUST 包含 ali_app_id、ali_private_key、ali_public_key、ali_notify_url、ali_return_url
• AND 请求 MAY 附带 ali_production 与 ali_pay_expire_minutes
• AND merchant_identity MUST 等于 ali_app_id

Scenario: 缺少必填字段时拒绝提交

• WHEN 提交的凭证缺少当前服务商组合的必填键
• THEN 前端 MUST 阻止提交并提示缺失的凭证字段名

Scenario: 拒绝不属于当前服务商的凭证字段

• WHEN 提交的凭证包含必填键与可选键之外的字段名
• THEN 前端 MUST 阻止提交并提示该字段不属于当前服务商支持的字段

Scenario: 校验凭证值类型

• GIVEN 凭证包含 ali_production 或 ali_pay_expire_minutes
• WHEN 管理员提交凭证
• THEN ali_production MUST 以布尔值提交
• AND ali_pay_expire_minutes MUST 以正整数提交
• AND 其余凭证字段 MUST 以字符串提交

Scenario: 校验商户标识一致性

• WHEN merchant_identity 与 wx_mch_id、fy_mchnt_cd 或 ali_app_id 的值不一致
• THEN 前端 MUST 阻止提交并提示商户标识必须与对应凭证字段一致

Requirement: 商户凭证访问控制

系统 SHALL 仅允许超级管理员（user_type=1）与平台用户（user_type=2）读取和写入商户凭证，且凭证内容 MUST NOT 进入日志、审计记录或支付快照。

Scenario: 平台账号可读写凭证

• GIVEN 当前登录账号的 user_type 为 1 或 2
• WHEN 账号打开支付商户管理页、支付商户详情页或提交商户凭证
• THEN 系统 MUST 允许读取凭证配置状态与写入凭证

Scenario: 非平台账号不可读写凭证

• GIVEN 当前登录账号的 user_type 为 3 或 4
• WHEN 账号访问支付商户管理页或支付商户详情页
• THEN 系统 MUST 拒绝访问并 MUST NOT 返回凭证字段或凭证状态
• AND 页面 MUST NOT 渲染凭证写入入口

Scenario: 凭证不写入日志与快照

• WHEN 创建、更新或删除支付商户成功或失败
• THEN 凭证内容 MUST NOT 出现在浏览器存储、页面日志、错误上报或支付快照中
• AND 页面 MUST 只展示“已配置/未配置”状态与 credential_version