497 lines
16 KiB
Markdown
497 lines
16 KiB
Markdown
# 瓦尔塔蓄电池配送管理系统
|
||
|
||
## 项目概述
|
||
|
||
这是一个基于微信小程序的蓄电池配送管理系统，为瓦尔塔蓄电池门店提供智能化的配送管理解决方案。系统支持双模式运行，既可以独立使用模拟数据进行功能测试，也可以连接真实后端服务进行联调。
|
||
|
||
## 前端功能特性
|
||
|
||
### 🗺️ 地图展示功能
|
||
- **仓库标记**: 在地图上显示所有瓦尔塔蓄电池门店位置
|
||
- **货运人员实时位置**: 显示配送人员的实时位置和状态
|
||
- **订单路线规划**: 可视化展示配送路线
|
||
- **交互式地图**: 支持缩放、拖动、点击查看详情
|
||
|
||
### 📋 订单管理功能
|
||
- **待指派订单列表**: 显示所有等待配送的订单
|
||
- **订单详情查看**: 点击查看订单详细信息
|
||
- **智能指派功能**: 将订单指派给合适的货运人员
|
||
- **订单状态跟踪**: 实时更新订单配送状态
|
||
|
||
### 用户系统功能
|
||
- **多角色支持**: 管理员、货运人员、游客等不同角色
|
||
- **用户登录/登出**: 支持微信登录
|
||
- **签到功能**: 支持每日签到记录和状态管理
|
||
- **注册功能**: 游客用户注册为正式用户
|
||
- **个人信息管理**: 查看和编辑个人信息
|
||
- **权限控制**: 不同角色有不同的操作权限
|
||
|
||
### ⚙️ 系统设置功能
|
||
- **数据模式切换**: 支持模拟数据和真实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. **微信登录请求**
|
||
```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
|
||
}
|
||
```
|
||
|
||
### 系统从服务器接收的消息数据
|
||
|
||
#### 用户相关消息
|
||
|
||
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. **签到响应**
|
||
```json
|
||
{
|
||
"success": boolean, // 签到是否成功
|
||
"message": "string", // 签到结果消息
|
||
"userInfo": { // 更新后的用户信息
|
||
"id": number,
|
||
"name": "string",
|
||
"avatarUrl": "string",
|
||
"nickName": "string",
|
||
"phone": "string",
|
||
"role": "string",
|
||
"lastSignInTime": number
|
||
}
|
||
}
|
||
```
|
||
|
||
4. **注册响应**
|
||
```json
|
||
{
|
||
"success": boolean, // 注册是否成功
|
||
"message": "string", // 注册结果消息
|
||
"userInfo": { // 注册后的用户信息
|
||
"id": number,
|
||
"name": "string",
|
||
"avatarUrl": "string",
|
||
"nickName": "string",
|
||
"phone": "string",
|
||
"role": "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)**: 包括未登录、已登录、已签到等状态
|
||
- **角色权限**: 根据用户角色控制功能访问权限
|
||
|
||
## 运货师傅上线与位置更新机制
|
||
|
||
### 师傅上线流程
|
||
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. **安装依赖**:
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
2. **编译TypeScript文件**:
|
||
```bash
|
||
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年
|
||
**技术支持**: 开发团队 |