feat(db): Detection Model Registry 스키마 (V034, Phase 1-1) #87

htlee · 2026-04-20T06:23:53+09:00

htlee 코멘트됨,

2026-04-20 06:23:53 +09:00

소유자

변경 사항

Detection Model Registry DB 스키마 (Phase 1-1)

.claude/plans/vast-tinkering-knuth.md Phase 1-1 의 DB 레이어. prediction 의 17 탐지 알고리즘을 "명시적 모델 단위" 로 분리하고, 프론트엔드에서 파라미터·버전·가중치를 서로 다른 설정으로 동시 실행하며 비교 할 수 있는 기반.

기존 V014 correlation_param_models 패턴의 일반화 — JSONB params + is_active 를 model_id × version × role×status 차원으로 확장.

설계 원리

Model = 독립 탐지 단위 (e.g. dark_suspicion, gear_violation_g01_g06)
Version = 같은 model 의 파라미터 스냅샷 (version 문자열 자유도, SemVer 권장)
Role = PRIMARY(운영 반영, 최대 1개) / SHADOW·CHALLENGER(관측용, N개)
Status = DRAFT → TESTING → ACTIVE → ARCHIVED
DAG = model_id 간 선행·후행 의존성 — 후행 모델은 PRIMARY 결과만 소비 (오염 차단)

테이블 4종 + 뷰 1개

객체	역할
`detection_models`	카탈로그 — model_id PK, tier(1~5), category, entry_module/callable, is_enabled
`detection_model_dependencies`	DAG 엣지 — (model_id, depends_on, input_key) PK, self-loop CHECK
`detection_model_versions`	버전 스냅샷 — params JSONB, status/role 전이, UNIQUE partial index `(model_id) WHERE status=ACTIVE AND role=PRIMARY`
`detection_model_run_outputs`	월별 파티션 — 버전별 결과 원시 JSON, PRIMARY×SHADOW JOIN 분석용
`detection_model_metrics`	사이클 단위 집계 (cycle_duration_ms, detected_count 등)
`v_detection_model_comparison`	VIEW — 같은 `(cycle, model, input_ref)` 로 PRIMARY × SHADOW JOIN

핵심 불변식

PRIMARY 최대 1건: UNIQUE INDEX uk_detection_model_primary ON detection_model_versions(model_id) WHERE status='ACTIVE' AND role='PRIMARY' — DB 레벨 보호
ACTIVE 는 role 필수: CHECK (status <> 'ACTIVE' OR role IS NOT NULL)
오염 차단 (후속 Phase 1-2 DAGExecutor 에서 구현): ctx.shared[model_id] 에는 PRIMARY 결과만 기록 — SHADOW 는 저장소에만 남고 후행 모델 입력에 절대 주입하지 않음

권한

auth_perm_tree('ai-operations:detection-models', parent=admin, nav_sort=250, url='/detection-models')
ADMIN 5 ops (READ/CREATE/UPDATE/DELETE/EXPORT)
OPERATOR READ + UPDATE (SHADOW activate 가능. promote-primary 는 ADMIN 만)
ANALYST / VIEWER READ (Compare API 조회)
FIELD 제외 (현장 단속 담당, 모델 관리 불필요)

테스트

Flyway SQL 문법 자체 점검 (CHECK/UNIQUE/PARTITION BY RANGE/JSONB GIN 모두 표준 PostgreSQL)
(운영) 백엔드 재빌드 + scp + restart → Successfully applied 1 migration to schema "kcg", now at version v034 확인
(운영) SELECT * FROM kcg.detection_models → 빈 결과 확인 (Phase 1-2/2 에서 seed)
(운영) \dt kcg.detection_model_run_outputs* → 파티션 2개(2026-04, 2026-05) 확인

후속 (별도 MR)

Phase 1-2 prediction models_core/ — base/registry/executor/params_loader/feature_flag + _stage() wrapping
Phase 1-2 부수 partition_manager 에 detection_model_run_outputs 월별 자동 생성·만료 로직 추가 (기본 7일 retention)
Phase 2 5 모델 PoC 마이그레이션 (dark_suspicion / gear_violation / transshipment / risk_composite / pair_trawl_tier) + 각 모델 seed
Phase 3 백엔드 DetectionModelController — CRUD + activate/promote-primary/archive + Compare API

주의

