DATA_MODEL.md 19 KB
DataOps Platform 数据模型
图中“当前”表示已有建库脚本、Alembic 迁移或 Neo4j 读写代码；“目标”仅用于后续迁移设计，尚未部署到生产。
1. PostgreSQL 当前表
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 当前治理图
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]->DataSourceBusinessDomain-[:INCLUDES]->DataMetaBusinessDomain-[:INPUT]->DataFlowDataFlow-[: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 的当前不可变凭据版本：
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 和耗时。
4.1 WP11 治理运营指标查询投影
WP11 不新增指标快照表，也不允许人工填报聚合结果。五项指标均在请求时从 PostgreSQL canonical 数据计算，并返回固定定义、分子、分母、比率和可用状态：
| 指标 | 分子 | 分母 |
|---|---|---|
| 台账完整率 | 名称、位置、组织、责任人非空，且至少存在一个授权有效来源映射的在用设备 | 当前用户可见在用设备 |
| 责任覆盖率 | 责任人非空的在用设备 | 当前用户可见在用设备 |
| 实体映射率 | 参与有效且未回滚实体合并的在用设备 | 当前用户可见在用设备 |
| 问题闭环率 | 状态为 closed 的可见质量问题 |
当前用户可见质量问题 |
| 问题复发率 | occurrence_number > 1 的可见质量问题 |
当前用户可见质量问题 |
分母为零时返回 rate = null 和 status = no_data，不能用 0% 替代暂无数据。比率最多保留
六位小数。指标明细只返回设备 UID/名称/类型/位置/组织/责任人、授权来源编码、缺失字段、
有效合并 UID，以及质量问题编号、设备、规则、字段、优先级、状态、发生次数、责任人 UID、
期限、关闭时间和实时逾期标记；不返回 device_assets.attributes、质量问题 message/
evidence、数据源 config/permission_scope 或凭据。
授权沿用知识检索的服务端身份和业务域授权上下文。普通用户只可见映射到
authorized_sources 的在用设备；实体合并只有 canonical/member 两端均可见且没有回滚记录
时才能计入；质量问题优先按其明确 source_uid 或 source_mapping_uid 授权。管理员可统计
全部在用设备和问题。聚合与明细均在 SQL 查询阶段先授权，不依赖前端过滤。
该投影只完成设备域固定运营视图，不代表综合业务域评分、员工绩效、排名趋势、成熟度驾驶舱、 通用 BI、NL2SQL 或分析开发平台已经建设。
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 canonical 数据的实时只读查询投影；不保存人工覆盖值。指标汇总与明细必须使用同一业务域授权边界，跨域合并只有两端均可见时才能计入非管理员结果。
- 设备本体、故障/原因/措施代码身份、不可变代码版本和审批记录以 PostgreSQL 为源真相；Neo4j 只接收通过发布门禁的本体投影。
DEVICE_SEMANTIC本体发布必须同时通过通用图校验、设备语义覆盖度校验和设备资产负责人校验；代码审批复用同一责任矩阵门禁。- 本轮只清理代码和建库脚本。生产表必须在数据核查、备份和依赖确认后以独立变更单下线。