niumalll/README.md

# 活牛采购智能数字化系统

## 项目概述

活牛采购智能数字化系统是一个专为活牛采购业务设计的全栈Web应用，提供从供应商管理、订单处理、运输调度到支付结算的完整数字化解决方案。

## 技术栈

### 后端技术
- **运行环境**: Node.js 18+
- **Web框架**: Express.js 4.x
- **数据库**: MySQL 8.0
- **ORM框架**: Sequelize 6.x
- **认证授权**: JWT (jsonwebtoken)
- **API文档**: Swagger/OpenAPI 3.0
- **数据验证**: Joi
- **进程管理**: PM2

### 前端技术
- **框架**: Vue.js 3.x
- **构建工具**: Vite
- **UI组件库**: Element Plus
- **状态管理**: Pinia
- **路由管理**: Vue Router 4.x
- **HTTP客户端**: Axios

## 核心功能

### 🔐 认证授权系统
- JWT Token认证机制
- 基于角色的权限控制(RBAC)
- 多用户类型支持（管理员、采购员、供应商、司机）
- 资源级别的访问控制

### 👥 用户管理
- 用户注册、登录、信息管理
- 用户状态管理（激活、暂停、删除）
- 用户角色和权限分配
- 用户操作日志记录

### 📋 订单管理
- 订单创建、编辑、审核流程
- 订单状态跟踪和管理
- 订单统计和报表分析
- 订单导入导出功能

### 🏢 供应商管理
- 供应商信息录入和维护
- 供应商资质证书管理
- 供应商评价和信用体系
- 供应商合作关系管理

### 🚛 运输管理
- 运输任务创建和分配
- 实时运输状态跟踪
- GPS定位和路线优化
- 运输费用计算和结算

### 👨‍💼 司机管理
- 司机档案和资质管理
- 司机任务分配和调度
- 司机绩效考核系统
- 司机培训记录管理

### 🚗 车辆管理
- 车辆信息和证件管理
- 车辆维护保养计划
- 车辆保险和年检提醒
- 车辆使用统计分析

### 💰 支付管理
- 多种支付方式支持
- 自动账单生成和管理
- 财务对账和结算
- 支付统计和报表

## 项目结构

```
niumall/
├── backend/                 # 后端应用
│   ├── src/
│   │   ├── config/         # 配置文件
│   │   ├── controllers/    # 控制器层
│   │   ├── services/       # 服务层
│   │   ├── models/         # 数据模型
│   │   ├── routes/         # 路由定义
│   │   ├── middleware/     # 中间件
│   │   ├── utils/          # 工具函数
│   │   └── main.js         # 应用入口
│   ├── tests/              # 测试文件
│   └── package.json        # 依赖配置
├── frontend/               # 前端应用
│   ├── src/
│   │   ├── components/     # Vue组件
│   │   ├── views/          # 页面视图
│   │   ├── router/         # 路由配置
│   │   ├── store/          # 状态管理
│   │   ├── utils/          # 工具函数
│   │   └── main.js         # 应用入口
│   └── package.json        # 依赖配置
├── docs/                   # 项目文档
│   ├── API接口文档.md
│   ├── 系统架构文档.md
│   └── 部署运维文档.md
└── README.md               # 项目说明
```

## 快速开始

### 环境要求
- Node.js 18.x 或更高版本
- MySQL 8.0 或更高版本
- npm 8.x 或更高版本

### 安装步骤

1. **克隆项目**
```bash
git clone https://github.com/your-org/niumall.git
cd niumall
```

2. **安装后端依赖**
```bash
cd backend
npm install
```

3. **配置环境变量**
```bash
cp .env.example .env
# 编辑 .env 文件，配置数据库连接等信息
```

4. **初始化数据库**
```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE niumall CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 运行数据库迁移
npm run migrate

# 创建管理员用户
node create_admin.js
```

5. **启动后端服务**
```bash
npm run dev
```

6. **安装前端依赖**
```bash
cd ../frontend
npm install
```

7. **启动前端服务**
```bash
npm run dev
```

8. **访问应用**
- 前端应用: http://localhost:5173
- 后端API: http://localhost:3000
- API文档: http://localhost:3000/api-docs

## 开发指南

### 代码规范
- 使用ESLint进行代码检查
- 使用Prettier进行代码格式化
- 遵循JavaScript Standard Style
- 提交前运行测试和代码检查

