feat: initialize existing development playout PCs

docs/DEVELOPMENT_LIVE_HANDOFF.md

@@ -13,17 +13,21 @@
 유효하다. `Release`와 일반 설치본의 기본 모드는 계속 `DryRun`이다. Release를 Live로 바꾸거나
 사용자·시스템 환경 변수에 Live 승인을 영구 저장하지 않는다.
 
-## 인수 전에 별도로 전달할 항목
+## Git 밖에서 확인하거나 준비할 항목
 
-다음 항목은 저장소가 아니라 승인된 사내 전달 경로로 제공한다.
+상사 PC에 이미 `Cuts`, `Res\MmoneyCoder.ini`, Tornado2/K3D x64와 장비 라이선스가 있다면
+같은 항목을 다시 전달하지 않는다. 대신 기존 설치 위치가 이번 인수 대상이 맞는지 확인하고,
+다음 값은 저장소가 아니라 승인된 사내 기록이나 전달 경로에서 확인한다.
 
-- `New-LegacyRuntimeBundle.ps1`로 생성한 runtime bundle ZIP과 별도 신뢰 경로로 전달할
-  기대 SHA-256.
 - DB endpoint와 계정 정보. 메신저 화면, 작업 기록 또는 Git에 값을 남기지 않는다.
-- Tornado2/K3D x64 벤더 설치본과 해당 장비용 라이선스 설치 절차.
+- 기존 `Cuts`와 `Res`의 공통 부모 경로, 그리고 실제 자격증명 INI 경로.
+- Tornado2/K3D x64 설치본과 해당 장비용 라이선스 상태.
 - 벤더 배포본 또는 관리자 검수로 **독립 승인된** native DLL과 Interop DLL의 SHA-256 두 개.
 - 개발 PGM의 실제 Network Server TCP port, 창 제목, 출력 라우팅과 담당자 확인 정보.
 
+해당 PC에 승인된 `Cuts`/`Res`가 없을 때만 `New-LegacyRuntimeBundle.ps1`로 생성한 runtime
+bundle ZIP과 별도 신뢰 경로로 전달할 기대 SHA-256을 추가로 준비한다.
+
 현재 설치된 DLL의 해시를 그 자리에서 계산한 뒤 같은 값을 승인값으로 삼지 않는다. 라이선스
 파일, DLL, 인증서 또는 자산을 앱 폴더에 임의 복사해 등록·라이선스 검사를 우회하지 않는다.
 
@@ -40,7 +44,88 @@
 
 한 항목이라도 불명확하면 이후 명령을 보내지 않는다.
 
