# docfill

`docfill` 是一个本地文档填充命令行工具。它从 Excel 或 SQLite 读取结构化数据，按业务条件筛选出需要使用的数据行，再把数据填入 Word 或 Excel 模板中的 `{{字段名}}` 占位符。

本工具的定位是“小型、稳定、便于数字员工调用”。它只负责本地数据到本地模板的填充，不内置业务系统登录、审批流、Web 界面、模板设计器或权限系统。

## 核心理解

`task.json` 是某一种业务报表的固定任务说明书，命令行 `--var` 是本次运行传入的具体条件。

```text
不同业务 = 不同 task.json
本次运行的日期、工单编号、人员、批次 = --var
真实数据 = Excel 或 SQLite
模板文件 = Word 或 Excel
```

优先级：

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

例如 `task.json` 中写了：

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

运行时执行：

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

实际使用的是：

```text
date = 2026-06-19
ticket_no = GD-001
```

也就是 `--var date=2026-06-19` 会覆盖 `task.json` 里的默认 `date=2026-06-18`。

## 最小实践

进入仓库目录：

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

构建本机二进制：

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

输出示例：

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

运行“按日期 + 工单编号筛选一条工单并生成 Word”的测试任务：

```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
```

更多可运行案例见 [HOWTO.md](HOWTO.md) 和 [manual_tests/README.md](manual_tests/README.md)。

## 常用命令

构建：

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

运行一个任务：

```bash
dist/docfill-darwin-arm64 run -c task.json
```

运行任务并传入本次筛选条件：

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

输出诊断日志：

```bash
dist/docfill-darwin-arm64 run -c task.json --verbose
```

重新生成本地测试素材：

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

运行自动化冒烟测试：

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

运行 Go 测试：

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

## 筛选配置示例

Excel 工单表：

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

`task.json`：

```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
  }
}
```

运行：

```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.expect` 支持：

- `one`: 必须只匹配一行，适合工单、单份日报、单个报表。
- `many`: 允许匹配多行，适合按日期生成多个人或多个部门的报表。

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

## 核心规则

- 配置文件使用 JSON。
- 数据源支持 `.xlsx` 和 SQLite `.db`。
- 模板与输出支持 `.docx` 和 `.xlsx`。
- 模板占位符格式为 `{{字段名}}`。
- Excel 数据的表头行提供字段名，SQLite 查询结果的列名提供字段名。
- 常用场景是通过 `filter.equals` 先筛选数据，再填充模板。
- 多个筛选条件之间是“全部满足”关系。
- 筛选只支持等值匹配，不支持模糊匹配、范围查询、OR 或复杂表达式。
- 复杂情况建议业务人员整理 Excel，例如新增“填报批次”“业务唯一标识”等辅助列。
- `vars` 提供默认变量，命令行 `--var key=value` 可以覆盖同名变量。
- 数据行字段优先于 `vars` 和 `--var`。
- `_row` 是内置变量，表示当前输出对应的结果行序号，从 `1` 开始。
- 默认不覆盖已存在文件，只有 `output.overwrite: true` 才允许覆盖。
- 成功结果写入 stdout，诊断日志和错误写入 stderr，便于数字员工或调度脚本判断执行结果。

## 退出码

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

错误输出格式：

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

常见筛选错误：

- `DATA_FILTER_FIELD`: 筛选字段不在数据表中。
- `DATA_FILTER_VALUE`: 筛选条件引用的变量没有提供。
- `DATA_FILTER_NO_MATCH`: 没有找到符合条件的数据行。
- `DATA_FILTER_MULTI_MATCH`: 期望匹配一行，但实际匹配多行。

完整错误码、日志说明和集成建议见 [HOWTO.md](HOWTO.md)。

## 文档索引

- [HOWTO.md](HOWTO.md): 完整使用说明，包含最小实践、详细配置、输入输出示例、错误处理和数字员工调用建议。
- [manual_tests/README.md](manual_tests/README.md): 本地真实测试素材说明。
- [docs/digital-employee-runbook.md](docs/digital-employee-runbook.md): 面向数字员工或调度脚本的最小运行约定。