# 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.