생성된 UI에서 맞춤 Vue 컴포넌트를 안전하게 추가하고 재생성 유지

생성된 UI를 편집하면 무엇이 깨지나

생성된 UI는 재생성하도록 설계되어 있습니다. AppMaster 같은 플랫폼에서는 Vue3 웹 앱 코드가 시각적 빌더에서 생성됩니다. 재생성은 화면, 로직, 데이터 모델 전체에서 변경 사항을 일관되게 유지하는 방식입니다.

문제는 단순합니다: 생성된 파일을 직접 편집하면 다음 재생성 때 당신의 수정이 덮어써질 수 있습니다.

그래서 팀은 커스텀 코드를 추가하려 합니다. 내장 UI 블록은 보통 표준 폼과 테이블을 처리하지만, 실제 앱은 복잡한 차트, 지도 선택기, 리치 텍스트 에디터, 서명 패드, 드래그 앤 드롭 플래너 같은 특수 요소가 필요합니다. 이런 이유로 맞춤 Vue 컴포넌트를 추가하는 것은 타당하지만, 그것들을 수정으로 다루지 말고 애드온으로 취급해야 합니다.

커스텀 코드가 생성된 코드와 뒤섞이면 실패는 지연되고 혼란스러워질 수 있습니다. 다음 UI 변경이 재생성을 트리거나 팀원이 시각적 편집기에서 화면을 조정할 때까지 문제를 모를 수도 있습니다. 흔한 문제는 다음과 같습니다:

• 템플릿이 재생성되어 당신의 커스텀 마크업이 사라짐.
• 파일명이나 구조가 바뀌어 import나 등록이 깨짐.
• "작은 수정"이 매 배포마다 병합 충돌로 변함.
• 생성된 로직과 커스텀 로직이 어긋나 엣지 케이스가 실패함.
• 어떤 것이 교체될지 몰라 업그레이드가 위험하게 느껴짐.

목표는 커스터마이제이션을 피하는 것이 아니라 재빌드를 예측 가능하게 만드는 것입니다. 생성된 화면과 커스텀 위젯 사이에 깔끔한 경계를 유지하면 재생성은 스트레스가 아닌 일상 작업으로 남습니다.

재생성을 안전하게 하는 경계 규칙

작업을 잃지 않고 커스터마이즈하려면 한 가지 규칙을 따르세요: 생성된 파일을 절대 편집하지 마세요. 그것들을 읽기 전용 출력물(예: 컴파일된 아티팩트)로 취급하세요.

UI를 두 개의 영역으로 생각하세요:

• 생성된 영역: 생성기가 만든 페이지, 레이아웃, 화면.
• 커스텀 영역: 별도의 폴더에 있는 손으로 쓴 Vue 컴포넌트.

생성된 UI가 당신의 커스텀 컴포넌트를 소비해야지, 생성된 곳에서 그 컴포넌트를 직접 만드는 장소가 되어서는 안 됩니다.

장기적으로 작동시키려면 “경계”를 작고 명확하게 유지하세요. 커스텀 위젯은 계약을 가진 작은 제품처럼 동작해야 합니다:

• Props 입력: 렌더링에 필요한 것만.
• 이벤트 출력: 페이지가 반응해야 할 것만.

위젯 내부에서 글로벌 상태에 접근하거나 관련 없는 API를 호출하는 것을 피하세요(그것이 명시적인 계약의 일부가 아닌 한).

AppMaster 스타일의 생성된 Vue3 화면에서는 보통 생성된 화면에서 props를 전달하고 이벤트를 처리하는 최소한의 연결만 하게 됩니다. 그 연결은 재생성 동안 변경될 수 있지만 작고 다시 하기 쉽습니다. 실제 작업은 커스텀 영역에 안전하게 남아 있습니다.

Vue3에 잘 맞는 격리 패턴

목표는 명확합니다: 생성된 파일은 자유롭게 교체될 수 있어야 하고, 당신의 위젯 코드는 건드리지 않아야 합니다.

실용적인 접근은 맞춤 위젯을 작은 내부 모듈로 유지하는 것입니다: 컴포넌트, 스타일, 도우미 유틸리티를 한 곳에 모으세요. 생성된 Vue3 앱에서는 보통 커스텀 코드는 생성된 페이지 밖에 두고 의존성으로 import합니다.