### 分支管理
- `main`: 主分支，用于生产环境
- `develop`: 开发分支，用于集成测试
- `feature/*`: 功能分支，用于新功能开发
- `hotfix/*`: 热修复分支，用于紧急修复

### 提交规范
```
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建过程或辅助工具的变动
```

## API文档

系统提供完整的RESTful API接口，支持以下功能模块：

- **认证模块** (`/api/auth`): 用户登录、注册、令牌管理
- **用户管理** (`/api/users`): 用户CRUD操作和权限管理
- **订单管理** (`/api/orders`): 订单全生命周期管理
- **供应商管理** (`/api/suppliers`): 供应商信息和资质管理
- **运输管理** (`/api/transports`): 运输任务和状态管理
- **司机管理** (`/api/drivers`): 司机档案和调度管理
- **车辆管理** (`/api/vehicles`): 车辆信息和维护管理
- **支付管理** (`/api/payments`): 支付记录和财务管理

详细的API接口文档请参考：[API接口文档](./docs/API接口文档.md)

## 系统架构

系统采用前后端分离的架构设计，后端使用分层架构模式：

- **路由层**: 处理HTTP请求和响应
- **控制器层**: 业务逻辑协调和数据验证
- **服务层**: 核心业务逻辑实现
- **数据层**: 数据模型和数据库操作

详细的系统架构说明请参考：[系统架构文档](./docs/系统架构文档.md)

## 部署指南

系统支持多种部署方式：

### 传统部署
- 单机部署：适用于小规模应用
- 集群部署：适用于高并发场景
- 负载均衡：支持多实例负载均衡

### 容器化部署
- Docker部署：快速部署和环境隔离
- Docker Compose：多服务编排
- Kubernetes：云原生部署和管理

### 云平台部署
- 阿里云ECS：弹性计算服务
- 腾讯云CVM：云服务器
- AWS EC2：亚马逊云计算服务

详细的部署和运维指南请参考：[部署运维文档](./docs/部署运维文档.md)

## 测试

### 单元测试
```bash
# 后端单元测试
cd backend
npm test

# 前端单元测试
cd frontend
npm test
```

### 集成测试
```bash
# 运行集成测试
npm run test:integration
```

### API测试
- 使用Postman进行API测试
- 提供完整的Postman Collection
- 支持自动化API测试

## 监控和日志

### 应用监控
- PM2进程监控
- 系统资源监控
- 应用性能监控

### 日志管理
- 结构化日志记录
- 日志轮转和归档
- 错误日志告警

### 健康检查
- 应用健康检查接口
- 数据库连接检查
- 外部服务依赖检查

## 安全特性

### 认证安全
- JWT Token认证
- 密码加密存储
- 会话管理和超时

### 授权安全
- 基于角色的访问控制
- 资源级权限验证
- API接口权限保护

### 数据安全
- 输入数据验证和过滤
- SQL注入防护
- XSS攻击防护

### 传输安全
- HTTPS强制加密
- CORS跨域配置
- 请求频率限制

## 性能优化

### 数据库优化
- 索引优化
- 查询优化
- 连接池管理

### 缓存策略
- Redis缓存
- 查询结果缓存
- 静态资源缓存

### 前端优化
- 代码分割
- 懒加载
- 资源压缩

## 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

1. Fork项目到你的GitHub账户
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

### 贡献类型
- 🐛 Bug修复
- ✨ 新功能开发
- 📚 文档改进
- 🎨 UI/UX优化
- ⚡ 性能优化
- 🔧 配置和工具改进

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 联系我们

- **项目维护者**: NiuMall Team
- **邮箱**: contact@niumall.com
- **官网**: https://www.niumall.com
- **技术支持**: support@niumall.com

## 更新日志

### v1.0.0 (2024-01-01)
- 🎉 初始版本发布
- ✨ 完整的业务功能模块
- 🔐 JWT认证和权限控制
- 📱 响应式前端界面
- 📖 完整的API文档
- 🚀 Docker容器化支持

## 致谢

感谢所有为这个项目做出贡献的开发者和用户！

特别感谢以下开源项目：
- [Express.js](https://expressjs.com/) - Web应用框架
- [Vue.js](https://vuejs.org/) - 前端框架
- [Sequelize](https://sequelize.org/) - ORM框架
- [Element Plus](https://element-plus.org/) - UI组件库
- [MySQL](https://www.mysql.com/) - 数据库系统

---

**活牛采购智能数字化系统** - 让活牛采购更智能、更高效！