# BEX ↔ 개발 세션(`Setting Up Development Environment`) 통합 정리 및 엔지니어링 핸드오프 명세서

> **작성일:** 2026-10-21  
> **작성 주체:** BEX (벡스 — Bimer EXecutive · 무인 회사 운영·행정·마케팅·영업 총괄 에이전트)  
> **수신 주체:** `"Setting Up Development Environment"` (코어 엔진 · UI · 백엔드/엣지 함수 개발 세션)  
> **무인 회사 거버넌스 원칙:** **대표님(Human Founder)은 오직 방향성 제시와 최종 결재 권한(본인인증 OTP 승인·고액 딜 최종 컨펌)만 행사**하며, 기술 스택 선정·회원가입·DB·결제 파이프라인·일상 운영·행정 최적화는 에이전트(BEX + 개발 세션)가 대표님의 수동 개입이 0분이 되도록 설계·집행한다.

---

## 1. `"Setting Up Development Environment"` 세션 전달 사항 인수 및 BEX 반영 완료 내역

개발 세션에서 2026-10-20 ~ 2026-10-21 동안 구현·검증 완료하여 BEX에 전달한 **3대 마일스톤**을 모두 인수하고 마케팅·영업 엔진(`src/sales/SalesAgentCore.ts`, `cli/sales-agent.mjs`, `docs/bex-marketing-plan.html`)에 100% 동기화했습니다.

### 1.1 [완료] BEX 5대 현업 가치 필러 (`VOC-1` ~ `VOC-5`) 100% 구현 완료 (`2026-10-20`)
- **`VOC-1` (조달청/KBIMS 표준 속성 프리셋 & 단품 IFC4 내보내기):**
  - `src/family/bimPresets.ts`, `src/io/ComponentIfcExport.ts`, `src/host/schedule/scheduleEngine.ts`
  - 전 패밀리 조달청/KBIMS 분류코드·재질·단위·내화등급 메타데이터 탑재, Studio 단품 `.ifc` 내보내기(`EXPORTIFC` / `data-testid="studio-export-ifc"`), Bimer Host 컴포넌트 일람표(`data-testid="schedule-components"`) 완료.
- **`VOC-2` (파라미터 Min~Max 안전 가드레일 & 1-Click Flex 무결성 검증):**
  - `src/family/types.ts`, `src/family/FamilyManager.ts`, `src/ui/BimReliabilityBar.ts`
  - 파라미터별 `min`~`max` 범위 클램핑 및 Studio 상단 `🔍 Flex 검증`(`FLEXVERIFY` / `data-testid="studio-verify-flex"`) 3단계 자동 스윕 검증 완료.
- **`VOC-3` (실시간 메쉬 경량성 지표 — Triangles · KB · LOD 200/300 배지):**
  - `src/ui/BimReliabilityBar.ts`, `src/host/ui/hostApp.ts`
  - Studio 및 Host 하단 상태바에 실시간 삼각형 개수·예상 용량(KB)·LOD 등급 표시 완료.
- **`VOC-4` (창호/문 `WallThickness` 벽 두께 자동 동기화 & MEP 37종 3D 커넥터 포트):**
  - `src/host/model/hostModel.ts`, `src/family/bimPresets.ts`
  - 14종 문/창호 패밀리 `WallThickness` 호스트 벽 두께 자동 연동 및 37종 MEP 패밀리 `HVAC`/`Piping`/`Electrical` 3D 커넥터 포트 기즈모 표시 완료.
- **`VOC-5` (2D CAD `.dxf`/`.dwg` 단면 → Studio 3D 돌출 & 평면도 → Host 3D 벽체 변환):**
  - `src/io/CadSectionImport.ts`, `src/host/cad/hostCadImporter.ts`
  - Studio `📐 CAD 단면`(`IMPORTCAD` / `data-testid="studio-import-cad"`) 및 Host `📐 CAD 평면도`(`data-testid="btn-import-cad"`) 원클릭 변환 완료.