래퍼 컴포넌트가 큰 도움이 됩니다. 래퍼가 생성된 앱과 대화하여 페이지의 기존 데이터 모양을 읽고 정규화하여 위젯에 깔끔한 props를 전달하게 하세요. 생성된 데이터 모양이 나중에 바뀌면 보통 위젯을 다시 쓰지 않고 래퍼를 업데이트합니다.

잘 견디는 몇 가지 패턴:

• 위젯을 블랙박스로 취급: props 입력, events 출력.
• API 응답, 날짜, ID를 위젯 친화적 형식으로 매핑하려면 래퍼 사용.
• 스타일을 스코프하여 생성된 페이지가 우연히 위젯을 덮어쓰지 않게 함.
• 부모 DOM 구조나 페이지 전용 클래스 이름에 의존하지 않음.

스타일링에서는 scoped CSS(또는 CSS Modules)를 선호하고 공유 클래스에는 네임스페이스를 사용하세요. 위젯이 앱 테마와 맞춰야 한다면 페이지 스타일을 import하지 말고 테마 토큰(색상, 간격, 글꼴 크기)을 props로 전달하세요.

슬롯은 작고 선택적으로 유지될 때 안전합니다(예: 빈 상태 메시지). 슬롯이 핵심 레이아웃이나 동작을 제어하기 시작하면 위젯을 생성된 레이어 안으로 다시 집어넣는 것이며, 그때부터 재생성 관련 문제가 시작됩니다.

안정적인 컴포넌트 계약 설계(Props와 Events)

재생성을 문제없이 유지하는 가장 안전한 방법은 각 위젯을 안정적인 인터페이스로 다루는 것입니다. 생성된 화면은 바뀔 수 있습니다. 당신의 컴포넌트는 변하지 않아야 합니다.

입력(props)부터 시작하세요. 적고 예측 가능하며 검증하기 쉬운 값으로 유지하세요. 단순한 원시값과 당신이 제어하는 평범한 객체를 선호합니다. 스크린이 아직 아무 것도 전달하지 않아도 위젯이 잘 동작하도록 기본값을 추가하세요. ID, 날짜 문자열, 열거형 같은 값이 잘못될 수 있다면 검증하고 부드럽게 실패하세요: 크래시 대신 빈 상태를 보여주기.

출력에서는 위젯이 앱의 다른 부분과 일관되게 느껴지도록 이벤트를 표준화하세요. 신뢰할 만한 집합은 다음과 같습니다:

• update:modelValue (v-model 지원)
• change (매 키 입력이 아닌 사용자 확정 변경)
• error (컴포넌트가 작업을 완료할 수 없을 때)
• ready (비동기 작업이 끝나 위젯이 사용 가능해질 때)

비동기 작업이 포함된다면 그것을 계약의 일부로 만드세요. loading과 disabled props를 노출하고 서버 측 실패에 대해 errorMessage를 고려하세요. 컴포넌트가 자체적으로 데이터를 가져온다면 부모가 반응할 수 있도록 error와 ready를 방출하세요(토스트, 로깅, 폴백 UI 등).

접근성 기대치

접근성은 계약에 녹여두세요. label(또는 ariaLabel) prop을 받아들이고 키보드 동작을 문서화하며, 액션 후 포커스를 예측 가능하게 유지하세요.

예를 들어 대시보드의 타임라인 위젯은 항목 간 이동에 화살표 키를 지원하고 세부 정보를 열 때 Enter를 사용하며, 다이얼로그가 닫힐 때 다이얼로그를 연 컨트롤로 포커스를 반환해야 합니다. 이렇게 하면 생성된 화면이 바뀌어도 추가 작업 없이 위젯을 재사용할 수 있습니다.

단계별: 생성된 파일을 건드리지 않고 맞춤 위젯 추가하기

작게 시작하세요: 사용자에게 중요한 한 화면, 그 화면을 돋보이게 하는 한 위젯. 처음 변경을 좁게 유지하면 재생성이 무엇을 건드리고 건드리지 않는지 보기 쉽습니다.

1. 생성된 영역 밖에서 컴포넌트를 만드세요. 당신이 소유하고 소스 컨트롤에 넣는 폴더(보통 custom 또는 extensions)에 위치시키세요.

