HMDesign/packages/org-chart/ai/AI_USAGE.md

@hm-design/org-chart — AI 코딩 도구 사용 안내 (OrgChart)

먼저 AI_GUIDE.md(공통 1~7단계)를 읽고 사용 유형이 OrgChart 또는 OrgChart가 포함된 혼합일 때 이 폴더를 씁니다. 이 폴더(node_modules/@hm-design/org-chart/ai/)는 Core @hm-design/org-chart 0.1.0과 React 어댑터 @hm-design/org-chart-react 0.1.0의 공개 Export·타입에서 확인한 내용만 적습니다.

문서	내용
COMPONENT_CATALOG.md	Core 함수·Handle·옵션, 데이터 계약·Validator, React OrgChart Props, 선택 Entry /hm-dialog
DESIGN_RULES.md	승인된 기본 디자인, 회사 컬러, 공개 CSS 입력 --hm-orgchart-*, 변경 가능/불가 경계
COMPOSITION_PATTERNS.md	Chart Only(React·Vanilla), Full Page(Web + OrgChart), 데이터 생성·변환, 팝업 선택

1. 생성 방식 사전 선택 (필수)

새 조직도 컴포넌트나 조직도 페이지를 만들 때 생성 방식이 요청에 없으면 코드 작성 전에 대화에서 묻습니다(웹페이지에 선택 UI를 만들지 않음). 이미 말했으면 다시 묻지 않습니다.

조직도만 기존 페이지에 삽입할까요, 아니면 레이아웃까지 구성한 새 페이지 전체를 생성할까요?

① 조직도만 생성 (Chart Only) ② 새 페이지 전체 생성 (Full Page)

방식	만드는 것	만들지 않는 것
Chart Only	기존 페이지에 넣을 독립 조직도 컴포넌트: 흰색 캔버스 + 노드 + 연결선, 최초 Fit to View, 일반 휠 Zoom, Pan. Core 내부 기능(그룹 접기, 직원 팝업)은 유지	페이지 제목·기준일·회사 수/인원 요약·설명·Zoom/Fit 버튼 바·배율 안내·Drag & Drop 문구·JSON/디버그 패널·외부 회색 배경·Page Header·Navigation·AI 입력 UI
Full Page	기존 HM UI(보통 Web @hm-design/ui)로 요청된 제목·정보·필터·컨트롤과 전체 배치·반응형 + 조직도 영역	요청에 없는 통계·설명·다운로드·외부 API·추가 메뉴

• layoutMode(Fixed / Auto)는 배치 모드이며 생성 방식 선택을 대신하지 않습니다.
• Chart Only는 Auto 전용입니다: layoutMode: 'auto' + presentationMode: 'chart-only'. Fixed와 함께 쓰면 TypeError. Fixed Chart Only 요청은 Auto로 임의 변경하지 말고 "미지원"으로 보고합니다.
• Chart Only에는 일반 Web 화면의 Navigation(GNB/LNB/DASHBOARD) 의무를 적용하지 않습니다. Full Page에는 Web 화면 규칙(Web COMPOSITION_PATTERNS §1 — 설치 경로 node_modules/@hm-design/ui/ai/)을 적용합니다.

2. 작업 순서

1. 요청을 가변 구조로 정리합니다: 회사 수·ID, 대표이사 유무, 조직 유형과 명칭, 부모·자식 관계, 조직별 하위 조직 수·직원 수, 전체 직원 수, Depth(회사·직원 카드 포함 여부), 집계 기준. 의미가 불분명해 구조·총원이 달라지는 항목만 질문합니다.
2. 데이터 만들기·변환 → validateOrgChartDataset로 검증(§3). 실패 항목을 지워서 통과시키지 않습니다.
3. 기존 Core·React OrgChart를 그대로 씁니다. 새 조직도 엔진·카드·연결선을 만들지 않고 Shadow DOM 내부를 조작하지 않습니다.
4. 공개 옵션으로 표현할 수 없는 요구(예: Fixed Chart Only, 임의 회사 프리셋 등록)는 지원 한계와 대안을 보고합니다.
5. 검증: 요청 대비 회사·조직·Depth·직원·조직장 수가 실제 데이터(organizations, 고유 employees)와 일치하는지, 렌더링·초기 Fit·Zoom/Pan·접기·팝업·키보드를 브라우저에서 확인합니다.

3. 데이터 규칙

