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

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

---

背景分析

当前问题

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

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

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

2. 缺少审核环节：

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

3. 用户需求：

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

---

解决方案

方案设计

采用 "解析 → 审核 → 生成" 三步流程，支持多种解析方式：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  选择解析方式   │  →  │  生成待审核文件 │  →  │  人工审核后移动  │
│  mammoth/MCP    │     │  (markdown)     │     │  到正式配置     │
└─────────────────┘     └─────────────────┘     └─────────────────┘

解析方式对比

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

使用场景

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

技术实现

1. 改进extractProductBasicInfo

尝试从多个位置提取产品基本信息：

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

  // 策略1: 从文档标题提取
  const titleMatch = content.match(/^#\s+(.+)$/m)
  if (titleMatch) {
    info.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.type = 'critical-illness'
  } else if (content.includes('人寿')) {
    info.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.name || '未提取'} | ✅ 请核对产品名称 |
| 产品类型 | ${config.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. 移动配置到正式文件
mv docs/parse-audit/pending/${auditFileName} \\
   src/config/plan-templates.backup.js

# 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: 改进解析逻辑 (30分钟)

• 改进extractProductBasicInfo函数
  • 添加文档标题提取
  • 添加币种信息提取
  • 添加产品类型推断
  • 测试验证提取效果

阶段2: 实现审核文件生成 (20分钟)

• 实现generateAuditFile函数
  • 创建待审核目录结构
  • 测试生成markdown格式
  • 添加文件路径返回

阶段3: 集成到主流程 (10分钟)

• 更新parse-docs.js主函数
  • 添加成功提示和审核引导
  • 错误处理和日志输出

阶段4: 测试验证 (10分钟)

• 使用实际文档测试
• 验证生成的审核文件格式
  • 确认目录结构正确

---

预期成果

1. 更准确的信息提取

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

2. 结构化审核流程

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

3. 更好的用户体验

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

---

风险评估

风险	影响	应对措施
提取仍不准确	需要大量人工补充	提供清晰的标记和默认值
审核文件过多	难以管理	定期清理已审核文件
目录权限问题	无法写入文件	提前创建目录并检查权限

---

后续优化

1. 交互式审核

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

2. 智能推断

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

3. 版本对比

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

---

相关文档

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