feat(org-chart): support standalone React integration and update guides

docs/org-chart/ai-page-generation-rules.md

@@ -1,12 +1,12 @@
 # HMDesign — AI 조직도 페이지 자동 생성 공통 정책
 
-적용 대상은 Codex·Claude 등 AI 코딩 에이전트가 자연어 또는 제공 데이터에서 **새로 생성하는 독립 조직도 페이지**다. 회사, 조직 유형, 계층, Depth, 인원수에 종속되지 않는다. **고정형(Fixed)과 확장형(Auto/Expanded) 모두 동일한 화면 생성 원칙을 적용한다.** 기존 Full Composition 및 Expanded OrgChart의 승인된 화면은 변경하지 않으며, 기존 P9.5·P-AI1 결과에도 소급 적용하지 않는다.
+적용 대상은 Codex·Claude 등 AI 코딩 에이전트가 자연어 또는 제공 데이터에서 **새로 생성하는 독립 조직도 페이지**다. 회사, 조직 유형, 계층, Depth, 인원수에 종속되지 않는다. **고정형(Fixed)과 확장형(Auto/Expanded) 모두 동일한 화면 생성 원칙을 적용한다.** 기존 Full Composition·Expanded OrgChart·Department Colors·Overview의 승인된 화면은 변경하지 않으며, 기존 P9.5·P-AI1 결과에도 소급 적용하지 않는다.
 
 ## 1. 실행 방식과 적용 우선순위
 
 - 사용자가 코딩 에이전트에 요청을 전달하면 에이전트가 조직 JSON과 실제 페이지 코드를 생성한다. 웹페이지에 AI 채팅창이나 생성 입력 UI를 추가하지 않는다. 브라우저 AI Provider 연결은 이 실행 방식의 전제가 아니다.
-- 현재 사용자의 명시적 요청 → 이 정책의 AI 조직도 전용 범위 → 충돌하지 않는 기존 AGENTS.md·CLAUDE.md 및 HM 공개 계약 순으로 적용한다. 관련 문서는 필요한 부분만 읽는다.
-- 이 정책의 기본 화면은 조직도만 표시한다. 일반 업무 화면의 GNB/LNB/DASHBOARD Navigation 의무를 가져와 메뉴나 Header를 추가하지 않는다. 사용자가 Navigation을 요청한 경우에만 기존 단일 Navigation 계약을 적용한다.
+- 사용자 요청에서 명시한 UI 요구사항 → 이 정책의 AI 조직도 전용 범위 → 기존 OrgChart Core의 디자인·동작 규칙 순으로 적용한다. 충돌하지 않는 AGENTS.md·CLAUDE.md와 HM 공개 계약·데이터 검증·접근성 규칙은 계속 준수한다. 관련 문서는 필요한 부분만 읽는다.
+- 이 정책의 기본 출력은 **White Canvas + OrgChart Nodes + Connectors**인 Chart Only 화면이다. 일반 업무 화면의 GNB/LNB/DASHBOARD Navigation 의무를 가져와 메뉴나 Header를 추가하지 않는다. 사용자가 Navigation을 요청한 경우에만 기존 단일 Navigation 계약을 적용한다.
 - 기존 Core·React Wrapper·Theme·카드·Storybook을 요청 없이 변경하지 않는다. 필요한 공통 변경은 사유와 영향 범위를 먼저 보고한다. 새 조직도 엔진이나 디자인 시스템은 만들지 않는다.
 
 ## 2. 요청을 가변 구조로 정리
@@ -65,32 +65,69 @@ Depth에 회사나 직원 카드를 포함하는지, 조직별 인원이 직접
 - 레이아웃·Depth·대표이사 표현·다중 회사·TB/LR/Hybrid·Zoom/Pan·접기·팝업은 실제 공개 API가 지원하는 범위만 사용한다. 직원 연결 방향을 전체 트리 방향 지원으로 해석하지 않는다.
 - 요청 구조나 최소 화면을 공개 API로 정확히 표현할 수 없으면 지원 한계와 대안을 보고한다. 임의 구현·합성 화면을 기존 Core 결과라고 주장하지 않는다. 공통 기능 확장이 필요하면 별도 승인 범위로 분리한다.
 
-## 6. 조직도 중심의 독립 페이지
+## 6. Chart Only 독립 페이지
 
