feat(admin-frontend): 完成订阅与系统管理真实工作台

补齐订单、优惠券、主题、插件、公告与支付管理页面，接入对应后台接口、路由入口与工具层类型定义。同时修复套餐页开关初始化误写问题，避免浏览即触发写操作。在订阅协议侧为 Stash 导出增加 AnyTLS 版本守卫，未知版本或低于 3.3.0 时不再导出该协议，并补充回归测试与知识记录。
2026-04-24 16:52:41 +08:00
parent 16203b14f6
commit f7cef30b9c
89 changed files with 11122 additions and 92 deletions
@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 5,
+  "failed": 0,
+  "pending": 0,
+  "total": 5,
+  "done": 5,
+  "percent": 100,
+  "current": "插件管理工作台、详情抽屉与构建验证已完成",
+  "updated_at": "2026-04-24 16:12:00"
+}
@@ -0,0 +1,51 @@
+{
+  "updatedAt": "2026-04-24T07:55:29.737Z",
+  "version": 1,
+  "source": "manual",
+  "originCommand": "plugin-management-r2",
+  "verifyMode": "review-first",
+  "reviewerFocus": [
+    "插件管理页是否延续当前 Apple 风格后台，并形成真实工作台而不是占位页",
+    "卡片动作优先级、危险动作和受保护插件边界是否清晰",
+    "详情抽屉中的 README 与配置双视图是否易读且层级明确"
+  ],
+  "testerFocus": [
+    "插件列表、类型切换、状态筛选与搜索是否真实连接 /plugin/getPlugins 数据流",
+    "上传、安装、启用、禁用、升级、卸载动作是否真实命中对应插件接口",
+    "插件配置读取与保存是否真实命中 /plugin/config"
+  ],
+  "ui": {
+    "required": true,
+    "designContract": true,
+    "sourcePriority": [
+      "plan.md",
+      ".helloagents/DESIGN.md",
+      "hello-ui"
+    ],
+    "styleAdvisor": {
+      "required": false,
+      "reason": "",
+      "focus": []
+    },
+    "visualValidation": {
+      "required": true,
+      "reason": "插件管理属于整页 UI 重做，需确认卡片列表、筛选工具栏与详情抽屉层级符合 Apple 风格后台契约",
+      "screens": [
+        "#/system/plugins desktop",
+        "#/system/plugins detail-drawer desktop"
+      ],
+      "states": [
+        "插件列表加载完成态",
+        "插件列表空状态或错误态",
+        "插件详情 README 态",
+        "插件配置编辑态"
+      ]
+    }
+  },
+  "advisor": {
+    "required": false,
+    "reason": "",
+    "focus": [],
+    "preferredSources": []
+  }
+}
@@ -0,0 +1,65 @@
+# admin-frontend 插件管理首版交付 — 实施规划
+
+## 目标与范围
+- 把 `#/system/plugins` 从占位页升级为真实插件管理页面。
+- 本轮范围聚焦“单页工作台 + 详情抽屉”模型：列表承担检索、筛选和高频动作，抽屉承担 README、配置与补充说明。
+- 其余系统管理子页保持现状，不借本轮需求扩展其他模块。
+
+## 架构与实现策略
+- 在 `admin-frontend/src/api/admin.ts` 与 `src/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 是动态结构，前端需要兼容多种字段类型与空配置插件。
+- 风险 2：`getPlugins` 已带部分配置和 README，但已安装插件的配置需要保证与 `/plugin/config` 拉取一致，避免抽屉内旧数据。
+- 风险 3：本地环境缺少真实登录态时，无法做完整浏览器联调；需要用 build + 代码级结构自检给出本轮 UI 验收结论。
+- 验证方式：
+  - `npm run build`
+  - 对构建产物与代码结构做 UI 自检，确认搜索、筛选、卡片操作与抽屉视图均已真实连接数据流
+
+## 决策记录
+- [2026-04-24] D001：插件管理采用“卡片列表 + 详情抽屉”，不回退到纯表格，兼顾截图风格和后台可操作性。
+- [2026-04-24] D002：配置编辑采用动态 schema 渲染，不为单个插件写死字段。
+- [2026-04-24] D003：README 与配置合并进同一个详情工作台，避免列表页信息密度失控。
@@ -0,0 +1,47 @@
+# admin-frontend 插件管理首版交付 — 需求
+
+确认后冻结，执行阶段不可修改。如需变更必须回到设计阶段重新确认。
+
+## 核心目标
+- 在 `admin-frontend` 中把 `/system/plugins` 从结构化占位页升级为真实插件管理工作台。
+- 页面视觉继续遵循 `apple/DESIGN.md` 与当前后台 Apple 化风格，并尽量贴近用户提供的目标截图：顶部搜索 / 分组切换 / 状态筛选 / 上传入口，下方插件卡片列表。
+- 让管理员可以在同一页面完成插件浏览、筛选、上传、安装、启用 / 禁用、升级、卸载，以及 README / 配置查看与编辑。
+
+## 功能边界
+- 必须接入现有 Laravel 管理接口的真实数据链路：
+  - `GET /plugin/types`
+  - `GET /plugin/getPlugins`
+  - `POST /plugin/upload`
+  - `POST /plugin/install`
+  - `POST /plugin/uninstall`
+  - `POST /plugin/enable`
+  - `POST /plugin/disable`
+  - `GET /plugin/config`
+  - `POST /plugin/config`
+  - `POST /plugin/upgrade`
+- 必须支持：
+  - 按关键词搜索插件
+  - 按插件类型切换（全部 / 功能 / 支付方式）
+  - 按状态筛选（全部 / 已启用 / 已安装未启用 / 未安装 / 可升级）
+  - 上传 zip 插件包
+  - 列表中直接执行安装、启用、禁用、升级、卸载动作
+  - 打开插件详情工作台，查看 README、基础元信息，并对可配置插件进行配置保存
+- 必须覆盖加载、空列表、错误、按钮提交中、配置保存成功 / 失败等状态。
+
+## 非目标
+- 本轮不实现主题、公告、支付配置、知识库管理的真实 CRUD 页面。
+- 本轮不新增或重构 Laravel 插件管理接口。
+- 本轮不接入浏览器端拖拽上传、批量操作或插件市场远程下载能力。
+- 本轮不修改 `public/assets/admin` 子模块之外的发布流程。
+
+## 技术约束
+- 技术栈固定为 `Vue 3 + TypeScript + Vite + Element Plus`。
+- 后端真相源以现有 `PluginController` / `PluginConfigService` / `PluginManager` 为准，不在前端猜测额外字段。
+- 视觉契约优先级：本方案 > `.helloagents/DESIGN.md` > `apple/DESIGN.md` 参考原则。
+- 构建验证使用 `admin-frontend/package.json` 中已有 `npm run build`。
+
+## 质量要求
+- 插件管理页必须保持 Apple 风格后台的一致性，同时比现有占位页更强调运营效率与状态可读性。
+- 卡片与详情工作台中的插件状态、危险动作和受保护插件边界必须清晰可辨。
+- README 展示与配置编辑必须是真实数据流，不允许停留在纯展示占位。
+- 最终至少完成一次构建验证，并补一份本轮 UI 验收结论。
@@ -0,0 +1,13 @@
+# admin-frontend 插件管理首版交付 — 任务分解
+
+## 任务列表
+- [x] 任务1：冻结本轮插件管理方案包与状态上下文（涉及文件：`.helloagents/plan/202604241553_admin-frontend-plugin-management/requirements.md`、`.helloagents/plan/202604241553_admin-frontend-plugin-management/plan.md`、`.helloagents/plan/202604241553_admin-frontend-plugin-management/tasks.md`、`.helloagents/plan/202604241553_admin-frontend-plugin-management/contract.json`、`.helloagents/sessions/master/default/STATE.md`；完成标准：存在可执行的需求/方案/任务/合同文件，状态文件已切到插件管理主线；验证方式：文件检查）
+- [x] 任务2：补齐插件管理前端类型与 API（涉及文件：`admin-frontend/src/api/admin.ts`、`admin-frontend/src/types/api.d.ts`、`admin-frontend/src/utils/plugins.ts`；完成标准：存在插件列表、动作、配置、上传所需的真实接口封装与辅助类型 / 工具；验证方式：`npm run build`）
+- [x] 任务3：实现插件管理列表工作台（涉及文件：`admin-frontend/src/router/index.ts`、`admin-frontend/src/views/system/PluginManagementView.vue`、`admin-frontend/src/views/system/PluginManagementView.scss`；完成标准：`#/system/plugins` 能展示真实插件卡片、搜索、类型切换、状态筛选、上传入口与列表动作；验证方式：`npm run build`）
+- [x] 任务4：实现插件详情与配置工作台（涉及文件：`admin-frontend/src/views/system/PluginDetailDrawer.vue`、`admin-frontend/src/utils/plugins.ts`、`admin-frontend/src/api/admin.ts`；完成标准：可打开 README / 配置抽屉，并支持真实配置读取与保存；验证方式：`npm run build`）
+- [x] 任务5：完成验证、知识库同步与交付证据（涉及文件：`.helloagents/modules/admin-frontend.md`、`.helloagents/CHANGELOG.md`、`.helloagents/.ralph-visual.json`、`.helloagents/.ralph-closeout.json`、`.helloagents/archive/_index.md`、`.helloagents/sessions/master/default/STATE.md`；完成标准：构建通过，UI 验收结论与知识库记录同步完成；验证方式：命令输出 + 证据文件）
+
+## 进度
+- [x] 已冻结插件管理首版交付范围。
+- [x] 已完成插件管理页面与详情工作台。
+- [x] 已完成验证与知识库同步。