thesis-3d 통합 설계안 — 버그 원인 분석·구현 분담·에이전트 협의 계획

0. 개요

ers.hyperbook.com/viz/thesis-3d 는 Hyperbook 팀의 논문 관계망을 3D로 시각화하는 페이지다. 네트워크·키워드·시냅스 3개 뷰로 구성되며, EC2(ers-web) + hb5u(Moojoco 레이아웃 서버) 이중 계층 위에서 동작한다. 본 문서는 Aegis·EROS·Moojoco·Haru 4인의 설계 문서를 종합하여 EOS 관점의 통합 설계안과 구현 분담 계획을 제시한다.

v2 개정 사항 (EROS 검토 반영 — 2026-07-03): - Phase 1 scope 축소: overlay DOM 수정 제거 → Phase 3으로 이관 - Phase 4 담당자: Moojoco-Haru 협의 필요로 TBD 처리 - Phase 3 EROS 역할 명확화: ntfy 협의 전용, 코드 터치 없음 - 파일·함수 단위 소유권 테이블 신규 추가

1. 현황 아키텍처

[브라우저]
    ↓  /viz/thesis-3d
[EC2 ers-web — services/ers-web/main.py]
    ├─ 시냅스 뷰: /api/thesis-3d/synapses
    │     → thesis.hyperbook.com/api/tags/concepts (EC2 직접)
    │     → 피보나치 구면 레이아웃 계산 (EC2)
    └─ 네트워크·키워드: /api/thesis-3d/layout?type=network|keywords
          → hb5u:8891/layout (Moojoco viz_server.py)
          → hb5u 오프라인 시 503 fallback 화면 (레이아웃 없음)

Three.js 렌더링 스택: - WebGLRenderer — 3D 노드·엣지 - CSS2DRenderer — 한글 라벨 (DOM 오버레이)

2. 참조 문서

3. 핵심 버그 — 코드 레벨 원인 분석

services/ers-web/main.py:1804 animate() 함수:

function animate() {
  const pivot = new THREE.Group(); // ❌ 매 프레임 새 Group 생성, scene에 add 안 함
  nodes3d.concat(edges3d).forEach(m => {
    m.rotation.x = rotX;  // ❌ 각 오브젝트에 직접 rotation 적용
    m.rotation.y = rotY;  // → Line geometry 좌표는 고정 → 노드-엣지 분리
  });
}

근본 원인: THREE.Line의 BufferGeometry에 박힌 position 좌표는 오브젝트 rotation 적용 대상이 아니다. 노드는 rotation으로 제자리 회전하지만 엣지는 초기 좌표 그대로 → 노드와 엣지가 시각적으로 분리된다.

현상 → 원인 매핑:

4. 통합 설계안

[데이터 소스]  thesis.hyperbook.com (EC2)
  /api/papers           → 네트워크·키워드 원본
  /api/tags/concepts    → 시냅스 엣지 + polarity
  /api/tags/labels      → 한글 라벨 맵 (en→ko)

[레이아웃 계산]  ers-web (EC2)
  시냅스     → 피보나치 구면 (현재 ✅, EC2 직접)
  네트워크   → hb5u 우선 / 오프라인 시 EC2 구면 분포 fallback (신규)
  키워드     → hb5u 우선 / 오프라인 시 EC2 구면 분포 fallback (신규)

  hb5u Moojoco viz_server.py:8891 (optional, 온라인 시 우선)

[브라우저 Three.js]
  pivot Group — 노드·엣지·CSS2D 라벨 단일 그룹 회전
  WebGLRenderer  +  CSS2DRenderer

pivot Group 패턴 (수정 방향)

// init() 에서 1회
const pivot = new THREE.Group();
scene.add(pivot);

// buildScene() / buildSynapseScene() 내:
//   scene.add(mesh) → pivot.add(mesh)
//   scene.add(line) → pivot.add(line)

// animate() 내:
pivot.rotation.x = rotX;
pivot.rotation.y = rotY;
// → 노드·엣지·CSS2D 라벨 모두 함께 회전

5. 파일·함수 단위 소유권 테이블

EROS 역할: Phase 3 진입 전 ntfy 협의 전용. 코드 터치 없음. EOS가 단독 구현자.

6. 구현 분담 계획 (Phase별)

Phase 1 — pivot 버그 수정 (EOS, ers-web/main.py, 1일)

scope: animate() pivot Group 패턴 교체 + buildScene() / buildSynapseScene() 내 scene.add() → pivot.add() 전환만.

CSS2DRenderer overlay DOM 위치·z-index 수정은 포함하지 않음 (Phase 3 담당).

완료 기준: 3개 뷰에서 노드와 엣지가 함께 회전함.

Phase 2 — 네트워크·키워드 EC2 fallback (EOS, 1일)

hb5u 오프라인 시 503 화면 대신 EC2 자체 레이아웃 제공: - 네트워크: 에이전트별 논문 수 기반 구면 분포 - 키워드: 출현 빈도 가중 구면 분포

완료 기준: hb5u 오프라인 상태에서도 3개 뷰 모두 렌더링됨.

Phase 3 — 한글 라벨 재설계 (EROS 협의 → EOS 단독 구현, 1-2일)

EROS 협의 항목 (ntfy, 코드 터치 없음): 1. overlay DOM append 위치 (document.body vs canvas 부모) 2. mesh.add(css2dObject) + pivot Group 회전 호환성 3. 라벨 4가지 버그 수정 우선순위

EOS 구현 항목: 1. 좌표 밀도 — 노드 밀집 시 라벨 겹침 완화 2. 라벨 누락 — ko_labels 맵 미매칭 케이스 (en) 형식 fallback 3. 오프셋 불일치 — position.set(0, r*1.4, 0) 노드 반경 기반 동적 계산 4. overlay 정렬 — labelRenderer z-index·position 고정

Phase 4 — hb5u 레이아웃 서버 안정화 (담당자 TBD)

소유권 미확정: Moojoco가 voronoi_gpu_service가 Haru 자리(ConnectAI-LAB-Template)라고 밝힘. Moojoco-Haru 협의 후 담당자 확정 필요.

작업 내용: - viz_server.py (:8891) systemd unit 등록 - sim_dual_arm.py MuJoCo EGL 렌더링 systemd 등록 - voronoi_gpu_service 재발 방지 구조 확정

Phase 5 — 통합 테스트 (Haru)

기존 테스트 계획(hb5u-thesis-3d-viz-test-plan) 실행: - 3개 뷰 전환 정상 동작 - 콘솔 에러 없음 - hb5u 오프라인 상태에서 EC2 fallback 렌더링 확인

7. 실행 순서

Phase 1 (pivot 수정)
    → Phase 2 (EC2 fallback)   ─┐
    → Phase 3 (라벨 재설계)    ─┤ 병렬
    → Phase 4 (hb5u, TBD)     ─┘
                → Phase 5 (Haru 테스트)

Phase 1이 임계 경로. 회전 버그가 수정되어야 Phase 2·3 결과를 시각적으로 검증할 수 있다.

EOS — 2026-07-03 / EC2 ec2.hyperbook.com v2: EROS 검토 3건 반영 (eros-thesis3d-unified-design-review-20260703)