# Payment Configuration Management Specification

## ADDED Requirements

### Requirement: 支付渠道类型定义

系统 SHALL 使用统一的 `provider_type` 枚举标识支付渠道主类型。

#### Scenario: 支持文档定义的渠道枚举

- **WHEN** 系统接收或返回支付配置对象的 `provider_type`
- **THEN** 该值 MUST 为 `wechat`、`wechat_v2` 或 `fuiou` 之一

### Requirement: 支付配置字段模型

系统 SHALL 在支付配置的读取和写入契约中支持统一的字段模型。

#### Scenario: 支持基础字段和渠道扩展字段

- **WHEN** 系统处理支付配置对象
- **THEN** 对象 MUST 支持基础字段 `id`、`name`、`description`、`provider_type`、`is_active`、`created_at`、`updated_at`
- **AND** 对象 MUST 支持微信支付字段 `wx_mch_id`、`wx_api_v2_key`、`wx_api_v3_key`、`wx_serial_no`、`wx_notify_url`、`wx_cert_content`、`wx_key_content`
- **AND** 对象 MUST 支持小程序字段 `miniapp_app_id`、`miniapp_app_secret`
- **AND** 对象 MUST 支持公众号字段 `oa_app_id`、`oa_app_secret`、`oa_token`、`oa_aes_key`、`oa_oauth_redirect_url`
- **AND** 对象 MUST 支持支付宝字段 `ali_app_id`、`ali_private_key`、`ali_public_key`、`ali_notify_url`、`ali_return_url`、`ali_pay_expire_minutes`、`ali_production`
- **AND** 对象 MUST 支持富友字段 `fy_api_url`、`fy_ins_cd`、`fy_mchnt_cd`、`fy_term_id`、`fy_notify_url`、`fy_private_key`、`fy_public_key`

### Requirement: 支付配置列表查询

系统 SHALL 提供支付配置列表查询能力，支持分页和条件筛选。

#### Scenario: 查询分页支付配置列表

- **WHEN** 管理员请求 `/api/admin/wechat-configs?page=1&page_size=20`
- **THEN** 系统 MUST 返回包含 `code`、`msg`、`timestamp` 和 `data` 的响应
- **AND** `data` MUST 包含 `items`、`page`、`size`、`total`
- **AND** `page` MUST 从 `1` 开始
- **AND** `page_size` MUST 支持 `1-100` 范围内的请求值
- **AND** `items` 中的每个配置对象 MUST 至少包含 `id`、`name`、`description`、`provider_type`、`is_active`、`created_at`、`updated_at`

#### Scenario: 按支付渠道类型筛选

- **WHEN** 管理员使用 `provider_type=wechat_v2` 查询支付配置列表
- **THEN** 系统 MUST 只返回 `provider_type` 为 `wechat_v2` 的配置

#### Scenario: 按激活状态筛选

- **WHEN** 管理员使用 `is_active=true` 查询支付配置列表
- **THEN** 系统 MUST 只返回当前已激活的支付配置

### Requirement: 创建支付配置

系统 SHALL 允许管理员创建支付配置，并保存与所选渠道相关的字段。

#### Scenario: 创建微信直连支付配置

- **GIVEN** 管理员提交的请求体包含 `name`、`provider_type=wechat`、`wx_mch_id`、`wx_api_v3_key`、`wx_serial_no`、`wx_cert_content`、`wx_key_content`
- **WHEN** 管理员向 `/api/admin/wechat-configs` 发起创建请求
- **THEN** 系统 MUST 创建新的支付配置记录
- **AND** 响应 MUST 返回新建后的支付配置对象
- **AND** 系统 MUST 同时保存请求中提供的可选 `description`、`miniapp_*`、`oa_*`、`ali_*`、`fy_*` 字段

#### Scenario: 缺少基础必填字段时拒绝创建

- **WHEN** 创建请求缺少 `name` 或 `provider_type`
- **THEN** 系统 MUST 拒绝该请求

#### Scenario: 缺少微信直连必填字段时拒绝创建

- **WHEN** 创建请求的 `provider_type=wechat` 且缺少文档要求的微信直连必填字段
- **THEN** 系统 MUST 拒绝该请求

### Requirement: 获取支付配置详情

系统 SHALL 提供按 ID 查询单个支付配置详情的能力。

#### Scenario: 返回完整的支付配置详情

- **WHEN** 管理员请求 `/api/admin/wechat-configs/{id}`
- **THEN** 系统 MUST 返回单个支付配置对象
- **AND** 返回对象 MUST 包含基础字段和所有已支持的渠道扩展字段

### Requirement: 更新支付配置

系统 SHALL 支持按 ID 对支付配置进行部分更新。

#### Scenario: 仅更新提交的字段

- **WHEN** 管理员向 `/api/admin/wechat-configs/{id}` 提交只包含 `name` 的更新请求
- **THEN** 系统 MUST 只更新已提交的字段
- **AND** 系统 MUST 保留未提交字段的原值

#### Scenario: 更新微信密钥和证书字段

- **WHEN** 管理员提交包含 `wx_api_v3_key`、`wx_cert_content`、`wx_key_content` 的更新请求
- **THEN** 系统 MUST 更新目标支付配置对应的字段值

### Requirement: 获取当前生效支付配置

系统 SHALL 提供当前生效支付配置查询能力。

#### Scenario: 返回当前生效的支付配置

- **WHEN** 管理员请求 `/api/admin/wechat-configs/active`
- **THEN** 系统 MUST 返回当前生效的支付配置对象
- **AND** 返回对象中的 `is_active` MUST 等于 `true`
- **AND** 返回对象 MUST 遵循与详情接口一致的字段模型

### Requirement: 敏感字段脱敏与配置状态展示

系统 SHALL 在读取支付配置时保护敏感信息，并使用配置状态标记展示证书和密钥内容。

#### Scenario: 读取响应中的密钥字段必须脱敏

- **WHEN** 系统返回支付配置的读取响应（列表、详情或当前生效配置）
- **THEN** `miniapp_app_secret`、`oa_app_secret`、`oa_token`、`oa_aes_key`、`wx_api_v2_key`、`wx_api_v3_key` MUST 以脱敏值返回
- **AND** 系统 MUST NOT 在读取响应中返回这些字段的明文值

#### Scenario: 证书和私钥字段以配置状态表示

- **WHEN** 系统返回支付配置中的证书或私钥相关字段
- **THEN** `wx_cert_content`、`wx_key_content`、`ali_private_key`、`ali_public_key`、`fy_private_key`、`fy_public_key` MUST 以配置状态值返回
- **AND** 该状态值 MUST 至少能够区分 `已配置` 和 `未配置`