2. 공개 표면을 작게 유지하세요. 몇 개의 props 입력, 몇 개의 이벤트 출력. 전체 페이지 상태를 전달하지 마세요.

3. 얇은 래퍼를 추가하세요(당신도 소유). 래퍼의 역할은 “생성된 페이지 데이터”를 위젯 계약으로 번역하는 것입니다.

4. 지원되는 확장 지점을 통해 통합하세요. 생성된 파일을 편집하지 않아도 래퍼를 참조할 수 있는 방식을 사용하세요.

5. 재생성하고 검증하세요. 당신의 커스텀 폴더, 래퍼, 컴포넌트는 변경되지 않고 컴파일되어야 합니다.

경계를 선명하게 유지하세요. 위젯은 표시와 상호작용에 집중하고, 래퍼는 데이터를 매핑하고 액션을 전달합니다. 비즈니스 규칙은 앱의 로직 레이어(백엔드나 공유 프로세스)에 남겨두세요, 위젯 안에 숨기지 마세요.

유용한 점검 질문: 지금 재생성이 발생하면 동료가 앱을 다시 빌드해서 수동 수정을 다시 하지 않고 같은 결과를 얻을 수 있는가? 그렇다면 패턴이 잘 잡힌 것입니다.

UI를 유지보수하기 위해 로직을 어디에 둘까

커스텀 위젯은 주로 어떻게 보이고 사용자의 입력에 어떻게 반응할지를 걱정해야 합니다. 위젯에 비즈니스 규칙을 많이 넣을수록 재사용, 테스트, 변경이 어려워집니다.

기본 규칙은: 비즈니스 로직은 페이지나 기능 레이어에 두고 위젯은 "덤(dumb)"으로 만드세요. 페이지가 위젯에 어떤 데이터를 줄지, 위젯이 이벤트를 발생시켰을 때 무슨 일이 벌어질지 결정합니다. 위젯은 렌더링하고 사용자 의도를 보고합니다.

위젯 근처에 로직이 필요할 때(포맷팅, 작은 상태, 클라이언트 검증)에는 작은 서비스 레이어 뒤에 숨기세요. Vue3에서는 모듈, composable, 또는 명확한 API를 가진 스토어가 될 수 있습니다. 위젯은 그 API만 import하고 무작위 앱 내부를 가져오지 마세요.

실용적인 분리 예:

• 위젯(컴포넌트): UI 상태, 입력 처리, 시각 요소, select, change, retry 같은 이벤트를 emit.
• 서비스/Composable: 데이터 형성, 캐싱, API 에러를 사용자 메시지로 매핑.
• 페이지/컨테이너: 비즈니스 규칙, 권한, 언제 데이터를 로드하고 저장할지 결정.
• 생성된 앱 부분: 건드리지 않음; 데이터 전달과 이벤트 수신만.

위젯 내부에서 직접 API를 호출하지 마세요, 그게 위젯 계약의 명확한 일부가 아닌 한. 호출을 소유한다면(예: CustomerSearchWidget) 해당 역할을 분명히 하고 호출 코드를 한 곳에 모으세요. 그렇지 않다면 items, loading, error를 props로 전달하세요.

오류 메시지는 사용자에게 보이는 형태로 일관되게 하세요. 원시 서버 텍스트 대신 "데이터를 불러올 수 없습니다. 다시 시도하세요." 같은 공통 메시지로 매핑하고 가능하면 재시도 액션을 포함하세요. 상세한 오류는 위젯 밖에서 로깅하세요.

예: 맞춤 ApprovalBadge 위젯은 청구서가 승인 가능한지 여부를 스스로 결정하지 말아야 합니다. 페이지가 status와 canApprove를 계산하고, 배지는 approve를 emit하면 페이지가 실제 규칙을 실행하고 백엔드를 호출한 뒤 성공/오류 상태를 UI로 전달합니다.

다음 재생성 이후 고통을 초래하는 흔한 실수들

문제의 대부분은 Vue 자체 때문이 아닙니다. 생성기가 소유한 곳에 커스텀 작업을 섞어 넣거나 변경될 가능성이 큰 세부사항에 의존하기 때문입니다.

자주 발생해 소규모 위젯을 반복적인 수리로 만드는 실수들:

