Project.Fengling.QoderVersion/前端功能概览.md at main

Demo/Project.Fengling.QoderVersion

- 后端新增管理员、商品、分类聚合模型
- 实现积分规则、礼品、订单、会员等完整功能
- 添加管理员认证和权限管理
- 完善数据库迁移和实体配置
- 前端管理后台实现登录、仪表盘、积分规则、礼品、订单、会员等页面
- 集成shadcn-vue UI组件库
- 添加前后端功能文档和截图

2026-02-11 21:36:37 +08:00

15 KiB

Raw Permalink Blame History

前端管理后台功能概览

本文档说明管理后台前端(Fengling.Backend.Admin)的技术实现与功能模块，便于后续开发和前后端联调。最后更新时间：2026-02-11

一、整体技术栈与架构

1.1 技术栈

Vue 3.5 - Composition API + <script setup> 语法
TypeScript 5.9 - 强类型，启用 erasableSyntaxOnly
Vite 7.3 - 构建工具，开发服务器端口 3000
pnpm - 包管理器
shadcn-vue - UI 组件库（基于 Radix Vue + Tailwind CSS v4）
Vue Router 4 - 路由管理，支持路由守卫
Pinia 3 - 状态管理
Axios - HTTP 客户端，含拦截器
lucide-vue-next - 图标库
vue-sonner - Toast 消息提示

1.2 架构风格

