220 lines
4.4 KiB
Markdown
220 lines
4.4 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`.
|
|
- Optional business filters in `filter.equals`.
|
|
- A template: `.docx` or `.xlsx`.
|
|
- An output path pattern in `task.json`.
|
|
|
|
Paths inside `task.json` are resolved from the config file directory.
|
|
|
|
Use one `task.json` per business task. Use `--var` for values that change per run, such as date, ticket number, person, or batch.
|
|
|
|
## 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 ticket_no=GD-002
|
|
```
|
|
|
|
Priority:
|
|
|
|
```text
|
|
row data > CLI --var > task.json vars
|
|
```
|
|
|
|
CLI variables override `vars` in `task.json`. The selected row data overrides both when rendering templates and output paths.
|
|
|
|
If `task.json` has a filter:
|
|
|
|
```json
|
|
"filter": {
|
|
"equals": {
|
|
"日期": "{{date}}",
|
|
"工单编号": "{{ticket_no}}"
|
|
},
|
|
"expect": "one"
|
|
}
|
|
```
|
|
|
|
then the command:
|
|
|
|
```bash
|
|
docfill run -c task.json --var date=2026-06-18 --var ticket_no=GD-002
|
|
```
|
|
|
|
selects the row where `日期 = 2026-06-18` and `工单编号 = GD-002`.
|
|
|
|
Use `--verbose` only when diagnosing a failed or suspicious run:
|
|
|
|
```bash
|
|
docfill run -c task.json --var date=2026-06-18 --var ticket_no=GD-002 --verbose
|
|
```
|
|
|
|
## 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: [TEMPLATE_FIELD_MISSING] render row 1: missing template field "done"
|
|
hint: Add column "done" to the data source or pass --var done=...
|
|
context: field=done template=/path/template.docx
|
|
```
|
|
|
|
Verbose logs are also written to stderr:
|
|
|
|
```text
|
|
log: load config path=/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
|
|
```
|
|
|
|
## Error Codes
|
|
|
|
`CLI_USAGE`
|
|
|
|
The command line is invalid.
|
|
|
|
`CONFIG_READ`
|
|
|
|
The config file cannot be read.
|
|
|
|
`CONFIG_PARSE`
|
|
|
|
The config file is not valid JSON.
|
|
|
|
`CONFIG_VALIDATE`
|
|
|
|
The config is missing required fields or uses unsupported values.
|
|
|
|
`DATA_EXCEL`
|
|
|
|
Excel data cannot be opened or read.
|
|
|
|
`DATA_SQLITE`
|
|
|
|
SQLite data cannot be opened, queried, or parameterized.
|
|
|
|
`DATA_EMPTY`
|
|
|
|
The data source returned no rows.
|
|
|
|
`DATA_FILTER_FIELD`
|
|
|
|
The filter references a field that is not in the data.
|
|
|
|
`DATA_FILTER_VALUE`
|
|
|
|
The filter references a variable that was not provided.
|
|
|
|
`DATA_FILTER_NO_MATCH`
|
|
|
|
The filter matched no rows.
|
|
|
|
`DATA_FILTER_MULTI_MATCH`
|
|
|
|
The filter expected one row but matched multiple rows.
|
|
|
|
`TEMPLATE_OPEN`
|
|
|
|
The template file cannot be opened or inspected.
|
|
|
|
`TEMPLATE_FIELD_MISSING`
|
|
|
|
The template references a field that is not available.
|
|
|
|
`TEMPLATE_UNRESOLVED`
|
|
|
|
The rendered file would still contain a `{{field}}` placeholder.
|
|
|
|
`OUTPUT_EXISTS`
|
|
|
|
The output file exists and overwrite is not enabled.
|
|
|
|
`OUTPUT_WRITE`
|
|
|
|
The output directory or file cannot be written.
|
|
|
|
`INTERNAL`
|
|
|
|
An unexpected unclassified error occurred.
|
|
|
|
## 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.
|
|
|
|
`filter matched no rows`
|
|
|
|
Check `filter.equals`, `--var` values, or the source table contents.
|
|
|
|
`filter matched N rows but expected one`
|
|
|
|
Add another filter condition or clean duplicate rows in the source table.
|
|
|
|
`filter field is not in data`
|
|
|
|
Check Excel headers or SQLite query column names.
|
|
|
|
`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 example configs including the filter case, and checks generated outputs.
|