← 자료실/designsLOW

FlatBuffer 중간 레이어 설계 (정현우 + 차도윤 + 한가영 D+14 3자 합의)

designs/flatbuffer_intermediate_layer_2026-05-18.md

FlatBuffer 중간 레이어 설계 (정현우 + 차도윤 + 한가영 D+14 3자 합의)

작성: 2026-05-04 (정현우 code-lead leading) · 차도윤 + 한가영 페르소나 인용 버전: v0.2 갱신 (2026-05-04 PD default 채택으로 옵션 B Self-build 잠금 / 외주 옵션 폐기 / D+14 3자 합의는 잔존) 상위 참조: project_v3_0_redesign_decisions.md #3 DB 통합 + project_flatbuffer_self_build_decision_2026-05-04.md (B 잠금 source) · designs/web-platform/v2_0_redesign_web_tech.md §4 모노레포 / §5 통합 인터페이스 #3 / §6 (FlatBuffer 빌드 산출 → Unity·Web 동시 임베드) · project_sprint01_w1_results.md (200F 4.255 baseline / 0.12% 편차) 범위: Datasheets/TSV → FlatBuffer → Unity SO + Phaser JSON 3 layer 빌드 파이프라인 1쪽 v0.1 → v0.2 변경: §1 TL;DR + §6 옵션 비교 → 결정 표 + §8 다음 액션 + §10 정현우 PoC 자체 검증 슬롯 추가

1. TL;DR (3줄)

  1. FlatBuffer 중간 레이어 = Datasheets/TSV → .fbs 스키마 → Unity SO export + Phaser JSON export 3 layer 빌드 파이프라인 — packages/shared/schema.fbs 단일 source / Unity·Web 동시 임베드 / sync 0 cost
  2. 3자 영역 분리 — 정현우 (Unity SO importer + TsvReader 통합) / 차도윤 (Phaser JSON 임베드 + 모노레포 packages/shared 갱신) / 한가영 (200F 4.255 baseline 회귀 검증 + 0 편차 원칙)
  3. 외주 ~40h 발주 시점 = 정현우 5/15 회신 — 자체 평가 후 Self-build 헷지 (정현우 + 차도윤 ~80h) 옵션 동시 평가. D+14 3자 합의 후 PD 결정

2. v3.0 #3 DB 통합 결정 인용

project_v3_0_redesign_decisions.md #3:

하이브리드 (Firestore=게임 진실 / Supabase=웹 메타·UGC·결제 / FlatBuffer=Datasheets/TSV → Unity·Web 동시 임베드)

근거 인용 — 김민준 권장 / 박세린 v1.1 §1 분리 정합 / Unity Phase 5 무재작업.

본 문서는 FlatBuffer layer 의 빌드 파이프라인·영역 분리·외주 발주 시점 3자 합의를 다룬다. Firestore / Supabase 영역은 차도윤 + 김민준 별도 합의 (본 문서 범위 밖).

3. FlatBuffer 선택 이유 3건

