feat(admin-frontend): 新增系统与订阅管理后台页面

扩展管理端侧边栏与路由，新增系统配置真实页面、订阅套餐管理页、节点管理页及多个结构化占位页补齐前端 API、类型与工具层，并增强仪表盘刷新、趋势切换、失败作业详情与流量排行 limit 联动能力同步后端 traffic rank limit 支持与知识库归档、设计约束、验证配置及视觉验收产物
2026-04-24 15:32:09 +08:00
parent 9ce345eb76
commit 16203b14f6
74 changed files with 6737 additions and 119 deletions
@@ -0,0 +1,55 @@
+{
+  "updatedAt": "2026-04-23T15:35:17.621Z",
+  "version": 1,
+  "source": "~auto",
+  "originCommand": "plan",
+  "verifyMode": "review-first",
+  "reviewerFocus": [
+    "系统管理侧边栏分组是否清晰且与现有 Apple 风格后台一致",
+    "系统配置页的左侧分组导航与右侧长表单结构是否清晰可读",
+    "其余系统管理入口是否被透明标注为后续接入"
+  ],
+  "testerFocus": [
+    "系统管理新路由是否可以正常进入",
+    "系统配置页是否真实连接 /config/fetch 与 /config/save",
+    "保存反馈与辅助按钮是否存在真实数据流"
+  ],
+  "ui": {
+    "required": true,
+    "designContract": true,
+    "sourcePriority": [
+      "plan.md",
+      ".helloagents/DESIGN.md",
+      "hello-ui"
+    ],
+    "styleAdvisor": {
+      "required": false,
+      "reason": "",
+      "focus": []
+    },
+    "visualValidation": {
+      "required": true,
+      "reason": "系统管理属于整页新建后台视图，需要确认导航、系统配置长表单层级与占位页结构在浏览器中符合 Apple 风格契约",
+      "screens": [
+        "#/system/config desktop",
+        "#/system/plugins desktop",
+        "#/system/themes desktop",
+        "#/system/notices desktop",
+        "#/system/payments desktop",
+        "#/system/knowledge desktop"
+      ],
+      "states": [
+        "系统配置默认加载完成态",
+        "系统配置保存态",
+        "系统配置错误/重试态",
+        "系统模块占位态"
+      ]
+    }
+  },
+  "advisor": {
+    "required": false,
+    "reason": "",
+    "focus": [],
+    "preferredSources": []
+  }
+}
@@ -0,0 +1,63 @@
+# admin-frontend 系统管理首批交付 — 实施规划
+
+## 目标与范围
+- 为 `admin-frontend` 增加“系统管理”信息架构，并先交付“系统配置”主页面。
+- 页面目标不是一次性做完整后台系统中心，而是先打通“可进入、可读取、可编辑、可保存”的配置主链路，同时把其余 5 个系统管理入口先稳定为可访问占位页。
+
+## 架构与实现策略
+- 在现有 `AdminLayout` 基础上新增“系统管理”二级分组，保持侧边栏结构统一。
+- 新增以下路由：
+  - `/system/config` 为真实功能页
+  - `/system/plugins`
+  - `/system/themes`
+  - `/system/notices`
+  - `/system/payments`
+  - `/system/knowledge`
+- 系统配置页直接消费现有后端接口，不在前端猜测或重塑接口契约：
+  - `/config/fetch`
+  - `/config/save`
+  - `/config/testSendMail`
+  - `/config/setTelegramWebhook`
+- 配置字段分组、控件元信息与序列化逻辑下沉到 `utils/systemConfig.ts`，避免页面组件膨胀。
+- 占位页使用统一的 `SystemPlaceholderView`，以一致的结构说明本轮范围与下一阶段扩展点。
+
+## 完成定义
+- 侧边栏出现“系统管理”分组，且可以进入 6 个子入口。
+- `/system/config` 页面可真实拉取配置数据，并按 9 个配置分组组织内容。
+- 用户可以修改并保存系统配置，保存后获得成功/失败反馈。
+- 邮件设置与 Telegram 设置保留辅助动作入口（测试邮件 / 设置 Webhook），但不在本轮额外扩展复杂工作流。
+- 其余 5 个系统管理子页可从侧边栏正常进入，并明确标注“下一阶段接入”。
+- 验证主路径：`review-first`
+- reviewer 关注边界：系统管理信息架构是否清晰、系统配置表单层级是否贴近 Apple 风格后台、占位页是否透明说明未实现范围。
+- tester 关注边界：菜单与路由是否真实连通、系统配置页是否真实连接 `/config/fetch` 与 `/config/save`、保存链路与辅助按钮是否存在真实数据流。
+
+## 文件结构
+- `admin-frontend/src/router/index.ts`
+- `admin-frontend/src/layouts/AdminLayout.vue`
+- `admin-frontend/src/api/admin.ts`
+- `admin-frontend/src/types/api.d.ts`
+- `admin-frontend/src/utils/systemConfig.ts`（新增）
+- `admin-frontend/src/views/system/SystemConfigView.vue`（新增）
+- `admin-frontend/src/views/system/SystemPlaceholderView.vue`（新增）
+- `.helloagents/DESIGN.md`
+
+## UI / 设计约束
+- 系统配置首页保留黑色 hero + 白色配置壳层的 Apple 后台节奏。
+- 左侧使用紧凑分组导航，右侧使用连续表单 section，优先满足“快速定位配置块”的后台效率诉求。
+- 页面首屏只保留一个主保存动作和少量辅助描述，不堆砌营销式视觉元素。
+- 占位页不做空白页，而是交付可继续扩展的结构化提示页。
+
+## 风险与验证
+- 风险 1：配置接口字段类型包含布尔、数值、数组和长文本，前端需要统一序列化与表单回填。
+- 风险 2：`/config/fetch` 返回分组对象，系统配置页必须避免直接把后端分组名暴露成低可读开发术语。
+- 风险 3：本地静态预览环境可能缺少 Laravel 注入或后台认证，浏览器验收要区分“结构验收”和“真实联调”边界。
+- 验证方式：
+  - `npm run build`
+  - 本地预览 + 浏览器检查 `#/system/config`
+  - 浏览器检查 `#/system/plugins`、`#/system/themes`、`#/system/notices`、`#/system/payments`、`#/system/knowledge`
+
+## 决策记录
+- [2026-04-23] 系统管理首批交付聚焦“系统配置真实页 + 其余入口占位页”，避免在一轮内同时展开多个 CRUD 模块。
+- [2026-04-23] “系统配置”保留左侧配置分组导航，优先满足后台场景中的长表单定位效率。
+- [2026-04-23] 前台主题相关配置不混入本轮系统配置页，而是留在“主题配置”入口的后续阶段实现。
+
@@ -0,0 +1,51 @@
+# admin-frontend 系统管理首批交付 — 需求
+
+确认后冻结，执行阶段不可修改。如需变更必须回到设计阶段重新确认。
+
+## 核心目标
+- 在 `admin-frontend` 中新增“系统管理”一级侧边栏分组。
+- 优先实现“系统配置”页面，并尽量贴近用户提供的目标结构：左侧分组导航 + 右侧长表单编辑区。
+- 页面视觉以 `apple/DESIGN.md` 为参考，并与现有 Apple 化仪表盘、用户管理、工单管理保持同一后台设计语言。
+
+## 功能边界
+- 必须新增系统管理分组，包含：
+  - 系统配置
+  - 插件管理
+  - 主题配置
+  - 公告管理
+  - 支付配置
+  - 知识库管理
+- 必须实现“系统配置”真实页面，覆盖：
+  - 站点设置
+  - 安全设置
+  - 订阅设置
+  - 邀请 & 佣金设置
+  - 节点配置
+  - 邮件设置
+  - Telegram 设置
+  - APP 设置
+  - 订阅模板
+- “系统配置”必须接入现有 Laravel 管理接口的真实数据读取与保存链路。
+- 插件管理、主题配置、公告管理、支付配置、知识库管理本轮只要求提供结构化占位页，为下一轮真实接入留入口。
+
+## 非目标
+- 本轮不实现插件、主题、公告、支付、知识库的完整 CRUD 页面。
+- 本轮不重做后端配置 API，不新增 Laravel 管理端接口。
+- 本轮不把前台主题配置混入“系统配置”页；主题能力保留在“主题配置”入口的后续阶段实现。
+
+## 技术约束
+- 技术栈固定为 `Vue 3 + TypeScript + Vite + Element Plus`。
+- 后端真相源以现有 Laravel 管理接口为准，系统配置使用：
+  - `GET /config/fetch`
+  - `POST /config/save`
+  - `POST /config/testSendMail`
+  - `POST /config/setTelegramWebhook`
+- 视觉契约优先级：本方案 > `.helloagents/DESIGN.md` > `apple/DESIGN.md` 的参考原则。
+- 构建验证使用 `admin-frontend/package.json` 中已有 `npm run build`。
+
+## 质量要求
+- 系统配置页必须保持 Apple 风格的一致性，并具备后台长表单的高可读性。
+- 异步页面必须覆盖加载、错误、保存成功与未修改状态反馈。
+- 表单交互需要明确区分主操作与辅助操作，避免一屏出现过多高强调按钮。
+- 最终至少完成一次构建验证与一次浏览器级视觉验收。
+
@@ -0,0 +1,13 @@
+# admin-frontend 系统管理首批交付 — 任务分解
+
+## 任务列表
+- [x] 任务1：补齐本轮 UI 契约与方案产物（涉及文件：`.helloagents/DESIGN.md`、`.helloagents/plans/202604232329_admin-frontend-system-management/*`；完成标准：存在可执行需求、方案、任务与合同文件；验证方式：文件检查）
+- [x] 任务2：扩展后台导航与路由结构（涉及文件：`admin-frontend/src/router/index.ts`、`admin-frontend/src/layouts/AdminLayout.vue`；完成标准：侧边栏出现系统管理分组并可进入 6 个子页面；验证方式：`npm run build` + 浏览器检查导航）
+- [x] 任务3：接入系统配置数据模型与 API（涉及文件：`admin-frontend/src/api/admin.ts`、`admin-frontend/src/types/api.d.ts`、`admin-frontend/src/utils/systemConfig.ts`；完成标准：前端可拉取并保存系统配置，字段可完成必要的回填与序列化；验证方式：`npm run build`）
+- [x] 任务4：实现系统配置主页面（涉及文件：`admin-frontend/src/views/system/SystemConfigView.vue`；完成标准：页面具备 9 个配置分组、加载/错误/保存反馈、左侧导航与真实保存入口；验证方式：`npm run build` + 浏览器检查 `#/system/config`）
+- [x] 任务5：实现其余系统管理占位页（涉及文件：`admin-frontend/src/views/system/SystemPlaceholderView.vue`；完成标准：其余 5 个入口可正常访问，并明确说明下一阶段接入范围；验证方式：`npm run build` + 浏览器检查对应路由）
+- [x] 任务6：完成验证、视觉验收与知识库同步（涉及文件：`.helloagents/CHANGELOG.md`、`.helloagents/modules/admin-frontend.md`、`.helloagents/.ralph-visual.json`、`.helloagents/.ralph-closeout.json`；完成标准：构建通过、视觉检查完成、知识库记录本轮变更；验证方式：命令输出 + 证据文件）
+
+## 进度
+- [x] 已冻结系统管理首批范围与系统配置优先级。
+- [x] 已完成 admin-frontend 系统管理导航、路由与系统配置页面。