Map Control — 자연어 명령부터 전자해도 좌표 해석, 이벤트 추적까지

워크숍 목표

다 끝내고 나면 D.Hub 안에서 다음 흐름을 한 사이클 손으로 통과한 셈이 됩니다.

• 시나리오 1개를 포털로 적재해 tactical_data (전술 정의) 와 map_ops (운영 제어) 두 sub-collection, 데이터셋 4종, 코드 노드 3종, 파이프라인 3종, 온톨로지 3엔티티/2관계, 대시보드, 지식 1종, 에이전트 1종을 한꺼번에 등록합니다.
• 해양 작전 영역의 전술 구역 7 종 (안전·작전·초계·경계·방공·감시·항만 통제) 정의를 살펴봅니다.
• 운용자의 자연어 명령("여의도 쪽 항만 통제 구역 한 번 보여 줘") 을 의도 분류 → 구역 룩업 → WGS84 좌표 해석 → 줌 레벨 결정 → 구조화 JSON 출력 의 5 단계로 풀어 가는 map_control 에이전트 워크플로를 한 사이클 통과합니다.
• 모든 명령 호출은 om_event_history 에 누가 · 무엇을 · 언제 · 어디서 감사 로그로 기록됨을 확인합니다.
• mc_tactical_zone ↔ mc_graphic_overlay ↔ mc_event_history 그래프에서 한 구역의 명령 호출 이력 을 한 화면에 펼칩니다.
• map_operations 대시보드로 의도 분포 · 시간대 · 사용자 별 활동 패턴을 운영자 시점에서 봅니다.

자연어 명령을 구조화 액션 으로 풀어 외부 UI 시스템 에 넘기는 패턴이 핵심 학습 주제입니다. 권장 소요 시간은 90분.

사전 준비

• D.Hub 포털 접근 가능한 분석가 또는 엔지니어 계정 (Editor 권한 이상)
• 약 44KB 의 zip 한 개를 받을 다운로드 여유

1. 시나리오 적재 (10분)

포털 좌측 사이드바 컬렉션 → 더보기(⋯) → 가져오기 로 zip 을 올립니다.

manifest.json 순서대로 다음 자산이 올라갑니다.

1. 컬렉션 2종 — tactical_data (alias: 전술 데이터), map_ops (alias: 전자해도 운영)
2. 데이터셋 4종 — om_tactical_zone (tactical_data), om_graphic_overlay (tactical_data), om_event_history (map_ops), ui_control_parameters (map_ops)
3. 코드 3종 (Python) — zone_resolver, parameter_formatter, build_map_control_ontology
4. 파이프라인 3종 — zone_data_ingestion, map_control_execution, ontology_materialization
5. 온톨로지 — 엔티티 3종(mc_tactical_zone, mc_graphic_overlay, mc_event_history), 관계 2종(mc_has_spatial_coordinates, mc_referenced_in_event)
6. 지식 1종 — operation_guide (운영 가이드 — 의도 분류 기준 + 출력 스키마)
7. 대시보드 — map_operations
8. 에이전트 — map_control (자연어 → 좌표)

2. 전술 구역 정의 둘러보기 (10분)

tactical_data 컬렉션을 엽니다. 시나리오의 출발점은 전술 구역 정의입니다.

om_tactical_zone (8 행) — 컬럼: zone_id, zone_name, zone_type (safety / operation / patrol / warning / air_defense / surveillance / port_control), description, priority_level, created_at. 시드 데이터는 한국 영해의 가상 구역 8 개를 정의합니다 (예: 안전 항해 구역 A, 초계 구역 부산 외해, 항만 통제 구역 인천).

om_graphic_overlay (8 행) — 같은 8 구역의 WGS84 좌표와 권장 줌 레벨. 컬럼: overlay_id, zone_id (외래키), center_longitude, center_latitude, recommended_zoom_level, boundary_polygon (WKT 텍스트), display_color.

두 데이터셋의 분리 가 의도된 설계입니다. 구역의 의미 (전술 정의) 와 구역의 좌표 (지리 표현) 를 분리해 두면, 같은 구역의 좌표가 변경돼도 의미는 유지되고 그 반대도 마찬가지입니다. §3 의 파이프라인이 두 영역을 zone_id 로 join 해 운영용 단일 테이블을 만듭니다.

3. 운영 파이프라인 — 구역 데이터 통합 (15분)

map_ops 컬렉션의 파이프라인 섹션에서 zone_data_ingestion 을 엽니다. 노드 하나, zone_resolver 스크립트가 두 입력을 통합합니다.

