# DataOps Platform 数据模型

> 图中“当前”表示已有建库脚本、Alembic 迁移或 Neo4j 读写代码；“目标”仅用于后续迁移设计，尚未部署到生产。

## 1. PostgreSQL 当前表

```mermaid
erDiagram
    users {
        varchar id PK
        varchar username UK
        varchar password "旧认证，仅本地验收"
        boolean is_admin
    }
    data_orders {
        serial id PK
        varchar order_no UK
        varchar status
        integer result_product_id "逻辑引用"
        integer result_dataflow_id "Neo4j 节点 ID"
        integer data_source "Neo4j 节点 ID"
        jsonb graph_analysis
    }
    data_products {
        serial id PK
        varchar product_name
        integer source_dataflow_id "Neo4j 节点 ID"
        varchar target_schema
        varchar target_table
        varchar status
    }
    metadata_review_records {
        bigserial id PK
        bigint business_domain_id "Neo4j 节点 ID"
        varchar record_type
        varchar status
        jsonb new_meta
        jsonb old_meta
        jsonb resolution_payload
    }
    metadata_version_history {
        bigserial id PK
        bigint meta_id "Neo4j 节点 ID"
        jsonb before_snapshot
        jsonb after_snapshot
        varchar created_by
    }
    task_list {
        serial task_id PK
        varchar task_name
        varchar status
        varchar create_by
    }
    datasource_credentials {
        uuid id PK
        uuid data_source_uid
        integer credential_version
        bytea encrypted_payload
        bytea nonce
        varchar key_version
        varchar status
    }
    datasource_credential_audit_events {
        bigserial id PK
        uuid data_source_uid
        integer credential_version
        varchar event_type
        varchar actor_uid
        text safe_detail
    }
    data_orders }o--o| data_products : "result_product_id（当前无 FK）"
    datasource_credentials ||--o{ datasource_credential_audit_events : "data_source_uid / credential_version"
```

当前脚本没有为跨表逻辑引用建立外键；跨 Neo4j 引用使用内部节点 ID，存在节点重建后失效风险。下一阶段必须引入稳定业务 UUID，内部节点 ID 仅用于查询加速，不作为长期契约。

## 2. Neo4j 当前治理图

```mermaid
flowchart LR
    BD["BusinessDomain"] -->|"COME_FROM"| DS["DataSource"]
    BD -->|"INCLUDES"| META["DataMeta"]
    BD -->|"LABEL"| LABEL["DataLabel"]
    META -->|"LABEL"| LABEL
    META -->|"ALIAS"| PRIMARY["DataMeta 主对象"]
    BD -->|"INPUT"| DF["DataFlow"]
    DF -->|"OUTPUT"| TARGET["BusinessDomain"]
```

唯一方向约定：

- `BusinessDomain-[:COME_FROM]->DataSource`
- `BusinessDomain-[:INCLUDES]->DataMeta`
- `BusinessDomain-[:INPUT]->DataFlow`
- `DataFlow-[:OUTPUT]->BusinessDomain`
- 治理对象 `-[:LABEL]->DataLabel`
- 别名 `alias DataMeta-[:ALIAS]->primary DataMeta`

遗留查询和注释中若出现反方向假设，应在下一阶段以自动化图模型契约测试消除。

### DataSource 安全字段约定

Neo4j `DataSource` 节点保存 `uid`、类型、主机、端口、数据库、schema、
TLS 白名单选项、连接池覆盖项、`credential_ref` 和 `credential_version`。
节点不允许保存 `username`、`password`、`conn_str`、`connection_string`
或 `connection_url`。`credential_ref` 指向平台 PostgreSQL 中相同
`data_source_uid` 的当前不可变凭据版本：

```mermaid
flowchart LR
    DS["Neo4j DataSource\nuid + credential_version"] -->|"逻辑引用"| CRED["PostgreSQL datasource_credentials\nAES-256-GCM 密文"]
    CRED --> AUDIT["datasource_credential_audit_events\n不含密钥的审计明细"]
    DS --> POOL["Worker 本地池键\nuid + version + fingerprint"]
```

数据库约束保证同一数据源每个 `credential_version` 唯一，且同一数据源最多
一个 `active` 版本。密文使用数据源 UID 和版本号作为认证附加数据，不能复制到
另一个数据源或版本后解密。删除生产凭据表不属于本轮范围。

## 3. 已实施的 PostgreSQL 增量表

下表均已由 `migrations/` 中的 Alembic 版本链创建，不再只是设计目标。

