시나리오와 Graph Builder¶

시나리오는 워크스페이스 소속 일반 시나리오와 워크스페이스 비종속 전역 템플릿으로 나뉩니다. Graph Builder 연동은 시나리오 실행·배포가 아니라 등록 전 유효성 검증에만 사용합니다.

전역 템플릿 검증과 저장¶

sequenceDiagram
    participant A as ROLE_ADMIN 클라이언트
    participant APP as App Backend
    participant GB as Graph Builder
    participant DB as PostgreSQL

    A->>APP: POST /v1/scenario-templates
    APP->>APP: 구조·metadata 일치·UTF-8 1MiB 검사
    APP->>GB: POST /v1/session/validate<br/>{"scenario_graph": scenarioContent}
    alt 2xx + status success|ok|valid
        GB-->>APP: 유효
        APP->>DB: scenario_template INSERT
        DB-->>APP: 저장 결과
        APP-->>A: 201 + 등록 본문
    else 그래프 오류
        GB-->>APP: 400/422 또는 실패 status
        APP-->>A: 400, 미저장
    else 통신·서비스 오류
        GB-->>APP: timeout/5xx/429/빈 응답 등
        APP-->>A: 503, 미저장
    end

POST /v1/scenario-templates는 구조 검사를 통과한 뒤 DB 트랜잭션 밖에서 Graph Builder POST /v1/session/validate를 호출하고, 성공한 경우에만 저장합니다. 시나리오 템플릿 API 중 Graph Builder를 호출하는 작업은 이 POST뿐입니다. GET 목록은 메타데이터만 읽습니다.

App Backend에는 Graph Builder를 향한 deploy, publish, session create 호출이 없습니다.

템플릿 본문 계약¶

요청은 slug, name, nullable description, 객체형 scenarioContent를 가집니다.

metadata, prompts, graph: 필수 객체
slots: 선택 객체
metadata.slug/name/description: 상위 필드와 정확히 일치
직렬화한 scenarioContent: UTF-8 1MiB 이하
활성 전역 slug: 유일, 중복은 409

본문은 등록 성공 응답에서 반환합니다. 목록은 slug, name, description, updatedAt만 제공하며 현재 본문 단건 조회·수정·삭제 API는 없습니다.

일반 시나리오¶

POST /v1/scenarios는 X-Workspace-Id가 필요한 워크스페이스 쓰기입니다.

새 slug: scenario와 DRAFT scenario_history를 만들고 201
기존 slug: 기존 scenario는 유지하고 DRAFT 이력을 append하며 200
isTemplate 누락/null: 새 slug는 false, 기존 slug는 저장된 값 유지
기존 slug에 다른 isTemplate 명시: 409

일반 생성은 검증하지 않습니다

POST /v1/scenarios는 Graph Builder /v1/session/validate를 호출하지 않습니다. 일반 시나리오가 저장되었다는 사실을 런타임 그래프 검증 통과나 게시 완료로 해석하면 안 됩니다.

isTemplate은 특정 원본 템플릿 ID를 가리키는 FK가 아니라 “전역 템플릿 기반 생성”이라는 Boolean provenance입니다. 최초 생성 뒤 불변이고, 원본 템플릿 버전은 추적하지 않습니다.

더미 검증 경로¶

공개 POST /v1/dummy-scenarios/validate도 같은 Graph Builder 검증 API를 호출하지만 저장하지 않습니다. scenario_graph를 우선하며 scenarioGraph는 하위 호환 별칭입니다. 더미 CRUD의 공개 범위는 보안과 현재 격차에 설명합니다.

응답·오류 형태는 공유 데이터 계약, 전체 경로는 REST API 참조를 참고하세요.