中职国家助学金材料批量整理
Overview
把"读本地 Excel/Word 材料 → 解析精准库标签与学籍异动 → 批量填表"这一套班主任每年都要做的
重复劳动，固化成一个可复用的 Skill。核心交付是一个 Python 引擎 scripts/prepare.py，
配合两份学校下发的申请表模板，自动产出每个学生/每班的全部助学金申报材料。
适用对象：中职学校班主任、资助经办人。默认适配广西中医药大学附设中医学校（广西中医学校）
药学/中医康复技术专业的 24（10）、24（15）班场景；模板与列名可换，引擎按表头关键词
自动定位列，换年级/换班级只需改参数。
When to use
- 用户说"帮我整理/生成/批量做助学金材料""把受助学生的表都填了""按学号表把异动的踢掉"等。
- 用户已把以下材料放进一个工作文件夹：助学金类型表(xlsx)、各班学号表(xlsx)、
学生基本信息表(xlsx)、精准库(xls)、两份申请表填写模板(docx)。 - 需要每年复用时，直接重跑引擎，仅数据源更新。
Workflow（标准流程）
- 核对材料齐全：确认工作文件夹含本 Skill「业务口径」所列 6 类文件；模板为
*认定申请表*填写模板*.docx与*助学金申请表*填写模板*.docx。 - 准备 Python 环境（首次）：用 managed python 建 venv 并装依赖：
<managed_python> -m venv <venv> <venv>/Scripts/pip install openpyxl python-docx xlrd
managed python 路径：C:\Users\Administrator\.workbuddy\binaries\python\versions\3.13.12\python.exe - 先 dry-run 核对口径：
<venv>/Scripts/python <skill>/scripts/prepare.py --workspace "<材料文件夹>" --dry-run
检查各班人数、连片人数、异动剔除人数是否与学号表一致。 - 正式生成：去掉
--dry-run，输出到工作文件夹下的班别班助学金材料/。 - 人工核对（必做）：逐班打开评议报告与汇总表，确认留空项、评议小组、连片勾选、
档次无误；详见references/business-rules.md的"待人工核对疑点"。
引擎参数（scripts/prepare.py）
| 参数 | 说明 | 默认 |
|---|---|---|
--workspace |
材料所在文件夹（必填） | — |
--out |
输出文件夹 | 同 workspace |
--classes |
班级列表，如 24（10） 24（15） |
24（10） 24（15） |
--type/--info/--prec/--rd/--zxj |
显式指定某输入文件 | 按通配符自动识别 |
--dry-run |
只打印计划不落盘 | 关 |
所有输入文件均按通配符自动识别；文件名变化时用显式参数覆盖。
关键实现要点（给维护者）
- 列定位靠表头关键词，不靠绝对列号；10班与15班学号表结构不同也能兼容。
- 连片判定以精准库「一般困难（连片地区）」sheet 的身份证为准（权威），不硬编码县区名单。
- 异动剔除按列分别判定：主表「备注」列命中的剔主表身份证；右侧异动子表的
「变动类型/异动理由」列命中的剔子表身份证——避免误伤主表同行学生（这是 2026 年首版踩过的坑）。 - 勾选框：
mark()做字符级精确勾选，勾选结果统一为单字符已勾选方框☑（U+2611），
绝不是√□双字符，也绝不保留原空框再在前面叠一个☑（旧实现会在旧空框前多插一个√/☑，已废弃）： - 选项前已有普通 Unicode 占位符
□/○/◯/▢/☐（BOX常量）→ 把该占位符替换为单字符☑
（如□特别困难→☑特别困难）； - 选项前是 Word 符号域
<w:sym font="Wingdings 2" char="00A3/F0A3/0052"/>空框
（在run.text里看不见）→ 删除该空框符号域并插入☑run 替代
（如[w:sym空框] 涉农→☑ 涉农），绝不能保留原空框再在前面加☑； - 选项前无任何占位符 → 直接在选项文字前插入单字符
☑； - 已勾选（前导已是
☑）则跳过，防止重复打勾。 - 注意：模板申请书 R14、认定表 R4 的说明句本身含有
打"√"字样（如"如实在相应类型□中打"√""），
那是模板说明文字，与勾选框无关，引擎只动选项前的占位符，不要误删说明句里的√。
旧实现"整段 run 前插 √"、"√ 加占位符"或"不删空框只在前方叠 ☑"都会导致勾错选项、浮出孤立√或出现□☑双框，已废弃。 - 两套模板措辞必须分别匹配：
parse_tags()返回的rd（认定表困难类型）与zxj
（助学金表 R14 申请理由）措辞不同（如认定表"最低生活保障家庭学生" / 助学金表
"城乡低保家庭学生"）。务必分别匹配各自模板原文，否则勾选框会对不上——这是 2026 年首版
一个隐藏 bug（低保学生助学金表申请理由从未被勾选），已修正。 - 专业名称只保留纯专业名：
s["major"]数据源形如2024级药剂15班，写入申请表时
必须去掉2024级前缀与末尾15班班号，只留药剂/中医康复技术等纯专业名
（落到 C(1,2) 与 C(2,2) 两个"专业名称"单元格）。不要出现2024级…班这类完整字眼。 - 初审意见 R16 与 学校审核意见 R17 都必须保留模板自带空格：两处模板原文分别为
…拟同意其享受（空格）等中职国家助学金补助。与…同意该生享受（空格）等中职国家助学金补助。
那 5 个空格是供评审人手写档次（一/二/三）的，引擎一律不得自动填入"一等/二等/三等"，也不要覆盖这两个单元格
——直接保留模板空白即可。两者空格字符数必须一致（现行模板均 5 个；实测 57 份全部一致）。
这是用户 2026-09-17 明确要求：档次不能在打印前写死，两个意见栏留白要一模一样。
（历史上曾误用re.sub把空格替换成一等等，已废弃；fill_level_in_opinion()因此默认不接进fill_zxj，仅作工具保留。） - 留空不编造：家庭人口/家长/收入/住房/银行卡/评议日期/签名等数据源没有的字段一律留空。
- 困难类型与申请理由由四库标签推导，映射表见
references/business-rules.md。
补充字段填写规则（2026-09 增补）
以下字段由「学生基本信息表」驱动，落在两份申请表中，单元格坐标以学校现行模板为准：
| 目标 | 位置 | 取值 |
|---|---|---|
| 家庭住址 | 助学金表 C(4,2) |
户口所在地 + 户口所在地区县以下详细地址 直接拼接 |
| 户籍性质 | 认定表 C(5,3) |
户口性质 含"非农业"→勾 城镇；含"农业"→勾 农村 |
| 户籍所在地 | 认定表 C(5,5) |
户口所在地（含省/市/县即可，不拼县级以下） |
| 家庭居住现居住地址 | 认定表 C(7,3) |
与"家庭住址"同源，直接套用合并后的地址 |
| 申请人承诺签章 | 认定表 C(18,7) |
把 本人是 学生 的空格替换为 本人是{姓名}学生 |
| 学校审核意见 | 助学金表 C(17,1) |
保留模板空格，不填档次（与初审意见留白一致，供手写一/二/三等） |
| 学校审核意见 | 认定表 C(20,1) |
勾 符合 + 勾困难类型（特别困难/比较困难/一般困难/不困难） |
关键坑位（都是踩过的）：
户口所在地区县以下详细地址列的定位不能用"县级以下"子串。表头实际写作
户口所在地区县以下详细地址（是"区县"不是"区级县"），"县级以下"不是它的子串，会静默定位失败
→ 家庭住址只剩到县一级、丢掉镇村门牌。必须用"县以下"定位。
同理不能用"户口所在地"定位，那会命中前面的省/市/县列。- 学校审核意见
享受 等的空格与等常分属不同 run
（实测R0="…同意该生享受"/R1=" "/R2="等中职…"）。
只写re.sub(r"\s+等", level+"等", run.text)在等所在 run 上匹配不到（该 run 里等在开头、前面无空格），
结果是空格被删而档次没填进去，变成"享受等"。必须处理跨 run：向前清掉纯空格 run
并rstrip前一个 run 尾部，再在等前加档次——见fill_level_in_opinion()。
⚠️ 该函数当前默认不调用（R16/R17 都要留空供手写），改引擎时不要顺手接回去；
另外一旦动过该单元格又想还原，务必重新从模板生成，否则空格删了就回不来。 - 承诺栏
本人是{姓名}学生只改本人是与学生之间的空白，
学生之后的（□父亲□母亲□监护人）是待家长手勾的项，绝不能被覆盖或删掉。
版式硬约束（务必遵守）
- 申请表必须正反面打印在一张纸上，即每份 docx 严格 ≤ 2 页。
- 学校现行模板本身就是 2 页，填字段不会撑破版式；但每次改引擎后必须抽验页数，
确认仍为 2 页再交付。 - 抽验方法（Windows + Word，走 COM，编码安全）：
$w = New-Object -ComObject Word.Application; $w.Visible = $false $doc = $w.Documents.Open($f.FullName, $false, $true) $doc.Repaginate(); $pages = $doc.ComputeStatistics(2) # wdStatisticPages = 2
结果用[System.IO.File]::WriteAllText(..., [System.Text.UTF8Encoding]::new($true))落盘再读
（PowerShell 直接回显 stdout 常为空且中文易乱码）。 - 若确实超页，优先缩页边距/行距，不要删减必填字段或勾选框。
输出结构
<workspace>/
24（10）班助学金材料/
24（10）231010043张三广西壮族自治区家庭经济困难学生认定申请表.docx
24（10）231010043张三广西中等职业教育国家助学金申请表.docx
...（非连片学生两份，连片学生仅助学金表）
24（10）班2026年助学金班级民主评议结果报告.docx
24（10）班助学金汇总表2026年.xlsx
24（15）班助学金材料/
...（同上）
参考资料
references/business-rules.md：完整业务口径、字段映射、连片/异动/档次规则、待核对疑点。scripts/prepare.py：全部生成逻辑。scripts/requirements.txt：依赖清单。
