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

## 1. 工程范围

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

1. 数据库、受控文件和 API 来源共用的发现计划、调度、范围和游标契约；
2. 数据库目录快照自动投影到匹配来源的启用计划，PostgreSQL 和 MySQL 继续复用既有采集器；
3. 跨批次资产当前态、不可变版本，以及资产/字段新增、变更和删除候选；
4. 已纳管 SQL 的保守字段血缘解析，以及不可解析语句的哈希证据和失败原因；
5. 质量、新鲜度、任务失败和使用热度四类资产健康信号；
6. 用户纠错、指定责任人处置、乐观版本控制和追加式审计；
7. 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 完成。