networkSetup/docs/code-design/09-install-flow-and-ui.md

설치 과정 편집과 설치 UI 커스터마이징

2026-10-19 실행 범위 변경: 이 문서의 EXE 설치 과정·BA·HTML 페이지 편집은 후속 범위다. 첫 제품의 Tauri UI는 MSIX 제작 설정을 편집하며 설치 마법사를 생성하지 않는다. 현재 설계 참조.

이 문서의 최종 사용자 설치 과정·마법사·Burn BA 커스터마이징은 EXE 출력 전용이다. MSIX는 Windows/Store가 설치 UI와 경로를 관리하며 제작기는 manifest의 이름·아이콘·지원 선언을 편집한다. 두 형식의 설정을 혼합하거나 미지원 단계를 조용히 생략하지 않는다. 범용 출력 계약 참조.

목표

2026-10-19에 InstallShield와 Inno Setup의 마법사 패턴을 참고해 설치 과정·UI를 재설계했다. 아래 실행/데이터 계약을 유지하면서 페이지 흐름, 편집 화면과 실패·취소·재부팅 상태를 구체화한다.

패키지 제작자가 설치 단계를 추가·삭제·비활성화·재배치하고, 최종 사용자가 보는 설치 화면도 변경할 수 있게 한다. 제작자가 정하는 실행 정책과 설치 사용자가 선택하는 옵션은 구분한다.

• 설치 과정 편집기: 환경 검사, 런타임, 제품 설치, 설정 이전, 바로가기, 완료 후 실행 등 작업을 설정한다.
• 설치 UI 편집기: 로고·색상·문구·약관·입력 항목·화면 순서를 설정하고 모드별 미리보기를 제공한다.

화면을 숨기는 것과 설치 작업을 제거하는 것은 별개다. 설치 폴더 화면을 숨겨도 경로 탐지·검증은 수행한다. 무인 설치에도 같은 설치 규칙을 적용한다.

실행 구조

flowchart TD
    A[Tauri 제작 프로그램] --> F[설치 과정 정의]
    A --> U[UI 정의와 리소스]
    F --> C[Rust 검증 및 변환]
    U --> C
    C --> M[MSI 컴포넌트 · Feature · Action]
    C --> B[Burn Chain · 조건 · BA 리소스]
    B --> S[최종 Setup.exe]
    M --> S
    S --> E[설치 PC의 Burn / Windows Installer]

제작 프로그램의 Tauri 화면과 배포되는 Setup.exe의 화면은 별개다. 설정을 WiX/Burn 정의와 UI 리소스로 변환하여 서명된 산출물에 포함한다. 이미 서명한 EXE의 테마나 작업을 외부 JSON으로 바꾸지 않고 새 빌드·서명·검증을 거친다.

단계 카탈로그

작업	구현 위치	편집 규칙
OS·공간·기존 제품 검사	Burn 탐지/조건; 필요한 항목은 MSI에도 검사	제품 필수 조건은 잠금
런타임 설치	Burn Chain 패키지	앱 의존성이 없어졌을 때 제거 가능
파일·레지스트리 설치	MSI Component/Feature와 표준 Action	리소스 그룹 편집; MSI 표준 실행 순서는 임의 이동하지 않음
바로가기·파일 연결	MSI 표준 정의/검증된 확장	선택 기능으로 추가/제거, 기존 설치 영향 검사
기존 설정 백업·이전	검증된 마이그레이션 핸들러	해당 전환의 필수 단계이면 삭제 차단
앱/서비스 종료·시작	MSI 표준 기능/검증된 확장 우선	데이터 저장, 종료 실패, 재시작 정책 필요
완료 후 앱 실행	BA의 설치 성공 후 작업	대화형 설치에서 선택, 원래 사용자 권한으로 실행
추가 업무 작업	버전이 고정된 사용자 정의 핸들러	권한·입력·설치 모드·실패 복구 계약 필요

카드 목록에서 추가/삭제/활성화, 조건 설정, 가능한 범위의 순서 이동을 제공한다. 내부 모델은 의존 관계를 가진 그래프다. 카드의 파일·레지스트리 설정은 실제 리소스 정의를 참조하고, MSI 밖 스크립트로 중복 실행하지 않는다.

StepDefinition은 id, kind, enabled, appliesTo, phase, dependsOn, condition, configRef, handlerRef를 가진다. 필수 여부·권한·지원 phase·실패 정책은 신뢰된 핸들러 카탈로그에서 정한다. 제작자가 필수 여부를 바꿔 보호 동작을 우회하지 못하게 한다.

appliesTo는 install, upgrade, patch, repair, uninstall을 구분한다. phase는 detect, beforeApply, managedInstall, afterSuccess로 제한한다. 이것이 MSI Sequence 번호를 직접 의미하지는 않는다. MSI 내부 작업이 필요한 핸들러는 별도의 스케줄 계약을 가진다.

