# docfill HOWTO

本文档说明如何使用 `docfill` 完成本地文档自动填充。文档分为两部分：

- “最小实践”用于快速完成一次可验证运行。
- “详细说明”用于理解任务配置、运行变量、筛选、模板、输出、错误和日志。

## 一、最小实践

### 1. 进入项目目录

```bash
cd /Users/zhaoyilun/Documents/xls_doc
```

### 2. 构建命令行工具

```bash
bash scripts/build.sh
```

输出示例：

```text
/Users/zhaoyilun/Documents/xls_doc/dist/docfill-darwin-arm64
```

构建后的可执行文件是：

```text
dist/docfill-darwin-arm64
```

### 3. 准备测试素材

仓库中已经包含 `manual_tests/` 测试素材。如果需要重新生成，可执行：

```bash
/Users/zhaoyilun/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3 scripts/make-manual-test-materials.py
```

输出示例：

```text
/Users/zhaoyilun/Documents/xls_doc/manual_tests
```

测试素材包含四类任务：

- `manual_tests/01_excel_to_word`: Excel 源数据生成 Word 日报。
- `manual_tests/02_sqlite_to_excel`: SQLite 源数据生成 Excel 汇总表。
- `manual_tests/03_excel_to_excel`: Excel 源数据生成 Excel 质检表。
- `manual_tests/04_filter_work_order_to_word`: 按日期和工单编号筛选一条工单，再生成 Word。

### 4. 运行筛选工单案例

命令：

```bash
dist/docfill-darwin-arm64 run -c manual_tests/04_filter_work_order_to_word/task.json --var date=2026-06-18 --var ticket_no=GD-002 --verbose
```

输出示例：

```text
log: load config path=manual_tests/04_filter_work_order_to_word/task.json
log: read data type=excel path=/Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/source_work_orders.xlsx
log: read data type=excel path=/Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/source_work_orders.xlsx rows=3
log: filter rows=3 matched=1 expect=one
log: render row=1 output=/Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/out/work_order_2026-06-18_GD-002.docx
generated 1 file(s)
- /Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/out/work_order_2026-06-18_GD-002.docx
```

查看输出目录：

```bash
open manual_tests/04_filter_work_order_to_word/out
```

输入 Excel 内容示例：

```text
日期          工单编号   客户名称  系统来源   处理结果  下一步
2026-06-18   GD-001    A 公司   PMS3.0   已派单   等待现场反馈
2026-06-18   GD-002    B 公司   D5000    已完成   归档并同步日报
2026-06-19   GD-001    C 公司   风控平台  待复核   补充截图
```

本次命令传入：

```text
date = 2026-06-18
ticket_no = GD-002
```

所以工具会筛选：

```text
日期 = 2026-06-18，并且 工单编号 = GD-002
```

最终只生成 `GD-002` 对应的 Word 文件。

## 二、详细说明

### 1. task.json 与 --var 的关系

`task.json` 是某一种业务报表的固定任务说明书。它通常由开发人员或维护人员准备好，普通运行时不需要频繁修改。

命令行 `--var` 是本次运行传入的具体条件，例如日期、工单编号、人员、批次。

可以这样理解：

```text
不同业务 = 不同 task.json
本次运行的具体条件 = --var
真实业务数据 = Excel 或 SQLite
输出模板 = Word 或 Excel
```

例如不同业务可以分别维护：

```text
工单日报.json
部门汇总.json
质检报告.json
```

运行时只传本次变化的信息：

```bash
dist/docfill-darwin-arm64 run -c 工单日报.json --var date=2026-06-18 --var ticket_no=GD-002
```

变量优先级：

```text
数据表里的字段 > 命令行 --var > task.json 里的 vars
```

示例：

```json
"vars": {
  "date": "2026-06-18"
}
```

如果运行时执行：

```bash
dist/docfill-darwin-arm64 run -c task.json --var date=2026-06-19
```

实际使用的是：

```text
date = 2026-06-19
```

也就是命令行 `--var` 会覆盖 `task.json` 中的同名默认变量。

### 2. 命令格式

`docfill` 当前只提供一个核心命令：

```bash
dist/docfill-darwin-arm64 run -c <task.json> [--var key=value] [--verbose]
```

参数说明：

