# DataOps Platform 架构总览

> 状态基线：2026-07-18。本文只描述当前可验证事实和已确认的下一阶段目标，不把占位入口描述为已完成功能。

## 1. 系统边界

DataOps Platform 面向数据治理人员、数据编辑者和数据消费者，负责数据源登记、业务域/元数据/数据流治理、数据产品与订单管理，并通过 n8n 承载流程编排和执行。当前唯一后端源码是 `app/`，前端为 Vue 2；Vue 3 迁移安排在业务能力稳定后的独立阶段。

```mermaid
flowchart LR
    U["管理员 / 编辑者 / 查看者"] --> FE["Vue 前端"]
    FE --> API["Flask API / app/"]
    API --> PG["PostgreSQL\n交易、审核、布局、映射"]
    API --> DSP["外部数据源连接池\nPostgreSQL / MySQL"]
    API --> NEO["Neo4j\n治理对象与血缘图"]
    API --> OBJ["MinIO\n非结构化原件与附件"]
    API --> N8N["n8n\nWorkflow 定义与执行"]
    API --> DS["DeepSeek\n生成与问答"]
    API --> QW["Qwen Embedding\n向量化"]
```

外部模型调用是唯一可选的非本地依赖。没有配置密钥时，本地基础设施、登录和非模型功能仍可验证，且代码不得回退到任何生产地址。

## 2. 容器与代码层级

```mermaid
flowchart TB
    subgraph Browser["浏览器"]
        UI["frontend/src"]
    end
    subgraph Runtime["应用运行时"]
        NGINX["Nginx 静态资源与 /api 代理"]
        ROUTES["app/api 蓝图路由"]
        CORE["app/core 领域逻辑"]
        SERVICES["app/services 基础服务"]
        CONFIG["app/config 环境配置"]
    end
    subgraph Stores["本地隔离数据服务"]
        POSTGRES["平台 PostgreSQL 16\n控制面与凭据密文"]
        SOURCEPG["外部 PostgreSQL\n业务数据"]
        SOURCEMY["外部 MySQL\n业务数据"]
        NEO4J["Neo4j 5"]
        MINIO["MinIO"]
        N8NLOCAL["n8n 1.100.1"]
    end
    UI --> NGINX --> ROUTES
    ROUTES --> CORE
    CORE --> SERVICES
    SERVICES --> CONFIG
    SERVICES --> POSTGRES
    CORE --> SOURCEPG
    CORE --> SOURCEMY
    SERVICES --> NEO4J
    SERVICES --> MINIO
    SERVICES --> N8NLOCAL
```

职责规则：

- `app/api/` 只负责协议转换、参数校验、鉴权和响应封装。
- `app/core/` 承载领域用例；`app/core/data_source/` 负责外部数据源凭据、
  驱动白名单、连接池、熔断和生命周期编排。
- `app/services/` 提供 PostgreSQL、Neo4j、MinIO、n8n 和模型客户端。
- `database/` 是基础建库脚本源；`migrations/` 是已启用的 Alembic 增量迁移链。
- `deployment/app/` 与 `deployment/database/` 是发布镜像，不是编辑源。

## 3. 当前业务闭环

| 能力 | 前端入口 | 后端前缀 | 主要存储 | 当前状态 |
|---|---|---|---|---|
| 数据源 | 数据治理/数据源 | `/api/datasource` | Neo4j 安全定义、PostgreSQL 凭据密文、Worker 本地连接池 | PostgreSQL/MySQL 可用 |
| 业务域 | 数据治理/业务域 | `/api/bd` | Neo4j、PostgreSQL 审核表 | 可用 |
| 元数据 | 元数据详情与审核 | `/api/meta` | Neo4j、PostgreSQL 审核/历史 | 可用 |
| 数据标准与标签 | 数据治理相关页面 | `/api/interface` | Neo4j | 可用 |
| DataFlow 定义 | 数据流程 | `/api/dataflow` | Neo4j | 可用；版本映射待实现 |
| n8n Workflow | n8n 适配页面 | `/api/datafactory` | n8n | 代理可用；首次需本地 API Key |
| 数据产品/订单 | 数据服务 | `/api/dataservice` | PostgreSQL、Neo4j | 可用 |
| 数据安全 | 保留入口 | 无完整接口 | 无 | 占位，不宣称实现 |
| 数据治理知识库 | 保留入口 | 待实现 | PostgreSQL/pgvector、Neo4j | 下一阶段 |
| 工作台 | 首页 | 待完善 | PostgreSQL | 验收样例；下一阶段持久化 |