• 생성된 Vue 파일을 직접 편집하고 무엇을 바꿨는지 잊어버림.
• 다른 화면의 마크업이 바뀌면 조용히 영향을 주는 글로벌 CSS나 광범위한 선택자 사용.
• 생성된 상태 구조를 직접 읽거나 변경하여 사소한 이름 변경으로 위젯이 깨짐.
• 한 컴포넌트에 페이지 특정 가정을 너무 많이 넣음.
• props/events API를 마이그레이션 계획 없이 변경.

예시 상황: 커스텀 테이블 위젯을 추가했는데 잘 작동합니다. 한 달 뒤 생성된 레이아웃이 바뀌어 글로벌 .btn 규칙이 로그인 및 관리자 페이지에 영향을 주거나, 데이터 객체가 user.name에서 user.profile.name으로 바뀌어 위젯이 조용히 실패합니다. 문제는 위젯이 아니라 불안정한 세부사항에 대한 의존입니다.

두 가지 습관이 대부분을 예방합니다:

첫째, 생성된 코드를 읽기 전용으로 취급하고 커스텀 파일을 분리된 곳에 두며 명확한 import 경계를 유지하세요.

둘째, 컴포넌트 계약을 작고 명시적으로 유지하세요. 진화가 필요하면 간단한 버전 prop(예: apiVersion)을 추가하거나 한 릴리스 동안 구형/신형 prop 모양을 모두 지원하세요.

커스텀 컴포넌트를 배포하기 전 빠른 체크리스트

맞춤 위젯을 생성된 Vue3 앱에 병합하기 전에 현실 점검을 하세요. 다음 재생성에서 히어로 행동 없이 살아남아야 하고, 다른 사람이 재사용할 수 있어야 합니다.

• 재생성 테스트: 전체 재생성을 실행하고 다시 빌드하세요. 생성된 파일을 다시 편집해야 했다면 경계가 잘못된 것입니다.
• 명확한 입력과 출력: props in, emits out. 외부 DOM을 잡아채거나 특정 페이지 스토어를 가정하지 마세요.
• 스타일 포함: 스타일을 스코프하고 명확한 클래스 접두사(예: timeline-) 사용.
• 모든 상태 확인: 로딩, 오류, 빈 상태가 존재하고 합리적인지 확인.
• 복제 없이 재사용 가능: 다른 페이지에 복사해 붙이는 대신 props와 이벤트 처리만으로 적용 가능한지 확인.

유효성 검사 방법: 위젯을 관리자 화면과 고객 포털 페이지에 넣어보고 props와 이벤트 처리만으로 둘 다 작동하면 안전한 상태입니다.

현실적인 예: 대시보드에 타임라인 위젯 추가하기

지원팀은 종종 티켓의 이야기를 보여주는 한 화면을 원합니다: 상태 변경, 내부 메모, 고객 답글, 결제나 배송 이벤트 등. 타임라인 위젯이 적합하지만 생성된 파일을 편집해 다음 재생성 때 작업을 잃고 싶지는 않습니다.

안전한 접근은 위젯을 생성된 UI 밖에 격리하고 얇은 래퍼를 통해 페이지에 꽂는 것입니다.

위젯 계약

간단하고 예측 가능하게 유지하세요. 예: 래퍼가 전달하는 것:

• ticketId (string)
• range (지난 7일, 지난 30일, 사용자 지정)
• mode (compact vs detailed)

위젯이 emit 하는 것:

• select (사용자가 이벤트를 클릭할 때)
• changeFilters (사용자가 범위나 모드를 조정할 때)

이제 위젯은 대시보드 페이지나 데이터 모델, 요청 방식을 전혀 알 필요가 없습니다. 단지 타임라인을 렌더링하고 사용자 동작을 알립니다.

래퍼가 페이지에 연결하는 방식

래퍼는 대시보드 옆에 위치해 페이지 데이터를 계약으로 번역합니다. 페이지 상태에서 현재 티켓 ID를 읽고 UI 필터를 range로 변환하며 백엔드 레코드를 위젯이 기대하는 이벤트 형식으로 매핑합니다.

위젯이 select를 emit하면 래퍼는 상세 패널을 열거나 페이지 액션을 트리거할 수 있습니다. changeFilters가 발생하면 래퍼가 페이지 필터를 업데이트하고 데이터를 새로고침합니다.

