niumalll/admin-system/README.md

# Admin System - 活牛采购智能数字化系统管理后台

## 📋 项目概述

活牛采购智能数字化系统管理后台是基于Vue 3 + TypeScript的现代化Web应用，为系统管理员、内部员工提供全面的业务管理和数据分析功能。

**核心功能：**
- 👥 用户权限管理（采购人、贸易商、供应商、司机）
- 📦 订单全流程管理和监控
- 🚛 运输跟踪和状态监控
- 💰 结算财务管理
- 📊 数据统计和分析报表
- ⚙️ 系统配置和维护

## 🛠 技术栈

| 类别 | 技术选型 | 版本 | 说明 |
|------|----------|------|------|
| **前端框架** | Vue 3 | ^3.3.0 | Composition API + `<script setup>` |
| **开发语言** | TypeScript | ^5.0.0 | 类型安全和智能提示 |
| **构建工具** | Vite | ^4.4.0 | 快速开发和构建 |
| **UI组件库** | Element Plus | ^2.3.0 | 企业级组件库 |
| **状态管理** | Pinia | ^2.1.0 | Vue 3官方推荐 |
| **路由管理** | Vue Router | ^4.2.0 | 单页面应用路由 |
| **HTTP客户端** | Axios | ^1.4.0 | API请求处理 |
| **代码规范** | ESLint + Prettier | latest | 代码质量保证 |
| **CSS预处理** | Sass/SCSS | ^1.64.0 | 样式管理 |
| **图标库** | @element-plus/icons-vue | ^2.1.0 | 图标组件 |

## 📂 项目结构

```
admin-system/
├── public/                     # 公共资源
│   ├── favicon.ico
│   └── index.html
├── src/
│   ├── api/                    # API接口定义
│   │   ├── auth.ts            # 认证相关API
│   │   ├── user.ts            # 用户管理API
│   │   ├── order.ts           # 订单管理API
│   │   ├── transport.ts       # 运输跟踪API
│   │   └── settlement.ts      # 结算管理API
│   ├── assets/                 # 静态资源
│   │   ├── images/
│   │   ├── icons/
│   │   └── styles/
│   │       ├── index.scss     # 全局样式
│   │       ├── variables.scss # SCSS变量
│   │       └── mixins.scss    # SCSS混入
│   ├── components/             # 公共组件
│   │   ├── common/            # 通用组件
│   │   │   ├── AppHeader.vue
│   │   │   ├── AppSidebar.vue
│   │   │   ├── AppBreadcrumb.vue
│   │   │   └── PageContainer.vue
│   │   ├── charts/            # 图表组件
│   │   │   ├── LineChart.vue
│   │   │   ├── BarChart.vue
│   │   │   └── PieChart.vue
│   │   └── forms/             # 表单组件
│   │       ├── UserForm.vue
│   │       ├── OrderForm.vue
│   │       └── SearchForm.vue
│   ├── composables/            # 组合式函数
│   │   ├── useAuth.ts         # 认证逻辑
│   │   ├── useTable.ts        # 表格通用逻辑
│   │   ├── useDialog.ts       # 弹窗逻辑
│   │   └── usePermission.ts   # 权限控制
│   ├── router/                 # 路由配置
│   │   ├── index.ts           # 路由主文件
│   │   ├── routes.ts          # 路由定义
│   │   └── guards.ts          # 路由守卫
│   ├── stores/                 # Pinia状态管理
│   │   ├── auth.ts            # 认证状态
│   │   ├── user.ts            # 用户状态
│   │   ├── order.ts           # 订单状态
│   │   └── app.ts             # 应用全局状态
│   ├── types/                  # TypeScript类型定义
│   │   ├── api.ts             # API响应类型
│   │   ├── user.ts            # 用户类型
│   │   ├── order.ts           # 订单类型
│   │   └── common.ts          # 通用类型
│   ├── utils/                  # 工具函数
│   │   ├── request.ts         # 请求封装
│   │   ├── storage.ts         # 本地存储
│   │   ├── format.ts          # 格式化工具
│   │   ├── validator.ts       # 表单验证
│   │   └── constants.ts       # 常量定义
│   ├── views/                  # 页面组件
│   │   ├── auth/              # 认证页面
│   │   │   ├── Login.vue
│   │   │   └── ForgotPassword.vue
│   │   ├── dashboard/         # 仪表盘
│   │   │   └── Dashboard.vue
│   │   ├── user/              # 用户管理
│   │   │   ├── UserList.vue
│   │   │   ├── UserDetail.vue
│   │   │   └── UserRoles.vue
│   │   ├── order/             # 订单管理
│   │   │   ├── OrderList.vue
│   │   │   ├── OrderDetail.vue
│   │   │   ├── OrderFlow.vue
│   │   │   └── OrderTracking.vue
│   │   ├── transport/         # 运输管理
│   │   │   ├── TransportList.vue
│   │   │   ├── TransportMap.vue
│   │   │   └── VehicleManage.vue
│   │   ├── settlement/        # 结算管理
│   │   │   ├── SettlementList.vue
│   │   │   ├── PaymentRecord.vue
│   │   │   └── FinancialReport.vue
│   │   ├── system/            # 系统管理
│   │   │   ├── SystemConfig.vue
│   │   │   ├── LogManage.vue
│   │   │   └── DataBackup.vue
│   │   └── error/             # 错误页面
│   │       ├── 404.vue
│   │       └── 500.vue
│   ├── App.vue                 # 根组件
│   └── main.ts                 # 应用入口
├── tests/                      # 测试文件
│   ├── unit/                  # 单元测试
│   └── e2e/                   # 端到端测试
├── .env.development           # 开发环境配置
├── .env.production            # 生产环境配置
├── .eslintrc.js               # ESLint配置
├── .prettierrc                # Prettier配置
├── tsconfig.json              # TypeScript配置
├── vite.config.ts             # Vite配置
├── package.json               # 项目依赖
└── README.md                  # 项目文档
```