当前 Flask 路由的机器可读清单和实际数量见 [OPENAPI.yaml](OPENAPI.yaml)，
该文件由路由源码自动生成并由契约测试校验。

## 4. 外部数据源连接池边界

```mermaid
flowchart LR
    ROUTE["数据源 API"] --> SERVICE["DataSourceService"]
    SERVICE --> GRAPH["Neo4j\n无密钥连接定义"]
    SERVICE --> CREDS["平台 PostgreSQL\nAES-256-GCM 凭据版本"]
    USE["元数据 / 质量 / DataFlow"] --> MANAGER["Worker 本地 ConnectionManager"]
    MANAGER --> REGISTRY["惰性 PoolRegistry\n2 + 3 / 数据源 / Worker"]
    REGISTRY --> PGADAPTER["postgresql+psycopg2"]
    REGISTRY --> MYADAPTER["mysql+pymysql"]
    PGADAPTER --> EXTPG["外部 PostgreSQL"]
    MYADAPTER --> EXTMYSQL["外部 MySQL"]
```

- 平台 PostgreSQL 是控制面数据库，沿用应用自身数据库会话，不进入该连接池注册表。
- 外部池按 `数据源 UID + 凭据版本 + 配置指纹` 隔离；一个后端 Worker
  对一个键最多创建一个 Engine。当前单实例使用 2 个 Gunicorn Worker，因此
  总连接预算必须按“单池上限 × Worker 数 × 活跃数据源数”核算。
- 仅允许 PostgreSQL 和 MySQL 固定驱动；客户端不能传入驱动名、任意
  `connect_args` 或自由连接串。
- 查询用途明确区分只读与写入；只读事务回滚，写入事务只执行一次并提交，
  连接失败不会自动重放写事务。
- 连续三次连接失败仅打开对应数据源的熔断器，30 秒后允许一个半开探测。
  故障不会改变平台 PostgreSQL、其他数据源或其他 Worker 的状态。
- 连接定义保存在 Neo4j，但不含用户名、密码或连接串；不可变凭据版本及审计
  事件保存在平台 PostgreSQL。日志、错误和管理诊断均经过脱敏。
- 配置或凭据版本变化会使旧池排空并惰性重建；空闲池 15 分钟回收，每个
  Worker 默认最多保留 20 个空闲池。进程退出时统一关闭。

## 5. 下一阶段目标链路

```mermaid
flowchart LR
    CHANGE["治理对象变更"] --> OUTBOX["PostgreSQL Outbox"]
    OUTBOX --> INDEXER["知识库增量同步"]
    INDEXER --> EMB["Qwen Embedding"]
    EMB --> VECTOR["pgvector"]
    VECTOR --> QA["DeepSeek 问答"]
    AUDIT["每日全量一致性巡检"] --> INDEXER

    DF["DataFlow 治理定义"] --> MAP["版本映射"]
    MAP --> WF1["n8n Workflow v1"]
    MAP --> WF2["n8n Workflow v2"]
    MAP --> ACTIVE["环境级唯一生效版本"]
```

实施顺序、依赖和验收口径见 [NEXT_ITERATION_ROADMAP.md](NEXT_ITERATION_ROADMAP.md)。

## 6. 架构产物索引

- [数据模型](DATA_MODEL.md)
- [部署源真相](DEPLOYMENT_SOURCE_OF_TRUTH.md)
- [前端历史删除清单](FRONTEND_REMOVAL_INVENTORY.md)
- [认证与权限 ADR](ADR-001-authentication.md)
- [DataFlow 与 n8n ADR](ADR-002-workflow-engine.md)
- [跨存储一致性 ADR](ADR-003-cross-store-consistency.md)
- [全本地 Docker 环境](../../deploy/docker/README.md)