JSON 생성 스크립트도 제품 코드였다

교육 콘텐츠를 ViewerData로 만드는 스크립트는 처음에는 보조 도구처럼 느껴졌다. chapter, learningScenes, metaData를 만들고 결과를 파일로 저장하면 되는 작업이었다. 하지만 화면은 이 스크립트의 결과를 전제로 동작했다. 생성 단계의 작은 실수가 나중에는 뷰어의 이상 동작으로 나타날 수 있었다.

값을 어디서 넣는지부터 정해야 했다

field와 왼쪽 콘텐츠의 id 같은 값을 어디에서 주입할지가 고민이었다. 생성 함수가 모든 값을 추측하면 호출부는 편해진다. 대신 데이터가 예상과 다를 때 왜 그 값이 들어갔는지 추적하기 어려워진다. 반대로 모든 필드를 외부에 맡기면 생성기의 역할이 희미해지고 반복 코드가 늘어난다.

지금 이 경계를 다시 적으면, 프로젝트마다 달라지는 의미 있는 값은 입력으로 받고 구조적인 기본값은 생성기가 책임지게 하겠다. 필수값이 없는 경우에는 빈 문자열을 채워 파일을 만들어 주기보다 어느 입력이 빠졌는지 알려 주는 편이 낫다.

읽기·변환·쓰기를 나눠 보는 이유

당시 Node.js로 data/kids, data/default의 파일을 읽고 결과를 public/data에 저장하는 작업을 했다. 이때 파일 시스템 접근과 객체 변환을 분리하면 변환 규칙만 따로 살펴보기 쉬워진다. 파일을 쓰지 않고도 입력 하나가 어떤 장면 구조가 되는지 확인할 수 있기 때문이다.

검증 기준으로는 장면 ID 중복, 필요한 콘텐츠 누락, 참조하는 ID의 존재 여부가 먼저 떠오른다. TypeScript 타입은 코드를 작성하는 동안 도움을 주지만 파일에서 읽은 실제 데이터가 타입과 맞는지는 별도 확인이 필요하다. 타입 선언만으로 잘못된 외부 JSON을 정상으로 바꿀 수는 없다.

다시 만든다면 남길 결과물

지금이라면 생성 성공 메시지에 출력 경로뿐 아니라 처리한 파일 수와 장면 수를 함께 남기겠다. 실패한 입력은 경로와 이유를 알려 주되 전체 데이터를 무작정 로그로 쏟지 않겠다. 결과 파일을 비교할 때 불필요한 변경이 생기지 않도록 생성 시점의 ID 정책도 점검하겠다.

이 경험은 “개발자만 쓰는 스크립트니까 대충”이라는 생각을 바꿨다. 사용자가 직접 누르지 않아도 제품의 데이터를 만드는 코드는 제품의 일부다. 화면에서 찾기 어려운 오류를 입력 단계에서 설명해 주는 것이 생성기의 중요한 기능이었다.

관련 기록: 장면 ID의 역할