gc/kcg-ai-monitoring
7
0
포크 0
코드 이슈 풀 리퀘스트 Actions 위키 활동

feat(detection): GEAR_IDENTITY_COLLISION 탐지 패턴 추가 + docs 정비 #73

병합
htlee feature/gear-identity-collision 에서 develop 로 2 commits 를 머지했습니다 2026-04-17 07:14:08 +09:00
대화 0 커밋 2 파일 변경됨 28 +2270 -1766
htlee 코멘트됨, 2026-04-17 06:59:56 +09:00
소유자
Copy Link

배경

prediction 5분 분석 사이클이 fleet_tracker.track_gear_identity 내부에서 gear_correlation_scores_pkey 충돌로 전부 실패하고 있어 탐지 API 응답이 비어 보이던 문제를 근본 해결한다. 동일 어구 이름이 서로 다른 MMSI 로 동시 송출되는 케이스는 오히려 어구 복제/스푸핑 의심 증거이므로, GEAR_IDENTITY_COLLISION 신규 탐지 패턴으로 기록·분류한다.

변경 요약

prediction

  • algorithms/gear_identity.py — 공존 쌍 추출 · 심각도 산정 (신규)
  • fleet_tracker.py — 공존(simultaneous) / 교체(sequential) 분기, gear_identity_collisions UPSERT, gear_correlation_scores 이전은 SAVEPOINT 로 격리
  • output/event_generator.py — run_gear_identity_collision_events() 추가 (CRITICAL/HIGH → prediction_events 승격, dedup 367분)
  • scheduler.py — track_gear_identity 직후 승격 호출

backend (domain/analysis)

  • GearIdentityCollision 엔티티 + Repository (Specification + status/severity 집계)
  • GearIdentityCollisionService — 조회 @Transactional(readOnly=true), resolve @Auditable
  • GearCollisionController — /api/analysis/gear-collisions (list/stats/detail/resolve)
  • Response / Stats / ResolveRequest 3종 record

DB

  • V030__gear_identity_collision.sql — gear_identity_collisions 테이블 + auth_perm_tree 엔트리 detection:gear-collision (nav_sort=950) + 역할별 권한

frontend

  • shared/constants/gearCollisionStatuses.ts + catalogRegistry 등록 (쇼케이스 자동 노출)
  • services/gearCollisionApi.ts — list/stats/get/resolve
  • features/detection/GearCollisionDetection.tsx — PageContainer + Section + DataTable + 분류 액션 폼 (디자인시스템 SSOT 준수)
  • componentRegistry + features/detection/index + i18n detection.json(ko/en) + common.json nav.gearCollision

docs

  • architecture.md, sfr-traceability.md, sfr-user-guide.md 2026-04-17 기준 갱신
  • data-sharing-analysis.md, next-refactoring.md, page-workflow.md stale 3건 제거

테스트 계획

  • 로컬 make dev-all 기동 후 /gear-collision 페이지 목록·필터·분류 액션 수동 검증
  • prediction 한 cycle 실행 → gear_identity_collisions UPSERT 로그 확인 + 기존 affinity score transfer failed / analysis cycle failed 로그 사라짐 확인
  • curl -H 'Cookie: ...' /api/analysis/gear-collisions?hours=48 응답 검증
  • ko/en 토글 + axe DevTools aria 위반 0건
  • 운영 반영: V030 마이그레이션 자동 적용 + backend / prediction systemctl restart 필요

배포 주의

  • /api/analysis/gear-collisions READ 권한: ADMIN/OPERATOR/VIEWER/ANALYST/FIELD
  • UPDATE 권한(분류 액션): ADMIN/OPERATOR
  • 좌측 메뉴 어구 정체성 충돌 이 중국어선 분석 과 단속 이력 사이에 노출됨
