877 lines
22 KiB
YAML
877 lines
22 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Arch Design Agent Skill Dashboard API
|
||
version: 0.1.0
|
||
description: 架构设计管理 Dashboard 后端 REST API
|
||
|
||
servers:
|
||
- url: http://localhost:8900
|
||
description: 开发环境
|
||
- url: http://localhost/api
|
||
description: 生产环境（Nginx 反代）
|
||
|
||
paths:
|
||
# === 健康检查 ===
|
||
/api/health:
|
||
get:
|
||
operationId: healthCheck
|
||
summary: 健康检查
|
||
tags: [system]
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
status:
|
||
type: string
|
||
example: ok
|
||
|
||
# === 项目管理 (MOD-PROJECT) ===
|
||
/api/projects:
|
||
get:
|
||
operationId: listProjects
|
||
summary: 列出所有项目
|
||
tags: [project]
|
||
responses:
|
||
"200":
|
||
description: 项目列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Project"
|
||
post:
|
||
operationId: createProject
|
||
summary: 注册新项目
|
||
tags: [project]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/CreateProjectRequest"
|
||
responses:
|
||
"201":
|
||
description: 项目已创建
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Project"
|
||
"400":
|
||
description: 设计目录不存在或路径无效
|
||
|
||
/api/projects/{project_id}:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: getProject
|
||
summary: 获取单个项目详情
|
||
tags: [project]
|
||
responses:
|
||
"200":
|
||
description: 项目详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Project"
|
||
"404":
|
||
description: 项目不存在
|
||
delete:
|
||
operationId: deleteProject
|
||
summary: 删除项目
|
||
tags: [project]
|
||
responses:
|
||
"204":
|
||
description: 已删除
|
||
"404":
|
||
description: 项目不存在
|
||
|
||
# === 扫描 (MOD-SCANNER) ===
|
||
/api/projects/{project_id}/scan:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
post:
|
||
operationId: triggerScan
|
||
summary: 触发扫描
|
||
tags: [scanner]
|
||
responses:
|
||
"200":
|
||
description: 扫描结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ScanResult"
|
||
get:
|
||
operationId: getLatestScan
|
||
summary: 获取最近一次扫描结果（缓存）
|
||
tags: [scanner]
|
||
responses:
|
||
"200":
|
||
description: 缓存的扫描结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ScanResult"
|
||
"404":
|
||
description: 尚未扫描
|
||
|
||
# === 关系图 (MOD-GRAPH) ===
|
||
/api/projects/{project_id}/graph:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: getGraph
|
||
summary: 获取全景关系图
|
||
tags: [graph]
|
||
responses:
|
||
"200":
|
||
description: 全景图数据
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/GraphView"
|
||
|
||
/api/projects/{project_id}/graph/nodes/{node_id}/neighbors:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
- name: node_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: 节点 ID（如 MOD-PROJECT、CAP-SCAN）
|
||
get:
|
||
operationId: getNodeNeighbors
|
||
summary: 下钻查询——获取某节点的所有邻居
|
||
tags: [graph]
|
||
responses:
|
||
"200":
|
||
description: 邻居子图
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/GraphView"
|
||
"404":
|
||
description: 节点不存在
|
||
|
||
# === 实体查询 (MOD-DESIGN via MOD-SCANNER) ===
|
||
/api/projects/{project_id}/entities/capabilities:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: listCapabilities
|
||
summary: 列出所有能力
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 能力列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Capability"
|
||
|
||
/api/projects/{project_id}/entities/capabilities/{capability_id}:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
- name: capability_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
get:
|
||
operationId: getCapability
|
||
summary: 获取单个能力详情（含关联 modules、value-flows）
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 能力详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/CapabilityDetail"
|
||
"404":
|
||
description: 能力不存在
|
||
|
||
/api/projects/{project_id}/entities/modules:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: listModules
|
||
summary: 列出所有模块
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 模块列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Module"
|
||
|
||
/api/projects/{project_id}/entities/modules/{module_id}:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
- name: module_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
get:
|
||
operationId: getModule
|
||
summary: 获取单个模块详情（含关联 capabilities、entities、integrations、codebase-alignment）
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 模块详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ModuleDetail"
|
||
"404":
|
||
description: 模块不存在
|
||
|
||
/api/projects/{project_id}/entities/entities:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: listEntities
|
||
summary: 列出所有数据实体
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 数据实体列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Entity"
|
||
|
||
/api/projects/{project_id}/entities/entities/{entity_id}:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
- name: entity_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
get:
|
||
operationId: getEntity
|
||
summary: 获取单个数据实体详情（含 owner module、data-flows）
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 实体详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EntityDetail"
|
||
"404":
|
||
description: 实体不存在
|
||
|
||
/api/projects/{project_id}/entities/integrations:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: listIntegrations
|
||
summary: 列出所有集成关系
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 集成列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Integration"
|
||
|
||
/api/projects/{project_id}/entities/value-flows:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: listValueFlows
|
||
summary: 列出所有价值流
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 价值流列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ValueFlow"
|
||
|
||
/api/projects/{project_id}/entities/user-journeys:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: listUserJourneys
|
||
summary: 列出所有用户旅程
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 用户旅程列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/UserJourney"
|
||
|
||
/api/projects/{project_id}/entities/data-flows:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: listDataFlows
|
||
summary: 列出所有数据流
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 数据流列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/DataFlow"
|
||
|
||
/api/projects/{project_id}/entities/external-systems:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: listExternalSystems
|
||
summary: 列出所有外部系统
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 外部系统列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ExternalSystem"
|
||
|
||
/api/projects/{project_id}/entities/traceability-links:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: listTraceabilityLinks
|
||
summary: 列出所有追溯链
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 追溯链列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/TraceabilityLink"
|
||
|
||
/api/projects/{project_id}/entities/runtime-components:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
get:
|
||
operationId: listRuntimeComponents
|
||
summary: 列出所有运行组件
|
||
tags: [entities]
|
||
responses:
|
||
"200":
|
||
description: 运行组件列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/RuntimeComponent"
|
||
|
||
# === 文件编辑 (MOD-EDITOR, Phase 2) ===
|
||
/api/projects/{project_id}/files:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
- name: path
|
||
in: query
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: 设计文件相对路径（相对于 design/ 目录）
|
||
get:
|
||
operationId: getFile
|
||
summary: 读取设计文件内容
|
||
tags: [editor]
|
||
responses:
|
||
"200":
|
||
description: 文件内容
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/FileContent"
|
||
"404":
|
||
description: 文件不存在
|
||
put:
|
||
operationId: saveFile
|
||
summary: 保存设计文件（保存后自动触发重新扫描）
|
||
tags: [editor]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/SaveFileRequest"
|
||
responses:
|
||
"200":
|
||
description: 保存成功，返回更新后的扫描结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ScanResult"
|
||
|
||
/api/projects/{project_id}/files/impact:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
- name: path
|
||
in: query
|
||
required: true
|
||
schema:
|
||
type: string
|
||
get:
|
||
operationId: getFileImpact
|
||
summary: 影响分析——修改该文件会影响哪些下游
|
||
tags: [editor]
|
||
responses:
|
||
"200":
|
||
description: 影响分析结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ImpactResult"
|
||
|
||
# === 实现进度 (MOD-IMPL-TRACKER, Phase 2) ===
|
||
/api/projects/{project_id}/impl-progress:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ProjectId"
|
||
post:
|
||
operationId: triggerImplProgress
|
||
summary: 触发实现进度评估
|
||
tags: [impl-tracker]
|
||
responses:
|
||
"200":
|
||
description: 实现进度结果
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ImplProgress"
|
||
get:
|
||
operationId: getImplProgress
|
||
summary: 获取实现进度
|
||
tags: [impl-tracker]
|
||
responses:
|
||
"200":
|
||
description: 实现进度列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ImplProgress"
|
||
|
||
components:
|
||
parameters:
|
||
ProjectId:
|
||
name: project_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
description: 项目 ID
|
||
|
||
schemas:
|
||
# --- Project ---
|
||
CreateProjectRequest:
|
||
type: object
|
||
required: [name, design_dir]
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: 项目名称
|
||
design_dir:
|
||
type: string
|
||
description: 设计文件目录绝对路径
|
||
code_dir:
|
||
type: string
|
||
description: 代码仓库目录绝对路径（可选，Phase 2）
|
||
|
||
Project:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
design_dir:
|
||
type: string
|
||
code_dir:
|
||
type: string
|
||
nullable: true
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
|
||
# --- Scan ---
|
||
ScanResult:
|
||
type: object
|
||
properties:
|
||
project_id:
|
||
type: string
|
||
scanned_at:
|
||
type: string
|
||
format: date-time
|
||
file_statuses:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/FileStatus"
|
||
summary:
|
||
type: object
|
||
properties:
|
||
total_files:
|
||
type: integer
|
||
ok:
|
||
type: integer
|
||
sparse:
|
||
type: integer
|
||
missing:
|
||
type: integer
|
||
placeholder_heavy:
|
||
type: integer
|
||
template_residue:
|
||
type: integer
|
||
|
||
FileStatus:
|
||
type: object
|
||
properties:
|
||
path:
|
||
type: string
|
||
description: 设计文件相对路径
|
||
status:
|
||
type: string
|
||
enum: [ok, sparse, missing, template-residue, placeholder-heavy]
|
||
content_lines:
|
||
type: integer
|
||
|
||
# --- Graph ---
|
||
GraphView:
|
||
type: object
|
||
properties:
|
||
nodes:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/GraphNode"
|
||
edges:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/GraphEdge"
|
||
groups:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/GraphGroup"
|
||
|
||
GraphNode:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: 设计实体 ID（如 MOD-PROJECT、CAP-SCAN）
|
||
type:
|
||
type: string
|
||
description: 实体类型（capability、module、entity、integration 等）
|
||
label:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [ok, sparse, missing, template-residue, placeholder-heavy, unknown]
|
||
group_id:
|
||
type: string
|
||
description: 所属分组 ID
|
||
|
||
GraphEdge:
|
||
type: object
|
||
properties:
|
||
source:
|
||
type: string
|
||
target:
|
||
type: string
|
||
relation:
|
||
type: string
|
||
description: 关系类型（traces_to、depends_on、owns、integrates_with 等）
|
||
|
||
GraphGroup:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
label:
|
||
type: string
|
||
layer:
|
||
type: string
|
||
enum: [business, application, data, technology, cross-layer]
|
||
|
||
# --- Design Entities ---
|
||
Capability:
|
||
type: object
|
||
properties:
|
||
capability_id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
priority:
|
||
type: string
|
||
related_value_flows:
|
||
type: string
|
||
phase:
|
||
type: string
|
||
|
||
CapabilityDetail:
|
||
allOf:
|
||
- $ref: "#/components/schemas/Capability"
|
||
- type: object
|
||
properties:
|
||
modules:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Module"
|
||
value_flows:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ValueFlow"
|
||
|
||
Module:
|
||
type: object
|
||
properties:
|
||
module_id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
layer:
|
||
type: string
|
||
depends_on:
|
||
type: string
|
||
capabilities:
|
||
type: string
|
||
phase:
|
||
type: string
|
||
|
||
ModuleDetail:
|
||
allOf:
|
||
- $ref: "#/components/schemas/Module"
|
||
- type: object
|
||
properties:
|
||
owned_entities:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Entity"
|
||
integrations:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Integration"
|
||
codebase_alignment:
|
||
type: object
|
||
nullable: true
|
||
properties:
|
||
repo_root:
|
||
type: string
|
||
code_root:
|
||
type: string
|
||
package_name:
|
||
type: string
|
||
|
||
Entity:
|
||
type: object
|
||
properties:
|
||
entity_id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
domain:
|
||
type: string
|
||
owner_module:
|
||
type: string
|
||
|
||
EntityDetail:
|
||
allOf:
|
||
- $ref: "#/components/schemas/Entity"
|
||
- type: object
|
||
properties:
|
||
data_flows:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/DataFlow"
|
||
|
||
Integration:
|
||
type: object
|
||
properties:
|
||
integration_id:
|
||
type: string
|
||
source:
|
||
type: string
|
||
target:
|
||
type: string
|
||
protocol:
|
||
type: string
|
||
direction:
|
||
type: string
|
||
description:
|
||
type: string
|
||
|
||
ValueFlow:
|
||
type: object
|
||
properties:
|
||
value_flow_id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
trigger:
|
||
type: string
|
||
steps:
|
||
type: string
|
||
outcome:
|
||
type: string
|
||
|
||
UserJourney:
|
||
type: object
|
||
properties:
|
||
journey_id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
precondition:
|
||
type: string
|
||
steps:
|
||
type: string
|
||
postcondition:
|
||
type: string
|
||
|
||
DataFlow:
|
||
type: object
|
||
properties:
|
||
data_flow_id:
|
||
type: string
|
||
source:
|
||
type: string
|
||
target:
|
||
type: string
|
||
data_content:
|
||
type: string
|
||
trigger:
|
||
type: string
|
||
protocol:
|
||
type: string
|
||
|
||
ExternalSystem:
|
||
type: object
|
||
properties:
|
||
system_id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
type:
|
||
type: string
|
||
protocol:
|
||
type: string
|
||
|
||
TraceabilityLink:
|
||
type: object
|
||
properties:
|
||
trace_id:
|
||
type: string
|
||
capability_id:
|
||
type: string
|
||
module_id:
|
||
type: string
|
||
entity_ids:
|
||
type: string
|
||
value_flow_ids:
|
||
type: string
|
||
|
||
RuntimeComponent:
|
||
type: object
|
||
properties:
|
||
component_id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
type:
|
||
type: string
|
||
technology:
|
||
type: string
|
||
port:
|
||
type: string
|
||
|
||
# --- Editor (Phase 2) ---
|
||
FileContent:
|
||
type: object
|
||
properties:
|
||
path:
|
||
type: string
|
||
format:
|
||
type: string
|
||
enum: [csv, md, yaml, openapi]
|
||
content:
|
||
type: string
|
||
last_modified:
|
||
type: string
|
||
format: date-time
|
||
|
||
SaveFileRequest:
|
||
type: object
|
||
required: [content]
|
||
properties:
|
||
content:
|
||
type: string
|
||
|
||
ImpactResult:
|
||
type: object
|
||
properties:
|
||
source_file:
|
||
type: string
|
||
affected_files:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
path:
|
||
type: string
|
||
reason:
|
||
type: string
|
||
|
||
# --- Impl Tracker (Phase 2) ---
|
||
ImplProgress:
|
||
type: object
|
||
properties:
|
||
module_id:
|
||
type: string
|
||
percentage:
|
||
type: number
|
||
format: float
|
||
minimum: 0
|
||
maximum: 100
|
||
source:
|
||
type: string
|
||
enum: [auto, llm, manual]
|
||
evaluated_at:
|
||
type: string
|
||
format: date-time
|