fix: initialize selected runtime for live playout

docs/DEVELOPMENT_LIVE_HANDOFF.md

@@ -54,28 +54,36 @@ SHA-256을 이 PC의 최초 기준으로 자동 고정한다. 이후 DLL이나
 PowerShell 명령은 필요 없다.
 
 1. 저장소를 clone하고 `MBN_STOCK_WEBVIEW.sln`을 Visual Studio 2026에서 연다.
-2. `Debug|x64`, `Legacy Parity App (VS F5)`,
+2. 솔루션 루트의 `.vsconfig` 안내에 따라 **WinUI 애플리케이션 개발** 워크로드를
+   설치한다. 설치 뒤에는 Visual Studio를 다시 시작한다.
+3. `Debug|x64`, `Legacy Parity App (VS F5)`,
    `MBN_STOCK_WEBVIEW.LegacyParityApp - Development Live (Package)`를 선택한다.
-3. 첫 번째 F5로 소스 전용 첫 실행 설정 앱을 연다. 이 프로세스는 DB와 송출 엔진을
+4. 첫 번째 F5로 소스 전용 첫 실행 설정 앱을 연다. 이 프로세스는 DB와 송출 엔진을
    만들지 않고 Tornado2/PGM에 연결하지 않는다.
-4. `Cuts 폴더 선택`에서 실제 실행 자산의 `Cuts` 폴더를 선택한다.
-5. `Res 폴더 선택`에서 기존 코더가 사용하는 실제 `Res` 폴더를 선택한다.
-6. 두 폴더가 같은 공통 부모 아래의 정확한 `Cuts`, `Res`인지 확인하고 `설정 시작`을 누른다.
-7. `설정 완료`가 표시되면 창을 닫고 F5를 한 번 더 누른다.
+5. `Cuts 폴더 선택`에서 실제 실행 자산의 `Cuts` 폴더를 선택한다.
+6. `Res 폴더 선택`에서 기존 코더가 사용하는 실제 `Res` 폴더를 선택한다.
+7. 두 폴더가 같은 공통 부모 아래의 정확한 `Cuts`, `Res`인지 확인하고 `설정 시작`을 누른다.
+8. Debug x64 빌드까지 끝나 `설정 완료`가 표시되면 창을 닫고 F5를 한 번 더 누른다.
+
+`GetLatestMSVCVersion`이 Visual Studio의 `VC\Tools\MSVC` 폴더를 찾지 못하면 WinUI
+워크로드가 빠진 상태이므로 2단계를 완료한 뒤 다시 연다. 이 문제는 K3D 또는 DB 연결
+오류가 아니다.
 
 소스 트리의 오래된 `RES`나 이름이 비슷한 백업 폴더를 선택하지 않는다. `설정 시작`은
-두 폴더의 고정 로컬 경로만 다음 위치에 저장한다.
+선택한 `Res\MmoneyCoder.ini`의 Oracle/MariaDB 형식을 먼저 확인하고 두 폴더의 고정 로컬
+경로를 다음 위치에 저장한다.
 
 - `%LOCALAPPDATA%\MBN_STOCK_WEBVIEW\Config\runtime-folders.local.json`
 - 저장소의 Git 제외 `Directory.Build.local.props`
 
-이 버튼은 폴더 안의 파일을 열거·파싱·복사하지 않으며 PowerShell, `dotnet build`, DB 복사,
-K3D 검사, Live 승인 발급 또는 Tornado2/PGM 명령을 실행하지 않는다. 따라서 경로 저장은
-즉시 완료되어야 한다. `Cuts`와 `Res`의 실제 파일 검사는 다음 F5의 빌드 또는 해당 기능을
-사용하는 시점에 필요한 파일 단위로 수행된다.
+이 버튼은 검증된 `Initialize-ExistingDevelopmentPc.ps1`을 실행해
+`C:\K3DAsyncEngine`의 x64 파일과 Registry64 등록, 최초 지속 K3D pin,
+`127.0.0.1:30001` Development Live 승인 및 전체 Debug x64 빌드를 확인한다. DB INI를
+복사하지 않으며 DB 연결, K3D COM 활성화, Tornado2/PGM 연결 또는 송출 명령도 실행하지
+않는다. 자동 pin은 검증한 최초 설치에만 가능하고 기존 pin과 다른 DLL을 재승인하지 않는다.
 
