매핑 시트 — ETL 의 설계도이자 계약서

코드보다 먼저 쓰는 것이 매핑 시트입니다. 소스의 각 필드가 온톨로지의 어디로, 어떻게 가는지의 대응표 — 앞 모듈의 프로파일 리포트와 코스 2의 스펙 사이를 잇는 교량입니다.

서식과 실례(입항신고 발췌):

소스 필드	예시값	대상 (온톨로지)	변환 규칙	검증(L2)	비고
호출부호	D7HB	Vessel.callSign + 결합키 보조	trim, upper	형식 검사	IMO번호 없을 때 보조 결합
선박명	한바다호	Vessel.name	trim	—	결합키로 쓰지 않음(앞 모듈 함정①)
입항일시	2026-08-13 03:20	ArrivalEvent.actualTime	KST 해석→UTC 저장	미래시각 거부	timeBasis="port", source="PORTMIS"
계선장소코드	PNC-B2	Berth 결합 (ALLOCATED_TO)	교차사전 조회	사전 부재 시 격리	코드 방언(함정③) — crosswalk 경유
전출항지	CNSHA	직전 PortCall 연결 (PRECEDED_BY)	UN/LOCODE 검증	코드 유효성	PL-01의 재료
총톤수	52,000	Vessel.grossTonnage	콤마 제거→int	범위(>0)	단위 GT 명시

작성 원칙 세 가지

① 모든 소스 필드는 세 갈래 중 하나로 처분합니다 — 매핑함 / 의도적 미사용(사유 기록) / 보류. ⚠️ 처분 안 된 필드가 남아 있으면 시트 미완성입니다. "이 컬럼은 뭐지?"를 남겨 두면 나중에 아무도 답하지 못합니다.

② 시각 필드는 반드시 timeBasis·source 를 함께 확정합니다. 앞 모듈의 "시각의 세 얼굴"에 대응하는 장치입니다. 이 둘을 비워 두고 넘어가면 나중에 그 시각이 무엇이었는지 복원할 수 없습니다.

③ 매핑 시트는 스펙 문서와 같은 버전 관리를 받습니다. 소스 포맷이 바뀌면 시트 개정이 코드 수정보다 먼저입니다. 코드만 고치면 문서와 실물이 갈라지고, 그때부터 시트는 죽습니다.