BurningTimesAi/개발실/코어_설계/03_배포방식_안건_v1.md

# 03. NerdNavis.Framework 배포 방식 안건 (OI-2)

> **작성자**: 개발실장
> **버전**: v1 (2026-04-15 재작성)
> **문서 성격**: PD님 의사결정 안건서. 권장안 + 근거 + 후속 조치
> **근거 규칙**: 🌟 헌법 제1원칙 (조직 비전 목표 1·2·3), C14(토큰 최소화), C15(일정 배제), C18(공유 완료 기준), C19(승인 범위 엄격 해석)

---

## 🚨 본 안건의 목적·용도·범위·비목적

| 축 | 내용 |
|----|------|
| **목적** | `NerdNavis.Framework`(UPM 패키지 `com.nerdnavis.framework`)의 **물리적 배포·참조 방식**을 결정 가능한 형태로 안건화한다 |
| **용도** | PD님 의사결정 1회로 OI-2 종결. 결정 후 Framework 레포 태그 정책 + Unity 프로젝트 참조 배선 + 신PC 셋업 절차가 일관되게 정의됨 |
| **범위** | 배포 방식(A/B/C + 하이브리드) 비교 · 권장안 · 선결 조건 · 후속 조치 · 열린 결정 항목 |
| **❌ 비목적** | ① **수상한 잡화점 투입 안건이 아님** — 수상한 잡화점은 본 프레임워크를 참조하지 않기로 기확정(PD님, 2026-04-15). 본 문서는 그 전제를 사용하지 않는다. ② 네임스페이스·릴리스 범위 등 타 OI 재결정이 아님. ③ Gitea 인프라 운영 정책 변경이 아님 |

---

## 1. 요약

**권장안**: **C안(UPM Git URL) + H1(로컬 file: 오버라이드)**. 태그 추적 기반 버전 고정. 근거 한 줄: 헌법 제1원칙 목표 1·2·3 세 축 모두에서 1위 또는 공동 1위이며, **추가 인프라 비용 없이** Tier 1 Core 4종의 현 Gitea push 상태와 최저 추가 작업으로 연결된다.

---

## 2. 판단 기준 (헌법 제1원칙 3대 목표 원문)

본 안건은 아래 3대 목표에 대한 정합성을 1차 기준으로 한다. 하위 핵심 규칙(C11·C14·C15 등)은 운영 규칙으로 부속 적용한다.

> **목표 1 — 코어 프레임워크의 PC 독립 최신화 유지**: 어느 PC에서 작업하든 항상 최신화된 너드나비스 조직의 자산으로 코어 코드 프레임워크를 유지·관리한다. 환경 이동·PC 추가·재기동 상황에서 프레임워크의 단일 최신 상태가 깨지지 않도록 구조를 설계·운영한다.
>
> **목표 2 — 차기 프로젝트부터 조직 자산으로 적극 활용**: 현행 수상한 잡화점 프로젝트는 코어 프레임워크를 활용하지 않는다. 다음 프로젝트부터 조직 자산으로 적극 도입하여, 범용성 높은 너드나비스만의 개발 노하우를 축적한다. 프레임워크는 "만들고 끝"이 아니라 "게임을 만들수록 쌓이는 자산"으로 운영한다.
>
> **목표 3 — 단기제작 가능한 유능한 게임 개발 스튜디오로의 발전**: 코어 프레임워크를 포함한 효율성 높은 개발 노하우를 지속 축적하여, 궁극적으로 어떤 게임이든 단기간 내 제작 가능한 유능한 스튜디오로 발전한다.

배포 방식이 3대 목표에 기여하는 관점:
- 목표 1 → **단일 최신 상태 유지·PC 독립 재현성**. 배포 방식이 PC별 경로·절대경로에 의존하지 않아야 함
- 목표 2 → **차기 프로젝트에서 한 번의 선언으로 도입 가능**해야 함. 도입 절차 길이가 곧 진입 장벽
- 목표 3 → **프로젝트를 거치며 버전이 누적**되는 구조. 릴리스 이력이 투명하고, 여러 프로젝트가 서로 다른 버전을 병행 사용할 수 있어야 함

---

## 3. 후보안 평가표

### 3.1 후보안 정의

