From daeffe125deed492febae90b9035b7a031552467 Mon Sep 17 00:00:00 2001 From: openclaw Date: Mon, 23 Mar 2026 14:31:19 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20fix=20spec=20review=20issues=20?= =?UTF-8?q?=E2=80=94=20detail=20endpoints,=20serialization,=20OpenAPI=20ga?= =?UTF-8?q?ps?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Enumerate all 13 entity query endpoints (10 list + 3 detail with join logic) - Add serialization strategy: CSV space-delimited → list[str] in domain and API - Clarify ScanResult internal domain object vs API response split - Add PUT impl-progress/{module_id} for manual override - Note Integration field name mapping (source_id → source in API) - Add MOD-FE-GRAPH phasing note for impl-progress (deferred to Phase 2) - Consolidate impl-progress API calls to MOD-FE-GRAPH (per INT-014) - Add Section 7 documenting all OpenAPI contract discrepancies Co-Authored-By: Claude Opus 4.6 --- .../2026-03-23-full-implementation-design.md | 54 ++++++++++++++++--- 1 file changed, 46 insertions(+), 8 deletions(-) diff --git a/docs/superpowers/specs/2026-03-23-full-implementation-design.md b/docs/superpowers/specs/2026-03-23-full-implementation-design.md index e6c6258..582af50 100644 --- a/docs/superpowers/specs/2026-03-23-full-implementation-design.md +++ b/docs/superpowers/specs/2026-03-23-full-implementation-design.md @@ -29,7 +29,7 @@ | 7 | MOD-IMPL-TRACKER | backend full | MOD-DESIGN, MOD-SCANNER | Phase 2 | | 8 | 前端基础设施 | frontend | - | MVP | | 9 | MOD-FE-PROJECT | frontend | 后端 MOD-PROJECT | MVP | -| 10 | MOD-FE-GRAPH | frontend | 后端 MOD-SCANNER, MOD-GRAPH | MVP | +| 10 | MOD-FE-GRAPH | frontend | 后端 MOD-SCANNER, MOD-GRAPH | MVP（impl-progress 功能延至 Phase 2，依赖 MOD-IMPL-TRACKER） | | 11 | MOD-FE-EDITOR | frontend | 后端 MOD-EDITOR, MOD-IMPL-TRACKER | Phase 2 | | 12 | Docker 部署 | infra | 前后端完成 | MVP | @@ -62,6 +62,8 @@ ### 3.2 MOD-DESIGN（核心领域，纯 Python） +**序列化策略：** CSV 中的空格分隔字段（如 `related_value_flows`、`depends_on`、`capabilities`、`entity_ids`、`value_flow_ids`）在 Python domain 层存储为 `list[str]`。API 响应中也返回为 JSON 数组（`list[str]`），由 router 层负责转换。OpenAPI 契约中这些字段定义为 `string` 是文档缺陷，实现时以 `list[str]` 为准。 + **domain/entities.py** — 28 种设计实体，用 `@dataclass` 定义： ```python @@ -73,7 +75,7 @@ class Capability: description: str priority: str # must / should / could phase: str - related_value_flows: list[str] + related_value_flows: list[str] # CSV 中空格分隔，解析为列表 @dataclass class ValueFlow: @@ -119,8 +121,8 @@ class Module: @dataclass class Integration: integration_id: str - source_id: str - target_id: str + source_id: str # API 响应中序列化为 "source"（兼容 OpenAPI） + target_id: str # API 响应中序列化为 "target"（兼容 OpenAPI） target_type: str direction: str protocol: str @@ -432,6 +434,9 @@ class ScanSummary: @dataclass class ScanResult: + """内部 domain 对象，携带所有解析出的实体。 + API 响应（ScanResultResponse）只包含 project_id, scanned_at, file_statuses, summary。 + 实体数据通过独立的 /entities/* 端点暴露。""" project_id: str scanned_at: datetime file_statuses: list[FileStatusEntry] @@ -487,7 +492,24 @@ class ScanService: """返回内存缓存的最近一次扫描结果""" ``` -**interfaces/http/router.py**：POST/GET scan + 11 个实体查询端点（capabilities, modules, entities, integrations, value-flows, user-journeys, data-flows, external-systems, traceability-links, runtime-components + 单个实体详情端点）。 +**interfaces/http/router.py**：POST/GET scan + 13 个实体查询端点： + +列表端点（10个）： +- GET `.../entities/capabilities` → `list[Capability]` +- GET `.../entities/modules` → `list[Module]` +- GET `.../entities/entities` → `list[Entity]` +- GET `.../entities/integrations` → `list[Integration]` +- GET `.../entities/value-flows` → `list[ValueFlow]` +- GET `.../entities/user-journeys` → `list[UserJourney]` +- GET `.../entities/data-flows` → `list[DataFlow]` +- GET `.../entities/external-systems` → `list[ExternalSystem]` +- GET `.../entities/traceability-links` → `list[TraceabilityLink]` +- GET `.../entities/runtime-components` → `list[RuntimeComponent]` + +详情端点（3个，返回关联数据）： +- GET `.../entities/capabilities/{capability_id}` → `CapabilityDetail`（含关联 modules + value_flows） +- GET `.../entities/modules/{module_id}` → `ModuleDetail`（含 owned_entities + integrations + codebase_alignment） +- GET `.../entities/entities/{entity_id}` → `EntityDetail`（含 data_flows） ### 3.5 MOD-GRAPH @@ -613,7 +635,7 @@ class ImplTrackerService: def set_manual_progress(project_id: str, module_id: str, percentage: float) ``` -**interfaces/http/router.py**：POST/GET impl-progress。 +**interfaces/http/router.py**：POST/GET impl-progress + PUT impl-progress/{module_id}（手动覆盖，OpenAPI 契约中缺失此端点，实现时补充）。 ### 3.8 main.py（应用入口） @@ -705,7 +727,7 @@ routes: [ **composables/useGraph.ts**：Pinia store — graphView, selectedNode, scanResult, loading。 -**api/index.ts**：triggerScan, getLatestScan, getGraph, getNodeNeighbors, + 实体查询 API。 +**api/index.ts**：triggerScan, getLatestScan, getGraph, getNodeNeighbors, + 实体查询 API, + Phase 2: getImplProgress, triggerImplProgress。 ### 4.3 MOD-FE-EDITOR（Phase 2） @@ -721,7 +743,7 @@ routes: [ **composables/useEditor.ts**：Pinia store — currentFile, impactResult, saving。 -**api/index.ts**：getFile, saveFile, getFileImpact, getImplProgress, triggerImplProgress。 +**api/index.ts**：getFile, saveFile, getFileImpact。 ## 5. 部署配置 @@ -758,3 +780,19 @@ volumes: - 前端模块只通过 REST API 与后端通信 - 设计文件是 single source of truth，不引入额外数据库 - 代码仓库只读 + +## 7. OpenAPI 契约偏差说明 + +实现时以本 spec 和 CSV 源数据为准，以下是与 OpenAPI 契约的已知偏差（实现时在 API 响应中包含这些额外字段）： + +| 实体 | 本 spec 有但 OpenAPI 缺失的字段 | 处理方式 | +|------|------|------| +| Capability | description | API 响应中包含 | +| Module | description | API 响应中包含 | +| Entity | description, phase, source_file | API 响应中包含 | +| ValueFlow | actor, phase, related_capabilities | API 响应中包含 | +| UserJourney | actor, phase, related_value_flows | API 响应中包含 | +| ExternalSystem | direction, description, phase | API 响应中包含 | +| Integration | target_type, trigger（字段名 source_id/target_id → API 中用 source/target） | API 响应中包含，字段名用 source/target | +| 多字段 list[str] | related_value_flows, depends_on, capabilities, entity_ids, value_flow_ids | OpenAPI 定义为 string，实现为 JSON array | +| ImplProgress | PUT /{module_id} 端点 | OpenAPI 缺失，实现时补充 |