railway_cloud/upload_app/使用指南.md

# Parquet数据处理脚本 - 使用指南

## 快速开始

### 1. 安装依赖
```bash
pip install pandas numpy openpyxl
```

### 2. 运行脚本
```bash
python process_parquet_to_excel.py
```

### 3. 查看结果
输出目录：`./output/`
- 川藏13B标二分部_水准数据报表.xlsx
- 川藏13B标一分部_水准数据报表.xlsx
- ...

## 新版本 v1.1 特性

### ✅ 修复了之前的错误
- 修复了 "The truth value of an array..." 错误
- 改进了numpy array的处理方式

### ✅ 数据质量检验
脚本现在会自动验证数据完整性：
- 对比预期记录数与实际记录数
- 如果不一致，提供详细分析
- 帮助快速发现数据问题

**示例输出：**
```
✅ 数据质量检验通过：实际记录数(150) = 预期记录数(150)
```

### ✅ 增强的错误提示
- 详细的错误堆栈跟踪
- 智能错误分析
- 更好的中文提示

### ✅ NYID期数ID重复检查
- 自动检测水准数据中的重复NYID
- 详细列出重复的NYID及其出现次数
- 全局汇总所有数据集的重复情况
- 计算额外重复记录数

**示例输出：**
```
检查NYID期数ID重复...

⚠️  发现 2 个重复的NYID:
   NYID=1308900 出现 2 次
   NYID=1317148 出现 3 次
```

### ✅ 全局统计报告
```
全局数据质量统计
============================================================
川藏13B标二分部: 150 条记录
川藏13B标一分部: 120 条记录
川藏14B标二分部: 200 条记录
川藏14B标三分部: 180 条记录
川藏14B标一分部: 160 条记录

总计: 810 条记录
============================================================
```

## 如何验证数据完整性

### 方法1：查看质量检验结果
脚本运行时会显示：
```
预期生成记录数: 200
数据质量检验：最终记录数应等于此数字
...
✅ 数据质量检验通过：实际记录数(200) = 预期记录数(200)
```

如果看到 ⚠️ 警告，说明有数据丢失，需要检查。

### 方法2：手动验证
1. 统计水准数据文件中的记录总数
2. 对比Excel文件中的记录数
3. 理论上应该相等（每条水准数据对应一条Excel记录）

### 方法3：检查日志
寻找以下警告：
- "NYID=xxx 无对应沉降数据" - 说明数据关联链断裂
- "处理水准数据时出错" - 说明处理过程中出现异常

### 方法4：检查NYID重复
脚本会自动检查NYID期数ID是否重复：
```
检查NYID期数ID重复...

✅ 未发现重复的NYID
```
或
```
⚠️  发现 2 个重复的NYID:
   NYID=1308900 出现 2 次
   NYID=1317148 出现 3 次
```

如果在"NYID期数ID重复汇总"中看到重复记录，需要检查数据质量。

## 输出文件说明

每个Excel文件包含8列：
- **日期**：水准数据时间（YYYY-MM-DD）
- **水准线路**：linecode
- **起始点**：benchmarkids拆分（如果存在）
- **终止点**：benchmarkids拆分（如果存在）
- **测点**：同一水准线路的所有观测点ID
- **起始时间**：原始数据mtime最早时间
- **终止时间**：原始数据mtime最晚时间
- **类型**：断面数据的work_site

## 常见问题

### Q: 出现数据质量警告怎么办？
A: 查看脚本输出的"可能原因"部分，通常是因为：
- 某些水准数据没有对应的沉降数据
- 数据文件损坏或不完整
- 数据关联链有问题

### Q: 起始点和终止点为空怎么办？
A: 这说明水准数据中不存在benchmarkids字段，属于正常情况。脚本会显示：
```
注意: 未发现benchmarkids字段，起始点/终止点将为空
```

### Q: 时间范围显示默认值怎么办？
A: 这说明该数据集没有原始数据表（原始数据表），脚本会使用水准数据时间作为默认值。

### Q: 如何查看详细的处理日志？
A: 脚本会自动输出详细日志，包括：
- 扫描到的文件数量
- 读取的记录数
- 处理进度
- 错误和警告信息

## 目录结构要求

```
data/
  ├── 川藏13B标二分部/
  │   ├── 沉降数据表/
  │   │   └── settlement_*.parquet
  │   ├── 断面数据表/
  │   │   └── section_*.parquet
  │   ├── 观测点数据表/
  │   │   └── point_*.parquet
  │   └── 水准数据表/
  │       └── level_*.parquet
  ├── 川藏13B标一分部/
  │   └── ...
  └── ...
```

## 配置选项

在脚本顶部可以修改：
```python
# 数据根目录
DATA_ROOT = "./data"

# 输出目录
OUTPUT_DIR = "./output"
```

## 技术支持

如有问题，请检查：
1. 所有parquet文件是否完整
2. 数据目录结构是否正确
3. 依赖包是否已正确安装
4. 查看脚本输出的错误和警告信息

## 版本历史

- **v1.2** (2025-11-08)
  - 彻底修复numpy array布尔值判断错误
  - 新增NYID期数ID重复检查功能
  - 新增全局重复NYID汇总
  - 增强数据质量检验
  - 增强防御性编程

- **v1.1** (2025-11-08)
  - 修复numpy array布尔值错误
  - 新增数据质量检验机制
  - 新增全局统计报告
  - 增强错误处理和提示

- **v1.0** (2025-11-08)
  - 初始版本
  - 基本的数据处理和Excel导出功能