| ID | 안 | 요약 |
|----|-----|------|
| A | 외부 경로 참조 | Unity 밖 고정 경로(`${FRAMEWORK_PKG_ROOT}`) 직접 참조 또는 `manifest.json`의 `file:` 절대경로 |
| B | Git 서브모듈 | Unity 레포 내 `.gitmodules` 로 Framework 레포 등록, Assets 또는 Packages 하위에 체크아웃 |
| C | UPM Git URL | `manifest.json` 의 `com.nerdnavis.framework` 항목을 Gitea URL(태그/커밋 고정)로 지정 |
| H1 | C + 로컬 file: 오버라이드 | 기본값은 C(원격 URL), Framework 동시 개발자만 로컬 `file:../NerdNavis.Framework` 로 덮어씀 |
| H2 | B + UPM 내부 참조 이중 | 서브모듈로 가져오되 manifest는 `file:` 로컬 참조. Git 이력 B + Unity 참조 C 장점 차용 시도 |
| S1 | 사내 Scoped Registry | Verdaccio 등 npm 호환 레지스트리 구축, UPM `scopedRegistries` 등록. tarball 배포 |

### 3.2 목표별 점수 (◎ 우수 · ○ 보통 · △ 열위 · ✕ 부적합)

| 안 | 목표 1 PC 독립 최신화 | 목표 2 차기 프로젝트 자산 활용 | 목표 3 누적 자산·단기제작 | 종합 |
|----|------|------|------|------|
| **A 외부경로** | ✕ PC별 절대경로 어긋남 상존. "내 PC에선 된다" 재현 | △ 차기 프로젝트 도입 시마다 경로 합의 필요 | △ 버전 개념이 파일 시스템에 의존 | **✕** |
| **B 서브모듈** | ○ clone으로 재현 가능하나 sub-commit 업데이트 누락 리스크 | ○ 프로젝트마다 서브모듈 등록 필요, 학습비 중 | ○ Git 이력은 풍부하나 버전 전환은 수동 | **○** |
| **C UPM Git URL** | ◎ Unity 표준, clone 직후 Package Manager가 자동 fetch·캐시 | ◎ 차기 프로젝트 `manifest.json` 한 줄 추가로 도입 | ◎ 태그 기반 semver 누적, 프로젝트별 버전 고정 병행 가능 | **◎** |
| **H1 C+로컬오버라이드** | ◎ 기본값은 원격 태그, 로컬 오버라이드는 명시적 수동 조작 | ◎ C와 동일 | ◎ 기본은 C와 동일하되 Framework 동시 개발 Inner Loop 단축 → 목표 3 효율성 가산 | **◎+** |
| **H2 서브모듈+file:** | △ 이중 관리로 "최신 상태"의 정의 흔들림 | △ 타 프로젝트에 이 이중 구조를 강요하게 됨 | △ 이력은 풍부하나 단기제작 지향과 상충 | **△** |
| **S1 Scoped Registry** | ◎ tarball 캐시로 최상. 단 레지스트리 인프라 선결 | ◎ 장래 복수 프로젝트·복수 패키지 확장 시 최적 | ◎ 정식 패키지 배포 경로. 단 현시점 비용 초과 | **◎ (선결 조건 충족 전엔 보류)** |

운영 규칙 관점(C11·C14): C/H1이 참조 경로 단일성과 팀 학습비 최소화 양면에서 우세. A는 `paths.local.json`·junction 3축 검증 부담을 Framework까지 확대시켜 C16·신PC 체크리스트 v2와 역행.

---

## 4. 권장안 상세 (C + H1)

### 4.1 구조
- **원격 SOT**: Gitea `NerdNavis/NerdNavis.Framework` 레포. 태그는 semver (`v0.x.y`, v0 개발판 허용)
- **Unity 참조**: 차기 프로젝트 `Packages/manifest.json` 에 다음 한 줄 추가 형태
  - `"com.nerdnavis.framework": "https://burning.i234.me/NerdNavis/NerdNavis.Framework.git#v0.x.y"`
- **로컬 오버라이드(H1)**: Framework 동시 개발자는 로컬에서만 `file:../../NerdNavis.Framework` 로 대체. 커밋 대상이 아님 (`.gitignore` 또는 `manifest.local.json` 패턴 중 택1)

### 4.2 초기 셋업 (현 Tier 1 Core 4종 기준)
1. Framework 레포에 **v0.1.0 태그** 부여 (Log·CoroutineRunner·MonoSingleton·ServiceLocator 기반)
2. 태그 푸시 후 Gitea에서 릴리스 노트 초안 자동 생성 확인
3. 신PC 셋업 체크리스트 v2에 **UPM 인증 절차** append (Git credential helper 또는 PAT URL)

