74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# Design: 支付配置管理能力对齐 MVP 文档
|
||
|
||
## Context
|
||
|
||
`docs/mvp/支付配置.md` 已经给出了后台支付配置的接口文档，包括：
|
||
|
||
- 支付配置列表查询
|
||
- 支付配置创建
|
||
- 支付配置详情
|
||
- 支付配置更新
|
||
- 当前生效配置查询
|
||
|
||
但当前仓库没有对应的 OpenSpec 能力说明，现有前端代码也仍沿用 `wechat-config` 命名，容易把“微信配置页面”误读成“仅支持微信支付的页面”。
|
||
|
||
同时，MVP 文档里存在一个需要明确记录的歧义：
|
||
|
||
- `provider_type` 只列出了 `wechat`、`wechat_v2`、`fuiou`
|
||
- 字段模型中又出现了完整的 `ali_*` 支付宝字段组
|
||
|
||
如果不先明确这层假设，后续实现时很容易在 `provider_type` 是否应支持 `alipay` 上出现分叉。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
- Goals:
|
||
- 为支付配置能力建立统一的 OpenSpec 能力边界
|
||
- 把列表、创建、详情、更新和当前生效配置查询的契约写清楚
|
||
- 明确敏感字段脱敏和“已配置/未配置”状态展示语义
|
||
- Non-Goals:
|
||
- 不在本次 spec 中补充文档未描述的删除接口
|
||
- 不在本次 spec 中补充文档未描述的激活/停用写接口
|
||
- 不擅自把 `provider_type` 扩展为文档未枚举的值
|
||
|
||
## Decisions
|
||
|
||
- Decision: 能力名称使用 `payment-configuration-management`，而不是沿用页面路径中的 `wechat-config`
|
||
|
||
- Rationale: 该能力已经覆盖微信、小程序、公众号、支付宝和富友相关字段，业务边界明显大于“微信配置”。
|
||
|
||
- Decision: `provider_type` 在本次 spec 中严格按文档限定为 `wechat`、`wechat_v2`、`fuiou`
|
||
|
||
- Rationale: 这是文档明确枚举出的渠道主类型，spec 不应凭猜测新增 `alipay`。
|
||
|
||
- Decision: `ali_*` 字段在本次 spec 中被视为支付配置对象支持的可选扩展字段，但不单独引入新的 `provider_type`
|
||
|
||
- Rationale: 文档已经明确给出这些字段；在没有更正枚举之前，先把它们作为统一字段模型的一部分记录下来。
|
||
|
||
- Decision: 所有读取响应中的敏感信息都必须采用脱敏或配置状态标记，不能返回明文密钥
|
||
|
||
- Rationale: 文档的详情和当前生效配置示例已经给出了 `***`、`已配置`、`未配置` 这类语义。
|
||
|
||
- Decision: 更新接口采用部分更新语义，只要求提交实际需要修改的字段
|
||
- Rationale: 文档明确说明更新请求“仅传需要修改的字段”，spec 需要保留这个约束。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- 风险: 当前前端类型定义尚未覆盖 `ali_*` 字段，按 spec 对齐后会触发类型和页面联动修改。
|
||
|
||
- Mitigation: 实施时先调整 `src/types/api/wechatConfig.ts`，再逐步修改列表、表单和详情展示。
|
||
|
||
- 风险: 文档没有给出“如何切换当前生效配置”的写接口，只有 `is_active` 状态和 `/active` 查询接口。
|
||
- Mitigation: 本次 spec 仅约束读取和编辑契约，不推断未文档化的激活写流程。
|
||
|
||
## Migration Plan
|
||
|
||
1. 先补齐支付配置类型定义和 API 契约。
|
||
2. 再对齐设置页列表、创建/编辑表单和详情页展示。
|
||
3. 最后核对首页“当前生效支付配置”展示组件是否遵循相同的脱敏语义。
|
||
4. 通过文档示例验证列表、详情、更新和当前生效配置的典型返回结构。
|
||
|
||
## Open Questions
|
||
|
||
- `provider_type` 是否最终应该补充 `alipay`，使其与 `ali_*` 字段组形成一致的一对一渠道语义？
|
||
- 删除、激活、停用接口是否属于正式 MVP 范围，是否需要在后续文档和 spec 中补齐？
|