| 参数 | 作用 | 示例 |
| --- | --- | --- |
| `run` | 执行一次填充任务 | `dist/docfill-darwin-arm64 run -c task.json` |
| `-c` | 指定任务配置文件 | `-c manual_tests/04_filter_work_order_to_word/task.json` |
| `--config` | `-c` 的完整写法 | `--config task.json` |
| `--var` | 传入运行时变量，可以重复使用 | `--var date=2026-06-18 --var ticket_no=GD-002` |
| `--verbose` | 输出诊断日志到 stderr | `--verbose` |

命令行参数错误示例：

```bash
dist/docfill-darwin-arm64 run --var date
```

输出示例：

```text
docfill: [CLI_USAGE] invalid value "date" for flag -var: invalid --var "date", want key=value
hint: Check command flags and use key=value for --var.
```

### 3. 任务配置结构

典型的筛选任务配置如下：

```json
{
  "vars": {
    "date": "2026-06-18"
  },
  "data": {
    "type": "excel",
    "path": "./source_work_orders.xlsx",
    "sheet": "工单",
    "header_row": 1
  },
  "filter": {
    "equals": {
      "日期": "{{date}}",
      "工单编号": "{{ticket_no}}"
    },
    "expect": "one"
  },
  "template": {
    "path": "./work_order_template.docx"
  },
  "output": {
    "path": "./out/work_order_{{日期}}_{{工单编号}}.docx",
    "overwrite": true
  }
}
```

配置字段说明：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `vars` | 否 | 默认变量。适合放日期、批次、班次等默认值。 |
| `data.type` | 是 | 数据源类型。支持 `excel`、`xlsx`、`sqlite`。 |
| `data.path` | 是 | 数据源路径。支持 `.xlsx` 或 SQLite `.db`。 |
| `data.sheet` | Excel 可选 | Excel 工作表名称。未填写时读取第一个工作表。 |
| `data.header_row` | Excel 可选 | Excel 表头行号，从 `1` 开始。未填写时默认为 `1`。 |
| `data.query` | SQLite 必填 | SQLite 查询语句。查询结果列名作为字段名。 |
| `data.params` | SQLite 可选 | SQL `?` 参数列表，支持 `{{变量名}}`。 |
| `filter.equals` | 否 | 等值筛选条件。左侧是数据字段，右侧是匹配值。 |
| `filter.expect` | 否 | 筛选结果数量要求。支持 `one`、`many`，默认 `one`。 |
| `template.path` | 是 | Word 或 Excel 模板路径。支持 `.docx`、`.xlsx`。 |
| `output.path` | 是 | 输出文件路径模板。可以使用 `{{字段名}}`。 |
| `output.overwrite` | 否 | 是否覆盖已存在文件。默认是 `false`。 |

相对路径规则：

```text
task.json 所在目录就是相对路径的基准目录。
```

### 4. 业务筛选 filter

`filter` 的作用是从数据表中筛选出本次要使用的数据行。它的目标不是提供数据库查询能力，而是提供符合表格使用习惯的简单筛选。

配置示例：

```json
"filter": {
  "equals": {
    "日期": "{{date}}",
    "工单编号": "{{ticket_no}}"
  },
  "expect": "one"
}
```

含义：

```text
找到 日期 等于 date，并且 工单编号 等于 ticket_no 的数据行。
```

命令：

```bash
dist/docfill-darwin-arm64 run -c task.json --var date=2026-06-18 --var ticket_no=GD-002
```

实际筛选：

```text
日期 = 2026-06-18
工单编号 = GD-002
```

筛选规则：

- `filter.equals` 左侧必须是 Excel 表头或 SQLite 查询结果列名。
- `filter.equals` 右侧可以写固定值，也可以写 `{{变量名}}`。
- 多个条件之间是“全部满足”关系。
- 比较前会去掉单元格值和筛选值两侧的空格。
- 只支持等值匹配。
- 不支持模糊匹配、范围查询、OR、排序表达式或复杂条件。

`filter.expect` 支持两个值：

| 值 | 含义 | 适用场景 |
| --- | --- | --- |
| `one` | 必须只匹配一行 | 工单、单份日报、单个报表。 |
| `many` | 允许匹配多行 | 按日期批量生成多个人或多个部门的报表。 |

未填写 `filter.expect` 时，默认按 `one` 处理。

如果没有配置 `filter`，工具会沿用旧行为：读取到的每一行都会生成一个输出文件。

复杂情况的处理建议：

- 如果多个字段才能确定一条数据，就在 `filter.equals` 中写多个条件。
- 如果表格本身不容易筛选，建议在 Excel 中新增辅助列，例如 `填报批次`、`业务唯一标识`、`筛选日期`。
- 不建议把复杂业务规则写进 `docfill`，复杂规则应在数据准备阶段完成。

