WXProgram/FRONTEND_DEVELOPMENT_GUIDE.md

前端开发指南

架构设计

本项目采用桥接模式（Bridge Pattern） 来实现数据访问层的抽象，支持：

1. 模拟数据模式 - 使用本地模拟数据进行独立开发和测试
2. 真实API模式 - 连接真实后端服务进行联调测试

核心服务

1. BridgeService (桥接服务)

位于 services/bridgeService.ts，是前端数据访问的统一入口。

主要功能:

• 自动路由请求到模拟数据或真实API
• 提供模式切换功能
• 统一的错误处理
• 调试和测试工具

使用示例:

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. 独立开发（模拟模式）

// 默认使用模拟数据，无需后端服务
// 所有功能都可以独立测试

2. 接口联调（API模式）

// 在设置页面切换到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. 查看当前模式

const mode = bridgeService.getCurrentMode(); // 'mock' 或 'api'
const info = bridgeService.getModeInfo();

2. 手动切换模式

// 程序切换
bridgeService.setUseMockData(true);

// 或者在设置页面使用开关

3. 错误处理

所有接口调用都应该使用 try-catch：

try {
  const data = await bridgeService.someMethod();
} catch (error) {
  console.error('API调用失败:', error);
  // 可以自动上传错误日志
  await bridgeService.uploadErrorLog(error);
}

4. 性能监控

// 在关键接口添加性能监控
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进行联调
• ✅ 提供完整的测试工具
• ✅ 支持多种环境部署
• ✅ 具备良好的扩展性