模块化目录结构：按功能模块组织页面、API、类型
API 服务层：每个后端模块对应一个 api/*.ts 文件，统一解包 ResponseData<T>
类型安全：所有后端 DTO 在 types/ 中有对应 TypeScript 接口
路由懒加载：所有页面组件使用 () => import() 动态导入
Mock 认证：当前使用模拟 Token，后端 JWT 完善后可无缝切换

二、项目结构

Frontend/Fengling.Backend.Admin/
├── src/
│   ├── api/                    # API 服务层
│   │   ├── client.ts          # Axios 实例 + 请求/响应拦截器
│   │   ├── gifts.ts           # 礼品管理 API（7 个函数）
│   │   ├── orders.ts          # 订单管理 API（5 个函数）
│   │   ├── marketing-codes.ts # 营销码 API
│   │   ├── points-rules.ts    # 积分规则 API
│   │   └── members.ts         # 会员查询 API
│   ├── components/
│   │   ├── layout/            # 布局组件
│   │   │   ├── AdminLayout.vue    # 主布局（侧边栏 + Header + 内容区）
│   │   │   ├── Sidebar.vue        # 左侧导航菜单
│   │   │   └── Header.vue         # 顶部面包屑导航
│   │   └── ui/                # shadcn-vue 组件（20+ 组件）
│   ├── lib/
│   │   ├── utils.ts           # cn() class 合并工具
│   │   └── constants.ts       # formatDate, truncateId, copyToClipboard 等工具函数
│   ├── pages/                 # 页面组件（9 个页面）
│   │   ├── auth/Login.vue
│   │   ├── dashboard/Dashboard.vue
│   │   ├── gifts/GiftList.vue, GiftForm.vue
│   │   ├── orders/OrderList.vue, OrderDetail.vue
│   │   ├── marketing-codes/MarketingCodes.vue
│   │   ├── points-rules/PointsRules.vue
│   │   └── members/MemberSearch.vue
│   ├── router/index.ts        # 路由配置 + 认证守卫
│   ├── stores/auth.ts         # Pinia 认证状态管理
│   ├── types/                 # TypeScript 类型定义（7 个文件）
│   │   ├── api.ts, enums.ts, gift.ts, order.ts
│   │   ├── member.ts, marketing-code.ts, points-rule.ts
│   ├── App.vue                # 根组件（RouterView + Toaster）
│   ├── main.ts                # 应用入口（Pinia + Router）
│   └── style.css              # Tailwind CSS + CSS 变量主题
├── .env.development           # 开发环境变量
├── .env.production            # 生产环境变量
├── components.json            # shadcn-vue 配置
├── vite.config.ts             # Vite 配置（Tailwind 插件 + 路径别名 + API 代理）
└── tsconfig.json / tsconfig.app.json

三、环境配置

3.1 环境变量

变量	开发环境	说明
`VITE_API_BASE_URL`	`http://localhost:5511`	后端 API 基础地址
`VITE_APP_TITLE`	`Fengling 管理后台`	应用标题

3.2 Vite 代理

开发模式下，所有 /api 请求通过 Vite proxy 代理到后端 http://localhost:5511，无需处理 CORS。

3.3 运行命令

cd Frontend/Fengling.Backend.Admin
pnpm install    # 安装依赖
pnpm dev        # 启动开发服务器 → http://localhost:3000
pnpm build      # 生产构建（vue-tsc 类型检查 + vite build）
pnpm preview    # 预览生产构建

四、认证与路由

4.1 认证机制（Mock）

当前后端 JWT 认证尚未完全实现，前端采用 Mock Token 方式：

登录：输入任意用户名密码，生成 mock-admin-token-{username}-{timestamp} 存入 localStorage
Token 注入：Axios 请求拦截器自动从 localStorage 读取 admin_token 并添加 Authorization: Bearer {token} 头
401 处理：响应拦截器检测到 401 时自动清除 Token 并跳转登录页
切换真实认证：修改 stores/auth.ts 的 login() 方法调用后端登录 API，返回真实 JWT 即可

4.2 路由结构

路径	页面	说明	认证
`/login`	Login.vue	管理员登录	否
`/dashboard`	Dashboard.vue	仪表盘	是
`/marketing-codes`	MarketingCodes.vue	营销码管理	是
`/gifts`	GiftList.vue	礼品列表	是
`/gifts/create`	GiftForm.vue	创建礼品	是
`/gifts/edit/:id`	GiftForm.vue	编辑礼品	是
`/orders`	OrderList.vue	兑换订单列表	是
`/orders/:id`	OrderDetail.vue	订单详情	是
`/points-rules`	PointsRules.vue	积分规则管理	是
`/members`	MemberSearch.vue	会员查询	是

4.3 路由守卫

beforeEach:
  未登录 + 访问受保护路由 → 重定向 /login
  已登录 + 访问 /login → 重定向 /dashboard

五、API 服务层

5.1 Axios 客户端配置 (`api/client.ts`)

baseURL：从 VITE_API_BASE_URL 环境变量读取
超时：15 秒
请求拦截器：自动附加 Bearer Token
响应拦截器：
- 检查 ResponseData.success 字段，失败时 Toast 提示并 reject
- 401 错误清除 Token 跳转登录
- 网络错误友好提示

5.2 API 模块与后端端点对照

礼品管理 (`api/gifts.ts`)

前端函数	HTTP 方法	后端端点
`getGifts()`	GET	`/api/admin/gifts`
`getGiftById(id)`	GET	`/api/admin/gifts/{GiftId}`
`createGift(data)`	POST	`/api/admin/gifts`
`updateGift(id, data)`	PUT	`/api/admin/gifts/{GiftId}`
`putOnShelf(id)`	POST	`/api/admin/gifts/{GiftId}/putonshelf`
`putOffShelf(id)`	POST	`/api/admin/gifts/{GiftId}/putoffshelf`
`addGiftStock(id, quantity)`	POST	`/api/admin/gifts/{GiftId}/addstock`

订单管理 (`api/orders.ts`)

前端函数	HTTP 方法	后端端点
`getOrders()`	GET	`/api/admin/redemption-orders`
`getOrderById(id)`	GET	`/api/admin/redemption-orders/{OrderId}`
`dispatchOrder(data)`	POST	`/api/admin/redemption-orders/{OrderId}/dispatch`
`completeOrder(orderId)`	POST	`/api/admin/redemption-orders/{OrderId}/complete`
`cancelOrder(data)`	POST	`/api/admin/redemption-orders/{OrderId}/cancel`

营销码管理 (`api/marketing-codes.ts`)

前端函数	HTTP 方法	后端端点
`generateMarketingCodes(data)`	POST	`/api/admin/marketing-codes/generate`

积分规则 (`api/points-rules.ts`)

前端函数	HTTP 方法	后端端点
`createPointsRule(data)`	POST	`/api/admin/points-rules`

会员查询 (`api/members.ts`)

前端函数	HTTP 方法	后端端点
`getMemberById(memberId)`	GET	`/api/members/{MemberId}`

六、类型定义

6.1 统一响应格式 (`types/api.ts`)

interface ResponseData<T> {
  success: boolean
  code: number
  message: string
  data: T
}

6.2 枚举常量 (`types/enums.ts`)

由于 TypeScript erasableSyntaxOnly 限制，使用 const as const 模式定义枚举：

// 礼品类型
GiftType.Physical = 1    // 实物
GiftType.Virtual = 2     // 虚拟
GiftType.Product = 3     // 自有产品

// 订单状态
OrderStatus.Pending = 1      // 待处理
OrderStatus.Dispatched = 2   // 已发货
OrderStatus.Delivered = 3    // 已送达
OrderStatus.Completed = 4    // 已完成
OrderStatus.Cancelled = 5    // 已取消

// 积分规则类型
PointsRuleType.Product = 1       // 产品规则
PointsRuleType.Time = 2          // 时间规则
PointsRuleType.MemberLevel = 3   // 会员等级规则

6.3 核心 DTO 类型

文件	接口	对应后端 DTO
`gift.ts`	`GiftDto`	礼品列表/详情数据
`gift.ts`	`CreateGiftRequest`	创建礼品请求体
`gift.ts`	`UpdateGiftRequest`	更新礼品请求体
`order.ts`	`RedemptionOrderDto`	订单列表/详情数据
`order.ts`	`RedemptionOrderAddressDto`	收货地址
`order.ts`	`DispatchOrderRequest`	发货请求体
`order.ts`	`CancelOrderRequest`	取消订单请求体
`member.ts`	`MemberDto`	会员信息
`marketing-code.ts`	`GenerateMarketingCodesRequest/Response`	生成营销码请求/响应
`points-rule.ts`	`CreatePointsRuleRequest/Response`	创建积分规则请求/响应

七、页面功能详情

7.1 登录页 (`/login`)

居中卡片式表单，用户名 + 密码
Mock 认证，成功后跳转仪表盘
表单验证：用户名和密码不为空

7.2 仪表盘 (`/dashboard`)

统计卡片（4 个）：总礼品数 / 待处理订单 / 已上架礼品 / 已完成订单
近期订单表：最新 5 条订单，显示订单号、礼品名、状态 Badge、时间
库存预警表：可用库存 < 10 的上架礼品，低库存红色高亮
数据来源：并行调用 getGifts() + getOrders() 计算统计

7.3 礼品列表 (`/gifts`)

筛选栏：礼品类型 Select（全部/实物/虚拟/产品）+ 上架状态 Select（全部/已上架/未上架）
数据表格：名称、类型 Badge、所需积分、总库存、可用库存（低库存高亮）、上架 Switch、时间、操作列
操作：
- 编辑按钮 → 跳转编辑页
- 上下架 Switch → 调用 putOnShelf/putOffShelf + Toast 反馈
- 增加库存按钮 → Dialog 输入数量 → 调用 addGiftStock
创建礼品按钮 → 跳转创建页

7.4 礼品创建/编辑 (`/gifts/create` | `/gifts/edit/:id`)

表单字段：名称、类型 Select（编辑时禁用）、描述 Textarea、图片 URL（含预览）、所需积分、总库存（编辑时禁用）、每人限兑
表单验证：必填字段非空、积分/库存为正数
模式判断：通过 route.params.id 区分创建/编辑，编辑时自动加载礼品数据

7.5 订单列表 (`/orders`)

筛选：订单状态 Select（全部/待处理/已发货/已送达/已完成/已取消）
数据表格：订单号、会员 ID（截短）、礼品名、数量、消耗积分、状态 Badge、时间、操作列
操作（根据状态动态显示）：
- 待处理 → 发货按钮（Dialog 输入物流单号）、取消按钮
- 已发货/已送达 → 完成按钮、取消按钮
- 所有状态 → 详情按钮
Dialog 交互：发货需输入物流单号（可选）、取消需输入原因（必填）

7.6 订单详情 (`/orders/:id`)

订单信息卡片：订单号、状态大 Badge、创建/更新时间、取消原因（如有）
礼品信息卡片：礼品名、类型 Badge、数量、消耗积分
收货地址卡片（仅实物）：收货人、电话、地址、物流单号
操作按钮：根据状态显示发货/完成/取消按钮 + 返回列表按钮

7.7 营销码管理 (`/marketing-codes`)

生成表单：批次号、产品 ID、产品名称、生成数量（1-10000）、过期时间（可选）
生成结果：显示批次号和数量，Table 列出所有营销码（等宽字体）
操作：单个复制按钮、复制全部按钮、导出 CSV 按钮

7.8 积分规则管理 (`/points-rules`)

创建表单：规则名称、规则类型 Select、积分值、奖励倍数（默认 1.0）、开始/结束时间
动态条件字段：
- 产品规则 → 显示产品 ID + 品类 ID 输入框
- 会员等级规则 → 显示会员等级编码输入框
- 时间规则 → 无额外字段
创建成功后自动清空表单

7.9 会员查询 (`/members`)

搜索区域：会员 ID 输入框（GUID 格式）+ 查询按钮
结果展示（2x2 网格）：
- 基本信息：ID、手机号、昵称
- 等级信息：等级编码、等级名称 Badge
- 积分信息：累计总积分、可用积分（大号字体）
- 账户状态：正常/禁用 Badge、注册时间

八、UI 组件使用

8.1 已安装的 shadcn-vue 组件

组件	用途
Button	操作按钮
Input	文本输入
Textarea	多行文本
Label	表单标签
Select	下拉选择（筛选器、类型选择）
Table	数据表格
Card	卡片容器
Dialog	对话框（发货/取消/库存）
Badge	状态标签
Switch	开关（上下架）
Tabs	标签页
Separator	分隔线
Avatar	头像
Breadcrumb	面包屑导航
Scroll Area	滚动区域
Sheet	侧边抽屉
Dropdown Menu	下拉菜单
Popover	弹出框
Tooltip	工具提示
Sonner	Toast 消息

8.2 添加新 shadcn-vue 组件

cd Frontend/Fengling.Backend.Admin
npx shadcn-vue@latest add [组件名]

九、当前状态与后续建议

9.1 当前状态

已完成：

项目基础架构搭建（Vite + Vue 3 + TypeScript + shadcn-vue）
全部 9 个管理页面的 UI 与交互逻辑
覆盖后端全部 15 个管理端 API 端点
路由守卫 + Mock 认证
pnpm build 通过，无类型错误
生产构建产物约 155KB JS (gzip ~57KB)

已知限制：

认证为 Mock 模式，需后端 JWT 完善后对接
列表页无分页，需后端添加分页接口后实现
表单验证为手动实现，未使用 VeeValidate 等验证库

9.2 后续建议

对接真实认证

修改 stores/auth.ts 的 login() 方法，调用后端登录 API
保存返回的 JWT Token 到 localStorage
无需修改 api/client.ts（拦截器已适配 Bearer Token 模式）

功能增强

分页：后端添加分页支持后，在列表页添加 Pagination 组件
积分规则列表：后端暴露查询端点后，在积分规则页添加已有规则列表
营销码查询：后端添加查询端点后，支持按批次号查看历史生成记录
数据导出：为订单列表、礼品列表添加 Excel/CSV 导出功能
仪表盘图表：引入 ECharts/Chart.js 添加趋势图表

技术优化

引入 VeeValidate 进行表单验证
大数据量场景引入虚拟滚动
添加 Vitest 单元测试

15 KiB Raw Permalink Blame History Unescape Escape