| 表 | 核心字段 | 约束/用途 |
|---|---|---|
| `users` | `id UUID`, `username`, `password_hash`, `status` | 替换旧明文/可逆密码字段 |
| `roles` | `id`, `code` | 固定 `admin/editor/viewer`，即管理员、编辑者、查看者 |
| `user_roles` | `user_id`, `role_id` | 用户与角色映射 |
| `governance_responsibility_scopes` | `resource_type`, `resource_uid`, `revision`, `updated_by` | 业务域、设备、本体、映射、故障分类和质量问题的责任矩阵版本 |
| `governance_responsibility_assignments` | `scope_id`, `user_id`, `responsibility_role`, `raci_role` | Owner、Steward、架构师、设备资产管理员与 RACI 责任绑定 |
| `governance_responsibility_audit_events` | `resource_type`, `resource_uid`, `actor_uid`, `before_state`, `after_state` | 责任矩阵变更前后快照与操作审计 |
| `dataflow_workflow_versions` | `id`, `dataflow_uid`, `environment`, `version_no`, `n8n_workflow_id`, `status` | 一个 DataFlow 对多个 n8n Workflow 版本 |
| `governance_documents` | `object_type`, `object_uid`, `object_version`, `content_hash` | 治理对象文本快照 |
| `governance_chunks` | `document_id`, `chunk_no`, `content`, `embedding vector` | Qwen Embedding 结果 |
| `governance_sync_jobs` | `mode`, `cursor`, `status`, `error` | 增量同步和每日全量一致性巡检 |
| `knowledge_query_audits` | `query_hash`, `user_id`, `roles`, `business_domain_uids`, `mode`, `retriever_counts`, `cited_points`, `degraded_components`, `correlation_id`, `latency_ms` | 最小化知识查询审计；不保存原始问题、回答或证据内容 |
| `knowledge_evaluation_sets/cases/runs/results` | `case_type`, `allowed_business_domains`, `expected_sources`, `expected_answer_points`, `must_refuse`, `metrics`, `citations` | 版本化检索、问答、授权与拒答验收证据 |
| `workbench_layouts` | `user_id`, `layout_version`, `widgets jsonb` | 按用户保存有限标准组件布局 |
| `outbox_events` | `event_id`, `aggregate_type`, `aggregate_id`, `payload`, `published_at` | 跨存储最终一致性 |
| `datasource_credentials` | `data_source_uid`, `credential_version`, `encrypted_payload`, `nonce`, `key_version`, `status` | 外部数据源不可变加密凭据 |
| `datasource_credential_audit_events` | `data_source_uid`, `credential_version`, `event_type`, `actor_uid`, `safe_detail` | 不含秘密的凭据及连接池审计 |
| `ingestion_sources` | `uid`, `source_type`, `config`, `permission_scope` | 数据库、文件、DDL 采集来源 |
| `source_artifacts` | `source_uid`, `content_hash`, `storage_ref`, `parser_version` | MinIO 原件/工件索引与哈希去重 |
| `ingestion_jobs` | `idempotency_key`, `status`, `attempt_count`, `failure_stage`, `statistics`, `last_error` | 可重复执行、可诊断、可重试的采集状态机 |
| `catalog_snapshots` | `job_uid`, `source_uid`, `attempt`, `content_hash`, `snapshot` | 每次数据库目录采集的不可变结构快照 |
| `evidence_fragments` | `artifact_uid`, `locator`, `excerpt`, `confidence` | 页、表、行列、坐标级证据 |
| `extraction_candidates` | `normalized_data`, `evidence_uids`, `confidence`, `status` | 解析候选项 |
| `data_elements` | `code`, `current_version`, `status`, `business_domain_uids` | 稳定数据元素身份与生命周期 |
| `data_element_versions` | `data_element_uid`, `version`, `snapshot`, `evidence_uids` | 不可变数据元素版本 |
| `candidate_decisions` | `candidate_uid`, `action`, `data_element_uid`, `actor_uid` | `reuse/create/map/ignore` 决策审计 |
| `device_assets` | `uid`, `asset_type`, `name`, `current_version`, `content_hash`, `location`, `organization`, `responsible_person`, `attributes` | 设备、部件、测点、告警和维护记录的稳定平台档案 |
| `device_asset_source_mappings` | `asset_uid`, `source_uid`, `source_entity`, `asset_type`, `source_code`, `source_updated_at` | 源系统身份映射；同一来源身份唯一，不在 WP-04 自动跨源合并 |
| `device_asset_versions` | `asset_uid`, `version`, `content_hash`, `snapshot`, `source_mapping_uid`, `actor_uid` | 设备资产不可变版本和变更来源追溯 |
| `device_semantic_codes` | `ontology_uid`, `code_type`, `canonical_code`, `canonical_name`, `status`, `current_version`, `source_mappings`, `evidence_uids`, `suggestion_source`, `confidence` | 故障、原因、措施规范代码；按本体、类型、代码保持唯一身份 |
| `device_semantic_code_versions` | `code_uid`, `version`, `snapshot`, `created_by` | 设备语义代码不可变版本；修订只追加、不覆盖历史 |
| `device_semantic_code_reviews` | `code_uid`, `version`, `decision`, `reason`, `actor_uid` | 设备资产负责人对代码版本的批准或退回审计 |
| `device_entity_match_candidates` | `left_asset_uid`, `right_asset_uid`, `canonical_asset_uid`, `status`, `suggestion_source`, `confidence`, `explanation`, `evidence_uids`, `current_version` | 跨来源实体匹配候选；开放候选对唯一，规则与 AI 候选共用受治理生命周期 |
| `device_entity_match_reviews` | `candidate_uid`, `version`, `decision`, `reason`, `actor_uid` | 人工批准、拒绝或严格门禁自动批准的不可变审核证据 |
| `device_entity_merge_events` | `candidate_uid`, `canonical_asset_uid`, `member_asset_uid`, `review_uid`, `snapshot` | 非破坏性主资产关联及合并前证据快照，不改写设备资产和来源映射 |
| `device_entity_merge_rollbacks` | `merge_uid`, `candidate_uid`, `reason`, `snapshot`, `actor_uid` | 每次合并最多一个追加式回滚事件；原合并事件保留 |
| `device_quality_profiles` | `uid`, `name`, `created_by` | 设备台账与故障质量策略的稳定身份 |
| `device_quality_profile_versions` | `profile_uid`, `version`, `status`, `rules`, `content_hash`, `published_by` | 七类封闭规则的不可变版本；只允许一个生效发布版本 |
| `device_quality_runs` | `policy_version_uid`, `policy_hash`, `source_uid`, `total_assets`, `total_violations`, `score` | 绑定精确策略版本和检查范围的不可变质量执行 |
| `device_quality_rule_results` | `run_uid`, `rule_code`, `evaluated_count`, `violation_count`, `pass_rate`, `weighted_score` | 每条启用规则的精确计数和得分贡献 |
| `device_quality_violation_samples` | `run_uid`, `rule_code`, `asset_uid`, `field_name`, `source_mapping_uid`, `evidence`, `expires_at` | 每条规则最多 100 条脱敏违规样本，保留 30 天 |
| `device_quality_asset_scores` | `run_uid`, `asset_uid`, `evaluated_rule_count`, `violation_count`, `score` | 按适用规则计算的资产级质量评分 |
| `device_quality_issues` | `source_violation_uid`, `asset_uid`, `recurrence_key`, `status`, `assignee_uid`, `due_at`, `current_version` | 从违规证据形成的整改问题、状态、责任和复发身份 |
| `device_quality_issue_remediations` | `issue_uid`, `round_number`, `summary`, `evidence_refs`, `review_status`, `reviewed_by` | 追加式整改轮次和独立复核结果 |
| `device_quality_issue_timeline` | `issue_uid`, `action`, `from_status`, `to_status`, `actor_uid`, `payload` | 质量问题不可变处理时间线 |
| `device_operational_events` | `source_uid`, `source_entity`, `source_code`, `event_type`, `asset_uid`, `component_uid`, `occurred_at`, `evidence_refs`, `content_hash` | 告警、故障、维修和停机事件的不可变来源证据 |
| `device_evidence_relations` | `from_kind`, `from_uid`, `relation_type`, `to_kind`, `to_uid`, `evidence_refs`, `source` | 设备资产、运行事件和质量问题之间的有向证据关系 |
| `ontologies` | `code`, `owner_uid`, `draft_revision`, `active_version_uid` | 本体稳定身份和生效版本 |
| `ontology_versions` | `ontology_uid`, `version`, `parent_version_uid`, `graph_document`, `content_hash` | 不可变本体版本 |
| `ontology_domain_links` | `ontology_uid`, `domain_uid`, `role` | 多业务域 owner/contributor/consumer 关系 |
| `ontology_change_sets` | `base_version_uid`, `changes`, `decisions`, `status` | 动态建议及人工决策 |
| `ontology_publish_runs` | `version_uid`, `idempotency_key`, `validation_result`, `status` | 幂等发布运行 |

