networkSetup/docs/code-design/06-patch-pipeline.md

# 기준 버전별 패치 생성

2026-10-19 실행 범위 변경: 아래 MSP 파이프라인은 후속 EXE 범위로 이월한다. 1차 MSIX는 전체 상위 버전 패키지와 App Installer 업데이트를 제공한다. [현재 설계](12-msix-first-builder.md) 참조.

이 문서는 EXE/MSI 백엔드의 MSP 생성 계약이다. MSIX 업데이트는 버전 증가 패키지와 Windows 배포 기능을 사용하며 MSP·Burn 기준 상태를 적용하지 않는다. [범용 출력 계약](11-generic-exe-msix-architecture.md) 참조.

## 입력 계약

패치는 이전 릴리스의 폴더와 새 폴더만 비교해 만드는 ZIP이 아니다. 보존한 기준 MSI/빌드 정보와 목표 전체 릴리스를 사용해 WiX MSP를 생성한다. WiX는 기준·업데이트 입력으로 MSI 또는 wixpdb와 관련 payload를 사용한다. 정확한 도구 호출은 버전별 백엔드가 담당한다. [WiX Windows Installer patches](https://docs.firegiant.com/wix/tools/patches/)

필수 입력은 `baseStateId`, `targetReleaseId`, 패치 정책, 고정 도구 프로필이다. baseState에는 기준 releaseId, 실제 ProductCode/PackageCode, ProductVersion, 언어, 아키텍처, 설치 범위, 기존 적용 PatchCode 집합, 관리 파일 상태를 포함한다. 목표는 이미 확정한 전체 릴리스의 동일한 서명 완료 파일을 사용한다. 패치 생성 중 목표 PE를 다시 서명하거나 재빌드하지 않는다.

기준 ProductVersion 문자열만 같은 임의 MSI는 허용하지 않는다. 등록된 기준 아티팩트 해시와 도구/설치 정의를 검증한다. 사용자 변경 데이터는 관리 파일 해시 비교에서 제외한다.

## 호환성 판정

| 검사 | 패치 생성 정책 |
| --- | --- |
| 제품 계열·ProductCode·언어·아키텍처·설치 범위 | 같은 패치 계열인지 확인; 불일치 시 전체 업그레이드 필요 |
| 목표 버전 | 기준보다 높은 MSI 버전; 네 번째 필드 변경만으로는 허용하지 않음 |
| GUID/key path/대상 경로 | MSI 컴포넌트 규칙 위반 시 차단 |
| 파일 추가 | 허용되는 새 컴포넌트/feature 구조인지 검사 후 지원 |
| 파일 삭제·이동·컴포넌트 제거 | 최초 버전은 전체 업그레이드 대상으로 분류; 자동 MSP 생성 금지 |
| 파일 버전 | PE 버전 역행, 내용 변경 없이 버전만 조작, 내용 변경인데 파일 버전 동일 등의 교체 규칙 검사 |
| 레지스트리 변경 | 지원 템플릿 내 변경과 제거/복구 동작 검증 |
| 설치 과정·UI 변경 | Component/Feature/CustomAction/조건 변경을 호환성 검사에 포함. 번들 UI 변경은 MSP만으로 배포되지 않으므로 새 번들 경로도 검증 |
| 필수 런타임·드라이버·서비스 구조 변경 | 최초 버전은 전체 업그레이드 대상으로 분류 |
| 기준 파일·wixpdb 등 누락 | 생성 중단; 현재 폴더로 기준을 임의 복원하지 않음 |

판정 결과는 `PatchEligible`, `FullUpgradeRequired`, `InvalidInput`로 구분한다. `FullUpgradeRequired`가 나오면 위반 항목과 새 제품 계열/ProductCode 검토 필요성을 표시한다. 사용자가 패치 생성을 요청했다고 자동으로 GUID를 바꾸거나 다른 형태의 패키지를 성공 결과로 내놓지 않는다.

이 기준은 초기 지원 범위를 보수적으로 정의한 것이다. 모든 파일 삭제·런타임 변경이 Windows Installer에서 원천적으로 불가능하다는 뜻은 아니다. 지원 범위를 넓히려면 템플릿과 시험 매트릭스를 함께 확장한다.

## 생성 흐름

1. 기준과 목표의 서명·해시·식별자 및 잠금 스냅샷을 읽는다.
2. 파일/레지스트리/컴포넌트 차이와 호환성 보고서를 생성한다.
3. PatchCode와 patch family/sequence, 대체 관계를 예약한다.
4. 기준→목표 패치 정의를 생성하고 WiX로 MSP를 만든다.
5. MSP를 서명하고 실제 적용 대상·순서·식별자를 기대값과 비교한다.
6. 크기·SHA-256·서명·기준 상태·목표·전체 대체 경로를 기록하고 불변 패치로 보관한다.
7. 각 선언된 기준 상태의 VM 시험 결과를 연결하여 배포 가능 여부를 판정한다.

초기에는 **기준 상태 하나에서 목표 하나로 가는 MSP 하나**를 기본으로 한다. 여러 기준을 선택하면 작업을 여러 개 만든다. 실제로 여러 기준을 지원하는 단일 MSP와 무제한 패치 체인은 후속 범위다. 패치가 전체 설치보다 커지거나 이점이 작으면 결과에 표시하고 배포 정책에서 전체 경로를 선택할 수 있게 한다.

새로 설치한 1.14.1과 1.14.0에 패치를 적용해 도달한 1.14.1은 표시 버전이 같아도 기준 MSI/패치 이력이 다를 수 있다. 별도 baseState로 기록하여 다음 패치를 각각 시험한다. 불필요한 모든 조합을 지원하지 않고 지원 상태 목록을 명시한다.

## 실행기와 Burn의 계약

패키지 생성기는 `applyRoute`를 출력하고 실제 적용은 기존 업데이터의 연계 작업이다. MSI가 관리하는 파일을 Rust 업데이터가 직접 덮어쓰지 않는다. 실행기는 설치 식별자와 패치 상태를 조회하고 승인된 MSP 적용 명령을 사용한다.

최초 구현의 시험용 경로는 Windows Installer를 통한 직접 MSP 적용으로 둘 수 있다. 정식 배포 전에는 Burn으로 설치한 제품에서 패치 후 번들 표시 버전, ARP, repair, uninstall, 다음 전체 업데이트가 일관적인지 확인해야 한다. 필요 시 패치용 Burn 번들을 추가한다. 이 검증이 끝나기 전에는 패치 파일 생성 성공만으로 운영 배포를 허용하지 않는다.

패치 실패 뒤에는 rollback 완료·재부팅 필요·현재 설치 상태를 확인한다. 상태가 불명확하면 전체 설치를 즉시 덮어 실행하지 않는다. 전체 대체 경로는 동일 목표 릴리스이며 해당 source state에서 검증된 업그레이드 동작을 가져야 한다. [전체 릴리스의 업그레이드 경로](05-release-pipeline.md)

## 검증·보존 기준

기준 설치 → 패치 적용 → 목표 신규 설치와 공급자 관리 파일/레지스트리/제품 등록 비교 → 실행 → repair → 제거 → 다음 패치 순서를 검증한다. MSI 파일 버전 규칙과 수정된 비버전 파일 때문에 파일이 실제로 교체되지 않는 경우까지 검사한다. 재부팅 코드와 MSI source cache 누락도 시험한다.

패치 제거 지원은 기본 꺼짐이며, 가능하게 작성하고 데이터/다음 업데이트까지 검증한 패치만 활성화한다. 일반 장애 대응은 더 높은 버전의 수정 릴리스를 우선한다. 기준과 목표의 전체 패키지, 원본 서명 payload, 패치 순서 정보와 검증 증빙은 지원 기간 동안 함께 보존한다. [운영 패치 정책](../plan/08-version-patching.md)