# ADR-ui-0001 · Inspector UX 방향 — Hierarchy + Search + Group fold

상태: **Accepted (2026-05-07)**
종속: ADR-0001 (제품 비전), ADR-cad-0001 (STEP 임포트 전략)

---

## 배경

산업 어셈블리 STP 261MB 변환 검증 결과:

| 항목 | 값 |
|---|---|
| 부품 노드 (mesh 보유) | 3500 |
| 어셈블리 그룹 노드 | 448 |
| 트리 최대 깊이 | 8단계 |
| 부품 코드명 보존 | 100% (3948/3948) |
| 메시 인스턴싱 | 평균 1.6배 (mesh 2155 → node 3500) |

비코딩 사용자가 **3500개 부품**을 어떻게 찾고 조작할지가 Phase 1 MVP의 핵심 UX 결정.

---

## 검토한 옵션

### A. Hierarchy 트리만 노출 (Unity Editor 기본 방식)

- 장점: 어셈블리 구조 그대로 시각화, 구현 단순
- 단점: 8단계 깊이 + 3500개 → 수직 스크롤만 1만 줄. 비코딩 사용자가 길을 잃음

### B. 검색·필터 위주 (이름 검색 기반)

- 장점: 부품 코드 알면 즉시 도달
- 단점: 부품 코드 모르는 사용자(공장 PM, 영업)가 시작점 못 찾음. 어셈블리 구조 인지 어려움

### C. 어셈블리 단위 접기 (Collapsible Group)

- 장점: 시각적 부담 감소, 어셈블리 단위 조작 자연스러움
- 단점: 단독으로는 깊은 부품 도달까지 클릭 8번

### D. Hybrid — Hierarchy + Search + Group fold (채택)

세 옵션을 결합:

1. **TreeView 위젯 (UI Toolkit 내장)** — 어셈블리 트리 자체 표시, 클릭으로 펼침/접힘
2. **상단 SearchField** — 부품 코드 / 이름 부분 일치 → TreeView가 매칭 노드만 펼쳐서 표시 + 하이라이트
3. **루트 어셈블리 자동 접기** — 첫 진입 시 1차 서브어셈블리(18개)만 펼쳐 시각 부담 최소화. 사용자가 필요할 때 펼침
4. **메시 인스턴스 통합 표시** — 같은 부품(예: 알루미늄 프로파일 32회 재사용)은 트리에서 대표 1개 + 옆에 "(×32)" 배지. 인스턴스 위치 패널로 별도 노출

---

## 기술 구현 (Phase 1 MVP)

### UI Toolkit 위젯

- `TreeView` (Unity 6 기본 제공) — 가상 스크롤 지원, 1만 노드까지 부드러움
- `ToolbarSearchField` — 검색 입력
- `Foldout` — 어셈블리 그룹 접기/펼치기 (TreeView 내부에서 자동 처리)

### 데이터 구조

`Part` 클래스(이미 정의)에 추가 필드 검토:

```csharp
public class Part {
    public string id;           // glTF node 경로 또는 UUID
    public string name;         // glTF node name 그대로
    public string parentId;     // 어셈블리 그룹
    public List<string> childIds;
    public bool isAssemblyGroup;  // children 보유 + mesh 없음
    public string sharedMeshId;   // 인스턴스인 경우 원본 mesh 참조
    public int instanceCount;     // 동일 sharedMesh를 참조하는 노드 수
    // ... existing
}
```

### 검색 동작

1. 입력 즉시 디바운스 200ms
2. 부분 일치 (대소문자 무시)
3. 매칭 노드의 모든 조상 자동 펼침
4. 매칭 노드 시각적 강조 (배경색 변경)
5. 결과 N건 표시 ("매칭 12건")

### 첫 진입 화면

- 루트 어셈블리(예: `MS24-1090-000-00`)만 펼쳐진 상태
- 1차 서브어셈블리 18개 가시
- 사용자가 클릭으로 깊이 진입

### 다중 선택

- Ctrl+클릭 / Shift+클릭 (PC 데스크탑) — 다중 부품 일괄 속성 편집 (movement, type 변경)
- 선택된 부품들 Inspector에 종합 표시

---

## 채택 사유 (D Hybrid)

| 사용자 페르소나 | 시작점 | 결과 |
|---|---|---|
| 부품 코드 아는 PM/엔지니어 | SearchField에 코드 입력 | 즉시 도달 |
| 어셈블리 구조 파악 중인 영업 | TreeView에서 위→아래 탐색 | 1차 어셈블리부터 단계적 진입 |
| 부품 클릭으로 시작 | 3D 뷰어에서 부품 선택 | TreeView가 해당 노드까지 자동 펼침 + 하이라이트 |
| 비코딩 사용자 (공장 운영자) | 그룹 단위 조작 | 어셈블리 그룹 클릭 → 회전·이동, 자식 부품 따라감 |

**비코딩 사용자가 부품을 코딩 없이 찾고 조작할 수 있다 = 제품 비전 ADR-0001 원칙 3번 충족.**

---

## 거절된 대안

### 노드 그래프 UI (기존 ADR-0001 R4 기준)

- Phase 1 MVP에서는 채택 안 함 (Engineering 6주+ 단위 작업)
- Phase 2 Pro 확장에서 Constraint 시각 편집용으로 추가
- 선언: ADR-0001 R4 그대로 유지

### Unity Hierarchy 그대로 노출

- Editor 모드만 가능, 빌드 후 사용자에게 노출되지 않음
- 별도 Runtime UI Toolkit 구현 필수

---

## 검증 계획 (Phase 1 진입 시)

1. **glTFast 통합 PoC** (Task #13) — 32MB factory.glb를 Unity Scene에 로드 → 3500 GameObject 분리 검증. Hierarchy 자동 매핑 확인.
2. **TreeView 1만 노드 성능** — 가상 스크롤 동작, 60fps 유지 확인
3. **SearchField 디바운스 + 펼침 로직** — 매칭 즉시 시각 도달
4. **사용성 — 협업자 BD Lead 직접 시험** — 부품 코드 모르고 진입 시 5분 내 원하는 부품 도달 가능한가

---

## 영향

- Phase 1 MVP 범위 확정 (TreeView + SearchField + Inspector + 3D 뷰어 4-pane 레이아웃)
- 데이터 모델: `Part` 클래스에 `isAssemblyGroup` / `sharedMeshId` / `instanceCount` 필드 추가 필요 (다음 PR)
- glTFast 임포트 후 Part 그래프로 변환하는 어댑터 레이어 신설 (`Assets/Scripts/Importers/GltfPartImporter.cs`)

---

## 거절 가능 시나리오 (재검토 트리거)

- TreeView 가상 스크롤이 1만 노드에서 30fps 이하로 떨어지면 → 페이지네이션 또는 LOD 도입
- 협업자 BD Lead 시험에서 5분 내 부품 도달 실패율 50% 이상이면 → 다른 정보 구조 설계 (카테고리별 탭 등)