91 lines
1.8 KiB
Markdown
91 lines
1.8 KiB
Markdown
# Digital Employee Runbook
|
|
|
|
This file is the minimal operating contract for calling `docfill` from a digital employee, scheduler, or shell script.
|
|
|
|
## Inputs
|
|
|
|
Each run needs:
|
|
|
|
- A `task.json` config file.
|
|
- A data source: `.xlsx` or SQLite `.db`.
|
|
- A template: `.docx` or `.xlsx`.
|
|
- An output path pattern in `task.json`.
|
|
|
|
Paths inside `task.json` are resolved from the config file directory.
|
|
|
|
## Command
|
|
|
|
```bash
|
|
docfill run -c /path/to/task.json --var date=2026-06-18
|
|
```
|
|
|
|
Use repeated `--var key=value` arguments for runtime values:
|
|
|
|
```bash
|
|
docfill run -c task.json --var date=2026-06-18 --var batch=早班
|
|
```
|
|
|
|
CLI variables override `vars` in `task.json`. Row data overrides both.
|
|
|
|
## Success
|
|
|
|
Exit code `0`.
|
|
|
|
Stdout contains generated files:
|
|
|
|
```text
|
|
generated 2 file(s)
|
|
- /path/to/out/report_张三.xlsx
|
|
- /path/to/out/report_李四.xlsx
|
|
```
|
|
|
|
## Failure
|
|
|
|
Exit code `1` means the task ran but failed.
|
|
|
|
Exit code `2` means the command line was invalid.
|
|
|
|
Errors are written to stderr with the `docfill:` prefix:
|
|
|
|
```text
|
|
docfill: render row 1: missing template field "done"
|
|
```
|
|
|
|
## Common Errors
|
|
|
|
`missing template field`
|
|
|
|
The template contains a `{{field}}` that is not present in data, `vars`, or CLI `--var`.
|
|
|
|
`output already exists`
|
|
|
|
The output file exists and `output.overwrite` is not `true`.
|
|
|
|
`missing sqlite params field`
|
|
|
|
A SQLite query parameter such as `{{date}}` was not provided.
|
|
|
|
`unresolved placeholder`
|
|
|
|
The rendered document still contains `{{field}}`. Check the source data value and the template.
|
|
|
|
## Build
|
|
|
|
```bash
|
|
bash scripts/build.sh
|
|
```
|
|
|
|
The local build output is:
|
|
|
|
```text
|
|
dist/docfill-darwin-arm64
|
|
```
|
|
|
|
## Smoke Test
|
|
|
|
```bash
|
|
bash scripts/smoke.sh
|
|
```
|
|
|
|
Smoke test builds a temporary binary, generates temporary example files, runs both example configs, and checks generated outputs.
|