Merge pull request 'docs: 2026-04-20 릴리즈 후속 정적 문서 최신화' (#91) from feature/docs-refresh-2026-04-20 into develop

Phase 0-1/0-2/0-3 + Phase 1-1 V034 반영 + Phase 1-2 재개 포인트 명시.

### 변경
- architecture.md — 27→29 보호 경로, /illegal-fishing + /transshipment 라우트 추가
- sfr-traceability.md
  - Flyway V001~V030 → V001~V034 (34 마이그레이션)
  - Database 51 → 56 테이블 (V034 detection_model_* 5종 + 뷰 1, 반영 대기)
  - Prediction 섹션에 stage_runner 사이클 에러 경계 (Phase 0-1) 추가
  - SFR-09: TransshipmentDetection(V033/PR #86) 페이지 추가
  - SFR-10: IllegalFishingPattern(V032/PR #85) 페이지 추가
  - 부록 A: 신규 화면 파일 경로 반영
- sfr-user-guide.md — SFR-10 하위에 "불법 조업 이벤트" + "환적 의심 탐지" 2개 신규 페이지 사용자 가이드 섹션 신설
- system-flow-guide.md — V030 미반영 경고를 V030~V034 노드 일괄 미반영으로 확장 (detection_models / detection_model_versions / detection_model_run_outputs / detection_model_metrics / dag_executor / shadow_runner / api.detection_models_* / ui.illegal_fishing / ui.transshipment_detection / ui.detection_model_management)
- prediction-analysis.md — P1 권고 4건 중 3건 완료 표시
  - ✅ 사이클 스테이지 에러 경계 (PR #83)
  - 🟡 임계값 외부화 (V034 스키마 머지, Phase 1-2 대기)
  - ✅ ILLEGAL_FISHING_PATTERN 전용 페이지 (PR #85)
  - ✅ 환적 전용 페이지 (PR #86)
  - 변경 이력에 2026-04-20 행 추가

### 범위 밖
- memory/* 는 세션 로컬 경로, 저장소 외
- prediction/backend 코드 변경 없음 — 문서만

docs/RELEASE-NOTES.md

@@ -4,6 +4,9 @@
 
 ## [Unreleased]
 
+### 문서
+- **2026-04-20 릴리즈 후속 정적 문서 최신화** — `architecture.md` 27→29 보호 경로 + 신규 라우트 2개, `sfr-traceability.md` V030→V034 · 51→56 테이블 · stage_runner · Phase 0-2/0-3 페이지 반영, `sfr-user-guide.md` 에 "불법 조업 이벤트" + "환적 의심 탐지" 사용자 가이드 섹션 신설, `system-flow-guide.md` V030~V034 매니페스트 미반영 경고 확장, `prediction-analysis.md` P1 권고 4건 중 3건 완료(✅) 표시
+
 ## [2026-04-20]
 
 ### 추가

docs/architecture.md

@@ -318,7 +318,7 @@ deps 변경 → useMapLayers        → RAF → overlay.setProps() (React 리렌
 
 ---
 
-## 라우팅 구조 (27 보호 경로 + login)
+## 라우팅 구조 (29 보호 경로 + login)
 
 `App.tsx`에서 `BrowserRouter` > `AuthProvider` > `Routes`로 구성된다.
 
@@ -332,6 +332,8 @@ deps 변경 → useMapLayers        → RAF → overlay.setProps() (React 리렌
   - `/dark-vessel` — 무등화 선박 탐지 (SFR-09)
   - `/gear-detection` — 어구 탐지 (SFR-10)
   - `/gear-collision` — 어구 정체성 충돌 (SFR-10, V030 — 동일 어구 이름 × 복수 MMSI 공존 감지)
+  - `/illegal-fishing` — 불법 조업 이벤트 통합 대시보드 (SFR-09/10/11, V032 — GEAR_ILLEGAL+EEZ_INTRUSION+ZONE_DEPARTURE 3 카테고리)
+  - `/transshipment` — 환적 의심 전용 탐지 대시보드 (SFR-09, V033 — prediction 5단계 필터 결과)
   - `/china-fishing` — 중국어선 탐지
   - `/patrol-route` — 순찰경로 (SFR-07)
   - `/fleet-optimization` — 함대 최적화 (SFR-08)

docs/prediction-analysis.md

@@ -180,10 +180,10 @@ def _stage(name: str, fn, *args, required=False, **kwargs):
 
 ### P1 — 지금 해야 할 것 (운영 안정성)
 
-1. **사이클 스테이지 단위 에러 경계** — `_stage(name, fn, required=False)` 유틸로 9번 출력 5모듈을 쪼갤 것. `logger.exception` 으로 stacktrace 보존. `required=True` 를 `fetch_incremental` 같은 fatal 에만 적용 → 실패 시 조기 반환
+1. ✅ **사이클 스테이지 단위 에러 경계** (2026-04-20 PR #83 완료) — `prediction/pipeline/stage_runner.py` 의 `run_stage(name, fn, required=False)` 유틸. 출력 6모듈(violation_classifier / event_generator / kpi_writer / stats_aggregate_hourly/daily / alert_dispatcher) 스테이지별 독립 실행 + 내부 6지점 `logger.warning → logger.exception` 전환. `upsert_results` required=True. **효과 검증**: 이 변경으로 V031 잠복 버그(`candidate_source` VARCHAR(30) 초과) 가 stacktrace 로 즉시 드러나 30분 내 hotfix 로 4시간 누락되던 `gear_group_parent_candidate_snapshots` 갱신 복원
-2. **임계값 외부화** — `correlation_param_models` 패턴을 확장해 `detection_params` 테이블 신설 (algo_name, param_key, value, active_from, active_to). 배포 없이 해상도 튜닝 가능. 운영자 권한으로 접근 시 감사 로그
+2. 🟡 **임계값 외부화** (2026-04-20 Phase 1-1 기반 머지, Phase 1-2 구현 대기) — V034 `detection_model_versions.params JSONB` + `correlation_param_models` 일반화. 기반 스키마 + 권한 완료, prediction Model Registry/DAG Executor 구현이 Phase 1-2 작업
-3. **ILLEGAL_FISHING_PATTERN 전용 페이지** + **환적 전용 페이지** — 백엔드 API·DB 는 이미 존재. 프론트만 GearCollisionDetection 패턴으로 추가 (`PageContainer` + `DataTable` + `Badge intent`)
+3. ✅ **ILLEGAL_FISHING_PATTERN 전용 페이지** (2026-04-20 PR #85 완료) + ✅ **환적 전용 페이지** (2026-04-20 PR #86 완료) — 둘 다 backend 변경 없이 프론트 전용. `/illegal-fishing` / `/transshipment` 메뉴 신설 + V032/V033 권한
-4. **사이클 부분 원자성 명시** — DB 쓰기 경계 문서화 (어디까지가 한 트랜잭션인지). 최소한 [architecture.md](architecture.md) 또는 신설 `docs/prediction-transactions.md` 에 다이어그램
+4. ⏸ **사이클 부분 원자성 명시** — DB 쓰기 경계 문서화. 향후 작업 (별도 `docs/prediction-transactions.md` 또는 architecture.md 확장 예정)
 
 ### P2 — 다음 (품질 확보)
 
@@ -248,3 +248,4 @@ def _stage(name: str, fn, *args, required=False, **kwargs):
 | 일자 | 내용 |
 |---|---|
 | 2026-04-17 | 초판 — opus 4.7 독립 리뷰. 구조/방향 중심 + 우선순위별 개선 제안 |
+| 2026-04-20 | Phase 0-1/0-2/0-3 + Phase 1-1 V034 완료 반영. P1 권고 4건 중 3건 (사이클 에러 경계, 2개 UI 페이지) 완료 표시. 임계값 외부화(P1 #2) 는 기반 스키마 V034 머지 상태이며 Phase 1-2 Model Registry + DAG Executor 구현 대기 |

docs/sfr-traceability.md

@@ -13,9 +13,9 @@
 | 레이어 | 기술 | 상태 |
 |-------|------|------|
 | Frontend | React 19 + TypeScript 5.9 + Vite 8 + Tailwind CSS 4 + Zustand 5 + MapLibre GL 5 + deck.gl 9 + ECharts 6 + react-i18next | 운영 배포 (rocky-211 nginx) |
-| Backend | Spring Boot 3.5.7 + Java 21 + PostgreSQL 14.19 + Flyway V001~V030 + Spring Security + JWT + Caffeine + 트리 RBAC | 운영 배포 (rocky-211 :18080) |
+| Backend | Spring Boot 3.5.7 + Java 21 + PostgreSQL 14.19 + Flyway V001~V034 + Spring Security + JWT + Caffeine + 트리 RBAC | 운영 (rocky-211 :18080, V034 재배포 대기) |
-| Prediction | Python 3.11+ + FastAPI + APScheduler, 17 알고리즘 모듈 + 7단계 분류 파이프라인 + 5 출력/룰 모듈 | 운영 배포 (redis-211 :18092, 5분 주기) |
+| Prediction | Python 3.11+ + FastAPI + APScheduler, 17 알고리즘 모듈 + 7단계 분류 파이프라인 + 5 출력/룰 모듈 + **stage_runner 사이클 에러 경계** (Phase 0-1) | 운영 배포 (redis-211 :18092, 5분 주기) |
-| Database | PostgreSQL `kcgaidb` / 51 테이블 / schema `kcg` + snpdb(AIS 원천) | 운영 |
+| Database | PostgreSQL `kcgaidb` / 51 → 56 테이블 (V034 반영 후 detection_model_* 5 + 뷰 1) / schema `kcg` + snpdb(AIS 원천) | 운영 (V034 반영 대기) |
 | Design System | `/design-system.html` 쇼케이스 SSOT + `shared/constants/` 25개 카탈로그 + `shared/components/ui/` 9개 공통 컴포넌트 | SSOT 전영역 준수 (2026-04-17 PR #C 완료) |
 | i18n | 10 네임스페이스 × ko/en, `common.json` 에 aria/error/dialog/message 54키 추가 | alert/confirm/aria-label 하드코딩 제거 완료 (2026-04-17 PR #B) |
 
@@ -86,8 +86,8 @@ Frontend ← Backend /api/analysis/* + /api/events + /api/alerts + ... (65+ API)
 | SFR-06 | 단속 계획·경보 연계 | EnforcementPlan | ✅ /api/enforcement/plans | - |
 | SFR-07 | AI 경비함정 단일 함정 순찰·경로 | PatrolRoute | 🔲 Mock | - |
 | SFR-08 | AI 경비함정 다함정 협력형 경로 | FleetOptimization | 🔲 Mock | - |
-| SFR-09 | 불법 어선 패턴 탐지 (Dark Vessel) | DarkVesselDetection, TransferDetection | ✅ /api/analysis/* | ✅ Dark 11패턴 + Transship 5단계 |
+| SFR-09 | 불법 어선 패턴 탐지 (Dark Vessel) | DarkVesselDetection, TransferDetection, **TransshipmentDetection(V033)** | ✅ /api/analysis/* | ✅ Dark 11패턴 + Transship 5단계 |
-| SFR-10 | 불법 어망·어구 탐지 및 관리 | GearDetection, GearIdentification, GearCollisionDetection(V030) | ✅ /api/vessel-analysis/groups + /api/analysis/gear-detections + /api/analysis/gear-collisions | ✅ DAR-03 G-01~G-06 + pair tier + GEAR_IDENTITY_COLLISION(PR #73) |
+| SFR-10 | 불법 어망·어구 탐지 및 관리 | GearDetection, GearIdentification, GearCollisionDetection(V030), **IllegalFishingPattern(V032)** | ✅ /api/vessel-analysis/groups + /api/analysis/gear-detections + /api/analysis/gear-collisions + /api/events?category= | ✅ DAR-03 G-01~G-06 + pair tier + GEAR_IDENTITY_COLLISION(PR #73) |
 | SFR-11 | 단속·탐지 이력 관리 | EnforcementHistory, EventList | ✅ /api/events + /api/enforcement/records | ✅ prediction_events |
 | SFR-12 | 모니터링 및 경보 현황판 | Dashboard, MonitoringDashboard, ChinaFishing | ✅ /api/stats + /api/alerts + /api/analysis/* | ✅ prediction_kpi_realtime + stats |
 | SFR-13 | 통계·지표·성과 분석 | Statistics | ✅ /api/stats (daily/monthly/hourly) | ✅ prediction_stats_* |
@@ -228,7 +228,7 @@ Frontend ← Backend /api/analysis/* + /api/events + /api/alerts + ... (65+ API)
 
 **제안요청서 정의:** AIS 끊김·스푸핑·환적 등 의심 패턴 탐지.
 
-**구현 화면:** `features/detection/DarkVesselDetection.tsx`, `features/vessel/TransferDetection.tsx`
+**구현 화면:** `features/detection/DarkVesselDetection.tsx`, `features/detection/TransshipmentDetection.tsx`(V033/PR #86, 2026-04-20), `features/vessel/TransferDetection.tsx`
 
 **Prediction 연동 ✅ 운영**:
 - **Dark Vessel**: 11패턴 P1~P11 기반 0~100점 연속 점수, 4 tier (CRITICAL≥70/HIGH≥50/WATCH≥30/NONE)
@@ -239,6 +239,7 @@ Frontend ← Backend /api/analysis/* + /api/events + /api/alerts + ... (65+ API)
 **백엔드 연동 ✅**: `/api/analysis/vessels` + `/api/analysis/dark` + `/api/analysis/transship` + `/api/analysis/history`
 - DarkDetailPanel: ScoreBreakdown + P1~P11 카탈로그
 - 2026-04-17 alertLevels 헬퍼(`ALERT_LEVEL_TIER_SCORE` 등) 적용
+- **TransshipmentDetection 전용 페이지 (V033, 2026-04-20)** — 5단계 필터 결과 목록·집계·상세 READ 전용 대시보드. `/api/analysis/transship` + `getTransshipSuspects` 재사용, features.transship_tier 로 tier 분류 (CRITICAL/HIGH/MEDIUM)
 
 ---
 
@@ -258,6 +259,7 @@ Frontend ← Backend /api/analysis/* + /api/events + /api/alerts + ... (65+ API)
 - 페어 탐색 `find_pair_candidates` (bbox + 궤적 유사도 2차)
 - 한중어업협정 906척 NAME_EXACT + NAME_FUZZY 매칭 53%+
 - **GEAR_IDENTITY_COLLISION (V030/PR #73)** — 동일 어구 이름이 서로 다른 MMSI 로 동일 사이클 내 공존 감지 → `gear_identity_collisions` UPSERT(name, mmsi_lo, mmsi_hi), CRITICAL/HIGH/MEDIUM/LOW severity 분류. 이전 "교체(sequential)" 로 오해하던 케이스를 "어구 복제/스푸핑 증거" 로 재정의. SAVEPOINT + try/except 로 `gear_correlation_scores_pkey` 충돌 격리
+- **IllegalFishingPattern 통합 대시보드 (V032/PR #85, 2026-04-20)** — `GEAR_ILLEGAL` + `EEZ_INTRUSION` + `ZONE_DEPARTURE` 3 카테고리 통합 뷰. 기존 `/api/events` 를 category 다중 병렬 호출 + occurredAt desc 머지로 backend 변경 없이 신설. KPI 5장 + 카테고리별 3장 + DataTable 7컬럼 + JSON features 상세 + EventList 네비게이션. 처리 액션은 EventList 경유 (READ 전용)
 
 **백엔드 연동 ✅**:
 - `/api/vessel-analysis/groups` + `/groups/{key}/detail|correlations|candidates/{mmsi}/metrics|resolve` — 모선 워크플로우 (VesselAnalysisGroupService, 2026-04-17 PARENT_RESOLVE @Auditable 추가)
@@ -413,8 +415,8 @@ Frontend ← Backend /api/analysis/* + /api/events + /api/alerts + ... (65+ API)
 | SFR-06 | `features/risk-assessment/EnforcementPlan.tsx`, `backend/.../enforcement/EnforcementController+Service.java` |
 | SFR-07 | `features/patrol/PatrolRoute.tsx` |
 | SFR-08 | `features/patrol/FleetOptimization.tsx` |
-| SFR-09 | `features/detection/DarkVesselDetection.tsx`, `features/detection/components/DarkDetailPanel.tsx`, `features/vessel/TransferDetection.tsx`, `prediction/algorithms/dark_vessel.py`, `spoofing.py`, `transship.py`, `risk.py` |
+| SFR-09 | `features/detection/DarkVesselDetection.tsx`, `features/detection/components/DarkDetailPanel.tsx`, `features/detection/TransshipmentDetection.tsx`(V033), `features/vessel/TransferDetection.tsx`, `prediction/algorithms/dark_vessel.py`, `spoofing.py`, `transship.py`, `risk.py` |
-| SFR-10 | `features/detection/GearDetection.tsx`, `GearIdentification.tsx`, `GearCollisionDetection.tsx`(V030), `features/detection/components/GearDetailPanel.tsx`, `GearReplayController.tsx`, `prediction/algorithms/pair_trawl.py`, `gear_violation.py`, `gear_identity.py`(V030), `gear_correlation.py`, `gear_parent_inference.py`, `vessel_type_mapping.py`, `backend/.../analysis/VesselAnalysisGroupService.java`, `GearCollisionController+Service.java`(V030) |
+| SFR-10 | `features/detection/GearDetection.tsx`, `GearIdentification.tsx`, `GearCollisionDetection.tsx`(V030), `IllegalFishingPattern.tsx`(V032), `features/detection/components/GearDetailPanel.tsx`, `GearReplayController.tsx`, `prediction/algorithms/pair_trawl.py`, `gear_violation.py`, `gear_identity.py`(V030), `gear_correlation.py`, `gear_parent_inference.py`, `vessel_type_mapping.py`, `backend/.../analysis/VesselAnalysisGroupService.java`, `GearCollisionController+Service.java`(V030) |
 | SFR-11 | `features/enforcement/EnforcementHistory.tsx`, `EventList.tsx`, `backend/.../event/EventController+Service.java`, `AlertService.java`, `enforcement/EnforcementService.java` |
 | SFR-12 | `features/dashboard/Dashboard.tsx`, `features/monitoring/MonitoringDashboard.tsx`, `features/detection/ChinaFishing.tsx`, `features/detection/components/VesselMiniMap.tsx`, `VesselAnomalyPanel.tsx`, `backend/.../analysis/VesselAnalysisController+Service.java` |
 | SFR-13 | `features/statistics/Statistics.tsx`, `ReportManagement.tsx`, `backend/.../stats/`, `admin/AdminStatsService.java` |

docs/sfr-user-guide.md

@@ -481,6 +481,68 @@ AIS(선박자동식별장치) 신호를 의도적으로 끈 의심 선박(Dark V
 
 ---
 
+### 불법 조업 이벤트 (V032, 2026-04-20 추가)
+
+**메뉴 위치:** 탐지/분석 > 불법 조업 이벤트
+**URL:** `/illegal-fishing`
+**접근 권한:** ADMIN, OPERATOR, ANALYST, FIELD, VIEWER (READ 전용)
+
+**화면 설명:**
+prediction 이 생산하는 **불법 조업 의심 이벤트 3 종을 한 화면에서 통합 조회**하는 READ 전용 대시보드입니다. 처리 액션(확인/상태변경/단속 등록)은 기존 `/event-list` 이벤트 목록에서 수행합니다.
+
+**통합 대상 카테고리:**
+- **어구 위반 (GEAR_ILLEGAL)** — G-01 수역-어구 불일치 · G-05 고정어구 drift · G-06 쌍끌이 공조
+- **영해/접속수역 침범 (EEZ_INTRUSION)** — 영해 침범(CRITICAL) · 접속수역 + 고위험
+- **특정수역 진입 (ZONE_DEPARTURE)** — ZONE_I~IV 진입 + 위험도 40점 이상
+
+**주요 기능:**
+- 심각도별 KPI 5장 (전체 / CRITICAL / HIGH / MEDIUM / LOW)
+- 카테고리별 건수 3장 + 설명
+- 이벤트 목록 7컬럼 (발생시각 / 심각도 / 카테고리 / 제목 / MMSI / 수역 / 상태)
+- 필터: 카테고리 (단일 또는 전체 3 카테고리 병합) / 심각도 / MMSI 검색
+- 이벤트 상세 패널 — features JSON 원본 + `EventList 에서 열기` 네비게이션
+
+**구현 완료 (2026-04-20 기준):**
+- ✅ 기존 `/api/events?category=X` 를 3 카테고리에 대해 **병렬 호출** 후 occurredAt desc 머지 (backend 변경 없음)
+- ✅ `frontend/src/services/illegalFishingPatternApi.ts` — `listIllegalFishingEvents` 함수 + byCategory/byLevel 집계
+- ✅ V032 권한 트리 `detection:illegal-fishing` + 전 역할 READ 부여
+
+**향후 구현 예정:**
+- 🔲 직접 처리 액션 (ack / 단속 등록) 추가 — 현재는 EventList 네비게이션만
+
+---
+
+### 환적 의심 탐지 (V033, 2026-04-20 추가)
+
+**메뉴 위치:** 탐지/분석 > 환적 의심 탐지
+**URL:** `/transshipment`
+**접근 권한:** ADMIN, OPERATOR, ANALYST, FIELD, VIEWER (READ 전용)
+
+**화면 설명:**
+prediction 의 **5단계 환적 필터 파이프라인** 결과를 전체 목록·집계·상세 수준으로 조회하는 READ 전용 대시보드입니다. 기존 `features/vessel/TransferDetection.tsx` 는 선박 상세 수준이고, 이 페이지는 **전체 환적 의심 선박 목록 운영 대시보드** 입니다.
+
+**prediction 5단계 필터:**
+1. 이종 쌍 (fishing ↔ carrier 매칭)
+2. 감시영역 (관심 수역 내부)
+3. RENDEZVOUS 90분 이상 접촉
+4. 점수 50점 이상
+5. 밀집 방폭 (군집 false positive 제거)
+
+**주요 기능:**
+- KPI 5장 — 전체 + Transship tier CRITICAL/HIGH/MEDIUM + 종합 위험도 CRITICAL
+- 이벤트 목록 8컬럼 (분석시각 / MMSI / 상대 MMSI / 지속분 / Tier / 위험도 / 종합위험 / 수역)
+- 필터: 조회기간(1/6/12/24/48h) / 위험도 / MMSI 검색
+- 상세 패널 — 환적 점수 + 좌표 + features JSON 원본
+
+**구현 완료 (2026-04-20 기준):**
+- ✅ 기존 `/api/analysis/transship` + `getTransshipSuspects` 재사용 (backend 변경 없음)
+- ✅ V033 권한 트리 `detection:transshipment` + 전 역할 READ 부여
+
+**향후 구현 예정:**
+- 🔲 VesselAnalysisController `/api/analysis/transship` 의 @RequirePermission 을 `detection:transshipment` 로 교체 (현재 `detection:dark-vessel` READ 로 가드 중, 운영자 역할은 양쪽 보유하여 실용 동작)
+
+---
+
 ## SFR-11: 단속/탐지 이력 관리
 
 **메뉴 위치:** 단속/이력 > 단속/탐지 이력

docs/system-flow-guide.md

@@ -10,10 +10,15 @@ KCG AI Monitoring 시스템 워크플로우 플로우차트 뷰어 사용법.
 - 메인 SPA(`/`)와 완전 분리된 별도 React 앱
 - 메뉴/링크 노출 없음 — 직접 URL 접근만
 
-> ⚠️ **V030 미반영 경고**: 2026-04-17 V030 로 추가된 GEAR_IDENTITY_COLLISION 파이프라인 (
+> ⚠️ **V030~V034 미반영 경고**: 2026-04-17 V030 (`algo.gear_identity_collision`,
-> `algo.gear_identity_collision`, `storage.gear_identity_collisions`, `api.gear_collisions_*`,
+> `storage.gear_identity_collisions`, `api.gear_collisions_*`, `ui.gear_collision`,
-> `ui.gear_collision`, `decision.gear_collision_resolve`) 노드가 아직 manifest 에 등록되지
+> `decision.gear_collision_resolve`) + 2026-04-20 V032 (`ui.illegal_fishing`) + V033
-> 않았다. 다음 `/version` 릴리즈 시 매니페스트 동기화 필요.
+> (`ui.transshipment_detection`) + **V034 Detection Model Registry**
+> (`storage.detection_models`, `storage.detection_model_versions`,
+> `storage.detection_model_run_outputs`, `storage.detection_model_metrics`,
+> `infra.dag_executor`, `infra.shadow_runner`, `api.detection_models_*`,
+> `ui.detection_model_management`) 노드들이 아직 manifest 에 등록되지 않았다.
+> 다음 `/version` 릴리즈 시 매니페스트 일괄 동기화 필요.
 
 ## 접근 URL