조건은 all/any/not/equals/isInstalled/featureSelected 같은 타입이 지정된 표현식으로 저장한다. 임의 JavaScript/PowerShell을 평가하지 않으며 변수 타입·평가 시점을 검사한다.

편집 검증

1. 삭제 단계의 의존 작업, 그래프 순환, phase 역전, 지원하지 않는 모드를 빌드 전에 검출한다.
2. 필수 런타임·무결성 검증·제품 설치·필수 백업은 임의로 삭제할 수 없다.
3. 재실행 가능한 작업에는 멱등성 또는 완료 마커가 필요하다. 마커는 제품·버전·설치 시도에 연결한다.
4. 단계 삭제가 기존 PC의 자원 삭제를 뜻하지는 않는다. 유지/제거/이전 정책을 명시하고 Component/Feature/CustomAction 변경을 패치 호환성 검사에 전달한다.
5. 모드별 실행 계획을 각각 보여 준다. 완료 후 앱 실행은 uninstall·무인 패치에서 제외한다.

설치에 필수인 변경을 afterSuccess에 놓아 실패 시 복구할 수 없는 구성을 허용하지 않는다. 완료 후 선택 작업 실패는 이미 성공한 설치 트랜잭션 실패와 구분해 보고한다.

사용자 정의 작업

표준 MSI 기능과 검증된 WiX 확장을 우선한다. 추가 업무 작업은 개발자가 작성한 Rust 실행 파일/DLL 등의 핸들러를 등록하는 인터페이스로 지원한다. MSI ABI 또는 외부 프로세스 프로토콜과 수명 관리 어댑터가 필요하며, 임의 EXE를 곧바로 MSI CustomAction으로 넣는 기능은 아니다.

핸들러에는 버전·해시·서명자·입력 스키마·실행 계정·시간 제한·종료 코드·재부팅 동작·rollback/복구 방법을 등록한다. 제작자는 등록된 핸들러를 추가/삭제하고 매개변수를 편집한다. 셸 명령 문자열을 입력해 관리자 작업으로 실행하는 기능은 초기 범위에서 제외한다.

시스템을 변경하는 MSI CustomAction은 적합한 deferred 실행과 rollback 작업을 설계하고 필요한 데이터를 제한된 CustomActionData로 전달한다. 즉시 실행 Action에서 시스템을 변경하거나 변경이 자동 복구된다고 가정하지 않는다. Microsoft Custom Actions, Rollback Custom Actions

Burn 체인 전체를 무조건 하나의 원자적 트랜잭션으로 표시하지 않는다. 런타임 EXE·외부 설정 이전은 별도의 복구 한계가 있다. MSI rollback, 보상 작업, 수동 복구 필요 상태를 구분한다. 기존 InstallShield 제거 스크립트에 의한 데이터 삭제도 별도 백업·복원 범위다.

UI 출력 방식

백엔드	지원 목적	제약
wixstdba-theme	로고, 이미지, 문구, 약관, 글꼴/배치 등 외형 수정	WixStdBA의 페이지·컨트롤·동작 계약 안에서 변경
custom-burn-ba	추가 입력 화면, 기능 선택 마법사, 조건별 분기, 자유로운 배치	별도 BA 프로그램과 Burn 연결 구현·검증 필요
MSI 자체 UI	MSI 직접 실행 시 기본 화면	Burn UI와 별도이며 중복 입력/표시 방지 필요

WixStdBA는 테마 XML과 리소스로 화면을 교체할 수 있지만 동작까지 제한 없이 바꾸는 UI 프레임워크는 아니다. 공식 페이지 계약을 지키는 테마를 생성한다. WixStdBA 테마

첫 구현은 기본 테마 편집으로 브랜드·문구·배치를 제공한다. 임의의 페이지 추가/삭제·분기까지 필요한 프로젝트는 사용자 정의 BA로 처리한다. 미지원 기능은 생략하지 않고 UnsupportedInstallerUiCapability로 표시한다. 자유로운 화면 요구를 기본 테마만으로 완료했다고 표시하지 않는다.

UI 편집기는 템플릿 선택, 리소스 등록, 문구/다국어, 허용 컨트롤 배치, 모드별 미리보기로 구성한다. 자유 배치 캔버스에 앞서 템플릿+속성 패널을 구현한다. 색상 등의 토큰은 백엔드에서 실제 지원하는 속성에만 매핑한다. 웹 CSS를 native 테마에 그대로 적용한다고 가정하지 않는다.

Rust/Tauri 사용자 정의 설치 UI

