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

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

---

## 1. 需求

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

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

### 约束条件
```yaml
范围约束: 本轮仅实现路由管理工作台与节点引用摘要，不扩展为完整拓扑/影响面详情页
技术约束: 继续使用 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` 才显示并做非空校验。
**理由**: 能与后端契约、用户截图和运营认知保持一致，降低表单噪音。