대시보드 UI가 재생성되면 위젯은 생성된 파일 밖에 있으므로 건드리지 않습니다. 보통 페이지 필드 이름이 바뀌거나 필터 저장 방식이 바뀌면 래퍼만 다시 보게 됩니다.

놀라움을 방지하는 테스트 및 배포 습관

커스텀 컴포넌트는 보통 지루한 방식으로 실패합니다: prop 모양이 바뀌거나 이벤트가 더 이상 발생하지 않거나 생성된 페이지가 위젯이 기대하는 것보다 더 자주 리렌더링되는 경우 등. 몇 가지 습관이 이러한 문제를 일찍 잡아냅니다.

로컬 테스트: 경계 파손을 초기에 발견

생성된 UI와 위젯 사이 경계를 API처럼 취급하세요. 전체 앱 없이 위젯을 먼저 하드코딩된 props로 테스트하세요.

"정상 경로" props와 값 누락 상황으로 렌더링하고, 저장/취소/선택 같은 주요 이벤트를 시뮬레이션해 부모가 이를 잘 처리하는지 확인하세요. 느린 데이터와 작은 화면에서도 테스트하세요. 위젯이 계약의 일부가 아닌 한 글로벌 상태를 쓰지 않는지 검증하세요.

AppMaster Vue3 웹 앱에서 작업한다면 재생성하기 전 이 검사를 먼저 수행하세요. 두 가지를 동시에 바꾸지 않으면 경계 문제를 진단하기가 더 쉽습니다.

재생성 후 회귀: 먼저 재확인할 것

각 재생성 후에는 접점부터 다시 확인하세요: 동일한 props가 전달되는가, 동일한 이벤트가 처리되는가? 보통 여기서 문제가 먼저 드러납니다.

포함 방식을 예측 가능하게 유지하세요. 파일 경로가 이동할 수 있는 취약한 import를 피하세요. 커스텀 컴포넌트에 대한 안정적인 진입점을 하나만 사용하세요.

프로덕션에서는 위젯 내부에 가벼운 로깅과 오류 캡처를 추가하세요:

• 마운트 시 핵심 props(정리된 형태)
• 계약 위반(필수 prop 누락, 잘못된 타입)
• 실패한 API 호출의 짧은 오류 코드
• 예상치 못한 빈 상태

문제가 생기면 빠르게 대답할 수 있어야 합니다: 재생성이 입력을 바꿨나, 아니면 위젯이 바뀌었나?

패턴을 앱 전체에 반복 가능하게 만들기 위한 다음 단계

첫 번째 위젯이 작동하면 진짜 이점은 같은 방식을 반복할 수 있게 만드는 것입니다. 다음 번은 일회성 요령이 아니어야 합니다.

작은 내부 표준을 만드세요(위젯 계약을 위한 문서). 팀 노트에 이름 규칙, 필수 vs 선택 props, 이벤트 집합, 오류 동작, 소유권(생성된 UI vs 커스텀 폴더)을 간단히 적어 두세요.

경계 규칙도 평이한 언어로 적어 두세요: 생성된 파일을 수정하지 말 것, 커스텀 코드는 격리할 것, 데이터는 props와 이벤트로만 전달할 것. 이것이 영구적인 유지보수 비용으로 변하는 "임시 수정"을 예방합니다.

두 번째 위젯을 만들기 전에 작은 재생성 실험을 실행하세요. 첫 위젯을 배포한 뒤 레이블 변경, 레이아웃 변경, 새 필드 추가 같은 정상적 변화 동안 최소 두 번 재생성하고 아무 문제가 없는지 확인하세요.

AppMaster를 사용한다면 UI 및 로직의 대부분을 시각적 편집기(UI 빌더, Business Process Editor, Data Designer) 안에 두는 것이 보통 잘 작동합니다. 에디터가 표현하지 못하는 진정한 맞춤 위젯(특수 타임라인, 차트 상호작용, 특이한 입력 컨트롤 등)에 대해서만 커스텀 Vue 컴포넌트를 사용하세요. 이 접근의 깔끔한 출발점이 필요하면 AppMaster on appmaster.io는 재생성을 중심으로 설계되어 있어 커스텀 위젯을 격리해 두는 것이 워크플로의 자연스러운 일부가 됩니다.