## 배경 prediction 5분 분석 사이클이 `fleet_tracker.track_gear_identity` 내부에서 `gear_correlation_scores_pkey` 충돌로 전부 실패하고 있어 탐지 API 응답이 비어 보이던 문제를 근본 해결한다. 동일 어구 이름이 서로 다른 MMSI 로 동시 송출되는 케이스는 오히려 어구 복제/스푸핑 의심 증거이므로, `GEAR_IDENTITY_COLLISION` 신규 탐지 패턴으로 기록·분류한다. ## 변경 요약 ### prediction - `algorithms/gear_identity.py` — 공존 쌍 추출 · 심각도 산정 (신규) - `fleet_tracker.py` — 공존(simultaneous) / 교체(sequential) 분기, `gear_identity_collisions` UPSERT, `gear_correlation_scores` 이전은 SAVEPOINT 로 격리 - `output/event_generator.py` — `run_gear_identity_collision_events()` 추가 (CRITICAL/HIGH → `prediction_events` 승격, dedup 367분) - `scheduler.py` — track_gear_identity 직후 승격 호출 ### backend (`domain/analysis`) - `GearIdentityCollision` 엔티티 + Repository (Specification + status/severity 집계) - `GearIdentityCollisionService` — 조회 `@Transactional(readOnly=true)`, resolve `@Auditable` - `GearCollisionController` — `/api/analysis/gear-collisions` (list/stats/detail/resolve) - Response / Stats / ResolveRequest 3종 record ### DB - **V030__gear_identity_collision.sql** — `gear_identity_collisions` 테이블 + `auth_perm_tree` 엔트리 `detection:gear-collision` (nav_sort=950) + 역할별 권한 ### frontend - `shared/constants/gearCollisionStatuses.ts` + `catalogRegistry` 등록 (쇼케이스 자동 노출) - `services/gearCollisionApi.ts` — list/stats/get/resolve - `features/detection/GearCollisionDetection.tsx` — PageContainer + Section + DataTable + 분류 액션 폼 (디자인시스템 SSOT 준수) - `componentRegistry` + `features/detection/index` + i18n `detection.json(ko/en)` + `common.json nav.gearCollision` ### docs - `architecture.md`, `sfr-traceability.md`, `sfr-user-guide.md` 2026-04-17 기준 갱신 - `data-sharing-analysis.md`, `next-refactoring.md`, `page-workflow.md` stale 3건 제거 ## 테스트 계획 - [ ] 로컬 `make dev-all` 기동 후 `/gear-collision` 페이지 목록·필터·분류 액션 수동 검증 - [ ] prediction 한 cycle 실행 → `gear_identity_collisions` UPSERT 로그 확인 + 기존 `affinity score transfer failed` / `analysis cycle failed` 로그 사라짐 확인 - [ ] `curl -H 'Cookie: ...' /api/analysis/gear-collisions?hours=48` 응답 검증 - [ ] ko/en 토글 + axe DevTools aria 위반 0건 - [ ] 운영 반영: V030 마이그레이션 자동 적용 + backend / prediction `systemctl restart` 필요 ## 배포 주의 - `/api/analysis/gear-collisions` READ 권한: ADMIN/OPERATOR/VIEWER/ANALYST/FIELD - UPDATE 권한(분류 액션): ADMIN/OPERATOR - 좌측 메뉴 `어구 정체성 충돌` 이 `중국어선 분석` 과 `단속 이력` 사이에 노출됨
htlee added 2 commits 2026-04-17 06:59:56 +09:00 
- docs/architecture.md: shared/components/ui 9개·i18n 네임스페이스 갱신
- docs/sfr-traceability.md: v3.0 전면 재작성 (운영 상태 기반 531 라인)
- docs/sfr-user-guide.md: 헤더 + SFR-01/02/09/10/11/12/13/17 구현 현황 갱신
- docs/data-sharing-analysis.md / next-refactoring.md / page-workflow.md: stale 3건 제거
동일 어구 이름이 서로 다른 MMSI 로 같은 5분 사이클에 동시 AIS 송출되는
공존 케이스를 신규 탐지 패턴으로 분리해 기록·분류한다. 부수 효과로
fleet_tracker.track_gear_identity 의 PK 충돌로 인한 사이클 실패도 해소.

Prediction
- algorithms/gear_identity.py: detect_gear_name_collisions + classify_severity
- fleet_tracker.py: 공존/교체 분기 분리, UPSERT helper, savepoint 점수 이전
- output/event_generator.py: run_gear_identity_collision_events 추가
- scheduler.py: track_gear_identity 직후 이벤트 승격 호출

Backend (domain/analysis)
- GearIdentityCollision 엔티티 + Repository(Specification+stats)
- GearIdentityCollisionService (@Transactional readOnly / @Auditable resolve)
- GearCollisionController /api/analysis/gear-collisions (list/stats/detail/resolve)
- GearCollisionResponse / StatsResponse / ResolveRequest (record)

DB
- V030__gear_identity_collision.sql: gear_identity_collisions 테이블
  + auth_perm_tree 엔트리(detection:gear-collision nav_sort=950) + 역할별 권한

Frontend
- shared/constants/gearCollisionStatuses.ts + catalogRegistry 등록
- services/gearCollisionApi.ts (list/stats/get/resolve)
- features/detection/GearCollisionDetection.tsx (PageContainer+Section+DataTable
  + 분류 액션 폼, design system SSOT 준수)
- componentRegistry + feature index + i18n detection.json / common.json(ko/en)
claude-bot 이 변경사항을 승인하였습니다. 2026-04-17 07:13:56 +09:00
claude-bot left a comment
멤버
Copy Link

GEAR_IDENTITY_COLLISION 탐지 패턴 + docs 정비 승인 (via /release)

GEAR_IDENTITY_COLLISION 탐지 패턴 + docs 정비 승인 (via /release)
htlee merged commit e0af0e089d into develop 2026-04-17 07:14:08 +09:00
htlee 삭제된 브랜치 feature/gear-identity-collision 2026-04-17 07:14:08 +09:00
"로그인하여 이 대화에 참여"
리뷰어
No reviewers
claude-bot
레이블
레이블 초기화
No items
레이블 없음
마일스톤
마일스톤 초기화
No items
마일스톤 없음
담당자
담당자 초기화
담당자 없음
참여자 2명
알림
마감일
기한이 올바르지 않거나 범위를 벗어났습니다. 'yyyy-mm-dd'형식을 사용해주십시오.

마감일이 설정되지 않았습니다.

의존성

No dependencies set.

Reference: gc/kcg-ai-monitoring#73
No description provided.
Delete Branch "feature/gear-identity-collision"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?