Главная Обзор Помощь
Вход
mxl_citu
/
DataOps-platform
1
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Дерево: 10e42a080d
Ветки Метки
DataOps-plat...
/
docs
/
superpowers
/
plans
/
2026-07-23-ontology-workbench-complete-chain.md

2026-07-23-ontology-workbench-complete-chain.md 9.5 KB
История Исходник

Ontology Workbench Complete Chain Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将现有“新建本体 + JSON 文本框”升级为可加载、可编辑、可校验、可比较、可回滚、可评审建议、可导入导出的完整本体治理工作台。

Architecture: PostgreSQL 继续作为本体、版本、变更集和发布状态的权威控制面；现有发布服务继续通过 Outbox 投影到 Neo4j。后端补充只读详情、版本、草稿和数据元素查询契约，并让动态建议返回可评审的变更集 UID；前端使用 Vue 2 + Vuetify 结构化编辑六类图数据，同时保留 JSON 高级模式。

Tech Stack: Flask、SQLAlchemy、PostgreSQL、Vue 2、Vuetify 2、Axios、Python pytest、Node 24、Docker Compose。

Global Constraints

  • 不新增前端框架或第三方 UI 依赖，复用现有 Vuetify 与 MDI。
  • 已发布版本不可原地修改；编辑始终创建新草稿版本。
  • 草稿保存必须使用 If-Match 修订号，冲突时重新加载而不是静默覆盖。
  • viewer 只读，editor 可编辑/校验/建议评审，admin 才能发布和回滚。
  • 动态建议必须显示来源、置信度和证据，并经过逐项接受/拒绝后才应用到草稿。
  • 导入支持 JSON/OWL 文件；导出支持 JSON/OWL 下载。
  • 所有生产代码先有失败测试，再做最小实现。

Task 1: 本体详情、版本与草稿读取契约

Files:

  • Modify: app/core/data_research/ontology/repository.py
  • Modify: app/core/data_research/ontology/publication.py
  • Modify: app/api/data_development/routes.py
  • Test: tests/data_research/test_ontology_api.py
  • Test: tests/data_research/test_ontology_repository.py

Interfaces:

  • Produces: repository.list_versions(ontology_uid) -> list[OntologyVersion]
  • Produces: GET /api/development/v1/ontologies/<uid>
  • Produces: GET /api/development/v1/ontologies/<uid>/versions

  • Produces: GET /api/development/v1/ontologies/<uid>/graph with ETag

  • [ ] Step 1: Write failing repository and API tests

def test_detail_versions_and_graph_are_readable(client):
    detail = client.get("/api/development/v1/ontologies/ontology-1")
    versions = client.get("/api/development/v1/ontologies/ontology-1/versions")
    graph = client.get("/api/development/v1/ontologies/ontology-1/graph")
    assert detail.status_code == 200
    assert versions.get_json()["data"][0]["graph_document"]["classes"]
    assert graph.headers["ETag"] == '"2"'
  • Step 2: Run tests and verify missing routes fail

Run: PYTHONPATH=. .venv/bin/pytest -q tests/data_research/test_ontology_api.py tests/data_research/test_ontology_repository.py

Expected: FAIL because detail/version/GET graph contracts do not exist.

  • Step 3: Implement repository/service/routes

Return ontology metadata with latest/active version summaries; return versions newest first; return the latest graph plus the ontology draft revision in ETag.

  • Step 4: Run tests and verify green

Run: PYTHONPATH=. .venv/bin/pytest -q tests/data_research/test_ontology_api.py tests/data_research/test_ontology_repository.py

Expected: PASS.

Task 2: 可选择的数据元素与动态建议变更集契约

Files:

  • Modify: app/core/data_research/repository.py
  • Modify: app/core/data_research/data_elements.py
  • Modify: app/core/data_research/ontology/change_sets.py
  • Modify: app/api/data_development/routes.py
  • Test: tests/data_research/test_data_element_lifecycle.py
  • Test: tests/data_research/test_ontology_dynamic_api.py

Interfaces:

  • Produces: GET /api/development/v1/data-elements?status=published&business_domain_uid=<uid>
  • Produces: suggestion response {change_set_uid, suggestions}

  • Consumes: decision payload {decisions: [{suggestion_uid, decision, reason, payload?}]}

  • [ ] Step 1: Write failing list and change-set response tests

  • [ ] Step 2: Run focused tests and verify expected failures

  • [ ] Step 3: Add filtered repository listing and return persisted change-set UID

  • [ ] Step 4: Run focused tests and verify green

Run: PYTHONPATH=. .venv/bin/pytest -q tests/data_research/test_data_element_lifecycle.py tests/data_research/test_ontology_dynamic_api.py

Expected: PASS.

Task 3: 前端状态模型与 API 客户端

Files:

  • Create: frontend/src/views/dataGovernance/ontology/model.js
  • Modify: frontend/src/api/dataDevelopment.js
  • Test: frontend/tests/ontology-workbench-model.test.mjs
  • Test: tests/test_frontend_contract.py

