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

项目概述

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

前端功能特性

🗺️ 地图展示功能

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

📋 订单管理功能

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

👤 用户系统功能

• 多角色支持: 管理员、货运人员、游客等不同角色
• 微信登录/登出: 支持微信授权登录和登出
• 签到/签退功能: 支持每日签到和签退状态管理
• 用户注册: 游客用户注册为正式用户
• 用户状态管理: 支持signed_in/signed_out/registered/unregistered四种状态
• 权限控制: 不同角色有不同的操作权限

👥 员工管理功能

• 员工列表查看: 管理员可以查看所有员工信息（姓名、手机号、角色、ID）
• 员工搜索过滤: 支持按姓名、手机号、角色搜索员工
• 添加新员工: 管理员可以添加新员工，包含姓名、手机号、角色信息
• 删除员工: 管理员可以删除不需要的员工
• 员工信息验证: 注册时验证员工信息是否存在
• 角色管理: 支持管理员和配送员两种角色分配

位置追踪功能

• 实时位置更新: 通过WebSocket实现货运人员实时位置追踪
• 位置订阅机制: 支持订阅特定货运人员的位置更新
• 在线状态管理: 实时显示货运人员在线/离线状态
• 位置历史记录: 记录货运人员位置历史轨迹
• 位置列表更新机制: 系统通过WebSocket被动接收服务器推送的位置列表更新，不主动请求刷新

🔧 系统管理功能

• API配置管理: 可以配置API服务器地址等参数
• 调试信息显示: 显示系统运行状态和调试信息
• 模块化架构: 基于模块化设计，便于功能扩展和维护

技术架构

模块化架构设计

系统采用现代化的模块化架构设计，专注于生产环境部署和功能扩展：

模块化设计模式

• 主页面模块 (MainPageModule): 协调各个子模块，处理页面生命周期和事件分发
• 登录模块 (LoginModule): 处理用户登录、授权、用户信息管理
• 地图模块 (MapModule): 处理地图显示、定位、标记点管理
• 订单模块 (OrderModule): 处理订单列表、指派、状态跟踪
• 仓库模块 (WarehouseModule): 处理仓库信息展示和管理
• 员工模块 (EmployeeModule): 处理员工管理、位置跟踪、交互
• 位置模块 (LocationModule): 处理位置追踪和实时更新
• 数据模块 (DataModule): 统一管理页面数据状态

真实API模式 (API Mode)

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

注意: 模拟数据模式已移除，系统现在仅支持真实API模式运行。

核心服务组件

• apiService.ts: 封装所有后端API调用和WebSocket连接管理的基础服务
• userService.ts: 用户认证和信息管理服务（包含签到/签退功能）
• mapService.ts: 地图展示、路线规划、地点搜索等地图相关功能
• orderService.ts: 订单管理和指派服务
• deliveryPersonService.ts: 配送人员信息管理服务
• warehouseService.ts: 仓库和库存管理服务
• employeeService.ts: 员工管理服务
• locationTrackingService.ts: 位置追踪管理服务（负责实时位置更新、在线用户状态管理、WebSocket位置订阅）

后端接口需求

基础配置

• API基础地址: http://localhost:8080
• WebSocket地址: ws://localhost:8080/ws/location

用户认证模块

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/signout

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

4. 获取用户状态 - GET /user/status

   • 响应: { status: 'signed_in' | 'signed_out' | 'registered' | 'unregistered'; lastSignInTime?: string; lastSignOutTime?: string }

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

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

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

   • 响应: UserInfo

7. 用户登出 - POST /user/logout

   • 响应: { success: boolean, message?: string }

员工管理模块

1. 获取员工列表 - GET /employees

   • 响应: EmployeeInfo[]

2. 添加员工 - POST /employees

   • 请求: { name: string, phone: string, role: string }
   • 响应: EmployeeInfo

3. 删除员工 - DELETE /employees/{id}

   • 响应: { success: boolean, message?: string }

4. 更新员工信息 - PUT /employees/{id}

   • 请求: { name?: string, phone?: string, role?: string }
   • 响应: EmployeeInfo

仓库管理模块

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. 系统统计 - 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
   }
   

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

WebSocket实时位置消息

1. 在线用户列表消息

   {
     "type": "onlineUserList",     // 消息类型
     "users": [                    // 在线用户列表
       {
         "id": number,             // 用户ID
         "name": "string",        // 用户名（或userName字段）
         "latitude": number,       // 纬度
         "longitude": number,      // 经度
         "timestamp": number       // 时间戳（或lastUpdateTime字段）
       }
     ]
   }
   

2. 用户位置列表消息

   {
     "type": "userLocationList",   // 消息类型
     "users": [                    // 用户位置列表
       {
         "id": number,             // 用户ID
         "name": "string",        // 用户名（或userName字段）
         "latitude": number,       // 纬度
         "longitude": number,      // 经度
         "timestamp": number       // 时间戳（或lastUpdateTime字段）
       }
     ]
   }
   

用户相关消息

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): 包括未登录、已登录、已签到等状态
• 角色权限: 根据用户角色控制功能访问权限

WebSocket实时位置交互机制

WebSocket连接管理

连接建立流程

1. 连接初始化: 通过 apiService.initLocationWebSocket() 建立WebSocket连接
2. 连接地址: 使用配置的API地址，将HTTP协议替换为WebSocket协议（如 ws://localhost:8080/ws/location）
3. 连接状态管理: 自动处理连接建立、消息接收、连接关闭和错误重连

连接生命周期

