611 lines
26 KiB
Markdown
611 lines
26 KiB
Markdown
# 窗帘工厂管理系统 — 技术框架与功能简介
|
||
|
||
## 一、项目概述
|
||
|
||
窗帘工厂管理系统是一套面向窗帘制造企业的全流程业务管理平台，覆盖从客户预约、测量报价、订单生产、安装交付到售后服务的完整业务闭环，同时整合财务管理、采购库存、人员管理、数据分析等支撑模块。
|
||
|
||
- **项目名称**：窗帘工厂管理系统 (Curtain Factory Management System)
|
||
- **版本**：v1.0.0
|
||
- **开发语言**：前端 JavaScript (Vue 3) / 后端 Java (Spring Boot)
|
||
- **界面语言**：简体中文
|
||
|
||
---
|
||
|
||
## 二、全栈技术架构
|
||
|
||
### 2.1 架构全景图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 客户端 (Browser) │
|
||
│ Vue 3 + Vite · Pinia · Chart.js · Font Awesome │
|
||
│ Hash Router · 路由懒加载 · 路由守卫 │
|
||
└──────────────────────────┬──────────────────────────────────────┘
|
||
│ HTTP / JSON (RESTful API)
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 网关层 (Nginx / Gateway) │
|
||
│ 反向代理 · 负载均衡 · HTTPS · 静态资源 │
|
||
└──────────────────────────┬──────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 业务服务层 (Spring Boot 2.7) │
|
||
│ ┌─────────────┬────────────────┬─────────────────────────────┐ │
|
||
│ │Spring Sec │ AOP 切面 │ 全局异常处理 @RestControllerAdvice │
|
||
│ │JWT 认证 │ 操作日志 │ 统一响应体 R<T> │
|
||
│ │RBAC 鉴权 │ 接口限流 │ 参数校验 JSR-303 │
|
||
│ └─────────────┴────────────────┴─────────────────────────────┘ │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ Controller → Service → Repository (JPA/Hibernate) │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────┬──────────────────────────────────────┘
|
||
│
|
||
┌────────────┴────────────┐
|
||
▼ ▼
|
||
┌──────────────────────┐ ┌──────────────────────┐
|
||
│ MySQL 8.0 (主库) │ │ Redis (缓存/Session) │
|
||
│ · 读写分离 │ │ · JWT Token 黑名单 │
|
||
│ · 慢查询日志 │ │ · 验证码存储 │
|
||
│ · 索引优化 │ │ · 热点数据缓存 │
|
||
└──────────────────────┘ └──────────────────────┘
|
||
```
|
||
|
||
### 2.2 技术栈明细
|
||
|
||
| 层级 | 技术选型 | 版本 | 用途 |
|
||
|------|----------|------|------|
|
||
| **前端框架** | Vue 3 (Composition API) | ^3.3.4 | 组件化 UI 构建 |
|
||
| **构建工具** | Vite | ^4.4.5 | 开发服务器 / HMR / 生产构建 |
|
||
| **路由管理** | Vue Router | ^4.6.4 | Hash 模式 SPA 路由 |
|
||
| **状态管理** | Pinia | ^2.1.7 | 全局状态与跨组件通信 |
|
||
| **图表可视化** | Chart.js | ^4.4.0 | KPI 仪表盘与数据分析图表 |
|
||
| **图标库** | Font Awesome 6 | CDN | 2000+ 矢量图标 |
|
||
| **样式方案** | CSS Variables + Scoped CSS | — | 设计令牌 + 组件隔离 |
|
||
| **后端框架** | Spring Boot | 2.7.x | 约定优于配置的微服务基座 |
|
||
| **安全框架** | Spring Security + JWT | — | 无状态认证 + RBAC 鉴权 |
|
||
| **ORM** | Spring Data JPA (Hibernate) | — | 对象关系映射 |
|
||
| **缓存** | Redis | 7.x | Token 黑名单 / 验证码 / 热点缓存 |
|
||
| **数据库** | MySQL | 8.0 | 主数据存储 |
|
||
| **API 文档** | Knife4j (Swagger) | — | 自动生成 RESTful API 文档 |
|
||
| **构建工具** | Maven | 3.8+ | 依赖管理与打包 |
|
||
|
||
---
|
||
|
||
## 三、前端项目架构
|
||
|
||
### 3.1 目录结构
|
||
|
||
```
|
||
html-vue3/
|
||
├── index.html # 入口 HTML（挂载 #app + Font Awesome CDN）
|
||
├── package.json # 项目依赖与 pnpm/npm 脚本
|
||
├── vite.config.js # Vite 配置（@别名 / 端口3001）
|
||
│
|
||
└── src/
|
||
├── main.js # 应用入口：createApp → Pinia → Router
|
||
├── App.vue # 根组件（<router-view> 路由出口）
|
||
│
|
||
├── assets/css/
|
||
│ └── global.css # 全局样式：CSS变量 / 卡片 / 按钮 / 表格 / 模态框 / Toast
|
||
│
|
||
├── components/
|
||
│ ├── common/
|
||
│ │ └── PagePlaceholder.vue
|
||
│ └── layout/
|
||
│ ├── MainLayout.vue # 主布局：Sidebar + TopBar + <router-view>
|
||
│ ├── Sidebar.vue # 左侧导航（260px / 可折叠 / 13组菜单）
|
||
│ └── TopBar.vue # 顶部栏（侧栏切换 / 面包屑 / 全局搜索 / 用户信息）
|
||
│
|
||
├── composables/ # 可复用逻辑
|
||
│ ├── useModal.js # 模态框 open/close/loading
|
||
│ ├── usePagination.js # 分页：page/size/total/pageChange
|
||
│ ├── useSearch.js # 搜索：keyword/loading/search
|
||
│ └── useToast.js # Toast：message/type/show/autoHide
|
||
│
|
||
├── router/index.js # 路由配置（Hash模式 / 42条路由 / 路由守卫）
|
||
│
|
||
├── stores/ # Pinia 状态管理
|
||
│ ├── customerStore.js # 客户 CRUD + 统计
|
||
│ ├── orderStore.js # 订单 CRUD + 状态流转
|
||
│ └── userStore.js # 登录/登出/持久化
|
||
│
|
||
├── utils/
|
||
│ └── dataService.js # 演示数据生成器
|
||
│
|
||
└── views/ # 42 个业务页面（按模块分目录）
|
||
├── Login.vue
|
||
├── Dashboard.vue
|
||
├── Workflow.vue
|
||
├── NotFound.vue
|
||
├── customer/ # 3页
|
||
├── quote/ # 2页
|
||
├── order/ # 6页
|
||
├── production/ # 3页
|
||
├── install/ # 4页
|
||
├── aftersale/ # 2页
|
||
├── finance/ # 2页
|
||
├── purchase/ # 3页
|
||
├── product/ # 2页
|
||
├── staff/ # 2页
|
||
├── system/ # 5页
|
||
└── analysis/ # 4页
|
||
```
|
||
|
||
### 3.2 前端技术亮点
|
||
|
||
| 特性 | 实现方式 |
|
||
|------|----------|
|
||
| **Composition API** | 全部页面采用 `<script setup>`，逻辑内聚 |
|
||
| **路由懒加载** | `() => import(...)` 动态按需加载，首屏 < 2s |
|
||
| **路由守卫** | `beforeEach` 检测 localStorage 登录态，未授权 → `/login` |
|
||
| **统一布局容器** | `.page-wrapper(24px) → .page-container(1600px居中)` 双重约束 |
|
||
| **响应式设计** | 4 级断点：≥1200 / 768-1199 / 480-767 / ≤480 |
|
||
| **CSS 设计令牌** | `:root` 定义 `--primary / --radius / --shadow`，全局可换肤 |
|
||
| **全局搜索** | TopBar 内建 18 个页面索引，实时模糊匹配 |
|
||
|
||
---
|
||
|
||
## 四、后端架构设计（Spring Boot 2.7）
|
||
|
||
### 4.1 分层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ Controller 层 (RESTful API) │
|
||
│ @RestController · @Validated · R<T> │
|
||
├─────────────────────────────────────────┤
|
||
│ Service 层 (业务逻辑) │
|
||
│ @Transactional · 缓存注解 · 业务编排 │
|
||
├─────────────────────────────────────────┤
|
||
│ Repository 层 (数据访问) │
|
||
│ JpaRepository · @Query · 分页查询 │
|
||
├─────────────────────────────────────────┤
|
||
│ Domain 层 (实体) │ DTO 层 (传输对象) │
|
||
│ @Entity · @Table │ 入参/出参分离 │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.2 推荐后端目录结构
|
||
|
||
```
|
||
curtain-factory-server/
|
||
├── pom.xml
|
||
├── src/main/java/com/pamido/curtain/
|
||
│ ├── CurtainApplication.java # Spring Boot 启动类
|
||
│ ├── config/
|
||
│ │ ├── SecurityConfig.java # Spring Security + JWT 配置
|
||
│ │ ├── RedisConfig.java # Redis 序列化配置
|
||
│ │ ├── CorsConfig.java # 跨域配置
|
||
│ │ └── Knife4jConfig.java # API 文档配置
|
||
│ ├── common/
|
||
│ │ ├── R.java # 统一响应体 {code, msg, data}
|
||
│ │ ├── PageResult.java # 分页结果
|
||
│ │ └── GlobalExceptionHandler.java # @RestControllerAdvice
|
||
│ ├── security/
|
||
│ │ ├── JwtTokenProvider.java # JWT 生成/验证/刷新
|
||
│ │ ├── JwtAuthenticationFilter.java # OncePerRequestFilter
|
||
│ │ └── UserDetailsServiceImpl.java # UserDetailsService
|
||
│ ├── module/
|
||
│ │ ├── customer/ # 客户模块
|
||
│ │ │ ├── CustomerController.java
|
||
│ │ │ ├── CustomerService.java
|
||
│ │ │ ├── CustomerRepository.java
|
||
│ │ │ ├── Customer.java # @Entity
|
||
│ │ │ ├── CustomerDTO.java
|
||
│ │ │ └── CustomerVO.java
|
||
│ │ ├── order/ # 订单模块 (同上)
|
||
│ │ ├── product/ # 产品模块
|
||
│ │ ├── finance/ # 财务模块
|
||
│ │ └── ...
|
||
│ └── aspect/
|
||
│ └── LogAspect.java # AOP 操作日志
|
||
└── src/main/resources/
|
||
├── application.yml # 主配置
|
||
├── application-dev.yml # 开发环境
|
||
└── application-prod.yml # 生产环境
|
||
```
|
||
|
||
---
|
||
|
||
## 五、功能模块一览
|
||
|
||
### 首页与总览（2页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 经营仪表盘 | `/dashboard` | KPI卡片 / 趋势图 / 排行榜 / 最新订单 / 待办 / 快捷入口 |
|
||
| 功能流程图 | `/workflow` | 业务全流程可视化 + 节点快捷跳转 |
|
||
|
||
### 客户管理（3页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 客户管理 | `/customer` | CRUD + 搜索筛选 + 分页 + 数据统计看板 |
|
||
| 预约测量 | `/customer/appointment` | 预约单管理 + 时间安排 + 状态跟踪 |
|
||
| 测量管理 | `/customer/measurement` | 测量任务分配 + 数据录入 + 进度管理 |
|
||
|
||
### 测量报价（2页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 测量报价 | `/quote` | 测量数据转报价 + 方案对比 |
|
||
| 报价表生成 | `/quote/generate` | 报价表CRUD + 方案A/B + 邮件/打印/复制 |
|
||
|
||
### 订单管理（6页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 订单管理 | `/order` | CRUD + 搜索筛选 + 分页 + 状态流转 |
|
||
| 订单跟踪 | `/order/tracking` | 全生命周期追踪 + 进度可视化 |
|
||
| 跟单页 | `/order/follow` | 跟单看板 + 客户沟通记录 |
|
||
| 定单明细 | `/order/detail` | 订单详情 + 产品明细 |
|
||
| 成交定单 | `/order/deal` | 成交订单管理 + 合同管理 |
|
||
| 复尺确认 | `/order/recheck` | 复尺分配 + 确认 + 安装前把控 |
|
||
|
||
### 生产管理（3页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 生产任务板 | `/production/task` | 任务看板 + 工序管理 + 状态跟踪 |
|
||
| 生产采购 | `/production/purchase` | 生产驱动采购发起 |
|
||
| 生产采购明细 | `/production/purchase-detail` | 采购明细 + 对账 |
|
||
|
||
### 安装管理（4页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 新增安装 | `/install/add` | 任务创建 + 人员/时间分配 |
|
||
| 安装任务板 | `/install/task` | 任务看板 + 状态管理 |
|
||
| 安装人员排班表 | `/install/schedule` | 日历排班 + 资源调配 |
|
||
| 安装完成 | `/install/complete` | 签收确认 + 满意度收集 |
|
||
|
||
### 售后管理（2页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 售后原因 | `/after-sale/reason` | 原因分类 + 分析 |
|
||
| 维修安排 | `/after-sale/arrange` | 维修工单 + 派工 + 跟踪 |
|
||
|
||
### 财务管理（2页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 收尾款 | `/finance/final-payment` | 尾款收款 + 到账确认 |
|
||
| 发票管理 | `/finance/invoice` | 发票申请 + 开具 + 寄送跟踪 |
|
||
|
||
### 采购库存（3页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 采购订单 | `/purchase/order` | CRUD + 审批流程 |
|
||
| 供应商管理 | `/purchase/supplier` | 信息维护 + 评估评级 |
|
||
| 库存管理 | `/purchase/inventory` | 出入库 + 库存盘点 |
|
||
|
||
### 产品管理（2页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 产品库管理 | `/product/library` | 产品信息 + 规格/定价 |
|
||
| 面料配件库 | `/product/material` | 面料/轨道/配件管理 |
|
||
|
||
### 人员管理（2页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 测量师管理 | `/staff/measurer` | 信息 + 资质 + 排班 |
|
||
| 安装师傅管理 | `/staff/installer` | 信息 + 技能评级 + 排班 |
|
||
|
||
### 系统设置（5页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 角色权限 | `/system/role` | 角色定义 + 权限分配 |
|
||
| 系统用户 | `/system/user` | 账号管理 + 密码重置 |
|
||
| 通知模板 | `/system/notification-template` | 短信/邮件模板 |
|
||
| 工作时间 | `/system/work-time` | 工作日/节假日配置 |
|
||
| 消息中心 | `/system/message` | 系统消息 + 站内信 |
|
||
|
||
### 数据分析（4页）
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 数据分析中心 | `/analysis/center` | 综合看板 + 交叉分析 |
|
||
| 报表分析 | `/analysis/report` | 定期报表 + 趋势 |
|
||
| 满意度调查 | `/analysis/satisfaction` | 满意度收集 + 统计 |
|
||
| 渠道管理 | `/analysis/channel` | 获客渠道 + 转化率 |
|
||
|
||
### 其他
|
||
|
||
| 页面 | 路由 | 功能说明 |
|
||
|------|------|----------|
|
||
| 登录页 | `/login` | 账号密码 + 验证码 + 快捷登录 |
|
||
| 404 | `/*` | 友好提示 + 首页回跳 |
|
||
|
||
---
|
||
|
||
## 六、快速开始
|
||
|
||
### 6.1 环境要求
|
||
|
||
| 组件 | 版本 |
|
||
|------|------|
|
||
| Node.js | 18.0+ |
|
||
| JDK | 11 或 17 |
|
||
| MySQL | 8.0+ |
|
||
| Redis | 7.x |
|
||
| Maven | 3.8+ |
|
||
|
||
### 6.2 前端启动
|
||
|
||
```bash
|
||
cd html-vue3
|
||
npm install
|
||
npm run dev # → http://localhost:3001
|
||
npm run build # 生产构建 → dist/
|
||
```
|
||
|
||
### 6.3 后端启动（规划）
|
||
|
||
```bash
|
||
cd curtain-factory-server
|
||
mvn clean package -DskipTests
|
||
java -jar target/curtain-factory-1.0.0.jar --spring.profiles.active=dev
|
||
# API 文档 → http://localhost:8080/doc.html
|
||
```
|
||
|
||
### 6.4 演示账号
|
||
|
||
| 角色 | 账号 | 密码 |
|
||
|------|------|------|
|
||
| 管理员 | admin | admin123 |
|
||
| 普通用户 | user | user123 |
|
||
|
||
---
|
||
|
||
## 七、产品经理视角 — 代码审查与优化建议
|
||
|
||
### 7.1 功能完整度评估
|
||
|
||
| 维度 | 当前状态 | 评分 | 问题 |
|
||
|------|---------|------|------|
|
||
| 核心业务流 | ✅ 客户→报价→订单→安装→售后完整串联 | ⭐⭐⭐⭐ | — |
|
||
| CRUD 操作 | ⚠️ 部分页面仅占位，无完整 CRUD | ⭐⭐ | `PagePlaceholder` 覆盖不够 |
|
||
| 演示数据 | ⚠️ 数据分散在各自组件内 | ⭐⭐ | 无统一数据工厂 |
|
||
| 表单校验 | ❌ 无校验框架 | ⭐ | 提交无拦截、无错误提示 |
|
||
| 操作反馈 | ⚠️ Toast 已统一但非所有操作都触发 | ⭐⭐ | 删改无确认对话框 |
|
||
| 权限控制 | ❌ 仅路由级区分，UI 无差异 | ⭐ | 按钮不隐藏、菜单全可见 |
|
||
| 异常处理 | ❌ 无全局错误捕获 | ⭐ | 接口失败无用户提示 |
|
||
| 加载状态 | ❌ 无骨架屏/loading | ⭐ | 数据为空时仅空白 |
|
||
| 导出功能 | ⚠️ 仅按钮入口无实现 | ⭐ | Excel/PDF 导出缺失 |
|
||
| 打印功能 | ⚠️ 仅 QuoteGenerate 有媒体查询 | ⭐⭐ | 其他页面无打印样式 |
|
||
|
||
### 7.2 产品层优先优化项
|
||
|
||
| 优先级 | 优化项 | 说明 |
|
||
|--------|--------|------|
|
||
| **P0** | 引入 Axios + 拦截器 + 统一错误处理 | 所有页面目前使用硬编码数据，必须先建立 HTTP 通信层 |
|
||
| **P0** | 全局 Loading/Skeleton 状态 | 用户等待时必须看到反馈，否则造成"页面坏了"的错觉 |
|
||
| **P1** | 操作确认弹窗 (ConfirmDialog) | 删除/状态变更等不可逆操作必须有二次确认 |
|
||
| **P1** | 表单校验 (vee-validate 或原生) | 必填拦截、格式校验、实时错误提示 |
|
||
| **P1** | 按钮级权限指令 `v-permission` | 无权限按钮直接移除 DOM，而非仅置灰 |
|
||
| **P2** | Excel 导入导出 (xlsx 库) | 批量操作必须支持导入导出 |
|
||
| **P2** | 通知中心 WebSocket 实时推送 | 当前消息中心为静态页面 |
|
||
| **P2** | 操作日志与审计轨迹 | 敏感操作记录操作人/时间/IP |
|
||
|
||
---
|
||
|
||
## 八、架构师视角 — 代码审查与优化建议
|
||
|
||
### 8.1 前端架构问题诊断
|
||
|
||
| 问题 | 严重度 | 现状 | 改进方案 |
|
||
|------|--------|------|----------|
|
||
| **无 HTTP 请求层** | 🔴 严重 | 数据全部硬编码在组件/composables | 建立 `utils/request.js`→Axios实例→拦截器链 |
|
||
| **Store 不调用 API** | 🔴 严重 | `stores/` 内只有静态 ref，无 async action | Store 负责调用 API + 缓存，组件只读 store |
|
||
| **路由守卫绕过 Store** | 🟡 中等 | `router.beforeEach` 直接读 `localStorage` | 应读 `userStore.isLoggedIn`，Store 是唯一真相源 |
|
||
| **无 TypeScript** | 🟡 中等 | 全项目 `.js` | 渐进式迁移：先 `stores/`→`api/`→组件 |
|
||
| **Composables 粗粒度** | 🟡 中等 | `useSearch`/`usePagination` 只管理状态 | 应内置请求逻辑：search → API → results |
|
||
| **菜单硬编码** | 🟡 中等 | `Sidebar.vue` 内 menuGroups 数组 | 应抽为 `config/menu.js` + 后端权限动态返回 |
|
||
| **无 env 配置** | 🟡 中等 | API 地址无处配置 | `.env.development` / `.env.production` |
|
||
| **CSS 变量不全** | 🟢 低 | 缺 `--danger / --warning / --success` 语义色 | 补齐设计令牌，全局一致性 |
|
||
| **无测试** | 🟢 低 | 无 Vitest/Jest | 核心逻辑 + Store 优先覆盖 |
|
||
| **Chart.js 功能有限** | 🟢 低 | 仅支持基础图表 | 复杂分析场景建议升级 ECharts |
|
||
|
||
### 8.2 前端重构路线图
|
||
|
||
```
|
||
阶段一：通信基座（本周）
|
||
├─ 新建 src/api/
|
||
│ ├── request.js # Axios 实例 + 拦截器
|
||
│ ├── modules/
|
||
│ │ ├── customer.js # 客户 API
|
||
│ │ ├── order.js # 订单 API
|
||
│ │ └── ...
|
||
│ └── index.js
|
||
├─ 新建 .env.development # VITE_API_BASE_URL=http://localhost:8080
|
||
└─ 重构 stores/ → async actions 调用 api/
|
||
|
||
阶段二：工程质量（下周）
|
||
├─ ESLint + Prettier 配置
|
||
├─ TypeScript 初始化（tsconfig.json）
|
||
├─ stores/ 迁移 .js → .ts
|
||
├─ v-permission 指令
|
||
└─ Vue DevTools 调试规范
|
||
|
||
阶段三：体验增强（两周内）
|
||
├─ 骨架屏组件 (Skeleton.vue)
|
||
├─ ConfirmDialog 全局组件
|
||
├─ vee-validate 表单校验
|
||
├─ Excel 导入导出
|
||
└─ 全局错误边界 (ErrorBoundary)
|
||
```
|
||
|
||
### 8.3 前端推荐新增目录
|
||
|
||
```
|
||
src/
|
||
├── api/ # ★ 新增：HTTP 请求层
|
||
│ ├── request.js # Axios 封装（baseURL/interceptor/retry）
|
||
│ ├── index.js
|
||
│ └── modules/
|
||
│ ├── auth.js
|
||
│ ├── customer.js
|
||
│ ├── order.js
|
||
│ ├── product.js
|
||
│ ├── finance.js
|
||
│ └── ...
|
||
├── config/
|
||
│ └── menu.js # ★ 新增：菜单配置（从 Sidebar.vue 抽取）
|
||
├── directives/
|
||
│ └── permission.js # ★ 新增：v-permission 指令
|
||
├── plugins/
|
||
│ └── echarts.js # ★ 可选：ECharts 按需引入
|
||
└── types/ # ★ 新增：TypeScript 类型定义
|
||
├── api.d.ts
|
||
└── models.d.ts
|
||
```
|
||
|
||
### 8.4 前端 API 层设计规范
|
||
|
||
```javascript
|
||
// src/api/request.js
|
||
import axios from 'axios'
|
||
import { useUserStore } from '@/stores/userStore'
|
||
import { ElMessage } from 'element-plus' // 或自定义 Toast
|
||
|
||
const request = axios.create({
|
||
baseURL: import.meta.env.VITE_API_BASE_URL,
|
||
timeout: 30000
|
||
})
|
||
|
||
// 请求拦截 — 自动附带 JWT
|
||
request.interceptors.request.use(config => {
|
||
const token = localStorage.getItem('accessToken')
|
||
if (token) config.headers.Authorization = `Bearer ${token}`
|
||
return config
|
||
})
|
||
|
||
// 响应拦截 — 统一解包 + 错误处理 + Token 刷新
|
||
request.interceptors.response.use(
|
||
res => res.data, // 自动解包 R<T> → data
|
||
async err => {
|
||
if (err.response?.status === 401) {
|
||
// Token 过期 → 尝试 refreshToken → 失败则跳登录
|
||
useUserStore().logout()
|
||
router.push('/login')
|
||
}
|
||
ElMessage.error(err.response?.data?.msg || '网络异常')
|
||
return Promise.reject(err)
|
||
}
|
||
)
|
||
|
||
export default request
|
||
```
|
||
|
||
### 8.5 后端架构要点
|
||
|
||
| 设计点 | 推荐方案 |
|
||
|--------|----------|
|
||
| **API 规范** | RESTful：`GET /api/orders` `POST /api/orders` `PUT /api/orders/{id}` `DELETE /api/orders/{id}` |
|
||
| **统一响应体** | `R<T>`：`{ code: 200, msg: "success", data: T }` |
|
||
| **分页响应** | `PageResult<T>`：`{ total, page, size, list }` |
|
||
| **参数校验** | `@Validated` + JSR-303 注解（`@NotBlank/@NotNull/@Min`） |
|
||
| **异常处理** | `@RestControllerAdvice` 全局捕获 → 转 `R.fail(code, msg)` |
|
||
| **JWT 设计** | AccessToken(2h) + RefreshToken(7d) 双令牌 |
|
||
| **Redis 缓存** | `@Cacheable` 查 / `@CacheEvict` 删，Key: `customer:{id}` |
|
||
| **AOP 日志** | `@Log("新增客户")` 注解驱动，记录 operator / IP / params |
|
||
| **事务管理** | Service 层 `@Transactional`，RuntimeException 自动回滚 |
|
||
| **SQL 审计** | `p6spy` 打印完整 SQL + 参数 |
|
||
|
||
### 8.6 后端统一响应体示例
|
||
|
||
```java
|
||
@Data
|
||
@NoArgsConstructor
|
||
@AllArgsConstructor
|
||
public class R<T> {
|
||
private int code;
|
||
private String msg;
|
||
private T data;
|
||
|
||
public static <T> R<T> ok(T data) {
|
||
return new R<>(200, "success", data);
|
||
}
|
||
public static <T> R<T> fail(int code, String msg) {
|
||
return new R<>(code, msg, null);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 九、前后端对接规范
|
||
|
||
| 前端 | 后端 | 说明 |
|
||
|------|------|------|
|
||
| `stores/` async actions | `@RestController` | Store 调用 API，组件调用 Store |
|
||
| `.env` 中的 `VITE_API_BASE_URL` | `application.yml server.port` | 开发/生产环境切换 |
|
||
| `import.meta.env.VITE_API_BASE_URL` | — | Vite 编译时注入 |
|
||
| `Authorization: Bearer {token}` | `JwtAuthenticationFilter` | 无状态认证 |
|
||
| `page / size` 查询参数 | `Pageable` (Spring Data) | 分页统一协议 |
|
||
| `{ code, msg, data }` | `R<T>` | 统一响应解包 |
|
||
|
||
---
|
||
|
||
## 十、设计说明
|
||
|
||
### 10.1 布局约束
|
||
|
||
```
|
||
.page-wrapper (padding: 24px) ← 侧边栏↔内容区间距
|
||
└── .page-container ← max-width: 1600px + margin: auto 居中
|
||
└── .{page-specific} ← 页面特有样式
|
||
```
|
||
|
||
### 10.2 响应式断点
|
||
|
||
| 断点 | 策略 |
|
||
|------|------|
|
||
| ≥ 1200px | 双列 + 完整侧边栏 |
|
||
| 768-1199px | 单列 + 表格横滚 |
|
||
| 480-767px | 48px 触控区域 |
|
||
| ≤ 480px | 紧凑布局 |
|
||
|
||
---
|
||
|
||
## 十一、总评分与行动建议
|
||
|
||
### 当前版本评分
|
||
|
||
| 评估维度 | 评分 | 评语 |
|
||
|----------|------|------|
|
||
| 功能覆盖度 | ⭐⭐⭐⭐ (4/5) | 42页面覆盖全业务流程，部分占位需补全 |
|
||
| 前端架构 | ⭐⭐⭐ (3/5) | 组件化良好，缺 HTTP 层和 TS |
|
||
| 代码质量 | ⭐⭐⭐ (3/5) | Composition API 使用正确，但缺规范约束 |
|
||
| 用户体验 | ⭐⭐⭐ (3/5) | 响应式 + 统一布局不错，缺加载/错误/确认 |
|
||
| 可扩展性 | ⭐⭐⭐ (3/5) | 模块化清晰，后端对接需重构 Store |
|
||
| 生产就绪度 | ⭐⭐ (2/5) | 纯演示版，不可直接上线 |
|
||
|
||
### 🔥 立即行动（本周必做）
|
||
|
||
1. **建立 `src/api/` 层**：Axios 封装 + 拦截器 + 统一错误处理
|
||
2. **重构 `stores/`**：async actions 调用 API，移除硬编码数据
|
||
3. **添加 `.env` 配置**：开发/生产环境 API 地址
|
||
|
||
### 📋 短期计划（两周内）
|
||
|
||
4. 表单校验 + 操作确认弹窗
|
||
5. 按钮级权限指令
|
||
6. 全局 Loading/Skeleton
|
||
7. ESLint + Prettier 配置
|
||
8. 后端 Spring Boot 项目搭建
|
||
|
||
### 🎯 中期计划（一月内）
|
||
|
||
9. TypeScript 渐进迁移
|
||
10. ECharts 替换 Chart.js（分析模块）
|
||
11. Excel 导入导出
|
||
12. 后端全部模块 Controller/Service/Repository
|
||
13. CI/CD Pipeline (GitHub Actions / Jenkins)
|