feat: add docfill mvp cli

README.md

@@ -0,0 +1,144 @@
+# 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、权限、审批流、模板设计器或业务系统直连。