环境级唯一生效约束：`UNIQUE (dataflow_uid, environment) WHERE status = 'active'`，保证同一环境只允许一个当前生效版本。

## 4. 数据治理知识库映射

| 治理对象 | 来源 | 文档标识 | 触发方式 |
|---|---|---|---|
| 业务域定义 | Neo4j `BusinessDomain` | `business_domain:{uid}` | 变更后增量同步 |
| 数据流程定义 | Neo4j `DataFlow` + 版本映射 | `dataflow:{uid}:{version}` | 变更/激活后增量同步 |
| 元数据定义 | Neo4j `DataMeta` | `metadata:{uid}` | 审核落库后增量同步 |
| 数据标准/标签 | Neo4j | `standard/label:{uid}` | 变更后增量同步 |
| 全量校验 | Neo4j + PostgreSQL | 内容哈希 | 每日全量一致性巡检 |
| 设备资产与运行事件 | PostgreSQL `device_assets`、授权后的来源映射和运行事件 | `device:{uid}:v{version}` | 查询时按数据源业务域直接检索，不复制事件原始证据 |

向量由 Qwen 的 embedding 模型生成；DeepSeek 只负责生成式问答。召回结果必须携带对象类型、业务域、版本、更新时间和访问范围，回答必须返回来源对象。