-전체 Debug x64 빌드는 설정 창을 닫고 누르는 다음 F5에서 진행된다. 필요하면 같은 조건을
-별도 MSBuild 인자나 환경 변수 없이 다음 명령으로 확인할 수 있다.
+자동 설정 안에서 전체 Debug x64 빌드를 이미 검증한다. 필요하면 설정 완료 뒤 같은 조건을
+별도 MSBuild 인자나 환경 변수 없이 다음 명령으로 다시 확인할 수 있다.
 
 ```powershell
 dotnet build .\src\MBN_STOCK_WEBVIEW.LegacyParityApp\MBN_STOCK_WEBVIEW.LegacyParityApp.csproj `
@@ -84,39 +92,38 @@ dotnet build .\src\MBN_STOCK_WEBVIEW.LegacyParityApp\MBN_STOCK_WEBVIEW.LegacyPar
 ```
 
 출력에 외부 runtime 경로가 활성화되었다는 메시지가 있어야 한다. 소스 전용 모드가 계속
-표시되면 Visual Studio에서 다시 빌드한다. Live 기동이 차단되면 별도의 Development Live
-승인이나 보호 설정이 아직 유효하지 않은 것이다.
+표시되면 Visual Studio에서 다시 빌드한다. Live 기동이 차단되면 선택한 DB INI, K3D pin,
+Development Live 승인 또는 보호 설정 중 하나가 유효하지 않은 것이다.
 같은 clone에서는 이후 `git pull` 뒤 Visual Studio 2026에서 `Debug|x64`, 시작 대상
 `Legacy Parity App (VS F5)`, 실행 프로필
 `MBN_STOCK_WEBVIEW.LegacyParityApp - Development Live (Package)`를 선택해 F5로 시작할 수
-있다. 저장소를 새 폴더에 다시 clone하면 첫 실행 경로 저장을 다시 진행한다. DB overlay,
-K3D pin과 Development Live 승인이 없는 새 PC에서는 아래 수동 초기화 절차를 별도로
-완료하기 전까지 전체 앱 기동을 차단한다. K3D DLL 변경은 경로 저장을 반복해도 자동
-승인되지 않는다. 최초 실제 동작
+있다. 저장소를 새 폴더에 다시 clone하면 첫 실행 설정을 다시 진행한다. K3D DLL 변경은
+자동 설정을 반복해도 자동 승인되지 않는다. 최초 실제 동작
 확인은 아래 최소 인수 시퀀스의 `5001` 하나로 제한한다.
 
-### Development Live까지 준비할 때
+### 자동 설정이 실패했거나 로컬 설정을 명시적으로 교체할 때
 
-첫 실행 경로 저장과 별개로 DB overlay, K3D pin과 Development Live 승인까지 새로
-준비해야 할 때 저장소 루트에서 다음 수동 명령을 사용한다. 이 명령은 전체 Debug 빌드
-검증까지 수행하므로 단순 폴더 저장 버튼보다 오래 걸리는 것이 정상이다.
+화면을 열 수 없거나 기존 runtime/Live 설정의 명시적 교체가 필요한 경우에만 저장소
+루트에서 다음 수동 명령을 사용한다. `-SkipDatabaseProfile`은 선택한
+`Res\MmoneyCoder.ini`를 복사하지 않고 런타임이 계속 직접 사용하게 한다.
 
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass `
   -File .\scripts\Initialize-ExistingDevelopmentPc.ps1 `
   -LegacyRuntimeSourceRoot '<Cuts와 Res의 공통 부모>' `
   -NoFolderPicker `
+  -SkipDatabaseProfile `
   -ConfigureDevelopmentLive `
   -PlayoutHost 127.0.0.1 `
   -PlayoutPort 30001 `
   -PinRegisteredK3D
 ```
 
-기존 로컬 runtime, DB 또는 Live 설정과 다르면 자동으로 덮어쓰지 않는다. 변경 대상을 검토한
-뒤에만 `-ReplaceRuntimeBinding`, `-ReplaceDatabaseProfile`, `-ReplaceLiveConfig` 중 필요한
-항목을 명시한다. 수동 모드는 기존처럼 독립 승인된 `-NativeSha256`과 `-InteropSha256`을
-사용할 수도 있으며, 이 두 값과 `-PinRegisteredK3D`는 함께 쓸 수 없다. 이 스크립트는
-첫 실행 화면에서 자동으로 호출되지 않는다.
+기존 로컬 runtime 또는 Live 설정과 다르면 자동으로 덮어쓰지 않는다. 오류와 변경 대상을
+검토한 뒤에만 `-ReplaceRuntimeBinding`, `-ReplaceLiveConfig` 중 필요한 항목을 명시한다.
+수동 모드는 기존처럼 독립 승인된 `-NativeSha256`과 `-InteropSha256`을 사용할 수도 있으며,
+이 두 값과 `-PinRegisteredK3D`는 함께 쓸 수 없다. 첫 실행 화면도 같은 스크립트를 위의
+고정 인수로 호출하지만 기존 값을 임의로 교체하지 않는다.
 
 ## 3. 자산이 없는 PC 대안: 검증된 Git 밖 runtime bundle 설치
 
