完善小细节

tradeCattle/DATA_SYNC_TROUBLESHOOTING_GUIDE.md

@@ -0,0 +1,106 @@
+# 数据同步问题诊断和解决方案
+
+## 问题分析
+
+根据用户提供的图片，我们发现了以下问题：
+
+### 1. iot_device_data表中有数据
+- 设备ID: 24075000139
+- 电压: 3.300
+- 温度: 25.80
+- 设备类型: 4 (项圈)
+- 运送订单ID: 86
+
+### 2. xq_client_log表中数据为空
+- device_voltage字段: (Null)
+- device_temp字段: (Null)
+- server_device_id字段: (Null)
+
+## 问题原因
+
+1. **字段映射不匹配**: xq_client_log表的实际字段结构与我们的实体类不匹配
+2. **数据同步未执行**: 60分钟定时任务可能还没有执行，或者手动同步失败
+3. **字段长度限制**: latitude字段长度不够，导致数据截断错误
+
+## 解决方案
+
+### 1. 修复字段映射问题
+
+我们已经修改了 `XqClientLogMapper.xml`，建立了正确的字段映射：
+
+| 实际表字段 | 实体类属性 | 说明 |
+|-----------|-----------|------|
+| `battery` | `deviceVoltage` | 电池电量→设备电压 |
+| `temperature` | `deviceTemp` | 温度 |
+| `deviceld` | `serverDeviceId` | 设备长ID→主机设备ID |
+| `steps` | `walkSteps` | 步数 |
+| `time` | `createTime/updateTime` | 时间字段 |
+
+### 2. 修复字段长度问题
+
+创建了SQL脚本 `fix_xq_client_log_field_length.sql` 来扩展字段长度：
+- latitude: VARCHAR(50)
+- longitude: VARCHAR(50)  
+- device_voltage: VARCHAR(50)
+- device_temp: VARCHAR(50)
+
+### 3. 手动触发数据同步
+
+使用API接口手动触发同步：
+```bash
+POST http://localhost:8080/api/deliveryDevice/manualSyncDeviceLogs
+```
+
+## 测试步骤
+
+### 1. 执行数据库修复脚本
+```sql
+-- 执行 fix_xq_client_log_field_length.sql
+-- 扩展字段长度，避免数据截断
+```
+
+### 2. 手动触发数据同步
+```bash
+# 等待应用完全启动后
+Invoke-WebRequest -Uri "http://localhost:8080/api/deliveryDevice/manualSyncDeviceLogs" -Method POST
+```
+
+### 3. 验证同步结果
+```sql
+-- 检查xq_client_log表中是否有新数据
+SELECT * FROM xq_client_log WHERE device_id = '24075000139' ORDER BY time DESC LIMIT 10;
+```
+
+### 4. 检查同步统计
+```bash
+# 获取同步统计信息
+Invoke-WebRequest -Uri "http://localhost:8080/api/deliveryDevice/getLogSyncStatistics" -Method GET
+```
+
+## 预期结果
+
+同步成功后，xq_client_log表应该包含：
+- device_id: 24075000139
+- battery: 3.300 (来自iot_device_data.voltage)
+- temperature: 25.80 (来自iot_device_data.temperature)
+- steps: 21 (来自iot_device_data.steps)
+- latitude: 30.4812778
+- longitude: 114.401791
+- time: 当前时间
+
+## 故障排除
+
+如果同步仍然失败，请检查：
+
+1. **应用日志**: 查看控制台输出，确认同步过程中的错误信息
+2. **数据库连接**: 确认应用能够正常连接数据库
+3. **字段权限**: 确认数据库用户有INSERT权限
+4. **数据格式**: 确认数据类型转换正确
+
+## 下一步
+
+1. 等待应用完全启动
+2. 执行数据库修复脚本
+3. 手动触发数据同步
+4. 验证同步结果
+5. 测试日志查询和轨迹功能