RailNetwork

리팩터링 전: apicall.js와 trainService.js

외부 API 호출부터 응답 변환·폴백·데이터 병합·노선별 예외까지 apicall.js 하나에 모여 있었습니다. trainService.js는 15초 폴링, 열차 생성과 종료, 시간표 찾기, 지연 계산, MongoDB 이력 저장까지 담당했습니다.

기능은 동작했지만 외부 API 하나를 고치려고 해도 지연 계산과 노선 특수 규칙까지 함께 확인해야 했습니다. 열차·편성 상태 일부가 프로세스 메모리에 있어 서버를 재시작하면 사라지는 문제도 있었습니다.

리팩터링 후: Provider·Policy·Registry·Strategy·Store

Provider는 외부 API를 호출하고 Mapper는 서로 다른 응답을 공통 형식으로 바꿉니다. Realtime Policy는 어느 소스를 먼저 쓰고 실패하면 어떻게 합칠지 정합니다. Registry에는 노선 설정을, Strategy에는 2호선·신분당선처럼 노선마다 다른 규칙을 뒀습니다.

Redis 저장과 부팅 복원은 Persistence가 맡고 app.ts는 이 객체들을 만들어 연결하는 조립 코드로 남겼습니다. 외부 API 변경은 Provider·Mapper에서, 노선별 규칙은 Registry·Strategy에서 찾습니다.

테스트가 덮는 곳과 덮지 않는 곳

2026.09.18 기준 test/ 아래 *.test.* 파일은 166개입니다. test/contract 18개는 Express 패리티, HTTP 헤더·본문 스냅샷, gRPC v1/v2 계약을 확인하고 test/unit 148개가 나머지입니다.

덮지 않는 곳도 있습니다. trainService의 도시철도 틱 경로는 41개 파일이 간접으로만 지나가고 2호선 열번 보정 규칙은 전용 단위 테스트 없이 계약 스냅샷이 결과로만 잡습니다. 신분당선 규칙은 line-sb 단위 테스트가 있습니다.

trainService.ts는 아직 큰 파일입니다. 계약 테스트가 그 경로를 충분히 덮을 때까지는 변경이 생기는 지점만 떼어냅니다.

TypeScript 타입 검사의 범위

빌드에 타입 검사를 넣어 코드 안에서 필드 이름과 형태가 어긋나는 실수를 실행 전에 잡습니다. 다만 타입은 컴파일 뒤 사라지므로 외부 API가 실제로 어떤 JSON을 주는지는 검사하지 않습니다.

외부 응답 검증은 별도입니다. 코레일 GIS는 응답이 GeoJSON FeatureCollection인지 런타임에 확인하고 아니면 예외를 던집니다. 다른 소스는 Mapper가 필요한 필드만 읽고 없으면 그 열차를 건너뜁니다.

v1의 문제: 시간표를 10분마다 통째로

v1 앱은 10분마다 하루치 시간표를 통째로 다시 받았습니다(1호선 gzip 256.8KB). 실시간 응답도 열차마다 행선지·정차역처럼 시간표에 이미 있는 값을 매 틱 다시 실었습니다.

시간표 gRPC(GetSched)는 정차 시각을 절대 unix 초로 내서 내용이 같아도 날마다 전 바이트가 바뀌었습니다. 시간표 세대 번호도 프로세스 안의 정수 하나여서 한 노선을 다시 읽으면 모든 노선 클라이언트가 다시 받았습니다.

v2 설계: 계획과 실적 분리, 내용 해시 버전

REST와 SSE를 그대로 두는 안도 있었지만 gRPC 전용으로 정했습니다. 첫 v2 설계는 실제로 REST와 SSE였습니다.

같은 실시간 필드를 JSON과 protobuf로 인코딩하면 2호선 974운행분이 압축 전 142,432B에서 56,479B로, gzip 후 19,594B에서 5,915B로 줄었습니다(2026.08.28). 데이터 대부분이 시각과 역 번호 같은 작은 정수라서 JSON이 숫자를 글자로 쓰고 키를 반복하는 비용이 그대로 드러났습니다. SSE의 snapshot·delta 스트림은 gRPC 서버 스트리밍으로 모양 그대로 옮길 수 있었습니다. 그리고 2025년에 만든 편성 제보가 이미 gRPC여서 앱에는 gRPC 클라이언트와 gzip 코덱이, 서버에는 gRPC 서버가 떠 있었습니다.

