洽商整理
把一份原始洽商台账，整理成可统计、可考核、经得起审计复核的成果：一版补全字段的 Excel 台账 + 一份可视化统计看板。
适用前提
- 输入为 Excel 台账（.xlsx），表头包含洽商编号、专业、洽商标题、洽商内容、变更金额等列。
- 表头行不固定在第几行——脚本自动探测；数据行从表头下一行开始。
- 脚本为纯标准库实现，不依赖 openpyxl / pandas，内网离线环境可运行。
环境约定
下文 PY 指本机 Python 解释器绝对路径。本机受管解释器为：
C:\Users\余愿\.workbuddy\binaries\python\versions\3.12.10\python.exe（无 python 全局命令时必须用绝对路径）。
Skill 目录 SK：D:\资料\学习\skill\洽商梳理\.workbuddy\skills\洽商整理
日期一律用 date +%Y%m%d 获取，禁止凭记忆填写。
工作流
第 1 步：解析台账
PY "$SK/scripts/read_ledger.py" --file "台账.xlsx" [--sheet 工作表名] [--header 4] --out parsed.json
输出 JSON 含 colmap（标准字段名→列字母）、rows（逐行字段值）。先读一遍输出，确认：识别到的工作表名、表头行号、行数、列映射是否与预期一致。列映射有偏差时用 --header 指定表头行重跑。
第 2 步：逐条判读（本 Skill 的核心，不可跳过）
对每条洽商，依据「洽商内容」与「初步原因」列，按 references/原因分类规则.md 判定：
- 内容简述 —— 固定格式
原：…… / 变更后：……，60 字内，只陈述技术事实。 - 涉及图纸 —— 联系单号、图号或纪要编号。
- 变更主因 / 变更辅因 —— 四选一：设计原因 / 校方原因 / 预算原因 / 其他原因，按规则中的优先级判读。
- 责任归属 —— 按映射表填写（设计单位 / 建设单位（校方） / 造价咨询 / 第三方单位 / 无责任方）。
- 变更金额拆分 —— 按多因拆分口径填入四列分项金额，四列合计必须等于变更金额。
- 资料情况 / 审核意见 —— 按
references/字段规范.md取值口径填写，审核意见中标注判读依据与置信度（高/中/低）。
判读纪律：
- 「洽商内容」「变更金额」「初步原因」三列只读不改写。
- 置信度低的条目（内容为空、仅有流程状态、多因交织难分主次），照填暂定值，但必须在交付时单独列出清单提请人工复核，且明确"未经复核不得作为考核依据"。
- 金额确需估算拆分的，在审核意见注明"金额按估算比例拆分，待造价复核"。
- 结论由人拍板，本 Skill 只提供依据与流程，不替人认定责任与金额。
第 3 步：写出整理结果 JSON
按 assets/整理结果模板.json 的结构写 整理结果.json：meta 填项目名与来源文件，header_row 填表头行号，updates 数组每条用 row（行号）+ 洽商编号 定位，只需列出要写入的字段，值传 null 表示跳过不写。
第 4 步：回填生成 Excel 台账（另存，不动原文件）
PY "$SK/scripts/write_ledger.py" --src "台账.xlsx" --data 整理结果.json --out "台账_整理_YYYYMMDD.xlsx"
- 以原文件为模板复制，只改单元格值，原表样式、合并单元格、列宽、打印设置全部保留。
- 金额以数值写入，Excel 可直接求和。
- 脚本自动校验「四列分项合计 = 变更金额」，不一致的条目会打印清单，必须逐条复核并修正后重跑。
第 5 步：生成统计看板
PY "$SK/scripts/build_dashboard.py" --data 整理结果.json --source parsed.json \
--out "洽商统计看板_项目名_YYYYMMDD.html" --stats "统计结果_YYYYMMDD.json"
看板为单文件 HTML，图表为内嵌 SVG、无外部 CDN 依赖，双击即可打开、可直接投屏或截图入汇报材料。内含：
- KPI：洽商条数、变更净额、正向/负向变更金额、设计原因影响占比（设计成果考核核心指标）；
- 四类原因金额构成环形图、各专业变更净额条形图（正红负绿）、主因分布、责任归属分布；
- 明细表，支持按专业/主因筛选、关键字搜索、导出 CSV；
- 口径说明（占比按绝对值计算、最终以造价审核及结算审定为准）。
第 6 步：自检与交付
交付前核对：
- 分项金额校验全部通过（第 4 步无差异清单）；
- 变更主因无空缺、无第四类以外的值；
- 低置信度条目已单独列出并提示复核；
- 两个成果文件均已生成，用
present_files一并呈现，先呈现看板。
输出文件规范
| 文件 | 命名 | 位置 |
|---|---|---|
| 整理后台账 | {原台账名}_整理_{YYYYMMDD}.xlsx |
与源台账同目录 |
| 统计看板 | 洽商统计看板_{项目名}_{YYYYMMDD}.html |
与源台账同目录 |
| 统计结果 | 统计结果_{YYYYMMDD}.json |
与源台账同目录 |
| 中间文件 | parsed.json / 整理结果.json |
源台账同目录下的 .workbuddy/洽商整理/ |
原始台账永不覆盖。整理结果 JSON 保留，便于人工修改后一键重跑。
资源索引
scripts/read_ledger.py—— 解析 xlsx → JSON（自动探测表头、模糊匹配列名）scripts/write_ledger.py—— 整理结果回填 → 新 xlsx（保留原样式、分项金额校验）scripts/build_dashboard.py—— 整理结果 → HTML 看板 + 统计 JSONreferences/字段规范.md—— 17 个字段的填写要求、资料情况与审核意见取值口径、审计自检要点references/原因分类规则.md—— 四类原因定义与关键词、判定优先级、责任归属映射、置信度分级、金额拆分规则、真实判例assets/整理结果模板.json—— 整理结果 JSON 结构模板
常见问题
- 未识别到洽商编号列：用
--header指定正确表头行；表头有合并单元格时，取文字所在的那一行。 - Excel 打开提示修复：原文件含 printerSettings 等二进制条目时可能出现，脚本已原样复制；若仍提示，说明原文件本身有残留设置，另存为一次即可。
- 看板金额显示为 0：检查整理结果 JSON 中四列分项金额是否为数值而非字符串。
- 新项目台账字段命名不同：脚本按关键词模糊匹配列名；匹配不上的列在
columns中std为 null，需人工确认后在 JSON 中用原表头名作键。