-- AI가 생성하는 Fixed 페이지와 Auto/Expanded 페이지 모두 요청한 조직도만 표시하는 원칙을 따른다. 레이아웃 모드가 다르다는 이유로 추가 UI를 허용하지 않는다. 해당 모드에서 지원되는 기존 Zoom/Pan·접기·펼치기·직원 정보 보기 등 탐색 기능은 유지한다. 요청 데이터가 달라지면 계층과 렌더링도 그 데이터에서 달라져야 한다.
-- 사용자가 별도로 요청하지 않는 한 조직도 외의 설명 문구, 안내 패널, 테스트 정보, JSON 미리보기 또는 불필요한 추가 UI를 표시하지 않는다. AI 입력창, 사용 설명, 생성 조건 설명, 별도 통계, 개발 문구, Navigation과 추가 메뉴도 동일하게 제외한다. 저장·게시·다운로드·운영 API는 요청 범위 밖에서 추가하지 않는다.
-- 기존 카드·회사색·연결선·직원 팝업 디자인과 Theme를 유지한다. 지원되는 공개 옵션으로 불필요한 내장 설명·요약을 제외하되 탐색 기능은 유지한다. 공개 옵션이 없으면 제약을 보고하며 Shadow DOM을 임의 조작하거나 공통 CSS를 고쳐 감추지 않는다.
-- 실제 콘텐츠 크기와 컨테이너를 기준으로 지원되는 초기 자동 배치·Fit을 적용한다. 임의 고정 좌표·배율을 회사별 템플릿으로 만들지 않는다. 전체 개요와 확대 시 읽기, 내부 이동, 외부 가로 넘침을 함께 확인한다.
-- 최소 배율, 많은 직원, 긴 명칭, 깊은 계층, 여러 회사에서 전체 Fit이 불가능하면 잘림·읽기·탐색 한계를 보고한다. 이를 해결하려고 이름·인원·Depth를 줄이지 않는다.
-- 새 페이지는 독립 React entry로 제공한다. 기존 Full Composition·Expanded OrgChart·Storybook 메뉴·P9.5·P-AI1 결과를 교체하지 않는다.
+### 6.1 기본 출력과 제외 요소
+
+기본 결과물은 **White Canvas + OrgChart Nodes + Connectors**다. 기존 흰색 조직도 영역을 최상위 화면으로 사용한다.
+
+- 회사·조직 그룹, 요청에 포함된 대표자·본부장·팀장·직원 카드, 연결선과 필요한 화살표, 회사별 컬러를 표시한다. 조직명·직위·직원 이름 등 조직도를 구성하는 필수 텍스트는 유지한다.
+- 해당 모드에서 지원되는 기존 Core의 그룹 접기·펼치기, Zoom/Pan·직원 정보 보기 등 조직도 내부 탐색 기능은 유지한다. 외부 조작 UI의 기본 제외를 Core 기능 삭제로 해석하지 않는다.
+- 사용자가 명시적으로 요청한 요소만 아래 기본 제외 목록의 예외로 추가한다. 한 요소의 요청을 다른 부가 UI의 승인으로 확대하지 않는다.
+
+기본 제외 요소:
+
+- 페이지 제목(예: 가상 조직도), 기준일, 회사 수·전체 인원 요약 문구
+- 확대·축소·100% 복원·Fit to View 버튼 바 등 외부 컨트롤
+- Zoom 배율 안내, Drag & Drop ON/OFF 상태 문구, 조작 방법 안내
+- 설명 문단, 생성 조건 설명, 사용 설명·안내 패널
+- JSON 미리보기, 테스트 결과·디버그 패널, 별도 통계 대시보드, 개발 안내
+- 외부 회색 배경, 불필요한 Page Header·Wrapper·바깥 여백
+- AI 채팅·생성 입력 UI, Navigation·추가 메뉴
+
+저장·게시·다운로드·운영 API는 요청 범위 밖에서 추가하지 않는다. 테스트 결과·가정·제약은 조직도 화면 대신 작업 완료 보고서에 기록한다.
+
+### 6.2 흰색 Root 캔버스와 초기 배치
+
+- 캔버스가 화면의 기본 Root 영역을 차지하며 배경은 흰색이다. 외부 회색 영역이나 불필요한 바깥 여백을 생성하지 않는다. 사용자가 지정한 캔버스 크기가 있으면 이를 우선한다.
+- 초기 배치는 조직도 전체의 실제 Bounds와 캔버스 크기를 기준으로 가로·세로 중앙 정렬한다. 노드·그룹·연결선을 포함한 전체 범위와 위치를 확인하며 임의 고정 좌표·배율을 회사별 템플릿으로 만들지 않는다.
+- 기본 배율은 조직 구조와 캔버스 크기를 고려해 지원되는 초기 자동 배치·Fit으로 결정한다. 대규모 조직도에서 전체 Fit만을 위해 텍스트를 지나치게 작게 만들지 않는다. 전체 개요와 확대 시 읽기, 내부 이동, 외부 가로 넘침을 함께 확인한다.
+- 기존 Zoom/Pan을 재사용하고 이를 위한 내부 이벤트 기능을 유지한다. 초기 Fit은 배치 동작이며 Fit to View 버튼 바를 렌더링해야 한다는 뜻이 아니다. 외부 컨트롤 버튼은 명시적 요청이 있을 때만 렌더링한다.
+- 기존 카드·회사색·연결선·직원 팝업 디자인과 Theme를 유지한다. 캔버스 배경은 실제 선언된 공개 Theme·스타일 경로를 확인해 적용하며 없는 Token을 추측하지 않는다.
+- 지원되는 공개 옵션으로 불필요한 내장 설명·요약·컨트롤을 제외한다. 옵션이 없거나 공개 API로 흰색 Root·중앙 배치를 구현할 수 없으면 제약을 보고한다. Shadow DOM 임의 조작, 공통 CSS 변경, Core·React Wrapper의 불필요한 공개 API 변경으로 해결하지 않는다.
+- 최소 배율, 많은 직원, 긴 명칭, 깊은 계층, 여러 회사에서 전체 Fit과 가독성을 함께 만족할 수 없으면 잘림·읽기·탐색 한계를 보고한다. 이름·인원·Depth를 줄이거나 단순히 내용을 숨겨 잘림·레이아웃 문제를 감추지 않는다.
+
+기본 구성은 다음과 같다.
+
+- 기존 구성: Page Background → Header → Controls → Description → White Canvas → OrgChart
+- 앞으로 생성할 기본 구성: **White Canvas → OrgChart**
+
+### 6.3 Fixed / Auto 공통 적용과 기존 화면 보호
+
+- **Fixed:** 승인된 기존 카드·연결선 디자인과 해당 모드의 기존 배치를 재사용하되, 새 AI 생성 독립 페이지에는 Chart Only 구성을 적용한다.
+- **Auto / Expanded:** 기존 Core 자동 배치를 재사용하되, 조직도 외부의 설명·테스트·조작 패널을 제외한다.
+- 두 모드 모두 가변 계층·정확한 인원·제공 데이터 보존 규칙을 유지한다. 레이아웃 모드가 다르다는 이유로 추가 UI를 허용하지 않는다. 요청 데이터가 달라지면 계층과 렌더링도 그 데이터에서 달라져야 한다.
+- 새 페이지는 독립 React entry로 제공한다. 기존 Full Composition·Expanded OrgChart·Department Colors·Overview·Storybook 메뉴·P9.5·P-AI1 결과를 교체하지 않으며 기존 Storybook 페이지의 제목·컨트롤·설명 UI를 삭제하지 않는다.
 - Guard나 문서 분석기의 제약 때문에 요청하지 않은 Navigation·통계·설명 UI를 추가하지 않는다. 정책과 검사 도구가 충돌하면 원본 검사 결과와 원인을 보고하며 도구나 공통 계약을 이번 범위 밖에서 임의 수정하지 않는다.
 
 ## 7. 생성 절차와 최종 통합 검증
 
