킨텍스 자동전시시스템 — API 규약 가이드

WISE(UIWS) 참조 — 응답 봉투(ApiResponse/PageResponse)·인증(JWT+2FA)·에러 처리 규약은 workspace/uiws/backend/README.md를 따른다. 정본 계약서: 엔드포인트 상세·요청/응답 shape·DB 매퍼 인수는 _workspace/01_backend_contracts.md가 단일 진실원천이다. 본 문서는 규약(convention)만 요약하고 세부는 계약서로 링크한다(중복 서술 회피).

1. 경로·버전 규약

베이스: /api. 프론트 axios baseURL=/api(동일 도메인 서빙, 별도 CORS 불필요).
도메인 경로는 행사 스코프 접두: /api/events/{eventId}/… (예 …/halls/{hallId}/layout, …/booths/{boothId}/design).
시스템/관리 경로: /api/system/**·/api/admin/**(ADMIN 전용). 인증: /api/auth/**.
내부(워커) 경로: /api/internal/**(공유 시크릿 인증).
버전: P0는 무접두(/api/...). 파괴적 변경 발생 시 /api/v2/... 도입 — 계약서 변경 이력에 기록하고 frontend·qa에 통지.

2. 응답 봉투

모든 응답은 ApiResponse<T>:

{ "success": true,  "data": { ... }, "error": null }
{ "success": false, "data": null,    "error": { "code": "FORBIDDEN", "message": "이 행사/부스에 대한 권한이 없습니다." } }

목록: PageResponse<T> = { "items": [...], "page": 0, "size": 20, "total": 123 }. (P0 갤러리/워크스페이스는 배열 직접 반환도 허용 — 계약서 §0-1.)
error.message는 사람이 읽을 요약만. 상세·스택트레이스 미노출(서버 로그).

3. 오류 코드 → HTTP (고정)

code	HTTP	의미
`VALIDATION`	400	요청 값 오류(필드 메시지 포함)
`UNAUTHORIZED`	401	미인증/토큰 만료
`FORBIDDEN`	403	행사/부스 권한 없음
`NOT_REGISTERED_COMPANY`	403	미등록 장치업체 초대·응찰 차단
`NOT_FOUND`	404	대상 없음
`CONFLICT`	409	상태 충돌(낙관적 잠금 등)
`COMPLIANCE_BLOCKED`	422	규정 위반(차단)
`RENDER_QUOTA_EXCEEDED`	429	행사 이미지 생성 쿼터 소진
`NOT_IMPLEMENTED`	501	매퍼/엔진 구현 대기(스켈레톤)
`INTERNAL`	500	서버 오류(요약만)

코드는 문자열 상수(common.exception.ErrorCode). 신규 코드 추가 시 계약서 §0-2와 본 표를 동시 갱신.

4. 인증 헤더 · RBAC

헤더: Authorization: Bearer <JWT> (HS256). 클레임: sub(userId)·name·roles(eventId→역할)·hm(홀매니저).
공개 경로(인증 불필요): GET /health, POST /api/auth/login, /ws/**, POST /api/internal/render/callback(워커 토큰).
2차 인증: POST /api/auth/login(1차) → verifyToken → POST /api/auth/verify-otp(EMAIL 코드/OTP) → access·refresh. (WISE auth 이식 — DEVELOPMENT_GUIDE.md §4.)
행사 단위 RBAC: 역할 ORGANIZER·EXHIBITOR·CONTRACTOR·HALL_MANAGER(COMMON_CODES.md EVENT_ROLE). 가드 — 열람=행사 멤버 or 홀매니저 / 편집·액션=엔드포인트별 역할.

5. 보안 불변 (API 계약 강제)

민감정보(IP·SSH·비밀번호·해시·내부 식별자·GEMINI_API_KEY) 응답 완전 제외. 사용자/업체 표시는 비민감 필드만.
AI 생성 이미지(M5)는 응답에 watermarkRequired:true+watermarkText+notice(계약·심사 서류 사용 금지) 항상 포함.
워커 실패 시 errorMessage는 요약만 통과(스택트레이스 유입 차단).
상세: DEVELOPMENT_GUIDE.md §5.

6. 비동기·실시간 (Redis + WebSocket)

RenderJob: POST …/render(발행) → Redis 큐(kintex:renderjob:queue) → Python 워커 소비 → POST /api/internal/render/callback(콜백) → 상태 갱신.
WebSocket(STOMP): 핸드셰이크 GET /ws(SockJS), 브로드캐스트 prefix /topic, 클라→서버 /app. 구독 /topic/render/{jobId} → RenderJob 완료/실패 푸시. (승인 이벤트 토픽은 M6/C-4 확장.)

7. 엔드포인트 카탈로그 (요약 — 상세는 계약서)

각 항목의 요청/응답 shape·완성/스켈레톤(501) 현황은 _workspace/01_backend_contracts.md 해당 절 참조.

영역	대표 경로	계약서 절
헬스	`GET /health`	§1
인증·워크스페이스	`/api/auth/login·workspaces·me·accept-invite`	§2
M2 플로어플랜	`/api/events/{eventId}/halls/{hallId}/layout` (`GET·PUT·validate·auto-generate`)	§3
M3 부스 설계	`/api/events/{eventId}/booths/{boothId}/design` (`GET·PUT·precheck`)	§4
M4 유틸리티/배선	`/api/events/{eventId}/booths/{boothId}/utility` (`quote·wiring·order·GET`)	§5
M5 나노바나나	`/api/events/{eventId}/booths/{boothId}/render` · `/render-jobs/{jobId}` · `/api/internal/render/callback`	§6
룰셋	`rulesets/compliance-v1.json`·`rates-v1.json` (데이터 계약)	§7
DB 매퍼 인수	UserMapper·BoothMapper·DesignMapper·WiringMapper·RenderJobMapper (PostGIS)	§8

Phase D 도메인(M10 관람객·M12 공개사이트/CMS·M15 옥션·M16 BI·M18 관리자)의 API는 각 도메인 에이전트가 계약서에 절을 추가하며 확장한다. 본 가이드의 §1~6 규약을 동일 준수.

8. 참조

정본 계약서: _workspace/01_backend_contracts.md
나노바나나 워커 계약: ../tools/nanobanana/_workspace/01_worker_contract.md
개발 표준: DEVELOPMENT_GUIDE.md · 공통코드: COMMON_CODES.md

5.8 KiB Raw Blame History

킨텍스 자동전시시스템 — API 규약 가이드

1. 경로·버전 규약

2. 응답 봉투

3. 오류 코드 → HTTP (고정)

4. 인증 헤더 · RBAC

5. 보안 불변 (API 계약 강제)

6. 비동기·실시간 (Redis + WebSocket)

7. 엔드포인트 카탈로그 (요약 — 상세는 계약서)

8. 참조

5.8 KiB

Raw Blame History