数据治理平台

本项目是一个面向“政策-专利融合分析”的数据治理平台，包含 数据融合 → 数据服务化发布 → 数据可信流通 的完整链路。

• backend/：Python 后端（Flask + SQLAlchemy + Marshmallow + MySQL）
• frontend/：基于 React + Vite 的单页前端，作为平台统一入口
• .gitattributes：Git 行尾配置，确保跨平台一致性

1. 目录总览

• backend/：Python 后端（Flask + SQLAlchemy + Marshmallow + MySQL）
  • app.py：Flask 应用主入口，统一注册所有 API 蓝图
  • config.py、extensions.py、models.py、schemas.py、utils.py：核心配置与工具模块
  • routes/：所有 API 路由模块
    • data_service.py：数据服务 API（已实现，包含查询、统计、导出功能，导出支持 K-匿名和差分隐私）
    • privacy_service.py：隐私保护 API（已实现）
    • synthesis_service.py：合成数据 API（已实现）
    • catalog.py：API 目录管理 API（已实现）
    • agent.py：智能体入口 API（占位）
    • federated.py：联邦学习场景 API（占位）
    • audit.py：审计与数据血缘 API（部分已实现）
  • services/：业务算法实现（隐私保护、合成数据、质量评估）
  • scripts/：数据导入等工具脚本
• frontend/：React + Vite 单页前端
  • src/pages/AgentPage.tsx：智能体页面（已实现）
  • src/pages/FederatedPage.tsx：联邦学习页面（已实现）
  • src/pages/AuditPage.tsx：审计与数据血缘页面（已实现）
  • src/pages/DataQueryPage.tsx：数据查询页面（已实现，支持查询、分页、导出）
  • src/pages/SynthesisPage.tsx：合成数据页面（已实现）

---

2. 快速开始（推荐路径）

2.1 创建并激活 Python 环境（后端）

cd DataGovernance
conda create -n datagovernance python=3.11 -y
conda activate datagovernance
pip install -r requirements.txt

requirements.txt 位于项目根目录，包含 SQLAlchemy / Marshmallow / Flask-Migrate / PyMySQL 等依赖，可支撑整个后端。

2.2 配置数据库连接

推荐使用 MySQL，如无条件可先使用 SQLite。

# PowerShell 示例
$env:DATABASE_URL = "mysql+pymysql://user:[email protected]:3306/data_governance"

如需快速演示（使用 SQLite 文件）：

$env:DATABASE_URL = "lab5_dev.db"  # Config 会自动补齐 sqlite:/// 前缀

2.3 （可选）初始化数据库 & 导入样例数据

首次使用需要初始化 migrations 目录：

# 1. 设置 Flask 应用入口
$env:FLASK_APP = "backend.app:create_app"

# 2. 初始化 migrations 目录（仅首次执行）
flask db init

# 3. 创建初始迁移文件
flask db migrate -m "init schema"

# 4. 应用迁移到数据库
flask db upgrade

后续使用只需执行：

$env:FLASK_APP = "backend.app:create_app"
flask db upgrade

导入样例数据（可选）：

python -m backend.scripts.load_data --excel data/fused_policy_patent_results.xlsx

注意：如果 migrations 目录已存在（例如从旧版本迁移），可跳过 flask db init 步骤，直接执行 flask db migrate 和 flask db upgrade。

2.4 启动统一平台后端

# 使用 backend/app.py 作为统一后端入口
$env:FLASK_APP = "backend.app:create_app"
flask run --debug --port 9000

健康检查：

curl http://127.0.0.1:9000/health

---

3. 安装 Node.js（如果未安装）

前端需要 Node.js 和 npm。如果系统未安装：

Windows 安装方法：

1. 访问 Node.js 官网 下载 LTS 版本（推荐 18.x 或 20.x）
2. 运行安装程序，按默认选项安装（会自动添加到 PATH）
3. 安装完成后，重新打开 PowerShell 终端（重要！）
4. 验证安装：

   node --version  # 应该显示版本号，如 v20.10.0
   npm --version   # 应该显示版本号，如 10.2.3

使用 Chocolatey（如果已安装）：

choco install nodejs-lts

使用 winget（Windows 10/11）：

winget install OpenJS.NodeJS.LTS

4. 启动前端单页应用

$env:PATH = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User");//刷新路径（可正常npm install不必执行）


cd frontend
npm install
npm run dev

在浏览器打开：http://127.0.0.1:5173/

开发模式下，/api 将自动代理到 http://127.0.0.1:9000。如需修改后端地址，可设置：

set VITE_BACKEND_URL=http://127.0.0.1:9001
npm run dev

注意： 前端开发服务器启动前，请确保后端服务已在运行（http://127.0.0.1:9000），否则会出现连接错误。

---

5. 后端模块说明（backend/）

