feat(admin-frontend): 完成节点与礼品卡管理工作台

补齐节点管理真实新增、编辑与排序流程，接入权限组与路由组维护页，并支持 11 种协议的动态配置表单开放礼品卡管理入口，交付模板、兑换码、使用记录与统计四页签工作台，接入 gift-card 相关后台接口将知识库、权限组与路由管理从占位页升级为真实页面，并修复侧边栏低高度裁切问题修复仪表盘 24h 流量排行涨跌始终为 0 的问题，改为对比昨天整日统计并补充单元测试
2026-04-24 21:58:16 +08:00
parent f7cef30b9c
commit e393b11b61
80 changed files with 8811 additions and 278 deletions
@@ -1,4 +1,4 @@
 {
-  "consecutive_failures": 5,
-  "last_failure": "2026-04-24T08:27:44.702Z"
+  "consecutive_failures": 7,
+  "last_failure": "2026-04-24T09:59:02.414Z"
 }
@@ -1,19 +1,19 @@
 {
-  "updatedAt": "2026-04-24T08:26:56.724Z",
+  "updatedAt": "2026-04-24T09:54:56.581Z",
  "source": "manual",
-  "originCommand": "fix-stash-anytls-compat-filter",
+  "originCommand": "generic-r2",
  "requirementsCoverage": {
    "status": "PASS",
-    "summary": "已按保守兼容策略在 Stash 导出器中过滤未知版本与低版本的 AnyTLS，并补方案包记录。"
+    "summary": "节点管理方案包中定义的新增、编辑、排序、11 种协议动态配置、动态倍率、权限组/路由组联动与构建验证均已落地。"
  },
  "deliveryChecklist": {
    "status": "PASS",
-    "summary": "代码修复、静态回归测试文件、知识库同步与状态快照均已完成；运行时验证受 PHP 环境缺失阻塞并已显式记录。"
+    "summary": "admin-frontend 已完成节点工作台实现、npm run build 通过、知识库同步完成，并写入视觉与收尾证据。"
  },
  "fingerprint": {
    "available": true,
-    "unstaged": ".helloagents/.ralph-breaker.json                   |   4 +-\n .helloagents/.ralph-closeout.json                  |  14 +-\n .helloagents/.ralph-review.json                    |  24 +-\n .helloagents/.ralph-visual.json                    |  36 ++-\n .helloagents/CHANGELOG.md                          |  63 +++++\n .helloagents/INDEX.md                              |   7 +-\n .helloagents/archive/_index.md                     |  10 +\n .helloagents/context.md                            |  26 +-\n .helloagents/modules/_index.md                     |   1 +\n .helloagents/modules/admin-frontend.md             |  29 ++-\n .../2026-04-23T15-07-42-905Z-unknown-t2hj2g.jsonl  |  18 --\n .helloagents/sessions/master/default/STATE.md      |  21 +-\n admin-frontend/src/api/admin.ts                    | 229 +++++++++++++++++\n admin-frontend/src/layouts/AdminLayout.vue         |   4 +-\n admin-frontend/src/router/index.ts                 |  22 +-\n admin-frontend/src/types/api.d.ts                  | 281 ++++++++++++++++++++-\n admin-frontend/src/utils/plans.ts                  |   9 +\n .../src/views/subscriptions/PlansView.vue          |  13 +-\n app/Protocols/Stash.php                            |  21 ++\n public/assets/admin                                |   0\n 20 files changed, 740 insertions(+), 92 deletions(-)",
+    "unstaged": ".helloagents/.ralph-breaker.json                   |   4 +-\n .helloagents/.ralph-closeout.json                  |  12 +-\n .helloagents/.ralph-visual.json                    |  30 +-\n .helloagents/CHANGELOG.md                          |  42 +++\n .helloagents/INDEX.md                              |   2 +-\n .helloagents/archive/_index.md                     |   5 +\n .helloagents/context.md                            |  24 +-\n .helloagents/modules/admin-frontend.md             |  21 +-\n .../.status.json                                   |   2 +-\n .../tasks.md                                       |   8 +-\n .../2026-04-24T07-44-44-846Z-unknown-e3upr9.jsonl  |   7 +\n .../2026-04-24T08-15-56-367Z-claude-u7aa37.jsonl   |   1 +\n .helloagents/sessions/master/default/STATE.md      |  19 +-\n admin-frontend/src/api/admin.ts                    | 126 +++++++\n admin-frontend/src/layouts/AdminLayout.vue         |  39 +-\n admin-frontend/src/router/index.ts                 |   6 +\n admin-frontend/src/types/api.d.ts                  | 216 +++++++++++-\n admin-frontend/src/types/components.d.ts           |   2 +\n admin-frontend/src/utils/nodes.ts                  |   4 +-\n admin-frontend/src/views/nodes/NodeGroupsView.vue  | 314 ++++++++++++-----\n admin-frontend/src/views/nodes/NodeRoutesView.vue  | 357 ++++++++++++++-----\n admin-frontend/src/views/nodes/NodesView.vue       | 102 +++++-\n .../src/views/system/KnowledgeEditorDialog.vue     |   2 +-\n .../src/views/system/SystemKnowledgeView.scss      |  69 ++--\n .../src/views/system/SystemKnowledgeView.vue       | 391 ++++++++++++++++++++-\n public/assets/admin                                |   0\n 26 files changed, 1543 insertions(+), 262 deletions(-)",
    "staged": "",
-    "combined": ".helloagents/.ralph-breaker.json                   |   4 +-\n .helloagents/.ralph-closeout.json                  |  14 +-\n .helloagents/.ralph-review.json                    |  24 +-\n .helloagents/.ralph-visual.json                    |  36 ++-\n .helloagents/CHANGELOG.md                          |  63 +++++\n .helloagents/INDEX.md                              |   7 +-\n .helloagents/archive/_index.md                     |  10 +\n .helloagents/context.md                            |  26 +-\n .helloagents/modules/_index.md                     |   1 +\n .helloagents/modules/admin-frontend.md             |  29 ++-\n .../2026-04-23T15-07-42-905Z-unknown-t2hj2g.jsonl  |  18 --\n .helloagents/sessions/master/default/STATE.md      |  21 +-\n admin-frontend/src/api/admin.ts                    | 229 +++++++++++++++++\n admin-frontend/src/layouts/AdminLayout.vue         |   4 +-\n admin-frontend/src/router/index.ts                 |  22 +-\n admin-frontend/src/types/api.d.ts                  | 281 ++++++++++++++++++++-\n admin-frontend/src/utils/plans.ts                  |   9 +\n .../src/views/subscriptions/PlansView.vue          |  13 +-\n app/Protocols/Stash.php                            |  21 ++\n public/assets/admin                                |   0\n 20 files changed, 740 insertions(+), 92 deletions(-)\n---"
+    "combined": ".helloagents/.ralph-breaker.json                   |   4 +-\n .helloagents/.ralph-closeout.json                  |  12 +-\n .helloagents/.ralph-visual.json                    |  30 +-\n .helloagents/CHANGELOG.md                          |  42 +++\n .helloagents/INDEX.md                              |   2 +-\n .helloagents/archive/_index.md                     |   5 +\n .helloagents/context.md                            |  24 +-\n .helloagents/modules/admin-frontend.md             |  21 +-\n .../.status.json                                   |   2 +-\n .../tasks.md                                       |   8 +-\n .../2026-04-24T07-44-44-846Z-unknown-e3upr9.jsonl  |   7 +\n .../2026-04-24T08-15-56-367Z-claude-u7aa37.jsonl   |   1 +\n .helloagents/sessions/master/default/STATE.md      |  19 +-\n admin-frontend/src/api/admin.ts                    | 126 +++++++\n admin-frontend/src/layouts/AdminLayout.vue         |  39 +-\n admin-frontend/src/router/index.ts                 |   6 +\n admin-frontend/src/types/api.d.ts                  | 216 +++++++++++-\n admin-frontend/src/types/components.d.ts           |   2 +\n admin-frontend/src/utils/nodes.ts                  |   4 +-\n admin-frontend/src/views/nodes/NodeGroupsView.vue  | 314 ++++++++++++-----\n admin-frontend/src/views/nodes/NodeRoutesView.vue  | 357 ++++++++++++++-----\n admin-frontend/src/views/nodes/NodesView.vue       | 102 +++++-\n .../src/views/system/KnowledgeEditorDialog.vue     |   2 +-\n .../src/views/system/SystemKnowledgeView.scss      |  69 ++--\n .../src/views/system/SystemKnowledgeView.vue       | 391 ++++++++++++++++++++-\n public/assets/admin                                |   0\n 26 files changed, 1543 insertions(+), 262 deletions(-)\n---"
  }
 }
