法律文书数据管线技术规格

1. 系统目标

管线面向大规模公开法律文书，将查询结果中的文书标识持续转换为原始详情、结构化字段和全文索引，并支持失败回收、增量同步、质量检查与受控交付。

2. 组件与职责

• 发现器：Python、Scrapy 或浏览器脚本遍历检索条件，生成文书标识和日期分片。
• 同步器：Go 程序在键值存储与关系数据库之间批量迁移标识。
• 下载器：按标识获取文书详情，保存原始响应并记录失败原因。
• 过滤器：Go 代码从文书正文抽取案件、法院、日期、案由和参与主体等字段。
• 索引器：将原文和结构化字段写入 Elasticsearch，供检索与统计。
• 客户清洗程序：Python 项目包含表结构、测试数据、测试代码和编译交付脚本。

3. 数据状态机

建议将一条文书任务定义为：已发现、待下载、下载成功、解析失败、结构化完成、索引完成、质量通过和已发布。每个状态保存批次、重试次数、程序版本和更新时间。

现存同步代码已经使用日期范围、带缓冲通道、多个工作协程和批量数据库写入。它把生产者和消费者分离，是管线中最清晰的并发设计；但终止、错误传播和断点恢复仍需重新实现为显式状态。

4. 存储架构

• 键值存储：保存大规模标识、详情或阶段任务。
• MySQL：保存稳定标识、结构化字段和处理状态。
• MongoDB：保存半结构化或来源差异较大的文档。
• Elasticsearch：提供全文、字段筛选和聚合。
• 文件归档：保存原始响应、失败样本和交付包，必须与业务记录建立校验和关联。

5. 技术亮点

• 发现、同步、下载、解析和索引分为独立命令，可按阶段扩容和重跑。
• Go 同步器支持日期范围分片、并发连接、缓冲队列和批量写入。
• 文书字段过滤有独立测试数据与字段说明，便于针对格式变化做回归。
• 原始文书与搜索索引分开，索引可以从上游重新生成。

6. 非功能要求

• 幂等：同一文书标识重复运行不会生成重复记录。
• 可恢复：任一阶段中断后从最后确认批次继续。
• 可追溯：结构化字段能定位到原文位置和解析器版本。
• 可观测：分别监控发现量、下载成功率、解析覆盖率、索引延迟和重试积压。
• 合规：记录来源使用边界，限制个人信息访问、导出与保留周期。

7. 已知缺口与风险

• 多个仓库是同一逻辑的复制或阶段快照，版本继承关系不完整。
• 部分仓库包含完整 vendor 或开发环境，文件量不能代表业务实现规模。
• 历史配置和注释曾保存不应进入版本控制的连接信息。
• 共享变量和超时轮询式终止可能造成错误丢失或任务未完全消费。
• 来源的查询限制和页面变化会直接影响覆盖率，现有代码缺少长期成功率证据。

8. 重建验收标准

• 固定日期分片可以重复运行并得到相同任务集合。
• 下载和解析失败有稳定分类、退避重试和人工复核入口。
• 结构化覆盖率按字段与文书类型统计，不能只报告下载总量。
• 删除搜索索引后能够从原文和结构化库完整重建。
• 导出包包含数据版本、字段字典、校验和与生成日志。

9. 证据边界

六个仓库覆盖了从早期方案到后期清洗交付的多个阶段，其中主 Go 文书仓有 78 次提交，客户清洗仓有 80 次提交。代码能够证明管线拆分和局部实现，不能证明历史数据全量完整、来源长期可访问或所有结构化字段通过验收。