규제 기관 안전 데이터 보고용 설정형 게이트웨이
기업 원천 데이터를 표준 객체로, 다시 규제 기관별 메시지 형식으로 매핑하는 보고 플랫폼을 설계했습니다. 설정은 9단계 마법사로 하고, 시크릿은 읽기 전용으로 마운트하며, 하드코딩된 기존 보고 서비스 두 개를 대체했습니다.
핵심 요약: 하드코딩된 보고 서비스 두 개를 게이트웨이 하나로 바꿨습니다. 기업 데이터를 표준 객체로, 다시 규제 기관별 메시지 형식으로 코드가 아닌 설정으로 매핑하며, 서명, 전송, 수신 확인, 재시도, 감사가 기본으로 들어 있습니다.
개요
규제를 받는 안전 분야의 산업 기업은 작업 허가, 인원, 실시간 위치, 위험 관리 데이터를 정부 플랫폼에 보고해야 합니다. 플랫폼마다 필드, 서명, 암호화, 수신 확인 규칙이 다릅니다. 구축 담당자는 9단계 마법사로 새 연동을 설정하고, 시크릿은 호스트에 읽기 전용으로 마운트됩니다.
문제
새 기업, 기업 시스템의 새 버전, 규제 플랫폼의 새 버전이 나올 때마다 기존 서비스의 코드를 고쳐야 했습니다. 업무상 의미는 스크립트와 예외 처리에 흩어져 있었습니다. 연동 작업은 개발자에게 의존했고 감사하기도 어려웠습니다.
제약
- 기존 코드는 업무상 예외를 찾는 데는 쓸 수 있지만, 새 아키텍처를 정하는 데 써서는 안 됨.
- 구축 담당자는 SQL, YAML, JSON, 스크립트를 편집하지 않음. 설계 목표는 신규 연동의 95% 이상을 UI로 설정하고 나머지는 안정적인 플러그인 인터페이스로 처리하는 것. 이 목표는 실제 샘플로 아직 증명해야 함.
- 오프라인 현장을 포함한 고객 구내 배포, 이미지 아키텍처 고정, 검증 가능한 이미지 ID.
- 자격 증명은 설정에 절대 저장하지 않음. 논리적 참조만 저장.
아키텍처
| 구성 요소 | 구현 |
|---|---|
| 백엔드 | Java 21, Spring Boot 4.1, MySQL 8, Flyway 마이그레이션 V1~V14 |
| 콘솔 | Vue 3 + TypeScript 설정 UI |
| 매핑 | 2단계: 원천 필드를 표준 객체로, 다시 표준 객체를 대상 메시지로. 스크립트 언어가 아니라 닫힌 표현식 트리로 표현 |
| 마법사 | 9단계: 범위, 데이터 소스, 조사, 표준 매핑, 대상 메시지, 플랫폼 기능, 테스트, 승인, 배포 |
| 전송 런타임 | 인증, 서명, 암호화. HTTP, TCP, 메시징 전송. 동기·비동기 수신 확인. 스케줄링, 증분, 멱등성, 재시도, 재보고, 대사 |
| 시크릿 | 컨테이너에 마운트하는 읽기 전용 파일 기반 시크릿 저장소 |
핵심 결정
- 닫힌 매핑 언어. 범위가 정해진 표현식 트리는 자유로운 스크립트와 달리 배포 전에 검증하고 감사할 수 있어, 검토자가 매핑이 무엇을 보낼지 정확히 볼 수 있습니다.
- 가운데에 표준 객체. 원천과 대상이 표준 객체에서만 만나므로, 새 기업 시스템이나 새 규제 기관 버전을 추가해도 매핑의 한쪽만 건드리면 됩니다.
- 기본값은 안전한 운영. 스모크 테스트는 상태만 확인하고, 실제 전송에는 명시적인 플래그가 필요합니다. 데이터베이스가 더 새 마이그레이션에 올라가 있으면 롤백은 이미지 다운그레이드를 거부하고, 대신 업그레이드 전 백업을 쓰도록 운영자에게 안내합니다.
근거
- 백엔드 테스트 클래스 78개. 버전 관리 마이그레이션 14개. 첫 범위의 업무 도메인 네 개: 작업 허가, 인원, 실시간 측위, 이중 예방 위험 관리.
- 요구 사항 기준선, 감사 보고서, 결정 로그, 단계별 인수 체크리스트, 배포 매뉴얼이 납품물에 포함됩니다.
한계
95% 설정 가능 목표는 설계 목표이며 현장에서 검증되지 않았습니다. 규제 기관 이름, 엔드포인트, 기업 데이터는 공개하지 않습니다.
자주 묻는 질문
개발자가 아니어도 새 기업 연동을 추가할 수 있나요?
그것이 설계 목표입니다. 구축 담당자는 9단계 마법사를 따라 작업합니다. 제품 범위를 벗어나는 기능은 코어를 고치지 않고 플러그인 인터페이스로 처리합니다.
자격 증명은 어떻게 보호하나요?
설정에는 논리적인 자격 증명 참조만 저장합니다. 실제 시크릿은 호스트에 읽기 전용으로 마운트한 디렉터리에서 읽습니다.
오프라인에서도 동작하나요?
네트워크가 되는 머신에서 이미지를 빌드해 내보낸 뒤, 현장에서 로드하고 이미지 ID로 확인할 수 있습니다.