raven-dev-ops/ETL-Identity-Data-Ruleset-Engine

# ETL 身份数据规则集引擎 ETL 身份数据规则集引擎是一个原型框架，旨在提高多源数据集的数据质量和身份一致性。该项目展示了 ETL 管道如何通过概率匹配来标准化不一致的记录、检测可能重复的身份，并使用确定性存留规则生成可信的“黄金记录”。 许多运营系统从多个来源摄取身份数据，这些来源存储的信息格式不一致、标识符不完整且存在重复记录。这些不一致性会向下传播到报告系统、分析环境和搜索界面，从而降低对数据的信任度。 本仓库使用合成数据集对这些挑战进行建模，现在还支持清单驱动的本地输入以及与对象存储兼容的批量输入，以便进行生产级评估。团队依然可以安全地使用合成数据探索身份解析技术，然后在显式清单契约下，针对已落地的 CSV 或 Parquet 批次验证相同的阶段性运行时。 ## 核心概念 ### 标准化 在转换和加载之前，将不一致的字段标准化为规范格式。 示例： - 将 `Smith, John` 和 `John A Smith` 转换为标准化的名称格式。 - 标准化日期格式。 - 标准化地址结构。 - 移除标点符号和格式不一致。 ### 概率身份匹配 使用加权信号而非精确匹配来评估潜在的重复记录。 信号可能包括： - 姓名相似度 - 出生日期匹配 - 地址重叠 - 电话或标识符相似度 - 语音匹配 每个潜在匹配都会获得一个置信度分数，指示两条记录代表同一个人的可能性。 ### 黄金记录生成 当检测到重复项时，存留规则决定哪些属性成为权威记录。 存留规则示例： - 优先使用全法定名称而非缩写名称。 - 优先使用已验证的标识符而非推断值。 - 优先使用最近的地址。 - 保留来源归属以确保可追溯性。 结果是一个合并的可信身份记录。 ## 目标 - 在 ETL 管道中演示身份解析。 - 提高下游分析和报告中的数据信任度。 - 提供一种透明的、基于规则的重复检测方法。 - 创建可适应不同数据环境的模块化架构。 - 提供用于安全实验的合成环境。 ## 高级管道 `源数据 -> 标准化层 -> 重复候选生成 -> 概率匹配引擎 -> 存留规则引擎 -> 黄金记录输出 -> 分析 / 报告数据` ## 身份冲突示例 合成输入记录： | ID | Name | DOB | Address | | --- | --- | --- | --- | | 1 | John A Smith | 1985-03-12 | 123 Main St | | 2 | Smith, John | 1985-03-12 | 123 Main Street | | 3 | Jon Smith | 1985-03-12 | 123 Main St | 匹配检测到高置信度重复集并生成： | Canonical Name | DOB | Address | | --- | --- | --- | | John A Smith | 1985-03-12 | 123 Main St | ## 仓库结构 ``` ETL-Identity-Data-Ruleset-Engine/ .github/ config/ data/ deploy/ docs/ planning/ scripts/ src/etl_identity_engine/ tests/ ``` 详细的结构和排序记录在 [planning/project-structure-outline.md](planning/project-structure-outline.md) 中。 ## 预期用途 本项目旨在作为 ETL 工作流中身份解析的参考实现。它对于处理跨多个运营系统的碎片化身份数据并希望改善以下方面的团队非常有用： - 数据质量 - 重复检测 - 分析可靠性 - 报告准确性 ## 数据安全 本项目使用的所有数据集均为合成数据，仅供演示使用。仓库中不包含任何运营数据、个人数据或敏感数据。 ## 范围边界 - 运行时现在支持两种输入模式：用于安全实验的合成生成，以及用于生产级评估的清单驱动落地批次。支持本地文件系统和与对象存储兼容的着陆区。通过 SQLite 路径或 PostgreSQL URL 实现的持久化 SQL 状态、用于清单时代输入的归档重放包、清单驱动的增量刷新、容器镜像、单主机 compose 部署基线、具有容量目标的命名基准测试固定装置以及经过身份验证的操作员服务 API 现已可用。当前的生产运行时支持由部署提供的 issuer、audience 和签名元数据支持的 JWT bearer auth，而本地容器基线保留 API-key 兼容模式。服务层现在除了稳定的 `reader` 和 `operator` 角色外，还强制执行文档化的端点作用域。 当前的服务线支持分页读取端列表和查找，以及仅限操作员的审查决策、重放、发布和导出触发操作。 - 当前 `0.x` 版本支持的匹配轨迹是确定性和可解释的：精确匹配加上启发式部分和语音信号。ML 辅助评分故意不在支持的公开版本范围内。 - 当前 `0.x` 版本支持的人工审查操作模式现在有两层：CSV 队列构件仍是可移植的文件交接，持久化运行也可以在配置的状态存储中跟踪审查案例的状态、受让人、时间戳和备注。 批准和拒绝的审查决定现在会延续到后续的持久化重新运行中，并且可以覆盖启发式集群和黄金结果。 ## 未来增强 - 可配置的身份匹配规则 - 额外的可解释启发式信号和更丰富的离线评估 - 使用地理编码服务的地址标准化 - 流式 ETL 支持 - 实时身份解析管道 ## 规划工件 - [项目结构大纲](planning/project-structure-outline.md) - [剩余工作清单](planning/remaining-work-task-list.md) - [活跃 GitHub Issues Backlog](planning/active-github-issues-backlog.md) - [v0.6.0 后 GitHub Issues Backlog（历史）](planning/post-v0.6.0-github-issues-backlog.md) - [v0.1.0 后 GitHub Issues Backlog（历史）](planning/post-v0.1.0-github-issues-backlog.md) - [启动阶段 GitHub Issues Backlog（历史）](planning/github-issues-backlog.md) ## 文档 - [架构](docs/architecture.md) - [数据模型](docs/data-model.md) - [标准化](docs/normalization.md) - [生产批量清单](docs/production-batch-manifest.md) - [兼容性策略](docs/compatibility-policy.md) - [基准测试与容量](docs/benchmarking-and-capacity.md) - [容器部署](docs/container-deployment.md) - [交付契约](docs/delivery-contracts.md) - [导出作业](docs/export-jobs.md) - [持久化状态](docs/persistent-state.md) - [恢复操作手册](docs/recovery-runbooks.md) - [审查工作流](docs/review-workflow.md) - [服务 API](docs/service-api.md) - [运行时环境](docs/runtime-environments.md) - [匹配与阈值](docs/matching-and-thresholds.md) - [运维与可观测性](docs/operations-observability.md) - [存留规则](docs/survivorship.md) - [评估与指标](docs/evaluation-and-metrics.md) - [输出契约](docs/output-contracts.md) - [生产运营模型](docs/production-operating-model.md) - [发布流程](docs/release-process.md) - [标准映射](docs/standards-mapping.md) ## 维护者发布包 使用以下命令打包文档化的发布样本存档： ``` python scripts/package_release_sample.py --output-dir dist/release-samples --profile small --seed 42 --formats csv,parquet ``` 发布过程将该脚本视为权威包入口点，生成的 zip 文件应附加到匹配标签的 GitHub release 中。 对于固定的干净提交，该包在重新运行时是字节稳定的。打包脚本默认从 HEAD 提交时间戳派生 `generated_at_utc`，并在需要可重现的重建时间戳覆盖时遵循 `SOURCE_DATE_EPOCH`。 ## 治理与安全 - [许可证](LICENSE) - [贡献](CONTRIBUTING.md) - [安全](SECURITY.md) - [行为准则](CODE_OF_CONDUCT.md) - [安全](SAFETY.md) ## 启动状态 (M1) 此仓库现在包含一个可工作的 `M1` 脚手架： - `src/etl_identity_engine/` 下的 Python 包骨架 - 阶段 CLI 命令：`generate`、`normalize`、`match`、`cluster`、`review-queue`、`golden`、`report`、`publish-delivery`、`publish-run`、`review-case-list`、`review-case-update`、`apply-review-decision`、`replay-run`、`benchmark-run`、`export-job-list`、`export-job-run`、`export-job-history`、`serve-api`、`run-all` - `tests/` 下的基础测试套件 - `.github/` 下的 CI 和 issue 模板 - 治理文件：`LICENSE`、`CONTRIBUTING.md`、`SECURITY.md`、`CODE_OF_CONDUCT.md`、`SAFETY.md` ## 合成生成器状态 (M2) `generate` 现在生成具有可配置冲突注入的确定性多表合成输出： - `person_source_a.*` - `person_source_b.*` - `conflict_annotations.*` - `incident_records.*` - `incident_person_links.*` - `address_history.*` - `generation_summary.json` 格式可配置（`csv`、`parquet`），默认为两者兼具。 `normalize` 阶段自动发现 CSV 输入，并在 CSV 输入缺失时回退到 Parquet，因此每次运行只使用一种发现的格式集。 ## 当前运行时输出 `run-all` 现在执行完整的配置驱动原型切片并写入： - `data/normalized/normalized_person_records.csv` 中的标准化行 - `data/matches/candidate_scores.csv` 中带有 `decision`、`matched_fields` 和 `reason_trace` 的评分候选对 - `data/matches/blocking_metrics.csv` 中的按轮次阻塞指标 - `data/matches/entity_clusters.csv` 中的确定性集群分配 - `data/golden/golden_person_records.csv` 中带有字段级溯源的黄金记录 - `data/golden/source_to_golden_crosswalk.csv` 中的源到黄金交叉引用 - `data/review_queue/manual_review_queue.csv` 中的人工审查队列 - `data/exceptions/` 下的异常工件和摘要输出 - `data/exceptions/run_summary.json` 中的阶段计时和吞吐量指标 这些文件的稳定输出结构记录在 [docs/output-contracts.md](docs/output-contracts.md) 中。 持久化运行也可以通过 [docs/delivery-contracts.md](docs/delivery-contracts.md) 中记录的版本化快照契约为下游消费者发布。 当前匹配器依然基于规则，但现在包括精确、部分和轻量级语音名称信号。候选输出通过 `matched_fields` 和 `reason_trace` 显式公开这些派生信号。 当 `run-all` 与 `--state-db` 和清单输入配对使用时，运行时还支持 `--refresh-mode incremental`。该路径重用先前完成的清单运行（来自持久化状态），仅重新计算受影响的实体和候选对，并在 `data/exceptions/run_summary.json` 中记录刷新结果。 完成的持久化运行随后可以通过 `publish-delivery` 发布到不可变的黄金和交叉引用快照中。 当前的人工审查操作模式通过 `data/review_queue/manual_review_queue.csv` 保持文件交接，持久化运行现在也通过 `review-case-list` 和 `review-case-update` 支持持久的审查案例状态。批准和拒绝的审查决定现在应用于后续的持久化重新运行，在集群和黄金重建之前强制合并或不合并结果。 持久化 SQL 状态现在也可以通过 `serve-api` 由经过身份验证的操作员 API 提供。该层公开运行状态、黄金记录查找、源到黄金交叉引用查找、分页的运行、黄金和审查案例集合，以及供下游系统和操作员使用的持久化审查案例检索，现在它还在独立的 API-key 或 JWT 支持的角色背后支持仅限操作员的审查决策、重放、发布和导出触发操作。它现在还公开经过身份验证的 `healthz`、`readyz` 和 `/api/v1/metrics` 端点，而特权 CLI 和服务操作发出结构化 JSON 日志并在配置的状态存储中持久化审计事件。服务契约记录在 [docs/service-api.md](docs/service-api.md) 中，当前的操作基线记录在 [docs/operations-observability.md](docs/operations-observability.md) 中。 对于操作员工作流，CLI 现在还公开： - `apply-review-decision` 用于幂等审查案例决策 - `replay-run` 用于清单支持的持久化重新运行 - `publish-run` 用于基于 JSON 的下游发布触发器 - `export-job-list` 用于配置的仓库和数据产品导出 - `export-job-run` 用于可审计的下游快照物化 - `export-job-history` 用于导出执行历史和重用跟踪 配置的下游导出作业现在建立在版本化交付契约之上，并且可以从 `config/export_jobs.yml` 针对不同的仓库或数据产品根目录。该操作员层记录在 [docs/export-jobs.md](docs/export-jobs.md) 中。 外部服务和工作流集成也应遵循 [docs/compatibility-policy.md](docs/compatibility-policy.md) 中的共享兼容性规则。 容器构建和 compose 部署指南记录在 [docs/container-deployment.md](docs/container-deployment.md) 中。 基准测试固定装置定义、回归目标和 `benchmark-run` 工作流记录在 [docs/benchmarking-and-capacity.md](docs/benchmarking-and-capacity.md) 中。 对于规模验证，`benchmark-run`针对来自 `config/benchmark_fixtures.yml` 的命名大批量固定装置执行真实的持久化管道，并将基准测试工件写入 `dist/benchmarks//`。 除非输入已包含 `cluster_id` 值，否则独立的 `golden` 阶段使用标准化记录加上 `data/matches/entity_clusters.csv`。独立的 `report` 阶段读取标准化工件加上当前的匹配、集群、黄金和审查队列工件，以便其计数与管道状态匹配。 `run-all` 也接受 `--formats`，并将尽可能从生成的 CSV 输出进行标准化，或者当 CSV 不在请求的格式集中时，从生成的 Parquet 输出进行标准化。 ## 本地快速入门 (优先 Venv) 前置条件：已安装 Python 3.11+ 并在 `PATH` 中可用。 虚拟环境仅安装 Python 依赖项和本地 `gh` CLI。它不提供 shell 运行时（如 `bash` 或 PowerShell），但当您需要无 shell 的本地验证和管道执行时，仓库提供了 Python 原生 `scripts/run_checks.py` 和 `scripts/run_pipeline.py` 入口点。 当前维护的 CI 支持涵盖： - Linux 和 Windows 上的 Python `3.11` 基线验证 - Linux、Windows 和 macOS 上的 Python `3.12` 兼容性验证 ### Windows (PowerShell) 在 Windows 上使用 PowerShell 路径。不要指望 venv 提供 `bash` 运行时。 ``` ./scripts/bootstrap_venv.ps1 .\.venv\Scripts\Activate.ps1 ./scripts/run_checks.ps1 python -m etl_identity_engine.cli generate --profile small --duplicate-rate 0.4 --formats csv,parquet ./scripts/run_pipeline.ps1 ``` `run_checks.ps1` 现在涵盖了与文档化 CI 基线相同的本地验证范围：包构建验证、`ruff`、`pytest`、已安装的 `etl-identity-engine` 控制台入口点冒烟测试、活跃积压干运行、发布样本打包和持久化状态恢复冒烟路径。构建和打包检查使用临时输出目录，因此包装器不会在 `dist/` 下留下工件。 它还验证已安装的可编辑包元数据是否与 `pyproject.toml` 匹配，因此在拉取版本更新后重新运行引导脚本或 `python -m pip install -e .[dev]`。 `run_pipeline.ps1` 转发任何额外的 `run-all` CLI 参数，例如 `./scripts/run_pipeline.ps1 --base-dir tmp --config-dir config`。 ### macOS / Linux (bash) 仅在已提供 `bash` 的系统上使用 bash 路径。该路径在 Linux CI 中验证，而不是由 Python venv 提供。 ``` chmod +x ./scripts/bootstrap_venv.sh ./scripts/run_checks.sh ./scripts/run_pipeline.sh ./scripts/bootstrap_venv.sh source .venv/bin/activate ./scripts/run_checks.sh python -m etl_identity_engine.cli generate --profile small --duplicate-rate 0.4 --formats csv,parquet ./scripts/run_pipeline.sh ``` `run_checks.sh` 涵盖了与文档化 CI 基线相同的本地验证范围：包构建验证、`ruff`、`pytest`、已安装的 `etl-identity-engine` 控制台入口点冒烟测试、活跃积压干运行、发布样本打包和持久化状态恢复冒烟路径。构建和打包检查使用临时输出目录，因此包装器不会在 `dist/` 下留下工件。 它还验证已安装的可编辑包元数据是否与 `pyproject.toml` 匹配，因此在拉取版本更新后重新运行引导脚本或 `python -m pip install -e .[dev]`。 `run_pipeline.sh` 转发任何额外的 `run-all` CLI 参数，例如 `./scripts/run_pipeline.sh --base-dir tmp --config-dir config`。 ### 直接命令 (任意平台) ``` python -m venv .venv .venv/bin/python -m pip install --upgrade pip setuptools wheel .venv/bin/python -m pip install -r requirements-dev.txt .venv/bin/python scripts/run_checks.py .venv/bin/python -m ruff check . .venv/bin/python -m pytest .venv/bin/python -m etl_identity_engine.cli run-all ``` 在 Windows 上，将 `.venv/bin/python` 替换为 `.venv\Scripts\python.exe`。 ### Windows 别名故障排除 如果 `python` 解析为 `...WindowsApps\python.exe`，请从 `python.org` 安装 Python，并在 Windows 设置中禁用 `python.exe` 和 `python3.exe` 的应用执行别名。 ## GitHub Backlog 自动化 使用跨平台 Python 自动化脚本通过规划积压创建标签、里程碑、史诗和 issue： ``` gh auth login python scripts/create_github_backlog.py --repo "raven-dev-ops/ETL-Identity-Data-Ruleset-Engine" --dry-run python scripts/create_github_backlog.py --repo "raven-dev-ops/ETL-Identity-Data-Ruleset-Engine" ``` 默认积压来源是 `planning/active-github-issues-backlog.md`。`planning/github-issues-backlog.md` 处的引导积压和已完成的 `planning/post-v0.1.0-github-issues-backlog.md` 文件是历史性的，仅在使用 `--include-closed` 重新同步已关闭的跟踪历史记录时才应使用： ``` python scripts/create_github_backlog.py --repo "raven-dev-ops/ETL-Identity-Data-Ruleset-Engine" --backlog-path planning/github-issues-backlog.md --include-closed --dry-run ``` 默认情况下，积压自动化忽略标记为 `Status: closed` 的目录条目，以便活跃积压文件可以在周期完成后保留为历史记录，而不会重新创建已关闭的 GitHub 工作。 手动提交新工作时，请使用针对 `bug`、`feature`、`docs`、`chore` 和 `epic` 的 GitHub issue 表单，以便 issue 与积压标签分类和里程碑结构保持一致。 在 Windows 上，如果您更喜欢该入口点，`scripts/create_github_backlog.ps1` 仍可作为 PowerShell 特定包装器使用。 `Issue Metadata` 工作流在 issue 模板更改到达 `main` 后运行，并通过 GitHub API 检查 GitHub 的默认分支 issue 元数据以及推送的模板文件。这提供了一种 GitHub 端的验证路径，而无需依赖手动浏览器检查。 引导脚本安装 Python 依赖项和 venv 范围的 GitHub CLI，因此本地检查不需要全局 `gh` 安装。它们不安装 OS shell 运行时；Windows 用户应在本地运行 PowerShell 入口点，而 Linux CI 验证文档化的 bash 路径。Python 原生 `scripts/run_checks.py` 和 `scripts/run_pipeline.py` 入口点在每个平台上均可用。 本地 `run_checks` 包装器是权威的预推送验证路径。它们包括本地 `pytest` 套件以及活跃积压干运行、发布样本打包和持久化状态恢复冒烟检查，并且它们使用临时打包输出，因此预推送验证不会留下发布工件。远程元数据检查仅验证 GitHub 当前在推送的默认分支上看到的内容。 ## 许可证 本项目作为技术演示和参考实现提供。

标签：CSV, ETL, JavaCC, MDM, Parquet, Python, survivors hip_rules, 主数据管理, 合成数据, 实体_resolution, 对象存储, 批处理, 数据去重, 数据治理, 数据清洗, 数据管道, 数据规范化, 数据质量, 数据集成, 无后门, 概率匹配, 测试用例, 生存认定规则, 相似度计算, 记录链接, 请求拦截, 身份解析, 软件工程, 逆向工具, 重复数据检测, 黄金记录