瓦尔塔蓄电池配送管理系统

项目概述

这是一个基于微信小程序的蓄电池配送管理系统，为瓦尔塔蓄电池门店提供智能化的配送管理解决方案。系统支持双模式运行，既可以独立使用模拟数据进行功能测试，也可以连接真实后端服务进行联调。

前端功能特性

🗺️ 地图展示功能

• 仓库标记: 在地图上显示所有瓦尔塔蓄电池门店位置
• 货运人员实时位置: 显示配送人员的实时位置和状态
• 订单路线规划: 可视化展示配送路线
• 交互式地图: 支持缩放、拖动、点击查看详情

📋 订单管理功能

• 待指派订单列表: 显示所有等待配送的订单
• 订单详情查看: 点击查看订单详细信息
• 智能指派功能: 将订单指派给合适的货运人员
• 订单状态跟踪: 实时更新订单配送状态

用户系统功能

• 多角色支持: 管理员、货运人员、游客等不同角色
• 用户登录/登出: 支持微信登录
• 签到功能: 支持每日签到记录和状态管理
• 注册功能: 游客用户注册为正式用户
• 个人信息管理: 查看和编辑个人信息
• 权限控制: 不同角色有不同的操作权限

⚙️ 系统设置功能

• 数据模式切换: 支持模拟数据和真实API两种模式
• 配置管理: 可以配置API服务器地址等参数
• 调试信息: 显示系统运行状态和调试信息

技术架构

双服务架构设计

系统采用创新的双服务架构，支持两种运行模式：

1. 模拟数据模式 (Mock Mode)

   • 使用本地模拟数据进行开发和测试
   • 不依赖后端服务，可以独立运行
   • 适合功能开发、单元测试、演示

2. 真实API模式 (API Mode)

   • 连接真实的后端RESTful API服务
   • 支持生产环境部署和联调测试
   • 数据实时更新，支持多用户协作

核心服务组件

• apiService.ts: 封装所有后端API调用的基础服务
• userService.ts: 用户认证和信息管理服务
• mapService.ts: 地图相关功能和服务
• orderService.ts: 订单管理和指派服务
• deliveryPersonService.ts: 配送人员管理和位置更新服务
• warehouseService.ts: 仓库和库存管理服务

后端接口需求

基础配置

• API基础地址: http://localhost:8080
• 模拟模式: 支持模拟数据和真实API两种模式切换

用户认证模块

1. 微信登录 - POST /user/wxlogin

   • 请求: { code: string }
   • 响应: { user: UserInfo, token: string, openid: string, session_key: string }

2. 用户签到 - POST /user/signin

   • 请求: { userId: number }
   • 响应: { success: boolean, userInfo: UserInfo, message?: string }

3. 用户注册 - POST /user/register

   • 请求: { name: string, phone: string }
   • 响应: { success: boolean, employeeInfo: EmployeeInfo, message?: string }

4. 获取用户信息 - GET /user/info

   • 响应: UserInfo

仓库管理模块

1. 获取仓库列表 - GET /warehouses

   • 响应: WarehouseInfo[]

2. 获取仓库详情 - GET /warehouses/{id}

   • 响应: WarehouseInfo

3. 获取仓库订单 - GET /warehouses/{id}/orders

   • 响应: Order[]

货运人员管理模块

1. 获取货运人员列表 - GET /delivery-persons

   • 响应: DeliveryPerson[]

2. 获取货运人员详情 - GET /delivery-persons/{id}

   • 响应: DeliveryPerson

3. 更新位置 - PUT /delivery-persons/{id}/location

   • 请求: { longitude: number, latitude: number }

4. 批量更新位置 - POST /delivery-persons/locations/batch

   • 请求: { locations: Array<{ deliveryPersonId: number, longitude: number, latitude: number, timestamp: number }> }

5. 更新状态 - PUT /delivery-persons/{id}/status

   • 请求: { status: 'idle' | 'busy' | 'offline' }