• 요청을 정확히 반영: 명시된 회사·조직명·관계·유형·조직 수·직원 수·직위·대표이사 유무를 그대로 만듭니다. 이전 예시의 회사·Depth·인원을 재사용하지 않고 특정 Depth를 강제하지 않습니다.
• 제공 JSON·CSV·Excel 보존: 직원·조직을 임의로 추가·삭제·병합하지 않고 이름·직위·원본 ID·상하 관계를 바꾸지 않습니다(trim·철자 교정 포함). 원본에 없는 근무 상태·관계사·유형을 실제 정보처럼 채우지 않습니다. Core는 CSV/XLSX parser를 제공하지 않습니다 — 변환 결과는 unknown으로 보고 Validator를 통과시킵니다.
• 직원 1회 생성: 대표이사·조직장은 employees에 한 번만 만들고 leaderId로 참조합니다. 별도 지시가 없으면 총원에 포함합니다.
• 복수 회사: 회사마다 parentId: null인 별도 Root. 회사들을 잇는 가짜 상위 조직을 만들지 않습니다. Root에 companyId(하위 조직이 상속).
• 조직 유형: type은 root | division | office | div | cell | team뿐입니다. 업무 명칭(본부·실·부서 …)은 name에 그대로 두고 type은 가장 가까운 값으로 대응한 뒤 그 대응을 보고합니다. 새 enum을 만들지 않습니다.
• 팀·셀 위계(확장형 데이터 생성 규칙): 팀(team)을 셀(cell)의 직접 자식이나 셀의 어떤 하위 계층에도 두지 않습니다. 팀 → 셀은 허용합니다. 제공 데이터가 이 규칙과 충돌하면 원본 경로·ID를 보고하고 조용히 고치지 않습니다(이 규칙은 데이터 생성 규칙이며 Validator가 자동 거절하지는 않음).
• 회사 컬러: Auto 회사 ID는 hanmac, saman, jangheon-industry, jangheon, ptc, halla, baron 7개뿐입니다. 미등록 회사를 기존 ID에 임의로 연결하지 않고 제약으로 보고합니다. 알 수 없는 ID는 Auto에서 TypeError.
• createOrgChartExampleDataset은 기존 fixture template에서 20 / 100 / 300명 예시를 만드는 helper입니다. 임의 인원 생성기나 실제 데이터 변환 API가 아닙니다.

4. 설치·Import

// React
import { OrgChart } from "@hm-design/org-chart-react"            // 기본 Entry, HM UI 불필요
import { JsonOrgChartDataSource, validateOrgChartDataset } from "@hm-design/org-chart"
import engineUrl from "@hm-design/org-chart/engine.css?url"       // Vite 전용 문법
import coreUrl from "@hm-design/org-chart/style.css?url"

• 최소 설치: Core + Vanilla = @hm-design/org-chart. React = @hm-design/org-chart + @hm-design/org-chart-react + React 19 + react-dom. HM Dialog 팝업을 쓸 때만 @hm-design/ui와 그 CSS 진입점 추가.
• Core exports: ., ./style.css, ./engine.css, ./browser(IIFE 전역 window.HMOrgChart, ESM named import용 아님). React exports: ., ./hm-dialog. 내부 src/dist 경로 import 금지.
• stylesheetUrls: { engine, core }는 필수이며 CSS의 URL입니다. Core가 자기 Shadow DOM에 engine → core 순으로 link를 넣습니다. 문서에 CSS를 import하는 것만으로는 카드가 스타일링되지 않습니다. ?url은 Vite 문법이며 다른 도구는 공개 CSS를 실제 배포 URL로 바꿔 전달합니다.
• 글꼴: 기본 Noto Sans KR. 호스트가 font-face를 한 번 등록합니다(Web 패키지 theme.css를 쓰면 이미 포함).
• URL JSON은 HTTP(S)/상대 경로만. file:// fetch는 지원하지 않습니다.

5. 디자인 보호

• 승인된 기본 디자인(카드·회사색·그룹 제목·연결선·Typography·간격)을 바꾸지 않습니다. 의도적 커스터마이징은 공개 CSS 입력 --hm-orgchart-*(외부 테마)로만 하고, 기본값 자체 변경은 사용자 확인이 필요합니다(DESIGN_RULES.md).
• 접근성 미해결: 삼안(#F08300, 약 2.64:1)·장헌산업(#4580A6, 약 4.29:1) 그룹 제목의 흰 글자 대비가 WCAG AA 4.5:1 미달입니다. 숨기거나 PASS로 보고하지 않습니다.
• Font Weight 400 / 500 / 700만 사용합니다.

6. 공개하지 않은 것

chartOnly, showToolbar, showHeader, React ref/imperative handle, data·title·children Props, 회사 프리셋 등록 setter, 카드 교체 API, Compact 모드는 없습니다. Chart Only의 정확한 API는 presentationMode입니다. displayMode: 'readOnly'나 createOrgChartTree는 Chart Only를 대신하지 않습니다.