### 1.2 [완료] `https://bimer.uk` 6대 워크스페이스 단일 도메인 통합 & Sample-First 퍼널 (`2026-10-21`)
- `public/portal.html`, `cli/deploy-unified-bimer.mjs`
- 단일 도메인(`https://bimer.uk`) 아래 6대 워크스페이스 통합:
  1. `/` — 통합 포털 (직군별 Sample-First 1-Click 런처 + `.dwg`/`.dxf`/`.ifc` 스마트 파일 라우터)
  2. `/host.html` (`/host/`) — Bimer 웹 BIM 호스트
  3. `/studio.html` (`/studio/`, `https://parastudio.bimer.uk`) — Parametric Studio 3D 컴포넌트 에디터
  4. `/pure-cad/` (`/cad/`) — Pure-CAD 2D 도면 편집기
  5. `/dwg-viewer.html` & `/dwg-viewer-3d.html` — DWG 2D/3D 뷰어
  6. `/bim/` — WASM 초고속 메쉬 단면 슬라이서

### 1.3 [완료] 건기연 빅데이터 플랫폼 라이선스 감사 & 4대 토목 분야 20종 클린룸 마스터 패키지 (`2026-10-21`)
- 건기연 플랫폼(`bigdata-eng.com`) 정적 파일(266개)의 이용약관 제17조(비영리 이용 제한) 리스크를 원천 배제하고, **KDS/KCS·KS·국토부·해수부·국가철도공단 공공 표준 치수표(사실 데이터)**에 기반한 **100% 상업용 클린룸 파라메트릭 패밀리 20종** 신규 구축 완료:
  - **01. 도로·교량·터널 (6종):** `IFC-B10` 사장교 H형 주탑, `IFC-B11` 강박스 거더, `IFC-B12` RC 라멘교, `IFC-T01` NATM 마제형 터널, `IFC-T02` 터널 표준 갱문(벨마우스), `IFC-R07` 도로 문형 표지판
  - **02. 항만·해양 (6종):** `IFC-M03` 테트라포드(8t~100t), `IFC-M04` 멀티격실 케이슨(6/8/12격실), `IFC-M05` 계선주(35t~100t), `IFC-M06` 셀형 고무 방충재, `IFC-M07` 방파제 상치 파라펫, `IFC-M08` 부두 차막이
  - **03. 철도·궤도 (4종):** `IFC-S03` 한국철도 표준 레일(50kgN/60kg/60kgK), `IFC-S04` 전차선 강관주 & 가동브래킷, `IFC-S05` 철도교 PSC 박스 거더, `IFC-S06` 고속철도 콘크리트 도상 궤도
  - **04. 상하수도·관망 (4종):** `IFC-W01` KS 조립식 원형 맨홀(1~5호), `IFC-W02` KS 원심력 흄관(D400~D1200), `IFC-W03` 조립식 PC 박스 암거(헌치형), `IFC-W04` 상수도 제수밸브실 챔버
- **최종 카탈로그 규모:** 총 **225종 패밀리** (`builtin` 167 + `infra` 53 + `tutorial` 5), **498개 표준 타입 프리셋**.

---

## 2. 차기 개발 세션(`"Setting Up Development Environment"`) 구현 요청 백로그 (`DEV-1` ~ `DEV-5`)

> **사용법:** 개발 세션에서 아래 항목 중 구현할 타겟(예: `"docs/bex-dev-handoff.md 의 DEV-1, DEV-4 구현해줘"`)을 지시하면 즉시 실행 검증 가능한 계약(Contract) 형태로 작성되었습니다.

### `DEV-1` [완료 · 2026-10-21] 서버리스 중앙 고객 니즈(VOC) & 리드 수집 API 연동
- **배경 (고객/마케팅 병목):**
  - 기존 `family-catalog.html`(`bex_voc_needs_v1`), `bex-marketing-plan.html`(`bex_leads_v1`), `pricing.html`에서 고객이 남긴 패밀리 제작 신청 및 실무 기능 제안이 방문자 브라우저 `localStorage`에만 저장되던 병목 해결.