반대로 기존 LineService proto로 재면 1호선이 JSON 164,058B, protobuf 178,493B로 오히려 컸습니다. 열차마다 시간표 전체를 다시 싣고 있었기 때문입니다. 크기를 줄인 건 데이터 모양을 바꾼 쪽이고 protobuf는 그 위에 이득을 더했습니다. curl로 응답을 바로 읽을 수 없는 대가가 있어 상태를 바꾸는 요청은 REST로 남겼습니다. 계획과 실적을 나누는 안은 제가 내고 동료를 설득해 진행했습니다. 앱이 시간표를 받는 경로를 바꿔야 해서 논의가 필요했습니다.

GTFS static과 GTFS-RT의 분업을 따라 계획(TimetableServiceV2.GetTimetables)과 실적(RealtimeServiceV2.GetSnapshot·Subscribe)을 나눴습니다. 계획의 버전은 정수 대신 (노선, 운행일) 내용 해시로 바꿔 blue-green 두 슬롯이 같은 값을 냅니다. 응답은 FULL 또는 NO_CHANGE 둘뿐이라 델타 계산이 없습니다.

정차 시각은 자정 기준 초, 역은 노선별 사전의 인덱스, 열차마다 packed 열로 실었습니다. 정차 패턴이 고른 인천2호선 하선 236편은 gzip 40.9KB에서 2.0KB로 줄었고 편마다 패턴이 다른 KTX는 같은 인코딩에서 60% 감소에 그쳤습니다.

측정한 것과 아직 재지 않은 것

같은 6노선 시간표를 개발 서버에서 재면(2026.09.04) REST JSON 무압축 4.37MB·759ms, gzip 575KB·316ms, gRPC 383KB·58ms였습니다. 압축하지 않은 gRPC가 gzip REST보다 1.5배 작고 5.4배 빨랐습니다. 이 수치는 6노선 시간표 한 번 전송이라는 조건 안의 값입니다.

실시간 SSE에는 Accept-Encoding 협상 뒤 프레임마다 flush하는 압축을 넣어 노선 1개 snapshot 142.6KB가 gzip 19.5KB, Brotli 11.4KB로 줄었습니다.

라이브 부하 테스트 (k6, 2026.09.05)

2026.09.05 새벽 라이브 서버에 앱과 같은 경로(api.railnetwork.kr, Cloudflare 경유)로 k6 부하를 넣었습니다. 부하 생성은 대상 호스트 밖 관측 서버에서 했고 p95가 1초를 넘거나 실패율이 5%를 넘으면 자동 중단하는 가드를 걸었습니다.

같은 부하를 준 비교는 모의 클라이언트 시나리오 하나뿐입니다. v1 계획(/sched)은 개발 컨테이너(CPU 가중치 512·메모리 1GB, 라이브와 호스트 공유)에서 약 10 req/s에 p95 2.04초로 가드가 발동하고 그 직후 컨테이너가 종료됐습니다. 그래서 라이브에서는 v1을 2→8 req/s 저램프로만 재고 v2는 5→40 req/s로 쟀습니다.

표의 계획 채널 p95(v1 196ms, v2 FULL 511ms)는 요청률이 달라 직접 비교하면 안 됩니다. 모의 클라이언트 시나리오는 계획 1회 + 10초마다 실적이고 60초에 걸쳐 점진 투입한 뒤 60초 동안 유지했습니다. 전 시나리오에서 실패 0건, 라이브 health 응답은 최대 53ms였습니다.

수집: 전국 1회 호출과 응답 검증

코레일 GIS는 bbox 하나로 전국 열차를 한 번에 줍니다(약 85KB, 147~153편). 노선별 폴링을 만들지 않고 5초마다 전국 1회 호출하는 별도 스케줄러 틱으로 돌리고 있습니다.

인증 토큰은 없지만 Referer 헤더가 없으면 403과 HTML 오류 페이지가 옵니다. 그래서 응답이 GeoJSON FeatureCollection인지 확인하고 아니면 예외를 던집니다. HTML을 JSON인 척 흘려보내면 상위 계층에서 '열차 0편'으로 조용히 둔갑하기 때문입니다.

추적 모드 3종과 공통 Train 타입

노선마다 확보할 수 있는 데이터가 다릅니다. 도시철도 20개 노선은 REALTIME(서울 열린데이터·SMSS), 코레일은 POSITION_REPORT(GIS 위치 + 시간표), 실시간 정보가 없는 노선은 SIMULATED(시간표만)로 갱신 루프를 나눴습니다.

세 모드 모두 같은 Train 형태를 만들어 Store·라우트·gRPC는 어느 모드가 만든 열차인지 알 필요가 없습니다. 추적 모듈은 네트워크·파일·환경변수 접근 없이 require할 수 있고 시계와 저장소는 인자로 주입합니다.

같은 기준으로 다시 센 커버리지

판정 방식을 바꾼 과정은 사례 카드에 있습니다. 여기서는 바꾼 뒤 다시 센 결과만 적습니다.