스키마만 추가. prediction/backend 코드는 아직 이 스키마를 사용하지 않음. 현행 사이클에 영향 없음
이 MR 단독 머지해도 운영상 위험 없음 (빈 테이블 생성 + 빈 권한 시드)

## 변경 사항 **Detection Model Registry DB 스키마 (Phase 1-1)** `.claude/plans/vast-tinkering-knuth.md` Phase 1-1 의 DB 레이어. prediction 의 17 탐지 알고리즘을 "명시적 모델 단위" 로 분리하고, 프론트엔드에서 파라미터·버전·가중치를 **서로 다른 설정으로 동시 실행하며 비교** 할 수 있는 기반. 기존 `V014 correlation_param_models` 패턴의 일반화 — JSONB params + is_active 를 `model_id × version × role×status` 차원으로 확장. ### 설계 원리 - **Model** = 독립 탐지 단위 (e.g. `dark_suspicion`, `gear_violation_g01_g06`) - **Version** = 같은 model 의 파라미터 스냅샷 (`version` 문자열 자유도, SemVer 권장) - **Role** = `PRIMARY`(운영 반영, 최대 1개) / `SHADOW`·`CHALLENGER`(관측용, N개) - **Status** = `DRAFT` → `TESTING` → `ACTIVE` → `ARCHIVED` - **DAG** = `model_id` 간 선행·후행 의존성 — 후행 모델은 **PRIMARY 결과만** 소비 (오염 차단) ### 테이블 4종 + 뷰 1개 | 객체 | 역할 | |---|---| | `detection_models` | 카탈로그 — model_id PK, tier(1~5), category, entry_module/callable, is_enabled | | `detection_model_dependencies` | DAG 엣지 — (model_id, depends_on, input_key) PK, self-loop CHECK | | `detection_model_versions` | 버전 스냅샷 — params JSONB, status/role 전이, UNIQUE partial index `(model_id) WHERE status=ACTIVE AND role=PRIMARY` | | `detection_model_run_outputs` | **월별 파티션** — 버전별 결과 원시 JSON, PRIMARY×SHADOW JOIN 분석용 | | `detection_model_metrics` | 사이클 단위 집계 (cycle_duration_ms, detected_count 등) | | `v_detection_model_comparison` | VIEW — 같은 `(cycle, model, input_ref)` 로 PRIMARY × SHADOW JOIN | ### 핵심 불변식 1. **PRIMARY 최대 1건**: `UNIQUE INDEX uk_detection_model_primary ON detection_model_versions(model_id) WHERE status='ACTIVE' AND role='PRIMARY'` — DB 레벨 보호 2. **ACTIVE 는 role 필수**: `CHECK (status <> 'ACTIVE' OR role IS NOT NULL)` 3. **오염 차단** (후속 Phase 1-2 DAGExecutor 에서 구현): `ctx.shared[model_id]` 에는 PRIMARY 결과만 기록 — SHADOW 는 저장소에만 남고 후행 모델 입력에 절대 주입하지 않음 ### 권한 - `auth_perm_tree('ai-operations:detection-models', parent=admin, nav_sort=250, url='/detection-models')` - **ADMIN** 5 ops (READ/CREATE/UPDATE/DELETE/EXPORT) - **OPERATOR** READ + UPDATE (SHADOW activate 가능. `promote-primary` 는 ADMIN 만) - **ANALYST / VIEWER** READ (Compare API 조회) - FIELD 제외 (현장 단속 담당, 모델 관리 불필요) ## 테스트 - [x] Flyway SQL 문법 자체 점검 (CHECK/UNIQUE/PARTITION BY RANGE/JSONB GIN 모두 표준 PostgreSQL) - [ ] (운영) 백엔드 재빌드 + scp + restart → `Successfully applied 1 migration to schema "kcg", now at version v034` 확인 - [ ] (운영) `SELECT * FROM kcg.detection_models` → 빈 결과 확인 (Phase 1-2/2 에서 seed) - [ ] (운영) `\dt kcg.detection_model_run_outputs*` → 파티션 2개(2026-04, 2026-05) 확인 ## 후속 (별도 MR) - **Phase 1-2** prediction `models_core/` — base/registry/executor/params_loader/feature_flag + `_stage()` wrapping - **Phase 1-2 부수** partition_manager 에 `detection_model_run_outputs` 월별 자동 생성·만료 로직 추가 (기본 7일 retention) - **Phase 2** 5 모델 PoC 마이그레이션 (dark_suspicion / gear_violation / transshipment / risk_composite / pair_trawl_tier) + 각 모델 seed - **Phase 3** 백엔드 `DetectionModelController` — CRUD + activate/promote-primary/archive + Compare API ## 관련 - `.claude/plans/vast-tinkering-knuth.md` Phase 1-1 - `docs/prediction-analysis.md` §7 P1/P2 구조적 개선 제안 - V014 `correlation_param_models` 의 일반화 (해당 테이블은 2~3 릴리즈 후 deprecate 예정) ## 주의 - 스키마만 추가. **prediction/backend 코드는 아직 이 스키마를 사용하지 않음**. 현행 사이클에 영향 없음 - 이 MR 단독 머지해도 운영상 위험 없음 (빈 테이블 생성 + 빈 권한 시드)

