# Handoff: 로봇 자동 티칭 시스템 (DOZIKWORKS OS)

> Yaskawa AR2010 용접 로봇용 티칭/시뮬레이션 소프트웨어. 3D 뷰포트 + 운동학(FK) +
> JBI 경로 재생 + AI 어시스턴트(ARIA)를 포함한 단일 화면 데스크톱 앱 디자인.

---

## Overview
현장의 숙련공이 손으로 하던 로봇 용접 티칭을, 3D 스캔/시뮬레이션 기반으로 자동화하는
제품의 메인 운용 화면이다. 화면에서:
- 3D 뷰포트에 실제 AR2010 STL 메시를 로드해 로봇 자세를 시각화
- JBI(로봇 실행 파일) 경로를 스텝 단위로 재생/일시정지/이동
- 정운동학(FK)으로 관절각 → TCP(공구 끝점) 좌표 계산
- 펄스 ↔ 각도 변환(실측 검증 계수)
- 충돌/특이점/소프트리밋 상태 모니터링
- AI 어시스턴트 'ARIA'에게 자연어로 지시(스텝 이동, 조그, 분석 등)

## About the Design Files
이 번들의 파일은 **HTML로 만든 디자인 레퍼런스이자 동작하는 프로토타입**이다. 그대로
프로덕션에 올리는 코드가 아니라, **의도한 화면/동작/운동학 로직을 보여주는 참조본**이다.
목표는 이 디자인과 로직을 **대상 코드베이스의 기존 환경(React/Electron/네이티브 등)으로
재구현**하는 것이다. 환경이 아직 없다면, 데스크톱 산업용 툴에 적합한 프레임워크
(예: Electron + React, 또는 Tauri)를 선택해 구현한다.

단, **운동학 계산식·변환 계수·URDF 체인·JBI 파싱 로직은 그대로 이식할 가치가 있는
실제 로직**이다 (단순 목업 아님). 아래 "운동학 / 데이터" 섹션 참고.

## Fidelity
**High-fidelity (hifi)** — 최종 색상/타이포/레이아웃/인터랙션이 모두 구현된 상태.
3D 뷰포트, 운동학, 데이터 바인딩이 실제로 동작한다. UI는 픽셀 단위로 재현하고,
로직은 그대로 포팅하는 것을 권장한다.

설계 캔버스(논리적 해상도): **1536 × 1024**. 상위 stage가 화면 크기에 맞춰 스케일링한다
(`fitStage`).

---

## Architecture (현재 프로토타입 구조)
- 단일 파일 `DOZIKWORKS OS.dc.html` — "Design Component(DC)" 포맷.
  - `<x-dc>...</x-dc>` 안의 마크업(인라인 스타일) + `class Component extends DCLogic { … }` 로직.
  - 런타임 `support.js` (DC 프레임워크, React 기반)가 이 둘을 조립해 렌더한다.
  - **재구현 시 이 DC/지원 런타임 구조는 버리고, 마크업은 컴포넌트로, 로직 클래스는
    상태관리(예: React state/Zustand)로 옮기면 된다.** 인라인 스타일 값은 그대로 토큰화.
- 3D: **three.js r0.149** (`window.THREE`). STL 메시는 `ar2010_stl.json`에서 로드.
- AI: `window.claude.complete(prompt)` 호출 (프로토타입 환경 전용). 재구현 시
  실제 LLM API(Anthropic 등) 호출로 교체. 실패 시 `localIntent()` 규칙 기반 폴백 존재.

## Screens / Views (단일 화면, 패널 구성)
화면은 1536×1024 단일 데스크톱 레이아웃. 주요 영역:

