Appearance
L02-20 项目实战（一）：把灌库做成一条可靠的管道
全局中心内容：灌库不是脚本，是一条要能重跑、能监控、能回滚的管道。 全局讲解主线：整体架构 → 数据源接入 → 解析与切分串联 → 任务编排 → 失败处理 → 验收清单。
P1 · 产出页
中心内容：一个可运行的多数据源灌库服务 + 任务看板。
- 讲解技巧
- 开场明确本节的定位：前三节我们学的都是零件，这一节开始装机器。
- 说明三节项目的分工：本節灌库、02-21 管理后台、02-22 用户端。
- 时长：30s
P2 · 整体架构
中心内容：接入层 / 解析层 / 切分层 / 向量层 四段解耦。
页面内容：架构图，标注每段的可替换点
讲解技巧
- 强调分层的目的：换文档类型只改解析层，换向量库只改向量层。
- 让学员对着图说出「如果要加飞书文档接入，改哪里」——答案是只加一个 Connector。
时长：5min
P3 · 数据源接入
中心内容：本地上传 / 对象存储 / 系统对接 / Webhook 四种源的统一抽象。
页面内容：SourceConnector 接口与三种实现
讲解技巧
- 讲清抽象的关键：Connector 只负责「把文件拿回来 + 给出 sourceId」，不做解析。
- 提醒 sourceId 要稳定：同一个文件每次同步都要得到同一个 ID。
时长：6min
P4 · Webhook 增量
中心内容：源系统变更时主动推，比定时轮询实时且省资源。
- 讲解技巧
- 讲取舍：轮询简单但有延迟和无效开销；Webhook 实时但要处理重复推送和乱序。
- 强调幂等：同一事件重复推送不能产生重复片段（靠 sourceId + 哈希）。
- 时长：5min
P5 · 解析与切分串联
中心内容：按文件类型路由解析器，统一输出结构化文本。
页面内容：类型路由表；解析失败的降级策略
讲解技巧
- 重点讲降级：PDF 解析失败不能让任务失败，要标记「需人工处理」并继续。
- 给出一个现实提醒：扫描件 PDF 一定要走 OCR，否则解析出来是空文本——而且空文本也会成功入库，非常隐蔽。
时长：6min
P6 · 任务编排
中心内容：一个任务 = 解析 → 切分 → 去重 → 批量向量化 → 写入 → 更新索引。
页面内容：任务执行流程与每步的失败处理
讲解技巧
- 讲清「空文本检测」这一道卡：解析出空内容要直接失败并告警，否则会污染检索结果。
- 提醒写入后要更新统计信息（PG 场景），否则查询计划不准。
时长：7min
P7 · 失败处理与重试
中心内容：任务级重试 + 片段级重试，两层都要有。
- 讲解技巧
- 区分：网络抖动重试片段即可；解析逻辑错误重试没用，要改代码。
- 强调失败原因要落库并可查，否则运营只能来问工程师。
- 时长：5min
P8 · 编码：管道装配
中心内容：用 Spring 的配置把各层装配起来，参数外置。
页面内容：配置类与关键参数说明
讲解技巧
- 强调参数外置的价值：调切分大小不用改代码重启，运营也能配合做实验。
时长：6min
P9 · 验收清单
中心内容：六条验收标准，缺一条就不能交付。
页面内容：重复同步不产生重复数据 / 改一个字只更新对应片段 / 失败可重试 / 进度可见 / 可取消 / 有告警
讲解技巧
- 把这六条当交付标准讲，学员可以直接拿去用。
- 引出下一节：库灌好了，谁来管理？——02-21 管理后台。
时长：3min
讲师备忘
| 项 | 内容 |
|---|---|
| 课前必做 | 准备架构图；准备一份扫描件 PDF 用于演示空文本问题 |
| 最容易超时处 | P6 任务编排，代码量大——提前写好只讲关键分支 |
| 学员最常问 | 「要不要用工作流引擎？」答：单服务内用状态机足够，跨服务再考虑 |
| 现场备用 | 无对象存储 → 用本地目录模拟 Connector |