56,202개 fix 재생을 '지나간 선로거리 구간 안의 역' 기준으로 다시 세면 2차원 방식과 선로거리 방식이 모두 KTX 94%·ITX 100%입니다. 처음에 본 KTX 61~83%는 판정 기하 때문이 아니라 주로 집계 기준이 이번과 달라서 나온 값이었습니다. 놓침의 대부분은 GIS 위치가 그 구간에 닿지 않은 경우였고 남은 6%는 전부 계획(시간표)이 틀린 열차의 역이었습니다.

선로거리 방식은 실제로는 점프 구간에 들어간 역의 통과 시각을 폐기하지 않고 비례 보간합니다. 계획과 실제 경로가 다른 열차(KTX 68: 계획은 경부선, 실제는 울산 고속선)도 즉시 드러냅니다. 후자는 시간표 품질 신호로 쓰기로 했습니다.

역쌍 930/940만 만들어져 결손 10쌍(동해선 삼척해변·추암, GTX 구성|동탄, 경의선 능곡|대곡)은 아직 선로거리 판정을 쓰지 못합니다.

지연 계산과 upstream_lost

코레일 지연은 업스트림이 주는 값과 시간표 대비 서버 계산값 중 큰 쪽을 씁니다. 업스트림 API는 언제든 부정확해질 수 있다는 전제로, 업스트림에서 사라진 열차를 '완주'로 기록하지 않는 규칙(upstream_lost)을 정했습니다. 종착 칸에 관측이 있으면 completed, 없으면 upstream_lost입니다.

v1 응답은 원칙적으로 동결이지만 잘못된 '완주' 기록만은 예외로 두고 정확성을 택했습니다(ADR-0007). 2026.09.10 기준 분류와 결손 디바운스까지 구현이 끝났습니다.

인덱스 구조

그날 쓰는 시간표(평일 또는 휴일)의 열차 한 편이 trip 하나입니다. trip은 정차역 id 배열과, 같은 길이의 승차·하차 시각 배열을 듭니다. 시각은 열차 추적과 같은 파서로 읽은 운행일 기준 초이고 시발역 하차와 종착역 승차 칸은 -1로 막습니다. 통과역은 넣지 않아서 탐색 코드에 통과역 분기가 없습니다.

노드는 역입니다. 노선이 달라도 같은 역은 한 노드이고 표기가 달라도 합칩니다(지하서울역 → 서울역). 이름만 같은 다른 역은 가릅니다(5호선 양평과 53km 떨어진 경의중앙 양평). 같은 역에서 다시 타면 라운드가 하나 늘어나므로 같은 노선 급행↔완행 갈아타기도 따로 규칙 없이 환승 1회가 됩니다.

route는 노선과 정차 패턴이 같은 trip 묶음입니다. 등급과 실제 정차 수가 뒤집힌 편성이 있어 등급 문자열로는 묶지 않습니다. route 안의 trip은 첫 출발 순으로 두고 역마다 그 역을 지나는 (route, 위치) 목록을 미리 만듭니다. 2026.08.21 평일 시간표에서 route 하나에 든 trip은 중앙값 1편, p90 10편, 최대 258편이었습니다.

trip에는 원본 시간표의 칸 번호도 둡니다. 통과역을 빼면 인덱스 위치와 원본 칸 위치가 갈리기 때문입니다. 2026.09.04 기준 코레일 991편 중 969편(97.8%)이 실제로 갈렸고 응답과 재탐색은 이 칸 번호로 승하차 지점을 가리킵니다.

라운드와 라벨

라운드 k는 k번째 승차입니다. 직전 라운드에 새 라벨이 생긴 역에서만 타고 이번 라운드가 만든 라벨은 다음 라운드부터 씁니다(격리 방식은 사례 카드에 있습니다). 새 라벨이 하나도 없거나 '최대 환승 + 1'번째 라운드가 끝나면 멈춥니다. 최대 환승 기본값은 3회입니다.

라벨이 있는 역마다 지나는 route의 trip을 전부 보고 가장 이른 라벨 도착 뒤에 출발할 수 있는 trip(지연 포함)을 모읍니다. route마다 가장 이른 trip 하나만 고르는 이진 탐색은 쓰지 않습니다. 지연을 더하면 같은 route에서도 뒤 열차가 앞 열차를 추월하고 최대 대기·도착 마감·최소금액 조건에서는 더 늦은 trip만 맞는 연결이 되기 때문입니다. route당 trip이 적어 전부 봐도 비용이 작습니다.

