改进文档解析工具-添加审核流程

创建时间: 2026-02-14 负责人: Claude Code 优先级: 🔴 高

---

背景分析

当前问题

使用 pnpm parse:docs --file="计划书模版2.docx" 解析文档时存在以下问题：

1. 解析不准确：mammoth解析.docx提取的内容与实际文档内容不符

   • 缺少产品基本信息（name, type, currency）
   • 字段定义提取不完整（form_schema, submit_mapping）
   • 结构化表格数据提取困难

2. 缺少审核环节：

   • 当前流程：解析 → 直接生成配置代码
   • 问题：无法验证解析准确性，直接写入配置文件风险高

3. 用户需求：

   • 需要"人工辅助"的半自动化方式
   • 在自动解析和直接生成配置之间增加审核环节

现状评审与差距

1. 审核流程已接入但模板不稳定：
   • parse-docs.js 已生成待审核文件并阻断写入配置，但审核模板存在重复定义与内容断裂风险
2. 字段命名不一致：
   • 现有方案示例使用 name/type，与实际解析配置字段 product_name/product_type 不一致
3. 审核指引不清晰：
   • 审核文件的“通过后操作”指向备份文件，未明确 pending/approved 目录治理
4. 解析结果可读性不足：
   • 审核模板对 form_schema 与 submit_mapping 预览不足，无法快速确认关键字段
5. 解析方式描述需要更新：
   • mammoth 的 Markdown 输出存在局限，复杂表格准确性不足，需要明确替代策略

---

解决方案

方案设计

采用 "解析 → 审核 → 人工合并" 三步流程，支持多种解析方式：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  选择解析方式   │  →  │  生成待审核文件 │  →  │  审核通过后合并  │
│  mammoth/MCP    │     │  (markdown)     │     │  到正式配置     │
└─────────────────┘     └─────────────────┘     └─────────────────┘

解析方式对比

特性	mammoth	MCP文档解析
准确性	基础（纯文本提取）	高（AI理解结构）
结构化	弱（需手动处理）	强（自动识别字段）
表格解析	一般（markdown表格）	好（保留结构）
速度	快（本地解析）	慢（网络请求）
成本	免费	可能需要API Key

使用场景

• mammoth: 快速预览、简单文档、离线使用
• MCP: 复杂文档、准确度要求高、有网络连接

注意事项

• mammoth 的 Markdown 输出能力有限，复杂结构建议使用 HTML 输出后再转 Markdown
• 审核文件统一输出到 docs/parse-audit/pending/，通过后移动到 docs/parse-audit/approved/

技术实现

1. 改进基础信息抽取

从多个位置提取产品基本信息（与实际配置字段对齐）：