订单管理模块

1. 获取待指派订单 - GET /orders/pending

   • 响应: Order[]

2. 指派订单 - POST /orders/{id}/assign

   • 请求: { deliveryPersonId: number }
   • 响应: { success: boolean, message?: string }

3. 创建订单 - POST /orders

   • 请求: Omit<Order, 'id' | 'createTime'>
   • 响应: Order

4. 更新订单状态 - PUT /orders/{id}/status

   • 请求: { status: Order['status'] }
   • 响应: { success: boolean, message?: string }

实时位置服务

1. 订阅位置更新 - POST /locations/subscribe

   • 请求: { deliveryPersonIds: number[] }
   • 响应: { subscriptionId: string, expiresAt: number }

2. 取消订阅 - POST /locations/unsubscribe

   • 请求: { subscriptionId: string }

统计和日志模块

1. 系统统计 - GET /stats/system

   • 响应: { totalWarehouses: number, totalDeliveryPersons: number, pendingOrders: number, activeOrders: number }

2. 订单统计 - GET /stats/orders

   • 响应: { totalOrders: number, completedOrders: number, inProgressOrders: number, averageDeliveryTime: number }

3. 用户统计 - GET /user/stats

   • 响应: { totalUsers: number, activeUsers: number, onlineUsers: number, newUsersToday: number }

详细接口文档请参考 backend-api.md 文件。

消息数据格式

系统发送给服务器的消息数据

用户相关消息

1. 微信登录请求

   {
     "code": "string" // 微信登录临时code
   }
   

2. 用户签到请求

   {
     "userId": number,    // 用户ID
     "timestamp": number  // 签到时间戳
   }
   

3. 用户注册请求

   {
     "name": "string",      // 真实姓名
     "phone": "string"      // 手机号
   }
   

4. 更新货运人员位置请求

   {
     "longitude": number, // 经度
     "latitude": number   // 纬度
   }
   

5. 指派订单请求

   {
     "deliveryPersonId": number // 货运人员ID
   }
   

系统从服务器接收的消息数据

用户相关消息

1. 微信登录响应

   {
     "user": {
       "id": number,          // 用户ID
       "name": "string",     // 用户名
       "nickName": "string", // 用户昵称
       "role": "string",     // 角色（admin/delivery_person）
       "avatarUrl": "string",// 头像URL
       "phone": "string"     // 手机号
     },
     "token": "string",      // 认证token
     "openid": "string",     // 微信openid
     "session_key": "string" // 微信会话密钥
   }
   

2. 用户信息响应

   {
     "id": number,          // 用户ID
     "name": "string",     // 用户名
     "avatarUrl": "string",// 头像URL
     "nickName": "string", // 用户昵称
     "phone": "string",    // 手机号
     "gender": number,      // 性别（可选）
     "city": "string",     // 城市（可选）
     "province": "string", // 省份（可选）
     "country": "string",  // 国家（可选）
     "language": "string", // 语言（可选）
     "role": "string",     // 角色（可选）
     "lastSignInTime": number // 最后签到时间戳（可选）
   }
   

3. 签到响应

   {
     "success": boolean,    // 签到是否成功
     "message": "string",  // 签到结果消息
     "userInfo": {         // 更新后的用户信息
       "id": number,
       "name": "string",
       "avatarUrl": "string",
       "nickName": "string",
       "phone": "string",
       "role": "string",
       "lastSignInTime": number
     }
   }
   

4. 注册响应

   {
     "success": boolean,    // 注册是否成功
     "message": "string",  // 注册结果消息
     "userInfo": {         // 注册后的用户信息
       "id": number,
       "name": "string",
       "avatarUrl": "string",
       "nickName": "string",
       "phone": "string",
       "role": "string"
     }
   }
   

仓库相关消息

