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

> **WISE(UIWS) 참조** — 응답 봉투(`ApiResponse`/`PageResponse`)·인증(JWT+2FA)·에러 처리 규약은 `workspace/uiws/backend/README.md`를 따른다.
> **정본 계약서**: 엔드포인트 상세·요청/응답 shape·DB 매퍼 인수는 [`_workspace/01_backend_contracts.md`](../_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>`:
```json
{ "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`](DEVELOPMENT_GUIDE.md) §4.)
- **행사 단위 RBAC**: 역할 `ORGANIZER·EXHIBITOR·CONTRACTOR·HALL_MANAGER`([`COMMON_CODES.md`](COMMON_CODES.md) `EVENT_ROLE`). 가드 — 열람=행사 멤버 or 홀매니저 / 편집·액션=엔드포인트별 역할.

---

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

- 민감정보(IP·SSH·비밀번호·해시·내부 식별자·`GEMINI_API_KEY`) 응답 완전 제외. 사용자/업체 표시는 비민감 필드만.
- **AI 생성 이미지**(M5)는 응답에 `watermarkRequired:true`+`watermarkText`+`notice`(계약·심사 서류 사용 금지) **항상** 포함.
- 워커 실패 시 `errorMessage`는 요약만 통과(스택트레이스 유입 차단).
- 상세: [`DEVELOPMENT_GUIDE.md`](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`](../_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`](../_workspace/01_backend_contracts.md)
- 나노바나나 워커 계약: [`../tools/nanobanana/_workspace/01_worker_contract.md`](../tools/nanobanana/_workspace/01_worker_contract.md)
- 개발 표준: [`DEVELOPMENT_GUIDE.md`](DEVELOPMENT_GUIDE.md) · 공통코드: [`COMMON_CODES.md`](COMMON_CODES.md)