zone_resolver 의 처리:

1. om_tactical_zone + om_graphic_overlay 를 zone_id 로 inner join.
2. WGS84 좌표를 십진도(decimal degree) 표준으로 정규화 (입력이 도분초 형식이면 변환).
3. recommended_zoom_level 이 누락된 구역은 zone_type 별 기본값으로 채움 (예: port_control = 11, patrol = 8).
4. 출력 ui_control_parameters — 컬럼: zone_id, zone_name, zone_type, longitude, latitude, zoom_level, display_color, priority_level.

이 한 테이블이 UI 가 명령 한 번에 받아 쓸 수 있는 형태 입니다. 다음 단계의 에이전트는 자연어 명령을 풀어 이 테이블의 한 행 으로 좁히는 게 핵심 작업입니다.

Run 을 눌러 실행합니다. 끝나면 ui_control_parameters 미리 보기에서 8 행의 좌표·줌이 모두 채워졌는지 확인합니다.

4. 의도 분류 + 안전 게이팅 (10분)

본 워크숍의 안전성 설계 핵심입니다. map_control 에이전트의 첫 도구는 classify_intent — LLM 이 자연어 명령을 다음 3 종 중 하나로 분류합니다.

• UI_CONTROL — 전자해도 화면 제어 의도 (팬닝·줌·오버레이 표시). 허용.
• DATA_QUERY — 데이터 조회 의도 (예: "오늘 초계 가본 구역 알려 줘"). 차단 (별도 운영 데이터 도구가 처리해야 함).
• SYSTEM_CONFIG — 시스템 설정 변경 의도 (예: "화면 색 바꿔"). 차단 (별도 관리자 권한 필요).

차단된 의도는 map_control_execution 파이프라인에 들어가지 않고, 응답으로 "이 명령은 본 에이전트의 범위가 아닙니다. ___ 도구를 사용해 주세요" 가 떨어집니다.

이 허용 목록 기반 게이팅 은 에이전트의 오작동 표면 을 좁히는 표준 안전 패턴입니다. 의도 분류 LLM 이 한 자릿수 오류율로 작동해도, 허용 범위 밖의 의도가 통과할 확률은 그보다 한 단계 더 낮습니다 (UI_CONTROL 로 잘못 분류되어야 통과 가능).

5. 에이전트 한 사이클 — 명령 → 좌표 (20분)

map_ops 컬렉션의 에이전트 영역에서 map_control 카드를 열고 새 세션을 시작합니다.

에이전트 워크플로는 다섯 단계입니다.

1. classify_intent — 자연어 명령을 UI_CONTROL / DATA_QUERY / SYSTEM_CONFIG 중 하나로 분류 (§4).
2. lookup_zone — UI_CONTROL 로 분류된 경우, ui_control_parameters 에서 명령의 구역 키워드 와 가장 잘 맞는 행을 찾습니다 (정확 매칭 우선, fuzzy 매칭 fallback).
3. resolve_coordinates — 찾은 행에서 longitude, latitude, zoom_level 을 추출. 상대 위치 표현 (예: "부산 외해 10NM 쪽") 이면 기준 구역 좌표에서 방위·거리 계산.
4. format_parameters — 외부 UI 시스템이 받을 구조화 JSON 으로 출력: {"command": "pan_and_zoom", "longitude": 129.12, "latitude": 35.05, "zoom": 8, "zone_id": "Z-003", "overlay_color": "#ff0000"}.
5. log_event — 호출 한 번을 om_event_history 에 한 행으로 기록. 컬럼: event_id, user_id, command_text, intent, target_zone_id, output_json, created_at.

세션에서 다음 명령을 차례로 입력합니다. 시드 om_tactical_zone 에는 15NM 안전 구역, 작전 구역 Alpha, 순찰 구역 B-3, 진해만 경계 구역, 제주 남방 방공식별구역, 동해 작전 구역 Charlie, 서해 NLL 감시 구역, 부산항 입출항 통제 구역 총 8 종이 들어 있어 명령의 구역 키워드가 직접 매핑됩니다.

• 명령 1: "15NM 안전 구역 한 번 보여 줘" — UI_CONTROL 로 분류되고, TZ-001 의 좌표·줌이 JSON 으로 떨어집니다.
• 명령 2: "부산항 입출항 통제 구역 쪽 줌인 해 봐" — TZ-008 행이 잡히고, port_control 의 추천 줌 레벨에서 +2 zoom in.
• 명령 3: "오늘 순찰 이력 알려 줘" — DATA_QUERY 로 분류되고 거부 응답이 떨어집니다. 거부도 om_event_history 에 한 행으로 남습니다.