1. 仓库列表响应

   [
     {
       "id": number,           // 仓库ID
       "name": "string",      // 仓库名称
       "address": "string",   // 仓库地址
       "contact": "string",   // 联系人（可选）
       "phone": "string",     // 联系电话（可选）
       "description": "string", // 描述（可选）
       "status": "string",    // 状态（open/closed/maintenance）
       "capacity": number      // 仓库容量（吨）
     }
     // 更多仓库...
   ]
   

2. 单个仓库详情响应

   {
     "id": number,           // 仓库ID
     "name": "string",      // 仓库名称
     "address": "string",   // 仓库地址
     "contact": "string",   // 联系人（可选）
     "phone": "string",     // 联系电话（可选）
     "description": "string", // 描述（可选）
     "status": "string",    // 状态（open/closed/maintenance）
     "capacity": number      // 仓库容量（吨）
   }
   

货运人员相关消息

1. 货运人员列表响应

   [
     {
       "id": number,             // 货运人员ID
       "name": "string",        // 姓名
       "phone": "string",       // 电话号码
       "avatarUrl": "string",   // 头像URL
       "status": "string",      // 状态（idle/busy）
       "currentLocation": {
         "longitude": number,    // 经度
         "latitude": number      // 纬度
       },
       "currentOrders": [        // 当前订单列表
         // 订单对象...
       ]
     }
     // 更多货运人员...
   ]
   

订单相关消息

1. 订单列表响应

   [
     {
       "id": number,          // 订单ID
       "startPoint": {
         "id": number,        // 起点（仓库）ID
         "name": "string",   // 起点名称
         "longitude": number, // 起点经度
         "latitude": number   // 起点纬度
       },
       "endPoint": {
         "name": "string",   // 终点名称
         "longitude": number, // 终点经度
         "latitude": number   // 终点纬度
       },
       "status": "string",   // 状态（pending/assigned/in_transit/delivered）
       "goodsType": "string",// 货物类型
       "goodsWeight": number, // 货物重量（公斤）
       "createTime": number,  // 创建时间戳
       "assignTime": number,  // 指派时间戳（可选）
       "deliveryTime": number // 配送完成时间戳（可选）
     }
     // 更多订单...
   ]
   

核心数据类型定义

系统使用以下核心数据类型进行数据交换和处理：

1. UserInfo - 用户信息接口
2. WarehouseInfo - 仓库信息接口
3. Order - 订单接口
4. DeliveryPerson - 货运人员接口
5. Marker - 地图标记点接口
6. RoutePlanResult - 路径规划结果接口

详细的数据类型定义可参考 miniprogram/types/index.ts 文件。

签到与注册交互流程

用户角色定义

• 游客 (guest): 未注册用户，只能查看基本信息，需要注册后才能使用完整功能
• 货运人员 (delivery_person): 已注册的配送人员，可以进行签到和接单
• 管理员 (admin): 系统管理员，拥有最高权限

签到流程

1. 已注册用户签到: 用户点击签到按钮 → 调用签到接口 → 更新签到状态 → 刷新用户信息
2. 签到状态管理: 记录最后签到时间，防止重复签到
3. 签到结果反馈: 显示签到成功/失败消息，更新界面状态

注册流程

1. 游客状态检测: 系统检测到用户角色为游客时显示注册入口
2. 注册表单提交: 用户填写真实姓名、手机号等必要信息
3. 注册接口调用: 提交注册信息到后端服务
4. 自动签到: 注册成功后自动执行签到操作
5. 状态更新: 更新用户角色和权限，刷新界面显示

交互状态管理

• 授权状态 (hasWxCode): 是否已获取微信授权
• 用户状态 (userStatus): 包括未登录、已登录、已签到等状态
• 角色权限: 根据用户角色控制功能访问权限

运货师傅上线与位置更新机制

师傅上线流程