### 5. Excel 数据源

Excel 数据源配置示例：

```json
{
  "data": {
    "type": "excel",
    "path": "./source_work_orders.xlsx",
    "sheet": "工单",
    "header_row": 1
  }
}
```

运行示例：

```bash
dist/docfill-darwin-arm64 run -c manual_tests/04_filter_work_order_to_word/task.json --var date=2026-06-18 --var ticket_no=GD-002
```

Excel 读取规则：

- `header_row` 指定表头行，表头单元格内容就是字段名。
- 表头下方的每一行是候选数据。
- 配置了 `filter` 时，先筛选，再生成输出。
- 未配置 `filter` 时，每一行都会生成一个输出文件。
- 空行会被跳过。
- 空表头列会被忽略。

表头在第 1 行的输入示例：

```text
日期          工单编号   客户名称  系统来源   处理结果  下一步
2026-06-18   GD-001    A 公司   PMS3.0   已派单   等待现场反馈
2026-06-18   GD-002    B 公司   D5000    已完成   归档并同步日报
2026-06-19   GD-001    C 公司   风控平台  待复核   补充截图
```

表头在第 2 行的配置示例：

```json
{
  "data": {
    "type": "excel",
    "path": "./source_audit_data.xlsx",
    "sheet": "Audit",
    "header_row": 2
  }
}
```

对应输入示例：

```text
日报质检导出

employee  date        item        score  comment
王五       2026-06-18  日报完整性    92     字段齐全，说明清楚
赵六       2026-06-18  系统截图一致性  87     缺少 1 张截图，需要补充
```

### 6. SQLite 数据源

SQLite 数据源配置示例：

```json
{
  "vars": {
    "date": "2026-06-18"
  },
  "data": {
    "type": "sqlite",
    "path": "./source_summary.db",
    "query": "select department, report_date, total_count, abnormal_count, owner from department_summary order by department",
    "params": []
  },
  "filter": {
    "equals": {
      "report_date": "{{date}}"
    },
    "expect": "many"
  }
}
```

运行示例：

```bash
dist/docfill-darwin-arm64 run -c manual_tests/02_sqlite_to_excel/task.json --var date=2026-06-18
```

SQLite 读取规则：

- `data.query` 的查询结果列名就是模板字段名。
- `data.params` 按顺序对应 SQL 中的 `?`。
- `data.params` 可以引用 `vars` 或命令行 `--var`。
- 配置了 `filter` 时，SQL 查询结果还会再经过业务筛选。
- 查询结果的每一行或筛选后的每一行生成一个输出文件。

输入数据示例：

```text
department  report_date  total_count  abnormal_count  owner
营销部        2026-06-17   115          2               张三
客服部        2026-06-18   76           0               李四
营销部        2026-06-18   128          3               张三
```

SQLite 可以继续使用 SQL 参数：

```json
"data": {
  "type": "sqlite",
  "path": "./source_summary.db",
  "query": "select department, report_date, total_count, abnormal_count, owner from department_summary where report_date = ? order by department",
  "params": ["{{date}}"]
}
```

这适合由开发人员维护的 SQLite 数据源。面向表格使用习惯时，优先使用 `filter.equals` 表达业务筛选。

### 7. Word 模板

Word 模板使用 `.docx` 文件，模板中写入 `{{字段名}}`：

```text
日期：{{日期}}
工单编号：{{工单编号}}
客户名称：{{客户名称}}
系统来源：{{系统来源}}
处理结果：{{处理结果}}
下一步：{{下一步}}
```

运行示例：

```bash
dist/docfill-darwin-arm64 run -c manual_tests/04_filter_work_order_to_word/task.json --var date=2026-06-18 --var ticket_no=GD-002
```

生成结果示例：

```text
日期：2026-06-18
工单编号：GD-002
客户名称：B 公司
系统来源：D5000
处理结果：已完成
下一步：归档并同步日报
```

Word 支持同一段落内被 Word 拆分的文本占位符。例如模板内部可能把 `{{name}}` 拆成相邻文本节点 `{{na` 和 `me}}`，工具会按同一段落进行最小兼容处理。

这种兼容会把同一段落内的拆分文本合并后再写回，渲染结果会写入该段落第一个文本节点的位置，后续拆分节点的独立格式不再体现。建议模板中每个占位符使用同一种字体、颜色和加粗状态，不要在 `{{`、字段名、`}}` 之间混用格式。