모은 trip은 첫 출발 순으로, 처음 탈 수 있는 위치부터 종착까지 훑습니다. 내릴 수 있는 역에서는 타고 있는 승객마다 지연을 더한 도착으로 라벨 후보를 만듭니다. 탈 수 있는 역에서는 직전 라운드 라벨마다 '도착 + 환승시간 + 사용자 여유 ≤ 출발'과 최대 환승 도보·대기를 확인합니다. 최소금액·도착 마감 검색이 아니면 먼저 탄 승객이 언제나 이기므로 승객이 하나라도 탄 trip은 뒤 역의 승차 후보를 만들지 않습니다.

라벨은 도착시각, 타고 온 route, 출발시각, 승차 횟수, 요금 상태, 구간 목록을 듭니다. 역마다 타고 온 route별로 버킷을 나누고 라운드와 상관없이 같은 버킷 안에서만 지배를 비교합니다. 승차 횟수와 도착이 모두 같거나 나으면 지배입니다. 최대 대기 조건은 도착이 같을 때만 지배로 봅니다. 도착 마감 검색은 늦은 출발을, 최소금액은 요금 상태를 기준에 더합니다.

버킷을 나눈 이유는 환승시간이 타고 온 노선마다 달라서입니다. 합성 시간표에서 X역에 1호선이 08:02, 2호선이 08:03에 닿고 3호선이 08:04에 떠나며 3호선까지 환승이 각각 300초·10초면 정답은 2호선→3호선입니다. 역마다 가장 이른 도착 하나만 두던 첫 판은 08:02 라벨이 08:03 라벨을 지워 결과가 비었습니다. 2026.09.12에 고치고 이 반례를 회귀 테스트로 남겼습니다.

trip 스캔이 끝나면 그 라운드 라벨의 스냅샷에서 도보 연결을 한 번만 풉니다. 걸어서 생긴 라벨은 같은 라운드에서 다시 타거나 도보를 잇지 않습니다. 마지막에는 목적지 라벨 중 (승차 횟수, 도착)에서 지배되지 않는 것만 남기고 목표에 맞춰 정렬합니다. 작업량이 상한(비교·스캔 500만 회, 라벨 25만 개)을 넘으면 부분 결과를 최적으로 내지 않고 오류(REST 422)로 답합니다.

가지치기, 캐시, 워커 스레드

2026.10.01에 탐색량을 줄이는 변경을 넣었습니다(탈 수 있는 trip만 모으기, 승객이 탄 trip의 추가 승차 생략, 받아들인 라벨에만 구간 목록 만들기, 목적지 하한 가지치기). 그날 시간표 질의 120개에서 최단시간·최소환승 결과는 모두 그대로였고 최단시간 p50은 144ms에서 33ms가 됐습니다. 2026.08.21의 p50 0.6ms는 역마다 도착 하나만 두던 스파이크 값이라 바로 비교하지 않습니다.

하한은 목적지에서 역방향 다익스트라를 한 번 돌려 구합니다. 간선은 route에서 이웃한 두 역 사이의 가장 짧은 주행시간과 도보 시간이고 환승은 0초로 봅니다. 그래서 실제보다 길 수 없고 '라벨 도착 + 하한'이 이미 찾은 최선 도착보다 늦을 때만 버립니다. 지연은 trip 전체를 같은 초만큼 미뤄 구간 시간이 그대로라 실시간 탐색에도 씁니다.

도착 마감 검색은 가장 늦은 출발을 찾느라 도착시각으로 가지치기를 못 합니다. 그래서 출발 창을 1·3·9·24시간으로 넓혀 가다 결과가 나온 첫 창에서 멈춥니다. 최소금액은 먼저 최단시간을 찾고 그 소요의 1.5배(최소 +30분) 안에서 찾습니다. 창 없이 하루치를 뒤지면 코레일이 끼는 역쌍 대부분이 작업 상한에 걸렸습니다. 2026.10.01 시간표 질의 40개에서 이 창의 p90은 1.0초였습니다.

탐색은 동기 CPU 작업이라 메인 스레드에서 돌면 열차 추적 틱·gRPC 스트림·헬스체크가 멈춥니다. 2026.10.01부터 워커 스레드에서 돌립니다. 바쁘면 거절 대신 줄을 세우며 같은 요청은 합쳐 한 번만 계산합니다. 최소금액은 다른 목표보다 10배쯤 무거워서(2026.10.01 dev 측정) 가벼운 요청을 먼저 내고 5초 넘게 기다린 최소금액은 먼저 냅니다.

같은 날 dev 부하 측정에서 워커 1개는 초당 약 5건이 한계였고 동시 50건일 때 헬스체크 p99는 47ms였습니다. 워커 2개로 동시 200건을 걸면 768MiB 컨테이너가 715MiB까지 차서 메모리 한도가 1.5GB 미만이면 워커를 1개로 둡니다.

