웹스퀘어(WebSquare) 화면을 React로 전환하는 절차 — 무엇이 바뀌고 무엇이 그대로인가

WebSquare(웹스퀘어)로 만든 업무 시스템을 React로 옮기려는 팀이 가장 먼저 묻는 것은 "어디까지 바꿔야 하나"다. 답은 생각보다 좁다. 바뀌는 것은 화면 계층(XML 화면 정의와 그 안의 스크립트)이고, 백엔드·DB·업무 로직은 그대로다. 이 글은 그 경계와, 도구(ws2react)를 써서 옮길 때의 절차·소요를 실측 기준으로 정리한 것이다.

바뀌는 것과 그대로인 것

백엔드를 건드리지 않는 것이 핵심이다. 전환 범위가 화면 계층으로 한정되기 때문에 사업 부서 승인, 테스트 범위, 보안 심사 범위가 모두 작아진다.

절차 5단계

1. 의존성 추출 — 화면 XML 전체에서 실제로 호출되는 공통 스크립트·컴포넌트·통신 규약을 자동으로 뽑는다. 이 목록이 "우리 시스템의 전환 난이도"를 결정한다. 미지원 컴포넌트가 있으면 이 단계에서 드러난다.
2. 어댑터 준비 — 프로젝트마다 다른 공통 스크립트(팝업 열기, 공통코드 조회, 통신 래퍼)를 호환 계층으로 이식한다. 도구가 골격을 생성하고 타입검사로 검증한다.
3. 화면 변환 — 화면 단위로 변환한다. 규칙 파서가 구조를 뽑고, LLM이 스크립트 로직을 옮기고, 검증 루프(타입검사 → 빌드 → 렌더 → 시나리오 → 계약 대조)가 통과한 코드만 남긴다. 실패하면 에러를 피드백해 자동 재시도한다.
4. 회귀 — 규칙·어댑터를 손댈 때마다 이미 통과한 화면 전체를 재검증한다. 통과 화면이 곧 테스트 스위트다.
5. 수작업 큐 처리 — 재시도 한도 안에 통과하지 못한 화면은 마지막 에러와 함께 목록화된다. 사람은 이 목록만 본다.

실측 소요

실제 업무 시스템 두 곳의 64화면(조회/등록, 팝업, 탭·멀티그리드, 트리, 파일첨부, 대형 화면)을 넣은 결과다.

화면 100개 규모라면 변환 자체는 하루 안에 끝나고, 사람의 시간은 어댑터 검토와 수작업 큐, 그리고 업무 검수에 쓰인다.

자주 묻는 질문

그리드처럼 무거운 컴포넌트는 어떻게 되나요?

1:1 매핑 대신 호환 래퍼로 감싼다. 화면 스크립트가 부르던 getRowCount, setCellData, getMatchedJSON 같은 이름이 그대로 살아 있고 내부만 React다. 편집 그리드·트리·캘린더·탭·팝업·파일첨부가 포함돼 있으며, 헤더 병합·엑셀 다운로드 같은 미지원 항목은 문서에 명시돼 있다.

서버 API 규약이 프로젝트마다 다른데요?

요청 래핑과 응답 봉투는 프로젝트별 어댑터에 담긴다. 실제로 규약이 전혀 다른 두 시스템을 같은 코어로 처리했고, 두 번째 시스템을 붙일 때 코어 변경은 수십 줄에 그쳤다.

전부 자동인가요?

아니다. 검증을 통과한 화면만 산출물로 남고, 통과하지 못한 화면은 수작업 큐에 기록된다. 64화면 실측에서는 전부 자동 통과했지만, 미지원 컴포넌트가 있는 화면은 사람이 마무리한다.

내 시스템으로 직접 확인할 수 있나요?

로컬 CLI라 소스가 PC를 떠나지 않는다. 라이선스 없이 프로젝트당 화면 2개까지 변환해 볼 수 있다.