1. **Top Bar** (height 56px)
   - 좌: DOZIKWORKS 로고(육각형 SVG) + `OS` 뱃지(파랑 #2563EB)
   - 파일 선택 드롭다운: `{{ fileName }}` (예: `12500(IN2222).JBI`)
   - `SAFE` 상태 뱃지(녹색 #16A34A)
   - 우: undo/redo, 카메라, 영상 등 아이콘 버튼(34×34, hover 시 배경 rgba(30,52,92,.08))
2. **3D 뷰포트** (중앙 메인) — three.js 캔버스. 로봇 메시 + 용접 경로 라인.
   - 뷰 프리셋 버튼: ISO / FRONT / TOP / SIDE (`viewBtns`)
3. **좌측/우측 패널** — TCP 좌표 카드, 관절각 카드, 좌표계 탭(`frameTab`: tcp/base/...),
   티칭 모드(`teachMode`), 포인트 리스트.
4. **플로팅 팔레트** — 제어(ctrl) / 조그(jog) 팔레트. 드래그 이동 가능(`palettes` 좌표 상태).
5. **하단/사이드 콘솔** — 로그 리스트(INFO/WARN/ERROR), I/O 신호(IN/OUT 8채널씩).
6. **AI 어시스턴트(ARIA)** — 채팅 입력 + 빠른 명령 버튼(20번 이동/U축 분석/충돌검사/용접경로).

> 정확한 픽셀 값/색/타이포는 `DOZIKWORKS OS.dc.html` 인라인 스타일을 직접 참조할 것.
> 모든 스타일이 인라인이라 측정값이 코드에 그대로 있다.

## Design Tokens (코드에서 반복되는 값)
- Primary blue: `#2563EB` / hover `#1D4FC4` / light accent `#5B8DF5`
- Ink(텍스트): `#1B2B47`, `#0A1428`, muted `#64769A` / `#33455F`
- 배경: 캔버스 `#EAF0F7`, 패널 그라데이션 `#FFFFFF → #F4F8FD`
- 상태색: SAFE/녹색 `#16A34A`, WARN `#CA8A04`, ERROR `#DC2626`
- 경계선: `rgba(30,52,92,.09~.12)`
- Radius: 카드/버튼 7~8px, 로고칩 5px
- Shadow: `0 3px 14px rgba(30,52,92,.05)` 류
- 폰트: 본문 **Pretendard**, 영문 헤드/숫자 **Space Grotesk**, 숫자에 `tabular-nums`

## 운동학 / 데이터 (★ 가장 중요한 이식 대상)
`DOZIKWORKS OS.dc.html`의 로직 클래스 내부:
- `dims` — 링크 치수(mm)
- `coeff` — **펄스↔각도 변환계수 (실측 검증, 기술보고서 표 2-2)**. 축별 `{zero, ppd, off}`.
  - `angleToPulse(axis,deg)` / `pulseToAngle(axis,pulse)`
- `urdf` — AR2010 실제 기구학 체인 6관절 `{a, xyz[], rpy[]}` + `tcpOffset[]`
- `fk(joints)` — **정운동학**: 행렬 곱(Tr→rpy→Rz)으로 TCP `{x,y,z,rx,ry,rz}` 산출.
  행렬 헬퍼 `mMul/mTr/mRx/mRy/mRz` 포함.
- `anchors` — 검증된 앵커 포즈(스텝→6축 각도). JBI 없을 때 보간용.
- `poseAt(pos)` — JBI 로드 시 `jbi.json`의 `stepPoses/cum/total`로 시간 보간,
  미로드 시 `anchors` 선형 보간.
- `blocksDef` — 경로 블록 정의(라벨/스텝범위/타입: LINE/ARC/WELD).

### 데이터 파일
- **`jbi.json`** — 로봇 실행 경로. `{ n, stepPoses[], cum[], total, ... }`.
  `componentDidMount` 후 `fetch('jbi.json')` → `buildWeldFromJbi()`로 용접 경로 구성.
- **`ar2010_stl.json`** — AR2010 STL 메시(로컬 링크 프레임, mm). 축별 그룹
  `{ base, S, L, U, R, B, T }`에 매핑해 three.js 메시로 렌더.
  - 본체 머티리얼: `MeshPhysicalMaterial({color:0x1e50d0, metalness:.35, roughness:.42, clearcoat:.6})`
- ⚠ 두 파일 모두 fetch 경로가 상대경로(`jbi.json`, `ar2010_stl.json`)다. 재구현 환경의
  정적 자산 경로/번들러에 맞게 조정 필요.

## Interactions & Behavior
- **재생 루프**: `requestAnimationFrame` 기반 `loop()`. `playing` true일 때 `speed`(localStorage
  `dzw_speed`에 영속)로 `pos` 증가, `poseAt(pos)`로 관절 갱신 → `fk()`로 TCP 갱신.
- **스텝 이동**: `gotoStep(n)` — 116 스텝 기준.
- **조그(jog)**: 축별 `delta` 증감 (joint/world 모드).
- **AI 명령(ARIA)**: 자연어 → `window.claude.complete`로 JSON 액션 요청
  (`goto_step/play/pause/stop/analyze_u/run_collision/show_weld_path/jog/add_point`),
  파싱 실패 시 `localIntent()` 규칙 폴백 → `runAction()` 실행.
- **상태 뱃지**: collision/singularity/servo/mode 표시.
- **설정 토글**: collisionGuard, softLimit, autoSave, dryRun, unit, maxSpeed, jogSpeed.

## State Management (현재 `state` 키 → 그대로 store 설계에 사용 가능)
`activeTool, screen, teachMode, frameTab, view, playing, speed, pos, joints{S..T},
tcp{x,y,z,rx,ry,rz}, mode, collision, singularity, servo, input, aiBusy, toast, showJog,
jogMode, jogStep, weldOnly, fullRobot, palettes{ctrl,jog}, insight, points[], io, logs[],
logFilter, settings{...}`

## 알려진 이슈 / 개발자 확인 요청 (사용자가 로컬에서 손볼 부분)
- **U축 오차**: 로그/insight에 "U축 오차: 모델/URDF 차이 134.6°" 경고가 있음.
  `urdf`의 U관절 rpy/부호, `coeff.U`, `anchors`의 U값 정합성 검증 필요
  (Theta Offset 문제 가능성). 실제 로봇/URDF와 대조해 보정할 것.
- **STL ↔ 링크 프레임 정합**: `ar2010_stl.json` 메시 원점과 `urdf` 링크 프레임이
  어긋나면 시각화가 틀어진다. `initThree` 내 그룹 매핑 확인.
- **AI 호출**: `window.claude.complete`는 프로토타입 전용. 실제 API로 교체 필요.

## Files (이 번들)
- `DOZIKWORKS OS.dc.html` — 메인 티칭 시스템 (UI + 운동학 + 3D + AI). ★ 핵심
- `teaching.html` — 자동 티칭 소개/마케팅 페이지 (위 시스템으로 진입하는 랜딩).
- `support.js` — DC 런타임(참조용). 재구현 시 불필요 — 로직/마크업만 추출하면 됨.
- `jbi.json` — 로봇 실행 경로 데이터.
- `ar2010_stl.json` — AR2010 STL 메시 데이터.

## External deps
- three.js r0.149 (`https://unpkg.com/three@0.149.0/build/three.min.js`)
- Pretendard, Space Grotesk (웹폰트)
- (선택) Anthropic/LLM API — ARIA 어시스턴트용