프로토타입 → 정본 이식 계약

<!-- 프로토타입 → 정본 이식 계약 v0.1 · https://namtank96.github.io/assets/a14-porting-contract -->

# 이식 계약 (Porting Contract)

데모·프로토타입을 정본에 합류시킬 때 **재작업이 0이 되도록 미리 못박는 계약.**

목적: 정본이 완성되기 전에 데모를 "이식 준비 완료" 상태로 만든다.
이 계약을 지키면 합류가 **기계 작업 2~3단계**로 끝난다. 안 지키면 데모를 통째로 다시 쓴다.

## 왜 필요한가

데모는 빨리 만들려고 정본과 다르게 짓는다. 그리고 통과하면 "이거 그대로 붙이면 되죠?" 소리를 듣는다.
그 시점에 이름이 다르고, 구조가 다르고, 색이 달라서 결국 다시 쓴다.
**계약은 데모를 만들기 전에, 늦어도 데모 v0.1 직후에 쓴다.** 다 만들고 나서 쓰면 회고에 그친다.

---

## 1. 교체 가능 경계

정본이 들어올 자리를 **함수·모듈 하나 안쪽으로 전부 몰아넣는다.**
그 밖은 정본이 나와도 불변임을 명시한다.

```
교체 대상 : {함수·컴포넌트 이름} 내부 전부
불변 영역 : {엔진·상태관리} / {네비게이션} / {좌측 화면} / {동기화 로직}
```

→ 이식할 때 **교체 대상 내부만 정본으로 갈아끼운다. 경계 밖 재작업 0.**

경계를 못 그으면 계약이 성립하지 않는다. 이 절이 안 써지면 데모 구조를 먼저 고친다.

## 2. 배선 계약

정본에 합류할 때 **손대야 하는 지점을 미리 전부 센다.** 하나라도 빠지면 조용히 안 뜬다.

| # | 계약 | 왜 |
|---|---|---|
| ① | `{함수}` 에 {N}번째 분기 추가 (기존 분기 뒤에 조건부로) | 이게 실제 드롭인 여부의 판정 기준 |
| ② | `{enum}` 을 **{N}곳 전부**에 동시 추가 (`{목록}`) | **한 곳만 넣으면 표출되지 않는다** |
| ③ | `{하드코딩 배열}` 에 값 추가 (@{위치} + @{섀도 사본 위치}) | 사본이 따로 있으면 둘 다 고쳐야 한다 |
| ④ | 해소 플래그 되쓰기 (`{플래그}` 를 루트에서 존중) | 없으면 확정한 건이 다음 실행에 되살아난다 |

**②와 ③이 이 절의 핵심이다.** 같은 값을 여러 곳에서 읽는 구조는 데모에서는 안 보이다가
정본에서 터진다. 몇 곳인지 세어서 숫자로 적는다.

## 3. 데이터 계약

데모가 자체 데이터를 들고 있어도 **필드명은 정본 그대로 쓴다.**

```
{ id, {필드}, {필드}, …            // 정본 기존 필드 — 이름 변경 ✕
  {신규필드1}: {…},                 // 이식 시 정본에 추가될 것
  {신규필드2}: {…} }
```

- 정본이 읽는 구조를 유지하면 **이전 시 필드명 변경이 0**이다.
- **신규 필드는 몇 개인지 명시한다.** 정본 담당이 추가해야 할 목록이 그것뿐임을 보장한다.
- 데모용 가짜 데이터에 **실명·실제 고객 정보를 넣지 않는다.** 데모는 돌아다닌다.

## 4. 토큰·클래스 일치

데모의 스타일을 정본과 **동일하게** 쓴다. 매핑이 아니라 붙여넣기가 되게.

- 토큰: 정본 `:root` 를 그대로 복사한다. 이름을 바꾸지 않는다.
- 클래스명: 정본 클래스를 그대로 쓴다. `demo-` 접두를 붙이지 않는다.
- 새 클래스가 필요하면 **계약서에 신규 목록으로 적는다.** 정본에 추가될 것들이다.

이름이 다르면 이식이 "스타일 다시 맞추기"가 되고, 그 작업은 항상 예상보다 오래 걸린다.

---

## 계약서 머리말 (고정)

```markdown
# {데모} ↔ {정본} 이식 계약 (SSOT)

목적: {정본} 완성 전에 {데모}를 "이식 준비 완료" 상태로 만든다.
      이 계약을 지키면 합류가 {N}단계 기계 작업으로 끝난다.

현황: {데모 현재 버전과 검증 상태} · {정본 현재 상태} · {건드리지 않은 정본 파일}
```

**현황 줄에 "정본 미편집"을 명시한다.** 데모 세션이 정본을 건드리는 순간 이 계약은 무효가 된다.

## 금칙

- 데모를 다 만든 뒤에 계약 쓰기
- 경계를 "대충 이 부분"으로 적기. 함수·파일 이름으로 적는다
- 배선 지점을 "여러 곳"으로 적기. **숫자로 센다**
- 데모용 접두사·별칭 도입
- 데모 데이터에 실명 넣기
- 계약 없이 "나중에 붙이면 됩니다"라고 말하기