networkSetup/docs/code-design/10-installer-wizard-redesign.md

# 설치 마법사와 편집 UI 재설계

2026-10-19 실행 범위 변경: 이 시안은 후속 EXE 출력용 자료로 보존한다. 이번 첫 제품 시안은 MSIX 제작 프로그램 화면이다. [현재 설계](12-msix-first-builder.md) 참조.

아래 EG-BIM 시안은 **범용 제작기의 EXE 출력용 참고 테마**다. 제품명·로고·경로·문구는 프로젝트에서 교체한다. MSIX의 OS 설치 UI를 이 마법사로 대체하지 않으며 MSIX 제작 화면은 별도 manifest/출력 설정을 제공한다. [범용 출력 계약](11-generic-exe-msix-architecture.md) 참조.

변경일: 2026-10-19. InstallShield와 Inno Setup의 마법사 패턴을 참고해 EG-BIM의 설치 과정과 화면을 구체화한다. 패키지 엔진은 기존 WiX MSI/MSP + Burn 설계를 유지한다. 설치기 제품을 바꾸거나 기존 제거 동작을 그대로 복제하는 변경이 아니다.

현재 결과는 상호작용 시안과 구현 설계다. 실제 설치·백업·서명 검사·관리자 승격·재부팅은 실행하지 않으며 표시되는 경로·진행률·검증 결과는 예시다.

## 참고한 패턴

