# yaan-gov-data-platform

**Repository Path**: Chester_Xue/yaan-gov-data-platform

## Basic Information

- **Project Name**: yaan-gov-data-platform
- **Description**: 雅安政务大数据管理平台 - 本地模拟原型。模拟政务数据从多部门产生、汇聚、治理到共享开放的全流程。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-03
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 雅安政务大数据管理平台（本地模拟原型）

> 模拟政务数据从多部门产生、汇聚、治理到共享开放的全流程，体验数据中台 **"汇、通、用"** 的核心逻辑。  
> 所有组件跑在本地 Docker 容器里，给旧笔记本用也扛得住（总计 ~1GB 内存占用）。

---

## 整体架构

```
┌─────────────────────────────────────────────────────────────────────┐
│                        数据源层（业务库）                            │
│  ┌────────────────────────┐     ┌──────────────────────────────┐   │
│  │  社保业务数据库        │     │  工商业务数据库              │   │
│  │  (MySQL:3306)          │     │  (MySQL:3306)               │   │
│  │  insurance_records     │     │  company_info               │   │
│  │  5,000 条社保缴费记录   │     │  200 条企业注册信息          │   │
│  └───────────┬────────────┘     └─────────────┬────────────────┘   │
└──────────────┼────────────────────────────────┼────────────────────┘
               │                                │
               ▼                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│                    ETL 数据汇聚层（Python）                           │
│                                                                      │
│  ① Extract                   ② Transform                   ③ Load  │
│  ┌──────────────┐    ┌─────────────────────┐    ┌──────────────┐    │
│  │ Pandas       │    │ • 空值填充（均值）    │    │ SQLAlchemy   │    │
│  │ SQLAlchemy   │───▶│ • 身份证号格式校验   │───▶│ to_sql()     │    │
│  │ read_sql()   │    │ • 企业名称关联匹配   │    │              │    │
│  └──────────────┘    │ • 公民维度汇总       │    └──────────────┘    │
│                      └─────────────────────┘                        │
└───────────────────────────────┬──────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│                    数据仓库层（PostgreSQL:5432）                      │
│                                                                      │
│  ┌────────────────────────────────────────────────────────────┐      │
│  │  ODS 层（操作数据存储）                                     │      │
│  │  ├── ods.ods_insurance_records  — 社保原始记录（5,000条）    │      │
│  │  └── ods.ods_company_info       — 企业原始信息（200条）      │      │
│  ├────────────────────────────────────────────────────────────┤      │
│  │  DW 层（数据仓库 — 清洗后宽表）                               │      │
│  │  ├── dw.dw_fact_insurance       — 企业综合宽表（5,000条）    │      │
│  │  └── dw.dw_dim_citizen          — 公民维度汇总（5,000条）    │      │
│  └────────────────────────────────────────────────────────────┘      │
└───────┬───────────────────────────────────────────┬──────────────────┘
        │                                           │
        ▼                                           ▼
┌──────────────────────────┐    ┌──────────────────────────────────────┐
│    数据开放层             │    │      数据服务层                      │
│                          │    │                                      │
│  MinIO 对象存储          │    │  FastAPI RESTful 服务                │
│  (localhost:9001)        │    │  (localhost:8000)                    │
│  ┌────────────────────┐  │    │  ┌──────────────────────────────┐   │
│  │ open-data 存储桶    │  │    │  │ GET  /health               │   │
│  │ ├ enterprise.csv   │  │    │  │ GET  /api/stats             │   │
│  │ ├ citizen.csv      │  │    │  │ GET  /api/company/{id}      │   │
│  │ └ insurance.csv    │  │    │  │ GET  /api/citizen/{id}      │   │
│  └────────────────────┘  │    │  │ GET  /api/citizen/{id}/rec  │   │
│                          │    │  │ GET  /api/catalog            │   │
│  Grafana 可视化面板      │    │  │ GET  /metrics (Prometheus)   │   │
│  (localhost:3000)        │    │  └──────────────────────────────┘   │
│                          │    │                                      │
│  Prometheus 监控         │    │  🔐 Token 认证模拟                  │
│  (localhost:9090)        │    │  📊 Prometheus 指标采集             │
└──────────────────────────┘    └──────────────────────────────────────┘
```

---

## 技术栈

| 层次 | 组件 | 技术选型 | 说明 |
|------|------|----------|------|
| 🐳 **容器编排** | Docker / Docker Compose | v29.6 / v5.3 | 每个容器都设了内存上限 |
| 🗄️ **业务数据库** | MySQL 8.0 | 官方镜像 | 拆成 shebao（社保）和 gongshang（工商）两个库 |
| 🏛️ **数据仓库** | PostgreSQL 15 | Alpine 镜像 | ODS 层存原始数据，DW 层存清洗后的宽表 |
| 🔄 **ETL 引擎** | Python 3.11 | Pandas + SQLAlchemy | 抽取→清洗空值/校验格式/关联→加载 |
| 🌐 **API 服务** | FastAPI + Uvicorn | 异步框架 | 7 个接口，Token 认证，挂 Prometheus 指标 |
| 📦 **对象存储** | MinIO | 最新版 | S3 兼容，存开放数据集 |
| 📊 **可视化** | Grafana + Prometheus | Alpine 镜像 | 容器监控 + 数据仓库查询 |
| 🎭 **模拟数据** | Faker (zh_CN) | 中文数据引擎 | 身份证/企业名/社保记录，还掺了点脏数据 |
| 🔧 **运维脚本** | Bash | 启动/停止脚本 | 一键启停，自动初始化 |

