본문으로 건너뛰기

Compliance

컴플라이언스 프레임워크 관리 및 평가를 수행하는 API입니다. GDPR, PIPA 등 규제 프레임워크별 자동/수동 체크 및 대시보드를 제공합니다.

CRUD 엔드포인트는 모두 admin 권한이 필요하며 Epic #1079 (Compliance CRUD) 에서 추가되었습니다. 자세한 운영 정책은 features/admin/compliance/frameworks 가이드를 함께 참조하세요.

조회 / 평가 / 대시보드​

GET /api/v1/compliance/frameworks​

설명: 등록된 컴플라이언스 프레임워크 목록을 반환합니다.

GET /api/v1/compliance/frameworks/{framework_id}​

설명: 프레임워크 상세 정보(카테고리·체크 항목 포함)를 반환합니다.

POST /api/v1/compliance/assessments​

설명: 새 컴플라이언스 평가를 생성합니다. (HTTP 201)

GET /api/v1/compliance/assessments​

설명: 평가 목록을 반환합니다.

GET /api/v1/compliance/assessments/{assessment_id}​

설명: 특정 평가의 상세 결과를 반환합니다.

POST /api/v1/compliance/assessments/{assessment_id}/run​

설명: 자동 체크 항목을 실행합니다.

PATCH /api/v1/compliance/assessments/{assessment_id}/results/{result_id}​

설명: 수동 체크 결과를 업데이트합니다.

GET /api/v1/compliance/assessments/{assessment_id}/report​

설명: 평가 보고서를 생성하여 반환합니다.

GET /api/v1/compliance/dashboard​

설명: 전체 컴플라이언스 현황 대시보드를 반환합니다.

GET /api/v1/compliance/changelog​

설명: /api/v1/compliance/* 에 대한 모든 mutation 감사 로그를 페이지네이션으로 반환합니다. AuditMiddleware 가 OpenSearch 에 적재한 이벤트를 그대로 재사용하며 별도 DB 테이블은 없습니다 (admin 전용).

쿼리 파라미터: start_date, end_date (ISO 8601), page (default 1), page_size (default 50, max 200).

GET /api/v1/compliance/check-engine/keys​

설명: compliance_engine 에 등록된 자동 점검 키 목록을 반환합니다. CheckItem 생성/수정 UI 의 auto_check_key 드롭다운에서 사용 (admin 전용).

Framework CRUD (#1079)​

모두 admin 권한이 필요합니다.

POST /api/v1/compliance/frameworks​

설명: 프레임워크를 생성합니다. (HTTP 201)

  • code 는 전역 unique. 중복 시 409 (이미 존재하는 코드입니다: ...).
  • DB unique 제약 위반(race) 도 동일 409 detail 로 정규화.

PATCH /api/v1/compliance/frameworks/{framework_id}​

설명: 프레임워크를 부분 수정합니다.

  • code 는 immutable — Pydantic 모델에 노출되지 않아 클라이언트 전송값은 무시 (silently dropped).
  • 빈 본문({}) 은 변경 없이 현재 상태 반환.

DELETE /api/v1/compliance/frameworks/{framework_id} (HTTP 204)​

설명: 프레임워크 삭제. 평가 이력 보존을 위해 soft+force 매트릭스를 따릅니다.

평가 이력force동작
> 0falseSoft delete (is_active=false)
> 0true409 거부 — 강제 삭제 불가
= 0falseSoft delete (안전 기본)
= 0trueHard cascade — categories + check-items 모두 삭제

쿼리 파라미터: force (default false)

Category CRUD (#1079)​

POST /api/v1/compliance/frameworks/{framework_id}/categories​

설명: 카테고리를 생성합니다. (HTTP 201)

  • (framework_id, code) 는 unique. 중복 시 409.
  • 상위 framework 가 없으면 404.

PATCH /api/v1/compliance/categories/{category_id}​

설명: 카테고리를 부분 수정합니다.

  • code 와 framework_id 는 immutable.

DELETE /api/v1/compliance/categories/{category_id} (HTTP 204)​

설명: 카테고리를 hard delete 합니다.

  • 하위 CheckItem 이 0건일 때만 가능. 1건이라도 있으면 409 (먼저 체크항목을 정리하세요).
  • soft delete 모드는 없음.

CheckItem CRUD (#1079)​

POST /api/v1/compliance/categories/{category_id}/check-items​

설명: 체크항목을 생성합니다. (HTTP 201)

  • (category_id, code) 는 unique. 중복 시 409.
  • check_type=auto 이면 auto_check_key 가 GET /check-engine/keys 목록 안에 있어야 함 (없으면 422).
  • check_type=manual 인데 auto_check_key 가 전송되면 자동으로 None 으로 정규화.

PATCH /api/v1/compliance/check-items/{item_id}​

설명: 체크항목을 부분 수정합니다.

  • code 는 immutable.
  • check_type / auto_check_key 는 최종 병합 결과 기준 화이트리스트 검증. 즉 DB row + 전송값 머지 후 (auto, valid_key) 또는 (manual, *) 이어야 함.
  • manual 로 전환되면 auto_check_key 는 자동으로 None.

DELETE /api/v1/compliance/check-items/{item_id}​

설명: 항상 405 Method Not Allowed — 감사 추적 보존을 위해 hard delete 영구 금지 (#1079 결정). 비활성화가 필요하면 별도 is_active 컬럼 마이그레이션이 선행되어야 합니다.

인증​

JWT Bearer 토큰이 필요합니다. CRUD/changelog/check-engine 엔드포인트는 추가로 admin 역할이 필요합니다.

에러 코드​

코드설명
400잘못된 평가 요청
403admin 권한 없음
404프레임워크 / 카테고리 / 체크항목 / 평가를 찾을 수 없음
405CheckItem DELETE (영구 금지)
409code 중복 · 하위 자원 존재 · 평가 이력 존재 시 force 강제 삭제 거부
422auto_check_key 가 미등록 키
500자동 체크 실행 실패 / 내부 오류