- **구현 완료 내역 (`loop/dev1-central-voc-leads/`):**
  1. Cloudflare Pages Functions (`functions/api/voc.ts`, `functions/api/leads.ts`) 및 `cli/sales-agent.mjs` 엔드포인트 구축:
     - `POST /api/voc` & `GET /api/voc` — 카탈로그 니즈 하베스터 및 무료 맞춤 패밀리 신청 데이터를 Cloudflare D1 (`env.DB` → `bex_voc` 테이블)에 영구 저장하며, D1 미바인딩 환경에서는 Edge Cache(`caches.default`)/메모리로 자동 폴백 + `BEX_WEBHOOK_URL`/`SLACK_WEBHOOK_URL`/`DISCORD_WEBHOOK_URL` 설정 시 실시간 Webhook 알림 발송.
     - `POST /api/leads` & `GET /api/leads` — BEX 라이브 콘솔 리드 및 Bimer 얼리액세스 대기자를 Cloudflare D1 (`env.DB` → `bex_leads` 테이블) 및 폴백 캐시에 저장 + Webhook 알림 발송.
  2. 클라이언트 3대 페이지 연동 (`public/pricing.html`, `docs/bex-marketing-plan.html`, `samples/families/build-catalog-html.ts` → `docs/family-catalog.html`):
     - 폼 제출 시 `localStorage` 즉각 반영과 동시에 `fetch('/api/voc', { method: 'POST', ... })` / `fetch('/api/leads', { method: 'POST', ... })` 비동기 전송.
     - `bex-marketing-plan.html` 로드 및 `🔄 중앙 서버 동기화` 클릭 시 `GET /api/voc` 및 `GET /api/leads`로 중앙 수집 데이터를 가져와 대시보드에 자동 병합 표시.
- **완료 검증 결과:**
  - `loop/dev1-central-voc-leads/tests.mjs` (D1 + Edge Cache 폴백 + Webhook 단위 검증) 및 `loop/dev1-central-voc-leads/e2e.mjs` (실제 브라우저 `family-catalog.html`, `pricing.html`, `bex-marketing-plan.html` 네트워크 POST/GET + `localStorage` 동기화 E2E) **100% PASS**.

---

### `DEV-2` [상용화 준비 · 회원가입/인증] 초경량 패스워드리스 로그인 & 일일 무료 AI 쿼터/라이선스 게이트
- **배경 (수익화/비용 방어 니즈):**
  - Bottleneck Labs 실험의 교훈처럼 유료 LLM(`AIDESIGN`) API 원가가 폭발하지 않도록 **비로그인 방문자는 일 3회 무료 체험**, **로그인(무료 베타 회원)은 일 10회**, **향후 Pro 구독자(`bimer_pro_license`)는 월 150회 + 상업용 일괄 Export 해금** 구조가 필요합니다.
- **구현 스펙:**
  1. `src/auth/BimerAuthManager.ts` (신규):
     - 무설정 로컬/베타 모드에서는 이메일 입력만으로 즉시 무료 베타 패스(`bimer_user_session`)를 발급하고, 환경변수(`VITE_SUPABASE_URL` 또는 `/api/auth/magic-link`) 설정 시 실제 이메일 매직링크/소셜 로그인과 연동되는 어댑터 패턴 구현.
     - `getQuotaStatus()` / `consumeAiCredit()` / `activateLicenseKey(key)` API 제공.
  2. UI 연동:
     - Studio 상단 타이틀바 우측에 컴팩트한 `[👤 무료 베타 로그인 · AI 3/3]` 배지 및 모달 제공 (3D 조회·파라메트릭 Flex·단품 테스트는 로그인 없이 100% 영구 무료 유지).
- **완료 검증 기준 (Acceptance):**
  - 비로그인 상태에서 3D 모델링/Flex는 무제한 작동하고, `AIDESIGN` 호출 시 쿼터 카운트 차감 및 라이선스 키 입력 시 Pro 상태 전환 단위/E2E 테스트 통과.

---

### `DEV-3` [상용화 준비 · 결제] 토스페이먼츠(Toss Payments) 서버 승인 엔드포인트 & 라이선스 자동 발급기
- **배경 (결제 연동 니즈):**
  - `public/pricing.html`에 클라이언트 결제창 호출 코드는 준비되어 있으나, 토스페이먼츠 정식 결제는 클라이언트 리다이렉트(`?paymentKey=...&orderId=...&amount=...`) 직후 **서버에서 시크릿 키(`TOSS_SECRET_KEY`)로 승인 API(`https://api.tosspayments.com/v1/payments/confirm`)를 호출**해야 실제 결제가 확정됩니다.
