中文数据与格式急救
处理中文表格里最常见、最烦人、又最容易被忽略的一类问题：文件能打开，但内容是错的。
典型症状：
- CSV 用 Excel 打开后中文全是乱码
- 身份证号、银行卡号、订单号显示成
4.51012E+17，后三位变成000 - 同一列日期里混着
2026/1/1、2026-01-01、20260101、2026年1月1日 - 数字和字母全角半角混用，导致匹配和查找失败
- 单元格前后有看不见的空格或制表符，
VLOOKUP匹配不上
通用数据清洗技能只处理"单表脏数据"，不解决这类编码层和存储层的结构性问题。本技能专门处理这一类。
何时使用
- 用户说"这个 CSV 打开是乱码"
- 用户说"身份证号后面几位变成 0 了"
- 用户说"日期格式太乱，没法排序"
- 用户拿到一份外部导出的数据，不确定能不能直接用
快速试用（含样例）
技能包自带一份可复现的脏数据样例，位于 examples/。首次使用时可直接跑一遍验证环境：
python scripts/fix_data.py examples/dirty_utf8_no_bom.csv --diagnose
python scripts/fix_data.py examples/dirty_utf8_no_bom.csv -o examples/fixed_sample.xlsx
样例覆盖乱码、长数字、5 种日期格式、全角半角、首尾空白、空行六类问题。预期结果与逐项校验见 examples/README.md。
执行步骤
- 先诊断，不要直接改。 运行诊断模式，让用户看到问题清单再决定是否修复。
- 确认输入文件路径、是否首行为表头。
- 运行修复脚本，默认输出为
.xlsx（长数字以文本格式写入，从根上避免科学计数法）。 - 向用户汇报修复了什么、改了多少处、有没有需要人工确认的存疑项。
用法
第一步：诊断（只读，不修改原文件）
python scripts/fix_data.py "输入文件.csv" --diagnose
输出示例：
编码探测 : gb18030（置信度：解码成功）
分隔符 : ,
数据规模 : 1250 行 × 12 列
发现 4 类问题
[1] 长数字风险列 第 3 列「身份证号」 1250 个值长度≥15，Excel 打开会变科学计数法
[2] 日期格式混乱 第 7 列「下单日期」 命中 4 种不同格式
[3] 全角半角混用 第 5 列「商品编码」 89 个值含全角字符
[4] 首尾空白 第 2、5、9 列 共 213 个单元格存在首尾空白
第二步：修复
python scripts/fix_data.py "输入文件.csv" -o "修复后.xlsx"
常用参数
| 参数 | 说明 |
|---|---|
--diagnose |
只诊断不输出，打印问题清单 |
-o, --output |
输出路径，后缀 .xlsx 或 .csv，默认 原文件名_fixed.xlsx |
--no-header |
输入文件没有表头行 |
--keep-width |
关闭全角转半角（默认开启） |
--date-format |
统一后的日期格式，默认 %Y-%m-%d |
--report |
额外输出 JSON 格式的诊断报告 |
--sheet |
读取 xlsx 时指定工作表名，默认第一个 |
输出说明
- 默认输出 xlsx：长数字列以文本格式写入并保留完整精度，Excel 打开不再变科学计数法。这是解决问题的根本方式。
- 若输出 csv：脚本会在长数字前写入一个不可见的零宽空格以阻止 Excel 自动转换，代价是其他程序读取时可能多出一个字符。仅在必须用 csv 时使用，并主动向用户说明。
修复规则
| 问题 | 判定规则 | 处理方式 |
|---|---|---|
| 编码错误 | BOM 检测 → UTF-8 → GB18030 → Big5 依次尝试解码 | 以探测到的编码读取，统一按 UTF-8 重新保存 |
| 长数字精度丢失 | 该列 ≥50% 的值为长度 ≥15 的纯数字，或长度 ≥8 且含前导零 | xlsx 中以文本格式写入；csv 中加保护前缀 |
| 日期格式混乱 | 同一列命中 ≥2 种日期格式 | 统一为 YYYY-MM-DD，无法解析的原样保留并提示 |
| 全角半角混用 | 值中含 U+FF01–U+FF5E 或 U+3000 字符 | 数字与字母转半角，中文不变 |
| 首尾空白 | 值前后含空格、制表符、换行 | 去除 |
| 空行 | 整行所有单元格为空 | 删除 |
| BOM | 文件头含 UTF-8 BOM | 读取时剥离，输出统一加 BOM（保证 Excel 不乱码） |
限制
- 只处理表格型数据（csv / tsv / xlsx），不处理 Word、PDF。
- 日期解析仅支持常见的中英文数字格式，无法解析的值会原样保留并在报告中列出，不会静默丢弃。
- 修复不会改动原文件，始终生成新文件。
- 超大文件（>50 万行）建议先拆分，脚本为全量内存处理。
依赖
仅使用 Python 标准库。读写 .xlsx 需要 openpyxl：
pip install openpyxl
若未安装，脚本自动降级为仅支持 csv 输入输出，并给出提示。
