Xboard/.helloagents/plan/202604241701_admin-frontend-node-route-management/proposal.md

变更提案: admin-frontend-node-route-management

元信息

类型: 功能增强
方案类型: implementation
优先级: P1
状态: 已完成
创建: 2026-04-24

---

1. 需求

背景

admin-frontend 当前已经完成节点管理主工作台，但 #/node-routes 仍停留在结构化占位页。用户已提供目标截图，并在本轮确认选择“CRUD 首版 + 节点引用摘要”方案，希望继续把路由管理做成真实可用的后台页面。

目标

• 将 #/node-routes 从占位页升级为真实可用的路由管理工作台。
• 支持路由列表查看、关键词搜索、新增、编辑、删除与动作值展示。
• 在列表中补充每条路由当前被多少节点引用、以及部分节点名预览，帮助运营判断影响面。

约束条件

范围约束: 本轮仅实现路由管理工作台与节点引用摘要，不扩展为完整拓扑/影响面详情页
技术约束: 继续使用 Vue3 + TypeScript + Element Plus，不新增第三方依赖
视觉约束: 贴近用户截图中的“黑色 hero + 白色表格工作台 + 中央编辑弹窗”结构，并继续遵循 apple/DESIGN.md 与 .helloagents/DESIGN.md
业务约束: 后端真相源固定为 server/route/fetch、server/route/save、server/route/drop；节点引用摘要由 server/manage/getNodes 的 route_ids 推导

验收标准

• #/node-routes 可真实拉取路由列表，并显示 ID、备注、动作值、动作类型与操作列。
• 页面支持关键词搜索，搜索范围覆盖备注、匹配规则、动作值与引用节点名称。
• 支持新增/编辑路由，字段覆盖备注、匹配规则、动作与按需出现的动作值。
• 支持删除路由，并给出明确成功/失败反馈。
• 列表中可看到每条路由的节点引用摘要，包括引用数量与部分节点名预览。
• admin-frontend 执行 npm run build 通过。

---

2. 方案

页面结构

1. 顶部保留黑色 hero，左侧说明“路由管理”的职责，右侧展示总路由数、禁止访问、DNS 解析与已引用路由数。
2. 主工作区采用白色表格容器，工具条只保留“添加路由”和“搜索路由”，贴近用户截图。
3. 列表主体展示：
   • 路由 ID
   • 备注（含节点引用摘要）
   • 动作值（主值 + 匹配规则条数）
   • 动作标签
   • 编辑 / 删除操作
4. 编辑路由采用中央 ElDialog，表单结构与截图一致：备注、匹配规则、动作；当动作为 dns 或 proxy 时，再补充动作值输入。

前端实现策略

1. 在 src/types/api.d.ts 中新增路由实体与保存载荷定义。
2. 在 src/api/admin.ts 中新增路由管理接口封装：fetchNodeRoutes / saveNodeRoute / deleteNodeRoute。
3. 新增 src/utils/routes.ts，统一处理：
   • 路由实体归一化
   • 搜索过滤
   • 动作标签 / 动作值映射
   • 表单模型转换
   • 节点引用摘要生成
4. 新增：
   • src/views/nodes/NodeRoutesView.vue
   • src/views/nodes/NodeRoutesView.scss
   • src/views/nodes/NodeRouteEditorDialog.vue
   • src/views/nodes/NodeRouteEditorDialog.scss
5. 保持 src/router/index.ts 与 AdminLayout 既有入口不变，只替换占位页面实现。

风险评估

风险	等级	应对
后端 match 字段要求数组，前端截图却是 textarea 录入	中	编辑器继续使用多行 textarea，提交前按行切分并去空，拉取后再回填为换行文本
action_value 仅部分动作需要	中	在工具层与表单层统一定义“需要动作值”的动作集合，仅在 dns / proxy 时展示与校验
节点引用摘要并非后端直接返回字段	低	与路由列表并行拉取节点列表，通过 route_ids 本地推导引用数量与名称摘要

---

3. 技术决策

admin-frontend-node-route-management#D001: 路由列表采用“截图同款表格 + 中央编辑弹窗”

日期: 2026-04-24 状态: ✅采纳 背景: 用户已经给出目标截图，并明确希望继续完成真实路由管理工作台。 决策: 列表、搜索与删除保留在主页面；新增/编辑统一进入中央弹窗。 理由: 最符合当前后台已有公告/知识库工作流，也最贴近用户截图。

admin-frontend-node-route-management#D002: 节点引用摘要放在列表备注区，而不扩展成独立拓扑视图

日期: 2026-04-24 状态: ✅采纳 背景: 用户本轮选择的是“CRUD 首版 + 节点引用摘要”，不是完整影响面可视化。 决策: 只在列表中提供“引用节点数 + 部分节点名预览”的只读摘要，不新增复杂详情工作台。 理由: 能满足当前运营判断需求，同时控制本轮范围。

admin-frontend-node-route-management#D003: 动作值仅在 dns / proxy 时显示独立输入

日期: 2026-04-24 状态: ✅采纳 背景: 后端允许 action_value 为空，截图中“禁止访问 / 直连”也没有额外输入框。 决策: block / direct 不展示动作值输入；dns / proxy 才显示并做非空校验。 理由: 能与后端契约、用户截图和运营认知保持一致，降低表单噪音。