docs: fix spec review issues — detail endpoints, serialization, OpenAPI gaps

- 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 <noreply@anthropic.com>

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 缺失，实现时补充 |