각 명령 끝나면 om_event_history 미리 보기로 가서 세 호출 모두 한 행씩 기록됐는지 확인합니다.

6. 온톨로지 + 그래프 탐색 (10분)

ontology_materialization 파이프라인을 Run 합니다. build_map_control_ontology 가 4 데이터셋을 batch 모드로 읽어 다음 3 엔티티 + 2 관계를 upsert 모드로 적재합니다.

관계 2종:

• mc_has_spatial_coordinates (mc_tactical_zone → mc_graphic_overlay)
• mc_referenced_in_event (mc_tactical_zone → mc_event_history) — 명령이 그 구역을 대상 으로 잡았을 때 연결

그래프 탐색기 에서 한 구역의 명령 호출 이력 을 한 화면에 띄웁니다.

MATCH (z:mc_tactical_zone {zone_type: 'port_control'})-[:mc_referenced_in_event]->(e:mc_event_history)
OPTIONAL MATCH (z)-[:mc_has_spatial_coordinates]->(o:mc_graphic_overlay)
RETURN z, o, e
ORDER BY e.created_at DESC
LIMIT 20

한 항만 통제 구역의 최근 명령 이력 20 건 이 떨어집니다. 같은 구역이 짧은 시간에 여러 번 호출되면 운용자 관심 집중 시그널이고, 한 구역이 서로 다른 사용자에게서 동시에 호출 되면 공유 작전 시점 시그널입니다.

7. 대시보드 + 다음 단계 (10분)

map_operations (alias: 해도 운용 대시보드) 위젯 4종은 모두 om_event_history 한 데이터셋을 봅니다.

• Total Events (statistic) — COUNT(*)
• Events by Intent Type (도넛) — intent_type 별 건수 (UI_CONTROL / DATA_QUERY / SYSTEM_CONFIG 분포)
• Events by User (막대, Top 20) — user_id 별 건수 내림차순
• Recent Events (데이터 테이블) — created_at 내림차순 최근 100건

핵심 운영 시그널은 Events by Intent Type 도넛입니다. 거부 의도 비율 (DATA_QUERY + SYSTEM_CONFIG) 이 지속적으로 30% 이상 이면 두 가지를 동시에 점검해야 합니다 — 명령 의도 분류 LLM 의 허용 목록 보수성 이 너무 빡빡한지, 운용자가 별도 도구로 라우팅해야 하는 의도 를 본 에이전트로 자주 보내고 있는지. 둘 다 다음 라운드의 의제입니다.

Recent Events 테이블은 감사 추적의 첫 표면입니다. 각 행에 누가 · 무엇을 · 언제 · 어떤 의도로 가 함께 기록돼 있어 운영자 시점의 최근 활동 점검 에 그대로 쓰입니다. 시간대별 추세 / 구역별 접근 패턴 같은 시계열 분석 위젯 은 시드에 빌트인 되어 있지 않습니다 — 운영 데이터가 쌓이고 분석 목적이 명확해지면 추가하는 게 자연스러운 다음 라운드 의제입니다.

다음 단계:

• 에이전트 코스 (Phase 2) 에서 허용 목록 게이팅 패턴을 다른 도메인에 옮겨 씁니다.
• 자기 도메인의 명령 → 구조화 액션 흐름 (스마트 팩토리의 작업 지시, 콜센터의 고객 응대) 을 본 형판으로 재구성합니다.

검증 체크리스트

• 컬렉션 트리에 tactical_data 와 map_ops 두 컬렉션이 다 보이고, 데이터셋 4종이 올라가 있는지
• zone_data_ingestion 실행 뒤 ui_control_parameters 의 8 행이 모두 longitude · latitude · zoom_level 컬럼을 채웠는지
• 에이전트 세션의 3 명령 사이클 후 om_event_history 에 정확히 3 행이 기록됐는지 (DATA_QUERY 거부도 한 행으로 남아야 함)
• 그래프 탐색기에서 mc_tactical_zone 한 노드를 시작점으로 좌표 (mc_graphic_overlay) 와 이벤트 (mc_event_history) 두 이웃을 한 화면에 펼칠 수 있는지
• map_operations 대시보드의 Events by Intent Type 도넛 위젯에서 UI_CONTROL 비중이 가장 크고, DATA_QUERY 와 SYSTEM_CONFIG 가 거부 통계로 잡혀 있는지