## 前端管理后台功能概览

> 本文档说明管理后台前端(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 运行命令

```bash
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`)

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

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

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

```typescript
// 礼品类型
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 组件

```bash
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 后续建议

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

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

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