文档解析改造任务清单

创建时间: 2026-02-14 分支: 当前分支 目标: 文档解析从 mock 走向可用链路

---

📊 总体进度

• 第 1 步: 目标与输出定义
• 第 2 步: 文本抽取管线
• 第 3 步: 结构化解析与校验
• 第 4 步: 生成与写入稳态化
• 第 5 步: 测试与验证
• 第 6 步: 运营与审计

---

📝 任务详情

第 1 步：目标与输出定义

目标: 明确解析输出结构与计划书配置的对齐规则

文件:

• docs/plan/plan-form-schema-usage.md
• scripts/parse-docs.js

子任务:

• 定义解析输出 JSON 结构（字段、类型、必填/可选）
• 对齐 form_schema 与 submit_mapping 规范
• 明确 form_sn 可复现生成规则
• 补齐输出示例与边界约束说明

验收标准:

• 输出结构在文档中完整可查
• form_sn 规则具备稳定性与可追溯性
• 解析输出可直接用于配置生成

---

第 2 步：文本抽取管线

目标: 建立 PDF/Word 文本抽取基础能力

文件:

• scripts/parse-docs.js
• package.json

子任务:

• 选择 PDF 文本抽取方案并完成接入
• 选择 Doc/Docx 文本抽取方案并完成接入
• 为扫描文档预留 OCR 接口与降级策略
• 统一抽取结果结构（text/meta/warnings）
• 增加抽取失败的错误提示与回退逻辑

验收标准:

• PDF 与 Docx 均可输出可用文本
• 抽取失败可定位原因并不写入配置
• 日志记录包含文件名与失败原因

---

第 3 步：结构化解析与校验

目标: 将文本解析成结构化配置并进行校验

文件:

• scripts/parse-docs.js
• scripts/parse-docs.test.js

子任务:

• 定义 JSON Schema 校验规则
• 接入结构化解析结果校验
• 校验失败输出清晰报告
• 校验失败阻断写入配置
• 增加最小覆盖单测与示例

验收标准:

• 不合法配置不会写入 plan-templates
• 校验错误可一眼定位缺失字段
• 单测覆盖关键异常路径

---

第 4 步：生成与写入稳态化

目标: 输出稳定可控、支持 diff 与回滚

文件:

• scripts/parse-docs.js
• src/config/plan-templates.js

子任务:

• form_sn 改为 slug + hash 的稳定规则
• 插入位置改为锚点块或结构化写入
• 增加重复 form_sn 检测与冲突提示
• 支持 dry-run 输出变更 diff
• 备份与回滚记录完善

验收标准:

• 重复解析不会产生随机 form_sn
• 插入位置稳定可靠
• dry-run 能清晰展示新增/修改内容

---

第 5 步：测试与验证

目标: 保证解析流程可回归验证

文件:

• scripts/parse-docs.test.js
• docs/to-parse/README.md

子任务:

• 新增 fixtures 文档样本说明
• 增加解析流程集成测试
• 补充 updateConfigContent 边界测试
• 运行测试并记录结果

验收标准:

• 解析流程有稳定测试兜底
• 关键边界路径有覆盖
• 测试可重复运行

---

第 6 步：运营与审计

目标: 便于长期维护与复盘

文件:

• scripts/parse-docs.js
• docs/to-parse/README.md

子任务:

• 输出解析摘要（成功/失败/耗时）
• 生成审计日志与变更摘要
• 更新使用说明与注意事项

验收标准:

• 每次解析均可追踪结果
• 文档能指导新成员完成解析

---

🔍 快速跳转

• 解析脚本
• 解析测试
• 待解析说明
• 计划书配置
• Schema 使用文档

---

📝 备注

• 每完成一个子任务，就在对应的 [ ] 中打勾 ✓
• 任务执行过程中的问题与结论直接补充在对应任务下