niumalll/docs/开发指南.md

# 开发指南

## 版本历史

| 版本 | 日期 | 修改人 | 修改内容 |
|------|------|--------|----------|
| 1.0.0 | 2024-01-20 | 开发团队 | 初始版本 |

## 1. 开发环境搭建

### 1.1 系统要求

- **操作系统**: macOS 10.15+, Ubuntu 18.04+, Windows 10+
- **Node.js**: 16.x 或更高版本
- **MySQL**: 8.0 或更高版本
- **Redis**: 6.0 或更高版本
- **Git**: 2.20 或更高版本

### 1.2 开发工具推荐

- **IDE**: VS Code, WebStorm
- **数据库管理**: Navicat, DBeaver
- **API测试**: Postman, Insomnia
- **版本控制**: Git, SourceTree

### 1.3 环境安装

#### 1.3.1 Node.js 环境

```bash
# 使用 nvm 管理 Node.js 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
```

#### 1.3.2 数据库安装

```bash
# MySQL 安装 (macOS)
brew install mysql
brew services start mysql

# Redis 安装 (macOS)
brew install redis
brew services start redis
```

#### 1.3.3 项目克隆与依赖安装

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

# 安装后端依赖
cd backend
npm install

# 安装前端管理系统依赖
cd ../admin-system
npm install

# 安装小程序依赖
cd ../mini_program/staff-mp
npm install
```

## 2. 项目结构

```
niumall/
├── backend/                 # 后端服务 (Node.js)
│   ├── src/
│   │   ├── controllers/     # 控制器
│   │   ├── models/         # 数据模型
│   │   ├── services/       # 业务逻辑
│   │   ├── middleware/     # 中间件
│   │   ├── routes/         # 路由配置
│   │   └── utils/          # 工具函数
│   └── package.json
├── admin-system/           # 前端管理系统 (Vue3 + TypeScript)
│   ├── src/
│   │   ├── views/          # 页面组件
│   │   ├── api/            # API服务
│   │   ├── utils/          # 工具函数
│   │   └── stores/         # 状态管理
│   └── package.json
├── mini_program/           # 小程序矩阵
│   ├── staff-mp/           # 员工小程序
│   ├── driver-mp/          # 司机小程序
│   ├── supplier-mp/        # 供应商小程序
│   └── client-mp/          # 客户小程序
├── go-backend/             # Go后端服务 (备选)
├── fastapi-backend/        # FastAPI后端服务 (备选)
├── website/                # 官方网站
└── docs/                   # 项目文档
```

## 3. 开发流程

### 3.1 分支管理

采用 Git Flow 工作流：

- **main**: 生产环境分支
- **develop**: 开发环境分支
- **feature/***: 功能开发分支
- **hotfix/***: 紧急修复分支
- **release/***: 发布准备分支

### 3.2 开发步骤

1. **创建功能分支**
```bash
git checkout develop
git pull origin develop
git checkout -b feature/订单管理优化
```

2. **开发与提交**
```bash
# 开发完成后提交
git add .
git commit -m "feat: 添加订单状态自动更新功能"
```

3. **代码审查**
```bash
# 推送到远程分支
git push origin feature/订单管理优化
# 在 GitHub/GitLab 创建 Pull Request
```

### 3.3 提交规范

使用 Conventional Commits 规范：

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

## 4. 本地开发

### 4.1 环境配置

#### 4.1.1 后端配置

创建 `backend/.env` 文件：

```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=niumall
DB_USER=root
DB_PASSWORD=your_password

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT配置
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=7d

# 微信小程序配置
WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret
```

#### 4.1.2 前端配置

创建 `admin-system/.env.development` 文件：

```env
# API基础URL
VITE_API_BASE_URL=http://localhost:3000/api
VITE_UPLOAD_URL=http://localhost:3000/uploads
```

### 4.2 启动服务

#### 4.2.1 启动后端服务

```bash
cd backend
npm run dev
# 服务启动在 http://localhost:3000
```

#### 4.2.2 启动前端管理系统

```bash
cd admin-system
npm run dev
# 服务启动在 http://localhost:5173
```

#### 4.2.3 启动小程序开发

```bash
cd mini_program/staff-mp
# 使用微信开发者工具打开项目目录
```

### 4.3 数据库初始化

```bash
# 创建数据库
mysql -u root -p
CREATE DATABASE niumall CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 运行初始化脚本
cd backend
node init_database.js
```

## 5. 代码规范

### 5.1 JavaScript/TypeScript 规范

- 使用 ESLint + Prettier 进行代码格式化
- 遵循 Airbnb JavaScript 风格指南
- 使用 TypeScript 进行类型检查

### 5.2 Vue 组件规范

- 使用 Composition API
- 组件命名采用 PascalCase
- Props 定义使用 TypeScript 接口

### 5.3 API 接口规范

- 遵循 RESTful 设计原则
- 统一的响应格式
- 完善的错误处理

## 6. 测试指南

### 6.1 单元测试

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

# 运行前端单元测试
cd admin-system
npm run test:unit
```

### 6.2 API测试

使用 Postman 或 Insomnia 进行 API 测试，测试文件位于 `docs/api/` 目录。

## 7. 调试技巧

### 7.1 后端调试

- 使用 VS Code 调试配置
- 查看日志文件
- 使用 Postman 测试 API

### 7.2 前端调试

- 使用浏览器开发者工具
- Vue DevTools 扩展
- 网络请求监控

### 7.3 小程序调试

- 微信开发者工具调试器
- 真机调试
- 性能监控

## 8. 常见问题

### 8.1 环境问题

**Q: 数据库连接失败**
```bash
# 检查数据库服务状态
brew services list | grep mysql
# 重启数据库服务
brew services restart mysql
```

**Q: 端口被占用**
```bash
# 查看端口占用
lsof -i :3000
# 杀死进程
kill -9 <PID>
```

### 8.2 开发问题

**Q: 热重载不生效**
```bash
# 清除缓存重启
rm -rf node_modules/.cache
npm run dev
```

**Q: 小程序真机预览失败**
- 检查网络连接
- 确认域名配置
- 查看控制台错误信息

## 9. 性能优化

### 9.1 后端优化

- 数据库查询优化
- Redis 缓存策略
- 异步处理优化

### 9.2 前端优化

- 代码分割
- 懒加载
- 图片优化

### 9.3 小程序优化

- 分包加载
- 图片压缩
- 请求合并

## 10. 联系信息

- **技术支持**: tech-support@company.com
- **开发团队**: dev-team@company.com
- **文档维护**: docs@company.com

## 相关文档

- [项目总览](./项目总览.md)
- [产品需求文档](./产品需求文档.md)
- [系统架构设计](./系统架构设计.md)
- [API接口文档](./API接口文档.md)
- [数据库设计](./数据库设计.md)
- [部署运维指南](./部署运维指南.md)
- [测试指南](./测试指南.md)