---

## 服务端口与凭据

| 服务 | 端口 | 访问地址 | 用户名 | 密码 |
|------|------|----------|--------|------|
| FastAPI 数据服务 | 8000 | `http://localhost:8000` | Token: `yaan-token-2024` | — |
| Grafana 可视化 | 3000 | `http://localhost:3000` | `admin` | `yaanadmin123` |
| MinIO 对象存储 | 9001 | `http://localhost:9001` | `yaan_admin` | `yaanadmin123` |
| Prometheus 监控 | 9090 | `http://localhost:9090` | — | — |
| MySQL 业务库 | 3306 | `localhost:3306` | `root` | `yaan123` |
| PostgreSQL 数据仓库 | 5432 | `localhost:5432` | `yaan_admin` | `yaan123` |

---

## 快速启动

### 前置条件

- Docker >= 24.0（含 Docker Compose 插件）
- Python 3.8+
- 4GB+ RAM, 20GB+ 磁盘空间

### 一键启动

```bash
# 克隆或进入项目目录
cd yaan-gov-data-platform/

# 一键启动（自动完成 容器→数据→API 全流程）
bash start.sh
```

启动脚本自动完成：
1. 检查 Docker 环境 → 2. 启动 5 个容器 → 3. 等待数据库就绪 →  
4. **首次运行**：创建数据库、生成模拟数据（200 企业 + 5000 社保记录）、执行 ETL、上传开放数据 →  
5. 启动 API 服务 → 6. 输出所有服务地址和凭据

### 分步启动

```bash
# 1. 启动 Docker 容器
docker compose up -d

# 2. 生成模拟数据
python3 data/generate_data.py

# 3. 执行 ETL 流程
python3 etl/run_etl.py

# 4. 导出 CSV 并上传到 MinIO
python3 scripts/export_csv.py
# 然后通过 MinIO Console 或 mc 命令上传 CSV

# 5. 启动 API 服务
python3 api/main.py
```

### 停止服务

```bash
bash stop.sh
# 停止 API 进程 + 停止所有 Docker 容器
# 如需清理数据: docker compose down -v
```

---

## 数据流详解

### 数据生成 → ETL → 服务 → 开放

```
┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│  生成     │   │  抽取    │   │  清洗    │   │  加载    │   │  服务    │
│  模拟数据  │──▶│ Extract  │──▶│ Transform│──▶│   Load   │──▶│   API   │
│  Faker   │   │  MySQL   │   │  Pandas  │   │PostgreSQL│   │ FastAPI  │
└──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
                                                                    │
                         ┌──────────────────────────────────────────┘
                         ▼
                   ┌──────────┐
                   │  开放    │
                   │  MinIO   │
                   └──────────┘
```

### ETL 处理细节

| 步骤 | 操作 | 说明 |
|------|------|------|
| Extract | 从 MySQL 抽取 | 全量抽取 insurance_records(5,000) + company_info(200) |
| Transform ① | 空值填充 | monthly_base 缺失值 → 均值 13,984.88 元填充（182 条） |
| Transform ② | 身份证校验 | 检测 50 条格式异常身份证号（末位替换为非法字符） |
| Transform ③ | 企业关联 | 通过 company_name 左连接，匹配率 100% |
| Transform ④ | 公民维度 | 按 citizen_id 聚合，生成 dw_dim_citizen |
| Load | PostgreSQL | ODS 层保留原始结构，DW 层写入清洗后宽表 |

---

## API 接口文档

### 接口一览

| 接口 | 方法 | 说明 | 需 Token |
|------|------|------|----------|
| `/` | GET | 服务信息及所有接口列表 | 否 |
| `/health` | GET | 健康检查（返回数据库连接状态） | 否 |
| `/api/catalog` | GET | 数据开放目录（描述所有开放数据集） | 否 |
| `/api/company/{id}` | GET | 企业综合信息（含社保参保人数和平均基数） | 是 |
| `/api/citizen/{citizen_id}` | GET | 公民社保缴费汇总 | 是 |
| `/api/citizen/{citizen_id}/records` | GET | 公民详细社保缴费记录 | 是 |
| `/api/stats` | GET | 数据仓库统计信息 | 是 |
| `/metrics` | GET | Prometheus 监控指标 | 否 |

### 认证方式

