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,51 @@
+{
+  "updatedAt": "2026-04-23T15:23:18.713Z",
+  "version": 1,
+  "source": "~auto",
+  "originCommand": "plan",
+  "verifyMode": "review-first",
+  "reviewerFocus": [
+    "节点管理侧边栏分组是否清晰且与现有 Apple 风格后台一致",
+    "未实现的创建/排序能力是否被透明标注为后续接入"
+  ],
+  "testerFocus": [
+    "节点列表是否真实连接 /server/manage/getNodes 与 /server/group/fetch",
+    "搜索、类型筛选、权限组筛选与显隐切换是否存在真实数据流",
+    "节点相关新路由是否可以正常进入"
+  ],
+  "ui": {
+    "required": true,
+    "designContract": true,
+    "sourcePriority": [
+      "plan.md",
+      ".helloagents/DESIGN.md",
+      "hello-ui"
+    ],
+    "styleAdvisor": {
+      "required": false,
+      "reason": "",
+      "focus": []
+    },
+    "visualValidation": {
+      "required": true,
+      "reason": "节点管理属于整页新建后台视图，需要确认导航、列表密度与占位页结构在浏览器中符合 Apple 风格契约",
+      "screens": [
+        "#/nodes desktop",
+        "#/node-groups desktop",
+        "#/node-routes desktop"
+      ],
+      "states": [
+        "节点列表默认加载完成态",
+        "节点列表筛选结果态",
+        "权限组管理占位态",
+        "路由管理占位态"
+      ]
+    }
+  },
+  "advisor": {
+    "required": false,
+    "reason": "",
+    "focus": [],
+    "preferredSources": []
+  }
+}
@@ -0,0 +1,54 @@
+# admin-frontend 节点管理首批交付 — 实施规划
+
+## 目标与范围
+- 为 `admin-frontend` 增加节点管理信息架构，并先交付“节点管理”主页面。
+- 页面目标不是一次性做完整节点中后台，而是先打通“可看、可筛、可切显隐、可做基础行级操作”的运营主链路。
+
+## 架构与实现策略
+- 在现有 `AdminLayout` 基础上新增“节点管理”二级分组，保持侧边栏结构统一。
+- 新增 `/nodes`、`/node-groups`、`/node-routes` 三个路由，其中 `/nodes` 为真实功能页，其余两页为明确占位页。
+- 节点列表页直接消费现有后端接口，不在前端猜测或重塑接口契约：
+  - `/server/manage/getNodes`
+  - `/server/group/fetch`
+  - `/server/manage/update`
+  - `/server/manage/copy`
+  - `/server/manage/drop`
+- 复杂的节点格式化逻辑（地址、状态、标签、筛选选项）下沉到 `utils/nodes.ts`，避免页面组件膨胀。
+
+## 完成定义
+- 侧边栏出现“节点管理”分组，且可以进入 3 个子入口。
+- `/nodes` 页面可真实拉取节点与权限组数据。
+- 用户可以通过搜索、节点类型和权限组筛选列表。
+- 用户可以切换节点显隐状态，并在界面中获得成功/失败反馈。
+- 用户可以通过更多菜单执行复制节点与删除节点；未覆盖的编辑/排序功能有明确边界提示。
+- 验证主路径：`review-first`
+- reviewer 关注边界：导航结构是否清晰、页面是否与 Apple 风格一致、未实现功能是否被透明标注。
+- tester 关注边界：构建是否通过、节点列表是否真实连接 API、筛选与显隐切换是否存在数据流。
+
+## 文件结构
+- `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/nodes.ts`（新增）
+- `admin-frontend/src/views/nodes/NodesView.vue`（新增）
+- `admin-frontend/src/views/nodes/NodeGroupsView.vue`（新增）
+- `admin-frontend/src/views/nodes/NodeRoutesView.vue`（新增）
+
+## UI / 设计约束
+- 节点管理首页保留黑色 hero + 白色表格壳层的 Apple 后台节奏。
+- 过滤器采用紧凑 pill / select 混合布局，优先满足快速运营判断。
+- 列表状态用圆点、标签和辅助文字三层表达，不只靠颜色。
+- 占位页不做空白页，而是交付可继续扩展的结构化提示页。
+
+## 风险与验证
+- 风险 1：后端节点字段可能存在空值或差异，页面要做健壮格式化。
+- 风险 2：节点显隐切换的字段是 `show`，前端需保持与布尔/整型兼容。
+- 风险 3：权限组接口若返回结构偏轻，前端需要容错处理。
+- 验证方式：
+  - `npm run build`
+  - 本地预览 + 浏览器检查 `/nodes`、`/node-groups`、`/node-routes`
+
+## 决策记录
+- [2026-04-23] 节点管理首批交付聚焦列表运营链路，不在本轮接入完整节点编辑表单，避免 UI 范围失控。
+- [2026-04-23] 权限组管理 / 路由管理先交付占位页，保证侧边栏信息架构先稳定下来。
@@ -0,0 +1,37 @@
+# admin-frontend 节点管理首批交付 — 需求
+
+确认后冻结，执行阶段不可修改。如需变更必须回到设计阶段重新确认。
+
+## 核心目标
+- 在 `admin-frontend` 中新增“节点管理”侧边栏分组。
+- 优先实现“节点管理”主页面，使管理者可以在 Apple 风格后台中查看、搜索、筛选和执行基础节点操作。
+- 页面视觉以 `apple/DESIGN.md` 为参考，并与现有 Apple 化仪表盘、用户管理、工单管理保持一致。
+
+## 功能边界
+- 必须新增节点管理分组，包含：节点管理、权限组管理、路由管理 3 个入口。
+- 必须实现“节点管理”列表页，覆盖：
+  - 节点列表拉取
+  - 关键字段展示（节点 ID、显隐、节点、地址、在线人数、倍率、权限组）
+  - 搜索
+  - 类型筛选
+  - 权限组筛选
+  - 显隐切换
+  - 行级更多操作菜单
+- 权限组管理、路由管理本轮只要求提供结构化占位页，为下一轮真实接入留入口。
+
+## 非目标
+- 本轮不实现完整的节点创建 / 编辑大表单。
+- 本轮不实现拖拽排序或完整排序编辑器。
+- 本轮不重做后端接口，不新增 Laravel 管理端 API。
+
+## 技术约束
+- 技术栈固定为 `Vue 3 + TypeScript + Vite + Element Plus`。
+- 后端真相源以现有 Laravel 管理接口为准，节点列表使用 `/server/manage/getNodes`。
+- 视觉契约优先级：本方案 > `.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/202604232320_admin-frontend-node-management/*`；完成标准：存在可执行需求、方案、任务与合同文件；验证方式：文件检查）
+- [x] 任务2：扩展后台导航与路由结构（涉及文件：`admin-frontend/src/router/index.ts`、`admin-frontend/src/layouts/AdminLayout.vue`；完成标准：侧边栏出现节点管理分组并可进入 3 个子页面；验证方式：`npm run build` + 浏览器检查导航）
+- [x] 任务3：接入节点管理数据模型与 API（涉及文件：`admin-frontend/src/api/admin.ts`、`admin-frontend/src/types/api.d.ts`、`admin-frontend/src/utils/nodes.ts`；完成标准：前端可拉取节点与权限组并完成必要格式化；验证方式：`npm run build`）
+- [x] 任务4：实现节点管理主页面（涉及文件：`admin-frontend/src/views/nodes/NodesView.vue`；完成标准：节点列表具备搜索、筛选、显隐切换、复制/删除基础能力，并覆盖加载/空/错误状态；验证方式：`npm run build` + 浏览器检查 `/nodes`）
+- [x] 任务5：实现权限组 / 路由管理占位页（涉及文件：`admin-frontend/src/views/nodes/NodeGroupsView.vue`、`admin-frontend/src/views/nodes/NodeRoutesView.vue`；完成标准：可从侧边栏进入，页面明确说明下一阶段接入范围；验证方式：`npm run build` + 浏览器检查对应路由）
+- [x] 任务6：完成验证、视觉验收与知识库同步（涉及文件：`.helloagents/CHANGELOG.md`、`.helloagents/.ralph-visual.json`、`.helloagents/.ralph-closeout.json`；完成标准：构建通过、视觉检查完成、知识库记录本轮变更；验证方式：命令输出 + 证据文件）
+
+## 进度
+- [x] 已创建方案包并冻结首批交付范围。
+- [x] 已完成 admin-frontend 节点管理首批页面与知识库同步。