# harmony_delivery

**Repository Path**: han050801/harmony_delivery

## Basic Information

- **Project Name**: harmony_delivery
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-14
- **Last Updated**: 2026-02-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# harmony_delivery 快递配送系统

## 项目介绍

harmony_delivery 是一个基于 HarmonyOS 的智能快递配送系统，包含快递柜管理、MQTT 通信服务、小程序客户端等模块，实现了完整的快递配送解决方案。

## 目录结构

```
harmony_delivery/
├── ExpressLockerNorth/   # 快递柜管理系统（北向服务）
├── mqtt server/          # MQTT 通信服务器
├── xiaochengxu/          # 测试用小程序
└── xiaochengxu_ui/       # 实际实现的小程序
```

## 功能模块

### 1. ExpressLockerNorth
- 快递柜设备管理
- 快递存取控制
- 设备状态监控
- 远程控制与配置

### 2. mqtt server
- MQTT 协议支持
- 设备间实时通信
- 消息发布与订阅
- 设备状态管理

### 3. xiaochengxu
- 测试用小程序
- 用于功能测试和开发调试
- 包含完整的小程序前后端功能
- 不建议用于生产环境

### 4. xiaochengxu_ui
- 实际实现的微信小程序
- 正式生产环境使用
- 完整的用户交互界面
- 订单查询与管理
- 快递柜位置显示
- 快递存取功能

## 技术栈

| 模块 | 技术 | 说明 |
|------|------|------|
| 设备端 | HarmonyOS | 快递柜设备开发 |
| 后端服务 | Node.js | 服务器开发 |
| 通信协议 | MQTT | 设备间通信 |
| 客户端 | 微信小程序 | 用户界面 |

## 安装说明

### 前提条件
- Node.js 14.0+ 
- HarmonyOS 开发环境
- 微信开发者工具

### 安装步骤

1. 克隆仓库
   ```bash
   git clone https://gitee.com/han050801/harmony_delivery.git
   cd harmony_delivery
   ```

2. 安装依赖
   ```bash
   # 安装MQTT服务器依赖
   cd "mqtt server"
   npm install
   
   # 安装测试用小程序依赖（可选）
   cd ../xiaochengxu
   npm install
   ```

3. 配置文件
   - 所有配置文件均提供示例文件（.example.js/.example.ets）
   - 复制示例文件为实际配置文件，然后修改为自己的环境配置
   
   **Windows系统命令：**
   ```cmd
   # 微信小程序配置
   copy xiaochengxu\utils\config.example.js xiaochengxu\utils\config.js
   
   # UI配置
   copy xiaochengxu_ui\utils\config.example.js xiaochengxu_ui\utils\config.js
   
   # HarmonyOS配置
   copy ExpressLockerNorth\DemoU\entry\src\main\ets\common\utils\ConfigManager.example.ets ExpressLockerNorth\DemoU\entry\src\main\ets\common\utils\ConfigManager.ets
   
   # MQTT服务器配置
   copy "mqtt server\server\config.example.js" "mqtt server\server\config.js"
   
   # MQTT数据库配置
   # 数据库文件会在首次运行时自动创建，无需手动复制
   ```
   
   **Linux/macOS系统命令：**
   ```bash
   # 微信小程序配置
   cp xiaochengxu/utils/config.example.js xiaochengxu/utils/config.js
   
   # UI配置
   cp xiaochengxu_ui/utils/config.example.js xiaochengxu_ui/utils/config.js
   
   # HarmonyOS配置
   cp ExpressLockerNorth/DemoU/entry/src/main/ets/common/utils/ConfigManager.example.ets ExpressLockerNorth/DemoU/entry/src/main/ets/common/utils/ConfigManager.ets
   
   # MQTT服务器配置
   cp "mqtt server/server/config.example.js" "mqtt server/server/config.js"
   
   # MQTT数据库配置
   # 数据库文件会在首次运行时自动创建，无需手动复制
   ```
   
   - 配置项说明：
     - 服务器IP和端口
     - 微信App ID和Secret（用于小程序登录）
     - JWT密钥
     - MQTT主题配置
     - 设备ID
     - 数据库文件路径（用于MQTT数据存储）
   
   - 生产环境使用时，主要配置 `mqtt server` 和 `xiaochengxu_ui`

4. 启动服务
   ```bash
   # 启动MQTT服务器
   cd "mqtt server"
   npm start
   
   # 启动测试用小程序后端（可选）
   cd ../xiaochengxu
   npm start
   ```

5. 运行小程序
   
   ### 生产环境使用（推荐）
   - 使用微信开发者工具打开 `xiaochengxu_ui` 目录
   - 配置小程序AppID
   - 编译并运行
   
   ### 测试环境使用
   - 使用微信开发者工具打开 `xiaochengxu` 目录
   - 配置小程序AppID
   - 编译并运行

## 使用说明

### 用户端操作
1. 打开微信小程序
2. 注册/登录账号
3. 查看附近快递柜位置
4. 下单寄件或查询快递
5. 接收取件码并前往快递柜取件

### 快递员端操作
1. 登录快递员账号
2. 扫描快递柜二维码
3. 存入/取出快递
4. 确认操作并完成配送

### 管理员端操作
1. 登录管理后台
2. 查看设备状态和统计数据
3. 管理用户和快递员账号
4. 处理异常情况

## 项目特色

1. **多端协同**：支持快递柜设备、小程序客户端、后端服务的协同工作
2. **实时通信**：基于 MQTT 协议实现设备间实时消息推送
3. **智能管理**：提供快递存取、状态监控、数据统计等功能
4. **易于扩展**：模块化设计，方便功能扩展和二次开发

## 开发指南

### 代码规范
- 遵循各技术栈的最佳实践
- 代码注释完整，便于维护
- 提交信息清晰，说明修改内容

### 贡献流程
1. Fork 本仓库
2. 新建功能分支 (`git checkout -b feature/xxx`)
3. 提交代码 (`git commit -m "添加xxx功能"`)
4. 推送分支 (`git push origin feature/xxx`)
5. 新建 Pull Request

## 版本更新

### v1.0.0 (2025-12-23)
- 初始版本发布
- 实现快递柜基本功能
- 完成MQTT服务器搭建
- 实现小程序基本界面和功能

### v1.1.0 (2026-01-14)
- 优化小程序UI设计
- 增强MQTT服务器功能
- 修复已知问题

## 联系方式

- 项目地址：[https://gitee.com/han050801/harmony_delivery](https://gitee.com/han050801/harmony_delivery)
- 问题反馈：通过 Issues 提交
- 合作联系：欢迎通过Gitee私信联系

## 许可证

MIT License