# python-data-orchestration-lab

**Repository Path**: szzhoujiarui/python-data-orchestration-lab

## Basic Information

- **Project Name**: python-data-orchestration-lab
- **Description**: Production-minded Python demo for pluggable data adapters, deterministic state, bounded integrations, and multi-sink exports.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-18
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[English](README.md) | [简体中文](README.zh-CN.md)

[![Gitee Go verified](https://img.shields.io/badge/Gitee%20Go-verified-brightgreen)](https://gitee.com/szzhoujiarui/python-data-orchestration-lab/gitee_go/pipelines/builds/86314/view)

![Python data orchestration portfolio banner](docs/assets/banner.png)

# Python 数据编排实验室

一个面向生产思维的 Python 数据编排演示：通过可插拔来源适配器采集异构业务数据，将结果收敛到统一的 Pydantic 类型边界，并以可重复方式完成状态合并、SQLite 持久化和 CSV 或 Google Sheets 输出。

## 项目价值

该案例展示了数据自动化、AI 助手和 Agent 工作流背后的可靠数据层。它把供应商载荷差异隔离在适配器内，让业务记录处理、状态保存和交付格式保持稳定，适合作为客户数据采集与整理项目的可审查技术样本。

- 四个面向供应商的适配器或适配器示例覆盖 Google Places、Apollo.io 联系人补充、商业地产 feed 和职位信号 feed，并汇入同一个类型化 `BusinessRecord` 边界。
- 离线路径执行规范化、去重、主记录合并和 SQLite 持久化，也可导出字段顺序固定的确定性 CSV 行。
- 已验证基线包含 51 项自动化测试和 2 条合成离线记录。
- Google Places 与 Google Sheets 是选择性启用的在线集成，运行时需要本地提供凭据。

## 效果预览

![Verified offline sample run](docs/assets/sample-run.png)

[演示脚本](docs/demo-script.md) 提供一条可直接录制的 75 秒复现路径。

无需外部账号即可运行合成数据流程。离线 dry run 的已验证摘要为：

```text
Run summary: collected=2 updated=0 failed=0 errors=0
```

持久化模式会为主记录生成稳定标识、保留来源历史并 upsert 到本地 SQLite；指定 `--csv-output` 后还会写出具有固定表头顺序的 CSV。

## 工作流程

```text
来源 API 或合成 fixtures
  -> 面向供应商的适配器
  -> Pydantic BusinessRecord
  -> 地址规范化与去重
  -> 主记录合并与来源历史
  -> SQLite 状态
  -> CSV 或选择性启用的 Google Sheets 输出
```

适配器共享 `search`、`normalize` 和 `validate` 契约。供应商字段映射停留在适配器层，编排逻辑只处理统一记录；离线样本经过相同的类型校验、去重、合并和输出阶段。

## 核心能力

- Google Places 新版与 legacy API 模式、单查询和确定性区域/关键词查询计划。
- Apollo.io 决策人联系信息补充适配器示例。
- 支持配置 endpoint 或本地 fixture 的商业地产与职位信号适配器示例。
- `BusinessRecord` 统一承载公司、位置、联系信息、来源、地产、联系人和增长信号字段。
- 基于公司、地址、网站、电话和 Google Place ID 的去重与主记录匹配。
- SQLite upsert、稳定 CSV 字段顺序和可选 Google Sheets 输出。
- 对在线调用进行有界验证，并生成不含凭据值的状态报告。

## 架构

![Adapter-to-export pipeline flow](docs/assets/pipeline-flow.png)

`src.main` 是 CLI 编排入口。它读取设置，选择合成数据或 Google Places 采集路径，将记录转换为 `BusinessRecord`，随后依次调用去重、主记录合并、SQLite 保存和导出组件。Apollo、商业地产和职位信号模块是经过独立测试的适配器示例；当前 CLI 在线采集路径编排 Google Places，在线输出路径可编排 Google Sheets。

这种分层使新增来源保持在适配器边界内，也让持久化和导出可以依靠统一记录结构独立验证。更完整的子系统说明见[架构文档](.monkeycode/docs/ARCHITECTURE.md)。

## 快速开始

要求 Python 3.9 或更高版本。

```bash
# 安装运行时与测试依赖
python3 -m pip install -r requirements.txt -r requirements-dev.txt

# 运行不写入数据库或外部目标的合成数据流程
python3 -m src.main --dry-run --use-sample-data

# 将合成记录保存到 SQLite 并导出确定性 CSV
python3 -m src.main --use-sample-data --csv-output data/output/master_records.csv
```

默认合成输入来自 `data/sample/business_records.json`。第二条运行命令会写入本地 SQLite 和 CSV，请在可写的项目目录执行。

## 配置

以 `.env.example` 为字段清单，在本地 `.env` 中配置准备启用的路径。凭据只通过环境变量或明确的本地凭据文件进入运行时。

| 变量 | 用途 |
|---|---|
| `GOOGLE_PLACES_API_KEY` | 启用 Google Places 在线搜索 |
| `GOOGLE_PLACES_API_VERSION` | 选择 `new` 或 `legacy` API 模式 |
| `APOLLO_API_KEY` | 启用 Apollo.io 适配器调用 |
| `GOOGLE_SHEETS_CREDENTIALS_JSON` | 运行时提供 Google 服务账号 JSON |
| `GOOGLE_SHEETS_NAME` / `GOOGLE_SHEETS_WORKSHEET` | 指定电子表格和工作表 |
| `SCRAPER_QUERY` / `SCRAPER_LOCATION` | 配置单次搜索和可选经纬度位置偏置 |
| `SCRAPER_SEARCH_AREAS` / `SCRAPER_RADIUS_METERS` | 配置查询计划区域和搜索半径 |
| `USE_QUERY_PLAN` | 启用确定性区域与关键词扩展 |
| `COMMERCIAL_PROPERTY_ENDPOINT` / `COMMERCIAL_PROPERTY_SAMPLE_PATH` | 配置商业地产来源或 fixture |
| `JOB_SIGNALS_ENDPOINT` / `JOB_SIGNALS_SAMPLE_PATH` | 配置职位信号来源或 fixture |
| `SQLITE_DB_PATH` | 指定本地 SQLite 状态文件 |
| `DRY_RUN` | 校验记录并跳过持久化与导出 |
| `USE_SAMPLE_DATA` / `SAMPLE_DATA_PATH` | 启用并指定合成离线记录 |

Google Places 和 Google Sheets 的在线流程均由使用者主动启用，并要求本地凭据。Google API 响应、账户权限和配额属于外部服务边界。

## 可靠性设计

- 所有 HTTP 请求设置 30 秒有限超时，适配器和在线验证脚本限制结果数量。
- 样本输入路径被约束在 `data/sample` 内，降低意外读取其他本地文件的风险。
- Pydantic 在记录进入合并、持久化和导出阶段前执行类型校验。
- 地址规范化、稳定公司标识、来源历史合并和 SQLite 冲突更新支持可重复运行。
- CSV 与 Google Sheets 共用固定导出表头；Google Sheets 验证会检查实际写入范围。
- 自动化测试覆盖正常路径以及空响应、畸形输入、请求失败和配置缺失等失败路径。

## 验证与测试

```bash
# 一键运行完整测试，再运行离线合成数据 dry-run
python3 -m scripts.verify_portfolio

# 运行确定性完整套件并避免生成 bytecode 与 pytest cache
PYTHONDONTWRITEBYTECODE=1 python3 -m pytest -p no:cacheprovider -q

# 单独验证离线编排路径
PYTHONDONTWRITEBYTECODE=1 python3 -m src.main --dry-run --use-sample-data
```

**Verified locally（本地验证）**：当前 61 项完整作品集测试套件由 51 项业务管道基线测试与 10 项作品集文档与验证契约组成；离线合成数据摘要为 2 条合成离线记录、0 失败。Python 3.11 手动流水线已通过；对应的 [Gitee Go 成功构建记录](https://gitee.com/szzhoujiarui/python-data-orchestration-lab/gitee_go/pipelines/builds/86314/view)需登录 Gitee 后查看。在线验证脚本位于 `scripts/`，仅在本地准备对应 Google 凭据后运行。

## 实现范围

这是一个面向生产思维的可执行演示，用于证明模块边界、确定性数据处理、持久化、导出、失败报告和测试策略。它以 CLI 和本地状态为交付形态，未提供托管生产数据服务、调度基础设施、多租户权限、持续监控或外部服务 SLA。真实部署需要客户侧的凭据管理、数据合规审查、运行环境、调度与可观测性方案。

## 项目结构

```text
src/
  adapters/       适配器契约、四个来源实现或示例、统一类型模型
  exports/        CSV 与 Google Sheets 输出
  records/        确定性主记录匹配与合并
  storage/        SQLite 持久化
  utils/          地址规范化、去重与日志
  main.py         CLI 编排入口
scripts/          有界在线集成验证脚本
data/sample/      合成离线 fixtures
tests/            单元、工作流、集成边界和文档契约测试
```

## 文档

- [架构](.monkeycode/docs/ARCHITECTURE.md)：运行流、子系统和安全边界。
- [接口](.monkeycode/docs/INTERFACES.md)：模块接口与数据契约。
- [开发指南](.monkeycode/docs/DEVELOPER_GUIDE.md)：本地开发与验证流程。
- [English case study](README.md)：完整英文案例文档。

## 许可证

本项目依据 [MIT License](LICENSE) 发布。