-## 2. 검증된 Git 밖 runtime bundle 설치
+## 2. 기존 자산 보유 PC: clone 후 1회 초기화
+
+상사 PC처럼 승인된 자산과 벤더 설치가 이미 있는 경우에는 이 흐름을 우선 사용한다. 저장소를
+clone한 뒤 Visual Studio를 열기 전에 저장소 루트의 PowerShell에서 다음 초기화기를 한 번
+실행한다.
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass `
+  -File .\scripts\Initialize-ExistingDevelopmentPc.ps1 `
+  -LegacyRuntimeSourceRoot '<Cuts와 Res의 공통 부모>' `
+  -ConfigureDevelopmentLive `
+  -PlayoutHost 127.0.0.1 `
+  -PlayoutPort <Tornado2에서 직접 확인한 Network-Server-port> `
+  -NativeSha256 '<독립 승인된 native DLL SHA-256>' `
+  -InteropSha256 '<독립 승인된 Interop DLL SHA-256>'
+```
+
+DB INI가 `<공통 부모>\Res\MmoneyCoder.ini`가 아닌 다른 위치에 있다면 검토한 절대 경로를
+`-DatabaseIniPath`로 추가한다. `-LegacyRuntimeSourceRoot`를 생략했을 때는 스크립트가
+정확한 기본 형제 저장소 경로를 먼저 확인하고, 찾지 못하면 폴더 선택기를 연다. 선택기에서는
+`Cuts`와 `Res`를 함께 포함하는 `bin\Debug` 공통 부모를 선택한다. 그 바로 아래의 `Cuts`
+또는 `Res`를 선택해도 스크립트가 공통 부모로 정규화한다. 이름이 비슷한 백업 폴더나 과거의
+다른 빌드 출력은 선택하지 않는다. 비대화형 실행에서 선택기를 금지하려면
+`-NoFolderPicker`를 추가하며, 이 경우 기본 형제 경로가 없으면 명시적 경로 없이 진행하지
+않는다.
+기존 승인 프로필이 별도 출력 채널을 사용하는 경우에만 확인된 숫자를
+`-OutputChannel <verified-channel>`로 추가하고, 기본 player를 사용하는 경우에는 생략한다.
+
+초기화기는 다음 작업을 한 번에 수행해야 한다.
+
+- 로컬 `Cuts`/`Res` tree와 프로젝트가 요구하는 자산 계약을 읽기 전용으로 검증하고, 임시
+  bundle을 거쳐 사용자 전용
+  `%LOCALAPPDATA%\MBN_STOCK_WEBVIEW\RuntimeBundles\<ZIP-SHA256>`에 검증된 복사본을 설치한다.
+- 저장소에서 제외되는 `Directory.Build.local.props`가 그 설치 root를
+  `LegacyRuntimeAssetsMode=Required`로 사용하게 한다.
+- 기존 DB INI를 `%LOCALAPPDATA%\MBN_STOCK_WEBVIEW\Res\MmoneyCoder.ini`로 복사하고 현재
+  Windows 사용자 전용 ACL을 적용한다.
+- K3D x64 등록 상태를 읽기 전용으로 점검한다.
+- `-ConfigureDevelopmentLive`를 지정했을 때만 port와 독립 승인 해시를 검증하고 보호된 로컬
+  Development Live 설정을 모든 선행 검증이 끝난 마지막 단계에서 새로 발급한다.
+- 별도 `-SkipBuild`를 주지 않은 기본 실행에서는 Debug x64 전체 자산 빌드 후 선택된 runtime
+  root, Cuts/Res의 경로·길이·SHA-256·전체 파일 집합, SourceOnly가 아님과 DB INI가 빌드
+  출력에 들어가지 않았음을 검증한다.
+
+초기화 과정 자체는 Tornado2/PGM에 `CONNECT`하거나 PREPARE, TAKE IN, NEXT, TAKE OUT 등의
+명령을 보내지 않는다. 초기화 도중 오류가 나면 F5로 송출을 시도하지 말고 원인부터 바로잡는다.
+`-ConfigureDevelopmentLive`와 `-SkipBuild`는 함께 사용할 수 없으므로 실제 송출 설정 전에
+전체 자산 빌드 검증을 생략할 수 없다. runtime 연결이나 DB overlay를 갱신한 뒤 선행 단계가
+실패하면 기존 파일의 정확한 내용과 ACL을 복구하고, Live 승인 파일은 제거된 상태로 둔다.
+
+기본 초기화가 이미 빌드를 확인한다. 필요하면 같은 조건이 유지되는지 별도 MSBuild 인자나 환경
+변수 없이 다음 명령으로 다시 확인할 수 있다.
+
+```powershell
+dotnet build .\src\MBN_STOCK_WEBVIEW.LegacyParityApp\MBN_STOCK_WEBVIEW.LegacyParityApp.csproj `
+  -c Debug `
+  -p:Platform=x64
+```
+
+출력에 전체 runtime 자산이 활성화되었다는 메시지가 있어야 한다. 소스 전용 모드,
+`bin\SourceOnly` 또는 `DryRun`만 표시되면 Development Live를 진행하지 않는다.
+위 권장 명령의 최종 요약은 `K3DStatus=Valid`, `K3DComActivated=false`,
+`BuildVerified=true`, `DevelopmentLiveRequested=true`여야 한다.
+`DevelopmentLiveWritten=true`, `DevelopmentLiveReused=false`여야 한다. 경로와 해시가 포함된
+전체 출력은 Git이나 일반 메신저에 붙이지 않는다.
+
+같은 자산·DB·Live 설정으로 다시 실행하면 검증된 runtime과 DB는 재사용하지만, 기존 Live
+승인은 먼저 무효화하고 전체 검증이 다시 성공한 뒤 새로 발급한다. 기존 값이 달라졌다면 자동으로
+덮어쓰지 않으며, 변경 대상을 먼저 검토한 뒤 필요한 항목에만 각각
+`-ReplaceRuntimeBinding`, `-ReplaceDatabaseProfile`, `-ReplaceLiveConfig`를 명시한다.
+
+같은 clone에서는 이후 `git pull` 뒤 Visual Studio 2026에서 `Debug|x64`, 시작 대상
+`Legacy Parity App (VS F5)`, 실행 프로필
+`MBN_STOCK_WEBVIEW.LegacyParityApp - Development Live (Package)`를 선택해 F5로 시작할 수
+있다. 저장소를 새 폴더에 다시 clone하거나 자산·DB·K3D·PGM 설정이 바뀐 경우에는 초기화기를
+다시 실행한다. pull 뒤 Required 자산 검증이 실패하는 경우에도 F5를 반복하지 말고 초기화기를
+다시 실행한다. 최초 실제 동작 확인은 아래 최소 인수 시퀀스의 `5001` 하나로 제한한다.
+
+## 3. 자산이 없는 PC 대안: 검증된 Git 밖 runtime bundle 설치
+
+기존 자산 보유 PC에서 2단계 초기화가 성공했다면 이 단계는 건너뛴다. 이 단계는 승인된
+`Cuts`/`Res`가 없는 새 개발 PC에만 사용하는 대안이다.
 
 원본 runtime tree를 새 PC에 직접 복사하거나 수동으로 ZIP을 만들지 않는다. 원본을 보유한
 지정 개발 장비에서 읽기 전용 `bin\Debug`을 입력으로 다음 스크립트를 실행한다.