환승시간 조회는 dev 규모로 모사한 시간표(2026.09.04)에서 탐색 한 번에 중앙값 6,275번 불렸지만 표본 150건 전체의 서로 다른 키는 1,395개였습니다. 그래서 (역, 노선쌍, 갈아타는 종류)를 수 하나로 묶은 키로 인덱스마다 메모합니다. 실시간 지연표는 1초 TTL일 때 거의 매 요청 다시 지어져 요청당 9.3ms를 더 썼습니다(2026.09.04 dev). 지금은 10초 틱의 스캔 시각을 키로 씁니다.

계속승차와 재탐색 정책

2호선 성수와 6호선 응암에서는 같은 차량이 계속 달리는데 원본 시간표는 거기서 열번을 나눕니다. 인덱스가 이 경계를 새 승차로 세서 2026.09.12 공개 서버에서 뚝섬→건대입구와 새절→역촌이 환승 1회로 나왔습니다. 같은 노선 환승을 통째로 0회로 치면 지선 이동과 반대 방향 재승차까지 사라져서 그 방법은 쓰지 않았습니다.

원본의 다음 열번 필드가 가리키는 trip이 하나뿐이고, 앞 trip 종착역이 뒤 trip 시발역이고, 10분 안에 이어 출발하고, 정해 둔 이음매 순서(뚝섬→성수→건대입구 등)와 맞을 때만 인덱스에 연결을 붙입니다. 편성 번호나 운행일이 다르거나, 입고이거나, 후보가 둘 이상이면 붙이지 않습니다.

탐색은 앞 trip 종착에 닿은 승객을 같은 라운드 안에서 뒤 trip에 그대로 태우고 지연도 넘깁니다. trip을 첫 출발 순으로 훑고 뒤 trip은 앞 trip보다 늦게 출발해야 하므로 앞 trip이 항상 먼저 처리됩니다. 응답은 원본 trip과 칸 번호를 그대로 두고 뒤 구간에 계속승차 표시만 붙입니다. 이 결정은 ADR로 남겼습니다.

최단시간·최소환승·최소금액 비교는 엔진의 라벨 안에서 합니다. 결과 몇 개를 받아 밖에서 다시 정렬하면 시간·환승에서 밀린 싼 경로는 이미 Pareto 단계에서 빠진 뒤이기 때문입니다. 최대 환승 기본값은 2026.10.05에 2회에서 3회로 올렸습니다. 질의 30개 × 출발 3시각에서 p50은 27ms → 22ms로 느려지지 않았고 90건 중 10건에 더 빠른 3회 환승 여정이 붙었습니다.

재탐색은 타고 있는 구간과 계속승차 구간을 고정하고 나머지만 다시 찾습니다. 환승 예산은 실제 새 승차만 깎고 최대 총시간은 처음 요청 기준의 절대 마감으로 둡니다. 처음에는 같은 목표로 60초 이상 빨라지면 경로를 바꿨지만 사용자가 고른 후보가 기록에 없어 첫 틱에 엔진 1순위로 바뀔 수 있었습니다. 2026.09.18부터는 환승 연결이 불가능해졌거나 도착이 3분 이상 늦어졌을 때만 교체를 검토합니다.

무엇이 깨지면 실패하는가

정답 데이터가 없어서 여정이 자기 자신과 모순되지 않는지를 검사합니다. 승차가 하차보다 늦은가, 다음 승차가 직전 하차 + 환승시간보다 이른가, 출발 전에 탔는가, 라운드 k의 도착이 k−1보다 이른가, 통과역에서 탔는가를 봅니다.

라운드 격리가 깨지면 두 번째 규칙이 잡습니다. 초기 엔진(2026.08.21) 실측은 15역쌍 × 6시각 질의에서 나온 여정 149건에서 정상 모드 위반 0건, 일부러 규칙을 깬 --broken 모드 위반 7건입니다. broken 모드가 반드시 실패해야 이 검사가 살아 있다는 뜻이라 함께 돌립니다.

모델링하지 않은 것

이름이 다른 역 사이의 도보 연결은 환승 통로로 확인한 두 쌍(아산↔천안아산, 경전철의정부↔의정부)뿐이고 좌표가 가깝다는 것만으로는 넣지 않습니다. 같은 역 안 환승은 공개 환승표 값을 씁니다. 표에 없는 쌍은 기본값(서울교통공사 데이터 중앙값 92초, 반대편 승강장 180초)으로 계산하고 여정에 추정 표시를 붙입니다. 계단·엘리베이터 동선은 없습니다.