## 🚀 快速开始

### 环境要求
- Node.js >= 16.0.0
- npm >= 8.0.0 或 yarn >= 1.22.0
- 现代浏览器（Chrome 90+, Firefox 88+, Safari 14+）

### 安装依赖
```bash
cd admin-system
npm install
# 或
yarn install
```

### 开发环境启动
```bash
npm run dev
# 或
yarn dev
```

访问地址：http://localhost:3000

### 生产环境构建
```bash
npm run build
# 或
yarn build
```

### 代码检查和格式化
```bash
# ESLint检查
npm run lint

# 自动修复
npm run lint:fix

# Prettier格式化
npm run format
```

### 测试
```bash
# 单元测试
npm run test:unit

# 端到端测试
npm run test:e2e

# 测试覆盖率
npm run test:coverage
```

## 🔐 认证和权限

### 用户角色
| 角色 | 权限描述 | 功能范围 |
|------|----------|----------|
| **super_admin** | 超级管理员 | 所有功能和系统配置 |
| **admin** | 系统管理员 | 用户管理、订单管理、数据查看 |
| **operator** | 业务操作员 | 订单处理、运输跟踪 |
| **viewer** | 只读用户 | 数据查看和报表导出 |

### 权限控制
- **路由级权限**：基于用户角色控制页面访问
- **组件级权限**：控制按钮、菜单项的显示
- **数据级权限**：控制数据的增删改查权限
- **API级权限**：后端接口权限验证

### 默认账号
```
管理员账号：admin / admin123
操作员账号：operator / operator123
查看员账号：viewer / viewer123
```

## 📊 功能模块

### 1. 用户管理模块
- **用户列表**：查看所有系统用户
- **用户详情**：查看和编辑用户信息
- **角色管理**：分配和修改用户角色
- **权限配置**：细粒度权限控制

### 2. 订单管理模块
- **订单列表**：所有采购订单管理
- **订单详情**：订单完整信息展示
- **流程监控**：订单状态流转跟踪
- **异常处理**：订单异常情况处理

### 3. 运输跟踪模块
- **运输列表**：所有运输任务
- **实时地图**：GPS位置实时显示
- **车辆管理**：运输车辆信息
- **轨迹回放**：历史运输轨迹

### 4. 结算管理模块
- **结算列表**：所有结算记录
- **支付记录**：支付流水查询
- **财务报表**：各类财务统计
- **对账管理**：自动对账功能

### 5. 数据分析模块
- **业务仪表盘**：核心指标展示
- **统计报表**：多维度数据分析
- **图表可视化**：数据图表展示
- **报表导出**：Excel/PDF导出

## 🔧 开发规范

### 代码规范
- **命名规范**：
  - 组件名：PascalCase（如 `UserList.vue`）
  - 文件名：kebab-case（如 `user-list.vue`）
  - 变量名：camelCase（如 `userName`）
  - 常量名：UPPER_SNAKE_CASE（如 `API_BASE_URL`）

- **组件开发**：
  - 使用 Composition API + `<script setup>`
  - 统一使用 TypeScript
  - 组件props必须定义类型
  - 使用defineEmits定义事件

