P2-WP02 主动元数据与字段血缘验证记录

1. 工程范围

P2-WP02 复用既有数据库目录采集和字段证据，在其上增加持续发现与治理闭环：

数据库、受控文件和 API 来源共用的发现计划、调度、范围和游标契约；
数据库目录快照自动投影到匹配来源的启用计划，PostgreSQL 和 MySQL 继续复用既有采集器；
跨批次资产当前态、不可变版本，以及资产/字段新增、变更和删除候选；
已纳管 SQL 的保守字段血缘解析，以及不可解析语句的哈希证据和失败原因；
质量、新鲜度、任务失败和使用热度四类资产健康信号；
用户纠错、指定责任人处置、乐观版本控制和追加式审计；
viewer 只读、editor 执行与纠错、admin 计划管理的独立权限和运营页面。

本工作包没有复制第二套目录采集服务，也没有改变既有 Neo4j 已发布元数据。受控文件/API 通过同一计划和批次接口提交规范化快照；第二业务域真实连接和样本仍按 P2-WP12 绑定验收。

2. 数据与事务边界

plan_uid + batch_key 唯一；重复请求返回原批次，不重复追加版本、变化、血缘或健康信号；
数据库目录快照与主动元数据投影在同一应用事务中完成，投影失败会使采集任务进入可重试失败态；
游标只在成功批次后推进；失败批次保留原游标和失败原因；
资产内容变化才追加不可变版本；当前快照缺失只标记资产或字段为删除候选，不物理删除；
字段血缘无法可靠解析时失败关闭并保存原因，不猜测字段关系；
健康信号只接受质量、新鲜度、任务失败和使用热度四类；
纠错只能由指定责任人按期望版本处置，提交和处置均追加审计版本；
计划、快照和纠错载荷递归拒绝密码、令牌、凭据、API Key 和私钥语义字段；
主动发现只形成 PostgreSQL 候选和证据，不绕过既有评审/发布门禁覆盖 Neo4j 元数据。

3. 接口与页面

新增 11 个 /api/meta/active-metadata 操作，覆盖计划、批次、资产、变化、字段血缘、健康信号和纠错。OpenAPI 已由当前路由重新生成，共 236 个操作。

“主动元数据与血缘”页面从数据研发中心进入，可以追溯计划、批次、来源资产、删除候选、字段变化、解析失败原因、健康信号和纠错审计。只有管理员显示新建计划入口。

4. 定向验证结果（2026-07-30）

遵循工作包级验证策略，本次未执行全量回归，只验证 P2-WP02 和直接触达能力：

核心、API、迁移、前端契约和目录投影专项测试 19 项通过；
既有目录采集 API 兼容测试 4 项通过；
OpenAPI 可复现和路由清单测试 2 项通过；
本地 PostgreSQL 主动元数据真实持久化集成测试 1 项通过；
PostgreSQL、MySQL 真实目录采集集成测试 2 项通过；
本地 Alembic 位于 20260730_380 (head)；
新增和触达 Python 文件 Ruff 检查通过；
新增和触达前端文件 ESLint 检查通过；
前端生产构建成功，仅保留项目既有的 Browserslist 数据过期和 Webpack 弃用警告；
app/ 与 deployment/app/ 的新增和触达后端文件逐字节一致。

真实持久化验证覆盖：启用来源计划自动投影、同批次重放幂等、跨批次字段类型变化、资产删除候选、游标推进、成功/失败字段血缘、四类健康信号、失败批次、责任人纠错和两版审计。

以上是本地工程完成证据，不代表第二业务域真实文件/API 样本、企业人员、目标环境调度器或生产发布已经验收；这些外部绑定仍由 P2-WP12、P2-WP13 完成。