当前不支持复杂模板语法，例如表格循环、条件判断、图片插入、跨段落拼接占位符。

### 8. Excel 模板

Excel 模板使用 `.xlsx` 文件，单元格中写入 `{{字段名}}`：

```text
B2: {{department}}
B3: {{report_date}}
B4: {{owner}}
B5: {{total_count}}
B6: {{abnormal_count}}
```

运行示例：

```bash
dist/docfill-darwin-arm64 run -c manual_tests/02_sqlite_to_excel/task.json --var date=2026-06-18
```

生成结果示例：

```text
B2: 营销部
B3: 2026-06-18
B4: 张三
B5: 128
B6: 3
```

Excel 模板会遍历所有工作表，替换单元格文本中的占位符。当前不支持公式重算、透视表刷新、复杂样式模板语法。

### 9. 输出路径

输出路径可以使用字段占位符：

```json
{
  "output": {
    "path": "./out/work_order_{{日期}}_{{工单编号}}.docx",
    "overwrite": true
  }
}
```

运行示例：

```bash
dist/docfill-darwin-arm64 run -c manual_tests/04_filter_work_order_to_word/task.json --var date=2026-06-18 --var ticket_no=GD-002
```

输出文件示例：

```text
work_order_2026-06-18_GD-002.docx
```

文件名清理规则：

```text
/ \ : * ? " < > |
```

以上字符会在输出路径字段值中替换为 `_`。例如：

```text
张三/测试 -> 张三_测试
```

覆盖规则：

- `output.overwrite` 未设置或为 `false` 时，输出文件已存在会失败。
- `output.overwrite` 为 `true` 时，允许覆盖同名输出文件。

### 10. 日志、标准输出和退出码

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

```text
generated 1 file(s)
- /path/to/out/work_order_2026-06-18_GD-002.docx
```

启用 `--verbose` 后，stderr 输出诊断日志：

```text
log: load config path=task.json
log: read data type=excel path=/path/data.xlsx
log: read data type=excel path=/path/data.xlsx rows=3
log: filter rows=3 matched=1 expect=one
log: render row=1 output=/path/out/work_order_2026-06-18_GD-002.docx
```

退出码：

| 退出码 | 含义 | 适用场景 |
| --- | --- | --- |
| `0` | 成功 | 可以读取 stdout 中的生成文件清单。 |
| `1` | 执行失败 | 配置、数据、模板、输出等处理失败。 |
| `2` | 命令行错误 | 参数缺失、命令错误、`--var` 格式错误。 |

数字员工或调度脚本建议：

- 判断退出码确认任务是否成功。
- 成功时读取 stdout 获取生成文件路径。
- 失败时记录 stderr，用于定位错误码、提示和上下文。
- 仅在诊断或审计时启用 `--verbose`。

### 11. 错误格式与错误码

错误输出格式：

```text
docfill: [ERROR_CODE] message
hint: repair suggestion
context: key=value
```

配置文件不存在示例：

```bash
dist/docfill-darwin-arm64 run -c manual_tests/not-exist.json
```

输出示例：

```text
docfill: [CONFIG_READ] read config: open manual_tests/not-exist.json: no such file or directory
hint: Check that the config file exists and is readable.
context: config=manual_tests/not-exist.json
```

筛选无匹配示例：

```bash
dist/docfill-darwin-arm64 run -c manual_tests/04_filter_work_order_to_word/task.json --var date=2026-06-18 --var ticket_no=GD-999 --verbose
```

输出示例：

```text
log: load config path=manual_tests/04_filter_work_order_to_word/task.json
log: read data type=excel path=/Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/source_work_orders.xlsx
log: read data type=excel path=/Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/source_work_orders.xlsx rows=3
docfill: [DATA_FILTER_NO_MATCH] filter matched no rows
hint: Check filter.equals, --var values, or source table contents.
context: expect=one filter=工单编号=GD-999,日期=2026-06-18
```

错误码说明：

