Xboard/.helloagents/archive/2026-04/202604241558_admin-frontend-payment-management/proposal.md

变更提案: admin-frontend-payment-management

元信息

类型: 功能开发
方案类型: implementation
优先级: P1
状态: 进行中
创建: 2026-04-24

---

1. 需求

背景

当前 admin-frontend 的“支付配置”仍是占位页，但 Laravel 后端已经提供 payment/fetch、payment/getPaymentMethods、payment/getPaymentForm、payment/save、payment/show、payment/drop、payment/sort 等完整管理接口。用户本轮明确选择“完整真实 CRUD”方案，并提供了支付列表、编辑抽屉与支付接口下拉截图，要求继续完成支付配置模块。

目标

• 将 #/system/payments 从占位页升级为真实可用的支付配置页面。
• 提供支付方式列表、关键词搜索、启停、新增/编辑、删除与排序能力。
• 抽屉表单按所选支付接口动态拉取配置字段，保持与后端支付插件表单契约一致。
• 视觉上延续 apple/DESIGN.md 与 .helloagents/DESIGN.md 的 Apple 风格后台体系。

约束条件

范围约束: 仅实现支付配置工作台，不扩展插件/主题/知识库等其他系统模块
技术约束: 继续使用 Vue3 + TypeScript + Element Plus，不新增第三方表单或拖拽依赖
业务约束: 后端真实契约以 PaymentController / PaymentService / 插件 form() 返回字段为准，不在前端猜测额外支付字段
数据约束: 排序继续调用 `/payment/sort`；启停继续调用 `/payment/show` 的“切换”语义接口
视觉约束: 延续黑色 hero + 白色工作台 + 克制蓝色交互，保持与现有系统配置/套餐管理同一视觉家族

验收标准

• #/system/payments 可真实拉取支付方式列表，并显示 ID、启用状态、显示名称、支付接口、通知地址与操作列。
• 页面支持关键词搜索，筛选后结果与分页计数同步更新。
• 支持新增与编辑支付方式，字段覆盖显示名称、图标 URL、通知域名、百分比手续费、固定手续费、支付接口与动态支付配置字段。
• 支持启停、删除与排序，并给出明确成功/失败反馈。
• admin-frontend 执行 npm run build 通过。

---

2. 方案

页面结构

1. 延续系统管理页面的 Apple 化后台结构，顶部使用黑色 hero 展示支付概览统计。
2. 主工作区使用白色表格容器，提供“添加支付方式”“搜索支付方式”“编辑排序”三类核心操作。
3. 支付方式编辑采用右侧抽屉，顶层字段集中展示显示名称、图标、通知域名、手续费与支付接口。
4. 抽屉下半区按支付接口动态加载真实配置字段，保持与后端插件 form() 返回结果一致。
5. 排序使用独立对话框，通过上移/下移维护本地顺序，再提交到 /payment/sort。

前端实现策略

1. 在 src/types/api.d.ts 与 src/api/admin.ts 中补齐支付方式列表、动态配置字段与保存载荷类型 / API 封装。
2. 新增 src/utils/payments.ts，集中处理支付方式归一化、关键词过滤、排序移动、手续费展示与动态配置序列化。
3. 新增：
   • src/views/system/SystemPaymentsView.vue
   • src/views/system/SystemPaymentsView.scss
   • src/views/system/SystemPaymentEditorDrawer.vue
   • src/views/system/SystemPaymentEditorDrawer.scss
4. 将 /system/payments 路由切换为真实页面，其余系统管理入口保持现状不动。

影响范围

涉及模块:
  - admin-frontend/src/types: 补齐支付配置相关类型定义
  - admin-frontend/src/api: 新增 payment 管理接口封装
  - admin-frontend/src/utils: 新增支付数据转换、过滤、保存辅助逻辑
  - admin-frontend/src/views/system: 新增支付列表页与编辑抽屉
  - admin-frontend/src/router: 将支付配置路由切换到真实页面
预计变更文件: 8-9

风险评估

| 风险 | 等级 | 应对 | | 后端 /payment/show 是切换型接口，不接受显式目标状态 | 中 | 前端只在用户主动切换时调用一次，并在成功后按目标值更新本地状态 | | 动态支付配置字段完全由插件 form() 返回，前端若自行假设字段会导致保存错位 | 高 | 抽屉内所有支付配置字段均通过 /payment/getPaymentForm 实时拉取，不写死配置项 | | 构建会刷新 public/assets/admin 子模块产物 | 中 | 仅执行 admin-frontend 构建验证，不自动代做子模块发布 |

---

3. 技术设计（可选）

架构设计

flowchart TD
    A[SystemPaymentsView] --> B[admin.ts payment API]
    A --> C[payments.ts]
    A --> D[SystemPaymentEditorDrawer]
    D --> B
    D --> C

API设计

GET /payment/fetch

• 请求: 无
• 响应: AdminPaymentListItem[]

GET /payment/getPaymentMethods

• 请求: 无
• 响应: string[]

POST /payment/getPaymentForm

• 请求: { payment, id? }
• 响应: Record<string, AdminPaymentConfigField>

POST /payment/save

