railway_cloud/upload_app/process_parquet_README.md

Parquet数据处理与Excel导出脚本

功能说明

本脚本用于处理铁路项目中的parquet数据文件，将其转换为Excel报表。

主要功能

1. 读取data目录下所有parquet文件（按文件夹分组）
2. 关联5种类型数据：断面、观测点、沉降、水准、原始数据
3. 以水准数据为主体整理并生成Excel报表

输出列

• 日期：水准数据时间（格式：YYYY-MM-DD）
• 水准线路：linecode
• 起始点：benchmarkids拆分后的起始点
• 终止点：benchmarkids拆分后的终止点
• 测点：同一水准线路的所有观测点ID（逗号分隔）
• 起始时间：原始数据mtime最早时间
• 终止时间：原始数据mtime最晚时间
• 类型：断面数据的work_site字段

目录结构

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

使用方法

1. 安装依赖

pip install pandas numpy openpyxl

2. 运行脚本

python process_parquet_to_excel.py

3. 查看结果

脚本运行完成后，在output目录中查看生成的Excel文件：

• 川藏13B标二分部_水准数据报表.xlsx
• 川藏13B标一分部_水准数据报表.xlsx
• ...

配置说明

可在脚本顶部修改以下配置：

# 数据根目录
DATA_ROOT = "./data"

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

数据关联逻辑

断面数据(sections)
    → 观测点数据(checkpoints) via section_id
    → 沉降数据(settlements) via point_id
    → 水准数据(levels) via NYID
    → 原始数据(originals) via NYID

特性

• ✅ 支持两层目录结构（主文件夹/中文子文件夹/parquet文件）
• ✅ 自动过滤空文件（<1KB）
• ✅ 断点续传支持（可扩展）
• ✅ 详细的日志输出
• ✅ 进度显示
• ✅ 容错处理（缺失字段、缺失数据等）
• ✅ 数据类型动态检查

注意事项

1. 原始数据：如果某个数据集没有原始数据表，时间范围将使用水准数据的createDate作为默认值
2. benchmarkids字段：如果水准数据中不存在benchmarkids字段，起始点和终止点将为空
3. 数据关联：如果某个水准数据找不到对应的沉降数据，将跳过该记录
4. 文件大小：自动过滤小于1KB的空parquet文件

日志说明

脚本运行时会输出详细日志，包括：

• 扫描到的文件数量
• 每种类型的数据记录数
• 处理进度
• 警告和错误信息
• 最终的统计信息

版本历史

• v1.2 (2025-11-08)

  • 🔧 彻底修复：numpy array布尔值判断错误根本原因
    • 修复 find_mtime_range 函数中的 not nyids 问题
    • 添加全面的 DataFrame 类型检查
    • 使用 .size 正确处理 numpy array
  • ✨ 新增：全面的防御性编程
    • 多层类型验证（isinstance 检查）
    • DataFrame/Series 安全检查
    • 防御性错误处理
  • 🛡️ 增强：代码健壮性
    • 防止各种边界情况
    • 安全的 numpy array 操作
    • 防止空值和类型错误
  • ✨ 新增：NYID期数ID重复检查
    • 自动检测水准数据中的重复NYID
    • 详细列出每个重复的NYID及其出现次数
    • 全局汇总所有数据集的重复情况
    • 计算额外重复记录数
  • 📝 改进：详细的修复文档和最佳实践

• v1.1 (2025-11-08)

  • 🔧 修复：numpy array布尔值判断错误（The truth value of an array...）
  • ✨ 新增：数据质量检验机制
    • 预期记录数 vs 实际记录数对比
    • 自动检测数据丢失或处理异常
    • 详细的数据质量报告
  • ✨ 新增：全局数据质量统计
    • 每个文件夹的记录数统计
    • 总计记录数显示
  • ✨ 新增：增强错误处理
    • 详细的错误堆栈跟踪
    • 针对常见错误的智能提示
  • 📝 改进：更详细的中文错误提示

• v1.0 (2025-11-08)

  • 初始版本
  • 支持5种数据类型关联
  • 支持Excel导出
  • 支持两层目录结构