---
paths:
  - "VideoDownloader.Core/**"
  - "VideoDownloader.Server/**"
---

# 엔진 · 서버 영역 규칙

## 플랫폼 중립

`Core` 는 `net8.0` 이다. WPF·Windows 전용 API 를 끌어들이지 않는다.
Avalonia/MAUI 가 같은 엔진을 쓰므로 여기 들어간 Windows 의존은 크로스플랫폼 이관을 막는다.
OS별 경로는 `Platform/CorePaths.cs` 를 통한다.

## 외부 프로세스 (ffmpeg 등)

`Platform/ProcessModels.cs` 의 실행 헬퍼를 쓴다. 직접 `Process.Start` 를 새로 쓰지 않는다.
그 헬퍼가 보장하는 것들을 우회하면 과거 버그가 재발한다:

- stdout/stderr **동시 드레인** — 안 읽으면 파이프 버퍼가 차서 ffmpeg 가 hang 한다
- 취소·실패 시 `Kill(entireProcessTree: true)` — 안 하면 좀비 프로세스가 남는다
- 인자는 배열 전달 — 문자열 연결 금지
- exit code ≠ 0 이면 예외 — 조용히 넘어가면 실패가 `.ts` 잔재로만 드러난다

## 취소

모든 장기 작업은 `CancellationToken` 을 끝까지 전달한다. 중간에 삼키지 않는다.
`Parallel.ForEachAsync` 는 `ParallelOptions.CancellationToken` 에 넣는다
(`Hls/HlsDownloader.cs:77` 패턴).

## 동시성

세그먼트 병렬도는 `AppConfig.Concurrency`, 동시 다운로드 수는 `MaxConcurrentDownloads`(기본 3)로
제어한다. 하드코딩된 병렬도를 새로 만들지 않는다 — 소켓 고갈로 이어진다.

## 데이터 경로

사용자 데이터는 `CorePaths` 를 통해서만 접근한다. `VD_DATA_DIR` 환경변수 오버라이드가
E2E 테스트 격리의 공식 후크이므로, 경로를 직접 조립하면 테스트가 실사용자 폴더를 오염시킨다.

## 서버

`Server` 는 App 안에서 호스팅되는 라이브러리다. 포트 0 이면 빈 포트를 자동 할당한다.
LAN 노출 API 이므로 인증·경로 검증을 우회하는 엔드포인트를 추가하지 않는다.