docfill

docfill 是一个最小化本地填报工具：从 Excel 或 SQLite 读取数据，把 {{字段名}} 填入 Word/Excel 模板，生成输出文件。

Build

go build -o docfill ./cmd/docfill
bash scripts/build.sh

scripts/build.sh writes the local macOS arm64 binary to dist/docfill-darwin-arm64.

Run

./docfill run --config task.json
./docfill run -c task.json --var date=2026-06-18 --var batch=早班

成功时 stdout 输出生成文件清单：

generated 2 file(s)
- /path/to/out/report_张三.xlsx
- /path/to/out/report_李四.xlsx

退出码：

0: 成功。
1: 配置、数据、模板或输出失败。
2: 命令行参数错误。

Run Case Tests

go test -run TestCase -v ./internal/docfill

当前案例覆盖：

Excel 日报数据填 Excel 模板，批量生成个人日报。
SQLite 日报数据填 Word 模板，批量生成个人日报。
SQLite 汇总数据填 Excel 模板，批量生成部门汇总表。

Smoke Test

bash scripts/smoke.sh

Smoke test 会：

跑全量 Go 测试。
构建临时 docfill 二进制。
复制 examples/ 到临时目录。
生成临时 Excel、Word、SQLite 示例数据。
执行两个示例任务并检查输出文件。

Digital Employee Runbook

给数字员工或调度脚本使用时，看：

docs/digital-employee-runbook.md

Runnable Examples

示例配置在 examples/：

examples/excel-to-word/task.json
examples/sqlite-to-excel/task.json

示例里的二进制 Office/SQLite 文件由 scripts/smoke-fixtures 临时生成，不提交到仓库。

Excel Data Example

{
  "vars": {
    "date": "2026-06-18"
  },
  "data": {
    "type": "excel",
    "path": "./data.xlsx",
    "sheet": "Sheet1",
    "header_row": 1
  },
  "template": {
    "path": "./template.docx"
  },
  "output": {
    "path": "./out/report_{{date}}_{{name}}_{{_row}}.docx",
    "overwrite": false
  }
}

Excel 第一行是字段名，后续每一行生成一个文件。

SQLite Data Example

{
  "vars": {
    "date": "2026-06-18"
  },
  "data": {
    "type": "sqlite",
    "path": "./data.db",
    "query": "select name, date, done from daily_report where date = ?",
    "params": ["{{date}}"]
  },
  "template": {
    "path": "./template.xlsx"
  },
  "output": {
    "path": "./out/report_{{name}}_{{_row}}.xlsx"
  }
}

SQL 查询结果的列名就是模板占位符字段名。

P0 Rules

配置里的相对路径按 task.json 所在目录解析。
vars 可以提供默认变量，命令行 --var key=value 会覆盖同名默认变量。
模板填充时，每行数据字段优先于 vars。
_row 是内置变量，表示当前数据行序号，从 1 开始。
SQLite params 对应 SQL 里的 ? 参数。
Excel header_row 从 1 开始，默认是 1。
默认不覆盖已有输出文件；只有 output.overwrite: true 才允许覆盖。
输出文件路径中的字段值会清理 / \ : * ? " < > |。
模板里缺字段或渲染后仍有 {{字段}}，会直接失败。
Word 模板支持同一段落内被拆开的文本占位符，例如 {{na 和 me}} 位于相邻文本节点。

MVP Limits

只支持 JSON 配置。
只支持 .xlsx 数据源、SQLite 数据源。
只支持 .docx 和 .xlsx 模板。
Word 占位符拆分只做最小兼容：支持同一段落内的文本节点拆分，不做复杂表格循环或样式级模板语法。
不做 Web、权限、审批流、模板设计器或业务系统直连。

3.5 KiB Raw Blame History Unescape Escape