@@ -208,31 +215,26 @@ dotnet build .\src\MBN_STOCK_WEBVIEW.LegacyParityApp\MBN_STOCK_WEBVIEW.LegacyPar
 
 ## 4. DB 로컬 설정 확인 또는 대안
 
-2단계의 기존 PC 초기화는 검증한 `MmoneyCoder.ini`를 다음 실행 사용자 전용 경로에 이미
-복사한다.
+2단계의 기존 PC 자동 설정은 선택한 `Res\MmoneyCoder.ini`에 필요한 Oracle/MariaDB 항목이
+있는지 확인하지만 파일을 복사하지 않는다. 전체 앱은
+`runtime-folders.local.json`에 저장된 `resourceDirectory`의 정확한
+`MmoneyCoder.ini`를 매 실행 직접 읽는다. DB 환경 변수는 적용하지 않으며 파일 누락, reparse
+point, 비고정 드라이브 또는 INI 형식 오류가 있으면 LocalAppData 설정으로 대체하지 않고
+Live 엔진 생성과 자동 연결을 차단한다. 값은 화면 캡처나 로그에 남기지 않는다.
+
+다음 기존 사용자 전용 INI와 JSON은 **저장된 `resourceDirectory`가 없는 설치에서만**
+호환 fallback으로 사용한다. 3단계 외부 bundle처럼 DB 파일을 의도적으로 포함하지 않고
+운영자 `Res` 경로도 저장하지 않은 흐름에서는 사용자 전용 INI 또는 JSON을 별도로 준비한다.
 
 ```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을 쓰는 환경이면
+기존 INI를 사용하지 않고 JSON 설정으로 전환하기로 명시적으로 결정한 경우에는 사용자 전용
+INI가 존재하지 않는 것을 먼저 확인한다. 기존 파일의 제거·전환은 이 절차에서 임의로 수행하지
+않고 별도 검토된 자격증명 작업으로 처리한다. JSON을 만들려면 저장소 루트에서 초기화
+스크립트를 사용한다. Oracle이 service name을 쓰는 환경이면
 `-OracleSid` 대신 `-OracleServiceName`을 사용한다.
 
 ```powershell
@@ -255,21 +257,25 @@ powershell -NoProfile -ExecutionPolicy Bypass `
 
 ## 5. K3D 설치, 라이선스와 기준 해시 확인
 
-벤더 절차로 Tornado2/K3D x64와 장비 라이선스를 먼저 설치한다. 저장소의 점검은 레지스트리와
+벤더 절차로 Tornado2/K3D x64와 장비 라이선스를 회사 표준 루트
+`C:\K3DAsyncEngine`에 먼저 설치한다. native는
+`DLL\x64\Release\K3DAsyncEngine.dll`, Interop은
+`Bin\x64\C#\Interop.K3DAsyncEngineLib.dll`이어야 한다. 저장소의 점검은 레지스트리와
 파일을 읽을 뿐 COM을 활성화하지 않는다. 2단계 초기화는 이 검사를 항상 수행하고 `Valid`,
