导出代码说明

upload_app/process_parquet_README.md

@@ -0,0 +1,146 @@
+# 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. 安装依赖
+```bash
+pip install pandas numpy openpyxl
+```
+
+### 2. 运行脚本
+```bash
+python process_parquet_to_excel.py
+```
+
+### 3. 查看结果
+脚本运行完成后，在output目录中查看生成的Excel文件：
+- 川藏13B标二分部_水准数据报表.xlsx
+- 川藏13B标一分部_水准数据报表.xlsx
+- ...
+
+## 配置说明
+
+可在脚本顶部修改以下配置：
+
+```python
+# 数据根目录
+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导出
+  - 支持两层目录结构