• backend/app.py（已实现）：Flask 应用主入口，创建应用并注册所有蓝图（数据服务、隐私、合成、目录、智能体、联邦、审计等），仅提供 REST API。
• backend/config.py（已实现）：后端配置模块，封装数据库连接（MySQL/SQLite）、SQL 回显、JSON 编码、合成数据条数上限等参数。
• backend/extensions.py（已实现）：Flask 扩展初始化模块，提供全局的 db（SQLAlchemy）、ma（Marshmallow）实例。
• backend/models.py（已实现）：ORM 模型定义：
  • PolicyPatentLink：政策-专利融合结果表，支撑数据服务 /api/v1/service/policy-links 等。
  • SyntheticDataset：合成数据集元信息表，用于记录合成结果与质量评估。
  • PrivacyAuditLog：隐私操作审计表，记录脱敏、K-匿名、差分隐私等行为。
  • DataCatalog：API 目录表，用于注册与管理所有对外数据服务。
• backend/schemas.py（已实现）：Marshmallow 序列化定义，负责模型到 JSON 的转换（如 PolicyPatentLinkSchema、SyntheticDatasetSchema、DataCatalogSchema）。
• backend/utils.py（已实现）：通用工具函数，主要包括统一响应格式（success_response / error_response）与分页参数校验函数 validate_pagination。
• backend/routes/（已实现）
  • __init__.py：定义所有蓝图（data_service_bp、privacy_bp、synthesis_bp、catalog_bp、agent_bp、federated_bp、audit_bp），并设置各自的 URL 前缀。
  • data_service.py（已实现）：数据服务 API，包括政策-专利关联的查询、统计、导出，以及数据目录视图与 /api-info 结构说明。蓝图前缀：/api/v1/service。
    • 查询功能：支持按区域、关键词、共同token数量等条件筛选，支持分页
    • 导出功能：支持 CSV/JSON 格式导出，默认使用 K-匿名 隐私保护（对准标识符进行泛化），也可选择 差分隐私（对数值字段添加噪声）
    • 导出参数：
      • privacy_method: k_anonymity（默认）或 differential_privacy
      • k: K-匿名参数（默认 5）
      • epsilon: 差分隐私参数（默认 1.0）
  • privacy_service.py（已实现）：隐私保护 API，包括脱敏、K-匿名、差分隐私三个接口，并写入 PrivacyAuditLog。蓝图前缀：/api/v1/privacy。
  • synthesis_service.py（已实现）：合成数据 API，包括规则合成、统计合成与质量评估，依赖 SyntheticDataset 与合成算法。蓝图前缀：/api/v1/synthesis。
  • catalog.py（已实现）：API 目录管理 API，可注册、查询、更新、删除目录项，并支持自动批量注册现有服务。蓝图前缀：/api/v1/catalog。
  • agent.py（已实现）：智能体入口 API POST /api/v1/agent/entry，当前根据自然语言 goal 返回调用计划（未自动执行）。
  • federated.py（已实现）：联邦学习场景 API POST /api/v1/federated/scenario，返回联邦训练计划草案（未接入真实框架）。
  • audit.py（部分已实现，没有画图）：审计与血缘 API：
    • GET /api/v1/audit/events：从 PrivacyAuditLog 读取隐私操作审计记录（已实现）。
    • GET /api/v1/audit/lineage：返回“源数据 → 融合表 → 服务 API”的血缘示意结构（占位）。
• backend/services/（实现）
  • privacy.py：隐私保护算法核心实现，包括字段脱敏（mask/keep_last/hash）、K-匿名 KACA 算法、差分隐私拉普拉斯机制。
  • synthesis.py：合成数据算法实现，包含基于规则与基于统计分布的两类生成方式。
  • evaluation.py：合成数据质量评估算法，用于比较真实数据与合成数据的统计特征。
  • dataclean.ipynb、test2.py、test3.py：实验/调试脚本与笔记本（仅供开发参考，不影响主流程）。
• backend/scripts/（已实现）
  • load_data.py：将融合结果 Excel 导入数据库的脚本，使用方式：python -m backend.scripts.load_data --excel data/fused_policy_patent_results.xlsx。

---

6. 前端模块说明（frontend/）

• frontend/index.html（已实现）：前端单页应用 HTML 容器，挂载 React 根节点 #root。
• frontend/vite.config.ts（已实现）：Vite 构建与开发配置，包含 React 插件与 /api 到后端 http://127.0.0.1:9000 的代理规则。
• frontend/src/main.tsx（已实现）：前端入口，创建 React 根并挂载 App，使用 BrowserRouter 管理路由。
• frontend/src/App.tsx（已实现）：应用主布局，提供顶部标题和左侧导航，路由到三个核心页面：智能体入口、联邦学习场景、审计与数据血缘。
• frontend/src/api/client.ts（已实现）：前端 API 客户端封装：
  • 统一创建 Axios 实例 api，baseURL 为 /api/v1。
  • 提供 callAgentEntry、createFederatedScenario、fetchAuditEvents、fetchLineage 等函数封装具体接口调用。