| 错误码 | 含义 | 常见处理方式 |
| --- | --- | --- |
| `CLI_USAGE` | 命令行参数错误 | 检查命令、`-c`、`--var key=value`。 |
| `CONFIG_READ` | 配置文件读取失败 | 检查路径、文件是否存在、读权限。 |
| `CONFIG_PARSE` | 配置 JSON 解析失败 | 检查 JSON 语法。 |
| `CONFIG_VALIDATE` | 配置字段缺失或不支持 | 检查 `data.type`、`data.path`、`template.path`、`output.path`、`filter.expect`。 |
| `DATA_EXCEL` | Excel 数据读取失败 | 检查 `.xlsx` 文件、工作表名、表头行。 |
| `DATA_SQLITE` | SQLite 数据读取或查询失败 | 检查 `.db` 文件、SQL、参数。 |
| `DATA_EMPTY` | 数据源没有返回可生成的数据行 | 检查源数据是否为空。 |
| `DATA_FILTER_FIELD` | 筛选字段不在数据中 | 检查 Excel 表头或 SQLite 查询列名。 |
| `DATA_FILTER_VALUE` | 筛选条件引用的变量没有提供 | 补充 `--var` 或 `vars`。 |
| `DATA_FILTER_NO_MATCH` | 筛选后没有符合条件的数据行 | 检查筛选条件，或整理源表。 |
| `DATA_FILTER_MULTI_MATCH` | 期望一行但匹配多行 | 增加筛选条件，或整理重复数据。 |
| `TEMPLATE_OPEN` | 模板读取失败 | 检查模板路径和文件格式。 |
| `TEMPLATE_FIELD_MISSING` | 模板字段缺失 | 在数据源、`vars` 或 `--var` 中补充字段。 |
| `TEMPLATE_UNRESOLVED` | 渲染后仍残留占位符 | 检查模板占位符拼写和字段值。 |
| `OUTPUT_EXISTS` | 输出文件已存在 | 修改输出路径或设置 `output.overwrite: true`。 |
| `OUTPUT_WRITE` | 输出写入失败 | 检查输出目录权限、文件占用状态。 |
| `INTERNAL` | 未分类内部错误 | 保留 stderr 和输入文件，开启 `--verbose` 复现。 |

### 12. 自动化调用示例

以下示例展示数字员工或调度脚本如何调用 `docfill`。该脚本只做最小封装，不承担模板解析或业务逻辑。

```bash
#!/usr/bin/env bash
set -euo pipefail

DOCFILL="/Users/zhaoyilun/Documents/xls_doc/dist/docfill-darwin-arm64"
CONFIG="/Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/task.json"
DATE="${1:?date is required, example: 2026-06-18}"
TICKET_NO="${2:?ticket_no is required, example: GD-002}"

"$DOCFILL" run -c "$CONFIG" --var date="$DATE" --var ticket_no="$TICKET_NO" --verbose
```

执行：

```bash
bash run-docfill.sh 2026-06-18 GD-002
```

预期结果：

```text
generated 1 file(s)
- /Users/zhaoyilun/Documents/xls_doc/manual_tests/04_filter_work_order_to_word/out/work_order_2026-06-18_GD-002.docx
```

集成建议：

- 把业务系统接口采集结果先落成 Excel 或 SQLite。
- 为每类报表维护一个 `task.json`。
- 数字员工只负责准备运行变量并执行命令。
- 复杂筛选优先通过整理 Excel 表解决，例如新增辅助列。
- 不要把账号密码、审批状态、业务系统访问逻辑写入 `docfill` 配置。

### 13. 开发与验证

运行全部 Go 测试：

```bash
go test -count=1 ./...
```

运行冒烟测试：

```bash
bash scripts/smoke.sh
```

构建发布用本机二进制：

```bash
bash scripts/build.sh
```

重新生成手工测试素材：

```bash
/Users/zhaoyilun/.cache/codex-runtimes/codex-primary-runtime/dependencies/python/bin/python3 scripts/make-manual-test-materials.py
```

冒烟测试覆盖内容：

- Go 单元测试。
- 临时构建 `docfill`。
- 生成临时 Excel、Word、SQLite 示例数据。
- 执行无筛选 Excel 到 Word 示例。
- 执行筛选 Excel 到 Word 示例。
- 执行 SQLite 到 Excel 示例。
- 检查输出文件是否生成。

### 14. 当前边界

为了保持工具小型、稳定、便于自动化调用，当前明确不包含以下能力：

- 不提供 Web 界面。
- 不提供模板设计器。
- 不直接登录业务系统。
- 不管理账号、密码或权限。
- 不实现审批流。
- 不实现 Word 表格循环或条件语法。
- 不实现 Excel 公式重算和透视表刷新。
- 不实现复杂筛选语法。
- 不实现复杂任务编排。

如需扩展，应优先通过外部脚本准备数据，再交给 `docfill` 执行单次文档填充。