// 尝试从文档标题、表格、特定文本模式提取
async function extractProductBasicInfo(content, fileName) {
  const info = {
    product_name: '',
    product_type: 'savings',
    currency: 'USD',
    form_sn: generateFormSn(fileName)
  }

  // 策略1: 从文档标题提取
  const titleMatch = content.match(/^#\s+(.+)$/m)
  if (titleMatch) {
    info.product_name = cleanProductName(titleMatch[1].trim())
  }

  // 策略2: 从表格中提取"币种"信息
  const currencyMatch = content.match(/币种[：:]\s*([A-Z]{3})/i)
  if (currencyMatch) {
    info.currency = currencyMatch[1]
  }

  // 策略3: 从表格中提取"产品类型"信息
  if (content.includes('重疾') || content.includes('危疾')) {
    info.product_type = 'critical-illness'
  } else if (content.includes('人寿')) {
    info.product_type = 'life-insurance'
  }

  return info
}

2. 实现generateAuditFile

生成结构化的待审核markdown文件：

async function generateAuditFile(fileName, config, code) {
  const auditDir = 'docs/parse-audit/pending/'
  const dateStr = new Date().toISOString().split('T')[0].replace(/:/g, '-')
  const auditFileName = `${dateStr}-${fileName.replace(/\.[^/.]+$/, '')}.md`
  const auditFilePath = path.join(auditDir, auditFileName)

  const content = `# 产品配置审核 - ${fileName}

**解析时间**: ${new Date().toLocaleString('zh-CN')}

---

## 📋 产品基本信息

| 字段 | 提取值 | 需要确认 |
|------|--------|---------|
| 产品名称 | ${config.product_name || '未提取'} | ✅ 请核对产品名称 |
| 产品类型 | ${config.product_type || '未提取'} | ✅ 请确认产品类型 |
| 币种 | ${config.currency || 'USD'} | ✅ 请确认币种 |
| form_sn | \`${config.form_sn || '未生成'}` | ✅ 请确认form_sn唯一性 |

---

## 📝 表单字段 (form_schema)

\`\`\`javascript
${code.form_schema || '// 请手动补充'}
\`\`\`

---

## 🔄 提交字段映射 (submit_mapping)

\`\`\`javascript
${code.submit_mapping || '// 请手动补充'}
\`\`\`

---

## ✅ 审核检查清单

- [ ] 产品名称正确
- [ ] 产品类型正确（savings/critical-illness/life-insurance）
- [ ] 币种正确（USD/CNY/HKD/EUR）
- [ ] form_sn 唯一且符合命名规范
- [ ] 缴费年期选项完整
- [ ] 年龄范围合理
- [ ] 提取计划配置（如适用）
- [ ] 表单字段定义完整
- [ ] 提交字段映射正确

---

## 📋 审核后操作

### 确认无误
\`\`\`bash
# 1. 移动到 approved 目录
mv docs/parse-audit/pending/${auditFileName} \\
   docs/parse-audit/approved/

# 2. 合并到正式配置
# 手动复制或使用工具合并

# 3. 删除待审核文件
rm docs/parse-audit/pending/${auditFileName}
\`\`\`

### 需要修改
1. 编辑本文件修正内容
2. 重新提交审核

### 放弃本次解析
\`\`\`bash
rm docs/parse-audit/pending/${auditFileName}
\`\`\`
`

---

**生成工具**: Claude Code - parse-docs.js
`

  return fs.writeFileSync(auditFilePath, content, 'utf-8')
}

---

实施计划

阶段1: 修复审核模板与字段对齐

• 清理 generateAuditFile 重复定义与模板断裂问题
• 统一字段命名为 product_name/product_type/currency/form_sn
• 优化审核模板展示 form_schema 与 submit_mapping

阶段2: 审核流程治理

• 确认 pending/approved 目录结构
• 明确审核通过后的合并指引
• 补齐审核状态与审核意见模板

阶段3: 解析策略补齐

• 增加标题/币种/类型的启发式补位策略
• 补齐文档样本验证与失败兜底说明

阶段4: 测试验证

• 使用实际文档回归生成审核文件
• 校验审核模板完整性与可读性

---

预期成果

1. 更准确的信息提取

   • 产品基本信息提取率提升
   • 减少人工补充工作

2. 结构化审核流程

   • 清晰的待审核markdown格式
   • 明确的审核检查清单
   • 简单的审核后操作指引

3. 更好的用户体验

   • 成功提示包含下一步操作
   • 降低配置错误风险

---

风险评估

风险	影响	应对措施
提取仍不准确	需要大量人工补充	提供清晰的标记和默认值
审核文件过多	难以管理	定期清理已审核文件
目录权限问题	无法写入文件	提前创建目录并检查权限
mammoth 输出限制	表格/结构信息丢失	使用 HTML 输出后再转 Markdown

---

后续优化

1. 交互式审核

   • 提供命令行工具逐步引导填写缺失信息
   • 支持编辑现有审核文件

2. 智能推断

   • 基于历史配置推断产品类型
   • 从表格结构自动推断字段定义

3. 版本对比

   • 检测配置变更并生成差异报告
   • 支持配置回滚

---

相关文档

• mammoth 使用文档
• 计划书模板配置规范
• 代码注释规范