- **구현 스펙:**
  1. `functions/api/payment/confirm.ts` (Cloudflare Pages Function):
     - `POST /api/payment/confirm` 요청 수신 → `amount` 위변조 검증(Tier 1: `39000`, Tier 2: `99000` / `690000`) → 토스페이먼츠 승인 API 호출 → 성공 시 서명된 Pro 라이선스 토큰 발급 및 반환.
  2. `public/pricing.html` 결제 성공 콜백 연동:
     - URL에 `paymentKey`, `orderId`, `amount` 쿼리가 감지되면 자동으로 `/api/payment/confirm`을 호출하고 발급받은 라이선스를 활성화.
- **완료 검증 기준 (Acceptance):**
  - Mock/Test 키 환경에서 결제 승인 플로우(`paymentKey` → `/api/payment/confirm` → 라이선스 활성화) 단위 테스트 통과.

---

### `DEV-4` [현업 실무 가치 2차 웨이브] 엔지니어 현장 피드백 기반 추가 기능 (`VOC-6` ~ `VOC-8`)

| 코드 | 현업 엔지니어 추가 요구사항 (BEX 수집) | 구현 대상 레이어 및 상세 스펙 |
|---|---|---|
| **`VOC-6`** | **"토목·구조 부재(라멘교·암거·맨홀·H형강)의 콘크리트 체적($m^3$)과 강재 중량($\text{kg}$)을 바로 알고 싶다"** | • `src/ui/BimReliabilityBar.ts` & `src/host/schedule/scheduleEngine.ts`<br/>• 현재 메쉬의 닫힌 솔리드 체적(Signed Volume)을 계산하여 재질이 콘크리트(`Concrete*`)면 **체적($m^3$) 및 추정 철근량**, 강재(`Steel*`)면 **중량($\text{kg}$, 비중 $7.85\text{ t/m}^3$)**을 Studio 상태바와 Host 컴포넌트 일람표/IFC `Pset_QuantityTakeOff`에 자동 산출 |
| **`VOC-7`** | **"내가 방금 맞춘 치수(예: B=450, H=4200) 그대로 동료에게 카톡/슬랙으로 보낼 '1-Click 딥링크 복사' 버튼이 에디터 안에 있으면 좋겠다"** | • `src/main.ts` / `src/ui/BimReliabilityBar.ts`<br/>• Studio 상단 바에 `🔗 현재 규격 링크 복사`(`data-testid="studio-copy-deeplink"`) 버튼 추가 → 현재 로드된 샘플 ID + 활성 타입 + 변경된 파라미터(`?sample=...&type=...&set=B:450,H:4200`) URL을 클립보드에 즉시 복사 |
| **`VOC-8`** | **"스케치 구속조건 치수에도 파라미터(`{ref}`)를 바인딩하고, 3D 뷰포트에서 스케치 선을 직접 클릭해 돌출(`EXT`)하고 싶다"** | • `GEMINI.md` §9.4 오픈 갭 해결<br/>• `syncBodiesFromGraph`에서 커밋된 `sketch` 노드의 와이어프레임 라인을 3D 뷰포트에 렌더링하여 클릭 피킹 허용 + `SketchConstraint.value`에 파라미터 이름/수식 바인딩 지원 |

---

### `DEV-5` [✅ 구현 및 영상 재촬영 완료] 3D 뷰포트 Skybox 배경 탑재 & 부재 가장자리 까맣게 타는 현상(GTAO · Shadow · Grid Bleed) 수정 (`VOC-9`)

- **상태**: **✅ 완료 (`2026-10-22` · `loop/dev5-viewport-skybox-ao/e2e.mjs` `4/4 PASS`, `ep01`·`ep02` 전체 세그먼트 재촬영 및 `bimer.uk` 라이브 배포 완료)**

