HMDesign/docs/org-chart/final-integration-2026-10-13.md

# OrgChart 최종 Feature 통합 — 2026-10-13

통합 범위는 **Chart Only + 초기 Fit + 직접 Wheel Zoom**, **GuardFix 해결 5건**, **AI 생성 방식 사전 선택 정책**이다. Cell 디자인 A/B안은 제외했다. 범위 검증·테스트는 PASS이며 전체 Guard는 잔여 FAIL 5건을 유지한다. Feature Commit·Push 완료 SHA와 최종 Working Tree는 이 작업의 최종 응답에서 보고한다.

## 범위와 원본 보호

- 대상: `D:\디자인시스템\HMDesign-OrgChart`, `feature/orgchart-package`, 기준 HEAD `0a8daf7ee7ac026952a2e1d3d5f25a922dab07cf`.
- Chart Only 원본 Worktree(24개 승인 파일)와 GuardFix 원본(2개 파일)은 같은 기준 HEAD다. 원본 파일을 해시 snapshot으로 복사했고, 통합 뒤 원본 SHA-256이 모두 같음을 확인했다. 원본 Worktree에 수정·Stage·Commit하지 않았다.
- 기존 미커밋 `AGENTS.md`, `CLAUDE.md`, `ai-page-generation-rules.md`의 사전 선택 변경을 보존했다. 겹치는 정책 문서는 전체 교체하지 않고 Auto 공개 API·Fixed 제약·현재 통합 범위만 합쳤다.
- Cell 실험은 제품 Core에 적용된 적이 없다. 별도 `examples/org-chart-cell-preview`만 경로 검증 후 ignored `test-results/org-chart-cell-withdrawn-2026-10-13/preview`로 옮겼다. Cell 전용 스타일·미리보기·이미지는 Commit 대상에 포함하지 않는다. 기존 그룹 타이틀·직원 카드·연결선 디자인을 유지한다.
- 회사 프리셋, 직원 카드, Fixed 승인 아트워크, 기존 Storybook 메뉴/Story, Theme/Token, Guard 분석기, JSON Contract, lockfile을 수정하지 않았다. `git reset --hard`, `git clean`, Force Push는 사용하지 않았다.
- main Merge·Docker·npm Registry Publish는 실행하지 않는다.

## 통합한 동작

- Auto Core/React 공통 `presentationMode: 'chart-only'`는 흰색 캔버스·조직 노드·연결선만 표시한다. 내장 제목·기준일·선택 회사/인원 요약·Toolbar를 생성하지 않고 기존 접근성 live feedback는 시각적으로 숨긴다. Shadow DOM 소비자 강제 조작은 없다.
- Chart Only의 기본은 `initialView: 'fit'`, `wheelZoom: 'direct'`다. 실제 Bounds를 최초 Fit·가로/세로 중앙 배치하며, 직접 휠 Zoom은 캔버스 안에서 포인터를 기준으로 적용한다. 바깥 휠은 페이지 스크롤을 유지한다.
- 옵션을 생략한 기존 Expanded는 제목·요약·Toolbar·Modifier 휠·기본 중앙/상단 배치를 유지한다. Fixed Chart Only는 승인 디자인 보호를 위해 TypeError로 거부하며 임의로 Auto로 바꾸지 않는다.
- React의 같은 값 inline 옵션 리렌더링에서 불필요한 재마운트/재Fit을 피하고, 데이터/회사/layout 교체에서는 새 Bounds로 Fit한다.
- 통합 검토에서 발견한 2개 뷰 보존 문제를 같은 범위에서 수정했다. controller 재생성의 `initialPlacement` default가 명시적 undefined를 center로 바꾸던 문제를 제거했고, 내부 `fitScale()` getter로 기존 Fit floor를 전달한다. 전체 데이터 교체 시 이전 floor를 버리고 새 Fit을 계산한다. 계획된 공개 Props 3개 외 공개 API 확장은 없다.
- AI 요청의 생성 방식이 미지정이면 코드 작성 전 Chart Only / Full Page를 질문하고 답변 후 구현한다. 이미 선택된 방식은 재질문하지 않는다. Fixed/Expanded 배치 선택은 생성 방식 선택을 대신하지 않는다.

## GuardFix 5건과 남은 결과

`department-colors.ts`의 미선언 contrast 후보 참조 3곳을 원래 fallback과 같은 `#10243b`/`#ffffff`로 교체했다. `expanded-content.ts`의 미소비 `--hm-orgchart-expanded-title-ink` setter와 그 안의 두 토큰 참조를 제거했다. 회사 primary·기존 흰색 제목 텍스트를 바꾸지 않는다. GuardFix 원본의 변경 전후 computed/geometry·캡처 hash 동일 증거도 확인했다.

현재 동일 범위 Guard는 **F3–F7 해결, 기존 FAIL 10→5, 새 FAIL 0, NOT VERIFIED 9**다. 남은 F1/F2/F8/F9/F10은 다음 5개 TOKEN-001 위치다.

- `department-colors.ts:47`: current-gradient / current-card-background.
- `style-presets.ts:9`: resolved-bg-surface.
- `style-presets.ts:74–75`: current-border / current-gradient.