-`ComActivated=false`가 아니면 로컬 설정을 완료하지 않는다. 다음 명령은 동일한 검사를 별도로
-다시 확인할 때 사용한다.
+`ComActivated=false`가 아니면 로컬 설정을 완료하지 않는다. 다음 명령은 동일한 검사를
+별도로 다시 확인할 때 사용한다.
 
 ```powershell
 powershell -NoProfile -ExecutionPolicy Bypass `
   -File .\scripts\Inspect-K3DRegistration.ps1
 ```
 
-Registry64, TypeLib/CLSID 양방향 매핑, `Apartment`, AMD64 PE, HKCU override 부재 검사가 모두
-성공해야 한다. 점검 성공은 라이선스 성공을 대신하지 않으므로 벤더 방식으로 라이선스도 별도
-확인한다. 첫 실행 설정은 이 검사를 통과한 native와 Interop 파일의 SHA-256을 최초 기준으로
-고정하며, 이후 실제 파일이 기준값과 하나라도 다르면 중단한다. 수동 승인 모드에서는 두 파일이
-각각 독립 승인된 SHA-256과 일치해야 한다.
+Registry64의 TypeLib, KAEngine, KAEventHandler가 모두 위 표준 native DLL을 가리키고,
+CLSID/ProgID 양방향 매핑, `Apartment`, AMD64 PE, HKCU override 부재 검사가 모두 성공해야
+한다. 다른 설치 루트나 fallback은 허용하지 않는다. 점검 성공은 라이선스 성공을 대신하지
+않으므로 벤더 방식으로 라이선스도 별도 확인한다. 첫 실행 설정은 이 검사를 통과한 native와
+Interop 파일의 SHA-256을 최초 기준으로 고정하며, 이후 실제 파일이 기준값과 하나라도 다르면
+중단한다. 수동 승인 모드에서는 두 파일이 각각 독립 승인된 SHA-256과 일치해야 한다.
 
 지속 pin 파일의 경로는 다음과 같다.
 
@@ -293,6 +299,7 @@ powershell -NoProfile -ExecutionPolicy Bypass `
   -File .\scripts\Initialize-ExistingDevelopmentPc.ps1 `
   -LegacyRuntimeSourceRoot '<Cuts와 Res의 공통 부모>' `
   -NoFolderPicker `
+  -SkipDatabaseProfile `
   -ConfigureDevelopmentLive `
   -PlayoutHost 127.0.0.1 `
   -PlayoutPort 30001 `
@@ -302,17 +309,19 @@ powershell -NoProfile -ExecutionPolicy Bypass `
   -ReplaceLiveConfig
 ```
 
-runtime이나 DB 위치도 의도적으로 달라졌을 때만 각각 `-ReplaceRuntimeBinding`,
-`-ReplaceDatabaseProfile`을 추가한다. 해시가 실제 등록 파일과 다르거나 K3D 등록 검사가
-실패하면 기존 pin을 보존하고 중단한다.
+runtime 위치도 의도적으로 달라졌을 때만 `-ReplaceRuntimeBinding`을 추가한다. 선택한
+`Res\MmoneyCoder.ini`는 계속 직접 사용하므로 이 흐름에서 DB profile을 복사하거나
+교체하지 않는다. 해시가 실제 등록 파일과 다르거나 K3D 등록 검사가 실패하면 기존 pin을
+보존하고 중단한다.
 
 ## 6. 보호된 로컬 송출 설정
 
-별도 수동 Development Live 초기화는 지속 K3D pin을 확인한 뒤 아래 송출 설정 두 파일도
-마지막 기능 설정 단계에서 검증 후 새로 발급한다. 기존 승인은 매번 먼저 무효화하며 runtime·DB·Debug 빌드가 모두
-성공하지 않으면 새 Live 승인 파일을 남기지 않는다. 자산 없는 PC의 3단계 bundle 흐름처럼
-설정만 별도로 초기화해야 할 때는 저장소 루트에서 다음 스크립트를 실행한다. 이 수동 경로의
-두 해시는 별도로 확인한 값이어야 한다. 지정 개발 PC의 endpoint는
+2단계 자동 설정과 별도 수동 Development Live 초기화는 지속 K3D pin을 확인한 뒤 아래
+송출 설정 두 파일도 마지막 기능 설정 단계에서 검증 후 새로 발급한다. 기존 승인은 매번 먼저
+무효화하며 runtime·DB 설정·Debug 빌드가 모두 성공하지 않으면 새 Live 승인 파일을 남기지
+않는다. 자산 없는 PC의 3단계 bundle 흐름처럼 설정만 별도로 초기화해야 할 때는 저장소
+루트에서 다음 스크립트를 실행한다. 이 수동 경로의 두 해시는 별도로 확인한 값이어야 한다.
+지정 개발 PC의 endpoint는
 `127.0.0.1:30001`로 고정한다. 기존 승인 프로필이 별도 출력 채널을 사용할 때만 검증된 숫자를
 `-OutputChannel`로 추가하며, 기본 player를 쓰는 경우에는 생략한다.
 
@@ -344,7 +353,7 @@ powershell -NoProfile -ExecutionPolicy Bypass `
 | `host` | 로컬 PGM이면 숫자형 loopback `127.0.0.1`. `localhost` 또는 원격 주소를 추정하지 않는다. |
 | `port` | 지정 개발 환경의 고정 Network Server TCP port `30001` |
 | `tcpMode` / `clientPort` | `1` / `0` |
-| `sceneDirectory` | `null`. 검증된 로컬 runtime이 빌드 출력에 배치한 기본 `Cuts`를 사용한다. |
+| `sceneDirectory` | `null`. 앱이 운영자 설정에 저장된 정확한 외부 `Cuts` 경로를 적용한다. |
 | `outputChannel` | 승인된 개발 PGM 라우팅 값. 기존 승인 프로필이 기본 player를 쓰는 경우에만 `null` |
 | `testSceneAllowlist` | 아래 active alias 45개만 허용 |
 | `trustedLiveOutputEnabled` | `true` |