# docfill 全方位评测报告

评测日期：2026-06-19

评测对象：`docfill` 当前工作区版本，包含错误码、日志、业务筛选 `filter.equals`、手工测试素材和用户文档更新。

## 结论

本轮评测结论：通过当前 MVP 质量门槛。

适用范围：

- 本地 macOS arm64 构建。
- Excel / SQLite 数据源读取。
- Word / Excel 模板填充。
- `filter.equals` 多条件等值筛选。
- `filter.expect` 的 `one` / `many` 行数约束。
- CLI 成功输出、错误码、提示和上下文。
- 用户文档、示例配置和手工测试素材一致性。

未宣称覆盖：

- Windows / Linux 二进制构建。
- 大体量数据性能测试。
- Excel 公式重算、透视表刷新。
- 复杂 Word 模板语法。
- 业务系统直连、权限、审批或调度系统。

## 工作区状态

当前工作区包含未提交变更，评测没有执行提交、回滚或清理。

基线提交：

```text
ca444bd feat: add docfill mvp cli
```

评测时存在的主要变更类型：

- CLI 错误码和日志。
- `filter.equals` / `filter.expect` 筛选能力。
- 新增 `HOWTO.md`。
- 新增 `manual_tests/` 真实测试素材。
- 新增 `examples/excel-filter-to-word/` smoke 示例。
- 更新 README、runbook 和示例文档。

## 自动化评测

| 项目 | 命令 | 结果 |
| --- | --- | --- |
| Git diff 格式检查 | `git diff --check` | 通过，无输出 |
| Go 单元测试 | `go test -count=1 ./...` | 通过 |
| Go race 测试 | `go test -race -count=1 ./...` | 通过 |
| Go 静态检查 | `go vet ./...` | 通过，无输出 |
| 本机构建 | `bash scripts/build.sh` | 通过，输出 `dist/docfill-darwin-arm64` |
| 冒烟测试 | `bash scripts/smoke.sh` | 通过，包含无筛选、筛选、SQLite 示例 |

`bash scripts/smoke.sh` 覆盖：

- Excel 到 Word：生成 2 个日报 Word 文件。
- Excel 筛选到 Word：按 `date + ticket_no` 生成 1 个工单 Word 文件。
- SQLite 到 Excel：生成 2 个部门汇总 Excel 文件。

## 真实素材成功路径

| 案例 | 命令 | 结果 |
| --- | --- | --- |
| Excel 筛选到 Word | `dist/docfill-darwin-arm64 run -c manual_tests/04_filter_work_order_to_word/task.json --var date=2026-06-18 --var ticket_no=GD-002 --verbose` | 生成 1 个 Word 文件 |
| Excel 到 Word | `dist/docfill-darwin-arm64 run -c manual_tests/01_excel_to_word/task.json --var batch=早班 --verbose` | 生成 2 个 Word 文件 |
| SQLite 到 Excel | `dist/docfill-darwin-arm64 run -c manual_tests/02_sqlite_to_excel/task.json --var date=2026-06-18 --verbose` | 生成 2 个 Excel 文件 |
| Excel 到 Excel | `dist/docfill-darwin-arm64 run -c manual_tests/03_excel_to_excel/task.json --var date=2026-06-18 --verbose` | 生成 2 个 Excel 文件 |

关键输出：

```text
manual_tests/04_filter_work_order_to_word/out/work_order_2026-06-18_GD-002.docx
manual_tests/01_excel_to_word/out/daily_2026-06-18_张三_测试_1.docx
manual_tests/01_excel_to_word/out/daily_2026-06-18_李四_2.docx
manual_tests/02_sqlite_to_excel/out/summary_客服部_1.xlsx
manual_tests/02_sqlite_to_excel/out/summary_营销部_2.xlsx
manual_tests/03_excel_to_excel/out/audit_2026-06-18_王五_1.xlsx
manual_tests/03_excel_to_excel/out/audit_2026-06-18_赵六_2.xlsx
```

## 真实素材内容核验

使用 bundled Python 读取生成的 Word / Excel 文件并断言关键字段。

核验结果：