@@ -125,15 +210,33 @@ dotnet build .\src\MBN_STOCK_WEBVIEW.LegacyParityApp\MBN_STOCK_WEBVIEW.LegacyPar
 않는다. bundle 초기화 결과와 `Directory.Build.local.props`를 고친 뒤 전체 자산 빌드부터 다시
 확인한다.
 
-## 3. DB 로컬 설정
+## 4. DB 로컬 설정 확인 또는 대안
 
-Debug/Release와 Package 앱의 DB 설정은 모두 실행 사용자 전용 경로에 만든다.
+2단계의 기존 PC 초기화는 검증한 `MmoneyCoder.ini`를 다음 실행 사용자 전용 경로에 이미
+복사한다.
+
+```text
+%LOCALAPPDATA%\MBN_STOCK_WEBVIEW\Res\MmoneyCoder.ini
+```
+
+파일 내용의 원본 일치 여부와 현재 Windows 사용자 전용 ACL을 확인하되 값을 화면 캡처나 로그에
+남기지 않는다. 기존 파일이 원본과 다르면 초기화기는 자동으로 덮어쓰지 않는다. 대상이 정확한지
+확인한 뒤 2단계 명령에 `-ReplaceDatabaseProfile`을 추가한다. 이 INI는 빌드 입력·출력이나
+runtime bundle에 포함되지 않는다.
+
+3단계의 외부 bundle은 DB 파일을 의도적으로 포함하지 않으므로 그 흐름에서는 다음 JSON
+초기화가 필요하다. 기존 INI를 사용하지 않고 새 JSON 설정으로 전환하기로 명시적으로 결정한
+경우에는 **아래 INI overlay가 존재하지 않는 것을 먼저 확인한 뒤에만** 2단계 초기화에
+`-SkipDatabaseProfile`을 주고 같은 대안을 사용한다. 이 옵션은 기존 INI를 삭제하거나
+비활성화하지 않으며, INI가 남아 있으면 앱이 JSON보다 먼저 사용한다. 기존 overlay가 있는
+PC의 전환은 이 절차에서 임의 삭제하지 말고 별도 검토된 자격증명 제거·전환 작업으로 처리한다.
+JSON 경로는 다음과 같다.
 
 ```text
 %LOCALAPPDATA%\MBN_STOCK_WEBVIEW\Config\database.local.json
 ```
 
-저장소 루트에서 기존 초기화 스크립트를 사용한다. Oracle이 service name을 쓰는 환경이면
+저장소 루트에서 초기화 스크립트를 사용한다. Oracle이 service name을 쓰는 환경이면
 `-OracleSid` 대신 `-OracleServiceName`을 사용한다.
 
 ```powershell
@@ -154,10 +257,12 @@ powershell -NoProfile -ExecutionPolicy Bypass `
 검증으로 넘어가지 않는다. DB 연결 확인은 [DB 운영 가이드](DATABASE.md)의 read-only smoke만
 먼저 수행하고, 실패 시 Tornado 명령을 보내지 않는다.
 
