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

补齐节点管理真实新增、编辑与排序流程,接入权限组与路由组
维护页,并支持 11 种协议的动态配置表单

开放礼品卡管理入口,交付模板、兑换码、使用记录与统计四页签
工作台,接入 gift-card 相关后台接口

将知识库、权限组与路由管理从占位页升级为真实页面,并修复侧边栏
低高度裁切问题

修复仪表盘 24h 流量排行涨跌始终为 0 的问题,改为对比昨天整日统
计并补充单元测试
This commit is contained in:
yinjianm
2026-04-24 21:58:16 +08:00
parent f7cef30b9c
commit e393b11b61
80 changed files with 8811 additions and 278 deletions
@@ -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] 已完成节点管理方案包、前端实现、验证与知识库同步。