• frontend/src/pages/AgentPage.tsx（已实现）：
  • UI：提供文本框输入自然语言 goal，展示后端返回的解析结果与计划步骤。
  • 调用：POST /api/v1/agent/entry（当前后端逻辑为占位规划，未真正执行后续 API 调用）。
• frontend/src/pages/FederatedPage.tsx（已实现）：
  • UI：配置任务名、轮数和参与节点，展示联邦训练计划草案。
  • 调用：POST /api/v1/federated/scenario（当前后端逻辑为占位）。
• frontend/src/pages/AuditPage.tsx（已实现）：
  • 左侧表格展示 /api/v1/audit/events 返回的隐私审计日志。
  • 右侧以 JSON 形式展示 /api/v1/audit/lineage 返回的数据血缘结构（可用于后续图形化展示）。
• frontend/src/pages/DataQueryPage.tsx（已实现）：
  • 提供数据查询界面，支持按区域、关键词、共同token数量筛选
  • 支持分页浏览，页面切换立即响应
  • 支持导出 CSV/JSON 格式（自动应用 K-匿名或差分隐私保护）
  • 显示数据统计信息（按区域统计）
• frontend/src/pages/SynthesisPage.tsx（已实现）：
  • 提供合成数据生成界面，支持基于规则和基于统计的合成方法
  • 支持合成数据质量评估
• frontend/src/styles.css（已实现）：统一 UI 主题与响应式布局，包含侧边导航、卡片、表格和 JSON 视图样式。
• frontend/tsconfig.json（已配置）：TypeScript 配置，包含 @types/node 类型定义
• frontend/vite.config.ts（已配置）：Vite 配置，包含代理设置和错误处理

---

7. 实现状态说明

• 已实现：功能完整，可直接使用

  • 数据融合（backend/lab4 中的脚本，可独立运行）
  • 数据服务化发布（backend/routes/data_service.py、privacy_service.py、synthesis_service.py、catalog.py）
  • 数据查询与导出（frontend/src/pages/DataQueryPage.tsx，支持 K-匿名和差分隐私保护）
  • 合成数据生成与评估（frontend/src/pages/SynthesisPage.tsx）
  • 前端核心页面（AgentPage.tsx、FederatedPage.tsx、AuditPage.tsx、DataQueryPage.tsx、SynthesisPage.tsx）
  • 审计事件列表（backend/routes/audit.py 的 /events 接口）
  • 隐私保护功能（K-匿名、差分隐私、数据脱敏）

• 占位：接口已定义，返回示例数据，但核心逻辑未实现

  • 智能体自动编排执行（backend/routes/agent.py，当前只返回计划）
  • 联邦学习训练（backend/routes/federated.py，当前只返回计划草案）
  • 数据血缘可视化（backend/routes/audit.py 的 /lineage 接口，当前只返回静态结构）

---

8. 主要功能说明

8.1 数据查询与导出

查询功能：

• 支持按实施区域、关键词、最小共同token数量筛选
• 支持分页浏览，每页可设置 10/20/50/100 条记录
• 页面切换立即响应，无延迟

导出功能：

• 支持 CSV 和 JSON 格式导出
• 默认使用 K-匿名隐私保护：
  • 对准标识符（实施区域、共同token数）进行泛化处理
  • 确保每组至少有 k 条记录，无法识别单个个体
  • 默认 k=5，可通过参数调整
• 可选差分隐私保护：
  • 对数值字段（共同token数）添加拉普拉斯噪声
  • 保护统计信息的同时保持数据可用性
  • 默认 epsilon=1.0，可通过参数调整

导出 API 示例：

# 使用 K-匿名（默认）
GET /api/v1/service/policy-links/export?format=csv&area=北京&privacy_method=k_anonymity&k=5

# 使用差分隐私
GET /api/v1/service/policy-links/export?format=json&privacy_method=differential_privacy&epsilon=1.0

8.2 隐私保护方法

平台支持三种隐私保护方法：

1. 数据脱敏（Masking）：对敏感字段进行掩码、哈希或部分保留
2. K-匿名（K-Anonymity）：通过泛化确保每组至少有 k 条记录
3. 差分隐私（Differential Privacy）：对数值添加噪声，保护统计信息

8.3 开发注意事项

• 行尾配置：项目使用 .gitattributes 确保跨平台一致性，所有文本文件使用 LF 行尾
• TypeScript 配置：前端已配置 @types/node，支持 Node.js 类型定义
• 代理配置：Vite 开发服务器自动代理 /api 到后端，包含错误处理和超时设置
• 启动顺序：先启动后端（端口 9000），再启动前端（端口 5173）

---