yinjianm
16203b14f6
扩展管理端侧边栏与路由，新增系统配置真实页面、订阅套餐 管理页、节点管理页及多个结构化占位页 补齐前端 API、类型与工具层，并增强仪表盘刷新、趋势切换、 失败作业详情与流量排行 limit 联动能力 同步后端 traffic rank limit 支持与知识库归档、设计约束、 验证配置及视觉验收产物
109 lines
6.2 KiB
Markdown
109 lines
6.2 KiB
Markdown
# 变更提案: admin-frontend-subscription-plan-management
|
||
|
||
## 元信息
|
||
```yaml
|
||
类型: 新功能
|
||
方案类型: implementation
|
||
优先级: P1
|
||
状态: 执行中
|
||
创建: 2026-04-23
|
||
```
|
||
|
||
---
|
||
|
||
## 1. 需求
|
||
|
||
### 背景
|
||
当前 `admin-frontend` 已具备仪表盘、用户管理与工单管理，但左侧信息架构仍缺少“订阅管理”业务分组。用户本轮明确要求参考 `apple/DESIGN.md` 和提供的后台截图，为管理端新增“订阅管理”侧边栏，并优先完整交付“套餐管理”页面；其余“订单管理 / 优惠券管理 / 礼品卡管理”本轮只保留菜单入口，不展开页面实现。
|
||
|
||
### 目标
|
||
- 在管理端侧边栏新增“订阅管理”分组，补齐“套餐管理 / 订单管理 / 优惠券管理 / 礼品卡管理”入口层级。
|
||
- 完整实现“套餐管理”页面，包括列表、搜索、分页、排序编辑、显隐/新购/续费开关、编辑抽屉和描述预览。
|
||
- 页面风格延续当前 Apple 化后台：黑色首屏、白色工作区、单一蓝色强调、克制交互。
|
||
|
||
### 约束条件
|
||
```yaml
|
||
范围约束: 仅完整实现“套餐管理”；其余 3 个子菜单只保留入口，不新增业务页
|
||
技术约束: 继续使用 Vue3 + TypeScript + Element Plus + Vite，不新增重型富文本或拖拽依赖
|
||
业务约束: 后端接口沿用现有 `/plan/*` 与 `/server/group/fetch`，不改 Laravel API
|
||
视觉约束: 遵循 `apple/DESIGN.md` 与 `.helloagents/DESIGN.md`，保持与现有后台同一视觉家族
|
||
```
|
||
|
||
### 验收标准
|
||
- [ ] 左侧导航新增“订阅管理”分组，且“套餐管理”可进入真实页面。
|
||
- [ ] 套餐管理页支持真实套餐列表读取、本地搜索/分页、显隐/新购/续费切换、编辑、删除与排序保存。
|
||
- [ ] 套餐编辑抽屉支持名称、标签、权限组、流量、限速、设备限制、容量限制、价格、描述与强制更新用户套餐等核心字段。
|
||
- [ ] 套餐描述区域支持 Markdown 编辑与预览，保留“使用模板”快捷入口。
|
||
- [ ] `admin-frontend` 构建通过，并同步检查 `public/assets/admin` 子模块产物状态。
|
||
|
||
---
|
||
|
||
## 2. 方案
|
||
|
||
### 技术方案
|
||
1. 扩展 `src/types/api.d.ts` 与 `src/api/admin.ts`，补齐套餐、权限组、排序与保存所需类型及请求封装。
|
||
2. 在 `src/utils/plans.ts` 中集中处理套餐价格映射、标签输入、Markdown 渲染、表单模型转换和统计展示。
|
||
3. 新增 `src/views/subscriptions/PlansView.vue` 与 `PlanEditorDrawer.vue`：
|
||
- `PlansView` 负责黑色首屏、列表工具栏、表格、分页、排序编辑和行内操作。
|
||
- `PlanEditorDrawer` 负责套餐创建/编辑表单、标签输入、价格矩阵、说明模板与预览。
|
||
4. 在 `src/layouts/AdminLayout.vue` 与 `src/router/index.ts` 中新增“订阅管理”菜单分组与 `/subscriptions/plans` 路由；其余菜单入口本轮以禁用状态保留。
|
||
|
||
### 影响范围
|
||
```yaml
|
||
涉及模块:
|
||
- admin-frontend/src/router
|
||
- admin-frontend/src/layouts
|
||
- admin-frontend/src/api
|
||
- admin-frontend/src/types
|
||
- admin-frontend/src/utils
|
||
- admin-frontend/src/views/subscriptions
|
||
预计变更文件: 6-9
|
||
```
|
||
|
||
### 风险评估
|
||
| 风险 | 等级 | 应对 |
|
||
|------|------|------|
|
||
| 后端套餐保存字段是弱约束，前端容易传入无效价格结构 | 中 | 在 `utils/plans.ts` 中统一清洗价格、标签和空值，再提交 |
|
||
| 菜单层级新增后，移动端折叠与激活态可能混乱 | 中 | 继续复用现有 `ElMenu` 分组模式，仅新增一个独立业务域 |
|
||
| `public/assets/admin` 为子模块产物目录，构建后状态可能只在子模块可见 | 中 | 验收阶段同时检查根仓与子模块状态，按双层发布事实给证据 |
|
||
|
||
---
|
||
|
||
## 3. 成果设计
|
||
|
||
### 设计方向
|
||
- **美学基调**: Apple Admin Commerce。像 Apple 系统设置中的“订阅与计费”面板，强调运营效率与价格结构的清晰表达。
|
||
- **记忆点**: 黑色首屏承载“订阅套餐”标题，正文进入大块白色工作台；价格矩阵与说明编辑区在抽屉中像系统级面板一样纵向展开。
|
||
- **参考**: 用户提供的侧边栏、套餐列表与编辑弹窗截图 + `apple/DESIGN.md`
|
||
|
||
### 视觉要素
|
||
- **配色**: 背景 `#f5f5f7`、工作区 `#ffffff`、标题 `#1d1d1f`、强调蓝 `#0071e3`、危险红 `#c93428`
|
||
- **排版**: 继续使用系统字体栈，大标题压缩行高，表格列标题和辅助文案维持轻量层级
|
||
- **布局**: 首屏标题区 + 列表工作台 + 抽屉式编辑器；描述编辑区采用工具栏 + 文本区 / 预览区双模式
|
||
- **状态**: 未实现的订阅菜单项以禁用态保留，明确表达“入口已规划，功能稍后接入”
|
||
|
||
---
|
||
|
||
## 4. 技术决策
|
||
|
||
### admin-frontend-subscription-plan-management#D001: 本轮只完整实现套餐管理，其余订阅菜单先保留禁用入口
|
||
**日期**: 2026-04-23
|
||
**状态**: ✅采纳
|
||
**背景**: 用户在确认环节明确选择“先完成订阅管理侧边栏 + 套餐管理完整页面，其余 3 个子项先只保留菜单入口”。
|
||
**决策**: “订单管理 / 优惠券管理 / 礼品卡管理”不新增页面，只在侧边栏展示禁用入口与即将开放提示。
|
||
**理由**: 确保信息架构先到位，同时避免范围蔓延到多个后台模块。
|
||
|
||
### admin-frontend-subscription-plan-management#D002: 套餐说明编辑采用轻量 Markdown 编辑器 + 预览，不引入富文本依赖
|
||
**日期**: 2026-04-23
|
||
**状态**: ✅采纳
|
||
**背景**: 参考图包含富文本工具条，但当前前端没有现成富文本编辑器，且本轮不适合引入重量级依赖。
|
||
**决策**: 使用自定义轻量工具条 + `textarea` + Markdown/HTML 预览模式实现说明编辑。
|
||
**理由**: 可覆盖截图中的主要录入与预览场景，并保持依赖与性能成本可控。
|
||
|
||
### admin-frontend-subscription-plan-management#D003: 套餐排序采用本地排序编辑对话框，而不是拖拽依赖
|
||
**日期**: 2026-04-23
|
||
**状态**: ✅采纳
|
||
**背景**: 页面需要“编辑排序”，但当前项目未引入拖拽库。
|
||
**决策**: 使用轻量排序对话框，通过“上移 / 下移”重排本地列表后调用 `/plan/sort` 保存。
|
||
**理由**: 足够满足后台排序需求，并且不引入新的交互依赖和维护成本。
|