공유 데이터 계약¶

App Backend는 프런트엔드, Socket Backend, Graph Builder와 코드를 직접 공유하지 않으므로 와이어 필드와 DB 의미가 통합 계약입니다. 변경할 때는 생산자와 소비자를 함께 확인해야 합니다.

공통 REST 응답¶

단건 성공 응답은 다음 envelope를 사용합니다.

{
  "status": 200,
  "message": "success",
  "data": {}
}

목록은 count와 list, 페이지 목록은 여기에 page를 추가합니다. 생성 API가 HTTP 201을 반환해도 공통 응답 객체의 status 필드는 현재 200으로 직렬화될 수 있으므로, 클라이언트는 실제 HTTP status를 우선해야 합니다.

오류는 기본적으로 status, 지역화된 message, 선택 data를 사용합니다.

{
  "status": 409,
  "message": "요청을 처리할 수 없습니다.",
  "data": {
    "code": "VOICE_PRESET_INACTIVE",
    "voicePreset": "example"
  }
}

기계 분기가 필요한 오류만 data.code를 보장합니다. DB 제약명, SQL, 드라이버 원문과 민감한 바인딩 값은 응답에 싣지 않습니다.

client-secret 계약¶

App Backend가 Ed25519 개인키로 서명하고 Socket Backend가 공개키로 검증합니다.

JOSE: alg=EdDSA, typ=JWT
claims: iss, 단일 문자열 aud, sub, workspaceId, jti, iat, exp
apiKeyId 없음
TTL 기본 3,600초, 300..10,800초로 clamp
DB 저장과 서버 측 사용 횟수 추적 없음

따라서 이 토큰은 무상태이고 만료 전 재사용 가능합니다. 자세한 발급 흐름은 API key와 client-secret을 참고하세요.

시나리오 계약¶

전역 템플릿의 scenarioContent는 객체이며 metadata, prompts, graph가 필수, slots가 선택입니다. App Backend는 전체 객체를 Graph Builder에 {"scenario_graph": ...}로 감싸 보냅니다.

Graph Builder 검증 성공은 HTTP 2xx와 status가 success, ok, valid 중 하나일 때입니다. Graph Builder의 400/422는 그래프 오류, 그 밖의 비정상 HTTP·통신 실패·빈 응답은 서비스 불가로 분류합니다.

일반 시나리오의 content는 JSON 문자열이며 전역 템플릿과 달리 저장 전에 Graph Builder가 검증하지 않습니다. isTemplate은 원본 ID가 아닌 Boolean provenance입니다.

`voicePreset` 계약¶

클라이언트가 주고받는 값은 voice_preset.preset_code 하나입니다.

GET /v1/voice-presets에서 활성 presetCode를 조회합니다.
PUT /v1/members/me/configs/TTS_VOICE의 configValue로 저장합니다.
실시간 세션 시작 때 같은 값을 voicePreset으로 보냅니다.

목록 응답은 presetCode, presetName, gender, ageGroup만 제공합니다. ttsProvider, ttsModel, voiceParams, 정렬값은 노출하지 않습니다. 실행 파라미터의 정본은 DB의 voice_preset이고 Socket Backend가 코드를 해석합니다.

관련 코드형 오류는 REST와 WebSocket이 같은 문자열을 사용합니다.

VOICE_PRESET_NOT_FOUND: 404
VOICE_PRESET_INACTIVE: 409
MEMBER_CONFIG_NOT_FOUND: 404
MEMBER_CONFIG_CONFLICT: 409

공유 DB 계약¶

Socket Backend는 대화·메시지·분석·요약을 쓰고 App Backend는 읽습니다. 공유 테이블을 한 서비스의 로컬 구현 상세로 취급하면 안 됩니다. UUID, timestamptz, JSONB, speech phase, 파티션과 soft-delete 의미의 정본은 sohri-db이며, App Backend의 schema.sql은 테스트용 사본입니다.

흐름은 대화·분석 조회, 템플릿 규칙은 시나리오와 Graph Builder를 참고하세요.