• 请求: { id?, name, icon?, payment, config, notify_domain?, handling_fee_fixed?, handling_fee_percent? }
• 响应: { status, data }

数据模型

字段	类型	说明
id	number	支付方式 ID
payment	string	支付接口代码，如 EPay / TokenPay
name	string	后台显示名称
icon	string | null	图标 URL
notify_domain	string | null	自定义通知域名
notify_url	string | null	后端拼接后的完整通知地址
handling_fee_fixed	number | null	固定手续费
handling_fee_percent	number | null	百分比手续费
enable	boolean	是否启用
config	Record<string, unknown>	支付插件配置对象

---

4. 核心场景

场景: 运营新增支付方式

模块: admin-frontend/system 条件: 管理员已登录，进入 #/system/payments 行为: 点击“添加支付方式”，选择支付接口并填写网关参数后提交 结果: 新支付方式保存成功，列表刷新并展示新记录

场景: 运营切换支付启用状态

模块: admin-frontend/system 条件: 列表中存在可用支付方式 行为: 在列表中切换启用开关 结果: 对应支付方式状态被切换，并在当前列表中即时更新

场景: 运营维护支付排序

模块: admin-frontend/system 条件: 系统中存在多个支付方式 行为: 打开“编辑排序”，调整上下顺序并保存 结果: 后端 /payment/sort 接收新的排序序列，列表刷新为最新顺序

---

5. 技术决策

admin-frontend-payment-management#D001: 支付配置采用“真实列表页 + 动态配置抽屉 + 独立排序对话框”

日期: 2026-04-24 状态: ✅采纳 背景: 用户截图已经明确表达“列表 + 右侧编辑抽屉 + 编辑排序”的后台工作流结构。 选项分析: | 选项 | 优点 | 缺点 | | A: 继续使用占位页 | 改动最小 | 无法完成真实支付配置任务 | | B: 列表页 + 动态配置抽屉 + 排序对话框 | 最贴近截图，也与套餐管理模式一致 | 需要新增更多前端结构与状态管理 | 决策: 选择方案 B 理由: 能同时覆盖用户截图中的真实使用方式与当前 Apple 风格后台架构。 影响: SystemPaymentsView.vue、SystemPaymentEditorDrawer.vue

admin-frontend-payment-management#D002: 支付配置字段完全以后端 /payment/getPaymentForm 为唯一真相源

日期: 2026-04-24 状态: ✅采纳 背景: 各支付插件的配置字段由插件 form() 动态生成，字段集并不固定。 选项分析:

选项	优点	缺点
A: 前端写死常见支付字段	实现快	无法覆盖不同插件，容易与后端表单脱节
B: 每次根据接口动态拉取字段	契约最稳定	需要额外处理加载与切换状态
决策: 选择方案 B
理由: 可同时兼容 EPay、TokenPay、AlipayF2F、Coinbase 等不同插件，不会因为字段假设错误而破坏保存链路。
影响: admin.ts、payments.ts、SystemPaymentEditorDrawer.vue

admin-frontend-payment-management#D003: 支付启停继续沿用现有“切换型接口”，前端做同值短路保护

日期: 2026-04-24 状态: ✅采纳 背景: /payment/show 后端实现是直接反转状态，不接收目标状态。 选项分析:

选项	优点	缺点
A: 前端假设为“设置型接口”并传目标值	交互直觉更强	与后端真实行为不一致，容易在重复事件下错位
B: 前端只做主动点击触发 + 成功后同步本地状态	与现有接口完全对齐	需要额外防止无效 change 事件
决策: 选择方案 B
理由: 能最小代价对齐后端现状，并避免初始化或重复事件导致的误切换。
影响: SystemPaymentsView.vue

---

6. 成果设计

设计方向

• 美学基调: Apple Admin Payments。黑色首屏强调“系统级支付运营台”的沉稳感，正文回到白底高密度工作台，重点突出支付方式与通知链路，而不是营销化装饰。
• 记忆点: 支付配置列表里的“图标 + 名称 + 手续费摘要”组合，与右侧动态配置抽屉形成明显的黑白双层结构。
• 参考: apple/DESIGN.md、.helloagents/DESIGN.md、用户提供的支付列表 / 编辑抽屉 / 支付接口下拉截图

视觉要素

• 配色: 首屏 #000000，页面背景 #f5f5f7，工作区 #ffffff，强调色 #0071e3，危险动作保持 var(--xboard-danger)
• 字体: 延续项目现有系统字体栈，首屏标题保持大字号紧行高，列表和抽屉字段走轻量运营层级
• 布局: Hero + 工具条 + 表格工作台；编辑器采用右侧抽屉，表单上半部为顶层字段，下半部为动态支付配置
• 动效: 仅保留抽屉开合、按钮 hover、排序对话框切换与开关状态变化的轻量动效
• 氛围: 使用克制阴影、圆角白底、胶囊型通知地址与简洁图标预览，不堆叠过多卡片或装饰性标签

技术约束

• 可访问性: 开关、按钮、抽屉表单需保留可见焦点；错误和危险操作不能只靠颜色表达
• 响应式: 桌面优先；窄屏下 hero、工具条、排序对话框和抽屉字段网格需折叠为单列