first commit
This commit is contained in:
232
FRONTEND_DEVELOPMENT_GUIDE.md
Normal file
232
FRONTEND_DEVELOPMENT_GUIDE.md
Normal file
@@ -0,0 +1,232 @@
|
||||
# 前端开发指南
|
||||
|
||||
## 架构设计
|
||||
|
||||
本项目采用**桥接模式（Bridge Pattern）** 来实现数据访问层的抽象，支持：
|
||||
|
||||
1. **模拟数据模式** - 使用本地模拟数据进行独立开发和测试
|
||||
2. **真实API模式** - 连接真实后端服务进行联调测试
|
||||
|
||||
## 核心服务
|
||||
|
||||
### 1. BridgeService (桥接服务)
|
||||
位于 `services/bridgeService.ts`，是前端数据访问的统一入口。
|
||||
|
||||
**主要功能**:
|
||||
- 自动路由请求到模拟数据或真实API
|
||||
- 提供模式切换功能
|
||||
- 统一的错误处理
|
||||
- 调试和测试工具
|
||||
|
||||
**使用示例**:
|
||||
```typescript
|
||||
import bridgeService from '../../services/bridgeService';
|
||||
|
||||
// 获取仓库列表
|
||||
const warehouses = await bridgeService.getWarehouses();
|
||||
|
||||
// 切换数据模式
|
||||
bridgeService.setUseMockData(true); // 切换到模拟模式
|
||||
bridgeService.setUseMockData(false); // 切换到API模式
|
||||
```
|
||||
|
||||
### 2. ApiService (API服务)
|
||||
位于 `services/apiService.ts`，封装所有后端API调用。
|
||||
|
||||
### 3. DataService (数据服务)
|
||||
位于 `services/dataService.ts`，提供本地模拟数据。
|
||||
|
||||
### 4. DeliveryService (货运服务)
|
||||
位于 `services/deliveryService.ts`，管理货运业务逻辑。
|
||||
|
||||
## 开发流程
|
||||
|
||||
### 1. 独立开发（模拟模式）
|
||||
```typescript
|
||||
// 默认使用模拟数据，无需后端服务
|
||||
// 所有功能都可以独立测试
|
||||
```
|
||||
|
||||
### 2. 接口联调（API模式）
|
||||
```typescript
|
||||
// 在设置页面切换到API模式
|
||||
// 或者调用：
|
||||
bridgeService.setUseMockData(false);
|
||||
|
||||
// 现在所有请求都会发送到真实后端
|
||||
```
|
||||
|
||||
### 3. 接口测试
|
||||
在设置页面提供了丰富的测试工具：
|
||||
- 测试系统统计接口
|
||||
- 测试健康检查
|
||||
- 测试错误日志上传
|
||||
- 清空缓存
|
||||
|
||||
## 后端接口要求
|
||||
|
||||
后端需要按照 `API_SPECIFICATION.md` 实现以下接口：
|
||||
|
||||
### 认证相关
|
||||
- `POST /user/login` - 用户登录
|
||||
- `POST /user/logout` - 用户登出
|
||||
- `GET /user/info` - 获取用户信息
|
||||
|
||||
### 仓库管理
|
||||
- `GET /warehouses` - 获取仓库列表
|
||||
- `GET /warehouses/{id}` - 获取仓库详情
|
||||
- `GET /warehouses/{id}/orders` - 获取仓库订单
|
||||
|
||||
### 货运人员
|
||||
- `GET /delivery-persons` - 获取货运人员列表
|
||||
- `GET /delivery-persons/{id}` - 获取人员详情
|
||||
- `PUT /delivery-persons/{id}/location` - 更新位置
|
||||
- `POST /delivery-persons/locations/batch` - 批量更新位置
|
||||
- `GET /delivery-persons/{id}/location-history` - 位置历史
|
||||
|
||||
### 订单管理
|
||||
- `GET /orders/pending` - 待指派订单
|
||||
- `POST /orders/{orderId}/assign` - 指派订单
|
||||
- `GET /delivery-persons/{id}/orders` - 人员订单
|
||||
|
||||
### 统计信息
|
||||
- `GET /stats/system` - 系统统计
|
||||
- `GET /stats/orders` - 订单统计
|
||||
|
||||
### 系统管理
|
||||
- `GET /health` - 健康检查
|
||||
- `POST /logs/error` - 错误日志
|
||||
|
||||
## 调试技巧
|
||||
|
||||
### 1. 查看当前模式
|
||||
```typescript
|
||||
const mode = bridgeService.getCurrentMode(); // 'mock' 或 'api'
|
||||
const info = bridgeService.getModeInfo();
|
||||
```
|
||||
|
||||
### 2. 手动切换模式
|
||||
```typescript
|
||||
// 程序切换
|
||||
bridgeService.setUseMockData(true);
|
||||
|
||||
// 或者在设置页面使用开关
|
||||
```
|
||||
|
||||
### 3. 错误处理
|
||||
所有接口调用都应该使用 try-catch：
|
||||
```typescript
|
||||
try {
|
||||
const data = await bridgeService.someMethod();
|
||||
} catch (error) {
|
||||
console.error('API调用失败:', error);
|
||||
// 可以自动上传错误日志
|
||||
await bridgeService.uploadErrorLog(error);
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 性能监控
|
||||
```typescript
|
||||
// 在关键接口添加性能监控
|
||||
const startTime = Date.now();
|
||||
const result = await bridgeService.getWarehouses();
|
||||
const duration = Date.now() - startTime;
|
||||
console.log(`接口耗时: ${duration}ms`);
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 始终使用 BridgeService
|
||||
不要直接调用 ApiService 或 DataService，始终通过 BridgeService 进行数据访问。
|
||||
|
||||
### 2. 处理模式切换
|
||||
组件应该能够处理数据模式的动态切换。
|
||||
|
||||
### 3. 提供降级方案
|
||||
当API不可用时，应该有合理的降级方案。
|
||||
|
||||
### 4. 记录使用情况
|
||||
在关键路径记录模式使用情况，便于分析。
|
||||
|
||||
## 测试策略
|
||||
|
||||
### 单元测试
|
||||
- 测试单个组件的功能
|
||||
- 使用模拟数据确保稳定性
|
||||
|
||||
### 集成测试
|
||||
- 测试组件间的协作
|
||||
- 可以切换模式进行测试
|
||||
|
||||
### 端到端测试
|
||||
- 使用真实API进行完整流程测试
|
||||
- 验证前后端集成
|
||||
|
||||
## 部署建议
|
||||
|
||||
### 开发环境
|
||||
- 默认使用模拟数据模式
|
||||
- 便于快速开发和调试
|
||||
|
||||
### 测试环境
|
||||
- 连接到测试服务器
|
||||
- 使用真实API进行集成测试
|
||||
|
||||
### 生产环境
|
||||
- 始终使用真实API模式
|
||||
- 确保数据一致性
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **API连接失败**
|
||||
- 检查网络连接
|
||||
- 确认后端服务正常运行
|
||||
- 查看API地址配置
|
||||
|
||||
2. **模式切换无效**
|
||||
- 确认调用了 `setUseMockData()`
|
||||
- 检查是否有缓存影响
|
||||
|
||||
3. **数据不一致**
|
||||
- 确认当前数据模式
|
||||
- 检查模拟数据和API响应的格式
|
||||
|
||||
### 调试工具
|
||||
|
||||
1. **设置页面**
|
||||
- 查看当前模式状态
|
||||
- 测试各个接口
|
||||
- 清空缓存
|
||||
|
||||
2. **控制台日志**
|
||||
- 所有数据访问都有详细日志
|
||||
- 包含模式信息和耗时
|
||||
|
||||
3. **错误监控**
|
||||
- 自动上传错误日志
|
||||
- 便于追踪问题
|
||||
|
||||
## 扩展开发
|
||||
|
||||
### 添加新接口
|
||||
1. 在 `ApiService` 中添加API方法
|
||||
2. 在 `BridgeService` 中添加桥接方法
|
||||
3. 提供模拟数据实现
|
||||
4. 更新接口文档
|
||||
|
||||
### 自定义模拟数据
|
||||
可以修改 `DataService` 和 `DeliveryService` 来定制模拟数据。
|
||||
|
||||
### 性能优化
|
||||
对于频繁调用的接口，可以考虑添加缓存机制。
|
||||
|
||||
---
|
||||
|
||||
通过这套架构，前端可以：
|
||||
- ✅ 独立开发，不依赖后端
|
||||
- ✅ 无缝切换到真实API进行联调
|
||||
- ✅ 提供完整的测试工具
|
||||
- ✅ 支持多种环境部署
|
||||
- ✅ 具备良好的扩展性
|
||||
Reference in New Issue
Block a user