-## 4. K3D 설치, 라이선스와 승인 해시 확인
+## 5. K3D 설치, 라이선스와 승인 해시 확인
 
 벤더 절차로 Tornado2/K3D x64와 장비 라이선스를 먼저 설치한다. 저장소의 점검은 레지스트리와
-파일을 읽을 뿐 COM을 활성화하지 않는다.
+파일을 읽을 뿐 COM을 활성화하지 않는다. 2단계 초기화는 이 검사를 항상 수행하고 `Valid`,
+`ComActivated=false`가 아니면 로컬 설정을 완료하지 않는다. 다음 명령은 동일한 검사를 별도로
+다시 확인할 때 사용한다.
 
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass `
@@ -169,9 +274,12 @@ Registry64, TypeLib/CLSID 양방향 매핑, `Apartment`, AMD64 PE, HKCU override
 확인한다. native와 Interop의 실제 파일은 각각 독립 승인된 SHA-256과 일치해야 하며 둘 중 하나라도
 다르면 중단한다.
 
-## 5. 보호된 로컬 송출 설정
+## 6. 보호된 로컬 송출 설정
 
-저장소 루트에서 다음 스크립트를 실행해 두 파일을 함께 만든다. port는 이번에 Tornado2 화면에서
+2단계 초기화에 `-ConfigureDevelopmentLive`와 필수 값을 주었다면 아래 설정 두 파일도
+마지막 단계에서 검증 후 새로 발급된다. 기존 승인은 매번 먼저 무효화하며 runtime·DB·Debug
+빌드가 모두 성공하지 않으면 새 Live 승인 파일을 남기지 않는다. 자산 없는 PC의 3단계 bundle 흐름처럼 설정만 별도로
+초기화해야 할 때는 저장소 루트에서 다음 스크립트를 실행한다. port는 이번에 Tornado2 화면에서
 직접 확인한 값이고, 두 해시는 독립 승인값이어야 한다. 기존 승인 프로필이 별도 출력 채널을
 사용할 때만 검증된 숫자를 `-OutputChannel`로 추가하며, 기본 player를 쓰는 경우에는 생략한다.
 
@@ -203,7 +311,7 @@ powershell -NoProfile -ExecutionPolicy Bypass `
 | `host` | 로컬 PGM이면 숫자형 loopback `127.0.0.1`. `localhost` 또는 원격 주소를 추정하지 않는다. |
 | `port` | Tornado2 화면에서 이번에 직접 확인한 Network Server TCP port |
 | `tcpMode` / `clientPort` | `1` / `0` |
-| `sceneDirectory` | `null`. 검증된 bundle이 빌드 출력에 배치한 기본 `Cuts`를 사용한다. |
+| `sceneDirectory` | `null`. 검증된 로컬 runtime이 빌드 출력에 배치한 기본 `Cuts`를 사용한다. |
 | `outputChannel` | 승인된 개발 PGM 라우팅 값. 기존 승인 프로필이 기본 player를 쓰는 경우에만 `null` |
 | `testSceneAllowlist` | 아래 active alias 45개만 허용 |
 | `trustedLiveOutputEnabled` | `true` |
@@ -221,6 +329,14 @@ powershell -NoProfile -ExecutionPolicy Bypass `
 `8010`, `8086`, 임의 파일명과 절대 scene 파일 경로는 allowlist에 추가하지 않는다. 실제 endpoint,
 채널, 경로와 allowlist가 든 이 파일을 Git이나 지원 첨부파일에 넣지 않는다.
 
+Development Live로 승인된 프로세스는 이 26개 속성을 strict JSON으로 다시 읽으며, 중복·추가
+속성, 대소문자 차이, 잘못된 타입을 거부한다. 상속된 `MBN_STOCK_PLAYOUT_*` 환경 변수와 기존
+운영자 scene/resource/background 선택은 적용하지 않는다. endpoint는 숫자형 loopback,
+scene root는 실행 파일 옆 검증된 `Cuts`로 마지막에 다시 고정한다. DB도
+`%LOCALAPPDATA%\MBN_STOCK_WEBVIEW\Res\MmoneyCoder.ini`를 우선하고, 없을 때만 보호된
+`Config\database.local.json`을 사용하며 DB 환경 변수는 무시한다. 이 strict 경로가 성립하지
+않으면 Live로 진행하지 않고 안전한 DryRun으로 시작한다.
+
 ### `playout.development-live.local.json`
 
 경로는 다음과 같다.
@@ -245,7 +361,7 @@ powershell -NoProfile -ExecutionPolicy Bypass `
 현재 설치 파일에서 즉석 계산한 값으로 placeholder를 채우지 않는다. 자세한 strict 파일 규칙은
 [Visual Studio Development Live 설정](DEVELOPMENT_LIVE_VISUAL_STUDIO.md)을 따른다.
 
