# 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**

```python
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**

```javascript
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**

```bash
git add app frontend tests docs
git commit -m "feat: complete ontology workbench workflow"
```