지연은 trip 전체를 같은 초만큼 미루는 값으로만 씁니다. 한 trip 안에서 역마다 지연이 달라지는 것(회복·누적)은 반영하지 않고 다른 날짜 검색에는 실시간을 쓰지 않습니다. 병결 열차는 후보로 표시만 하고 환승 없는 연결로 쓰지 않습니다. 최대 환승 상한은 3회입니다.

안내 중에 타고 있는 열차에서 원래 하차역보다 앞에 내려 갈아타는 최적화는 없습니다. 서버의 탑승 여부는 열차 위치로 추정한 값이고 열차를 놓친 뒤에는 사용자가 다시 검색합니다. 최소금액은 운임을 계산할 수 있는 후보 안에서 비교한 추정이라 전체망 최저운임을 보장하지 않습니다.

아키텍처

외부 데이터는 Provider·Mapper에서 공통 형식으로 바꾸고 Realtime Policy가 소스 선택·폴백·병합을 결정합니다. 노선·운영사 설정은 Registry에, 신분당선 열번 추론 같은 예외는 Strategy에 둡니다.

현재 런타임 상태는 Train/Vote Store가 관리하고 Redis는 매 틱 저장과 부팅 복원을, MongoDB는 운행 이력을 맡습니다. 이력은 열차 객체 하나의 운행을 통째로 쌓고 통째로 읽기 때문에, 관계형 테이블로 나눌 이유를 찾지 못해 문서 한 덩어리로 저장합니다. Fastify REST v1·gRPC v2·SSE로 결과를 제공하고 있으며 v1 REST는 기존 앱 호환을 위해 바이트 단위로 동결했습니다.

두 공공 API를 같은 형식으로 정규화

SMSS와 열린데이터는 응답 구조와 필드 의미가 다릅니다. 데이터 출처를 서비스 코드 곳곳에서 확인하지 않도록 두 응답을 같은 형식(열린데이터 응답의 열차 목록 필드, ttcVOList)으로 바꿨습니다. 그래서 주 소스를 SMSS에서 열린데이터로 바꿀 때 열차 처리 코드는 그대로 둘 수 있었습니다.

제보 요청 검증과 제한

공공 API는 열차 편성(어떤 차량이 몇 량인지) 정보를 주지 않고 크롤링으로도 얻을 수 없어 사용자가 제보하고 다른 사용자가 투표로 검증하는 흐름을 만들었습니다.

제보 요청은 SHA-256 해시를 비교하고 타임스탬프·Nonce를 확인해 변조된 요청과 같은 요청의 재사용을 제한합니다. gRPC 제보 경로에는 요청 횟수 제한과 IP 지역 제한을 적용했고 오류는 Winston 구조화 로그로 남깁니다.

앱·watchOS·위젯까지 이어받은 한 달

팀에서는 백엔드(TrainAccAPI)를 담당했고 이후 Flutter 앱(Dart 약 37k LOC, MVVM)·watchOS 앱·iOS 홈 위젯까지 포함한 서비스 전체를 이어받았습니다. 코드베이스를 읽어 구조를 파악하고 스토어 배포(GitHub Actions)와 장애 대응을 유지하는 것이 그 한 달의 목표였습니다.

약 한 달 뒤 원래 클라이언트를 개발하던 동료가 복귀해 지금은 2인 팀이고 저는 백엔드·인프라를 전담하고 있습니다. 앱·watchOS·위젯 구현은 그 동료가 맡고 있습니다.

서버 계약은 proto 파일을 먼저 레포에 올리고 주석에 필드가 왜 있는지까지 적는 방식으로 정합니다. 동료가 그걸 읽고 구현하고 애매한 건 채팅으로 정했습니다. 별도 문서는 만들지 않았습니다.

신규 노선 추가 (엑셀 배선도 + MapTool)

팀은 노선 배선도를 엑셀로 관리하고 Python 변환 도구(MapTool)로 앱 노선도 데이터를 생성합니다. 이 워크플로를 이어받아 경강선 등 신규 노선을 배선도 파일 작성과 변환 명령만으로 추가하고 있습니다.

변환기 코드는 240줄 남짓이고 실제 자산은 25개 노선의 승강장 위치·선로 연결이 들어 있는 엑셀 쪽입니다. 2인 팀이 이 도구로 25개 노선을 유지보수하고 있습니다.

레포 7개 점검 (2026.08)

레포가 7개로 늘어난 뒤에는 기억만으로 문제를 관리하기 어려웠습니다. 2026년 8월에 앱·백엔드·변환 도구·랜딩을 다시 확인하고 레포별 문제 목록을 만들었습니다.

