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