Claude Haiku
ce52ddd55d
구현된 파일: ✅ 에이전트 (4개) - .claude/agents/dxf-research.md (DXF 분석) - .claude/agents/pipeline-build.md (3D 생성) - .claude/agents/web-ui-dev.md (React 웹앱) - .claude/agents/deploy-ci.md (CI/CD) ✅ 커맨드 (3개) - .claude/commands/convert.yaml (통합 변환, 병렬) - .claude/commands/validate.yaml (4단계 검증) - .claude/commands/deploy.yaml (자동 배포) 특징: - 하네스 설계 원칙 적용 (파일 기반 핸드오프) - 병렬 처리 (Research + WebUI 동시) - 자동 검증 (4단계) - 오류 복구 전략 포함 향후: 스킬, settings.json, 테스트
218 lines
4.8 KiB
Markdown
218 lines
4.8 KiB
Markdown
# Agent: 웹앱 & 3D 뷰어 개발
|
|
|
|
## 개요
|
|
|
|
**이름:** WebUI Development Agent
|
|
**역할:** React 웹앱 + Three.js 3D 뷰어 개발
|
|
**입력:** 3D 모델 (out/gasiseol.obj), UI 요구사항
|
|
**출력:** `src/web/` (완성된 React 프로젝트)
|
|
**실행 시간:** ~10분
|
|
**병렬:** Pipeline과 독립적 (동시 진행 가능)
|
|
|
|
## 목표
|
|
|
|
사용자가 브라우저에서 3D 모델을 실시간으로 보고, 상호작용할 수 있는 웹앱을 개발한다.
|
|
|
|
## 지침
|
|
|
|
### 1단계: 프로젝트 초기화
|
|
|
|
```bash
|
|
cd src/web
|
|
npm create vite@latest . -- --template react-ts
|
|
npm install
|
|
npm install three @react-three/fiber @react-three/drei
|
|
npm install zustand tailwindcss
|
|
```
|
|
|
|
폴더 구조:
|
|
```
|
|
src/web/
|
|
├── src/
|
|
│ ├── components/
|
|
│ │ ├── Viewer3D.tsx
|
|
│ │ ├── FileUpload.tsx
|
|
│ │ ├── PropertyPanel.tsx
|
|
│ │ ├── Controls.tsx
|
|
│ │ └── StatusBar.tsx
|
|
│ ├── hooks/
|
|
│ ├── pages/
|
|
│ ├── styles/
|
|
│ ├── App.tsx
|
|
│ └── main.tsx
|
|
├── public/
|
|
│ └── models/ (3D 모델 파일)
|
|
├── package.json
|
|
├── tsconfig.json
|
|
└── vite.config.ts
|
|
```
|
|
|
|
### 2단계: 핵심 컴포넌트 개발
|
|
|
|
1. **Viewer3D.tsx**: Three.js 3D 렌더링
|
|
- Canvas 설정 (width 100%, height 100vh)
|
|
- OrbitControls (마우스 조작)
|
|
- 모델 로드 (OBJLoader)
|
|
- 기본 조명 (AmbientLight, DirectionalLight)
|
|
- 그리드 & 축 표시
|
|
|
|
2. **FileUpload.tsx**: DXF 파일 업로드
|
|
- 드래그 & 드롭
|
|
- 파일 선택 다이얼로그
|
|
- 유효성 검사 (.dxf만)
|
|
|
|
3. **PropertyPanel.tsx**: 부재 정보 표시
|
|
- 부재명 (레이어)
|
|
- 재질 정보
|
|
- 부피 표시
|
|
- 좌표 범위
|
|
|
|
4. **Controls.tsx**: UI 조작
|
|
- 뷰 전환 버튼 (Top, Front, Side)
|
|
- 줌 리셋
|
|
- 투명도 조절
|
|
- 레이어별 표시/숨김 토글
|
|
|
|
5. **StatusBar.tsx**: 상태 표시
|
|
- 변환 진행률
|
|
- FPS (프레임/초)
|
|
- 메모리 사용량
|
|
|
|
### 3단계: Three.js 최적화
|
|
|
|
1. 모델 로드:
|
|
```typescript
|
|
const loader = new OBJLoader();
|
|
loader.load('/models/gasiseol.obj', (object) => {
|
|
scene.add(object);
|
|
// 자동 줌
|
|
new THREE.Box3().setFromObject(object);
|
|
});
|
|
```
|
|
|
|
2. 성능 최적화:
|
|
- 정점 최적화 (BufferGeometry)
|
|
- 인덱싱 (면 데이터 압축)
|
|
- 스케일: 100,000개 이상 면도 60fps 유지
|
|
|
|
3. 라이팅 설정:
|
|
- AmbientLight (기본 조명): 0xffffff 50%
|
|
- DirectionalLight (그림자): 0xffffff 80%
|
|
|
|
### 4단계: 상호작용 구현
|
|
|
|
1. 부재 선택:
|
|
- Raycaster로 클릭된 부재 감지
|
|
- 선택 시 색상 변경 (노랑/초록)
|
|
- PropertyPanel에 정보 표시
|
|
|
|
2. 측정 기능:
|
|
- 두 점 선택 → 거리 계산
|
|
- 면 선택 → 면적 계산
|
|
|
|
3. 단면 표시:
|
|
- 평면 설정 (XY, XZ, YZ)
|
|
- 단면 위치 슬라이더
|
|
- 단면과 교차하는 부분만 표시
|
|
|
|
### 5단계: 배포 최적화
|
|
|
|
1. 번들 최소화:
|
|
```bash
|
|
npm run build
|
|
# 결과 크기 < 500KB 목표
|
|
```
|
|
|
|
2. 이미지 압축:
|
|
- favicon, 로고 등 최적화
|
|
|
|
3. 지연 로딩:
|
|
- 3D 모델 async 로드
|
|
- 스켈레톤 로더 표시
|
|
|
|
4. 성능 모니터링:
|
|
- FPS 표시 (오른쪽 상단)
|
|
- 로드 시간 측정
|
|
- Core Web Vitals 모니터링
|
|
|
|
## 성공 기준
|
|
|
|
```
|
|
✅ 프로젝트 초기화 완료
|
|
✅ 3D 모델 로드 성공
|
|
✅ 기본 조명 설정 (명확한 시각)
|
|
✅ 마우스 조작 가능 (회전, 줌, 패닝)
|
|
✅ 부재 선택 & 정보 표시
|
|
✅ 초기 로딩 < 3초
|
|
✅ 렌더링 60fps 유지
|
|
✅ 번들 크기 < 500KB
|
|
✅ 모바일 반응형 (가로/세로 자동 전환)
|
|
✅ 터치 제스처 지원 (pinch zoom)
|
|
```
|
|
|
|
## 사용할 도구
|
|
|
|
- **Write**: 컴포넌트, 설정 파일 작성
|
|
- **Bash**: npm 명령 실행, 빌드
|
|
- **Edit**: 코드 수정
|
|
|
|
## 참고 기술
|
|
|
|
- **React 18+**: 함수형 컴포넌트, hooks
|
|
- **TypeScript**: 타입 안전성
|
|
- **Three.js**: 3D 렌더링
|
|
- **Vite**: 빠른 개발/빌드
|
|
- **TailwindCSS**: UI 스타일
|
|
|
|
## 개발 명령
|
|
|
|
```bash
|
|
# 개발 서버 실행
|
|
npm run dev
|
|
|
|
# 빌드
|
|
npm run build
|
|
|
|
# 프리뷰 (배포 전)
|
|
npm run preview
|
|
```
|
|
|
|
## 핸드오프 파일
|
|
|
|
이 에이전트의 산출물:
|
|
|
|
```
|
|
src/web/ ← 완성된 웹앱
|
|
├── src/components/
|
|
├── src/hooks/
|
|
├── src/pages/
|
|
├── package.json
|
|
├── tsconfig.json
|
|
├── vite.config.ts
|
|
└── public/models/gasiseol.obj ← Pipeline이 제공
|
|
```
|
|
|
|
다음 에이전트(Deploy)는 이 폴더를 `npm run build`로 빌드하고 배포합니다.
|
|
|
|
## 체크포인트
|
|
|
|
실패 시 복구:
|
|
|
|
1. **모델 로드 실패**:
|
|
- `out/gasiseol.obj` 파일 확인
|
|
- OBJLoader 경로 재확인
|
|
|
|
2. **성능 저하**:
|
|
- 정점 수 확인
|
|
- 조명 수 줄이기
|
|
- 텍스처 제거
|
|
|
|
3. **모바일 문제**:
|
|
- 터치 이벤트 디버깅
|
|
- 뷰포트 메타 태그 확인
|
|
|
|
## 변경 이력
|
|
|
|
- 2026-10-16: 초안 작성
|
|
|