861 lines
29 KiB
Markdown
861 lines
29 KiB
Markdown
# 瓦尔塔蓄电池配送管理系统
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于微信小程序的蓄电池配送管理系统，为瓦尔塔蓄电池门店提供智能化的配送管理解决方案。系统支持双模式运行，既可以独立使用模拟数据进行功能测试，也可以连接真实后端服务进行联调。
|
||
|
||
## 前端功能特性
|
||
|
||
### 🗺️ 地图展示功能
|
||
- **仓库标记**: 在地图上显示所有瓦尔塔蓄电池门店位置
|
||
- **货运人员实时位置**: 显示配送人员的实时位置和状态
|
||
- **订单路线规划**: 可视化展示配送路线
|
||
- **交互式地图**: 支持缩放、拖动、点击查看详情
|
||
|
||
### 📋 订单管理功能
|
||
- **待指派订单列表**: 显示所有等待配送的订单
|
||
- **订单详情查看**: 点击查看订单详细信息
|
||
- **智能指派功能**: 将订单指派给合适的货运人员
|
||
- **订单状态跟踪**: 实时更新订单配送状态
|
||
|
||
### 👤 用户系统功能
|
||
- **多角色支持**: 管理员、货运人员、游客等不同角色
|
||
- **微信登录/登出**: 支持微信授权登录和登出
|
||
- **签到/签退功能**: 支持每日签到和签退状态管理
|
||
- **用户注册**: 游客用户注册为正式用户
|
||
- **用户状态管理**: 支持signed_in/signed_out/registered/unregistered四种状态
|
||
- **权限控制**: 不同角色有不同的操作权限
|
||
|
||
### 👥 员工管理功能
|
||
- **员工列表查看**: 管理员可以查看所有员工信息（姓名、手机号、角色、ID）
|
||
- **员工搜索过滤**: 支持按姓名、手机号、角色搜索员工
|
||
- **添加新员工**: 管理员可以添加新员工，包含姓名、手机号、角色信息
|
||
- **删除员工**: 管理员可以删除不需要的员工
|
||
- **员工信息验证**: 注册时验证员工信息是否存在
|
||
- **角色管理**: 支持管理员和配送员两种角色分配
|
||
|
||
### 位置追踪功能
|
||
- **实时位置更新**: 通过WebSocket实现货运人员实时位置追踪
|
||
- **位置订阅机制**: 支持订阅特定货运人员的位置更新
|
||
- **在线状态管理**: 实时显示货运人员在线/离线状态
|
||
- **位置历史记录**: 记录货运人员位置历史轨迹
|
||
- **位置列表更新机制**: 系统通过WebSocket被动接收服务器推送的位置列表更新，不主动请求刷新
|
||
|
||
### 🐛 问题修复记录
|
||
|
||
#### 2024年12月19日修复
|
||
|
||
**1. TypeError错误修复**
|
||
- **问题**: `mainPageModule.ts`中`MainPageModule`接口声明了`cleanup()`方法但类实现中缺失该方法
|
||
- **错误表现**: 页面销毁时调用`detached`生命周期方法触发TypeError
|
||
- **修复方案**: 在`MainPageModule`类中添加`cleanup()`方法实现，包含资源清理日志和调用`locationModule.cleanup()`
|
||
|
||
**2. 签退后签到按钮不显示问题**
|
||
- **问题**: 用户签退后签到按钮不再显示
|
||
- **根本原因**: 签退后调用`refreshAllData()`方法触发登录状态检查，导致`authStatus.hasWxCode`被重置为`false`
|
||
- **修复方案**: 移除签退后调用`refreshAllData()`的逻辑，确保签退后用户状态更新为`signed_out`且`authStatus.hasWxCode`保持`true`
|
||
- **显示条件**: 签到按钮显示需要满足：已获取微信code、用户状态为registered/signed_out且非游客角色
|
||
|
||
**3. 管理界面跳转导致页面销毁问题**
|
||
- **问题**: 点击管理按钮跳转后，返回时页面状态丢失
|
||
- **根本原因**: `goToManagementPage()`方法使用`wx.redirectTo()`跳转，导致当前页面被销毁触发`detached`生命周期清理资源
|
||
- **修复方案**: 将跳转方式改为`wx.navigateTo()`，保持页面栈状态
|
||
- **效果**: 用户返回时页面状态和登录数据得以保留，签到按钮正常显示
|
||
|
||
### 🔧 系统管理功能
|
||
- **API配置管理**: 可以配置API服务器地址等参数
|
||
- **调试信息显示**: 显示系统运行状态和调试信息
|
||
- **模块化架构**: 基于模块化设计，便于功能扩展和维护
|
||
|
||
### 👑 管理员管理逻辑
|
||
|
||
#### 管理员界面 (admin-dashboard)
|
||
- **功能菜单**: 提供6个核心管理功能入口
|
||
- 员工管理 (👥): 管理员工信息
|
||
- 订单管理 (📦): 处理订单分配
|
||
- 仓库管理 (🏭): 管理库存信息
|
||
- 数据统计 (📊): 查看业务数据
|
||
- 系统设置 (⚙️): 系统配置管理
|
||
- 地图监控 (🗺️): 实时位置监控
|
||
- **系统概览**: 显示员工总数、订单总数、仓库数量等关键指标
|
||
- **权限验证**: 自动验证用户是否为管理员角色
|
||
|
||
#### 员工管理 (employee-management)
|
||
**核心方法**:
|
||
- `loadEmployees()`: 加载员工列表，支持搜索过滤
|
||
- `submitAddForm()`: 提交添加员工表单，包含表单验证
|
||
- `deleteEmployee()`: 删除员工，包含确认对话框
|
||
- `validateForm()`: 验证员工信息（姓名、手机号、角色）
|
||
- `getFilteredEmployees()`: 根据关键词过滤员工列表
|
||
|
||
**功能特性**:
|
||
- **双标签页设计**: 员工列表页和添加员工页
|
||
- **实时搜索**: 支持按姓名、手机号、角色搜索
|
||
- **表单验证**: 手机号格式验证、必填项检查
|
||
- **权限控制**: 过滤当前登录用户，防止误删
|
||
- **角色管理**: 支持管理员和配送员角色分配
|
||
|
||
#### 订单管理 (order-management)
|
||
**核心方法**:
|
||
- `refreshData()`: 刷新订单和员工数据
|
||
- `createOrder()`: 创建新订单，包含完整表单验证
|
||
- `assignOrder()`: 指派订单给合适的货运人员
|
||
- `updateOrderStatus()`: 更新订单状态
|
||
- `filterOrders()`: 按状态过滤订单列表
|
||
|
||
**功能特性**:
|
||
- **多状态管理**: 支持pending/assigned/in_transit/delivered/cancelled状态
|
||
- **智能指派**: 自动筛选空闲状态的货运人员
|
||
- **订单详情**: 显示订单起点、终点、货物信息
|
||
- **实时更新**: 下拉刷新获取最新数据
|
||
- **批量操作**: 支持批量指派和状态更新
|
||
|
||
#### 仓库管理 (warehouse-management)
|
||
**核心方法**:
|
||
- `loadWarehouses()`: 加载仓库列表
|
||
- `submitAddForm()`: 提交添加仓库表单
|
||
- `deleteWarehouse()`: 删除仓库，包含确认对话框
|
||
- `filterWarehouses()`: 按名称、地址、联系人搜索仓库
|
||
- `getWarehouseInventoryStatus()`: 获取库存状态评估
|
||
|
||
**功能特性**:
|
||
- **库存监控**: 实时显示库存状态（充足/正常/偏低/不足）
|
||
- **位置管理**: 支持仓库经纬度坐标管理
|
||
- **容量管理**: 设置仓库最大容量限制
|
||
- **状态管理**: 支持营业中/已关闭/维护中状态
|
||
- **联系人管理**: 仓库联系人和电话信息
|
||
|
||
#### 员工界面 (employee-dashboard)
|
||
**功能菜单**:
|
||
- 我的订单 (📦): 查看分配订单
|
||
- 位置上报 (📍): 上报当前位置
|
||
- 工作安排 (📅): 查看工作计划
|
||
- 个人信息 (👤): 个人资料管理
|
||
- 消息通知 (📨): 查看系统消息
|
||
- 帮助中心 (❓): 使用帮助文档
|
||
|
||
**工作统计**:
|
||
- 今日订单数量
|
||
- 已完成订单数量
|
||
- 待处理订单数量
|
||
|
||
#### 权限控制机制
|
||
- **角色验证**: 管理员界面自动验证用户角色
|
||
- **访问限制**: 非管理员用户自动跳转回首页
|
||
- **数据隔离**: 员工列表过滤当前登录用户
|
||
- **功能权限**: 不同角色显示不同的功能菜单
|
||
|
||
## 技术架构
|
||
|
||
### 模块化架构设计
|
||
系统采用现代化的模块化架构设计，专注于生产环境部署和功能扩展：
|
||
|
||
**模块化设计模式**
|
||
- **主页面模块 (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`
|
||
- **请求参数**: `{ latitude: number, longitude: number, timestamp: number }`
|
||
- **成功响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"userInfo": {
|
||
"id": 123,
|
||
"name": "张三",
|
||
"phone": "13800138000",
|
||
"role": "DELIVERY_PERSON",
|
||
"openid": "oK4fS5ABCDEF123456"
|
||
}
|
||
}
|
||
```
|
||
- **失败响应**:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误信息"
|
||
}
|
||
```
|
||
|
||
3. **用户签退** - `POST /user/signout`
|
||
- **请求参数**: `{ userId: number }`
|
||
- **成功响应**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "签退成功"
|
||
}
|
||
```
|
||
- **失败响应**:
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误信息"
|
||
}
|
||
```
|
||
|
||
4. **获取用户状态** - `GET /user/status`
|
||
- 响应: `{ status: 'signed_in' | 'signed_out' | 'registered' | 'unregistered'; lastSignInTime?: string; lastSignOutTime?: string }`
|
||
|
||
5.2. **用户注册** - `POST /user/register`
|
||
- **请求参数**: `{ name: string, phone: string }`
|
||
- **服务器响应**: `{ success: boolean, userInfo: UserInfoResponse, message?: string }`
|
||
- **说明**: 服务器采用统一的DTO响应格式，包含success字段和userInfo对象
|
||
|
||
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. **微信登录请求**
|
||
```json
|
||
{
|
||
"code": "string" // 微信登录临时code
|
||
}
|
||
```
|
||
|
||
2. **用户签到请求**
|
||
```json
|
||
{
|
||
"userId": number, // 用户ID
|
||
"timestamp": number // 签到时间戳
|
||
}
|
||
```
|
||
|
||
3. **用户注册请求**
|
||
```json
|
||
{
|
||
"name": "string", // 真实姓名
|
||
"phone": "string" // 手机号
|
||
}
|
||
```
|
||
|
||
3. **更新货运人员位置请求**
|
||
```json
|
||
{
|
||
"longitude": number, // 经度
|
||
"latitude": number // 纬度
|
||
}
|
||
```
|
||
|
||
4. **指派订单请求**
|
||
```json
|
||
{
|
||
"deliveryPersonId": number // 货运人员ID
|
||
}
|
||
```
|
||
|
||
### 系统从服务器接收的消息数据
|
||
|
||
#### WebSocket实时位置消息
|
||
|
||
1. **在线用户列表消息**
|
||
```json
|
||
{
|
||
"type": "onlineUserList", // 消息类型
|
||
"users": [ // 在线用户列表
|
||
{
|
||
"id": number, // 用户ID
|
||
"name": "string", // 用户名（或userName字段）
|
||
"latitude": number, // 纬度
|
||
"longitude": number, // 经度
|
||
"timestamp": number // 时间戳（或lastUpdateTime字段）
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
2. **用户位置列表消息**
|
||
```json
|
||
{
|
||
"type": "userLocationList", // 消息类型
|
||
"users": [ // 用户位置列表
|
||
{
|
||
"id": number, // 用户ID
|
||
"name": "string", // 用户名（或userName字段）
|
||
"latitude": number, // 纬度
|
||
"longitude": number, // 经度
|
||
"timestamp": number // 时间戳（或lastUpdateTime字段）
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 用户相关消息
|
||
|
||
1. **微信登录响应**
|
||
```json
|
||
{
|
||
"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. **用户信息响应**
|
||
```json
|
||
{
|
||
"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. **签到响应（服务器DTO格式）**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"userInfo": {
|
||
"id": 123,
|
||
"name": "张三",
|
||
"phone": "13800138000",
|
||
"role": "DELIVERY_PERSON"
|
||
},
|
||
"message": "签到成功"
|
||
}
|
||
```
|
||
|
||
4. **前端转换后的签到响应格式**
|
||
```json
|
||
{
|
||
"success": true, // 签到是否成功
|
||
"employeeInfo": { // 员工信息
|
||
"id": number,
|
||
"name": "string",
|
||
"phone": "string",
|
||
"role": "string"
|
||
},
|
||
"message": "签到成功" // 签到结果消息
|
||
}
|
||
```
|
||
|
||
5. **签退响应（服务器DTO格式）**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "签退成功"
|
||
}
|
||
```
|
||
|
||
6. **前端转换后的签退响应格式**
|
||
```json
|
||
{
|
||
"success": true, // 签退是否成功
|
||
"message": "签退成功" // 签退结果消息
|
||
}
|
||
```
|
||
|
||
**重要说明**: 服务器现在采用统一的DTO响应格式，包含success字段和message字段。前端代码已适配新的DTO格式，直接使用服务器返回的success和message字段。签到和注册接口返回userInfo对象，前端转换为employeeInfo格式以保持兼容性。
|
||
|
||
4. **注册响应**
|
||
```json
|
||
{
|
||
"success": boolean, // 注册是否成功
|
||
"userInfo": { // 注册后的用户信息
|
||
"id": number,
|
||
"name": "string",
|
||
"phone": "string",
|
||
"role": "string"
|
||
},
|
||
"message": "string" // 注册结果消息
|
||
}
|
||
```
|
||
|
||
#### 仓库相关消息
|
||
|
||
1. **仓库列表响应**
|
||
```json
|
||
[
|
||
{
|
||
"id": number, // 仓库ID
|
||
"name": "string", // 仓库名称
|
||
"address": "string", // 仓库地址
|
||
"contact": "string", // 联系人（可选）
|
||
"phone": "string", // 联系电话（可选）
|
||
"description": "string", // 描述（可选）
|
||
"status": "string", // 状态（open/closed/maintenance）
|
||
"capacity": number // 仓库容量（吨）
|
||
}
|
||
// 更多仓库...
|
||
]
|
||
```
|
||
|
||
2. **单个仓库详情响应**
|
||
```json
|
||
{
|
||
"id": number, // 仓库ID
|
||
"name": "string", // 仓库名称
|
||
"address": "string", // 仓库地址
|
||
"contact": "string", // 联系人（可选）
|
||
"phone": "string", // 联系电话（可选）
|
||
"description": "string", // 描述（可选）
|
||
"status": "string", // 状态（open/closed/maintenance）
|
||
"capacity": number // 仓库容量（吨）
|
||
}
|
||
```
|
||
|
||
#### 货运人员相关消息
|
||
|
||
1. **货运人员列表响应**
|
||
```json
|
||
[
|
||
{
|
||
"id": number, // 货运人员ID
|
||
"name": "string", // 姓名
|
||
"phone": "string", // 电话号码
|
||
"avatarUrl": "string", // 头像URL
|
||
"status": "string", // 状态（idle/busy）
|
||
"currentLocation": {
|
||
"longitude": number, // 经度
|
||
"latitude": number // 纬度
|
||
},
|
||
"currentOrders": [ // 当前订单列表
|
||
// 订单对象...
|
||
]
|
||
}
|
||
// 更多货运人员...
|
||
]
|
||
```
|
||
|
||
#### 订单相关消息
|
||
|
||
1. **订单列表响应**
|
||
```json
|
||
[
|
||
{
|
||
"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. **发送位置更新**
|
||
```json
|
||
{
|
||
"type": "updateLocation",
|
||
"userId": 123,
|
||
"latitude": 39.9042,
|
||
"longitude": 116.4074,
|
||
"timestamp": 1640995200000
|
||
}
|
||
```
|
||
|
||
#### 服务端推送消息类型
|
||
|
||
1. **位置更新消息**
|
||
```json
|
||
{
|
||
"type": "updateLocation",
|
||
"userId": 123,
|
||
"latitude": 39.9042,
|
||
"longitude": 116.4074,
|
||
"timestamp": 1640995200000
|
||
}
|
||
```
|
||
|
||
2. **在线用户列表消息**
|
||
```json
|
||
{
|
||
"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. **安装依赖**:
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
2. **编译TypeScript文件**:
|
||
```bash
|
||
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年
|
||
**技术支持**: 开发团队 |