후보빌드 검증Unity 호환Web 호환스키마 진화평가
Cap'n ProtoA (capnp 컴파일)B (Unity binding 미성숙)A (capnp-ts)A비추 (Unity 약점)
ProtobufA (protoc)A (protobuf-net)A (protobuf.js)A보류 (런타임 reflection 약점)
FlatBuffer ★A (flatc)A (Google C# binding 검증)A (flatbuffers JS)A (forward/backward)채택
JSON 직접C (스키마 검증 0)AAC비추 (검증 없음)
MessagePackB (스키마 옵션)BAB비추 (Unity 약점)

FlatBuffer 채택 3 사유:

  1. 빌드 타임 검증 — flatc 컴파일러가 .fbs 스키마 위반 즉시 빌드 실패 → 한가영 0 편차 원칙 sync
  2. Unity·Web 동시 호환 — Google C# binding (FlatBuffers.dll) + flatbuffers JS 양 클라 1급 지원
  3. zero-copy parsing — Unity 런타임 메모리 부담 0 (정현우 라이브 안정성 원칙) / Phaser 임베드 시 초기 parse 비용 0

차도윤 발화 가정 인용: "도윤입니다. flatbuffers JS 패키지 검증했고 모노레포 packages/shared 에 .fbs 단일 source 박을 수 있습니다. Phaser asset preload 시 binary 1회 fetch + zero-copy 로 60fps 영향 0. 임재훈 부하 테스트 통과 가정."

4. 빌드 파이프라인 3 layer

[Layer 1] Datasheets/*.tsv (윤서아 시트 single source)
              |
              | TsvReader (정현우 + 김민준 공동 소유, Sp02 이월)
              v
[Layer 2] packages/shared/schema.fbs (FlatBuffer 스키마)
              |
              | flatc 컴파일러
              | (CI/CD GitHub Actions 자동)
              v
[Layer 3a] Unity SO export (정현우)         [Layer 3b] Phaser JSON export (차도윤)
              |                                       |
              v                                       v
   Unity6/Assets/.../GeneratedSO/.asset       webgame/public/data/*.bin
              |                                       |
              v                                       v
   AddressablesGroup (라이브 핫픽스)         Phaser asset preload (Vite manifest)

한가영 검증 라인 (Layer 2 → Layer 3 사이):

5. 3자 영역 분리

영역정현우차도윤한가영비고
Datasheets/*.tsv 작성———윤서아 단일 source (한가영 흡수만)
packages/shared/schema.fbs 작성⭐ leading⭐ co-owner—모노레포 공동 소유 (김민준 패턴)
flatc 컴파일러 CI/CD 통합⭐——정현우 GitHub Actions 영역
TsvReader → FlatBuffer 변환⭐——Sp02 이월 TsvReader 활용
Unity SO export (Layer 3a)⭐——Sp01 W2 Importer baseline 보존
Phaser JSON 임베드 (Layer 3b)—⭐—Vite manifest 통합
200F 4.255 baseline 회귀——⭐주 1회 자동 검증
0 편차 원칙 검증 (Unity ↔ Phaser binary diff)——⭐편차 0.5% 초과 시 빌드 실패
모노레포 packages/shared 갱신—⭐—김민준 1:1 합의 의무
충돌 시박세린(PM) 중재 → PD

한가영 발화 가정 인용: "가영입니다. 200F 4.255 / 0.12% 편차 baseline (project_sprint01_w1_results.md W1-04) 절대 보존 원칙입니다. Layer 3a Unity binary 와 Layer 3b Phaser binary 의 affix_pool 35건 / prestige_items 30항목 / transcendent_milestone 22건 100% 동일 검증. 편차 0.5% 초과 시 즉시 차도윤 + 윤서아 보고 + 빌드 실패 처리."

6. 외주 ~40h 발주 시점 vs Self-build 헷지

옵션 A — 외주 ~40h 발주 (직전 정현우 회신 = 2026-05-15)

항목내역
작업 범위flatc 컴파일러 CI/CD 통합 + TsvReader → fbs 자동 변환 + Unity·Phaser dual export 보일러플레이트
외주 비용~40h × 시간당 비용 = 별도 PD 결정
장점정현우 본업 (Sp01 W2 Importer 마무리 + Sp02 재개) 간섭 0 / 차도윤 Sp-W01 킥오프 5/18 간섭 0
단점외주 검수 부담 + 한가영 0 편차 원칙 검증 외주 인계 부담
발주 시점5/15 정현우 회신 — D+14 3자 합의 (5/18) 직전 PD 결정

옵션 B — Self-build (정현우 + 차도윤 ~80h)

항목내역
작업 범위정현우 ~50h (CI/CD + Unity export) + 차도윤 ~30h (Phaser 임베드 + 모노레포 통합)
일정Sp-W01 (5/18~5/31) 14h + Sp-W02 (6/1~6/14) 14h × 2주 정현우 분산
장점외주 검수 0 / 한가영 검증 라인 인하우스 / 향후 유지보수 용이
단점정현우 Sp02 재개 (9/15) 일정 1~2주 지연 위험 / 차도윤 Sp-W01~W02 30h 추가
발주 시점D+14 (5/18) 합의 후 즉시

정현우 권장: 본인 의견은 옵션 B (Self-build) 약간 우세. 사유 — 한가영 0 편차 원칙 검증 라인이 외주 인계 가능 단계가 아님 + 모노레포 packages/shared 가 김민준·차도윤 공동 소유라 외주 갱신 권한 모호. 단 PD 결정 우선.

7. 위험 가정 2건

  1. flatc 컴파일러 GitHub Actions 통합 미검증 → 헷지: D+14 합의 전 정현우 PoC 1h (5/12~5/14) — flatc Linux binary CI 실행 + Unity Editor batch mode 호출 검증. 실패 시 Protobuf 차선 검토
  2. 한가영 0 편차 원칙 검증 자동화 도구 부재 → 헷지: Sp-W01 W2 (5/25 한가영 첫 발주) 시 차도윤 + 한가영 1:1 — Unity binary ↔ Phaser binary diff 도구 (tools/balance/diff_binary.ts) 자체 PoC 4h. 미완 시 수동 diff 1주 운영 + Sp-W02 자동화

8. 다음 액션

9. 분업 인계 사항