• 连接建立: 调用 wx.connectSocket() 建立WebSocket连接
• 连接保持: 连接成功后保持活跃状态，接收实时位置更新
• 自动重连: 连接异常断开时，3秒后自动尝试重连（非正常关闭除外）
• 连接关闭: 调用 apiService.closeLocationWebSocket() 主动关闭连接

消息交互协议

客户端发送消息类型

1. 发送位置更新

{
  "type": "updateLocation",
  "userId": 123,
  "latitude": 39.9042,
  "longitude": 116.4074,
  "timestamp": 1640995200000
}

服务端推送消息类型

1. 位置更新消息

{
  "type": "updateLocation",
  "userId": 123,
  "latitude": 39.9042,
  "longitude": 116.4074,
  "timestamp": 1640995200000
}

2. 在线用户列表消息

{
  "type": "onlineUserList",
  "users": [
    {
      "userId": 123,
      "name": "张三",
      "latitude": 39.9042,
      "longitude": 116.4074,
      "lastUpdate": 1640995200000
    }
  ]
}

位置更新处理流程

订阅机制

1. 用户签到: 用户签到成功后，服务器自动处理位置订阅逻辑
2. WebSocket连接: 建立WebSocket连接后，服务器会自动推送位置更新
3. 回调绑定: 通过 apiService.onLocationUpdate(callback) 注册位置更新回调函数

实时位置处理

1. 消息接收: WebSocket接收到位置更新消息后，解析JSON数据
2. 消息分发: 调用所有注册的位置更新回调函数
3. 地图更新: 回调函数中更新对应货运人员的地图标记点位置
4. 数据同步: 同步更新货运人员对象的当前位置信息

回调机制设计

多回调支持

• 回调集合: 使用 Set 数据结构管理多个位置更新回调函数
• 动态注册: 支持多个组件同时订阅位置更新
• 自动清理: 当所有回调都被移除时，自动关闭WebSocket连接

取消订阅机制

• 取消订阅: 调用返回的取消订阅函数移除特定回调
• 连接管理: 当没有活跃回调时，自动关闭WebSocket连接以节省资源

错误处理与重连机制

连接错误处理

• 连接失败: 捕获连接异常并记录错误日志
• 环境检测: 自动检测当前环境是否支持WebSocket
• 优雅降级: 在不支持WebSocket的环境中使用模拟数据

自动重连策略

• 异常检测: 监控WebSocket连接状态
• 智能重连: 仅在非正常关闭时触发重连（排除主动关闭）
• 重连间隔: 3秒重连间隔，避免频繁重连

真实环境部署

生产环境要求

• WebSocket支持: 后端服务必须支持WebSocket协议
• 实时通信: 支持实时位置更新推送
• 连接管理: 支持连接保持和自动重连机制

部署注意事项

• HTTPS要求: 生产环境必须使用HTTPS和WSS协议
• 认证授权: WebSocket连接需要身份验证
• 性能优化: 合理控制位置更新频率

关键服务组件

ApiService (核心WebSocket管理)

• 连接管理: WebSocket连接的建立、维护和关闭
• 消息处理: WebSocket消息的发送、接收和分发
• 错误处理: 连接异常和消息处理错误的统一处理

DeliveryPersonService (货运人员服务)

• 位置订阅: 封装位置订阅和取消订阅接口
• 实时更新: 提供位置更新发送和接收功能
• 服务集成: 与地图服务和用户服务集成

LocationTrackingService (位置追踪服务)

• 状态管理: 管理在线用户状态和位置信息
• 位置分发: 将位置更新分发给所有订阅者
• 超时检测: 检测用户离线状态和位置更新超时

性能优化策略

连接复用

• 单例模式: 整个应用共享同一个WebSocket连接
• 按需连接: 仅在需要时建立连接，无订阅时自动关闭
• 资源节约: 避免多个组件创建重复的WebSocket连接

消息优化

• 消息压缩: 使用简洁的消息格式减少网络传输
• 批量更新: 支持批量位置更新消息处理
• 频率控制: 控制位置更新频率，避免过度频繁的更新

安全考虑

认证授权

• Token验证: WebSocket连接使用Bearer Token进行身份验证
• 权限控制: 仅允许授权用户订阅和发送位置更新
• 数据隔离: 确保用户只能访问自己有权限的位置数据

数据安全

• 数据验证: 对接收的WebSocket消息进行格式验证
• 异常防护: 防止恶意消息导致的系统异常
• 日志记录: 记录关键操作和异常情况

开发与测试

开发环境要求

1. 确保后端API服务已启动并运行在配置的API地址
2. 系统会自动连接后端API进行数据交互
3. 支持WebSocket实时位置更新功能

联调测试

1. 验证所有API接口调用正常
2. 测试WebSocket连接和实时位置更新
3. 检查位置追踪服务的正常运行

快速开始

1. 安装依赖:

   npm install
   

2. 编译TypeScript文件:

   npx tsc -w
   

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

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

4. 配置后端服务:

   • 确保后端API服务运行在 http://localhost:8080
   • 确保WebSocket服务运行在 ws://localhost:8080/ws/location

项目结构

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服务基础封装（包含WebSocket连接管理）
│   ├── deliveryPersonService.ts # 配送人员服务（包含位置订阅功能）
│   ├── locationTrackingService.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. 确保WebSocket服务正常运行
4. 提交审核发布

开发环境配置

1. 本地启动后端开发服务器
2. 配置API地址为开发环境地址
3. 确保WebSocket连接正常

注意事项

1. API一致性: 确保前端API调用与后端接口格式一致
2. 错误处理: 实现完善的网络错误和API错误处理机制
3. 性能优化: 注意网络请求的优化和WebSocket连接管理
4. 安全性: 生产环境务必使用HTTPS和WSS协议，实现合适的认证机制

联系方式

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

---

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