- 筛选工单 Word 包含 `GD-002`、`B 公司`、`D5000`、`已完成`。
- 筛选工单 Word 不包含非目标行 `GD-001`、`A 公司`。
- 日报 Word 包含 `张三/测试`、`早班`、`营销部`。
- SQLite 汇总 Excel 中 `summary_营销部_2.xlsx` 的 B2:B6 为 `营销部 / 2026-06-18 / 张三 / 128 / 3`。
- Excel 质检输出中 `audit_2026-06-18_赵六_2.xlsx` 的 B2:B6 为 `2026-06-18 / 赵六 / 系统截图一致性 / 87 / 缺少 1 张截图，需要补充`。
- SQLite 源表包含 3 行测试数据。

## DOCX 渲染核验

使用 `documents` skill 的 `render_docx.py` 渲染两个 Word 输出：

```text
manual_tests/_evaluation_rendered/filter/page-1.png
manual_tests/_evaluation_rendered/daily/page-1.png
```

视觉核验结果：

- 筛选工单页可读，字段位置正常，关键值为 `2026-06-18 / GD-002 / B 公司 / D5000 / 已完成 / 归档并同步日报`。
- 日报页可读，字段位置正常，关键值为 `张三/测试 / 营销部 / 早班`。
- 未观察到明显空白页、文本重叠、缺字或表格错位。

## CLI 失败路径

| 场景 | 命令或配置 | 预期错误码 | 结果 |
| --- | --- | --- | --- |
| 筛选无匹配 | `ticket_no=GD-999` | `DATA_FILTER_NO_MATCH` | 通过 |
| 筛选变量缺失 | 不传 `ticket_no` | `DATA_FILTER_VALUE` | 通过 |
| 筛选匹配多行 | 临时配置只按 `日期` 筛选且 `expect=one` | `DATA_FILTER_MULTI_MATCH` | 通过 |
| 非法 `filter.expect` | 临时配置 `expect=single` | `CONFIG_VALIDATE` | 通过 |
| 配置不存在 | `-c manual_tests/not-exist.json` | `CONFIG_READ` | 通过 |
| CLI 参数错误 | `--var date` | `CLI_USAGE`，退出码 2 | 通过 |

典型错误输出：

```text
docfill: [DATA_FILTER_NO_MATCH] filter matched no rows
hint: Check filter.equals, --var values, or source table contents.
context: expect=one filter=工单编号=GD-999,日期=2026-06-18
```

```text
docfill: [DATA_FILTER_MULTI_MATCH] filter matched 2 rows but expected one
hint: Add another filter condition or clean duplicate rows in the source table.
context: filter=日期=2026-06-18 matches=2
```

## 结构与文档一致性

| 检查 | 结果 |
| --- | --- |
| 所有 `task.json` 可被 JSON 解析 | 通过 |
| `manual_tests/**/out/*.{docx,xlsx}` 内部 XML 无残留 `{{` / `}}` 占位符 | 通过 |
| README / HOWTO / runbook 均说明 `filter.equals`、`filter.expect`、`--var` 优先级 | 通过 |
| 用户文档未出现不合适措辞 `小白`、`大白话` | 通过 |
| 用户文档无 `TODO` / `TBD` / `FIXME` | 通过 |

## 能力覆盖评估

已验证：

- Excel 数据源读取。
- SQLite 数据源读取。
- Word 模板填充。
- Excel 模板填充。
- Word 同段落拆分占位符替换。
- 输出文件名非法字符清理。
- `vars` 默认变量。
- CLI `--var` 覆盖 `vars`。
- 数据行字段优先于 `--var` / `vars`。
- 多条件业务筛选。
- `expect=one` 和 `expect=many`。
- 筛选错误、配置错误、CLI 错误。
- stdout 输出生成文件清单。
- stderr 输出日志、错误码、hint、context。

未覆盖或仅部分覆盖：

- 大文件性能。
- 多 sheet 大范围模板扫描性能。
- Windows / Linux 路径与构建。
- Excel 公式、图表、透视表类模板。
- Word 跨段落拆分占位符。
- 真实业务系统导出的复杂脏数据。

## 风险与建议

P0 无阻塞问题。

建议进入下一轮前只做小范围补强：

1. 增加一条大约 500 到 1000 行 Excel 的筛选性能测试，确认小工具在常见业务表规模下响应稳定。
2. 增加文档中的“字段命名建议”，例如日期列、工单编号列、辅助列的命名方式。
3. 保持筛选语法只支持等值 AND，不增加模糊匹配、范围查询或表达式。
4. 发布前在目标机器上补一次 `bash scripts/build.sh && bash scripts/smoke.sh`。