L02-07 元数据设计：决定你后面能过滤什么

全局中心内容：元数据是「事后补不回来」的——灌库时没存，线上就过滤不了。 全局讲解主线：一个翻车场景 → 必存字段清单 → 反例对比 → 编码 → 版本与权限 → 检查清单。

P1 · 产出页

中心内容：一套完整的元数据 schema + 灌库时的校验器。

中心内容：七个字段，缺一个将来都要返工。

页面内容：sourceId / tenantId / acl / version / titlePath / updatedAt / embeddingModel
讲解技巧
- 强调 sourceId 是元数据的主键：它是「同一篇文档」的唯一标识，增量更新全靠它（预告 02-14）。
- embeddingModel 这个字段最容易被漏，但它决定了换模型时你能不能分辨哪些片段是旧模型生成的。
时长：6min

中心内容：只存文件名是不够的。

页面内容：坏例子 vs 好例子并排
讲解技巧
- 坏例子直接写 {filename: "员工手册.pdf"}，让学员自己说「能不能按部门过滤、能不能判断新旧」。
- 好例子展示完整字段，并指出每个字段对应一个将来会用到的能力。
时长：5min

中心内容：在切分阶段就把元数据注入每个 Document。

页面内容：MetadataBuilder / 必填字段校验 / 缺失即快速失败
讲解技巧
- 重点讲「缺失即失败」的取舍：宁愿灌库失败，也不要灌一堆查不到的数据进去。这条原则要写在代码注释里。
- 提醒：元数据的值要用枚举/常量，别让业务方自由发挥写中文，将来过滤条件拼不出来。
时长：7min

中心内容：acl 字段决定谁能看到这条片段，是安全底线。

页面内容：acl 设计（角色/部门/用户组）；tenantId 强制注入
讲解技巧
- 强调 tenantId 不能由调用方传，必须从认证上下文取，否则一个参数就能跨租户。
- 讲清 acl 的两种做法：简单场景存部门列表；复杂场景存 ACL ID，检索时联查。
时长：5min

中心内容：同一篇文档的新旧版本必须能区分。

页面内容：version 字段；updatedAt；过期标记策略
讲解技巧
- 用「年假制度改了」的例子：旧版本还在库里，检索时两条都命中，模型可能引用旧的。
- 给出解法预告：02-14 增量更新会用 sourceId + version 做替换。
时长：4min

中心内容：标题要写进文本，不能只放元数据。

页面内容：同一片段的两种写法对比
讲解技巧
- 这是本节的关键反直觉点：元数据字段不会被向量化，所以只放元数据的话，「年假」这个词在向量里根本不存在。
- 正确做法：titlePath + 正文 一起作为 embedding 的输入文本，元数据里再单独存一份用于过滤。
时长：5min

中心内容：schema 变更等于重灌，所以第一次就要想全。

讲解技巧
- 给一个自检口诀：「能不能按 X 过滤？」——把产品、运营、安全各问一遍，列出来的维度全存上。
- 引出下一节：相似度阈值怎么定——02-08。
时长：2min

项	内容
课前必做	准备坏/好元数据对比样例；准备一份真实文档用于现场灌库
最容易超时处	P2 字段清单，容易陷入讨论——按「先讲用途，细节看文档」推进
学员最常问	「元数据能不能后加？」答：PGVector 的 JSONB 可以 ALTER，但要逐条补全，数据量大时不如重灌
现场备用	如无数据库 → 用内存 VectorStore 演示元数据构建过程