DXZW-cfpz 重复片障端口预警台账
用途
把电信「片障告警详单」原表，按固定口径清洗成可直接上报的「鹰潭电信重复片障端口预警台账」。
全流程由 scripts/process_pianzhang.py 确定性执行，避免每次手工重复造轮子、口径漂移。
触发场景
- 用户提供/指向一份片障告警详单（xlsx/xlsm），要求清洗或出预警台账
- 用户提到「重复片障」「端口预警台账」「DXZW-cfpz」「中断时长」「中断超过 15 分钟」
- 用户描述了如下任一动作：删空工单编号行、加中断时长列、按 15 分钟筛、删地市/IP 列
处理口径（固定，不得擅自改动）
| 步骤 | 动作 | 规则 |
|---|---|---|
| 1 | 删除无工单的行 | 「工单编号」列为空、纯空格、纯空白的行全部删除 |
| 2 | 新增「中断时长」列 | 加在最后一列，逐行套用公式：<br>=DATEDIF(H,I,"d")*24*60+HOUR(I-H)*60+MINUTE(I-H)，单位=分钟 |
| 2b | 按阈值删除 | 删除「中断时长」小于等于 15 的行（保留 > 15） |
| 3 | 删除冗余列 | 删除「地市」列和「IP」列 |
| 4 | 输出 | 另存为 鹰潭电信重复片障端口预警台账YYYYMMDD.xlsx |
⚠️ 必须知道：业务方原始公式写错了减法方向
业务方给的原始文字是 ...HOUR(H当前行-I当前行)*60+MINUTE(H当前行-I当前行)。
其中 H=告警时间、I=恢复时间，H 早于 I，H-I 是负数，而 Excel/WPS 的 HOUR/MINUTE
不接受负数参数，会返回 #NUM!——整条公式作废，每一行都算不出值。
已用本机表格引擎（WPS / KET.Application）实测确认：
| 写法 | 40 分钟行 | 16 分钟行 | 跨天 1530 分钟行 |
|---|---|---|---|
原始 HOUR(H-I) |
#NUM! |
#NUM! |
#NUM! |
修正为 HOUR(I-H) |
40 ✅ | 16 ✅ | 1530 ✅ |
因此脚本默认输出修正后的公式：把减法方向改成 I-H，DATEDIF(H,I,"d") 的日数部分保持不变。
如需逐字照抄原始文字（仅用于对照排查），加 --formula literal。
处理前若用户没有确认过这一点，应主动说明该修正，不要默默改掉。
关键细节，实现时必须遵守：
- 公式里的 H/I 是位置缩写，不是写死的字母。 脚本会先按表头名识别时间列
（告警时间/开始时间/发生时间…与恢复时间/结束时间/复通时间…），识别不到才回落到 H/I 列位置。
口径固定为「恢复时间 − 告警时间，折算成分钟」，并按上节所述修正减法方向。 - 删除地市/IP 列会让列字母左移，因此脚本在删列之后按时间列的新字母重算公式文本，
保证打开表格不出现#REF!或算错。 - Python 侧与 Excel 侧口径必须一致：分钟数 =
天数*1440 + 时*60 + 分，
即先按 DATEDIF 取整日、再取余下的时分。脚本用timedelta.days/seconds复刻这一算法，
已用 WPS 引擎实测对齐（40 / 16 / 1530 三个样本完全一致）。 - 时间无法解析的行不删。 告警未恢复（恢复时间空）属于正常业务情况，
这类行会保留并在结果里列为警告；此时「中断时长」留空，不写公式，避免台账里出现#NUM!。 - 若检测到多数行「告警时间」晚于「恢复时间」，脚本会自动对调两列角色并给出警告。
- 默认只处理第一张工作表；多 sheet 时用
--sheet指定。 .xls不支持，需先另存为.xlsx。
使用方法
脚本固定在本 skill 目录下的 scripts/process_pianzhang.py。先确定本机可用的 Python：
# 任选一个能跑通的即可，不要写死绝对路径
python --version || python3 --version
依赖只需 openpyxl。缺失时先装（优先装进隔离环境，别污染用户全局环境）：
python -m pip install -r "<本skill目录>/scripts/requirements.txt"
然后执行（<本skill目录> 换成该 skill 实际所在目录）：
python "<本skill目录>/scripts/process_pianzhang.py" "<片障告警详单.xlsx>"
脚本自身会检查依赖，缺 openpyxl 时直接提示安装命令，不会静默失败。
常用参数：
... process_pianzhang.py 详单.xlsx --output-dir ./out # 指定输出目录
... process_pianzhang.py 详单.xlsx --sheet "详单" # 指定工作表
... process_pianzhang.py 详单.xlsx --threshold 15 # 阈值，默认 15
... process_pianzhang.py 详单.xlsx --start-col H --end-col I # 手工指定时间列
... process_pianzhang.py 详单.xlsx --formula literal # 逐字照抄原始公式（仅对照用）
脚本会打印一份摘要：原始行数、每步删除行数、删掉的列、输出文件名、时长范围、警告。
执行后必须把摘要里的实际数字转述给用户（删了多少行、输出叫什么名字），
并把生成的台账文件路径展示给用户。
输出
- 文件名：
鹰潭电信重复片障端口预警台账YYYYMMDD.xlsx（YYYYMMDD 为运行当天日期） - 默认落在输入文件同目录，可用
--output-dir改变 - 版式：红色表头加粗、首行冻结、列宽自适应、全表细边框
- 「中断时长」列为公式（非静态值），用 Excel/WPS 打开会自动重算
排查
| 现象 | 原因 / 处理 |
|---|---|
| 报错找不到「工单编号」列 | 表头名不在别名表里；脚本会打印当前表头，据实补别名或改名后重跑 |
| 提示回落到 H/I 列 | 时间列表头未被识别，确认列位置是否正确；必要时用 --start-col/--end-col |
| 输出打开后中断时长是空的 | 该行告警/恢复时间缺一个（如未恢复），或打开它的软件不自动重算公式；用 Excel/WPS 打开即可 |
台账里出现 #NUM! |
说明有人把公式改回了原始文字 HOUR(H-I)；改回 HOUR(I-H)，或加 --formula fixed 重跑 |
| 行数比预想少 | 告警/恢复时间有无法解析的行被保留、或确有大量 <=15 分钟记录，看摘要里的警告 |