| 출처 | 확인한 특징 | EG-BIM에 적용한 설계 |
| --- | --- | --- |
| [InstallShield: 기본 패키지와 의존 패키지](https://docs.revenera.com/installshield31helplib/helplibrary/StePrimDepend.htm) | 설치된 기본 패키지 상태에 따라 최초 설치와 유지 관리 모드를 구분한다. | 제품 탐지를 먼저 하고 신규 설치·전환·패치·복구·제거를 분리한다. 런타임 존재만으로 제품 설치 여부를 판정하지 않는다. |
| [InstallShield: Wizard Pages 편집](https://www.revenera.com/blog/software-installation/putting-the-wizard-in-wizard-pages/) | 페이지 생성·복제·템플릿으로 화면을 구성하는 편집 패턴을 설명한다. 오래된 버전의 설명이므로 내부 XML 형식은 재사용하지 않는다. | 제작기를 페이지 목록·미리보기·속성 패널로 구성한다. 페이지와 동작 연결은 자체 계약으로 검증한다. |
| [Inno Setup: WizardStyle](https://jrsoftware.org/ishelp/topic_setup_wizardstyle.htm) | classic/modern의 화면 표현과 테마 설정을 제공한다. | 간결한 제목/설명, 본문, 일관된 하단 버튼을 갖는 마법사형을 제공한다. 지원 여부는 선택한 WiX/BA 백엔드에서 별도 판정한다. |
| [Inno Setup: 사용자 정의 페이지](https://jrsoftware.org/ishelp/topic_scriptpages.htm) | 기존 페이지 사이에 사용자 정의 입력 페이지를 삽입하고 입력값을 읽을 수 있다. | 페이지 ID와 조건·입력 바인딩을 가진 페이지 카탈로그를 둔다. 자유 페이지는 사용자 정의 BA에서 처리한다. |
| [Inno Setup: Tasks](https://jrsoftware.org/ishelp/topic_taskssection.htm) | 추가 작업을 체크박스/라디오 버튼으로 표현하고 실제 설치 항목에 연결한다. | 바로가기 같은 사용자 선택 작업을 필수 구성요소와 구분한다. 선택 UI만 있고 실제 작업 연결이 없는 설정을 검증 오류로 처리한다. |
| [Inno Setup: CloseApplications](https://jrsoftware.org/ishelp/topic_setup_closeapplications.htm) | 설치 준비 단계에서 사용 중인 파일과 앱 종료를 다루며 강제 종료 시 작업 손실 위험을 설명한다. | 저장·종료 안내와 재확인 상태를 제공한다. EG-BIM의 미저장 도면을 강제 종료하는 기본 동작은 채택하지 않는다. |

위 자료는 2026-10-19 확인했다. 제품별 외형·동작에서 참고한 패턴이며, 두 도구의 모든 기능이 WiX 기본 테마에 그대로 매핑된다는 의미는 아니다.

## 디자인 방향

두 외형은 동일한 페이지 데이터와 실행 계약을 사용한다. 기본 제안은 **진행 안내형**이다. 기존 설치본 전환의 준비·백업·적용 단계를 쉽게 이해하도록 현재 구간을 왼쪽에 표시한다. **표준 마법사형**은 Inno Setup 계열에서 익숙한 상단 제목/설명·중앙 본문·하단 버튼 구조로 화면을 간결하게 구성한다.

- 제목은 현재 할 일을 설명하고 본문에는 해당 단계에 필요한 입력만 둔다.
- 하단 버튼은 `이전 / 다음 또는 작업 시작 / 취소`, 완료 시 `마침`으로 일관되게 배치한다.
- 단계 목록은 진행 표시이며 클릭으로 필수 단계를 건너뛰는 탐색 메뉴가 아니다.
- 신규 설치의 위치·구성요소·바로가기 선택은 한 화면의 세 구역으로 묶는다. 설정이 많아지면 위치/구성/추가 작업 페이지로 나누되 같은 변수를 사용한다.
- 기존 설치본의 경로와 패치/복구의 Feature 상태는 읽기 전용이다. 제거에서는 제거 대상과 유지할 데이터를 분리해서 표시한다.
- 재부팅 필요, 백업 실패, 설치 실패, 취소는 각각 별도 상태로 표시한다. 실패를 완료 체크 표시로 표현하지 않는다.
- 운영 화면에는 MSI GUID·도구 버전·개발 백엔드 이름을 노출하지 않는다. 진단 정보는 상세 로그에 둔다.

[상호작용 시안 원본](../../output/egbim-installer-wizard.html), [브라우저 미리보기](../../output/egbim-installer-wizard-preview.html). 이전 [초기 시안](../../output/egbim-installer-preview.html)은 비교 자료로 보존한다.

## 상황별 화면 흐름

실제 모드는 탐지 결과와 승인된 적용 경로에서 결정한다. 시안 위의 상황/상태 선택기는 검토용이며 배포되는 설치기의 메뉴가 아니다.

| 모드 | 사용자 화면 | 핵심 제한 |
| --- | --- | --- |
| 신규 설치 | 시작 → 약관 → 위치/구성/바로가기 → 최종 확인 → 준비 → 적용 → 완료/재부팅 | 약관 미동의·경로 오류를 차단. 필수 본체는 해제 불가. |
| 기존 InstallShield 전환 | 기존 제품 탐지 → 최종 확인 → 준비/파일 확보/백업 → 전환/복원 → 완료/재부팅 | 지원 legacy만 허용. 기존 경로 유지. 백업 검증 전에 제거 금지. |
| 후속 MSP | 기준/목표 확인 → 최종 확인 → 준비/백업 → 패치/설정 확인 → 완료/재부팅 | Feature·경로 유지. 기준 상태 불일치 시 검증된 대체 경로 안내 또는 차단. |
| 설치 복구 | 복구 안내 → 최종 확인 → 원본 확보/준비 → 복구 → 완료/재부팅 | 새 WiX 설치 체계의 지원 상태만 대상. 필요한 원본 미확보 시 적용 차단. |
| 제거 | 제거 안내 → 대상/보존 데이터 확인 및 동의 → 준비 → 제거 → 완료/재부팅 | 사용자 도면·설정·백업과 타사 CAD 소유 연결은 유지. 공유 런타임 일괄 제거 금지. |

약관 버전이 달라진 업데이트에는 약관 단계를 추가한다. 시안의 전환·패치 경로는 재동의가 필요 없는 예시이며, 실제 생략 조건은 기존 동의 버전·배포 약관 정책으로 판정한다. 무인 설치는 별도 명시적 동의 입력 계약을 사용한다. 화면을 숨긴 것만으로 동의했다고 간주하지 않는다.

복구·제거 화면의 데이터 보존 정책은 새 설치기에 적용할 설계다. 기존 InstallShield 제거 스크립트에 자동으로 적용된다고 보장하지 않는다. legacy 제거는 전환 핸들러와 검증된 백업 절차를 통해서만 실행한다. 일반적인 구성 변경(Modify)은 Feature 변경 경로가 검증될 때 별도 모드로 확장하고 이번 시안에는 노출하지 않는다.

## 페이지별 계약

| 페이지 ID | 표시/입력 | 다음 단계 조건 | 사용자 버튼 |
| --- | --- | --- | --- |
| welcome | 제품/작업·탐지된 설치 위치·보존 정책 | 지원 가능한 제품/버전/모드, 차단 오류 없음 | 다음, 취소 |
| license | 승인된 약관 전문/버전·동의 | 해당 약관 동의 | 이전, 다음, 취소 |
| options | 설치 위치, 필수/선택 Feature, 바로가기 | 경로/권한/지원 Feature 검증 | 이전, 다음, 취소 |
| review | 실제 실행 계획, 경로, 구성, 백업/보존, 필요한 권한 | 유효한 planId/revision, 제거 시 명시적 확인 | 이전, 설치/업데이트/복구/제거 시작, 취소 |
| prepare | 실행 앱, 패키지 확보·서명·해시·디스크·백업 결과 | 모든 필수 준비 성공, 앱 종료, 적용 직전 허가 유효 | 취소, 차단 원인별 다시 확인 |
| apply | 현재 작업/전체 상태, 엔진이 제공한 진행률, 로그 | 엔진 완료·오류·취소·재부팅 이벤트 | 가능한 지점에서 취소 요청; 이전 없음 |
| finish | 설치 결과, 복원 상태, 백업 위치·실행 선택 | 성공이며 재부팅 불필요 | 마침 |
| rebootRequired | 재부팅 필요 이유, 지금/나중에 선택 | 사용자의 명시적 선택; 기본은 나중에 | 마침 또는 재시작 |
| failure | 실패 단계, 기존 제품 상태, 백업/로그, 다음 조치 | 복구 상태에 따라 다름 | 재검사 또는 진단 안내/닫기 |
| cancelled | 변경 전 취소 여부 또는 적용 후 복구 결과 | 엔진이 확인한 실제 상태 | 닫기 |

`prepare`에는 다운로드·캐시 확보와 로컬 무결성 검사를 포함한다. 온라인 흐름에서는 적용 허가를 재확인하고, 오프라인 흐름은 승인된 배포 정책을 적용한다. `review`의 시작 버튼 이후에는 입력값을 고정하고 작업 ID 하나로 실행한다. 준비 실패 후 입력 수정이 필요하면 계획을 다시 만든다.

## 실패·취소·완료 동작

| 상태 | 표현과 허용 동작 |
| --- | --- |
| 실행 앱 발견 | 저장/종료 안내 → 다시 확인. 자동 강제 종료와 사용자 작업 저장 추정 금지. |
| 다운로드/공간/백업 실패 | 실제 원인을 표시. 제거 전이라면 기존 제품 미변경을 표시하고 안전한 준비 단계만 재시도. |
| 적용 전 취소 | 확인 후 종료. 만들어진 백업/캐시의 보존 정책은 명시하고 기존 제품은 유지. |
| 적용 중 취소 | 취소 요청 접수와 처리 중 상태를 표시. 프로세스를 강제 종료하거나 즉시 성공으로 표시하지 않는다. |
| 적용 실패 또는 취소 후 상태 불명확 | 로그·백업 보존, 복구 진단 안내. 무조건 다시 설치/전체 설치 버튼을 제공하지 않는다. |
| 롤백 완료 확인 | MSI 복구와 외부 런타임/설정 보상 결과를 구분. 각 결과가 확인된 범위만 복구 완료로 표시. |
| 재부팅 필요 | ‘설치 성공·실행 확인 대기’를 구분. 앱 실행 선택 숨김, 지금 재부팅은 기본 미선택. 실제 재부팅은 명시적 동의 후 수행. |
| 정상 완료 | 호환 설정 복원과 실제 확인 항목 표시. 앱 실행은 대화형·원래 사용자 권한. 백업 자동 삭제 금지. |

시안의 ‘작업 진행’ 버튼은 자동 설치 이벤트를 수동으로 넘겨보는 검토용 조작이다. 실제 UI의 prepare/apply에는 이 버튼이 없으며 Burn/작업 서비스 이벤트로 진행한다. ‘다시 확인’과 ‘다시 검사’도 시안에서는 정상 상태로 바꾸는 모의 동작이며 실제 파일/프로세스를 검사하지 않는다.

## 제작기의 설치 과정·UI 편집 화면

화면 편집은 **왼쪽 페이지 목록 / 중앙 미리보기 / 오른쪽 속성**의 세 영역으로 구성한다. 설치 과정 탭에서는 같은 공간을 **작업 목록 / 모드별 실행 순서 / 조건·입력·복구 정책**으로 바꾼다. 최종 사용자 마법사의 단계 이동과 제작자의 페이지 편집은 구분한다.

| 영역 | 편집 동작 | 제약과 피드백 |
| --- | --- | --- |
| 상단 설정 | install/upgrade/patch/repair/uninstall 미리보기, 기본 테마/사용자 정의 BA 선택 | 선택 백엔드가 지원하지 않는 기능 표시. 모드 변경은 화면 미리보기이며 시스템 실행 아님. |
| 페이지 목록 | 템플릿에서 추가, 선택, 복제, 허용 순서 변경, 표시 조건 | review/prepare/apply/결과의 실행 계약은 잠금. 페이지 숨김으로 필수 작업을 삭제하지 않음. |
| 중앙 미리보기 | 선택 페이지와 이전/다음 연결, 정상/차단/실패/재부팅 상태 | 실제 설치 미수행. native 출력 시험 필요 표시. |
| 속성 패널 | 제목/설명/번역 키, 로고/이미지, 지원 색상/글꼴, 레이아웃 슬롯, 입력 변수와 검증 | 읽기 전용 설치 경로/필수 Feature 등 모드 제약을 즉시 표시. 임의 JS/셸 바인딩 불가. |
| 설치 과정 | 카탈로그 추가, 선택 단계 활성화, 의존성 범위 내 순서, 실패 정책 확인 | 필수 백업/무결성/설치 작업 제거 차단. trusted catalog의 권한/복구 정책은 임의 약화 불가. |
| 검증 결과 | 페이지·단계·변수 경로와 오류 원인/수정 위치 | 미지원 기능·순환·필수 입력 누락이면 배포 빌드 불가. |

설치 과정 편집기 자체의 세 영역 UI는 이 문서에서 구체화했으며 이번 상호작용 파일은 **배포되는 설치 마법사**의 화면을 구현한 시안이다. 제작기 편집 화면의 구현 완료를 의미하지 않는다.

## 커스터마이징 데이터와 백엔드 지원

기존 `InstallerUi`의 templateId/version·assets·strings/locales·pages·bindings를 유지한다. 레이아웃·색상 등 지원 속성은 버전이 지정된 템플릿 스키마에서 정의한다. `InstallationFlow`는 별도로 유지하며 각 화면이 직접 관리자 작업을 실행하지 않는다.

| 변경 | 기본 테마 | 사용자 정의 BA |
| --- | --- | --- |
| 로고·문구·약관·지원 스타일 | 고정 WiX 테마가 지원하는 속성으로 매핑 | 구현한 토큰/리소스 스키마로 지원 |
| 시안의 두 외형 전체 재현 | 페이지/컨트롤 계약에 대한 실험 필요, 동일 재현 보장 안 함 | 선택한 컴포넌트/레이아웃 구현 후 지원 |
| 임의 페이지·입력·분기 | 미지원이면 빌드 차단 | 페이지 그래프·입력 검증·무인 기본값 계약 필요 |
| 필수 백업/무결성 약화 | 불가 | 불가 |
| UAC 화면 변경 | 불가 | 불가 |

UI 수정은 새 스냅샷·빌드·서명·시험으로 배포한다. 목표 페이지 목록, 약관 버전, 입력 검증, 모드 분기, 선택 Feature가 달라지면 설치/패치 호환성도 다시 검사한다.

## 인수 기준과 작업 연결

- BL-15/30: 페이지와 실행 단계의 구분, 필수 단계 보호, 모드별 과정 검증.
- BL-24/27: 준비/적용/취소/실패/재부팅 상태와 승인된 설치·패치·복구 경로 연결.
- BL-31: 두 외형의 템플릿·문구·리소스 편집과 백엔드 지원 여부 표시.
- BL-32: 약관 조건·입력·페이지 분기·선택값 유지·설치 시작 후 계획 고정.
- BL-33: 5개 모드, 약관/경로/제거 확인, 이전 이동 시 선택값 보존, 준비 실패, 실행 앱, 적용 중 취소, 상태 불명확, 재부팅을 시험. DPI·키보드·스크린 리더·다국어 및 native 결과를 검증.

시안 작성은 위 구현 항목을 완료 처리하지 않는다. 신규 기능 ID를 늘리지 않고 미착수 BL-15/24/30~33의 완료 기준을 구체화한다. 일정은 단독 개발·AI 지원 없음 가정을 유지하며 M0/BL-08 실험과 M4 착수 시 기본 테마로 가능한 화면 범위와 사용자 정의 BA 공수를 다시 산정한다.