1. 数据获取: 通过 deliveryPersonService.getDeliveryPersons() 获取所有货运人员数据
2. 列表更新: 在 deliveryPersonModule.loadDeliveryPersons() 中调用服务获取数据
3. 标记点生成: 通过 updateDeliveryPersonMarkers() 方法将货运人员转换为地图标记点
4. 地图更新: 调用 dataModule.updateMarkers() 更新地图显示

实时位置更新机制

1. 订阅机制: 通过 deliveryPersonService.subscribeToRealTimeLocations() 订阅实时位置更新
2. WebSocket连接: 在真实环境中使用WebSocket接收实时位置数据
3. 回调处理: 位置更新通过 handleRealTimeLocationUpdate() 回调函数处理
4. 单个标记更新: 通过 updateSingleDeliveryPersonMarker() 方法更新特定货运人员的图形位置

数据刷新机制

• 实时更新: 当收到位置消息时，直接更新对应货运人员的标记点位置（经度、纬度）
• 数据同步: 位置更新会同步修改货运人员对象的 currentLocation 属性
• 状态保持: 货运人员的其他信息（姓名、状态、订单等）保持不变，只有位置信息更新

关键代码位置

• deliveryPersonModule.ts - 处理货运人员显示和位置更新
• deliveryPersonService.ts - 提供货运人员数据服务
• dataModule.ts - 管理地图数据和标记点

开发与测试

开发模式（模拟数据）

1. 在设置页面切换到"模拟数据"模式
2. 系统使用本地模拟数据进行开发测试
3. 所有功能都可以独立运行，不依赖后端

联调模式（真实API）

1. 在设置页面切换到"真实API"模式
2. 确保后端服务运行在配置的API地址
3. 系统会自动连接后端API进行数据交互

快速开始

1. 安装依赖:

   npm install
   

2. 编译TypeScript文件:

   npx tsc -w
   

3. 启动微信开发者工具:

   • 导入项目目录
   • 点击编译运行

4. 切换数据模式:

   • 进入"设置"页面
   • 切换数据模式进行测试

项目结构

miniprogram/
├── app.json              # 小程序全局配置
├── app.less              # 全局样式
├── app.ts                # 小程序全局入口
├── components/           # 公共组件
│   ├── bottom-modal/     # 底部弹窗组件
│   └── navigation-bar/   # 导航栏组件
├── images/               # 图片资源
│   ├── trucks.png        # 货运车辆图标
│   └── warehouse.png     # 仓库图标
├── libs/                 # 第三方库
│   └── amap-wx.js        # 高德地图小程序SDK
├── pages/                # 页面组件
│   ├── admin/            # 管理员页面
│   └── index/            # 首页（地图+订单）
├── services/             # 服务层
│   ├── apiService.ts     # API服务基础封装
│   ├── deliveryPersonService.ts # 配送人员服务
│   ├── mapService.ts     # 地图服务
│   ├── orderService.ts   # 订单服务
│   ├── userService.ts    # 用户服务
│   └── warehouseService.ts # 仓库服务
├── sitemap.json          # 小程序站点地图
├── types/                # TypeScript类型定义
│   └── index.ts          # 核心类型定义
└── utils/                # 工具函数
    ├── helpers.ts        # 辅助函数
    └── util.ts           # 通用工具函数

部署说明

生产环境部署

1. 确保后端API服务已部署并正常运行
2. 修改API服务地址配置
3. 切换到"真实API"模式
4. 提交审核发布

开发环境配置

1. 本地启动后端开发服务器
2. 配置API地址
3. 使用"真实API"模式进行联调测试

注意事项

1. 数据一致性: 确保模拟数据格式与后端API返回格式一致
2. 错误处理: 两种模式下的错误处理机制需要保持一致
3. 性能优化: 真实API模式下注意网络请求的优化
4. 安全性: 生产环境务必使用HTTPS和合适的认证机制

联系方式

如有任何问题或建议，请联系开发团队。

---

版本: 1.0.0
最后更新: 2025年
技术支持: 开发团队