feat(admin-frontend): 完成节点与礼品卡管理工作台
补齐节点管理真实新增、编辑与排序流程，接入权限组与路由组 维护页，并支持 11 种协议的动态配置表单 开放礼品卡管理入口，交付模板、兑换码、使用记录与统计四页签 工作台，接入 gift-card 相关后台接口 将知识库、权限组与路由管理从占位页升级为真实页面，并修复侧边栏 低高度裁切问题 修复仪表盘 24h 流量排行涨跌始终为 0 的问题，改为对比昨天整日统 计并补充单元测试
This commit is contained in:
yinjianm
+49
@@ -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] 兑换码导出先按“当前选中批次”提供显式出口，不额外扩展复杂多选批量导出流程。
|
||||
+49
@@ -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` 子模块。
|
||||
|
||||
## 质量要求
|
||||
- 礼品卡页面需要对齐截图中的运营后台结构：白色工作台、轻量页签、克制筛选条、高密度表格。
|
||||
- 表单字段需要覆盖加载、保存、取消、校验失败与成功提示等基本状态。
|
||||
- 金额、流量、时间与倍率展示必须按人类可读方式格式化，不直接暴露原始后端数值。
|
||||
- 最终至少完成一次构建验证，并留下结构化视觉验收与交付证据。
|
||||
+14
@@ -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] 已完成构建验证，待输出最终交付摘要。
|
||||
Reference in New Issue
Block a user