- **배경 (대표님 유튜브 시연 영상 검수 피드백 · `2026-10-21`):**
  - 대표님께서 유튜브 시연 영상(`ep01-bimer-fullstack-masterclass.mp4` — `seg-05.png`, `seg-12.png`, `seg-16.png`)을 직접 검수하신 결과, 다음 **4가지 치명적인 3D 뷰포트 시각 결함**이 확인되었습니다:
    1. **부재 가장자리·모서리가 까맣게 탄 것처럼 얼룩지는 현상 (GTAO Millimeter Scale Mismatch):**
       - `src/view/ModelViewer3D.ts` (L489–493): `GTAOPass`가 기본 파라미터(`radius = 0.25`, 미터 단위 씬 기준) 그대로 추가되어 있고 `camera.near = 0.01`, `camera.far = 10000` (OrbitControls `maxDistance = 5e7`) 상태에서 밀리미터(`mm`) 단위 부재(예: `2,720mm` 테트라포드, `4,200mm` 기둥)를 렌더링하면서, 모서리/실루엣 주변에 검은 그을음·노이즈 점(`stipple black burn`)이 발생함.
    2. **Shadow Map 절두체(Frustum)가 부재 내부(`±60mm`)에 갇혀 검은 그림자 띠가 생기는 현상:**
       - `src/view/ModelViewer3D.ts` (L397–409): `key.position.set(18, -8, 28)` 및 `key.shadow.camera.left/right/top/bottom = ±60`, `far = 200`으로 설정되어 있어, 수천 `mm` 크기인 실제 BIM 부재 내부(원점 부근 `120mm` 영역)에서만 그림자 맵이 투사·절단되어 부재 표면이 검게 타 들어감 (`solidMesh.castShadow / receiveShadow = true`, L1109–1110).
    3. **배경이 칠흑 같은 단색(`#0a0a23` / `#0d1117`)이라 공간감이 없고 어두침침한 현상 (Skybox 부재):**
       - `src/view/ModelViewer3D.ts` (L121, L373 `this.scene.background = new THREE.Color(CANVAS_BG)`) 및 `src/host/ui/hostApp.ts` (Host 3D 뷰포트) 모두 단색 남색/검정 배경만 사용하고 있어, 상용 CAD/BIM 프로그램(Revit·Rhino·Fusion 360·onshape) 같은 쾌적한 **절차적 스카이박스(Procedural Gradient Skybox Dome / Studio Environment HDRI 조명)** 가 전혀 없음.
    4. **부재가 작업 평면 그리드(`Z = 0`) 아래에 파묻히고 그리드가 부재를 관통해 지저분하게 보이는 현상:**
       - `src/view/ModelViewer3D.ts` (L427 `this.gridRoot`, L689 `const zGrid = -cell * 0.05`): 그리드가 무조건 `Z = 0`에 고정되어 있어, 중심이 원점(`0,0,0`)에 있는 부재(`IFC-M03` 테트라포드 등 `minZ < 0`인 부재)의 하반신이 그리드 아래로 내려가 그리드 선이 부재 몸통을 가로질러 비쳐 보이며, `gridRoot`에 `userData.noAO = true`가 누락되어 `GTAOPass`가 그리드 선을 부재 표면에 검은 격자 얼룩으로 구워버림.

