Initial commit: EG-BIM installer plans and design concepts

docs/plan/08-version-patching.md

@@ -0,0 +1,79 @@
+# 버전별 패치와 복구
+
+버전별 패치는 필수 요구사항이다. 현재 설치된 버전과 상태를 확인해 변경분만 적용할 수 있어야 하며, 신규 설치·최초 설치기 전환·패치 비호환 상태를 위한 전체 설치 패키지도 함께 제공한다.
+
+## 권장 구현 방식
+
+WiX가 생성하는 Windows Installer 패치인 MSP를 우선 검토한다. MSP는 기준 패키지와 업데이트 패키지의 차이를 담으며, 변경 내용에 따라 전체 설치보다 다운로드와 설치 부담을 줄일 수 있다. 모든 릴리스의 패치가 반드시 작아지는 것은 아니므로 생성 후 크기를 비교한다. [WiX 패치 지원](https://docs.firegiant.com/wix/tools/patches/)
+
+MSI가 관리하는 파일을 별도 ZIP 업데이터로 덮어쓰는 방식은 우선 채택하지 않는다. 파일만 바꾸면 설치 복구·제거·버전 등록과 실제 파일이 어긋날 수 있다. MSI 관리 밖의 독립 콘텐츠가 있다면 소유 범위를 명확히 나눈 뒤 별도 방식으로 검토한다.
+
+| 상황 | 기본 경로 |
+| --- | --- |
+| 미설치 PC | 전체 설치 |
+| 기존 InstallShield 설치본에서 새 설치 체계로 전환 | 검증된 전체 설치 업그레이드 |
+| 같은 제품 계열에서 패치 규칙을 만족하는 변경 | 해당 기준을 지원하는 MSP |
+| 여러 버전을 건너뛰는 업데이트 | 기준을 명시한 누적·직접 패치, 없으면 전체 설치 |
+| 제품 구조·아키텍처·필수 런타임 변경 등 패치 비호환 | 검증된 전체 설치 업그레이드 |
+| 패치 대상 파일 변경·누락, 기준 또는 이력 불일치 | 패치 적용 차단 후 검증된 복구·전체 설치 경로 |
+
+이 표의 최초 전환 정책은 프로젝트 권고안이다. 기존 InstallShield 패키지에 MSP를 적용하는 것이 기술적으로 항상 불가능하다는 뜻은 아니다.
+
+## MSI 패치 계열 설계
+
+최초 전환은 Major Upgrade로 검토하되, 이후 패치 가능한 계열은 ProductCode와 구성요소 식별·경로 규칙을 안정적으로 유지한다. 버전을 구분하는 패치는 Minor Upgrade를 우선 사용해 ProductVersion을 올리고, 변경된 MSI의 PackageCode는 갱신한다. 앱의 버전 명명 규칙과 Windows Installer의 Major·Minor 구분은 같은 의미가 아니다. [Windows Installer 업데이트 구분](https://learn.microsoft.com/en-us/windows/win32/msi/patching-and-upgrades)
+
+새 WiX 설치 정의부터 패치 가능성을 고려한다. 파일 추가·삭제·이동, 구성요소 키 경로, 레지스트리 변경이 패치 규칙을 만족하는지 검사하고, 규칙에 맞지 않으면 전체 업그레이드로 전환한다. 기준 버전의 MSI, 서명된 실제 파일, 구성요소 정의, WiX 빌드 정보와 도구 버전을 보관한다.
+
+Burn EXE를 통해 설치한 제품은 MSP 적용 후에도 번들 표시 버전·MSI 등록·복구·제거가 일관되도록 설계한다. 직접 MSP 실행 또는 패치용 번들 중 실행 방식을 정하고, 이후 전체 설치와의 탐지·업데이트 경로까지 시험한다. 전체 파일을 다시 실행하는 것만으로 같은 ProductCode의 Minor Upgrade나 복구가 자동 처리된다고 가정하지 않는다.
+
+## 패키지와 메타데이터
+
+전체 설치본과 여러 패치를 하나의 목표 릴리스에 연결한다. 패치 아티팩트마다 다음 정보를 관리한다.
+
+| 필드 | 의미 |
+| --- | --- |
+| patchId / artifactId | 변경 불가능한 패치 식별자 |
+| targetReleaseId | 적용 완료 시 도달할 목표 릴리스 |
+| supportedBases | 허용 기준 릴리스·빌드·설치 정보의 명시적 목록 |
+| installerIdentity | 제품 코드, 아키텍처, 언어, 설치 범위 |
+| patchState | 필요한 기존 패치와 대체되는 패치, 적용 순서 |
+| requirements | 최소 업데이터, OS·런타임 조건, 공간·재부팅 조건 |
+| integrity | 패치 크기·해시·서명, 필요한 기준 파일 및 목표 파일 검증 정보 |
+| fallbackArtifactId | 동일 목표 릴리스의 검증된 전체 설치 경로 |
+
+표시 버전 문자열만으로 패치 가능 여부를 판정하지 않는다. 같은 버전에서 다시 빌드한 파일, 아키텍처, 적용된 패치 이력 등이 다를 수 있다. 클라이언트의 파일 검증은 공급자가 관리하는 대상에 한정하고 사용자 CUI·도면·사용자 설정은 기준 해시와 같아야 하는 파일에 포함하지 않는다.
+
+## 선택 예시
+
+아래 버전은 모두 전환 후 같은 패치 계열이라는 가정의 예시다. 실제 지원 여부를 의미하지 않는다.
+
+| 현재 상태 | 그룹 목표 | 선택 |
+| --- | --- | --- |
+| 미설치 | 2.0.2 | 2.0.2 전체 설치 |
+| 2.0.0, 기준 일치 | 2.0.2 | 2.0.0→2.0.2 누적 패치 |
+| 2.0.1, 기준 일치 | 2.0.2 | 2.0.1→2.0.2 패치 |
+| 2.0.1, 기준 불일치 | 2.0.2 | 검증된 복구·전체 설치 경로 |
+| 2.0.2 | 2.0.2 | 정상 상태라면 작업 없음 |
+| 2.0.3 | 2.0.2 | 일반 정책에서 다운그레이드하지 않음 |
+
+초기에는 지원 기준에서 목표까지 한 번에 도달하는 패치를 우선한다. 누적 패치는 선언한 모든 기준과 패치 이력을 검증한다. 모든 과거 버전 쌍의 패치를 만들 필요는 없으며, 지원 범위 밖은 전체 설치로 연결한다. 지원 기준 범위와 보존 기간은 운영 규모에 맞춰 확정한다.
+
+## 적용과 실패 처리
+
+1. 인증된 그룹의 목표 릴리스를 결정하고 현재 설치 정보·패치 이력·기준 상태를 조회한다.
+2. 검증된 적용 경로 중 패치를 선택한다. 호환 패치가 없거나 이점이 없으면 승인된 전체 경로를 선택한다.
+3. 패치를 다운로드하고 서명·해시·호환 조건을 검증한다. 설치 직전 배포 중지 여부를 다시 확인한다.
+4. 설정 백업 성공과 앱 종료를 확인하고 다른 설치 작업과 직렬화한다.
+5. Windows Installer로 적용하고 종료 코드·재부팅 필요 여부·패치 등록 상태를 기록한다.
+6. 목표 파일 및 자체 PE 서명, 설치 버전, 핵심 기능을 검증한 후 성공을 확정한다.
+
+다운로드 실패는 원본 설치를 변경하지 않은 상태에서 재시도한다. 적용 실패는 먼저 롤백 완료·재부팅 대기·현재 설치 상태를 판별한다. 상태가 확인되고 전체 경로가 허용될 때만 전체 설치로 전환한다. 롤백 실패나 불확실한 상태에서는 로그·백업을 보존하고 복구 대상으로 표시하며 무조건 덮어쓰지 않는다.
+
+패치 제거를 통한 이전 버전 복귀는 패치가 제거 가능하게 작성되고 데이터 호환성이 검증된 경우에만 허용한다. 그 외에는 더 높은 버전의 수정 릴리스를 사용한다. 클라이언트 캐시·원본 패키지가 필요한 복구·제거 경로도 시험한다.
+
+## 배포와 완료 기준
+
+지원 기준별 패치는 전체 설치본과 함께 4단계 배포를 통과한다. 동일 목표에 도달하더라도 각 패치 경로의 검증 결과가 필요하다. 전체 릴리스 중지는 패치와 전체 설치 모두에 적용한다.
+
+패치 적용 후 새로 설치한 목표 버전과 공급자 관리 파일·레지스트리·등록 버전·기능 상태가 일치해야 한다. 사용자 데이터는 보존하며 동일 바이트 상태를 요구하지 않는다. 패치 후 복구·제거·다음 업데이트와 실패 복구를 [검증 계획](07-implementation-and-validation.md)에 포함한다.