```bash
# Token 认证（模拟政务网安全认证）
curl -H "Authorization: Bearer yaan-token-2024" http://localhost:8000/api/stats
```

### 测试示例

```bash
# 健康检查
curl http://localhost:8000/health

# 查询企业信息（需 Token）
curl -H "Authorization: Bearer yaan-token-2024" http://localhost:8000/api/company/1

# 查询数据仓库统计
curl -H "Authorization: Bearer yaan-token-2024" http://localhost:8000/api/stats

# 查询数据目录（无需 Token）
curl http://localhost:8000/api/catalog
```

### API 响应示例

```json
// GET /api/company/1
{
  "id": 1,
  "company_name": "雅安维涛环保有限公司",
  "unified_social_credit_code": "91511800Q853QJL13E",
  "legal_representative": "王丹",
  "registered_capital": 25292.5,
  "establish_date": "1991-03-11",
  "employee_count": 20,
  "avg_salary_base": 11620.33
}

// GET /api/stats
{
  "ods.ods_insurance_records": 5000,
  "ods.ods_company_info": 200,
  "dw.dw_fact_insurance": 5000,
  "dw.dw_dim_citizen": 5000,
  "参保企业数": 200,
  "参保公民数": 5000,
  "平均缴费基数": 13984.88
}
```

---

## 数据开放目录

MinIO `open-data` 存储桶中已上传的 CSV 数据集：

| 数据集 | 文件名 | 记录数 | 文件大小 | 开放类型 |
|--------|--------|--------|----------|----------|
| 企业综合信息 | `enterprise_comprehensive.csv` | 200 | 17 KB | 无条件开放 |
| 公民社保缴费信息 | `citizen_social_security.csv` | 5,000 | 368 KB | 有条件开放 |
| 社保缴费明细 | `insurance_records_detail.csv` | 5,000 | 666 KB | 授权开放 |

访问方式：`http://localhost:9001`（凭据见上表）

---

## 数据质量报告摘要

| 维度 | 评分 | 说明 |
|------|------|------|
| 完整性 | ⭐⭐⭐⭐☆ (4/5) | monthly_base 空值率 3.64%（已填充） |
| 准确性 | ⭐⭐⭐⭐⭐ (5/5) | 身份证号格式错误率 1%（模拟异常） |
| 一致性 | ⭐⭐⭐⭐⭐ (5/5) | 企业名称 100% 匹配 |
| **综合评分** | **4.6 / 5.0** | 详见 `reports/data_quality_report.md` |

---

## 数据仓库分层

```
ODS 层（操作数据存储 — 保持原始结构）
├── ods.ods_insurance_records  — 社保缴费原始记录（5,000 条）
└── ods.ods_company_info       — 企业注册原始信息（200 条）

DW 层（数据仓库 — 清洗后宽表）
├── dw.dw_fact_insurance       — 企业+社保综合宽表（5,000 条）
└── dw.dw_dim_citizen          — 公民社保维度汇总（5,000 条）
```

---

## 项目结构

```
yaan-gov-data-platform/
│
├── start.sh / stop.sh              ← 一键启动/停止脚本（符号链接）
├── docker-compose.yml              ← Docker 容器编排（6 个服务）
├── Dockerfile.api                  ← API 镜像构建
├── requirements.api.txt            ← API Python 依赖
│
├── data/
│   ├── generate_data.py            ← 模拟数据生成（Faker 中文）
│   └── export/                     ← CSV 导出目录
│
├── etl/
│   └── run_etl.py                  ← ETL 全流程脚本
│
├── api/
│   └── main.py                     ← FastAPI 应用（7 接口 + Token 认证）
│
├── scripts/
│   ├── start.sh                    ← 完整启动脚本（含初始化逻辑）
│   ├── stop.sh                     ← 停止脚本
│   ├── export_csv.py               ← CSV 导出脚本
│   └── upload_minio.py             ← MinIO 上传脚本
│
├── config/
│   └── mysql/init/01_init.sql      ← MySQL 初始化
│
├── grafana/
│   ├── datasources/                ← 数据源自动配置
│   └── dashboards/                 ← 预置仪表盘
│
├── prometheus/
│   └── prometheus.yml              ← 监控配置
│
├── reports/
│   └── data_quality_report.md      ← 数据质量报告
│
└── README.md                       ← 本文件
```

---

## 环境要求与资源控制

| 项目 | 要求 |
|------|------|
| 最低配置 | 4GB RAM, 20GB 磁盘, 双核 CPU |
| 推荐配置 | 8GB RAM, 40GB 磁盘 |
| 容器内存限制 | MySQL 256m / PostgreSQL 256m / MinIO 256m |
| | Grafana 128m / Prometheus 128m / API 256m |
| 总计占用 | ~1.5GB RAM |
| Python 版本 | 兼容 3.8+（使用 3.11 开发） |
| 操作系统 | Linux (Ubuntu 22.04 开发), macOS, WSL2 |

---

## License

MIT