# docfill

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

## Build

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

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

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

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

退出码：

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

## Run Case Tests

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

当前案例覆盖：

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

## Smoke Test

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

```json
{
  "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

```json
{
  "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、权限、审批流、模板设计器或业务系统直连。