openclaw
b67780007c
Covers GAP-B1 (status mapping), GAP-B3 (compound graph with document nodes), GAP-F1 (group-partitioned layout), GAP-F2 (rich detail panel), GAP-F3 (legend), GAP-F4 (back button), GAP-F5 (edit shortcut). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
431 lines
15 KiB
Markdown
431 lines
15 KiB
Markdown
# V2 Gap Fix Design — 7 Gaps (P0+P1)
|
||
|
||
Date: 2026-03-24
|
||
Branch: `feat/v2-fix-gaps`
|
||
Status: Design
|
||
|
||
## 1. Problem Statement
|
||
|
||
The current graph visualization has three critical issues:
|
||
1. All 63 nodes share a single `forceCenter`, producing a "hairball" layout with no group separation
|
||
2. All node statuses are hardcoded to `"unknown"` — node colors are meaningless grey
|
||
3. DesignDocument upstream/downstream edges are dead code (file paths vs node IDs mismatch)
|
||
|
||
Additionally, the detail panel is nearly empty, there's no way to return from drill-down, no edit shortcut, and no legend.
|
||
|
||
## 2. Design Decisions
|
||
|
||
### DD-1: Architecture Layer Layout (方案 A)
|
||
Y-axis represents abstraction level, matching TOGAF/ArchiMate conventions:
|
||
|
||
```
|
||
group_id targetX(ratio) targetY(ratio)
|
||
business 0.50 0.15
|
||
application 0.50 0.38
|
||
data 0.30 0.65
|
||
technology 0.70 0.65
|
||
cross-layer 0.50 0.85
|
||
```
|
||
|
||
### DD-2: Compound Graph for Document View
|
||
- Document nodes are containers; entity nodes nest inside their parent document
|
||
- Toggle between default (group-partitioned) and document view modes
|
||
- Both doc→doc edges and entity→entity edges coexist
|
||
|
||
### DD-3: Status Mapping via source_file
|
||
- Entity type → source CSV file → FileStatus from ScanResult
|
||
- Same-CSV entities share that file's status (one CSV = one entity type's completeness)
|
||
|
||
## 3. Gap Specifications
|
||
|
||
---
|
||
|
||
### 3.1 GAP-B1: Node Status Mapping
|
||
|
||
**Layer:** Backend
|
||
**Priority:** P0
|
||
**File:** `backend/app/modules/graph/application/services.py`
|
||
|
||
**Current behavior:** `GraphService.build_panorama()` hardcodes `status="unknown"` for all nodes.
|
||
|
||
**Target behavior:** Each node gets its status from the Scanner's `FileStatus` for the source CSV file that contains that entity type.
|
||
|
||
**Implementation:**
|
||
|
||
1. Build `file_status_map: dict[str, str]` from `scan_result.file_statuses`:
|
||
```python
|
||
file_status_map = {fs.path: fs.status.value for fs in scan_result.file_statuses}
|
||
```
|
||
|
||
2. Define entity-type-to-source-file mapping (from `design/data-architecture/01-entities.csv`):
|
||
```python
|
||
_SOURCE_FILES = {
|
||
"capability": "business-architecture/02-capability-map.csv",
|
||
"module": "application-architecture/02-modules.csv",
|
||
"entity": "data-architecture/01-entities.csv",
|
||
"runtime_component": "technology-architecture/01-runtime-components.csv",
|
||
}
|
||
```
|
||
|
||
3. When creating each node:
|
||
```python
|
||
status = file_status_map.get(_SOURCE_FILES.get(node_type, ""), "unknown")
|
||
```
|
||
|
||
**Acceptance criteria:**
|
||
- Nodes have real status values (ok/sparse/missing/template-residue/placeholder-heavy) instead of "unknown"
|
||
- Nodes without a known source file retain "unknown"
|
||
|
||
---
|
||
|
||
### 3.2 GAP-B3: DesignDocument Edges — Compound Graph
|
||
|
||
**Layer:** Backend
|
||
**Priority:** P0
|
||
**File:** `backend/app/modules/graph/domain/entities.py`, `backend/app/modules/graph/application/services.py`
|
||
|
||
**Current behavior:** Step 9 in `build_panorama()` tries to match `doc.upstream`/`doc.downstream` (file paths like `./02-capability-map.csv`) against node IDs. Always fails because (a) paths ≠ IDs and (b) DesignDocuments are never added as nodes.
|
||
|
||
**Target behavior:**
|
||
1. DesignDocument objects become graph nodes (type="document", group="cross-layer")
|
||
2. Entity nodes get a `parent` field pointing to their containing document's `doc_id`
|
||
3. Two edge types: doc→doc (relation="documents") and entity→entity (existing relations unchanged)
|
||
|
||
**Domain model change — GraphNode:**
|
||
```python
|
||
@dataclass
|
||
class GraphNode:
|
||
id: str
|
||
type: str # capability | module | entity | runtime_component | document
|
||
label: str
|
||
status: str
|
||
group_id: str
|
||
parent: str | None = None # doc_id of containing document, if any
|
||
```
|
||
|
||
**Implementation in build_panorama():**
|
||
|
||
Step 5.5 — Create document nodes:
|
||
```python
|
||
file_to_doc: dict[str, str] = {}
|
||
for doc in scan_result.design_documents:
|
||
file_to_doc[doc.source_file] = doc.doc_id
|
||
nodes.append(GraphNode(
|
||
id=doc.doc_id,
|
||
type="document",
|
||
label=doc.title or doc.doc_id,
|
||
status=file_status_map.get(doc.source_file, "unknown"),
|
||
group_id="cross-layer",
|
||
))
|
||
node_ids.add(doc.doc_id)
|
||
```
|
||
|
||
Entity nodes get parent:
|
||
```python
|
||
parent_doc_id = file_to_doc.get(_SOURCE_FILES.get(node_type))
|
||
node = GraphNode(..., parent=parent_doc_id)
|
||
```
|
||
|
||
Step 9 — Fix doc→doc edges using file path mapping:
|
||
```python
|
||
path_to_doc = {doc.source_file: doc.doc_id for doc in scan_result.design_documents}
|
||
for doc in scan_result.design_documents:
|
||
for up_path in doc.upstream:
|
||
normalized = up_path.lstrip("./")
|
||
up_doc_id = path_to_doc.get(normalized)
|
||
if up_doc_id and up_doc_id in node_ids:
|
||
edges.append(GraphEdge(source=up_doc_id, target=doc.doc_id, relation="documents"))
|
||
for down_path in doc.downstream:
|
||
normalized = down_path.lstrip("./")
|
||
down_doc_id = path_to_doc.get(normalized)
|
||
if down_doc_id and down_doc_id in node_ids:
|
||
edges.append(GraphEdge(source=doc.doc_id, target=down_doc_id, relation="documents"))
|
||
```
|
||
|
||
**Acceptance criteria:**
|
||
- Document nodes appear in the graph (type="document", group="cross-layer")
|
||
- Entity nodes have correct `parent` references
|
||
- doc→doc edges are created based on upstream/downstream file path resolution
|
||
- API response includes `parent` field (null for nodes without a parent)
|
||
|
||
---
|
||
|
||
### 3.3 GAP-F1: Group-Partitioned Layout + Compound Layout
|
||
|
||
**Layer:** Frontend
|
||
**Priority:** P0
|
||
**File:** `frontend/src/modules/graph/components/GraphPanorama.vue`
|
||
|
||
**Current behavior:** Single `d3.forceCenter()` for all nodes — all groups overlap.
|
||
|
||
**Target behavior:** Two layout modes controlled by a toggle.
|
||
|
||
#### Default Mode (Document View OFF)
|
||
|
||
- Filter out nodes where `type === "document"` and edges where `relation === "documents"`
|
||
- Use `d3.forceX` / `d3.forceY` per group with strength ~0.3-0.5:
|
||
```js
|
||
const groupPositions = {
|
||
business: { x: 0.50, y: 0.15 },
|
||
application: { x: 0.50, y: 0.38 },
|
||
data: { x: 0.30, y: 0.65 },
|
||
technology: { x: 0.70, y: 0.65 },
|
||
'cross-layer': { x: 0.50, y: 0.85 },
|
||
}
|
||
|
||
simulation
|
||
.force('x', d3.forceX(d => groupPositions[d.group_id].x * width).strength(0.4))
|
||
.force('y', d3.forceY(d => groupPositions[d.group_id].y * height).strength(0.4))
|
||
.force('collide', d3.forceCollide(30))
|
||
.force('link', d3.forceLink(edges).id(d => d.id).distance(60))
|
||
```
|
||
- Remove the single `forceCenter` — forceX/forceY provide the centering per group
|
||
|
||
#### Document View Mode (Toggle ON)
|
||
|
||
- Show all nodes including documents
|
||
- Document nodes rendered as large `<rect>` containers, sized by child count:
|
||
```js
|
||
const childCount = nodes.filter(n => n.parent === doc.id).length
|
||
doc.width = Math.max(150, childCount * 60)
|
||
doc.height = Math.max(100, childCount * 40)
|
||
```
|
||
- Document containers participate in force simulation (with high mass to resist movement)
|
||
- Entity nodes with `parent` are constrained inside their parent's bounds on each tick:
|
||
```js
|
||
simulation.on('tick', () => {
|
||
nodes.forEach(n => {
|
||
if (n.parent) {
|
||
const p = nodeMap[n.parent]
|
||
const pad = 20
|
||
n.x = clamp(n.x, p.x - p.width/2 + pad, p.x + p.width/2 - pad)
|
||
n.y = clamp(n.y, p.y - p.height/2 + pad, p.y + p.height/2 - pad)
|
||
}
|
||
})
|
||
})
|
||
```
|
||
- doc→doc edges rendered between container borders
|
||
- entity→entity edges rendered normally (may cross container boundaries)
|
||
|
||
#### Toggle
|
||
|
||
- State: `showDocumentView: ref(false)`
|
||
- UI: Toggle button in toolbar area
|
||
- Switching destroys current simulation and reinitializes with the appropriate mode
|
||
|
||
#### Node Rendering
|
||
|
||
Shapes (both modes):
|
||
| type | shape | size |
|
||
|------|-------|------|
|
||
| capability | circle | r=18 |
|
||
| module | rect | 28×28 |
|
||
| entity | diamond (rotated rect) | 24×24 |
|
||
| runtime_component | circle | r=14 |
|
||
| document | large rect container | dynamic |
|
||
|
||
Colors (by status):
|
||
| status | color |
|
||
|--------|-------|
|
||
| ok | #4CAF50 |
|
||
| sparse | #FFC107 |
|
||
| missing | #F44336 |
|
||
| template-residue | #FF9800 |
|
||
| placeholder-heavy | #9C27B0 |
|
||
| unknown | #9E9E9E |
|
||
|
||
Edge styles:
|
||
| relation | style |
|
||
|----------|-------|
|
||
| traces_to | solid, #666 |
|
||
| depends_on | dashed, #999 |
|
||
| documents | solid, #42A5F5 (blue) |
|
||
| integrates_with | dotted, #AB47BC |
|
||
|
||
**Acceptance criteria:**
|
||
- Default mode: nodes cluster by group in 5 distinct regions, no "hairball"
|
||
- Document view: documents render as containers with entities nested inside
|
||
- Toggle smoothly switches between modes
|
||
- Nodes have correct shapes and colors
|
||
|
||
---
|
||
|
||
### 3.4 GAP-F2: Rich GraphDetail Panel
|
||
|
||
**Layer:** Frontend
|
||
**Priority:** P1
|
||
**File:** `frontend/src/modules/graph/components/GraphDetail.vue`
|
||
|
||
**Current behavior:** Shows only `id, type, status, group_id`.
|
||
|
||
**Target behavior:** Full attribute display + related entity list, fetched from detail APIs.
|
||
|
||
**API calls by node type:**
|
||
| node.type | endpoint | response type |
|
||
|-----------|----------|---------------|
|
||
| capability | `GET /entities/capabilities/{id}` | CapabilityDetail |
|
||
| module | `GET /entities/modules/{id}` | ModuleDetail |
|
||
| entity | `GET /entities/entities/{id}` | EntityDetail |
|
||
| document | no API call, use node properties | — |
|
||
| runtime_component | no API call, use node properties | — |
|
||
|
||
**Panel layout:**
|
||
```
|
||
┌─ GraphDetail ──────────────────────────┐
|
||
│ ✕ Close │
|
||
│ │
|
||
│ ● CAP-001 [Edit] │
|
||
│ capability · business │
|
||
│ │
|
||
│ ── Attributes ── │
|
||
│ name: 项目管理 │
|
||
│ description: 管理项目生命周期... │
|
||
│ owner: ... │
|
||
│ │
|
||
│ ── Related Entities ── │
|
||
│ → MOD-001 项目管理模块 (traces_to) │
|
||
│ → MOD-003 扫描服务 (traces_to) │
|
||
│ ← DOC-005 scope文档 (documents) │
|
||
│ │
|
||
└────────────────────────────────────────┘
|
||
```
|
||
|
||
**Behavior:**
|
||
- On node selection: if type has detail API, fetch it (show spinner while loading)
|
||
- Error fallback: show basic 4 fields
|
||
- Clicking a related entity → updates selected node → panel refreshes
|
||
- Related entities are derived from `graphView.edges` where source or target matches the selected node
|
||
|
||
**Acceptance criteria:**
|
||
- Detail API is called for capability/module/entity nodes
|
||
- All attributes from the API response are displayed
|
||
- Related entities list is clickable and navigates the graph
|
||
- Graceful fallback on API error
|
||
|
||
---
|
||
|
||
### 3.5 GAP-F5: Edit Button in GraphDetail
|
||
|
||
**Layer:** Frontend
|
||
**Priority:** P1
|
||
**File:** `frontend/src/modules/graph/components/GraphDetail.vue`
|
||
|
||
**Current behavior:** No way to jump from graph node to editor.
|
||
|
||
**Target behavior:** "Edit" button in the detail panel header, navigating to the editor page.
|
||
|
||
**Implementation:**
|
||
- Button visible only when `source_file` is available:
|
||
- From detail API response (CapabilityDetail, ModuleDetail, EntityDetail have this field)
|
||
- For document nodes: use node properties
|
||
- For runtime_component: use static `_SOURCE_FILES` mapping
|
||
- Click action:
|
||
```js
|
||
router.push({
|
||
path: `/projects/${projectId}/editor`,
|
||
query: { file: sourceFilePath }
|
||
})
|
||
```
|
||
|
||
**Acceptance criteria:**
|
||
- Edit button appears for nodes with known source files
|
||
- Clicking navigates to editor with correct file pre-selected
|
||
- Button hidden for nodes without source file info
|
||
|
||
---
|
||
|
||
### 3.6 GAP-F4: Back to Panorama Button
|
||
|
||
**Layer:** Frontend
|
||
**Priority:** P1
|
||
**File:** `frontend/src/modules/graph/components/GraphPanorama.vue`
|
||
|
||
**Current behavior:** Double-click drills down to neighbor subgraph; no way to return.
|
||
|
||
**Target behavior:** Floating "back" button in drill-down mode.
|
||
|
||
**Implementation:**
|
||
- State: `isDrillDown: ref(false)`, `drillDownNodeLabel: ref('')`
|
||
- On double-click drill-down: set `isDrillDown = true`, store the node label
|
||
- Render (conditionally):
|
||
```html
|
||
<div v-if="isDrillDown" class="drill-down-bar">
|
||
<button @click="returnToPanorama">← 返回全景图</button>
|
||
<span>当前: {{ drillDownNodeLabel }}</span>
|
||
</div>
|
||
```
|
||
- `returnToPanorama()`: calls existing `loadGraph()` method, sets `isDrillDown = false`
|
||
|
||
**Acceptance criteria:**
|
||
- Button appears only in drill-down mode
|
||
- Shows which node was drilled into
|
||
- Clicking restores the full panorama graph
|
||
|
||
---
|
||
|
||
### 3.7 GAP-F3: Graph Legend
|
||
|
||
**Layer:** Frontend
|
||
**Priority:** P1
|
||
**File:** New `frontend/src/modules/graph/components/GraphLegend.vue`, imported in `GraphPanorama.vue`
|
||
|
||
**Design:**
|
||
```
|
||
┌─ Legend ────────────────────┐
|
||
│ Shapes Status │
|
||
│ ○ Capability ● OK │
|
||
│ ■ Module ● Sparse │
|
||
│ ◇ Entity ● Missing │
|
||
│ ○ Runtime Comp ● Template│
|
||
│ ▭ Document ● Placeholder │
|
||
│ ● Unknown │
|
||
│ Edges │
|
||
│ ── traces_to │
|
||
│ -- depends_on │
|
||
│ ━━ documents │
|
||
│ ·· integrates_with │
|
||
└────────────────────────────┘
|
||
```
|
||
|
||
**Implementation:**
|
||
- Positioned bottom-right of the graph canvas, `position: absolute`
|
||
- Semi-transparent background (`rgba(255,255,255,0.9)`)
|
||
- Collapsible: click title to toggle expand/collapse
|
||
- Default: expanded
|
||
- Uses actual SVG shapes/colors matching the graph rendering
|
||
|
||
**Acceptance criteria:**
|
||
- Legend renders in bottom-right corner
|
||
- Shows all node shapes, status colors, and edge styles
|
||
- Collapsible
|
||
- Does not block graph interaction (pointer-events on legend only)
|
||
|
||
---
|
||
|
||
## 4. Files Changed
|
||
|
||
| File | Change Type | Gaps |
|
||
|------|-------------|------|
|
||
| `backend/app/modules/graph/domain/entities.py` | Modify | B3 |
|
||
| `backend/app/modules/graph/application/services.py` | Modify | B1, B3 |
|
||
| `frontend/src/modules/graph/components/GraphPanorama.vue` | Modify | F1, F4 |
|
||
| `frontend/src/modules/graph/components/GraphDetail.vue` | Modify | F2, F5 |
|
||
| `frontend/src/modules/graph/components/GraphLegend.vue` | New | F3 |
|
||
|
||
## 5. Out of Scope
|
||
|
||
The following gaps from the full analysis are NOT addressed in this spec:
|
||
- GAP-X1 (layered drill-down) — Phase 2
|
||
- GAP-X2 (implementation progress on nodes) — Phase 2
|
||
- GAP-B2 (more entity types as nodes) — separate effort
|
||
- GAP-B4 (recursive impact traversal) — separate effort
|
||
- GAP-B5 (LLM-based impl tracking) — separate effort
|
||
- GAP-F6 (route path alignment) — cosmetic
|
||
- GAP-F7 (panel position conflict) — cosmetic
|
||
|
||
## 6. Constraints
|
||
|
||
1. Do not modify files under `design/` — those are the source of truth
|
||
2. All changes must pass `vue-tsc` (frontend) and Python type checking (backend)
|
||
3. Implementation order follows DDD layers: Domain → Infrastructure → Application → Interfaces
|