145 lines
3.5 KiB
Markdown
145 lines
3.5 KiB
Markdown
# 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、权限、审批流、模板设计器或业务系统直连。
|