设备检索以 PostgreSQL canonical 数据为源真相：`ingestion_sources.permission_scope.business_domains`
为空时仅管理员可见；普通用户查询必须先在 SQL 的 `authorized_sources` 范围内完成来源
映射、事件聚合和文本匹配，候选进入 RRF 后再次按访问上下文授权。设备证据只包含平台
UID、名称、授权源 ID、位置、组织、责任人和授权事件类型/标题/源 ID，不包含数据源配置、
设备扩展属性、事件 `evidence_refs` 或凭据。LightRAG 仍是影子投影，不能绕过 canonical
授权、直接回答或阻断 canonical 发布。

问答只允许模型选择已召回证据的引用索引；引用无效、证据不足或模型不可用时回答为空，
页面仍可展示当前用户有权访问的检索证据。每次已执行检索和问答必须成功写入
`knowledge_query_audits`，但只保存规范化问题的 SHA-256、身份/角色/授权域、检索模式、
检索器计数、引用知识点身份、降级组件、关联 ID 和耗时。

## 5. 所有权与删除规则

- PostgreSQL 是身份、权限、映射、任务状态、布局和一致性事件的源真相。
- Neo4j 是治理对象结构和血缘的源真相。
- MinIO 是附件原件的源真相；PostgreSQL 只保存对象键和元数据。
- n8n 是 Workflow 定义与执行记录的源真相；平台保存治理映射和生效状态。
- 本体与数据元素的发布版本以 PostgreSQL 为源真相；Neo4j 是可重建的已发布语义投影。
- 设备资产、源编码映射和不可变版本以 PostgreSQL 为源真相；跨来源匹配、合并与回滚在 WP-06 经审核后实施。
- 实体匹配候选、审核、主资产关联和回滚证据以 PostgreSQL 为源真相；合并是可撤销关系，不删除、不搬迁设备资产、来源映射或历史版本。
- 规则自动合并默认关闭，只允许显式开闸后的确定性规则高置信度候选；AI 候选始终进入人工审核。
- 设备质量策略版本、执行结果、规则计数、违规样本和资产评分以 PostgreSQL 为源真相；检查只读设备资产和已发布语义代码，不修改来源台账。
- 质量问题、整改轮次和处理时间线以 PostgreSQL 为源真相；问题保存 WP-07 违规的安全证据快照，状态变更采用乐观锁，关闭必须由 `quality_issue/DEVICE_QUALITY_ISSUES` 唯一负责的设备资产管理员独立复核。逾期由期限和未关闭状态实时计算，复发由规则、资产和字段的确定性身份统计，不等同于自动根因结论。
- 设备运行事件和有向证据关系以 PostgreSQL 为源真相；关系图是最多三跳、100 个节点和 200 条边的可重建查询投影。根因分析只沿 `indicates`、`triggered` 和 `evidences` 上游关系返回候选及证据路径；没有持久化路径时必须返回“证据不足，无法确认根因”，结果不触发自动修复或维修计划。
- 设备知识检索直接读取授权后的 PostgreSQL canonical 资产、来源映射和运行事件；不建立第二份设备主数据，不读取来源配置和事件原始证据。问答不能替代 WP-09 的证据路径或设备专家根因结论。
- 设备本体、故障/原因/措施代码身份、不可变代码版本和审批记录以 PostgreSQL 为源真相；Neo4j 只接收通过发布门禁的本体投影。
- `DEVICE_SEMANTIC` 本体发布必须同时通过通用图校验、设备语义覆盖度校验和设备资产负责人校验；代码审批复用同一责任矩阵门禁。
- 本轮只清理代码和建库脚本。生产表必须在数据核查、备份和依赖确认后以独立变更单下线。