htlee added 2 commits 2026-04-20 06:23:53 +09:00

feat(db): Detection Model Registry 스키마 (V034, Phase 1-1) dae7aea861

prediction 의 17 탐지 알고리즘을 "명시적 모델 단위" 로 분리하고 프론트엔드에서
파라미터·버전을 관리할 수 있도록 하는 기반 인프라의 DB 계층.

기존 V014 correlation_param_models 패턴을 일반화:
- JSONB params + is_active(V014) → model_id × version × role×status (V034)
- 한 모델을 여러 파라미터 셋으로 동시 실행 지원 (PRIMARY/SHADOW/CHALLENGER)
- Compare API 기반 제공 (PRIMARY vs SHADOW diff 집계)

### 스키마 (테이블 4 + 뷰 1)

1. detection_models — 모델 카탈로그 (model_id PK, tier 1~5, category, entry_module/callable, is_enabled)
2. detection_model_dependencies — 모델 간 DAG 엣지 (self-loop 금지, input_key 포함)
3. detection_model_versions — 파라미터 스냅샷 + 라이프사이클 + role
   - status: DRAFT / TESTING / ACTIVE / ARCHIVED
   - role: PRIMARY / SHADOW / CHALLENGER (ACTIVE 일 때만)
   - UNIQUE partial index: model_id 당 PRIMARY×ACTIVE 최대 1건
   - SHADOW/CHALLENGER×ACTIVE 는 N건 허용 (병렬 비교)
   - parent_version_id 로 fork 계보 추적
4. detection_model_run_outputs — 버전별 실행 결과 원시 snapshot
   - PARTITION BY RANGE (cycle_started_at)
   - 초기 2개월(2026-04, 2026-05) 파티션 + 이후 월별 자동생성 TODO (Phase 1-2)
   - input_ref JSONB GIN index — 같은 입력 기준 PRIMARY×SHADOW JOIN 용
5. detection_model_metrics — 사이클 단위 집계 메트릭 (cycle_duration_ms 등)
6. v_detection_model_comparison — PRIMARY×SHADOW 같은 입력으로 JOIN 한 VIEW

### 권한
- auth_perm_tree: 'ai-operations:detection-models' (parent=admin, nav_sort=250)
- ADMIN 5 ops / OPERATOR READ+UPDATE / ANALYST·VIEWER READ

### 후속 (Phase 1-2)
- partition_manager 에 detection_model_run_outputs 월별 자동 생성/만료 로직 추가
- 기본 retention 7일 (SHADOW 대량 누적 대비)

### 검증
- Flyway 자동 적용 (백엔드 재빌드+배포)
- 이후 Python Model Registry 가 이 스키마 위에서 동작

docs: 릴리즈 노트 업데이트 410d0da9cf

claude-bot 이 변경사항을 승인하였습니다. 2026-04-20 06:48:42 +09:00

claude-bot left a comment

멤버

Phase 1-1 V034 스키마 승인 — release 동일 묶음 반영

htlee added 1 commit 2026-04-20 06:48:45 +09:00

Merge branch 'develop' into feature/phase1-1-detection-models-schema 82ffe7cb06

htlee merged commit 30abe6a951 into develop

2026-04-20 06:49:02 +09:00

htlee 삭제된 브랜치 feature/phase1-1-detection-models-schema

2026-04-20 06:49:02 +09:00

htlee 커밋