# 前端开发指南

## 架构设计

本项目采用**桥接模式（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进行联调
- ✅ 提供完整的测试工具
- ✅ 支持多种环境部署
- ✅ 具备良好的扩展性