- **구현 스펙 (개발 세션 즉시 적용 항목):**
  1. **절차적 스카이박스(Procedural Skybox Dome / Equirectangular Environment) 탑재 (`src/view/ModelViewer3D.ts` & `src/host/` 3D 뷰어 공통):**
     - 외부 무거운 텍스처 파일 없이 즉시 로드되는 `THREE.ShaderMaterial` 기반 **Z-up BIM 스튜디오 스카이박스 돔(또는 `PMREMGenerator` 환경맵 + 천정 `#e8f0fe` ~ 지평선 `#f8fafc` ~ 지면 `#d0dae8` 건축 주간 스카이 그라데이션 / 다크모드 시 `#1e293b` ~ `#0f172a` 스튜디오 호라이즌 스카이박스)** 적용.
     - `scene.environment`에도 소프트 스튜디오 환경광(PMREM)을 연결하여 금속(`Steel`)·콘크리트(`Concrete`)·유리(`Glass`) 재질이 은은한 반사광으로 입체감 있게 표현되도록 개선.
  2. **부재가 절대 그리드 아래에 놓이지 않도록 바닥면(`Z >= 0`) 정렬 + 그리드 동적 바닥 배치 & 그리드 숨김(`?grid=0`) 지원:**
     - **부재 `Z >= 0` 안착 & 그리드 하단 자동 스냅 (`src/view/ModelViewer3D.ts` L677 `_rebuildGrid`):** 솔리드 부재의 바운딩 박스 최하단(`solidMinZ`)이 `0`보다 작을 경우 부재를 그리드 위(`Z >= 0`)로 올리거나 `zGrid = Math.min(0, solidMinZ) - cell * 0.05`로 그리드를 부재 바닥면 아래로 자동 배치하여 **그 어떤 부재도 그리드 아래에 파묻히거나 그리드에 관통되지 않도록 보장**.
     - **그리드 표시/숨김 토글 및 URL 쿼리(`?grid=0` / `viewer.setGridVisible(false)`):** 시연 영상 촬영 및 깔끔한 프레젠테이션 모드에서 그리드를 즉시 끌 수 있도록 `ModelViewer3D.setGridVisible(visible: boolean)` 메서드와 URL 파라미터 `?grid=0` 지원 추가.
  3. **부재 가장자리 까맣게 타는 현상(`GTAOPass` & `DirectionalLight` Shadow) 완전 제거 (`src/view/ModelViewer3D.ts`):**
     - **Shadow 수정 (L397–409, L1109–1110):** 밀리미터(`mm`) 스케일(부재 크기 `500mm ~ 100,000mm`)에서 고정 `±60mm` Shadow Map으로 인한 자기 그림자(Self-shadowing burn)를 막기 위해 `key.castShadow = false` (또는 모델 바운딩 박스에 맞춰 `key.position` 및 `shadow.camera` 절두체를 동적 스케일링 + 충분한 `normalBias`)로 변경하고, 다방향 스튜디오 조명(Key + Fill + Rim + Hemisphere + Environment)으로 깔끔한 면 음영(CAD Shading) 구현.
     - **GTAO 수정 (L489–493):**
       - `this.gridRoot.userData.noAO = true` 및 모든 그리드 자식(`minor`, `major`, `axis-*`)에 `userData.noAO = true` 설정하여 그리드가 부재에 검은 격자 얼룩을 입히지 않도록 차단.
       - `gtaoPass.updateGtaoMaterial({ radius: ..., distanceExponent: ..., thickness: ..., scale: ... })` 및 `gtaoPass.blendIntensity = 0.25~0.35`로 낮춰 가장자리가 까맣게 타지 않고 모서리에만 은은한 입체 음영이 돌도록 조정 (필요시 SwiftShader/소프트웨어 렌더러 감지 시 GTAO 노이즈 자동 비활성화).
  4. **능선 엣지(`SOLID_EDGE`) 및 면 색상(`SOLID_FILL`) 시인성 개선 (`src/view/ModelViewer3D.ts` L133–134):**
     - 스카이박스 배경 위에서 부재 윤곽이 선명하고 고급스럽게 보이도록 `SOLID_FILL` 밝기와 `LineMaterial` 엣지 컬러/두께(`1.2~1.5px`) 및 `polygonOffset`을 정밀 튜닝하여 가장자리 Z-fighting 검은 점 현상 제거.

- **완료 검증 기준 (Acceptance):**
  - `studio.html?sample=builtin/S01-column-steel-wide-flange`, `studio.html?sample=infra/IFC-M03-tetrapod-armor-unit`, `host.html?sample=office-with-annex` 로드 시:
    1. 배경에 스카이박스(하늘~지평선 그라데이션)가 자연스럽게 렌더링될 것.
    2. 모든 부재가 그리드 위(`Z >= 0`)에 깔끔하게 올라와 있거나 `?grid=0`으로 그리드를 완전히 숨길 수 있어, 그리드 아래에 잠긴 부재가 절대 없을 것.
    3. 부재 모서리·표면에 검은 그을음/점박이(GTAO/Shadow burn)나 그리드 비침 현상이 전혀 없을 것.
    4. 수정 완료 후 `node cli/youtube-factory.mjs`로 유튜브 시연 영상을 재촬영했을 때 방송급 3D CAD/BIM 화면 품질이 나올 것.