清收清欠表格处理（qingshou-qingqian-table）
Overview
本技能封装清收清欠业务中「前期费用逾期情况表」的处理工作流：
1. 解析表格：读取逾期表（双层表头），输出结构化数据，支持表头探测校验
2. 异议处理：按【异议单位、项目及金额、原因】新增"异议原因"列
3. 情况说明：在"情况说明.docx"对应锚点段后插入结构化异议表格
4. 数据看板：基于表格数据生成"清欠项目数据看板"HTML（可选，可部署）
通用化设计：表格结构知识集中在 config/table-schema.json，脚本全部读配置运行；换新表型（不同表头/行号/列布局）只需改配置，不用改代码。
配置层（config/）
| 文件 | 作用 |
|---|---|
config/table-schema.json |
表结构 schema：标题/单位单元格、表头行区间、合计行、数据起始行、列映射（含金额分组与回款率列）、异议原因列配置 |
config/reason-templates.json |
异议原因模板库（华南市场部 / 华南投资公司 / 成都汇票挪用），新场景直接追加条目 |
表格结构速览（默认 schema，详见 references/table-schema.md）
- 第1行：合并标题（如「2026年前期费用逾期情况表」）
- 第2行：编制单位（A2:C2 合并）+ 单位：万元（最右列）
- 第3-4行：双层表头（第3行大项，第4行子项）
- 第5行：合计行（A5:D5 合并）
- 第6行起：数据行（序号 1, 2, ...）
- 列布局：A序号 B所属单位 C项目名称 D业主名称 | E-G 上年末逾期金额(合计/本金/利息) | H-J 预计新增逾期金额(合计/本金/利息) | K-M 预计年底逾期金额(合计/本金/利息) | N建议清收目标下达值 O本金回款率 P利息回款率 Q综合清收率 R备注 S异议原因(可选新增)
工作流
Step 0: 运行环境
脚本依赖 openpyxl / python-docx，已装入隔离 venv（managed Python 3.13.12）。统一用以下解释器运行：
PY="C:/Users/46025/.workbuddy/binaries/python/envs/default/Scripts/python.exe"
"$PY" scripts/parse_table.py "<表格路径>"
Step 1: 定位表格文件
文件名模式：{year}年前期费用逾期情况表-{unit}.xlsx（如 2026年前期费用逾期情况表-华南公司.xlsx）。
通常位于桌面或项目备份目录（C:\Users\46025\WorkBuddy\2026-08-26-14-47-49\逾期表修改备份\）。
Step 2: 解析表格结构（含表头校验）
"$PY" scripts/parse_table.py "<表格路径>" [--output out.json]
--schema：表结构配置文件（默认config/table-schema.json）--output / -o：解析结果（含校验信息）落盘为 JSON，供看板等下游复用- 输出：表格维度、合并单元格、表头校验（与 schema 比对，不匹配打 WARN 并打印实际结构）、合计行、数据行明细（含异议原因列如存在）
Step 3: 新增"异议原因"列（如表中无此列）
"$PY" scripts/add_reason_column.py "<表格路径>" --reasons '{"6":"原因文本A","7":"原因文本B"}' [--column-name 异议原因] [--width 40]
--reasons为 JSON：键是 Excel 行号（1-based），值是原因文本- 列名/表头行/样式来源列（默认"备注"列）/列宽从 schema 读取，可用参数覆盖
- 自动：在现有最大列后追加列、复制样式来源列样式、自动换行、设置列宽；已存在目标列则跳过
Step 4: 更新情况说明.docx（插入结构化异议表格）
"$PY" scripts/update_remark_docx.py "<docx路径>" --anchor "现华南公司反馈如下异议：" --rows '[[...]]' [--delete-prefix "前缀1"] [--delete-prefix "前缀2"] [--font-name Times New Roman] [--east-font 宋体] [--font-size 10.5] [--table-style "Table Grid"]
--anchor：表格插入位置的锚点段落文本（须存在于 docx 中）--rows：JSON 二维数组，首行为表头["异议单位","项目及金额","异议原因"]--delete-prefix：可重复，删除锚点后旧叙述性异议段落- 字体/字号/表格样式均可参数化，默认 宋体10.5pt + Table Grid（向后兼容）
Step 5: 构建清欠数据看板（可选）
"$PY" scripts/parse_table.py "<表格路径>" -o out.json
"$PY" scripts/build_dashboard.py out.json -o "清欠数据看板.html" [--title "自定义标题"]
看板为自包含 HTML（内嵌数据、纯 CSS、无外部 CDN 依赖，可离线打开），含：
- KPI 卡：项目数 / 上年末逾期 / 预计新增 / 预计年底逾期 / 清收目标 / 综合清收率
- 金额结构对比条、预警列表（>5000万红色、>1000万橙色大额逾期 + 清收率<30%）
- 单位维度汇总（含占比条形）、异议原因明细（如有）、项目明细表（可搜索 + 单位筛选）
生成后可用 CloudStudio 部署为公开链接（用户惯例）。数据字段：summary / units / alerts / projects / reasons。
Step 6: 回归测试（改代码/配置后必跑）
"$PY" scripts/run_tests.py # 全量：自动用真实表 + 示例表
"$PY" scripts/run_tests.py --skip-real # 仅脱敏示例表（CI/无真实数据环境）
21 项用例覆盖环境/结构、parse、add_reason、docx、dashboard 全链路，全部在临时副本上运行，不碰原始文件。
Step 7: 演示与试用（脱敏示例）
examples/sample_2026年前期费用逾期情况表-示例公司.xlsx 为虚构数据示例表（结构对齐真实表），可用于演示、评估、离线测试。重新生成："$PY" scripts/make_sample.py。
新表适配流程（遇到不认识的表型时）
- 先跑解析：
parse_table.py "<新表>"→ 看表头校验 WARN - 对照告警改配置：WARN 会打印"期望 vs 实际"，据此调整
config/table-schema.json的layout（行号）和columns（列字母/关键词） - 复跑确认：直到「✓ 全部列与 schema 匹配」，之后所有步骤（加列/情况说明/看板）自动适配
> 适配原则：header/sub 用关键词（如"逾期金额"、"本金"），不用完整标题，这样年份变化、合并单元格布局微调都能容忍。
数据要点
- 金额单位：万元；回款率列（O/P/Q）为小数（0.1 = 10%，1 = 100%）
- 建议清收目标下达值通常 = 预计年底逾期金额 × 10%
- 异议原因模板：见
config/reason-templates.json（华南市场部 / 华南投资公司 / 成都汇票挪用），对话中指定 key 即可选用 - 示例数据（仅作格式参考，勿当作实时数据）：华南 2026 底预计逾期 48643.99 万（坪山共和城）等，详见 references/table-schema.md
Resources
config/table-schema.json— ★ 表结构配置（换表型只改这里）config/reason-templates.json— ★ 异议原因模板库scripts/parse_table.py— 解析逾期表为结构化数据（schema 化 + 表头校验 + JSON 落盘）scripts/add_reason_column.py— 新增"异议原因"列（schema 化）scripts/update_remark_docx.py— 情况说明.docx 插入异议表格（样式参数化）scripts/build_dashboard.py— 基于解析 JSON 生成自包含 HTML 看板scripts/run_tests.py— 一键回归测试（21 项，--skip-real 支持 CI）scripts/make_sample.py— 生成脱敏示例表examples/sample_*.xlsx— 脱敏示例表（虚构数据，可作 demo）references/table-schema.md— 默认 schema 的完整结构与列含义详解README.md/CHANGELOG.md— 发布配套（中英双语 / 变更记录；LICENSE 仅本地保留，不随包提交）