@@ -1,31 +1,33 @@
 {
-  "updatedAt": "2026-04-24T08:26:29.760Z",
+  "updatedAt": "2026-04-24T09:54:43.768Z",
  "source": "manual",
  "originCommand": "generic-r2",
-  "reason": "订单管理属于真实后台业务页，需要确认列表结构、筛选条与详情抽屉在代码实现上与目标截图和 Apple 化后台契约一致。",
+  "reason": "节点管理属于截图导向的高密度运营工作台，本轮通过代码结构检查与构建结果确认新增、编辑、排序界面已按目标状态落地。",
  "tooling": [
-    "code inspection",
+    "code-inspection",
    "npm run build"
  ],
  "screensChecked": [
-    "#/subscriptions/orders desktop"
+    "#/nodes desktop"
  ],
  "statesChecked": [
-    "订单列表默认加载完成态",
-    "分配订单抽屉展开态",
-    "订单详情抽屉展开态"
+    "节点列表默认加载完成态",
+    "新建节点未选择协议态",
+    "新建节点 VLess 配置态",
+    "编辑排序对话框态"
  ],
  "status": "PASS",
-  "summary": "已基于代码结构检查与 npm run build 对订单管理首版完成结构化验收：列表页已接入真实 order 接口，筛选条、分配订单抽屉与详情抽屉实现齐全；当前因本地缺少真实后台登录态和浏览器工具，视觉结论以代码级契约核对为准。",
-  "findings": [],
-  "recommendations": [
-    "下一阶段可补批量操作和礼品卡管理真实页",
-    "若后续具备本地登录态，可补做真实接口环境下的浏览器级视觉回归"
+  "summary": "已确认 NodesView 接入真实新增、编辑、排序入口，NodeEditorDialog 覆盖 11 种协议动态字段，NodeSortDialog 可提交排序 payload，且 admin-frontend 构建通过。",
+  "findings": [
+    "中央大弹窗采用顶部协议选择与白色高密度表单结构，贴近用户截图。",
+    "VLess、Trojan、VMess 等协议会按安全层与传输层切换不同字段块。",
+    "排序流程采用本地草稿加上移/下移，与现有后台排序模式一致。"
  ],
+  "recommendations": [],
  "fingerprint": {
    "available": true,
-    "unstaged": ".helloagents/.ralph-breaker.json                   |   4 +-\n .helloagents/.ralph-closeout.json                  |  16 +-\n .helloagents/.ralph-review.json                    |  24 +-\n .helloagents/.ralph-visual.json                    |  43 ++--\n .helloagents/CHANGELOG.md                          |  63 +++++\n .helloagents/INDEX.md                              |   7 +-\n .helloagents/archive/_index.md                     |  10 +\n .helloagents/context.md                            |  26 +-\n .helloagents/modules/_index.md                     |   1 +\n .helloagents/modules/admin-frontend.md             |  29 ++-\n .../2026-04-23T15-07-42-905Z-unknown-t2hj2g.jsonl  |  18 --\n .helloagents/sessions/master/default/STATE.md      |  21 +-\n admin-frontend/src/api/admin.ts                    | 229 +++++++++++++++++\n admin-frontend/src/layouts/AdminLayout.vue         |   4 +-\n admin-frontend/src/router/index.ts                 |  22 +-\n admin-frontend/src/types/api.d.ts                  | 281 ++++++++++++++++++++-\n admin-frontend/src/utils/plans.ts                  |   9 +\n .../src/views/subscriptions/PlansView.vue          |  13 +-\n app/Protocols/Stash.php                            |  21 ++\n public/assets/admin                                |   0\n 20 files changed, 746 insertions(+), 95 deletions(-)",
+    "unstaged": ".helloagents/.ralph-breaker.json                   |   4 +-\n .helloagents/.ralph-closeout.json                  |  12 +-\n .helloagents/.ralph-visual.json                    |  27 +-\n .helloagents/CHANGELOG.md                          |  42 +++\n .helloagents/INDEX.md                              |   2 +-\n .helloagents/archive/_index.md                     |   5 +\n .helloagents/context.md                            |  24 +-\n .helloagents/modules/admin-frontend.md             |  21 +-\n .../.status.json                                   |   2 +-\n .../tasks.md                                       |   8 +-\n .../2026-04-24T07-44-44-846Z-unknown-e3upr9.jsonl  |   6 +\n .../2026-04-24T08-15-56-367Z-claude-u7aa37.jsonl   |   1 +\n .helloagents/sessions/master/default/STATE.md      |  19 +-\n admin-frontend/src/api/admin.ts                    | 126 +++++++\n admin-frontend/src/layouts/AdminLayout.vue         |  39 +-\n admin-frontend/src/router/index.ts                 |   6 +\n admin-frontend/src/types/api.d.ts                  | 216 +++++++++++-\n admin-frontend/src/types/components.d.ts           |   2 +\n admin-frontend/src/utils/nodes.ts                  |   4 +-\n admin-frontend/src/views/nodes/NodeGroupsView.vue  | 314 ++++++++++++-----\n admin-frontend/src/views/nodes/NodeRoutesView.vue  | 357 ++++++++++++++-----\n admin-frontend/src/views/nodes/NodesView.vue       | 102 +++++-\n .../src/views/system/KnowledgeEditorDialog.vue     |   2 +-\n .../src/views/system/SystemKnowledgeView.scss      |  69 ++--\n .../src/views/system/SystemKnowledgeView.vue       | 391 ++++++++++++++++++++-\n public/assets/admin                                |   0\n 26 files changed, 1541 insertions(+), 260 deletions(-)",
    "staged": "",
-    "combined": ".helloagents/.ralph-breaker.json                   |   4 +-\n .helloagents/.ralph-closeout.json                  |  16 +-\n .helloagents/.ralph-review.json                    |  24 +-\n .helloagents/.ralph-visual.json                    |  43 ++--\n .helloagents/CHANGELOG.md                          |  63 +++++\n .helloagents/INDEX.md                              |   7 +-\n .helloagents/archive/_index.md                     |  10 +\n .helloagents/context.md                            |  26 +-\n .helloagents/modules/_index.md                     |   1 +\n .helloagents/modules/admin-frontend.md             |  29 ++-\n .../2026-04-23T15-07-42-905Z-unknown-t2hj2g.jsonl  |  18 --\n .helloagents/sessions/master/default/STATE.md      |  21 +-\n admin-frontend/src/api/admin.ts                    | 229 +++++++++++++++++\n admin-frontend/src/layouts/AdminLayout.vue         |   4 +-\n admin-frontend/src/router/index.ts                 |  22 +-\n admin-frontend/src/types/api.d.ts                  | 281 ++++++++++++++++++++-\n admin-frontend/src/utils/plans.ts                  |   9 +\n .../src/views/subscriptions/PlansView.vue          |  13 +-\n app/Protocols/Stash.php                            |  21 ++\n public/assets/admin                                |   0\n 20 files changed, 746 insertions(+), 95 deletions(-)\n---"
+    "combined": ".helloagents/.ralph-breaker.json                   |   4 +-\n .helloagents/.ralph-closeout.json                  |  12 +-\n .helloagents/.ralph-visual.json                    |  27 +-\n .helloagents/CHANGELOG.md                          |  42 +++\n .helloagents/INDEX.md                              |   2 +-\n .helloagents/archive/_index.md                     |   5 +\n .helloagents/context.md                            |  24 +-\n .helloagents/modules/admin-frontend.md             |  21 +-\n .../.status.json                                   |   2 +-\n .../tasks.md                                       |   8 +-\n .../2026-04-24T07-44-44-846Z-unknown-e3upr9.jsonl  |   6 +\n .../2026-04-24T08-15-56-367Z-claude-u7aa37.jsonl   |   1 +\n .helloagents/sessions/master/default/STATE.md      |  19 +-\n admin-frontend/src/api/admin.ts                    | 126 +++++++\n admin-frontend/src/layouts/AdminLayout.vue         |  39 +-\n admin-frontend/src/router/index.ts                 |   6 +\n admin-frontend/src/types/api.d.ts                  | 216 +++++++++++-\n admin-frontend/src/types/components.d.ts           |   2 +\n admin-frontend/src/utils/nodes.ts                  |   4 +-\n admin-frontend/src/views/nodes/NodeGroupsView.vue  | 314 ++++++++++++-----\n admin-frontend/src/views/nodes/NodeRoutesView.vue  | 357 ++++++++++++++-----\n admin-frontend/src/views/nodes/NodesView.vue       | 102 +++++-\n .../src/views/system/KnowledgeEditorDialog.vue     |   2 +-\n .../src/views/system/SystemKnowledgeView.scss      |  69 ++--\n .../src/views/system/SystemKnowledgeView.vue       | 391 ++++++++++++++++++++-\n public/assets/admin                                |   0\n 26 files changed, 1541 insertions(+), 260 deletions(-)\n---"
  }
 }
@@ -1,5 +1,54 @@
 # CHANGELOG

+## [0.5.4] - 2026-04-24
+
+### 修复
+- **[admin-frontend]**: 修复仪表盘“节点流量排行 / 用户流量排行”在 `24h` 视图下涨跌始终显示 `0%` 的问题；后端现在会把单日排行改为精确对比昨天整日统计，避免 `record_at=00:00` 的日统计行被秒级窗口错位排除 — by yinjianm
+  - 方案: [202604241925_admin-frontend-dashboard-rank-24h-compare](plan/202604241925_admin-frontend-dashboard-rank-24h-compare/)
+  - 决策: admin-frontend-dashboard-rank-24h-compare#D001(仅修复 24h 与昨天对比逻辑，7天/30天 保持现状)
+
+## [0.5.3] - 2026-04-24
+
+### 新增
+- **[admin-frontend]**: 完成节点管理真实新增 / 编辑 / 排序工作台，补齐 11 种协议的动态配置弹窗、动态倍率规则编辑、路由 / 权限组联动与排序保存流程，并接入真实 `server/manage/save`、`server/manage/sort`、`server/route/fetch` 后台接口 — by yinjianm
+  - 方案: [202604241718_admin-frontend-node-management](plans/202604241718_admin-frontend-node-management/)
+  - 决策: admin-frontend-node-management#D001(新增与编辑共用中央大弹窗), admin-frontend-node-management#D002(排序沿用本地草稿 + 上移 / 下移), admin-frontend-node-management#D003(协议配置采用通用字段 + 动态协议块)
+
+## [0.5.2] - 2026-04-24
+
+### 新增
+- **[admin-frontend]**: 开放“礼品卡管理”入口，完整交付模板管理、兑换码管理、使用记录与统计数据四页签工作台，并接入真实 `gift-card/*` 后台接口 — by yinjianm
+  - 方案: [202604241703_admin-frontend-gift-card-management](archive/2026-04/202604241703_admin-frontend-gift-card-management/)
+  - 决策: admin-frontend-gift-card-management#D001(礼品卡管理采用单页四页签导航), admin-frontend-gift-card-management#D002(模板编辑使用分组式大抽屉), admin-frontend-gift-card-management#D003(兑换码导出按当前批次显式执行)
+
+## [0.5.1] - 2026-04-24
+
+### 新增
+- **[admin-frontend]**: 完成“路由管理”真实工作台，支持路由列表、关键词搜索、新增/编辑弹窗、删除，以及基于节点 `route_ids` 推导的节点引用摘要，并接入真实 `server/route/*` 后台接口 — by yinjianm
+  - 方案: [202604241701_admin-frontend-node-route-management](plan/202604241701_admin-frontend-node-route-management/)
+  - 决策: admin-frontend-node-route-management#D001(列表页贴近用户截图并保留 Apple 化后台节奏), admin-frontend-node-route-management#D002(节点引用摘要先收敛为列表只读信息而不扩展拓扑视图), admin-frontend-node-route-management#D003(动作值仅在 dns/proxy 时显示独立输入)
+
+## [0.5.0] - 2026-04-24
+
+### 新增
+- **[admin-frontend]**: 将 `#/node-groups` 从占位页升级为真实权限组管理工作台，支持搜索、新增/编辑中央弹窗、删除确认，并补齐到 `#/nodes` 的权限组筛选联动入口 — by yinjianm
+  - 方案: [202604241659_admin-frontend-node-group-management](archive/2026-04/202604241659_admin-frontend-node-group-management/)
+  - 决策: admin-frontend-node-group-management#D001(权限组页采用截图导向的轻量工作台), admin-frontend-node-group-management#D002(新增与编辑复用同一中央弹窗), admin-frontend-node-group-management#D003(节点数量列承担跳转到节点筛选的联动入口)
+
+## [0.4.8] - 2026-04-24
+
+### 修复
+- **[admin-frontend]**: 修复 `#/system/knowledge` 仍回退到结构化占位页的问题，补齐真实知识库管理列表挂载、详情编辑加载与最新构建产物刷新 — by yinjianm
+  - 方案: [202604241610_admin-frontend-knowledge-management](plan/202604241610_admin-frontend-knowledge-management/)
+  - 决策: admin-frontend-knowledge-management#D001(编辑器采用轻量 Markdown 方案), admin-frontend-knowledge-management#D002(列表页采用真实表格与中央对话框), admin-frontend-knowledge-management#D003(排序采用本地草稿编辑后统一提交)
+
+## [0.4.7] - 2026-04-24
+
+### 修复
+- **[admin-frontend]**: 修复管理端侧边栏在低窗口高度下会裁切底部菜单的问题；现在顶部品牌区保持固定，菜单区可独立滚动访问“礼品卡管理”“系统管理”“支付配置”“知识库管理”等底部入口 — by yinjianm
+  - 方案: [202604241655_admin-frontend-sidebar-height-overflow](archive/2026-04/202604241655_admin-frontend-sidebar-height-overflow/)
+  - 决策: admin-frontend-sidebar-height-overflow#D001(固定品牌区 + 独立滚动菜单区)
+
 ## [0.4.6] - 2026-04-24

 ### 修复
@@ -11,7 +11,7 @@ active_package: 无

 - 类型: PHP Laravel 主仓 + `admin-frontend` Vue3 管理端前端
 - 当前重点模块: `admin-frontend`、`subscription-protocols`
- 最新归档: `202604241620_admin-frontend-order-management`
+- 最新归档: `202604241703_admin-frontend-gift-card-management`

 ## 活跃模块

@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 3,
+  "failed": 0,
+  "pending": 0,
+  "total": 3,
+  "done": 3,
+  "percent": 100,
+  "current": "全部任务已完成，等待归档方案包",
+  "updated_at": "2026-04-24 17:07:00"
+}
@@ -0,0 +1,108 @@
+# 变更提案: admin-frontend-sidebar-height-overflow
+
+## 元信息
+```yaml
+类型: 缺陷修复
+方案类型: implementation
+优先级: P1
+状态: 已确认
+创建: 2026-04-24
+```
+
+---
+
+## 1. 需求
+
+### 背景
+`admin-frontend` 新增系统管理与订阅管理分组后，左侧导航项明显增多。当前 `AdminLayout.vue` 的侧边栏仍采用“Logo + ElMenu 直接铺满”的结构，而 `body` 又被全局设置为 `overflow: hidden`。在用户截图所示的小窗口高度下，底部菜单会被直接裁切，导致“礼品卡管理”“系统管理”“支付配置”等入口无法完整访问。
+
+### 目标
+- 修复管理端侧边栏在低视口高度下显示不全的问题。
+- 按用户已确认的方案，保留顶部 Logo/品牌区固定，仅让菜单区独立纵向滚动。
+- 保持现有 Apple 风格后台的导航层级、折叠行为和移动端体验不回退。
+
+### 约束条件
+```yaml
+范围约束: 仅处理 admin 侧边栏在低高度下的可访问性与滚动行为，不扩展菜单信息架构
+技术约束: 继续使用 Vue3 + TypeScript + Element Plus，不新增依赖
+兼容性约束: 需兼容桌面展开态、折叠态以及现有移动端 fixed aside 行为
+视觉约束: 延续 apple/DESIGN.md 与 .helloagents/DESIGN.md 的纯白侧栏 + 单一蓝色激活态体系
+```
+
+### 验收标准
+- [ ] 在窗口高度不足时，侧边栏底部菜单项仍可通过纵向滚动访问完整。
+- [ ] 顶部 Logo/品牌区保持固定，不跟随菜单滚动一起消失。
+- [ ] 折叠态与移动端侧边栏不出现新的遮挡、抖动或布局错位。
+- [ ] `admin-frontend` 执行 `npm run build` 通过。
+
+---
+
+## 2. 方案
+
+### 技术方案
+1. 在 `AdminLayout.vue` 中把侧边栏拆成“固定头部品牌区 + 独立滚动的菜单容器”两层结构，而不是直接让 `ElMenu` 占满整个 `ElAside`。
+2. 为侧边栏与菜单滚动容器补齐 `min-height: 0`、`overflow-y: auto`、底部留白和滚动条细节，解决 flex 子项在固定高度容器中无法正确收缩的问题。
+3. 保持现有 `ElMenu`、`ElSubMenu` 和折叠逻辑不变，确保这次修复是针对根因的最小改动，而不是重写导航实现。
+
+### 影响范围
+```yaml
+涉及模块:
+  - admin-frontend: 更新主布局侧边栏结构与样式，修复低高度下菜单裁切
+  - .helloagents/modules/admin-frontend.md: 记录侧边栏低高度滚动规则
+预计变更文件: 3
+```
+
+### 风险评估
+| 风险 | 等级 | 应对 |
+|------|------|------|
+| Element Plus 菜单在滚动容器中出现高度塌陷或双滚动条 | 中 | 采用独立滚动容器并显式补齐 `min-height: 0` 与内边距，避免只在 `ElMenu` 上追加单点样式 |
+| 移动端 fixed aside 与桌面侧栏样式相互影响 | 中 | 仅在当前侧边栏作用域内增加滚动容器样式，保留现有移动端定位策略 |
+| 构建会刷新 `public/assets/admin` 构建产物 | 低 | 本轮仅完成本地构建验证，不自动代做子模块发布 |
+
+---
+
+## 3. 核心场景
+
+### 场景: 低高度窗口中的侧边栏导航
+**模块**: admin-frontend
+**条件**: 浏览器窗口高度不足以同时容纳品牌区与全部菜单项
+**行为**: 用户在左侧导航区域滚动菜单
+**结果**: 顶部品牌区固定可见，菜单项可完整访问，激活态与分组结构保持正常
+
+---
+
+## 4. 技术决策
+
+### admin-frontend-sidebar-height-overflow#D001: 侧边栏采用“固定品牌区 + 独立滚动菜单区”
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 用户明确选择“顶部 Logo/品牌区固定，仅菜单区域独立纵向滚动”的处理方式。
+**选项分析**:
+| 选项 | 优点 | 缺点 |
+|------|------|------|
+| A: 固定品牌区，菜单区独立滚动 | 保留品牌识别和导航定位，改动集中、体验最稳定 | 需要微调侧栏结构和滚动容器样式 |
+| B: 整个侧边栏整体滚动 | 实现简单 | 品牌区会被滚出视口，低高度下辨识度更差 |
+| C: 低高度自动折叠成图标栏 | 可压缩空间 | 会改变现有导航行为，且不是用户选定方案 |
+**决策**: 选择方案 A
+**理由**: 最符合用户已确认交互，也与当前 Apple 风格后台“固定品牌区 + 稳定导航层级”的设计基线一致。
+**影响**: 影响 `AdminLayout.vue` 侧边栏结构与样式，不涉及 API、路由或业务数据流。
+
+---
+
+## 5. 成果设计
+
+### 设计方向
+- **美学基调**: 克制运营后台 —— 保留纯白侧栏、细边框、轻阴影和单一蓝色激活态，让修复更像“增强可用性”而非“换一套皮肤”
+- **记忆点**: 窗口再矮，顶部品牌区依旧稳定悬停，菜单像独立轨道一样顺滑滚动
+- **参考**: 现有 `apple/DESIGN.md` 与 `.helloagents/DESIGN.md` 的 Apple 风格后台规范
+
+### 视觉要素
+- **配色**: 保持现有 `#ffffff` 侧栏底色、`#0071e3` 激活色和中性文字层级，不引入新强调色
+- **字体**: 延续全局系统字体栈 `--xboard-font-sans`，不新增字体
+- **布局**: 侧栏继续分为顶部品牌区与下方菜单区，但改为明确的上下分层，菜单区获得独立滚动上下文
+- **动效**: 保留当前宽度折叠过渡；滚动本身不增加额外装饰动画
+- **氛围**: 维持轻薄、低噪音的 Apple 化后台质感，仅补齐滚动可达性
+
+### 技术约束
+- **可访问性**: 键盘聚焦与当前菜单激活态不可被滚动修复破坏
+- **响应式**: 桌面低高度、桌面折叠态和移动端 fixed aside 都需保持可用
@@ -0,0 +1,42 @@
+# 任务清单: admin-frontend-sidebar-height-overflow
+
+> **@status:** completed | 2026-04-24 17:05
+
+```yaml
+@feature: admin-frontend-sidebar-height-overflow
+@created: 2026-04-24
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 3 | 0 | 0 | 3 |
+
+---
+
+## 任务列表
+
+- [√] 1. 审查 `admin-frontend/src/layouts/AdminLayout.vue` 当前侧边栏结构与低高度裁切根因，冻结“固定品牌区 + 菜单独立滚动”实现边界 | depends_on: []
+- [√] 2. 在 `admin-frontend/src/layouts/AdminLayout.vue` 中调整侧边栏结构与样式，修复低高度下菜单显示不全问题 | depends_on: [1]
+- [√] 3. 运行 `admin-frontend` 构建验证，并同步 `.helloagents/modules/admin-frontend.md` 与 `CHANGELOG.md` 记录本轮修复 | depends_on: [2]
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-24 16:55 | 方案包初始化 | completed | 已确认采用“顶部品牌区固定，菜单区域独立纵向滚动”的修复策略 |
+| 2026-04-24 16:58 | 根因分析 | completed | 已确认裁切来自 `ElAside` 固定高度 + `ElMenu` 缺少独立滚动上下文，菜单区可滚动高度不足 |
+| 2026-04-24 17:02 | 布局修复 | completed | 已将侧边栏拆为固定品牌区与独立滚动菜单区，并补齐 `min-height: 0` / `overflow-y: auto` 样式 |
+| 2026-04-24 17:07 | 验证与知识同步 | completed | `npm run build` 通过；Playwright 在 1200x540 视口下确认菜单区 `scrollHeight 1020 > clientHeight 442`，滚动到底后可见系统管理与知识库管理入口 |
+
+---
+
+## 执行备注
+
+- 本轮只修复侧边栏低高度可访问性，不调整菜单信息架构与图标分组。
+- 构建验证会刷新 `public/assets/admin` 构建产物，本轮仅完成本地实现与验证，不自动代做子模块发布。
@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 4,
+  "failed": 0,
+  "pending": 0,
+  "total": 4,
+  "done": 4,
+  "percent": 100,
+  "current": "权限组管理真实页、节点页联动与构建验证已完成",
+  "updated_at": "2026-04-24 17:10:00"
+}
@@ -0,0 +1,166 @@
+# 变更提案: admin-frontend-node-group-management
+
+## 元信息
+```yaml
+类型: 功能增强
+方案类型: implementation
+优先级: P1
+状态: 已完成
+创建: 2026-04-24
+```
+
+---
+
+## 1. 需求
+
+### 背景
+`admin-frontend` 的 `#/node-groups` 目前仍是结构化占位页，而用户已经提供了目标截图，明确要求继续完成“权限组管理”真实工作台。现有 Laravel 后端已经开放 `server/group/fetch`、`server/group/save` 与 `server/group/drop`，节点管理页也已接入权限组筛选，但缺少从权限组页进入节点筛选的维护闭环。
+
+### 目标
+- 将 `#/node-groups` 从占位页升级为真实权限组管理页面，支持列表、搜索、添加、编辑、删除。
+- 列表中直接展示权限组 ID、组名称、用户数量、节点数量，并给出符合截图习惯的操作位。
+- 补齐与 `#/nodes` 的联动：从权限组页可以一键带筛选跳转到节点页，节点页也能快速回到权限组维护入口。
+
+### 约束条件
+```yaml
+范围约束: 仅实现 admin-frontend 的权限组前端工作台与节点页联动，不改 Laravel 后端接口行为
+技术约束: 继续使用 Vue3 + TypeScript + Element Plus + 现有 axios/adminClient 栈，不新增第三方状态或表格依赖
+视觉约束: 以用户截图为直接参考，保留 Apple 化后台的克制留白、系统字体与轻量表格节奏，不套用订阅页黑色 Hero
+业务约束: 后端真相源固定为 server/group/fetch、server/group/save、server/group/drop；删除失败原因以前端透传后端文案为准
+```
+
+### 验收标准
+- [√] `#/node-groups` 可以展示真实权限组列表，并支持关键字搜索与分页浏览。
+- [√] 页面支持新增、编辑、删除权限组；新增/编辑使用中央弹窗，删除前有明确确认。
+- [√] 节点数量支持跳转到 `#/nodes` 并自动带入对应权限组筛选；节点页提供回到权限组维护入口的联动按钮。
+- [√] `admin-frontend` 执行 `npm run build` 通过，产物可继续输出到 `public/assets/admin`。
+
+---
+
+## 2. 方案
+
+### 技术方案
+1. 在 `src/types/api.d.ts` 与 `src/api/admin.ts` 中补齐权限组保存请求类型与 `save/delete` 封装。
+2. 新增 `src/utils/nodeGroups.ts`，统一处理权限组计数归一化、本地搜索和摘要计算，避免视图层堆积业务细节。
+3. 重写 `NodeGroupsView.vue`，采用“页头说明 + 紧凑工具条 + 白色表格工作台 + 中央编辑弹窗”的结构贴近截图。
+4. 新增 `NodeGroupEditorDialog.vue` 处理新增/编辑流程；节点数量使用按钮式链接跳转到 `/nodes?group={id}`。
+5. 轻量补齐 `NodesView.vue`：识别路由查询中的权限组筛选，并提供“管理权限组”入口形成维护闭环。
+
+### 影响范围
+```yaml
+涉及模块:
+  - admin-frontend: 权限组管理真实页、节点页筛选联动、API/类型/工具层补齐
+  - .helloagents: 方案包、模块文档、CHANGELOG 与状态证据同步
+预计变更文件: 8
+```
+
+### 风险评估
+| 风险 | 等级 | 应对 |
+|------|------|------|
+| 后端删除接口因用户/节点/订阅占用返回失败 | 中 | 前端保持后端错误透传，不自行猜测失败原因 |
+| 节点页联动仅靠前端路由查询，若权限组已删除会产生空筛选 | 低 | 页面加载后校验 query 对应分组是否存在，不存在则自动回退为“全部权限组” |
+| 新页面过度复用黑色 Hero 会与截图不一致 | 中 | 以截图为最高优先级，改为轻量标题区 + 高密度表格，不强行套用订阅页首屏模式 |
+
+---
+
+## 3. 技术设计（可选）
+
+### API设计
+#### GET /server/group/fetch
+- **请求**: 无
+- **响应**: `AdminServerGroupItem[]`，包含 `id`、`name`、`users_count`、`server_count`
+
+#### POST /server/group/save
+- **请求**: `{ id?: number, name: string }`
+- **响应**: `boolean`
+
+#### POST /server/group/drop
+- **请求**: `{ id: number }`
+- **响应**: `boolean`
+
+### 数据模型
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | number | 权限组 ID |
+| name | string | 权限组名称 |
+| users_count | number | 绑定用户数量 |
+| server_count | number | 绑定节点数量 |
+
+---
+
+## 4. 核心场景
+
+### 场景: 运营新增权限组
+**模块**: admin-frontend
+**条件**: 管理员进入 `#/node-groups`
+**行为**: 点击“添加权限组”，填写组名称并提交
+**结果**: 列表刷新并出现新的权限组记录
+
+### 场景: 运营从权限组进入节点排查
+**模块**: admin-frontend
+**条件**: 某权限组已存在关联节点
+**行为**: 在权限组列表点击“节点数量”跳转
+**结果**: `#/nodes` 自动带入对应权限组筛选，仅展示该组关联节点
+
+---
+
+## 5. 技术决策
+
+### admin-frontend-node-group-management#D001: 权限组页改为截图导向的轻量工作台，而不是延续黑色 Hero
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 用户提供的参考图就是目标界面，重点是轻量标题区、工具条和高密度表格。
+**选项分析**:
+| 选项 | 优点 | 缺点 |
+|------|------|------|
+| A: 延续节点/订阅页的黑色 Hero | 与部分已有页面一致 | 与当前截图不符，页面信息密度被拉低 |
+| B: 采用截图式轻量工作台 | 更贴近用户目标，便于高频运营维护 | 与部分页面的 Hero 结构不完全统一 |
+**决策**: 选择方案 B
+**理由**: 本轮任务已有明确视觉参考，参考优先级高于通用页面套路。
+**影响**: `NodeGroupsView.vue` 的首屏结构与样式策略
+
+### admin-frontend-node-group-management#D002: 新增与编辑复用同一个中央弹窗
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 后端保存接口统一为 `server/group/save`，截图也展示了中央编辑弹窗。
+**选项分析**:
+| 选项 | 优点 | 缺点 |
+|------|------|------|
+| A: 新增/编辑拆成两个独立组件 | 职责更独立 | 代码重复，交互不连续 |
+| B: 统一弹窗组件按模式切换 | 与后端接口一致，界面行为稳定 | 组件需处理回填逻辑 |
+**决策**: 选择方案 B
+**理由**: 能最小化重复代码，同时贴合截图中的工作流。
+**影响**: `NodeGroupEditorDialog.vue` 的设计与表单逻辑
+
+### admin-frontend-node-group-management#D003: 节点数量列承担“跳转到节点筛选”联动入口
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 用户选择了“完整闭环”，不仅要做权限组页，还要补齐节点页联动。
+**选项分析**:
+| 选项 | 优点 | 缺点 |
+|------|------|------|
+| A: 只做权限组页 CRUD | 实现最小 | 无法形成节点维护闭环 |
+| B: 在节点数量列加入带筛选跳转，并让节点页识别 query | 联动直接、改动范围可控 | 需要额外处理路由筛选同步 |
+**决策**: 选择方案 B
+**理由**: 这是当前范围内成本最低、用户价值最高的联动方式。
+**影响**: `NodeGroupsView.vue`、`NodesView.vue`
+
+---
+
+## 6. 成果设计
+
+### 设计方向
+- **美学基调**: 精密运营台账风——保留 Apple 化后台的轻薄分区与系统字体，但将视觉重心收敛到“标题、工具条、表格、弹窗”四个层级，避免营销感首屏
+- **记忆点**: 大面积留白中的细线表格与圆角操作按钮，让“节点数量可跳转”的数据列成为页面最有识别度的互动点
+- **参考**: 用户提供的权限组管理截图与编辑弹窗截图
+
+### 视觉要素
+- **配色**: 以 `#ffffff` / `#f5f5f7` 为背景层，正文使用 `--xboard-text-strong` 与 `--xboard-text-secondary`，交互强调保持 `#0071e3`
+- **字体**: 延续项目现有系统字体栈，不额外引入新字体；通过更克制的字号梯度和字重对比强化“台账式”阅读效率
+- **布局**: 顶部使用轻标题区，正文直接进入紧凑工具条与全宽表格；编辑器保持中央对话框，不用抽屉
+- **动效**: 仅保留按钮 hover、表格行内操作反馈、分页与弹窗开合的默认 Element Plus 过渡
+- **氛围**: 依靠细边框、极轻阴影、圆角输入框与足够留白构成“干净但不空”的后台质感
+
+### 技术约束
+- **可访问性**: 搜索框、主按钮、编辑/删除操作与节点跳转入口都要保留可见焦点；危险删除继续使用明确确认文案
+- **响应式**: 桌面优先显示完整表格；窄屏下工具条允许换行，底部分页与统计信息可纵向堆叠
@@ -0,0 +1,43 @@
+# 任务清单: admin-frontend-node-group-management
+
+> **@status:** completed | 2026-04-24 17:11
+
+```yaml
+@feature: admin-frontend-node-group-management
+@created: 2026-04-24
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 4 | 0 | 0 | 4 |
+
+---
+
+## 任务列表
+
+- [√] 1. 梳理 `server/group/*` 后端接口、现有 `admin-frontend` 设计契约与节点页联动边界 | depends_on: []
+- [√] 2. 补齐权限组 API / 类型 / 工具层，并实现新增 / 编辑弹窗 | depends_on: [1]
+- [√] 3. 重写 `NodeGroupsView` 真实工作台，并补齐 `NodesView` 的权限组筛选联动入口 | depends_on: [1, 2]
+- [√] 4. 运行 `admin-frontend` 构建验证，更新 `.helloagents` 文档与交付证据 | depends_on: [2, 3]
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-24 17:00 | 方案包初始化 | completed | 用户已选择“完整闭环”，本轮范围包含权限组真实页与节点页联动 |
+| 2026-04-24 17:04 | 页面实现 | completed | 已补齐权限组 API、工具层、中央编辑弹窗与真实列表工作台 |
+| 2026-04-24 17:07 | 联动实现 | completed | 节点数量列现可跳转 `#/nodes?group={id}`，节点页新增“管理权限组”入口 |
+| 2026-04-24 17:10 | 构建与文档同步 | completed | `npm run build` 通过，并已更新 `.helloagents` 文档与变更日志 |
+
+---
+
+## 执行备注
+
+- 当前根仓存在其他未归档方案包与历史改动，本轮仅增量修改权限组管理及节点页联动相关文件。
+- `public/assets/admin` 为前端产物子模块；构建通过后需要同时复核根仓与子模块状态。
@@ -0,0 +1,49 @@
+{
+  "updatedAt": "2026-04-24T09:09:46.384Z",
+  "version": 1,
+  "source": "manual",
+  "originCommand": "generic-r2",
+  "verifyMode": "test-first",
+  "reviewerFocus": [
+    "礼品卡管理整体结构是否贴近用户提供的四页签后台截图",
+    "模板抽屉字段分组是否与截图和现有后端 JSON 结构一致"
+  ],
+  "testerFocus": [
+    "礼品卡管理是否真实连接 gift-card/templates、codes、usages、statistics、types 接口",
+    "模板新增编辑是否能正确序列化 conditions、rewards、limits、special_config",
+    "兑换码管理是否支持生成、导出、复制、启停、编辑和删除主链路"
+  ],
+  "ui": {
+    "required": true,
+    "designContract": true,
+    "sourcePriority": [
+      "requirements.md",
+      ".helloagents/DESIGN.md",
+      "hello-ui"
+    ],
+    "styleAdvisor": {
+      "required": false,
+      "reason": "",
+      "focus": []
+    },
+    "visualValidation": {
+      "required": true,
+      "reason": "礼品卡管理属于整页新增的真实后台业务页，需要确认四页签导航、模板表格、模板抽屉和统计卡片在代码结构上与目标截图及 Apple 化后台契约一致。",
+      "screens": [
+        "#/subscriptions/gift-cards desktop"
+      ],
+      "states": [
+        "模板管理默认加载完成态",
+        "模板新增抽屉展开态",
+        "兑换码管理列表态",
+        "统计数据总览态"
+      ]
+    }
+  },
+  "advisor": {
+    "required": false,
+    "reason": "",
+    "focus": [],
+    "preferredSources": []
+  }
+}
@@ -0,0 +1,59 @@
+# admin-frontend 礼品卡管理首版交付 — 实施规划
+
+## 目标与范围
+- 在现有订阅管理分组中补齐礼品卡管理真实页，替换原先的禁用入口。
+- 页面聚焦“礼品卡运营工作台”主链路：建模板、生成兑换码、查看使用记录、追踪统计数据。
+
+## 架构与实现策略
+- 在 `AdminLayout` 中开放 `/subscriptions/gift-cards` 导航入口，并在路由中新增对应页面。
+- 新增 `GiftCardsView` 作为整页工作台，整体结构参考用户截图：
+  - 顶部标题与说明
+  - 四段式分段导航（模板管理 / 兑换码管理 / 使用记录 / 统计数据）
+  - 每个页签独立的筛选条、表格/卡片内容与操作按钮
+- 新增两个业务弹层组件：
+  - `GiftCardTemplateDrawer.vue`：负责模板新增与编辑
+  - `GiftCardCodeBatchDialog.vue`：负责批量生成兑换码
+- 在 `src/utils/giftCards.ts` 中集中处理：
+  - 类型/状态映射
+  - 模板表单序列化与反序列化
+  - 金额(元)/流量(GB)/倍率/日期等展示与提交格式转换
+  - 本地搜索筛选与统计卡片整理
+- API 层在 `src/api/admin.ts` 中新增礼品卡接口封装；类型定义统一补到 `src/types/api.d.ts`。
+
+## 完成定义
+- 侧边栏中的“礼品卡管理”不再是禁用入口，能正常进入 `#/subscriptions/gift-cards`。
+- 模板管理页可真实连接模板列表与 CRUD 接口，支持搜索、筛选、启停与删除。
+- 模板抽屉可完整编辑截图展示的主要字段分组，并正确序列化为后端 `conditions / rewards / limits / special_config` 结构。
+- 兑换码页可真实连接兑换码列表，支持批量生成、复制、启停、导出当前批次、编辑有效期/次数与删除。
+- 使用记录与统计数据页可真实连接后端数据，不使用硬编码假数据。
+
+## 文件结构
+- `admin-frontend/src/layouts/AdminLayout.vue`
+- `admin-frontend/src/router/index.ts`
+- `admin-frontend/src/api/admin.ts`
+- `admin-frontend/src/types/api.d.ts`
+- `admin-frontend/src/utils/giftCards.ts`
+- `admin-frontend/src/views/subscriptions/GiftCardsView.vue`
+- `admin-frontend/src/views/subscriptions/GiftCardsView.scss`
+- `admin-frontend/src/views/subscriptions/GiftCardTemplateDrawer.vue`
+- `admin-frontend/src/views/subscriptions/GiftCardCodeBatchDialog.vue`
+
+## UI / 设计约束
+- 页面采用“标题说明 + 轻量分段页签 + 白色工作台”的 Apple 化运营后台节奏，不额外叠加夸张 hero 或营销化视觉。
+- 四个页签保持统一信息架构与表格密度，让用户能快速在模板、兑换码、记录、统计之间切换。
+- 模板抽屉使用分组 section 和双列表单布局，对齐截图中的信息分区；在窄屏下自动堆叠为单列。
+- 状态标签、奖励摘要、统计卡片继续沿用单一蓝色强调和语义色状态胶囊，不引入新配色体系。
+
+## 风险与验证
+- 风险 1：模板表单字段较多，若直接散落在组件内易导致提交结构和展示结构不一致，因此统一收敛到 `src/utils/giftCards.ts`。
+- 风险 2：兑换码列表接口不支持关键词搜索，需要前端在当前拉取结果上做本地搜索，并明确这是列表内过滤。
+- 风险 3：本地环境缺少真实后台登录态时，只能做结构与构建验证，不能替代完整联调。
+- 验证方式：
+  - `npm run build`
+  - 代码级结构自检 `#/subscriptions/gift-cards`
+  - 结构化视觉验收记录（无浏览器工具时以 code inspection 说明边界）
+
+## 决策记录
+- [2026-04-24] 礼品卡管理采用单页四段式导航，而不是四个独立路由，以贴近用户截图中的运营切换路径。
+- [2026-04-24] 模板抽屉使用分组式大表单，不把复杂字段塞进居中弹窗，以保证高密度配置仍可读。
+- [2026-04-24] 兑换码导出先按“当前选中批次”提供显式出口，不额外扩展复杂多选批量导出流程。
@@ -0,0 +1,49 @@
+# admin-frontend 礼品卡管理首版交付 — 需求
+
+确认后冻结，执行阶段不可修改。如需变更必须回到设计阶段重新确认。
+
+## 核心目标
+- 在 `admin-frontend` 中开放“订阅管理 / 礼品卡管理”入口，不再保留禁用态。
+- 参考用户提供的 5 张截图，交付礼品卡管理真实工作台，覆盖模板管理、兑换码管理、使用记录与统计数据四个页签。
+- 保持 `apple/DESIGN.md` 与 `.helloagents/DESIGN.md` 定义的 Apple 化后台视觉语言，同时优先贴近截图中的高密度运营视图与轻量分段导航。
+
+## 功能边界
+- 必须实现 `#/subscriptions/gift-cards` 真实页面。
+- 页面必须包含：
+  - 顶部标题说明与四段式页签导航
+  - 模板管理列表、搜索、类型/状态筛选、显隐切换、新增/编辑、删除
+  - 模板新增/编辑大表单，覆盖基础配置、奖励内容、使用条件、使用限制、特殊配置、显示效果
+  - 兑换码管理列表、模板/状态筛选、复制、启停、编辑、删除、批量生成、批次导出
+  - 使用记录列表与用户邮箱搜索
+  - 统计数据总览，至少展示模板总数、活跃模板数、兑换码总数、已使用兑换码
+- 必须接入现有 Laravel 管理接口：
+  - `GET /gift-card/templates`
+  - `POST /gift-card/create-template`
+  - `POST /gift-card/update-template`
+  - `POST /gift-card/delete-template`
+  - `POST /gift-card/generate-codes`
+  - `GET /gift-card/codes`
+  - `POST /gift-card/toggle-code`
+  - `GET /gift-card/export-codes`
+  - `POST /gift-card/update-code`
+  - `POST /gift-card/delete-code`
+  - `GET /gift-card/usages`
+  - `GET /gift-card/statistics`
+  - `GET /gift-card/types`
+
+## 非目标
+- 本轮不改造 Laravel 礼品卡后端逻辑、校验规则或数据库结构。
+- 本轮不实现用户端礼品卡兑换体验。
+- 本轮不引入复杂图表库，只使用现有栈完成统计展示。
+
+## 技术约束
+- 技术栈固定为 `Vue 3 + TypeScript + Vite + Element Plus`。
+- 后端真相源以仓库内 `App\Http\Controllers\V2\Admin\GiftCardController`、`GiftCardTemplate`、`GiftCardCode` 与 `GiftCardUsage` 为准。
+- 构建验证使用 `admin-frontend/package.json` 中已有 `npm run build`。
+- 构建产物继续输出到 `public/assets/admin` 子模块。
+
+## 质量要求
+- 礼品卡页面需要对齐截图中的运营后台结构：白色工作台、轻量页签、克制筛选条、高密度表格。
+- 表单字段需要覆盖加载、保存、取消、校验失败与成功提示等基本状态。
+- 金额、流量、时间与倍率展示必须按人类可读方式格式化，不直接暴露原始后端数值。
+- 最终至少完成一次构建验证，并留下结构化视觉验收与交付证据。
@@ -0,0 +1,14 @@
+# admin-frontend 礼品卡管理首版交付 — 任务分解
+
+## 任务列表
+- [x] 任务1：补齐礼品卡管理方案与合同产物（涉及文件：`.helloagents/plans/202604241703_admin-frontend-gift-card-management/*`；完成标准：存在需求、方案、任务与合同文件；验证方式：文件检查）
+- [x] 任务2：开放礼品卡导航与路由入口（涉及文件：`admin-frontend/src/layouts/AdminLayout.vue`、`admin-frontend/src/router/index.ts`；完成标准：侧边栏可进入 `#/subscriptions/gift-cards`；验证方式：`npm run build`）
+- [x] 任务3：补齐礼品卡 API、类型与工具层（涉及文件：`admin-frontend/src/api/admin.ts`、`admin-frontend/src/types/api.d.ts`、`admin-frontend/src/utils/giftCards.ts`；完成标准：前端可消费 `gift-card/*` 接口并统一完成字段映射；验证方式：`npm run build`）
+- [x] 任务4：实现礼品卡管理主页面（涉及文件：`admin-frontend/src/views/subscriptions/GiftCardsView.vue`、`admin-frontend/src/views/subscriptions/GiftCardsView.scss`；完成标准：四个页签支持真实数据展示、搜索筛选、表格/统计渲染与关键操作入口；验证方式：`npm run build`）
+- [x] 任务5：实现模板抽屉与兑换码生成弹层（涉及文件：`admin-frontend/src/views/subscriptions/GiftCardTemplateDrawer.vue`、`admin-frontend/src/views/subscriptions/GiftCardCodeBatchDialog.vue`；完成标准：支持模板新增/编辑与兑换码批量生成；验证方式：`npm run build`）
+- [x] 任务6：完成验证与知识库同步（涉及文件：`.helloagents/CHANGELOG.md`、`.helloagents/context.md`、`.helloagents/modules/admin-frontend.md`、`.helloagents/.ralph-visual.json`、`.helloagents/.ralph-closeout.json`；完成标准：构建通过、知识库更新、交付证据写入；验证方式：命令输出 + 证据文件）
+
+## 进度
+- [x] 已确认礼品卡管理按完整四页签首版推进。
+- [x] 已完成礼品卡管理真实页面、模板抽屉、兑换码生成弹层与后端接口接入。
+- [x] 已完成构建验证，待输出最终交付摘要。
@@ -7,6 +7,9 @@

 | 时间戳 | 名称 | 类型 | 涉及模块 | 决策 | 结果 |
 |--------|------|------|---------|------|------|
+| 202604241703 | admin-frontend-gift-card-management | implementation | admin-frontend | admin-frontend-gift-card-management#D001,#D002,#D003 | ✅完成 |
+| 202604241659 | admin-frontend-node-group-management | implementation | admin-frontend | admin-frontend-node-group-management#D001,#D002,#D003 | ✅完成 |
+| 202604241655 | admin-frontend-sidebar-height-overflow | - | - | - | ✅完成 |
 | 202604241620 | admin-frontend-order-management | implementation | admin-frontend | admin-frontend-order-management#D001,#D002,#D003 | ✅完成 |
 | 202604241558 | admin-frontend-payment-management | implementation | admin-frontend | admin-frontend-payment-management#D001,#D002,#D003 | ✅完成 |
 | 202604241553 | admin-frontend-plugin-management | implementation | admin-frontend | admin-frontend-plugin-management#D001,#D002,#D003 | ✅完成 |
@@ -29,6 +32,8 @@
 ## 按月归档

 ### 2026-04
+- [202604241703_admin-frontend-gift-card-management](./2026-04/202604241703_admin-frontend-gift-card-management/) - 开放“礼品卡管理”入口，交付模板管理、兑换码管理、使用记录与统计数据四页签工作台，并接入真实 gift-card 接口
+- [202604241659_admin-frontend-node-group-management](./2026-04/202604241659_admin-frontend-node-group-management/) - 将 `#/node-groups` 从占位页升级为真实权限组管理工作台，并补齐到 `#/nodes` 的权限组筛选联动
 - [202604241620_admin-frontend-order-management](./2026-04/202604241620_admin-frontend-order-management/) - 开放“订单管理”入口，交付真实订单列表、筛选、分配订单、详情抽屉、手动支付与佣金状态维护
 - [202604241558_admin-frontend-payment-management](./2026-04/202604241558_admin-frontend-payment-management/) - 将 `#/system/payments` 从占位页升级为真实支付配置工作台，接入支付方式列表、动态配置抽屉、启停、删除与排序
 - [202604241553_admin-frontend-plugin-management](./2026-04/202604241553_admin-frontend-plugin-management/) - 将 `#/system/plugins` 从占位页升级为真实插件管理工作台，接入插件列表、筛选、上传、安装、启停、升级、卸载，以及 README / 动态配置抽屉
@@ -26,7 +26,14 @@
  - `plan/fetch`
 - 管理端节点管理现已接入:
  - `server/manage/getNodes`
+  - `server/manage/save`
+  - `server/manage/sort`
  - `server/group/fetch`
+  - `server/group/save`
+  - `server/group/drop`
+  - `server/route/fetch`
+  - `server/route/save`
+  - `server/route/drop`
  - `server/manage/update`
  - `server/manage/copy`
  - `server/manage/drop`
@@ -44,6 +51,20 @@
  - `order/paid`
  - `order/cancel`
  - `order/update`
+- 管理端礼品卡管理现已接入:
+  - `gift-card/templates`
+  - `gift-card/create-template`
+  - `gift-card/update-template`
+  - `gift-card/delete-template`
+  - `gift-card/generate-codes`
+  - `gift-card/codes`
+  - `gift-card/toggle-code`
+  - `gift-card/export-codes`
+  - `gift-card/update-code`
+  - `gift-card/delete-code`
+  - `gift-card/usages`
+  - `gift-card/statistics`
+  - `gift-card/types`
 - 管理端公告管理现已接入:
  - `notice/fetch`
  - `notice/save`
@@ -71,7 +92,8 @@
 ## 开发约定

 - 管理端路由使用 Hash 模式
- 管理端当前业务路由包含 `/dashboard`、`/users`、`/tickets`、`/nodes`、`/node-groups`、`/node-routes`、`/subscriptions/plans`、`/subscriptions/orders`、`/subscriptions/coupons`、`/system/config`、`/system/notices` 与 `/system/payments`
+- 管理端当前业务路由包含 `/dashboard`、`/users`、`/tickets`、`/nodes`、`/node-groups`、`/node-routes`、`/subscriptions/plans`、`/subscriptions/orders`、`/subscriptions/coupons`、`/subscriptions/gift-cards`、`/system/config`、`/system/notices`、`/system/payments`、`/system/plugins`、`/system/themes` 与 `/system/knowledge`
+- `#/nodes` 当前已升级为真实节点工作台：支持搜索、显隐切换、复制、删除，以及 11 种协议的新增 / 编辑弹窗和排序对话框
 - Bearer Token 存储于 `sessionStorage/localStorage`
 - `admin-frontend` 的视觉方向当前以 Apple 风格为基线，优先纯色分区、系统字体栈和低装饰成本

@@ -4,7 +4,7 @@

 - 提供 Vue3 管理端登录页、认证状态、路由守卫和主布局
 - 封装管理端统计/系统状态、用户管理、节点管理、套餐管理和系统配置接口
- 渲染后台仪表盘、用户管理工作台、节点管理工作台、订阅套餐管理页、系统配置页、主题管理页、插件管理工作台、公告管理工作台、支付配置工作台，以及预留的工单管理入口
+- 渲染后台仪表盘、用户管理工作台、节点管理工作台、路由管理工作台、订阅套餐 / 订单 / 优惠券 / 礼品卡管理页、系统配置页、主题管理页、插件管理工作台、公告管理工作台、支付配置工作台，以及工单管理入口

 ## 行为规范

@@ -16,18 +16,28 @@
 - 仪表盘“作业详情”支持打开失败作业报错弹窗，集中查看 Horizon 失败作业的报错摘要、失败时间与队列信息
 - 仪表盘“节点流量排行 / 用户流量排行”均支持独立的 `10个 / 20个` 显示切换，长列表固定在面板内滚动，避免首页高度失控
 - `stat/getTrafficRank` 现支持 `limit=10|20`，前端会按当前排行面板的显示数量重新请求；24h 口径也继续显示涨跌百分比
+- `stat/getTrafficRank` 在 `24h` 口径下会按“昨天同日”统计做涨跌对比，避免日统计表因 `record_at=00:00` 被秒级窗口错位后全部回落为 `0%`
 - 仪表盘 Hero 区提供“刷新全部数据”入口，统一触发总览、趋势、排行和系统状态刷新，并在页面内展示最近一次刷新时间
 - 用户管理页通过真实后端 `user/fetch`、`user/update`、`user/generate`、`user/resetSecret`、`user/destroy` 与 `plan/fetch` 完成数据读写
 - 新增用户时采用“先 generate，后按邮箱回查并 update”的两段式流程，以兼容后端基础创建接口
- 节点管理页通过真实后端 `server/manage/getNodes` 与 `server/group/fetch` 获取列表，并通过 `server/manage/update`、`server/manage/copy`、`server/manage/drop` 完成首批行级操作
- 节点相关导航入口固定归入“节点管理”分组；`/node-groups` 与 `/node-routes` 本轮先交付结构化占位页，不伪装为完整功能
- 订阅管理新增独立“订阅管理”侧边栏分组，现已完整实现 `#/subscriptions/plans`、`#/subscriptions/orders` 与 `#/subscriptions/coupons`；礼品卡管理仍保留禁用态
+- 节点管理页通过真实后端 `server/manage/getNodes`、`server/group/fetch` 与 `server/route/fetch` 获取列表 / 关联数据，并通过 `server/manage/save`、`server/manage/sort`、`server/manage/update`、`server/manage/copy`、`server/manage/drop` 完成新增、编辑、排序与行级操作
+- 节点新增 / 编辑采用统一中央大弹窗，支持 `Shadowsocks / VMess / Trojan / Hysteria / VLess / TUIC / SOCKS / Naive / HTTP / Mieru / AnyTLS` 11 种协议的首版动态配置表单
+- 节点排序采用本地草稿 + 上移 / 下移模式，保存时向 `server/manage/sort` 提交 `{ id, order }[]` 顺序 payload
+- 权限组管理页使用真实后端 `server/group/fetch`、`server/group/save` 与 `server/group/drop`，支持关键字搜索、新增/编辑中央弹窗、删除确认，以及从节点数量列跳转到 `#/nodes?group={id}` 的筛选联动
+- 路由管理页使用真实后端 `server/route/fetch`、`server/route/save` 与 `server/route/drop`，支持路由列表、关键词搜索、新增/编辑中央弹窗、删除与动作值展示
+- 路由管理页的节点引用摘要由 `server/manage/getNodes` 返回的 `route_ids` 推导，不在前端伪造额外接口
+- 节点页会读取路由查询中的 `group` 参数并自动应用对应权限组筛选，同时提供“管理权限组”入口回到权限组页；`/node-routes` 已升级为真实工作台
+- 订阅管理新增独立“订阅管理”侧边栏分组，现已完整实现 `#/subscriptions/plans`、`#/subscriptions/orders`、`#/subscriptions/coupons` 与 `#/subscriptions/gift-cards`
 - 套餐管理页使用真实后端 `plan/fetch`、`plan/save`、`plan/update`、`plan/drop`、`plan/sort` 与 `server/group/fetch`
+- 侧边栏在低窗口高度下采用“顶部品牌区固定 + 菜单区独立纵向滚动”的结构，避免新增分组后底部导航入口被直接裁切
 - 套餐管理页渲染 `ElSwitch` 前，会先把 `show / sell / renew` 归一化成布尔值；开关事件若新旧值相同则直接短路，避免初始化阶段误写后台状态
 - 套餐说明编辑采用轻量 Markdown/HTML 编辑器与预览模式，不引入额外富文本依赖
 - 订单管理页使用真实后端 `order/fetch`、`order/detail`、`order/assign`、`order/paid`、`order/cancel` 与 `order/update`，支持订单列表、类型/周期/状态筛选、详情抽屉、手动分配、人工标记已支付与佣金状态维护
 - 订单金额、佣金金额与相关拆解字段以“分”为后端真相源，前端统一在 `src/utils/orders.ts` 中格式化为“元”展示，避免后台金额口径混乱
 - 优惠券管理页使用真实后端 `coupon/fetch`、`coupon/generate`、`coupon/update` 与 `coupon/drop`，支持本地搜索、类型筛选、启停、删除与弹窗式新增/编辑
+- 礼品卡管理页使用真实后端 `gift-card/templates`、`gift-card/create-template`、`gift-card/update-template`、`gift-card/delete-template`、`gift-card/generate-codes`、`gift-card/codes`、`gift-card/toggle-code`、`gift-card/export-codes`、`gift-card/update-code`、`gift-card/delete-code`、`gift-card/usages`、`gift-card/statistics` 与 `gift-card/types`
+- 礼品卡工作台采用单页四页签结构，覆盖模板管理、兑换码管理、使用记录和统计数据；模板编辑使用分组式大抽屉，兑换码生成使用独立对话框
+- 礼品卡模板的 `conditions / rewards / limits / special_config` 映射统一收敛到 `src/utils/giftCards.ts`，避免表单展示结构与提交 JSON 结构漂移
 - 优惠券编辑弹窗支持金额/比例两种优惠类型、有效期范围、批量生成、自定义券码、指定周期与指定订阅限制
 - 系统管理新增独立“系统管理”侧边栏分组，当前已完整实现 `#/system/config`、`#/system/themes`、`#/system/plugins`、`#/system/notices`、`#/system/payments` 与 `#/system/knowledge`
 - 系统配置页使用真实后端 `config/fetch`、`config/save`、`config/testSendMail` 与 `config/setTelegramWebhook`，并按站点、安全、订阅、邀请佣金、节点、邮件、Telegram、APP、订阅模板 9 个分组组织长表单
@@ -42,6 +52,7 @@
 - 支付编辑抽屉根据所选支付接口动态拉取真实配置字段，不在前端写死 EPay / TokenPay 等网关表单；通知地址继续以后端拼接结果为准
 - 知识库管理页使用真实后端 `knowledge/fetch`、`knowledge/getCategory`、`knowledge/save`、`knowledge/show`、`knowledge/drop` 与 `knowledge/sort`，支持标题搜索、分类筛选、显隐切换、编辑弹窗、删除与排序模式
 - 知识编辑弹窗继续使用轻量 Markdown/HTML 工具栏，不引入额外富文本依赖；编辑时会单独请求详情补齐 `body / language`
+- `#/system/knowledge` 当前直接渲染 `SystemKnowledgeView` 真实页面，不再回退 `SystemPlaceholderView`
 - 当前首页视觉基线为 Apple 风格：纯色分区、系统字体栈、单一蓝色强调和轻量层次
 - 性能优化优先级高于装饰性表达，避免远程字体、全局模糊背景和固定特效层

@@ -51,12 +62,15 @@
 - 依赖 `src/utils/users.ts` 负责用户管理表单转换、筛选组装和状态计算
 - 依赖 `src/utils/plans.ts` 负责套餐价格、说明渲染、排序与表单转换
 - 依赖 `src/utils/orders.ts` 负责订单金额换算、状态映射、周期标签与筛选参数组装
+- 依赖 `src/utils/nodeGroups.ts` 负责权限组计数归一化、本地搜索与摘要计算
 - 依赖 `src/utils/coupons.ts` 负责优惠券类型映射、时间范围转换、过期状态计算与表单序列化
+- 依赖 `src/utils/giftCards.ts` 负责礼品卡类型/状态映射、模板表单序列化、金额/流量换算与本地筛选逻辑
 - 依赖 `src/utils/themes.ts` 负责主题列表排序、动态配置默认值回填与序列化
 - 依赖 `src/utils/plugins.ts` 负责插件状态判断、README 渲染、筛选与动态配置表单序列化
 - 依赖 `src/utils/payments.ts` 负责支付方式归一化、搜索过滤、排序移动与动态配置序列化
 - 依赖 `src/utils/knowledge.ts` 负责知识库分类、Markdown 渲染、过滤与表单转换
 - 依赖 `src/utils/notices.ts` 负责公告表单转换、内容摘要、排序与显示字段归一化
 - 依赖 `src/utils/systemConfig.ts` 负责系统配置字段元信息、默认值、回填与保存序列化
+- 依赖 `src/utils/routes.ts` 负责路由动作映射、匹配规则序列化、节点引用摘要与搜索过滤
 - 依赖 Laravel 注入的 `window.settings`
 - 构建输出到 `public/assets/admin`
@@ -7,5 +7,5 @@
  "done": 4,
  "percent": 100,
  "current": "知识库管理页已完成并通过构建验证",
-  "updated_at": "2026-04-24 16:24:00"
+  "updated_at": "2026-04-24 17:03:49"
 }
@@ -1,6 +1,6 @@
 # 任务清单: admin-frontend-knowledge-management

-> **@status:** completed | 2026-04-24 16:24
+> **@status:** completed | 2026-04-24 17:03

 ```yaml
@feature: admin-frontend-knowledge-management
@@ -31,9 +31,9 @@
 | 时间 | 任务 | 状态 | 备注 |
 |------|------|------|------|
 | 2026-04-24 16:10 | 方案包初始化 | completed | 用户已确认采用轻量 Markdown 编辑器方案 |
-| 2026-04-24 16:18 | 页面实现 | completed | 已接入知识列表、分类筛选、编辑弹窗、显隐切换与排序对话框 |
-| 2026-04-24 16:22 | 构建验证 | completed | `admin-frontend` 执行 `npm run build` 通过，并输出知识库页面产物 |
-| 2026-04-24 16:24 | 文档同步 | completed | 已更新 CHANGELOG、模块文档与状态快照 |
+| 2026-04-24 16:18 | 页面实现 | completed | 已补齐知识列表、分类筛选、详情编辑弹窗、显隐切换、删除与排序对话框，并将 `/system/knowledge` 从占位页切换为真实页面 |
+| 2026-04-24 17:01 | 构建验证 | completed | `admin-frontend` 重新执行 `npm run build` 通过，并刷新 `public/assets/admin` 最新知识库页面产物 |
+| 2026-04-24 17:03 | 文档同步 | completed | 已更新 CHANGELOG、模块文档、方案包时间戳与状态快照，修正文档先于代码落地的不一致 |

 ---

@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 4,
+  "failed": 0,
+  "pending": 0,
+  "total": 4,
+  "done": 4,
+  "percent": 100,
+  "current": "路由管理真实工作台、节点引用摘要与构建验证已完成",
+  "updated_at": "2026-04-24 17:08:00"
+}
@@ -0,0 +1,49 @@
+{
+  "updatedAt": "2026-04-24T09:01:00.000Z",
+  "version": 1,
+  "source": "R2",
+  "originCommand": "design",
+  "verifyMode": "review-first",
+  "reviewerFocus": [
+    "路由管理页面是否贴近用户截图的 Apple 风格后台结构",
+    "列表、编辑弹窗与节点引用摘要是否覆盖用户本轮确认的范围",
+    "节点管理其他页面与导航边界是否未被误改"
+  ],
+  "testerFocus": [
+    "路由列表是否真实连接 /server/route/fetch",
+    "新增编辑是否真实连接 /server/route/save，删除是否连接 /server/route/drop",
+    "节点引用摘要是否由 /server/manage/getNodes 的 route_ids 正确推导，且 admin-frontend 构建通过"
+  ],
+  "ui": {
+    "required": true,
+    "designContract": true,
+    "sourcePriority": [
+      "plan.md",
+      ".helloagents/DESIGN.md",
+      "hello-ui"
+    ],
+    "styleAdvisor": {
+      "required": false,
+      "reason": "",
+      "focus": []
+    },
+    "visualValidation": {
+      "required": true,
+      "reason": "路由管理属于真实后台 CRUD 页，需要确认列表页与编辑弹窗符合 Apple 风格后台契约，并补足节点引用摘要可读性",
+      "screens": [
+        "#/node-routes desktop",
+        "#/node-routes editor dialog"
+      ],
+      "states": [
+        "路由列表加载完成态",
+        "新增/编辑弹窗态"
+      ]
+    }
+  },
+  "advisor": {
+    "required": false,
+    "reason": "",
+    "focus": [],
+    "preferredSources": []
+  }
+}
@@ -0,0 +1,101 @@
+# 变更提案: 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` 才显示并做非空校验。
+**理由**: 能与后端契约、用户截图和运营认知保持一致，降低表单噪音。
@@ -0,0 +1,43 @@
+# 任务清单: admin-frontend-node-route-management
+
+> **@status:** completed | 2026-04-24 17:08
+
+```yaml
+@feature: admin-frontend-node-route-management
+@created: 2026-04-24
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 4 | 0 | 0 | 4 |
+
+---
+
+## 任务列表
+
+- [√] 1. 梳理路由管理后端接口、字段边界与当前节点管理设计契约
+- [√] 2. 实现路由 API/类型/工具层与真实列表页面
+- [√] 3. 实现路由编辑弹窗、删除流程与节点引用摘要
+- [√] 4. 运行 `admin-frontend` 构建验证，并同步 `.helloagents` 记录
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-24 17:01 | 方案包初始化 | completed | 用户选择“CRUD 首版 + 节点引用摘要”方案 |
+| 2026-04-24 17:05 | 页面实现 | completed | 已接入路由列表、动作映射、编辑弹窗、删除流程与节点引用摘要 |
+| 2026-04-24 17:07 | 构建验证 | completed | `admin-frontend` 执行 `npm run build` 通过，并刷新 `public/assets/admin` 产物 |
+| 2026-04-24 17:08 | 文档同步 | completed | 已更新 CHANGELOG、项目上下文与模块文档 |
+
+---
+
+## 执行备注
+
+- 当前仓存在未提交的历史变更与多个已完成方案包，本轮只增量实现 `node-routes`，不覆盖无关模块。
+- `public/assets/admin` 为前端构建产物子模块；构建后需要同时复核根仓与子模块状态。
@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 4,
+  "failed": 0,
+  "pending": 0,
+  "total": 4,
+  "done": 4,
+  "percent": 100,
+  "current": "24h 排行对昨天比较修复、测试补充与语法校验已完成",
+  "updated_at": "2026-04-24 19:25:00"
+}
@@ -0,0 +1,39 @@
+{
+  "updatedAt": "2026-04-24T11:25:00.000Z",
+  "version": 1,
+  "source": "R2",
+  "originCommand": "design",
+  "verifyMode": "targeted-check",
+  "reviewerFocus": [
+    "24h 排行比较窗口是否准确命中昨天整日统计",
+    "7天 / 30天 对比逻辑是否保持原样，未被意外改动",
+    "节点排行与用户排行是否共用同一后端修复入口"
+  ],
+  "testerFocus": [
+    "单日窗口应返回昨天整日作为 previous window",
+    "多日窗口应继续沿用原等跨度比较规则",
+    "修改文件至少通过 PHP 语法校验"
+  ],
+  "ui": {
+    "required": false,
+    "designContract": false,
+    "sourcePriority": [],
+    "styleAdvisor": {
+      "required": false,
+      "reason": "",
+      "focus": []
+    },
+    "visualValidation": {
+      "required": false,
+      "reason": "",
+      "screens": [],
+      "states": []
+    }
+  },
+  "advisor": {
+    "required": false,
+    "reason": "",
+    "focus": [],
+    "preferredSources": []
+  }
+}
@@ -0,0 +1,64 @@
+# 变更提案: admin-frontend-dashboard-rank-24h-compare
+
+## 元信息
+```yaml
+类型: 缺陷修复
+方案类型: implementation
+优先级: P1
+状态: 已完成
+创建: 2026-04-24
+```
+
+---
+
+## 1. 需求
+
+### 背景
+用户反馈 `admin-frontend` 仪表盘中的“节点流量排行 / 用户流量排行”在 `24h` 视图下，右侧趋势百分比始终显示 `0%`。当前期望是：`24h` 口径应与“昨天同日统计”做对比，而不是固定归零。
+
+### 目标
+- 修复 `24h` 排行涨跌百分比的对比窗口。
+- 保持本轮范围最小，只处理 `24h` 口径，不改动 `7天 / 30天` 的既有对比方式。
+
+### 约束条件
+```yaml
+范围约束: 仅修复 admin 仪表盘 traffic rank 的 24h 对比逻辑
+技术约束: 优先做后端定点修复，不改动前端排行展示结构
+业务约束: 24h 必须与昨天整日统计对比；7天/30天 本轮保持现状
+验证约束: 本地无 composer vendor，无法直接跑 Laravel/PHPUnit 全量测试
+```
+
+### 验收标准
+- [ ] `stat/getTrafficRank` 在单日窗口下返回的 `change` 不再因昨日统计行被排除而全部回退为 `0`
+- [ ] 节点排行与用户排行共用同一修复逻辑
+- [ ] 修改文件通过基础语法校验
+- [ ] `.helloagents` 变更记录已同步
+
+---
+
+## 2. 方案
+
+### 根因
+后端 `StatUserJob / StatServerJob` 会把日统计记录写入当天 `00:00:00` 的 `record_at`。现有 `getTrafficRank` 在单日窗口下使用“当前秒级跨度回推上一窗口”的方式计算：
+
+- 当前窗口：`2026-04-24 00:00:00 ~ 2026-04-24 23:59:59`
+- 旧逻辑上一窗口起点：`2026-04-23 00:00:01`
+
+这样会把昨天 `00:00:00` 的整日统计记录排除掉，导致 `previousValue = 0`，最终 `change` 全部落回 `0`。
+
+### 修复策略
+1. 在 `StatController` 中新增单独的对比窗口解析方法。
+2. 当当前窗口是单日口径时，上一窗口直接固定为 `start_time - 86400 ~ start_time`，精确命中昨天整日统计。
+3. 多日窗口沿用现有等跨度逻辑，避免超出本轮范围。
+4. 增加单元测试覆盖窗口计算规则，便于后续回归。
+
+---
+
+## 3. 技术决策
+
+### admin-frontend-dashboard-rank-24h-compare#D001: 仅修复 24h 与昨天对比逻辑，7天/30天 保持现状
+**日期**: 2026-04-24
+**状态**: ✅采纳
+**背景**: 用户在确认阶段明确选择“只修复 24h，对昨天同时间窗口比较；7天 / 30天 保持现状”。
+**决策**: 后端只对单日窗口切换为“昨天整日”比较，多日窗口不在本轮调整。
+**理由**: 与用户确认范围一致，改动最小，回归风险最低。
@@ -0,0 +1,42 @@
+# 任务清单: admin-frontend-dashboard-rank-24h-compare
+
+> **@status:** completed | 2026-04-24 19:25
+
+```yaml
+@feature: admin-frontend-dashboard-rank-24h-compare
+@created: 2026-04-24
+@status: completed
+@mode: R2
+```
+
+## 进度概览
+
+| 完成 | 失败 | 跳过 | 总数 |
+|------|------|------|------|
+| 4 | 0 | 0 | 4 |
+
+---
+
+## 任务列表
+
+- [√] 1. 定位 24h 排行涨跌全部为 0 的根因，确认前后端边界
+- [√] 2. 在后端实现单日窗口与昨天整日统计的定点对比修复
+- [√] 3. 补充单元测试覆盖窗口解析逻辑
+- [√] 4. 进行语法校验并同步 `.helloagents` 记录
+
+---
+
+## 执行日志
+
+| 时间 | 任务 | 状态 | 备注 |
+|------|------|------|------|
+| 2026-04-24 19:13 | 根因定位 | completed | 确认日统计 `record_at` 固定为当天 00:00，旧窗口回推会把昨天记录错位排除 |
+| 2026-04-24 19:18 | 后端修复 | completed | `StatController` 新增单日窗口解析逻辑，仅修复 24h 对昨天比较 |
+| 2026-04-24 19:21 | 测试补充 | completed | 新增窗口解析单元测试，覆盖单日与多日两条路径 |
+| 2026-04-24 19:25 | 校验与文档同步 | completed | 已执行 PHP 语法校验，并更新模块文档与 CHANGELOG |
+
+---
+
+## 执行备注
+
+- 本地环境缺少 `vendor/autoload.php` 与 `vendor/bin/phpunit`，本轮无法执行 PHPUnit；已退化为语法校验，并保留测试文件供后续有依赖环境时执行。
@@ -0,0 +1,49 @@
+{
+  "updatedAt": "2026-04-24T09:09:46.384Z",
+  "version": 1,
+  "source": "manual",
+  "originCommand": "generic-r2",
+  "verifyMode": "test-first",
+  "reviewerFocus": [
+    "礼品卡管理整体结构是否贴近用户提供的四页签后台截图",
+    "模板抽屉字段分组是否与截图和现有后端 JSON 结构一致"
+  ],
+  "testerFocus": [
+    "礼品卡管理是否真实连接 gift-card/templates、codes、usages、statistics、types 接口",
+    "模板新增编辑是否能正确序列化 conditions、rewards、limits、special_config",
+    "兑换码管理是否支持生成、导出、复制、启停、编辑和删除主链路"
+  ],
+  "ui": {
+    "required": true,
+    "designContract": true,
+    "sourcePriority": [
+      "requirements.md",
+      ".helloagents/DESIGN.md",
+      "hello-ui"
+    ],
+    "styleAdvisor": {
+      "required": false,
+      "reason": "",
+      "focus": []
+    },
+    "visualValidation": {
+      "required": true,
+      "reason": "礼品卡管理属于整页新增的真实后台业务页，需要确认四页签导航、模板表格、模板抽屉和统计卡片在代码结构上与目标截图及 Apple 化后台契约一致。",
+      "screens": [
+        "#/subscriptions/gift-cards desktop"
+      ],
+      "states": [
+        "模板管理默认加载完成态",
+        "模板新增抽屉展开态",
+        "兑换码管理列表态",
+        "统计数据总览态"
+      ]
+    }
+  },
+  "advisor": {
+    "required": false,
+    "reason": "",
+    "focus": [],
+    "preferredSources": []
+  }
+}
@@ -0,0 +1,59 @@
+# admin-frontend 礼品卡管理首版交付 — 实施规划
+
+## 目标与范围
+- 在现有订阅管理分组中补齐礼品卡管理真实页，替换原先的禁用入口。
+- 页面聚焦“礼品卡运营工作台”主链路：建模板、生成兑换码、查看使用记录、追踪统计数据。
+
+## 架构与实现策略
+- 在 `AdminLayout` 中开放 `/subscriptions/gift-cards` 导航入口，并在路由中新增对应页面。
+- 新增 `GiftCardsView` 作为整页工作台，整体结构参考用户截图：
+  - 顶部标题与说明
+  - 四段式分段导航（模板管理 / 兑换码管理 / 使用记录 / 统计数据）
+  - 每个页签独立的筛选条、表格/卡片内容与操作按钮
+- 新增两个业务弹层组件：
+  - `GiftCardTemplateDrawer.vue`：负责模板新增与编辑
+  - `GiftCardCodeBatchDialog.vue`：负责批量生成兑换码
+- 在 `src/utils/giftCards.ts` 中集中处理：
+  - 类型/状态映射
+  - 模板表单序列化与反序列化
+  - 金额(元)/流量(GB)/倍率/日期等展示与提交格式转换
+  - 本地搜索筛选与统计卡片整理
+- API 层在 `src/api/admin.ts` 中新增礼品卡接口封装；类型定义统一补到 `src/types/api.d.ts`。
+
+## 完成定义
+- 侧边栏中的“礼品卡管理”不再是禁用入口，能正常进入 `#/subscriptions/gift-cards`。
+- 模板管理页可真实连接模板列表与 CRUD 接口，支持搜索、筛选、启停与删除。
+- 模板抽屉可完整编辑截图展示的主要字段分组，并正确序列化为后端 `conditions / rewards / limits / special_config` 结构。
+- 兑换码页可真实连接兑换码列表，支持批量生成、复制、启停、导出当前批次、编辑有效期/次数与删除。
+- 使用记录与统计数据页可真实连接后端数据，不使用硬编码假数据。
+
+## 文件结构
+- `admin-frontend/src/layouts/AdminLayout.vue`
+- `admin-frontend/src/router/index.ts`
+- `admin-frontend/src/api/admin.ts`
+- `admin-frontend/src/types/api.d.ts`
+- `admin-frontend/src/utils/giftCards.ts`
+- `admin-frontend/src/views/subscriptions/GiftCardsView.vue`
+- `admin-frontend/src/views/subscriptions/GiftCardsView.scss`
+- `admin-frontend/src/views/subscriptions/GiftCardTemplateDrawer.vue`
+- `admin-frontend/src/views/subscriptions/GiftCardCodeBatchDialog.vue`
+
+## UI / 设计约束
+- 页面采用“标题说明 + 轻量分段页签 + 白色工作台”的 Apple 化运营后台节奏，不额外叠加夸张 hero 或营销化视觉。
+- 四个页签保持统一信息架构与表格密度，让用户能快速在模板、兑换码、记录、统计之间切换。
+- 模板抽屉使用分组 section 和双列表单布局，对齐截图中的信息分区；在窄屏下自动堆叠为单列。
+- 状态标签、奖励摘要、统计卡片继续沿用单一蓝色强调和语义色状态胶囊，不引入新配色体系。
+
+## 风险与验证
+- 风险 1：模板表单字段较多，若直接散落在组件内易导致提交结构和展示结构不一致，因此统一收敛到 `src/utils/giftCards.ts`。
+- 风险 2：兑换码列表接口不支持关键词搜索，需要前端在当前拉取结果上做本地搜索，并明确这是列表内过滤。
+- 风险 3：本地环境缺少真实后台登录态时，只能做结构与构建验证，不能替代完整联调。
+- 验证方式：
+  - `npm run build`
+  - 代码级结构自检 `#/subscriptions/gift-cards`
+  - 结构化视觉验收记录（无浏览器工具时以 code inspection 说明边界）
+
+## 决策记录
+- [2026-04-24] 礼品卡管理采用单页四段式导航，而不是四个独立路由，以贴近用户截图中的运营切换路径。
+- [2026-04-24] 模板抽屉使用分组式大表单，不把复杂字段塞进居中弹窗，以保证高密度配置仍可读。
+- [2026-04-24] 兑换码导出先按“当前选中批次”提供显式出口，不额外扩展复杂多选批量导出流程。
@@ -0,0 +1,49 @@
+# admin-frontend 礼品卡管理首版交付 — 需求
+
+确认后冻结，执行阶段不可修改。如需变更必须回到设计阶段重新确认。
+
+## 核心目标
+- 在 `admin-frontend` 中开放“订阅管理 / 礼品卡管理”入口，不再保留禁用态。
+- 参考用户提供的 5 张截图，交付礼品卡管理真实工作台，覆盖模板管理、兑换码管理、使用记录与统计数据四个页签。
+- 保持 `apple/DESIGN.md` 与 `.helloagents/DESIGN.md` 定义的 Apple 化后台视觉语言，同时优先贴近截图中的高密度运营视图与轻量分段导航。
+
+## 功能边界
+- 必须实现 `#/subscriptions/gift-cards` 真实页面。
+- 页面必须包含：
+  - 顶部标题说明与四段式页签导航
+  - 模板管理列表、搜索、类型/状态筛选、显隐切换、新增/编辑、删除
+  - 模板新增/编辑大表单，覆盖基础配置、奖励内容、使用条件、使用限制、特殊配置、显示效果
+  - 兑换码管理列表、模板/状态筛选、复制、启停、编辑、删除、批量生成、批次导出
+  - 使用记录列表与用户邮箱搜索
+  - 统计数据总览，至少展示模板总数、活跃模板数、兑换码总数、已使用兑换码
+- 必须接入现有 Laravel 管理接口：
+  - `GET /gift-card/templates`
+  - `POST /gift-card/create-template`
+  - `POST /gift-card/update-template`
+  - `POST /gift-card/delete-template`
+  - `POST /gift-card/generate-codes`
+  - `GET /gift-card/codes`
+  - `POST /gift-card/toggle-code`
+  - `GET /gift-card/export-codes`
+  - `POST /gift-card/update-code`
+  - `POST /gift-card/delete-code`
+  - `GET /gift-card/usages`
+  - `GET /gift-card/statistics`
+  - `GET /gift-card/types`
+
+## 非目标
+- 本轮不改造 Laravel 礼品卡后端逻辑、校验规则或数据库结构。
+- 本轮不实现用户端礼品卡兑换体验。
+- 本轮不引入复杂图表库，只使用现有栈完成统计展示。
+
+## 技术约束
+- 技术栈固定为 `Vue 3 + TypeScript + Vite + Element Plus`。
+- 后端真相源以仓库内 `App\Http\Controllers\V2\Admin\GiftCardController`、`GiftCardTemplate`、`GiftCardCode` 与 `GiftCardUsage` 为准。
+- 构建验证使用 `admin-frontend/package.json` 中已有 `npm run build`。
+- 构建产物继续输出到 `public/assets/admin` 子模块。
+
+## 质量要求
+- 礼品卡页面需要对齐截图中的运营后台结构：白色工作台、轻量页签、克制筛选条、高密度表格。
+- 表单字段需要覆盖加载、保存、取消、校验失败与成功提示等基本状态。
+- 金额、流量、时间与倍率展示必须按人类可读方式格式化，不直接暴露原始后端数值。
+- 最终至少完成一次构建验证，并留下结构化视觉验收与交付证据。
@@ -0,0 +1,14 @@
+# admin-frontend 礼品卡管理首版交付 — 任务分解
+
+## 任务列表
+- [x] 任务1：补齐礼品卡管理方案与合同产物（涉及文件：`.helloagents/plans/202604241703_admin-frontend-gift-card-management/*`；完成标准：存在需求、方案、任务与合同文件；验证方式：文件检查）
+- [x] 任务2：开放礼品卡导航与路由入口（涉及文件：`admin-frontend/src/layouts/AdminLayout.vue`、`admin-frontend/src/router/index.ts`；完成标准：侧边栏可进入 `#/subscriptions/gift-cards`；验证方式：`npm run build`）
+- [x] 任务3：补齐礼品卡 API、类型与工具层（涉及文件：`admin-frontend/src/api/admin.ts`、`admin-frontend/src/types/api.d.ts`、`admin-frontend/src/utils/giftCards.ts`；完成标准：前端可消费 `gift-card/*` 接口并统一完成字段映射；验证方式：`npm run build`）
+- [x] 任务4：实现礼品卡管理主页面（涉及文件：`admin-frontend/src/views/subscriptions/GiftCardsView.vue`、`admin-frontend/src/views/subscriptions/GiftCardsView.scss`；完成标准：四个页签支持真实数据展示、搜索筛选、表格/统计渲染与关键操作入口；验证方式：`npm run build`）
+- [x] 任务5：实现模板抽屉与兑换码生成弹层（涉及文件：`admin-frontend/src/views/subscriptions/GiftCardTemplateDrawer.vue`、`admin-frontend/src/views/subscriptions/GiftCardCodeBatchDialog.vue`；完成标准：支持模板新增/编辑与兑换码批量生成；验证方式：`npm run build`）
+- [x] 任务6：完成验证与知识库同步（涉及文件：`.helloagents/CHANGELOG.md`、`.helloagents/context.md`、`.helloagents/modules/admin-frontend.md`、`.helloagents/.ralph-visual.json`、`.helloagents/.ralph-closeout.json`；完成标准：构建通过、知识库更新、交付证据写入；验证方式：命令输出 + 证据文件）
+
+## 进度
+- [x] 已确认礼品卡管理按完整四页签首版推进。
+- [x] 已完成礼品卡管理真实页面、模板抽屉、兑换码生成弹层与后端接口接入。
+- [x] 已完成构建验证，待输出最终交付摘要。
@@ -0,0 +1,11 @@
+{
+  "status": "completed",
+  "completed": 5,
+  "failed": 0,
+  "pending": 0,
+  "total": 5,
+  "done": 5,
+  "percent": 100,
+  "current": "节点管理新增 / 编辑 / 排序已完成，等待后续需求",
+  "updated_at": "2026-04-24 17:30:00"
+}
@@ -0,0 +1,49 @@
+{
+  "updatedAt": "2026-04-24T09:18:00.000Z",
+  "version": 1,
+  "source": "manual",
+  "originCommand": "generic-r2",
+  "verifyMode": "test-first",
+  "reviewerFocus": [
+    "节点编辑弹窗是否贴近用户截图中的高密度 Apple 化后台结构",
+    "不同协议切换时是否真正呈现差异化配置，而不是统一占位表单"
+  ],
+  "testerFocus": [
+    "节点新增与编辑是否真实接入 /server/manage/save",
+    "节点排序是否真实接入 /server/manage/sort 并生成正确顺序 payload",
+    "11 种节点协议是否都拥有可用的首版动态配置表单"
+  ],
+  "ui": {
+    "required": true,
+    "designContract": true,
+    "sourcePriority": [
+      "requirements.md",
+      ".helloagents/DESIGN.md",
+      "hello-ui"
+    ],
+    "styleAdvisor": {
+      "required": false,
+      "reason": "",
+      "focus": []
+    },
+    "visualValidation": {
+      "required": true,
+      "reason": "节点管理属于截图导向的整页高密度运营工作台，新增节点弹窗与排序流程需要确认结构和状态呈现与目标截图一致。",
+      "screens": [
+        "#/nodes desktop"
+      ],
+      "states": [
+        "节点列表默认加载完成态",
+        "新建节点未选择协议态",
+        "新建节点 VLess 配置态",
+        "编辑排序对话框态"
+      ]
+    }
+  },
+  "advisor": {
+    "required": false,
+    "reason": "",
+    "focus": [],
+    "preferredSources": []
+  }
+}
@@ -0,0 +1,61 @@
+# admin-frontend 节点管理真实工作台补全 — 实施规划
+
+## 目标与范围
+- 在现有节点列表工作台内补齐“添加节点 / 编辑节点 / 编辑排序”三条真实运营链路。
+- 让节点配置从“只读列表 + 局部开关”升级为“列表 + 动态协议编辑器 + 排序对话框”的完整后台工作台。
+
+## 架构与实现策略
+- 保留现有 `NodesView` 列表骨架、统计卡片、筛选条、显隐切换、复制和删除逻辑，在此基础上接入真实新增 / 编辑 / 排序流程。
+- 新增 `NodeEditorDialog.vue`：
+  - 负责节点新增与编辑
+  - 中央大弹窗布局，顶部标题与说明左对齐，协议选择器右置
+  - 采用“通用信息 → 动态倍率 → 协议安全层 → 传输层 → 协议专属设置”分组结构
+- 新增 `NodeSortDialog.vue`：
+  - 负责可见顺序调整
+  - 使用本地排序草稿 + 上移 / 下移交互
+  - 保存时转换为 `[{ id, order }]` 并提交到 `/server/manage/sort`
+- 新增 `src/utils/nodeEditor.ts`：
+  - 收敛协议选项、TLS / 传输 / 协议字段默认值
+  - 负责节点实体与表单模型的双向转换
+  - 负责把动态表单序列化为 `ServerSave` 所需 payload
+- 在 `src/types/api.d.ts` 与 `src/api/admin.ts` 中补齐节点保存 / 排序的类型和接口封装。
+
+## 完成定义
+- `#/nodes` 的“添加节点”按钮能打开真实节点编辑弹窗并提交保存。
+- 列表行菜单中的“编辑节点”能回填当前节点数据，并允许修改后提交。
+- 不同协议切换后，表单配置区会随协议变化，不再是统一占位结构。
+- “编辑排序”能打开真实排序对话框，调整顺序并保存到后台。
+- 现有节点列表的显隐 / 复制 / 删除能力保持可用，不因本轮重构回归。
+
+## 文件结构
+- `.helloagents/plans/202604241718_admin-frontend-node-management/*`
+- `admin-frontend/src/api/admin.ts`
+- `admin-frontend/src/types/api.d.ts`
+- `admin-frontend/src/utils/nodes.ts`
+- `admin-frontend/src/utils/nodeEditor.ts`
+- `admin-frontend/src/views/nodes/NodesView.vue`
+- `admin-frontend/src/views/nodes/NodeEditorDialog.vue`
+- `admin-frontend/src/views/nodes/NodeEditorDialog.scss`
+- `admin-frontend/src/views/nodes/NodeSortDialog.vue`
+- `admin-frontend/src/views/nodes/NodeSortDialog.scss`
+
+## UI / 设计约束
+- 列表页继续保持“黑色 Hero + 白色工作台”的 Apple 化后台节奏，不额外引入营销化视觉。
+- 节点编辑弹窗整体贴近用户截图：标题与说明在顶部，协议切换器独立，表单区以白底轻边框输入为主，操作栏固定在底部。
+- 协议差异应体现在配置结构与字段显隐上，不使用“JSON 文本编辑器”替代真实表单。
+- 动态倍率、TLS、Reality、ECH、多路复用等高级项默认折叠在分组内，保证高密度但仍可读。
+- 节点排序流程沿用现有套餐排序的 Apple 化列表草稿模式，避免引入沉重拖拽依赖。
+
+## 风险与验证
+- 风险 1：协议差异字段较多，如果全部堆在 `NodesView.vue` 会导致页面过大，因此节点表单与序列化逻辑必须拆到专属组件 / util。
+- 风险 2：后端 `protocol_settings` 存在嵌套对象和协议差异，若序列化不统一容易导致编辑后字段丢失，因此统一通过 `src/utils/nodeEditor.ts` 生成 payload。
+- 风险 3：本地环境缺少真实后台登录态时，只能做结构与构建验证，不能替代完整联调。
+- 验证方式：
+  - `npm run build`
+  - 代码级结构自检 `#/nodes`
+  - 结构化视觉验收记录（无浏览器工具时以 code inspection 说明边界）
+
+## 决策记录
+- [2026-04-24] 节点新增与编辑共用同一中央大弹窗，而不是拆成独立路由页。
+- [2026-04-24] 排序沿用“本地草稿 + 上移 / 下移”的后台排序模式，不引入额外拖拽库。
+- [2026-04-24] 协议配置采用“通用字段 + 动态协议块”结构，以同时满足截图风格和 11 种协议的差异表达。
@@ -0,0 +1,75 @@
+# admin-frontend 节点管理真实工作台补全 — 需求
+
+确认后冻结，执行阶段不可修改。如需变更必须回到设计阶段重新确认。
+
+## 核心目标
+- 在 `admin-frontend` 的 `#/nodes` 页面内，补齐“添加节点 / 编辑节点 / 编辑排序”三条真实链路，不再保留“下一阶段接入”占位提示。
+- 参考用户提供的节点弹窗截图，交付居中大弹窗式节点编辑器，并让不同节点协议按各自配置方式动态切换字段。
+- 保持 `apple/DESIGN.md` 与 `.helloagents/DESIGN.md` 定义的 Apple 化后台视觉语言，同时贴近截图中的高密度运营表单结构。
+
+## 功能边界
+- 必须实现 `#/nodes` 页面中的：
+  - 添加节点
+  - 编辑节点
+  - 节点排序
+- 必须支持以下协议的首版真实新增 / 编辑表单：
+  - `Shadowsocks`
+  - `VMess`
+  - `Trojan`
+  - `Hysteria`
+  - `VLess`
+  - `TUIC`
+  - `SOCKS`
+  - `Naive`
+  - `HTTP`
+  - `Mieru`
+  - `AnyTLS`
+- 表单必须覆盖通用字段：
+  - 节点名称
+  - 基础倍率
+  - 动态倍率开关与时间段倍率规则
+  - 自定义节点 ID
+  - 节点标签
+  - 权限组
+  - 节点地址
+  - 连接端口 / 服务端口
+  - 父级节点
+  - 路由组
+  - 前台显示 / 节点启用状态
+- 必须根据协议切换不同的配置块，至少覆盖当前后端 `ServerSave` 校验与 `Server::PROTOCOL_CONFIGURATIONS` 中已定义的关键字段：
+  - 传输协议 / 传输层参数
+  - TLS / Reality / ECH / uTLS
+  - Hysteria 版本 / 带宽 / 混淆
+  - TUIC 版本 / 拥塞控制 / ALPN / UDP relay
+  - Shadowsocks cipher / obfs / plugin
+  - VLess flow / encryption
+  - Mieru transport / traffic pattern
+  - AnyTLS padding scheme
+- 必须接入现有 Laravel 管理接口：
+  - `GET /server/manage/getNodes`
+  - `POST /server/manage/save`
+  - `POST /server/manage/sort`
+  - `POST /server/manage/update`
+  - `POST /server/manage/copy`
+  - `POST /server/manage/drop`
+  - `GET /server/group/fetch`
+  - `GET /server/route/fetch`
+
+## 非目标
+- 本轮不改造 Laravel 节点后端逻辑、校验规则或数据库结构。
+- 本轮不接入机器管理、批量删除、批量更新、批量重置流量等二级操作。
+- 本轮不实现节点健康诊断、联机测试或复杂拓扑视图。
+
+## 技术约束
+- 技术栈固定为 `Vue 3 + TypeScript + Vite + Element Plus`。
+- 后端真相源以仓库内 `App\Http\Controllers\V2\Admin\Server\ManageController`、`App\Http\Requests\Admin\ServerSave` 与 `App\Models\Server` 为准。
+- 节点排序继续采用当前后台 `server/manage/sort` 的顺序保存模式。
+- 构建验证使用 `admin-frontend/package.json` 中已有 `npm run build`。
+- 构建产物继续输出到 `public/assets/admin` 子模块。
+
+## 质量要求
+- 弹窗结构需要贴近用户截图：顶部标题说明、右上角协议选择、白色表单面板、长内容滚动区、底部固定操作栏。
+- 不同协议切换时，字段分组和默认值必须清晰，不能把所有字段堆成一张无差别长表单。
+- 传输层 / TLS / Reality / 多路复用等设置需要按协议语义组织，而不是只暴露原始 JSON 文本。
+- 排序流程需要提供可见的顺序编辑界面和保存反馈。
+- 最终至少完成一次构建验证，并留下结构化视觉验收与交付证据。
@@ -0,0 +1,12 @@
+# admin-frontend 节点管理真实工作台补全 — 任务分解
+
+## 任务列表
+- [x] 任务1：补齐节点管理方案与合同产物（涉及文件：`.helloagents/plans/202604241718_admin-frontend-node-management/*`；完成标准：存在需求、方案、任务与合同文件；验证方式：文件检查）
+- [x] 任务2：补齐节点保存 / 排序接口、类型与表单工具层（涉及文件：`admin-frontend/src/api/admin.ts`、`admin-frontend/src/types/api.d.ts`、`admin-frontend/src/utils/nodes.ts`、`admin-frontend/src/utils/nodeEditor.ts`；完成标准：前端具备节点新增、编辑、排序的类型和序列化能力；验证方式：`npm run build`）
+- [x] 任务3：实现节点新增 / 编辑弹窗（涉及文件：`admin-frontend/src/views/nodes/NodeEditorDialog.vue`、`admin-frontend/src/views/nodes/NodeEditorDialog.scss`；完成标准：支持 11 种协议的动态配置表单与保存；验证方式：`npm run build`）
+- [x] 任务4：实现节点排序流程并接入列表页（涉及文件：`admin-frontend/src/views/nodes/NodeSortDialog.vue`、`admin-frontend/src/views/nodes/NodeSortDialog.scss`、`admin-frontend/src/views/nodes/NodesView.vue`；完成标准：列表页新增真实添加 / 编辑 / 排序入口，排序可保存；验证方式：`npm run build`）
+- [x] 任务5：完成验证与知识库同步（涉及文件：`.helloagents/CHANGELOG.md`、`.helloagents/context.md`、`.helloagents/modules/admin-frontend.md`、`.helloagents/.ralph-visual.json`、`.helloagents/.ralph-closeout.json`；完成标准：构建通过、知识库更新、交付证据写入；验证方式：命令输出 + 证据文件）
+
+## 进度
+- [x] 已确认按“全量协议首版”推进节点管理新增 / 编辑 / 排序。
+- [x] 已完成节点管理方案包、前端实现、验证与知识库同步。
@@ -24,3 +24,13 @@
 {"ts":"2026-04-24T08:26:56.881Z","event":"turn_state_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","details":{"kind":"complete","role":"main","requiresDeliveryGate":false}}
 {"ts":"2026-04-24T08:26:56.986Z","event":"closeout_evidence_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","skillName":"fix-stash-anytls-compat-filter","artifacts":[".helloagents/.ralph-closeout.json"],"details":{"requirementsCoverage":{"status":"PASS","summary":"已按保守兼容策略在 Stash 导出器中过滤未知版本与低版本的 AnyTLS，并补方案包记录。"},"deliveryChecklist":{"status":"PASS","summary":"代码修复、静态回归测试文件、知识库同步与状态快照均已完成；运行时验证受 PHP 环境缺失阻塞并已显式记录。"}}}
 {"ts":"2026-04-24T08:27:02.763Z","event":"turn_state_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","details":{"kind":"complete","role":"main","requiresDeliveryGate":false}}
+{"ts":"2026-04-24T08:51:26.770Z","event":"turn_state_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","details":{"kind":"waiting","role":"main","requiresDeliveryGate":false,"reasonCategory":"ambiguity","reason":"需要确认侧边栏在低视口高度下的滚动/折叠策略"}}
+{"ts":"2026-04-24T09:07:07.749Z","event":"closeout_evidence_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","skillName":"R2-generic","artifacts":[".helloagents/.ralph-closeout.json"],"details":{"requirementsCoverage":{"status":"PASS","summary":"已按用户确认方案完成侧边栏低高度修复：顶部品牌区固定，菜单区独立滚动，低高度下可访问底部入口。"},"deliveryChecklist":{"status":"PASS","summary":"已完成 AdminLayout 代码修复、npm run build 验证、Playwright 低视口滚动检查，以及 admin-frontend 模块文档与 CHANGELOG 同步。"}}}
+{"ts":"2026-04-24T09:07:37.945Z","event":"turn_state_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","details":{"kind":"complete","role":"main","requiresDeliveryGate":false}}
+{"ts":"2026-04-24T09:18:48.741Z","event":"turn_state_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","details":{"kind":"waiting","role":"main","requiresDeliveryGate":false,"reasonCategory":"ambiguity","reason":"需要确认24h趋势修复范围：仅对比昨天，还是连同7天/30天一并改为上一周期对比。"}}
+{"ts":"2026-04-24T09:45:03.633Z","event":"visual_evidence_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","skillName":"generic-r2","artifacts":[".helloagents/.ralph-visual.json"],"details":{"reason":"礼品卡管理属于整页新增的真实后台业务页，需要确认四页签导航、模板表格、模板抽屉和统计卡片在代码结构上与目标截图及 Apple 化后台契约一致。","tooling":["code inspection","npm run build"],"screensChecked":["#/subscriptions/gift-cards desktop"],"statesChecked":["模板管理默认加载完成态","模板新增抽屉展开态","兑换码管理列表态","统计数据总览态"],"status":"PASS"}}
+{"ts":"2026-04-24T09:45:03.661Z","event":"closeout_evidence_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","skillName":"generic-r2","artifacts":[".helloagents/.ralph-closeout.json"],"details":{"requirementsCoverage":{"status":"PASS","summary":"礼品卡管理已交付完整四页签首版：模板管理、兑换码管理、使用记录和统计数据均已接入真实 gift-card 接口，导航入口已开放，方案包已归档。"},"deliveryChecklist":{"status":"PASS","summary":"已完成 admin-frontend 礼品卡页面、抽屉与数据层实现，执行 npm run build 通过，并同步 CHANGELOG/context/modules/archive 等知识库文件。"}}}
+{"ts":"2026-04-24T09:54:43.933Z","event":"visual_evidence_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","skillName":"generic-r2","artifacts":[".helloagents/.ralph-visual.json"],"details":{"reason":"节点管理属于截图导向的高密度运营工作台，本轮通过代码结构检查与构建结果确认新增、编辑、排序界面已按目标状态落地。","tooling":["code-inspection","npm run build"],"screensChecked":["#/nodes desktop"],"statesChecked":["节点列表默认加载完成态","新建节点未选择协议态","新建节点 VLess 配置态","编辑排序对话框态"],"status":"PASS"}}
+{"ts":"2026-04-24T09:54:56.774Z","event":"closeout_evidence_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","skillName":"generic-r2","artifacts":[".helloagents/.ralph-closeout.json"],"details":{"requirementsCoverage":{"status":"PASS","summary":"节点管理方案包中定义的新增、编辑、排序、11 种协议动态配置、动态倍率、权限组/路由组联动与构建验证均已落地。"},"deliveryChecklist":{"status":"PASS","summary":"admin-frontend 已完成节点工作台实现、npm run build 通过、知识库同步完成，并写入视觉与收尾证据。"}}}
+{"ts":"2026-04-24T09:55:06.594Z","event":"turn_state_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","details":{"kind":"complete","role":"main","requiresDeliveryGate":false}}
+{"ts":"2026-04-24T13:55:29.445Z","event":"turn_state_written","host":"unknown","source":"manual","sessionId":"2026-04-24T07-44-44-846Z-unknown-e3upr9","details":{"kind":"waiting","role":"main","requiresDeliveryGate":false,"reasonCategory":"ambiguity","reason":"需确认批量操作范围后再进入方案设计"}}
@@ -1,3 +1,5 @@
 {"ts":"2026-04-24T08:15:56.368Z","event":"verify_gate_blocked","host":"claude","source":"ralph-loop","sessionId":"2026-04-24T08-15-56-367Z-claude-u7aa37","reason":"[Ralph Loop] Verification failed: ✗ npm run build npm error Missing script: \"build\" npm error npm error To see a list of scripts, run: npm error npm run npm error A complete log of this run can be found in: C:\\Users\\xiaohuli\\AppData\\Local\\npm-cache\\_logs\\2026-04-24T08_15_56_204Z-"}
 {"ts":"2026-04-24T08:21:21.570Z","event":"verify_gate_blocked","host":"claude","source":"ralph-loop","sessionId":"2026-04-24T08-15-56-367Z-claude-u7aa37","reason":"[Ralph Loop] Verification failed: ✗ npm run build npm error Missing script: \"build\" npm error npm error To see a list of scripts, run: npm error npm run npm error A complete log of this run can be found in: C:\\Users\\xiaohuli\\AppData\\Local\\npm-cache\\_logs\\2026-04-24T08_21_21_436Z-"}
 {"ts":"2026-04-24T08:27:44.729Z","event":"verify_gate_blocked","host":"claude","source":"ralph-loop","sessionId":"2026-04-24T08-15-56-367Z-claude-u7aa37","reason":"[Ralph Loop] Verification failed: ✗ npm run build npm error Missing script: \"build\" npm error npm error To see a list of scripts, run: npm error npm run npm error A complete log of this run can be found in: C:\\Users\\xiaohuli\\AppData\\Local\\npm-cache\\_logs\\2026-04-24T08_27_44_587Z-"}
+{"ts":"2026-04-24T09:08:27.161Z","event":"verify_gate_blocked","host":"claude","source":"ralph-loop","sessionId":"2026-04-24T08-15-56-367Z-claude-u7aa37","reason":"[Ralph Loop] Verification failed: ✗ npm run build npm error Missing script: \"build\" npm error npm error To see a list of scripts, run: npm error npm run npm error A complete log of this run can be found in: C:\\Users\\xiaohuli\\AppData\\Local\\npm-cache\\_logs\\2026-04-24T09_08_27_050Z-"}
+{"ts":"2026-04-24T09:59:02.424Z","event":"verify_gate_blocked","host":"claude","source":"ralph-loop","sessionId":"2026-04-24T08-15-56-367Z-claude-u7aa37","reason":"[Ralph Loop] Verification failed: ✗ npm run build npm error Missing script: \"build\" npm error npm error To see a list of scripts, run: npm error npm run npm error A complete log of this run can be found in: C:\\Users\\xiaohuli\\AppData\\Local\\npm-cache\\_logs\\2026-04-24T09_59_02_303Z-"}
@@ -1,27 +1,26 @@
 # 恢复快照

 ## 主线目标
-继续推进 `admin-frontend` 的订阅管理模块，完成“订单管理”首版真实工作台交付。
+继续推进 `admin-frontend` 的节点管理模块，完成“添加节点 / 编辑节点 / 排序”真实工作台交付。

 ## 正在做什么
-当前任务已完成，正在整理订单管理本轮的验证证据、知识库同步与交付摘要。
+当前任务已完成，正在整理节点管理本轮的验证证据、知识库同步与交付摘要。

 ## 关键上下文
- 用户已在本轮选择“1”，确认按完整首版工作台实现订单管理。
- 设计约束来自 `apple/DESIGN.md` 与 `.helloagents/DESIGN.md`，订单页贴近用户截图，采用轻量筛选条 + 高密度表格 + 详情抽屉。
- 后端真相源为 `App\Http\Controllers\V2\Admin\OrderController`，当前可用接口为 `/order/fetch`、`/order/detail`、`/order/assign`、`/order/paid`、`/order/cancel`、`/order/update`。
- 已归档方案包：`.helloagents/archive/2026-04/202604241620_admin-frontend-order-management/`。
- 已新增 `admin-frontend/src/utils/orders.ts`、`OrdersView.vue`、`OrdersView.scss`、`OrderAssignDrawer.vue` 与 `OrderDetailDrawer.vue`，并将 `/subscriptions/orders` 路由切换为真实页面。
- `admin-frontend` 已执行 `npm run build` 并通过；构建产物已刷新 `public/assets/admin` 子模块。
+- 用户已在本轮选择“1”，确认按“全量协议首版”推进节点管理新增 / 编辑 / 排序。
+- 设计约束来自 `apple/DESIGN.md` 与 `.helloagents/DESIGN.md`，节点弹窗贴近用户截图，采用居中大弹窗 + 顶部协议选择 + 白色高密度表单。
+- 后端真相源为 `App\Http\Controllers\V2\Admin\Server\ManageController`、`App\Http\Requests\Admin\ServerSave` 与 `App\Models\Server`，当前可用接口为 `/server/manage/getNodes`、`/server/manage/save`、`/server/manage/sort`、`/server/manage/update`、`/server/manage/copy`、`/server/manage/drop`。
+- 已在 `admin-frontend` 中新增节点动态表单工具层、中央编辑弹窗与排序对话框，并让 `#/nodes` 接入真实新增 / 编辑 / 排序流程。
+- 当前方案包：`.helloagents/plans/202604241718_admin-frontend-node-management/`。

 ## 下一步
-当前任务已完成；如继续同一业务域，可在现有订单工作台基础上补批量操作、礼品卡管理与更完整的订单运营统计能力。
+当前任务已完成；如继续同一业务域，可在现有节点工作台基础上补机器管理、批量操作或更深的协议高级配置。

 ## 阻塞项
 （无）

 ## 方案
-archive/2026-04/202604241620_admin-frontend-order-management
+plans/202604241718_admin-frontend-node-management

 ## 已标记技能
 frontend-design, hello-ui, hello-verify