원본 `status/staticStatus = FAIL`, `runtimeStatus = NOT VERIFIED`를 보존한다. 원본 `styleEvidence`는 STATIC PASS / RUNTIME NOT VERIFIED / DESIGN_INTENT PASS / FINAL NOT VERIFIED이며 이 값으로 전체 Guard를 PASS로 바꾸지 않는다. 결합 styleVerification은 생성하지 않았다. 기존 P10/P10.3의 FAIL 10건 기록은 수정하지 않는다. `org-chart-content.css`의 추가 미선언 후보 참조까지 해결한 전체 패키지 검사는 이번 GuardFix 5건 범위가 아니다.

실행: `node scripts/ai-generation-guard.mjs --target . --scope PARTIAL --profile STORYBOOK --files packages/org-chart/src/core/department-colors.ts,packages/org-chart/src/core/expanded-content.ts,packages/org-chart/src/core/style-presets.ts --json`. 결과는 ignored `_local/final-integration/guard-final.json`에 보존한다.

## 최종 통합 검증

- **PASS:** 루트 `tsc -b`, Core/React/독립 소비자 TypeScript 검사, 패키지 빌드, 독립 Chart Only production build, Storybook production build, Theme defaults 92 colors/94 defaults, `git diff --check`.
- **PASS:** Core 86/86, Guard 회귀 94/94. viewport 수정 후 Core/관련 타입·빌드만 재검사했고 변경하지 않은 Guard 회귀는 반복하지 않았다.
- **PASS:** 실제 통합 production 빌드의 React/Vanilla Chart Only **51/51**, 콘솔 오류 0. 20/100/500명·다중 회사·TB/LR/Hybrid·390px/1440px, 초기 Fit/중앙, 직접 휠의 포인터 고정·범위, Pan, 캔버스 밖 페이지 스크롤, 데이터 교체, popup Core/HM Dialog, 접기·직원 보존, 모바일 CDP touch를 확인했다.
- **PASS:** 추가 5개 회귀는 미조작 초기 Fit 직후 접기/펼치기, Fit보다 높은 `zoom.min=0.8`로 재생성 후 축소 floor, Vanilla `setInteractions` 재생성 후 뷰 보존을 검사한다. 별도 `verify-min` query는 예제 검증용이며 제품 API/기본값 변경이 아니다.
- **PASS:** 새 Storybook의 공개 메뉴 4개·Fixed 구성·Expanded 내장 UI·Fit 버튼 4개 검사는 첫 실행에서 통과했다. Modifier 휠 항목은 페이지 smooth scroll의 좌표 이동 때문에 실패했으므로 actual wheel 이벤트/배율로 진단하고 instant scroll로 테스트 좌표를 고정해 해당 항목만 재검사했다(1/1 PASS, 일반 휠 scale=1, Ctrl 휠=1.2214). 최초 결과 4/5와 재검사 결과를 별도 보존했다. 제품 휠 코드는 이 진단으로 변경하지 않았다.
- 원본 Chart Only 작업의 기존 baseline DOM/픽셀 비교 9/9는 원본 작업 당시 증거다. 현재 통합의 5개 Storybook 동작 검사와 구분하며, 통합 후 전체 Storybook 픽셀 baseline 비교 완료를 주장하지 않는다.

실제 증거: `test-results/org-chart-chart-only/results.json`, `storybook/results.json`, `storybook/results-wheel.json`, 캡처 PNG 및 `_local/final-integration/` 로그. 서버 네트워크 범위를 맞추기 전 connection timeout은 검사 실행 전의 도구 오류였으며, 실제 브라우저 실행 결과와 구분한다.

Build는 성공했지만 기존 `:host-context(.dark)` 처리·bundle size 경고와 Storybook 기존 경고를 보존한다. 경고 해결을 위해 범위를 넓히지 않았다.

**NOT VERIFIED / 기존 제약:** Fixed Chart Only, Safari/Firefox, 실제 모바일 기기·스크린리더, 2,100명 전체 회귀, 모든 회사·폭의 수동 시각 검토, 신규 npm tarball 외부 fresh install, 전체 baseline 픽셀 회귀. 기존 Fixed 390px 내부 스크롤 검사 실패는 원본 작업에서 기준 HEAD에도 재현된 기존 기록이며 이번 통합에서 해당 검사를 재실행하거나 수정하지 않았다.

## 미리보기와 기록

- React: `http://127.0.0.1:6045/react.html?data=100`
- Vanilla: `http://127.0.0.1:6045/vanilla.html?data=100`
- 통합 Storybook: `http://127.0.0.1:6046`

Feature Push 대상은 공식 `https://gitea.hmac.kr/b25027/HMDesign.git`의 `feature/orgchart-package`다. 시작 시 원격 Feature는 기준 HEAD와 같고, 원격 main은 `c45d63a03b84eaac43f01bd400a16488a80e4229`였다. Commit/Push 직전에 다시 확인하며 원격 변경 시 덮어쓰지 않는다.

작업 시작: 2026-10-13 18:18:29 KST. 최초 Estimated Duration: 20–30분. Commit·Push를 포함한 완료 시각/Actual Duration/Variance는 최종 응답에서 기록한다.