Csv Handler

核心用法

CSV Handler 专为建筑行业数据处理设计，基于 Python pandas 和 chardet 库构建。核心功能包括：

1. 智能检测：自动识别文件编码（支持 UTF-8、Latin-1、CP1252 等）和分隔符（逗号、分号、制表符、竖线）
2. 数据剖析：profile_csv() 方法快速分析文件结构，返回编码、分隔符、行列数、列名等元数据
3. 自动清洗：清理列名（标准化为小写下划线格式）、去除空行空列、裁剪字符串空白
4. 批量操作：支持多文件合并 (merge_csvs) 和按列拆分 (split_csv)
5. 专用解析器：ScheduleCSVHandler 自动识别日期列；CostCSVHandler 智能解析成本金额列

显著优点

• 开箱即用：无需预先知道文件编码或分隔符，自动适配欧洲软件常见的分号分隔和 Latin 编码
• 健壮性：on_bad_lines='skip' 和 errors='replace' 确保损坏文件仍可读取
• 类型推断：自动尝试将列转换为数值或日期时间类型
• 建筑场景优化：针对进度计划（P6 导出）和成本估算文件提供专用解析逻辑

潜在缺点与局限

• 编码检测限制：chardet 对短文件或小样本可能误判，10000 字节采样在超大文件中可能不够代表性
• 分隔符启发式简单：仅统计出现频率，未考虑引号上下文，极端情况下可能误判
• 日期解析激进："start"/"end"/"date" 关键字匹配可能误伤非日期列
• 内存占用：low_memory=False 适合大文件但增加内存压力；合并大 CSV 时未实现分块处理
• 无数据验证：缺少 schema 校验，无法确保关键字段（如 WBS 编码）格式正确

适合人群

• 建筑项目经理、BIM 工程师、成本估算师
• 需要整合多来源（P6、SAP、ERP）数据的分析人员
• 处理历史项目档案中编码混乱的遗留 CSV 文件

常规风险

• 编码回退风险：检测失败时默认 UTF-8，可能导致非 ASCII 字符（如中文、特殊符号）乱码
• 数据丢失风险：on_bad_lines='skip' 静默丢弃损坏行，关键数据可能遗漏
• 类型转换失败：金额列含货币符号时，replace(r'[\$,]', '') 仅处理美元，其他币种需扩展正则
• 路径遍历：output_dir 参数未验证，传入恶意路径可能写入系统敏感目录
• 列名冲突：多文件合并时同名列自动添加后缀，可能导致下游代码引用错误

核心用法

CSV Handler 是专为建筑行业设计的 CSV 数据处理 Skill，解决从施工软件（如 P6、CostX 等）导出文件时常见的编码混乱、分隔符不统一、数据脏污等问题。

主要功能模块：
1. 智能检测：使用 chardet 自动识别文件编码，通过采样分析识别分隔符（逗号/分号/制表符/竖线）
2. 数据清洗：标准化列名（小写+下划线）、去除空行空列、字符串去空白
3. 批量处理：支持多文件合并（按列关联或简单拼接）、按分类列拆分文件
4. 类型转换：自动识别数值/日期列，或手动指定类型映射
5. 专用处理器：ScheduleCSVHandler 解析进度计划日期列，CostCSVHandler 处理成本金额字段

典型工作流：

handler = ConstructionCSVHandler()
profile = handler.profile_csv("export.csv")  # 先分析文件特征
df = handler.read_csv("export.csv", clean=True)  # 自动检测并清洗

显著优点

• 零配置开箱即用：无需手动指定编码和分隔符，大幅降低非技术用户门槛
• 工程场景深度优化：针对建筑行业常见的日期格式混乱、货币符号混杂等问题提供专门处理
• 内存友好：使用 low_memory=False 和分块采样避免大文件崩溃
• 可追溯性：合并时自动添加 _source_file 列记录数据来源

潜在局限

• 日期解析保守：仅对含 "date/start/end" 字样的列尝试转换，可能漏检其他日期列
• 编码检测非绝对：chardet 基于概率推测，极端罕见编码可能误判
• 无增量处理机制：大文件完整读入内存，超大规模数据集可能需分块手动处理
• 类型推断简单：自动数值转换可能将 ID 字段误转为数字丢失前导零

适合人群

• BIM/施工管理人员：处理从 Primavera P6、MS Project、CostX 等导出的数据
• 造价工程师：合并多期成本报表、清洗招标清单导出文件
• 数据分析师：在建筑项目数据预处理环节节省格式调试时间
• 开发者：作为 ETL 流程的第一环节，标准化输入数据

常规风险

• 文件路径注入：read_csv 等函数直接接收路径参数，若路径来自用户输入需自行校验
• 数据隐私：处理含商业敏感信息的 CSV 时，输出目录需设置适当权限
• 依赖更新：pandas 和 chardet 为活跃维护库，重大版本升级可能带来 API 变更

---

技术实现：纯 Python 实现，基于 pandas 数据框架和 chardet 编码检测库，无外部网络依赖，全部本地运算。