이 점검에서 gRPC 델타 응답의 변경 열차 누락(사례 카드 참조)과 호출되지 않는 캐시 무효화 함수를 찾았습니다. 앱 로그에서 본 증상을 서버 코드로 따라가는 방식이라 이후로는 앱 로그 확인을 점검 절차에 넣었습니다.

배포 파이프라인

라이브는 2026.08.22까지 PM2 프로세스였습니다. 앱 배포는 GitHub Actions인데 서버만 Jenkins인 건 과도기라서입니다. 서버를 OKE 플랫폼으로 옮기고 싶지만 지금 서버는 다른 리전의 프리티어 인스턴스여서 제 리전으로 옮기면 과금이 붙습니다. 지금은 Jenkins가 main·dev 푸시를 받아 typecheck·테스트·패리티를 거쳐 이미지를 만들고 Portainer 스택으로 올립니다.

라이브 스택은 lb(nginx)·redis·api-blue·api-green 넷입니다. lb의 active-slot·writer-slot 마커 두 줄을 switch.sh가 한 번에 바꿔 전환하고 두 슬롯은 Redis lease로 writer를 하나만 둡니다. standby는 잡을 걸지 않고 lease 홀더만 등록합니다.

종료 순서를 정한 이유

종료는 SIGTERM 뒤 8초 안에 진행 중 틱 대기 → 상태 큐 비움 → SSE·HTTP·gRPC 닫기 → 최종 저장 → lease 반납 순서로 끝냅니다.

순서를 정하기 전에는 최종 저장 뒤에 writer가 메모리를 다시 바꾸거나 이미 닫힌 Redis에 쓰는 구간이 있었습니다. flip 뒤 90초를 기다리는 것도 lb의 worker_shutdown_timeout이 90초라 옛 워커가 그때까지 살아 있기 때문입니다.

호스트 제약

dev와 live가 같은 2코어 호스트를 쓰고 있어 부하 실측 중 dev 컨테이너가 종료됐습니다. 용량 계획은 남은 과제입니다.

부하 생성기(k6)는 대상 호스트 밖 관측 서버(noraneko)에 두고 있습니다. 런북 첫 줄은 'Redis를 비우지 마라'입니다. 여기서 Redis는 캐시가 아니라 열차 상태 저장소여서 지우면 전 노선 지연이 0부터 다시 쌓입니다.

월간 총 사용자 추이 (2025.09~2026.10)

2026.10 총 사용자는 27일까지 7,693명으로 월 단위 최고치입니다. 1년 전 같은 달(2025.10) 3,420명의 2.2배입니다. 2025.09 3,035명부터 한 번도 줄지 않았습니다.

2025.09~2026.08 12개월 합산은 총 사용자 15,838명, 새 사용자 10,377명, 재방문 12,207명, 이벤트 4,823만 건, 사용자당 평균 참여 시간 3시간 45분이었습니다. 유입은 Organic Search 55.7%·Direct 46.7%(채널 중복 포함)이고 광고는 집행하지 않았습니다.

최근 28일 (2026.09.29~10.26)

총 사용자 7,797명, 새 사용자 2,591명, 재방문 6,174명입니다. 30일·7일·1일 활성 사용자는 7.8천·4.3천·1.9천 명이고 DAU/MAU 24.1%, DAU/WAU 43.5%, WAU/MAU 55.5%입니다. 직전 측정(아래 절)과 비교하면 30일 활성은 약 6천 명에서 7.8천 명으로, 1일 활성은 1.7천 명에서 1.9천 명으로 늘었고 DAU/MAU는 29.0%에서 24.1%가 됐습니다.

활성 사용자당 평균 참여 시간은 52분 50초, 참여 세션 15회, 세션당 3분 05초입니다. 이벤트 633만 건 중 열차 상세 조회(page_trainDetails)가 140만 건, 역 상세 48만 건, 노선 상세 37만 건입니다. 활성 사용자는 Android 71.6%·iOS 28.4%이고 비정상 종료 없는 사용자 비율은 Android 98.6%·iOS 98.0%입니다.

앱 광고 (AdMob)

2026.09 한 달 광고 요청은 414만 회, 노출은 145만 회, 일치율은 63.12%였습니다(AdMob 미디에이션 보고서). 1년 전 같은 달(2025.09)에는 광고 기록이 없습니다.

최근 7일(2026.10.20~26)은 요청 164만 회, 노출 48.8만 회, 일치율 55.02%입니다. 노출의 74%가 Android이고 형식은 대부분 배너입니다. 보상형 광고 노출은 같은 7일 동안 109회였습니다.

재방문·참여·유지 (2026.08.08~09.04)

이 28일 동안 활성 사용자는 5,997명이고 그중 재방문이 5,246명(87.5%), 새 사용자가 1,016명이었습니다. DAU/MAU 29.0%, DAU/WAU 45.7%, WAU/MAU 63.5%로, 30일 활성 6천 명 중 하루 평균 1.7천 명이 들어옵니다.