Interfaces:

  • Produces: emptyGraph(), normalizeGraph(), applySuggestionDecisions(), canEditOntology(), canPublishOntology()

  • Produces API methods: getOntology, getOntologyGraph, getOntologyVersions, getDataElements, reviewOntologyChangeSet, importOntology, exportOntology

  • [ ] Step 1: Write Node tests for graph normalization, suggestion application and permissions

test('viewer is read-only and only publisher can publish', () => {
  assert.equal(canEditOntology(['governance:read']), false)
  assert.equal(canEditOntology(['ontologies:edit']), true)
  assert.equal(canPublishOntology(['ontologies:edit']), false)
  assert.equal(canPublishOntology(['ontologies:publish']), true)
})
  • Step 2: Run Node tests and verify module is missing

Run: node --experimental-default-type=module --test tests/ontology-workbench-model.test.mjs

Expected: FAIL with module not found.

  • Step 3: Implement pure state helpers and API methods
  • Step 4: Run Node and Python frontend-contract tests

Run: node --experimental-default-type=module --test tests/ontology-workbench-model.test.mjs

Expected: PASS.

Task 4: 结构化本体中心与工作台

Files:

  • Modify: frontend/src/views/dataGovernance/ontology/index.vue
  • Rewrite: frontend/src/views/dataGovernance/ontology/workbench.vue
  • Create: frontend/src/views/dataGovernance/ontology/components/GraphSectionEditor.vue
  • Create: frontend/src/views/dataGovernance/ontology/components/VersionWorkspace.vue
  • Test: tests/test_frontend_contract.py

Interfaces:

  • Consumes: Task 1-3 APIs and helpers.

  • Produces: detail load, section editing, domain selection, element mapping, JSON advanced mode, save, validate, publish, diff and rollback UI.

  • [ ] Step 1: Add failing source-contract assertions for every workflow control

  • [ ] Step 2: Run contract test and verify missing controls fail

  • [ ] Step 3: Implement center-page domain selection and permission-aware creation

  • [ ] Step 4: Implement workbench header, six section editors and advanced JSON mode

  • [ ] Step 5: Implement save/reload/conflict handling, validation results and permission-aware publish

  • [ ] Step 6: Implement version history, version pair selection, diff display and admin rollback

  • [ ] Step 7: Run contract tests and production build

Run: PYTHONPATH=. .venv/bin/pytest -q tests/test_frontend_contract.py

Run: npm run build

Expected: PASS/build exit 0.

Task 5: 动态建议评审与导入导出

Files:

  • Modify: frontend/src/views/dataGovernance/ontology/workbench.vue
  • Create: frontend/src/views/dataGovernance/ontology/components/SuggestionReviewDialog.vue
  • Modify: app/api/data_development/routes.py
  • Test: tests/data_research/test_ontology_dynamic_api.py
  • Test: tests/test_frontend_contract.py

Interfaces:

  • Consumes: {change_set_uid, suggestions} from Task 2.

  • Produces: suggestion generate/review/apply flow and multipart JSON/OWL import.

  • [ ] Step 1: Write failing tests for multipart import and suggestion-review controls

  • [ ] Step 2: Run focused tests and verify expected failures

  • [ ] Step 3: Accept multipart uploads while preserving raw-body compatibility

  • [ ] Step 4: Implement suggestion payload input, evidence/confidence display and immutable decisions

  • [ ] Step 5: Implement JSON/OWL file import and download actions

  • [ ] Step 6: Run focused tests and production build

Expected: PASS/build exit 0.

Task 6: Docker integration and browser acceptance

Files:

  • Modify: tests/integration/test_data_research_docker_api.py
  • Modify: docs/validation/data-research-v60-v65-acceptance.md

Interfaces:

  • Verifies the complete user path through http://localhost:18183.

  • [ ] Step 1: Rebuild backend and frontend containers

Run: docker compose -f deploy/docker/docker-compose.yml up -d --build backend frontend

  • Step 2: Run live Docker API integration

Run: RUN_DATA_RESEARCH_DOCKER_API=1 TEST_BACKEND_URL=http://127.0.0.1:18183/api TEST_DATABASE_URL=postgresql://dataops:dataops-test-password@127.0.0.1:15432/dataops TEST_ADMIN_PASSWORD=AdminPass123 PYTHONPATH=. .venv/bin/pytest -q tests/integration/test_data_research_docker_api.py

Expected: PASS.

  • Step 3: Run browser flow

Flow: 本体中心 → 新建/选择本体 → 加载现有草稿 → 编辑一个概念 → 保存 → 校验 → 查看版本差异 → 生成并评审建议 → 导出 → 管理员发布。

  • Step 4: Run full regression

Run: PYTHONPATH=. .venv/bin/pytest -q

Run: node --experimental-default-type=module --test frontend/tests/ontology-workbench-model.test.mjs

Run: npm --prefix frontend run build

Expected: all tests pass and build exits 0; only documented pre-existing warnings remain.

  • Step 5: Commit
git add app frontend tests docs
git commit -m "feat: complete ontology workbench workflow"