제작 프로그램과 별도로 installer-ui 실행 프로그램과 burn-bridge 계층을 설계한다. 설치 화면에는 제작기의 파일 편집·도구 실행 API를 포함하지 않는다. UI는 입력·탐지·진행률을 표시하고 Rust 어댑터가 Burn의 Detect → Plan → Apply 및 취소/오류/재부팅 이벤트를 연결한다. UI가 별도로 msiexec를 실행하여 Burn과 경쟁하게 만들지 않는다.

WiX는 out-of-process BA와 native API를 제공하지만 Rust/Tauri용 완성 SDK를 제공한다는 뜻은 아니다. 고정한 WiX 버전의 native ABI/콜백에 대한 Rust FFI 연결을 작은 실험으로 먼저 검증한다. 필요한 native 어댑터의 범위·유지보수 비용도 이때 확정한다. WiX out-of-process BA

Tauri 설치 UI는 WebView2 없는 PC에서도 시작할 수 있어야 한다. 지원되는 native 선행 BA/오프라인 UI 런타임 등 부트스트랩 경로를 검증한다. UI가 뜬 다음에야 UI 런타임을 설치하는 순환 구조를 피한다. 오프라인/Store 출력은 UI 런타임도 다운로드 없이 준비하고 전체 용량에 포함한다.

UI는 일반 권한을 유지하고 시스템 변경은 Burn/MSI의 적합한 권한 경로로 수행한다. 입력·경로·Feature 선택을 Rust에서 재검증한다. 원격 페이지나 임의 JS에 관리자 실행 기능을 연결하지 않는다. Windows UAC 보안 화면은 커스터마이징 대상이 아니다.

데이터 계약과 무인 설치

v2 PackageProject.formats.exe에 installationFlow와 installerUi를 둔다. 기존 초안 예제에서 생략한 경우 버전이 고정된 기본 과정/테마를 적용하고 빌드 스냅샷에는 전체 정의와 리소스 해시를 저장한다.

정의	필드
InstallationFlow	schemaVersion, templateId/version, steps, variables, features
InstallerUi	backend, templateId/version, assets, strings/locales, pages, bindings
UiPage	id, kind, appliesTo, visibleWhen, controls, transitions
UiBinding	controlId, variableRef, type, validator, silentDefault 또는 requiredInput
HandlerDescriptor	id/version, capability set, inputSchema, execution/rollback contract
CompiledInstallPlan	모드별 단계, MSI/Burn 매핑, UI 지원 검사, 정의/리소스 해시

페이지 전환과 작업 의존성은 다른 그래프다. 다음 버튼을 여러 번 눌러도 설치는 중복 실행되지 않는다. 적용 시작 후 선택값과 계획을 고정한다. MSI 속성 입력은 허용 목록·타입·권한을 검사하며 비밀번호/토큰을 일반 속성·명령줄·로그에 넣지 않는다.

Feature 선택은 MSI 모델에 연결하고 repair/patch에서 설치된 선택 상태를 유지한다. 패치가 미설치 선택 기능을 임의 추가하지 않게 한다. 무인 설치는 같은 검증을 사용하며 필수 입력이 기본값이나 명령줄로 제공되지 않으면 명확히 실패한다. 약관 화면 숨김을 동의로 처리하지 않고 무인 배포의 동의 전달 규칙을 정의한다. 작업을 특정 화면 버튼에서만 실행하지 않는다.

검증과 구현 순서

최소 Rust/Burn 연결·부트스트랩 실험 → 단계 카탈로그·검증 → 과정 편집기 → 기본 테마 편집 → 사용자 정의 BA·페이지 편집 순서로 진행한다. 모두 기존 전체 릴리스·MSP와 같은 스냅샷·서명·검증 절차를 적용한다.

2026-10-19의 통합 일정에 따라 위험 실험(BL-08)은 기준 확정 단계에 수행한다. 본 편집기와 사용자 정의 BA 구현은 공통 엔진 및 적용 계약 검증 이후 진행한다.

• 의존 단계 삭제, 순환, 모드/조건 오류의 사전 검출.
• 대화형·숨김·무인 모드에서 관리 파일/레지스트리 결과의 동등성.
• optional Feature, patch/repair 선택 상태 유지, 제거와 rollback.
• DPI·키보드·스크린 리더·다국어·취소·실패·재부팅 화면.
• 핸들러 실패/시간 초과/재부팅 재개, WebView2 없는 PC와 오프라인 실행.
• 테마/핸들러 변경 후 새 빌드 해시·서명·증빙 연결.

편집기 미리보기는 시스템 변경 없이 동작한다. 미리보기와 최종 native UI는 다를 수 있어 실제 번들의 VM 화면 시험을 완료 기준으로 둔다. 현재는 설계만 작성했으며 BA/FFI 구현·설치 시험은 수행하지 않았다.