### 4.3 버전 관리 정책
- **태그 정책**: semver. breaking change → minor (v0.x) / patch (v0.0.x)
- **프로젝트별 고정**: 프로젝트는 태그 또는 커밋 SHA 고정. 브랜치(`#main`) 추적은 금지 (목표 1 재현성 보장)
- **갱신 절차**: Framework 릴리스 → 사용 프로젝트가 `manifest.json` 의 ref 만 갱신 → 커밋

### 4.4 다음 프로젝트 도입 절차 (목표 2·3 구현)
1. 신규 Unity 프로젝트 생성 시 `Packages/manifest.json` 템플릿에 위 한 줄 동봉
2. Framework가 제공하는 asmdef·samples는 UPM 표준으로 자동 노출
3. 프로젝트가 필요로 하는 확장은 **Framework 본체에 PR**로 역제안 → 조직 자산 축적

### 4.5 리스크 · 완화
| 리스크 | 완화 |
|-------|------|
| Gitea private 인증 (PAT 주입) | Windows Credential Manager 자동 캐싱(현 NerdNavisAi push 실증). 체크리스트 v2에 명시 |
| 태그 미지정·브랜치 추적 오남용 | manifest.json 리뷰 체크항목 신설, CI에서 ref 패턴 검증 |
| 레포 공개 범위 변경(가령 외부 스튜디오 협업) | URL만 교체. Scoped Registry(S1) 승격 경로 보존 |
| 로컬 file: 오버라이드가 커밋에 섞여 들어감 | `manifest.local.json` 분리 패턴 채택 검토 (선결 조건) |

---

## 5. 대안 요약

- **차선 (선결 조건 충족 시 승격)**: **S1 사내 Scoped Registry**. 목표 3 장기 축적에서 C와 동등 이상. 단 Verdaccio 운영·백업·인증 연동이 선결. 현시점 즉시 채택은 비용 초과
- **기각**: A 외부경로 — 목표 1 PC 독립성과 정면 충돌. B 단독 — Assets 내부 meta/GUID 경계 리스크. H2 — 이중 관리 비용 대비 이득 불명확

---

## 6. 후속 작업 목록 (선결 조건 충족 시 순차 착수)

| # | 항목 | 담당 | 선결 조건 |
|---|------|------|----------|
| F1 | Framework 레포 v0.1.0 태그 부여 + 릴리스 노트 초안 | 개발실장 | PD님 권장안 승인 |
| F2 | `manifest.local.json` 분리 패턴 PoC | 클라이언트팀장 + DevOps | F1 |
| F3 | 신PC 체크리스트 v2에 UPM 인증 절차 append | 총괄PM | F1 |
| F4 | 06 설계안 §2.4·§7 OI-2 상태 `🟡 협의 중` → `✅ 결정` 갱신 | 개발실장 | PD님 결정 반영 직후 |
| F5 | 차기 프로젝트 `Packages/manifest.json` 템플릿화 | 클라이언트팀장 | F1, 차기 프로젝트 착수 시점 |

(일정·기한 표현은 C15에 따라 사용하지 않음. 각 항목은 선결 조건 충족 시 착수)

---

## 7. 열린 의사결정 항목 (PD님 결정 요청)

| 항목 | 선택지 | 개발실 권장 |
|------|--------|-----------|
| 1. 기본 배포 방식 | A / B / **C** / H1 / H2 / S1 | **C + H1** |
| 2. 버전 고정 방식 | 브랜치 추적(`#main`) / **태그(`#v0.x.y`)** / 커밋 SHA | **태그 추적** |
| 3. 로컬 개발자 `file:` 오버라이드 허용 여부 | 허용(문서화 조건) / 금지 | **허용** |
| 4. Scoped Registry(S1) 승격 경로 | 지금 구축 / **장래 과제 보류** / 불필요 | **장래 과제 보류** |

> **C19 준수 명시**: 본 문서는 안건 제시까지이며, PD님 승인 없이 되돌리기 어려운 액션(태그 부여·`manifest.json` 병합 등)은 수행하지 않는다. 승인 범위는 위 4개 항목에 한정된다.

---

## 8. 변경 이력

- **v1 (2026-04-15, 재작성)**: 헌법 제1원칙 3대 목표 기반 평가표로 재구성. 4축 섹션(목적·용도·범위·비목적) 상단 추가. OI-5 폐기 반영(수상한 잡화점 투입 전제 삭제). C18·C19 준수 명시. 권장안: C + H1 + 태그 추적 + S1 장래 보류.