+> P10.2 구현 한계 확인: 이 정책은 목표이며 현재 Core의 모든 내장 UI를 끄는 공개 옵션을 의미하지 않는다. 실제 Auto/Fixed 독립 검사는 Chart Only PARTIAL이다. Auto의 기본 초기 배치는 가로 중앙·상단 정렬이고, Vanilla의 공개 `fitToView()`는 전체 Bounds 기준 가로·세로 중앙 배치를 지원한다. React Wrapper에는 이를 호스트가 직접 호출할 공개 handle/ref가 없다. 지원 범위·후속 개선 후보는 [공통 사용 가이드](org-chart-usage-guide.md#chart-only-정책과-현재-기능의-관계)를 확인한다. 기존 화면·Core·공개 API를 변경하거나 내장 DOM을 숨겨 정책 완료로 보고하지 않는다.
+
 1. 요청을 분석하고 현재 작업 경로·Git 상태·기준 커밋·공개 API를 확인한다. 기존 미커밋 변경과 병렬 작업, 서버 포트를 보호한다.
 2. 회사별 계층·유형·Depth·조직 수·직원 수·조직장 집계 조건을 정리한다. 충돌하는 필수 조건만 확인한다.
 3. 요청에서 가상 데이터를 생성하거나 제공 데이터를 보존해 변환한다. 계획과 변환 대응은 화면 밖에 기록한다.
 4. 기존 Contract와 추가 정합성 검사를 통과시킨다. 이는 잘못된 데이터를 렌더러에 넘기지 않기 위한 필요한 사전 확인이다.
-5. 공개 Core·React Wrapper로 조직도만 있는 독립 페이지를 생성한다. 새로운 구조를 고정된 사례로 바꾸지 않는다.
+5. 공개 Core·React Wrapper로 흰색 Root 캔버스에 조직도만 있는 Chart Only 독립 페이지를 생성한다. 실제 Bounds 기준 가로·세로 중앙 배치와 연결선을 확인한다. 새로운 구조를 고정된 사례로 바꾸지 않는다.
 6. 구현 후 변경 범위의 코드·diff·계층·인원·중복 집계·보존·핵심 동작을 한 번에 검증한다. 필요한 Typecheck·Build·Guard를 수행하고 실제 브라우저에서 확인한다. 이미 성공한 동일 조건 검사를 반복하지 않고 수정·실패 범위만 다시 확인한다.
-7. 390/768/1280/1440px에서 초기 Fit, 콘텐츠/내부 스크롤, 줄바꿈, 카드·연결선·회사색, Zoom/Pan·접기·팝업, 키보드·포커스를 관련 사용 요소에 맞게 확인한다. 실제 실행 URL과 화면 캡처를 보고한다.
+7. 390/768/1280/1440px와 사용자 지정 캔버스 크기에서 흰색 Root, 실제 Bounds 기준 초기 중앙 정렬·배율·가독성, 외부 Header·Controls·Description 및 상태 문구의 기본 제외, 콘텐츠/내부 스크롤, 줄바꿈, 카드·연결선·회사색, Zoom/Pan 내부 이벤트·접기·팝업, 키보드·포커스를 관련 사용 요소에 맞게 확인한다. 실제 실행 URL과 화면 캡처를 보고한다.
 8. 요청 대비 회사·조직·Depth·직원·조직장 집계, 생성 파일, 재사용 API, 가정, 제약, PASS/PARTIAL/FAIL와 NOT VERIFIED를 간결하게 보고한다. Guard 원본·정적·Runtime·STYLE 디자인 의도/최종 상태를 구분하고 미검증을 덮어쓰지 않는다.
 
-정책 작성·연결만 수행하는 작업에는 화면 구현·빌드·브라우저 실행·전체 회귀를 추가하지 않는다. 데이터 생성·렌더링 기능을 실행하지 않았다면 정책 작성 완료를 범용 런타임 지원 PASS로 보고하지 않는다.
+정책 작성·연결만 수행하는 작업에는 화면 구현·빌드·브라우저 실행·전체 회귀를 필수로 추가하지 않는다. 독립 실험 환경에서 선택적으로 화면을 검증할 수 있으나 기존 Storybook·AI Playground 테스트 페이지는 수정하지 않는다. 화면 검증을 수행하지 않았다면 **VISUAL NOT VERIFIED**로 보고한다. 데이터 생성·렌더링 기능을 실행하지 않았다면 정책 작성 완료를 범용 런타임 지원 PASS로 보고하지 않는다.
 
 ## 8. 범위 보호와 완료 기준
 
-- 기존 P9.5·P-AI1 산출물과 검증 기록을 보존한다. 이번 정책 작성·연결 범위는 이 파일과 AGENTS.md·CLAUDE.md의 참조 안내이며 화면·데이터·Core 변경을 포함하지 않는다.
+- 기존 P9.5·P-AI1 산출물, P10 PARTIAL과 기존 Guard FAIL 10건의 검증 기록을 보존한다. 기존 P10.1 작업 폴더와 AI Playground Worktree를 수정하지 않으며 삼안 500명 테스트 페이지를 이관하지 않는다. 이번 정책 작성·연결 범위는 이 파일과 AGENTS.md·CLAUDE.md의 참조 안내이며 화면·데이터·Core 변경을 포함하지 않는다.
 - 이 정책을 참조한 생성 요청만으로 Stage·Commit·Push·Merge를 승인받은 것으로 간주하지 않는다. 현재 사용자의 작업별 Git 지시를 우선하며 이번 정책 작성에서는 해당 작업을 진행하지 않는다.
 - 서로 다른 회사·대표이사 유무·조직 유형·Depth·분기 수·직원 수가 같은 요청 분석 → 데이터 변환 → Contract 검증 → Core 소비 절차로 처리돼야 한다. 특정 테스트 수치나 전용 템플릿에 의존하면 완료가 아니다.
 - 생성 작업의 완료는 명시 조건의 일치, 제공 데이터 보존, 기존 Core의 실제 렌더링, 요청 범위의 최소 UI, 실행 증거로 판단한다. 미지원 구조를 지원한 것처럼 보고하거나 분석·JSON만으로 화면 생성 성공을 선언하지 않는다.