187 lines
7.1 KiB
Markdown
187 lines
7.1 KiB
Markdown
# 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`。
|