Word批量生成文档（通知/合同/证书） · 一份模板，生成一百份文档
HR 发续签通知、行政发培训证书、销售发报价函、项目经理发验收单——
内容只有姓名、金额、日期不同，却要复制粘贴几十上百次。
本技能把这件事变成一条命令：
Excel/CSV 数据 + DOCX 模板 → 每人一份填好的 Word。
不是“查找替换”那么简单。它会跨 run 处理被拆开的占位符，支持表格里的明细行循环、
页眉页脚同步替换、缺失字段报告、文件名规则与重复名避让，并保留模板原有格式。
适合谁
- HR / 行政：续签通知、劳动合同、培训证书、在职证明。
- 销售 / 商务：报价函、授权书、验收单、客户通知。
- 任何“一人一份、内容只差几个字段”的批量文书场景。
何时使用
- 一份合同/通知/证书模板，要按名单批量生成，每人一份。
- 正文里有一张费用明细/商品清单表，需要按每个人的多条明细自动展开行。
- 页眉里要写每份文档对应的公司/项目名称。
- 生成后要拿到一份清单：哪些成功、哪些缺字段、文件在哪。
不适用：扫描件 OCR、PDF 填表、复杂条件排版（if/else 模板语法）、
保留 Word 修订/批注的合并、把多份文档再合并成一个 Word。
复杂版式建议先在 Word 里做好模板，再用占位符替换。
怎么用
# 1) 内置样例：合同续签通知（含明细表循环、页眉替换）
python3 scripts/word_batch.py --sample --out-dir 批量样例
# 2) 基础用法：数据表 + 模板
python3 scripts/word_batch.py 名单.xlsx 通知模板.docx \
--out-dir 生成结果 --name-template "{序号}_{姓名}_续签通知.docx"
# 3) 带明细表：主表按合同编号关联明细表
python3 scripts/word_batch.py 合同清单.xlsx 合同模板.docx \
--items 费用明细.xlsx --data-key 合同编号 --items-key 合同编号 \
--out-dir 合同输出
# 4) 缺失字段写成【待补：字段】，而不是留空
python3 scripts/word_batch.py 名单.csv 证书模板.docx --mark-missing --out-dir 证书
# 5) 只校验模板字段和数据，不生成文件
python3 scripts/word_batch.py 名单.csv 模板.docx --dry-run
在对话里可以直接说：「用这份名单批量生成 Word 通知，每人一份」，并给出模板和数据文件。
模板怎么写
在 Word 里正常排版，把要替换的地方写成双花括号：
| 模板写法 | 作用 |
|---|---|
{{姓名}} |
替换为主表「姓名」列的值 |
{{合同编号}} |
列名就是占位符名，支持中文 |
{{items.项目名称}} |
在明细循环里取明细字段（也支持直接写 {{项目名称}}） |
{{#items}} ... {{/items}} |
表格行循环；同一行内同时放开始和结束标记 |
{{日期}} |
页眉/页脚里也会替换 |
明细循环示例（Word 表格里放两行）：
| 项目 | 金额 |
|---|---|
{{#items}}{{项目名称}} |
{{金额}}{{/items}} |
生成时，这一行会按该合同在明细表里的记录数复制；没有明细时整行删除。
输出
| 文件 | 内容 |
|---|---|
每个数据行一份 .docx |
按 --name-template 命名，默认 {序号}_{第一列}.docx |
生成清单.csv |
序号 / 输出文件 / 状态 / 缺失字段 |
生成汇总.md |
生成数量、跳过/失败、模板里有但数据没有的字段 |
安全与边界
- 纯标准库 Python，本地运行，不联网、不上传、不依赖 Word / python-docx。
- 只读取模板和数据，只写入
--out-dir；不改模板和源数据。 - 默认跳过已存在的同名输出；确认覆盖时加
--force。 - 占位符被 Word 拆成多个 run 也能替换；替换文本沿用占位符起始处的格式。
- 只支持“同行内”的表格行循环；跨多行的循环块不处理，会保留原样并提示。
- 复杂域代码、SmartArt、图表内的文字不替换；建议先在 Word 里转成普通文本。