활성 사용자당 평균 참여 시간은 28일 동안 55분 19초, 참여 세션 17회, 세션당 2분 53초였습니다. 열차를 확인하고 바로 닫는 짧은 세션이 하루 여러 번 반복되는 패턴입니다.

신규 사용자 유지는 1일째 30.4%, 8일째 15.1%, 34일째 약 11%입니다(2026.09.04에 끝나는 42일 기준). 같은 28일의 이벤트 414만 건 중 열차 상세 조회(page_trainDetails)가 129만 건으로 가장 많았습니다.

지역 분포와 기간이 다른 집계

2025.11~2026.02 Firebase Analytics 기준으로 서울 68%·경기 22%·기타 10%였습니다. 같은 90일 동안 이벤트 1,200만 건 이상, 활성 사용자 6,375명이 기록됐습니다.

이 6,375명은 90일 창의 활성 사용자이고 위의 5,997명은 28일 창의 활성 사용자라 서로 비교하는 값이 아닙니다. metrics의 6,510명은 또 다른 정의(2026.09 한 달의 총 사용자)입니다.

리팩터링 순서: 2024년과 2026년

2024년 3월 커밋 메시지는 'code refactoring, apply later', 4월은 'still problem arises (ONLY USE IN LOCAL)'입니다. 구조를 먼저 바꾸고 나서 동작이 같은지 확인하려 했는데 확인할 방법이 없어서 라이브에 올리지 못했습니다.

2026년 8월에는 거꾸로 했습니다. 노선·소스별 특수 규칙 115개를 목록으로 만들고 기존 응답과 헤더를 특성화 테스트로 고정한 뒤(Phase 0), 그 테스트를 돌리면서 apicall.js와 trainService.js의 책임을 Provider·Policy·Registry·Strategy·Domain으로 옮겼습니다.

이때부터 변경 전에 '이 변경이 깨지면 무엇이 알려주나'를 먼저 확인하고 있습니다.

레거시 호환: v1 응답 동결

리팩터링 중에도 스토어에 있는 앱은 v1 REST를 그대로 호출합니다. 그래서 v1은 필드 이름은 물론 헤더 순서와 오류 본문까지 바이트 단위로 동결했습니다. Express에서 Fastify로 옮기는 동안에는 두 서버를 같은 요청으로 두드려 응답을 비교하는 패리티 도구(parity·header-parity·live-parity)를 만들어 CI에 넣었습니다.

JSON 파싱 오류 응답이 V8 엔진의 문구를 그대로 싣고 있어서 Node 버전이 바뀌면 계약이 깨지는 문제도 이때 발견했습니다. v2에서는 엔진 문구를 싣지 않는 봉투 형식으로 바꿨습니다(ADR-0003). 새 기능은 전부 v2 표면에만 두고 v1은 손대지 않는 것이 규칙입니다.

계획서와 실측

절 번호가 붙은 계획서를 먼저 쓰고 구현은 그 절 단위로 합니다. 이번 리팩터링에서 계획서가 틀린 지점이 세 번 있었습니다.

gRPC 시간표 인코딩의 바이트 계산에서 trip_id 열 하나를 빼고 세어 구현 후 재측정과 3~5% 어긋났습니다. 원인을 찾아 표 옆에 '세지 않은 열이 있었다'고 적었습니다. 관광열차를 새마을호와 가르던 열번 대역 규칙은 업스트림이 둘을 같은 코드로 준다는 걸 확인하고 지웠습니다. 코레일 선로거리 판정은 계획서에서 커버리지 90%를 기대했는데 재생하니 기존 방식보다 1~3역 뒤져서 버리지 않고 둘을 합집합으로 확정했습니다.

셋 다 재생·재측정·로그가 잡았습니다. 이후로는 계획서 항목마다 '틀렸다면 무엇으로 알 수 있나'를 같이 적습니다.

남은 것

trainService.ts는 여전히 큽니다. 운영 중인 핵심 경로라 계약 테스트가 그 경로를 충분히 덮을 때만 잘라낼 생각입니다.

dev와 live가 같은 2코어 호스트를 쓰고 있어 용량 계획이 필요합니다. 선로거리 판정은 결손 역쌍 10개가 남아 있고 선로 데이터의 버킷 연동도 컨버터 파이프라인에 붙일 때까지는 scp로 둡니다.

다시 만든다면 SSE는 넣지 않을 겁니다. v2 Subscribe와 역할이 겹쳐 전송 표면이 셋이 됐고 지금은 v1 앱 호환 때문에 유지하고 있습니다.