导出代码说明

2025-11-08 19:33:05 +08:00
parent 74fbece74b
commit 4ecc770d20
3 changed files with 527 additions and 0 deletions
--- a/upload_app/使用指南.md
+++ b/upload_app/使用指南.md
@@ -0,0 +1,201 @@
+# 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导出功能