- **样式规范**：
  - 使用SCSS语法
  - 遵循BEM命名规范
  - 使用CSS变量定义主题色彩
  - 响应式设计适配

### Git提交规范
```
feat: 新增功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 其他修改
```

### 目录命名规范
- 页面组件放在 `views/` 目录
- 公共组件放在 `components/` 目录
- API接口放在 `api/` 目录
- 工具函数放在 `utils/` 目录
- 类型定义放在 `types/` 目录

## 🌐 API接口

### 接口基础配置
```typescript
// 开发环境
VITE_API_BASE_URL=http://localhost:3001/api
VITE_WS_BASE_URL=ws://localhost:3001

// 生产环境
VITE_API_BASE_URL=https://api.niumall.com/api
VITE_WS_BASE_URL=wss://api.niumall.com
```

### 核心接口模块
- **认证接口**：登录、登出、刷新token
- **用户接口**：用户CRUD、角色管理
- **订单接口**：订单管理、状态更新
- **运输接口**：GPS跟踪、状态上报
- **结算接口**：支付、对账、报表

## 📱 响应式设计

### 断点定义
```scss
$breakpoints: (
  xs: 0,
  sm: 576px,
  md: 768px,
  lg: 992px,
  xl: 1200px,
  xxl: 1400px
);
```

### 适配策略
- **桌面端**：1200px+ 完整功能
- **平板端**：768px-1199px 简化布局
- **手机端**：<768px 移动优化

## 🔍 性能优化

### 构建优化
- **代码分割**：路由级别的懒加载
- **资源压缩**：Gzip/Brotli压缩
- **缓存策略**：浏览器缓存配置
- **CDN加速**：静态资源CDN

### 运行时优化
- **虚拟列表**：大数据列表优化
- **图片懒加载**：减少初始加载
- **防抖节流**：高频操作优化
- **内存管理**：避免内存泄漏

## 🧪 测试策略

### 单元测试
- **组件测试**：Vue组件功能测试
- **工具函数测试**：纯函数测试
- **Store测试**：状态管理测试
- **覆盖率要求**：>80%

### 集成测试
- **API集成测试**：接口联调测试
- **路由测试**：页面跳转测试
- **权限测试**：权限控制测试

### E2E测试
- **关键流程测试**：用户核心操作路径
- **浏览器兼容性测试**：多浏览器测试
- **性能测试**：页面加载性能

## 🚀 部署指南

### 构建命令
```bash
# 开发环境构建
npm run build:dev

# 测试环境构建
npm run build:test

# 生产环境构建
npm run build:prod
```

### Nginx配置
```nginx
server {
    listen 80;
    server_name admin.niumall.com;
    
    location / {
        root /var/www/admin-system;
        try_files $uri $uri/ /index.html;
    }
    
    location /api {
        proxy_pass http://backend-server;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### Docker部署
```dockerfile
FROM nginx:alpine
COPY dist/ /usr/share/nginx/html/
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
```

## 🛡️ 安全措施

### 前端安全
- **XSS防护**：输入输出转义
- **CSRF防护**：Token验证
- **Content Security Policy**：内容安全策略
- **敏感信息保护**：避免敏感数据泄露

### 认证安全
- **JWT Token**：无状态认证
- **Token刷新**：自动刷新机制
- **权限验证**：多级权限控制
- **会话管理**：安全会话处理

## 📈 监控和日志

### 前端监控
- **错误监控**：JavaScript错误捕获
- **性能监控**：页面加载性能
- **用户行为**：操作行为统计
- **接口监控**：API调用监控

### 日志管理
- **操作日志**：用户操作记录
- **错误日志**：错误信息收集
- **性能日志**：性能指标记录

## 🤝 贡献指南

1. **Fork** 仓库
2. **创建**特性分支 (`git checkout -b feature/AmazingFeature`)
3. **提交**更改 (`git commit -m 'Add some AmazingFeature'`)
4. **推送**到分支 (`git push origin feature/AmazingFeature`)
5. **开启** Pull Request

### 开发流程
1. 领取任务并创建分支
2. 本地开发和测试
3. 代码审查和合并
4. 部署测试环境
5. 上线生产环境

## 📞 技术支持

- **技术负责人**：张工程师 (zhang@niumall.com)
- **产品经理**：李经理 (li@niumall.com)
- **技术群组**：微信群-前端技术交流
- **问题反馈**：GitHub Issues

---

**🎯 让管理更智能，让业务更高效！**