Files
Xboard/.helloagents/archive/2026-04/202604241553_admin-frontend-plugin-management/plan.md
T
yinjianm f7cef30b9c feat(admin-frontend): 完成订阅与系统管理真实工作台
补齐订单、优惠券、主题、插件、公告与支付管理页面,
接入对应后台接口、路由入口与工具层类型定义。
同时修复套餐页开关初始化误写问题,避免浏览即触发写操作。

在订阅协议侧为 Stash 导出增加 AnyTLS 版本守卫,
未知版本或低于 3.3.0 时不再导出该协议,并补充回归测试与知识记录。
2026-04-24 16:52:41 +08:00

4.4 KiB
Raw Blame History

admin-frontend 插件管理首版交付 — 实施规划

目标与范围

  • #/system/plugins 从占位页升级为真实插件管理页面。
  • 本轮范围聚焦“单页工作台 + 详情抽屉”模型:列表承担检索、筛选和高频动作,抽屉承担 README、配置与补充说明。
  • 其余系统管理子页保持现状,不借本轮需求扩展其他模块。

架构与实现策略

  • admin-frontend/src/api/admin.tssrc/types/api.d.ts 中补齐插件管理接口和类型定义,保证所有页面动作都走真实后端契约。
  • 新增 src/utils/plugins.ts,集中处理插件类型文案、状态判断、筛选、README 渲染与配置表单值序列化,避免视图组件堆积逻辑。
  • /system/plugins 路由替换为独立的 PluginManagementView.vue,继续保留黑色 hero + 白色工作台层次,首屏承载搜索、类型切换、状态筛选、上传入口与运营摘要。
  • 新增 PluginDetailDrawer.vue 作为插件详情工作台:
    • 左侧 / 顶部展示插件基本信息与状态
    • 中部切换 README / 配置两个视图
    • 配置基于后端返回的动态 schema 渲染,不额外臆造字段
  • 列表卡片提供高频动作按钮:
    • 未安装:安装
    • 已安装未启用:启用、卸载
    • 已启用:禁用
    • 可升级:升级
    • 受保护 / 核心插件:明确显示保护边界,避免危险误操作

完成定义

  • #/system/plugins 能真实拉取插件列表,并按类型 / 状态 / 关键词筛选。
  • 页面支持上传 zip 插件包,并在上传成功后刷新列表。
  • 管理员可以对插件执行安装、启用、禁用、升级、卸载动作,并获得明确成功 / 失败反馈。
  • 详情抽屉可查看 README 和插件基础信息;对存在配置 schema 的插件,可读取并保存配置。
  • 验证主路径:review-first
  • reviewer 关注边界:
    • 插件管理首屏是否与现有 Apple 风格后台一致,且不像占位页
    • 列表动作优先级、危险按钮和受保护插件边界是否清晰
    • 详情抽屉的 README / 配置双视图是否足够清楚
  • tester 关注边界:
    • /plugin/getPlugins/plugin/upload/plugin/install/plugin/enable/plugin/disable/plugin/uninstall/plugin/upgrade 是否都已接入真实数据流
    • 插件配置读取 / 保存是否真实命中 /plugin/config
    • 搜索、类型切换、状态筛选是否真实影响渲染结果

文件结构

  • admin-frontend/src/router/index.ts
  • admin-frontend/src/api/admin.ts
  • admin-frontend/src/types/api.d.ts
  • admin-frontend/src/utils/plugins.ts(新增)
  • admin-frontend/src/views/system/PluginManagementView.vue(新增)
  • admin-frontend/src/views/system/PluginManagementView.scss(新增)
  • admin-frontend/src/views/system/PluginDetailDrawer.vue(新增)

UI / 设计约束

  • 首屏延续当前系统管理模块的黑色 hero,右侧摘要卡片改为“插件总数 / 已启用 / 可升级 / 用户上传”等运营信息。
  • 列表采用大卡片而不是传统密表格,强调插件名称、类型、版本、作者、描述与状态标签,贴近用户截图的阅读方式。
  • 顶部筛选区使用轻量 segmented control + select + search 组合,不引入多层复杂过滤器。
  • 配置表单要兼容 boolean / string / text / json / select 等基础字段类型,字段说明与 placeholder 保持可见。
  • README 区域使用真实 Markdown 渲染,保留代码块、列表和标题层级。

风险与验证

  • 风险 1:后端返回的插件配置 schema 是动态结构,前端需要兼容多种字段类型与空配置插件。
  • 风险 2getPlugins 已带部分配置和 README,但已安装插件的配置需要保证与 /plugin/config 拉取一致,避免抽屉内旧数据。
  • 风险 3:本地环境缺少真实登录态时,无法做完整浏览器联调;需要用 build + 代码级结构自检给出本轮 UI 验收结论。
  • 验证方式:
    • npm run build
    • 对构建产物与代码结构做 UI 自检,确认搜索、筛选、卡片操作与抽屉视图均已真实连接数据流

决策记录

  • [2026-04-24] D001:插件管理采用“卡片列表 + 详情抽屉”,不回退到纯表格,兼顾截图风格和后台可操作性。
  • [2026-04-24] D002:配置编辑采用动态 schema 渲染,不为单个插件写死字段。
  • [2026-04-24] D003README 与配置合并进同一个详情工作台,避免列表页信息密度失控。