-## 6. 정확한 로컬 PGM 연결 전용 확인
+## 7. 정확한 로컬 PGM 연결 전용 확인
 
 Network Monitoring을 먼저 연다. 독립 승인 해시는 이 진단을 실행할 현재 PowerShell
 프로세스에만 설정한 뒤 실제 port로 connect-only 진단을 한 번 실행한다.
@@ -272,15 +388,15 @@ timeout, `OutcomeUnknown`, 대상 PID·시작 시각·listener 변경 또는 결
 진단을 반복하지 않는다. 새 명령을 보내지 말고 PGM과 Network Monitoring 상태를 읽기 전용으로
 확인한 뒤 새 인수 회차를 계획한다.
 
-## 7. Development Live 최소 인수 시퀀스
+## 8. Development Live 최소 인수 시퀀스
 
 1. 기존 앱 인스턴스를 정상 종료한다.
 2. Visual Studio에서 구성 `Debug`, 플랫폼 `x64`, 시작 대상
    `Legacy Parity App (VS F5)`를 선택한다.
 3. 실행 프로필을
    `MBN_STOCK_WEBVIEW.LegacyParityApp - Development Live (Package)`로 선택하고 F5로 시작한다.
-4. 앱이 소스 전용 또는 DryRun으로 시작했다면 실제 명령을 시도하지 않는다. runtime bundle,
-   시작 인자와 두 로컬 파일을 고친 뒤 앱을 새로 시작한다.
+4. 앱이 소스 전용 또는 DryRun으로 시작했다면 실제 명령을 시도하지 않는다. runtime 초기화와
+   로컬 binding, 시작 인자와 두 로컬 파일을 고친 뒤 앱을 새로 시작한다.
 5. 최초 인수는 자산이 완전한 사전 합의 scene 하나만 사용한다. 기본 최소 회차는 active alias
    `5001`의 `CONNECT 1회 → PREPARE 1회 → 화면·Network Monitoring 확인 → TAKE IN 1회
    → 화면 확인 → TAKE OUT 1회 → DISCONNECT 1회`다.
@@ -293,7 +409,7 @@ timeout, `OutcomeUnknown`, 대상 PID·시작 시각·listener 변경 또는 결
 allowlist 실패가 발생하면 다음 동작, 같은 동작 반복, 반대 동작이나 추측성 cleanup을 하지 않는다.
 PGM/Tornado2를 강제 종료하지 말고 상태를 보존한다.
 
-## 8. DryRun 복귀와 인수 완료 조건
+## 9. DryRun 복귀와 인수 완료 조건
 
 Live 앱을 종료하면 부트스트랩이 만든 Live 환경은 프로세스와 함께 사라져야 한다.
 `playout.local.json`의 `mode`는 계속 `DryRun`이어야 한다. 다음으로
@@ -304,7 +420,7 @@ Live 앱을 종료하면 부트스트랩이 만든 Live 환경은 프로세스
 다음 항목이 모두 맞아야 인수를 완료한다.
 
 - 지정 개발 PC와 정확한 로컬 PGM 대상 확인
-- 외부 runtime bundle과 허용 scene 검증
+- 기존 자산 또는 외부 bundle에서 설치한 검증된 로컬 runtime과 허용 scene 확인
 - K3D x64 등록, 장비 라이선스와 두 독립 승인 해시 확인
 - 개발 DB read-only smoke 성공
 - 두 `%LOCALAPPDATA%` 설정 파일의 내용·ACL 검증