shkim4
7621934f69
- Usage types are now Web / SW (general mode, viewer mode) / OrgChart / mixed. Shared AI_GUIDE step 1 asks for the SW mode only when the request or the project setting (HMDesign 사용 유형: SW 일반 | SW 뷰어) leaves it open; examples B0/B1/B2 cover "HMDesign SW로 화면을 만들어 주세요", general and viewer. - Missing-component handling in three steps (reuse in the chosen type/mode -> build with that mode's tokens -> HMDesign-consistent style, reported as "AI 구성 값 — 디자인 확인 필요"), plus SW general/viewer separation rules. - sw/ai: AI_USAGE §0 mode selection, catalog §8 lists all 33 SWViewer* exports, DESIGN_RULES §11 viewer tokens, PATTERNS 7 viewer composition; examples B/F marked as general mode. ui/ai and org-chart/ai aligned with the new types. - AGENTS_SNIPPET, AGENTS.md and MAINTAINING updated; copies synced. - scripts/ai-docs.mjs: shared-copy check ignores CRLF/LF (core.autocrlf=true checks out packages/sw as LF and the rest as CRLF). - Verification record updated (code samples typechecked, built and rendered).
85 lines
10 KiB
Markdown
85 lines
10 KiB
Markdown
# @hm-design/org-chart — AI 코딩 도구 사용 안내 (OrgChart)
|
|
|
|
먼저 [AI_GUIDE.md](./AI_GUIDE.md)(공통 1~7단계)를 읽고 사용 유형이 **3 OrgChart** 또는 OrgChart가 포함된 **4 혼합**일 때 이 폴더를 씁니다. 이 폴더(`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](./COMPONENT_CATALOG.md) | Core 함수·Handle·옵션, 데이터 계약·Validator, React `OrgChart` Props, 선택 Entry `/hm-dialog` |
|
|
| [DESIGN_RULES.md](./DESIGN_RULES.md) | 승인된 기본 디자인, 회사 컬러, 공개 CSS 입력 `--hm-orgchart-*`, 변경 가능/불가 경계 |
|
|
| [COMPOSITION_PATTERNS.md](./COMPOSITION_PATTERNS.md) | Chart Only(React·Vanilla), Full Page(Web + OrgChart), 데이터 생성·변환, 팝업 선택 |
|
|
|
|
## 0. 사용 유형 (공통 체계)
|
|
|
|
사용 유형은 **1 Web / 2 SW(SW 일반 모드 · SW 뷰어 모드) / 3 OrgChart / 4 혼합**이고, 소비 프로젝트 설정 값은 `HMDesign 사용 유형: Web | SW 일반 | SW 뷰어 | OrgChart | 혼합(영역별)`입니다. 확인 순서·질문 문구·설정 방법은 [AI_GUIDE.md](./AI_GUIDE.md)가 정의하며 여기서 반복하지 않습니다. 유형·모드 사이를 임의로 섞지 않고, 이 패키지의 컴포넌트·CSS 원본은 수정하지 않습니다.
|
|
|
|
- **OrgChart 선택 시** 아래 §1의 Chart Only / Full Page 질문은 유형 질문과 **같은 메시지에서 한 번만** 묻습니다. 유형·생성 방식이 이미 정해졌으면 묻지 않습니다.
|
|
- **혼합:** 영역별로 패키지를 나눕니다. Full Page의 바깥(Page·Navigation·제목·필터)은 Web(또는 요청한 패키지), 조직도 영역은 OrgChart입니다. SW 화면 안의 조직도는 SW 영역과 OrgChart 영역을 분리하고, SW 모드 규칙은 `node_modules/@hm-design/sw/ai/` 문서를 따릅니다. 두 패키지는 서로 의존하지 않으며 **SW 화면 + 조직도 조합은 패키지에서 검증된 적이 없어 NOT VERIFIED**입니다(결과 보고에 적습니다).
|
|
|
|
### 없는 UI의 처리 (OrgChart 기준 3단계)
|
|
|
|
1. **기존 Core/React 우선:** [COMPONENT_CATALOG.md](./COMPONENT_CATALOG.md)의 컴포넌트·옵션·Props로 먼저 해결합니다(예: `presentationMode`, `autoLayout`, `employeePopup`, `companyTopNodes`).
|
|
2. **없으면 소비 프로젝트에 신규 구현:** 조직도 바깥 UI는 소비 프로젝트에 만들고, 조직도에 맞춘 색·글꼴은 공개 입력 `--hm-orgchart-*`와 [DESIGN_RULES.md](./DESIGN_RULES.md)를 참고합니다. 카드·연결선·배치(승인 디자인)는 바꾸지 않고 패키지 원본·Shadow DOM 내부도 수정하지 않습니다.
|
|
3. **참고할 값이 없으면:** HMDesign 공통 규칙(Font Weight 400/500/700, Light/Dark 없음, 전역 CSS 금지)과 조화되게 구성합니다. 토큰·승인 기록에 없는 값은 결과 보고에 **"AI 구성 값 — 디자인 확인 필요"**로 적습니다.
|
|
|
|
## 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](../../ui/ai/COMPOSITION_PATTERNS.md) — 설치 경로 `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
|
|
|
|
```tsx
|
|
// 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](./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를 대신하지 않습니다.
|