HMDesign/docs/org-chart/implementation-report-p5-23.md

HMDesign OrgChart P5-2 + P5-3 구현 보고

RESULT: PARTIAL — 요청된 기능 구현·변경 범위 검증은 PASS. 참고 SVG 두 개의 원본 일치와 최종 카드 디자인 승인, 물리적 터치·스크린리더 검증은 NOT VERIFIED.

작업 환경 및 시간

• 실제 폴더: D:\디자인시스템\HMDesign-orgchart-package
• 브랜치: feature/orgchart-package
• HEAD: a92913d6bcc950dacc6fdf21cf3b0843ee79416d (시작/완료 동일)
• origin: https://gitea.hmac.kr/b25027/HMDesign.git
• P5-1B 채팅 완료 상태와 미커밋 변경을 확인한 뒤 확장. 시작 시 변경 12파일·신규 검증 스크립트 1개를 보존. 시작 diff는 test-results/org-chart-p5-23/p5-1b-before.patch, 비교 dist는 같은 폴더의 baseline-dist.
• 작업 범위: BOTH — 공통 Core·HTML·React와 요청된 기존 Expanded Story. 운영 프로젝트·main 수정 없음. 신규 페이지 Navigation 없음(임베드 조직도 컴포넌트).
• Started At: 2026-10-12 19:27:14 KST
• Completed At: 2026-10-12 19:52:30 KST
• Actual Duration: 25분 16초
• Estimated Duration: 60–90분 (확인 10분 / 구현 35–55분 / 검증 15–25분)
• Variance: 최초 예상 하한보다 34분 44초, 상한보다 64분 44초 빠르게 완료.

기능 결과

항목	결과·근거
회사 전체·단일·복수·해제	PASS. 독립 Root Forest를 가로 배치. undefined=전체, []=빈 상태. 원본 직원 수 불변, 선택 인원 별도 표시.
회사 ID·계층	PASS. 선택적 Organization.companyId, 부모 상속, 다른 회사 부모·자식 연결 오류. 기존 JSON은 알려진 Root leader affiliation 또는 기존 companyId fallback.
회사별 최상위	PASS. 기존 Root·Employee 그대로 사용. 직위·이름·조직명 override, card/titleOnly/hidden, employeeId/null. 예시는 회장·사업총괄·본부장 등과 최상위 직원 없는 바론. 이미지 URL 검증과 표시 경로 지원; 별도 프로필 이미지 변경의 시각 검증은 NOT VERIFIED.
그룹 타이틀	PASS. 전체 타이틀 native button, Enter/Space, aria-expanded, 빈 그룹 disabled. 조직장 유지·직원/하위 조직 숨김. 부모 재확장·회사 재선택 시 유효한 자식 상태 보존. 별도 링크 아이콘으로 이동.
재귀 자동 배치	PASS. dabeng 6.0.0 Forest 유지. 형제 가로 배치, 자신의 부모 아래 자식, 동일 Depth 높이 예약. Small 0–2, Medium 0–3, Large 0–4 Depth. 카드 겹침 0, 실제 DOM parentId 일치.
Zoom/Pan/Fit	PASS. 기본 5–300%, 설정 min/max/step. 확대/축소/100%/Fit, 현재 배율. Ctrl/Command+휠, 드래그, 방향키. 일반 휠에는 preventDefault하지 않음. 직원 카드 드래그 팝업 억제. 합성 touch PointerEvent 경로 PASS; 물리적 터치는 NOT VERIFIED.
회사 테마	PASS. 기존 7개 ID·메인 색상 모두 정확. P5-0 파일 변경 없음. 보조색 변수 보존. 삼안·장헌산업 제목은 대비를 위해 중립 짙은 텍스트.
직원 Border	PASS. 직원 회사 affiliation의 기존 preset(미등록 affiliation은 조직 회사)을 CSS 변수로 참조. 실제 SVG endpoint와 top/left/right 면 일치, 나머지 중립. 3방향 실제 예시 모두 확인. inset accent 두께 변수로 외형 크기 보존.
확장형 카드	PASS(기능). 공통 비원형 사람 아이콘, 실제 이름·직위, Noto Sans KR, 홍길동→홍 길 동. Auto 전용 Width/Height/Padding/Border/Radius/사진/Font/간격 변수. 승인 SVG 재현은 NOT VERIFIED.
직원 정보 팝업	PASS. 공통 Core dialog, 변환 Forest 밖, focus·Escape 복귀. 표시 override에도 원본 직원 identity·callback 데이터 유지.
Fixture	PASS. Small 20명·3회사, Medium 100명·5회사, Large 300명·7회사. 고유 Employee ID, 유효 parentId·leader membership, 중복 없는 조직장 집계. 고정 JSON·결정적 생성 스크립트. 실제 개인정보 없음.
HTML·React	PASS. 실제 HTML 예시와 StrictMode React Story의 ID·직위·이름·크기·회사·색·방향 일치. 필터 로직은 Story가 아닌 Core. DataSource 계약 유지, API/DB 구현 없음.
Fixed	PASS. P5-1B 시작 dist와 현재 dist의 카드 좌표·크기·SVG·이름·직위·색 정확 비교 및 공통 팝업 최소 회귀. Fixed CSS·SVG·Full Composition Story 변경 없음.
Storybook	PASS. 사용자 메뉴 4개 유지. Expanded 하나에 20/100/300명·회사 체크박스·전체/해제 및 공통 확대 도구.

실제 사용 요소·선택 근거

React Story는 공개 @hm-design/ui의 Button, Checkbox, Label, Select/Trigger/Value/Content/Item을 실제 렌더링한다. Label은 실제 control ID와 연결한다. FilterBar를 검토했으며 이번 도구는 검색·조회 조건이 아니라 Fixture 전환과 즉시 회사 표시 상태이므로 기존 Pattern의 목록 검색 구조를 강제하지 않았다. 체크박스 복수 선택과 Select를 직접 조합한다.

공통 Core는 React 의존성 없는 명시적 HTML Runtime adapter다. 그룹·Zoom native button과 HTML 예시의 native select/checkbox/label은 이 계약의 접근성 요소이며 HM React UI 모방이 아니다. Core·Wrapper·DataSource 역할을 유지한다.

성능 측정

Windows 로컬 Headless Chrome, 1440×1000, 실제 300명 JSON. 아래는 측정치이며 임의 성능 기준에 따른 PASS 판정이 아니다.

처리	실측
Small 최초 mount (모듈·CSS + 2 animation frames)	93.3ms
Medium 최초 mount (동일 방식)	93.9ms
Large 최초 mount (동일 방식)	195.6ms
300명 그룹 접기 (native click + 2 frames, 두 측정)	222.7 / 281.9ms
자동화 Enter/Space 접기·펼치기 (조작·focus·프레임 대기 포함)	317.9–656.8ms
300명→단일 회사 선택 + 재배치 2 frames	42.0ms
Zoom + 60회 panBy + 1 frame (두 측정)	20.5 / 0.9ms

대용량 전체 DOM 누락·중복·카드 겹침 없음. 위 pan 일괄 호출은 실기기 프레임율/FPS를 뜻하지 않는다. 최초 mount 수치에는 초기 스크립트 경로 비용이 포함되며 다운로드 성능 인증이 아니다. 별도 가상화·엔진 교체·신규 라이브러리 설치 없음.

변경 범위 검증

• Core typecheck PASS; Core ESM/IIFE 및 선언 build PASS.
• React Wrapper typecheck·선언/ESM build PASS; 앱/Story TypeScript 검사 PASS.
• Expanded Story만 소비하는 독립 React bootstrap의 Vite production build PASS. 500kB 초과 chunk 경고 있음(기존 Core 이미지 자산 포함); 빌드 오류 아님. 결과: test-results/org-chart-p5-23/react-build/dist/index.html.
• 영향 범위 단위 테스트 7/7 PASS. Node 20의 globSync 부재로 최초 실행 불가였으며, 제공된 Node 런타임으로 정상 실행. 기존 전체 테스트를 반복하지 않음.
• 브라우저 96/96 PASS, 신규 console/runtime error 0. 실행기 선택자 오류를 수정하고 미완료 범위만 이어서 확인. 390/768/1280/1440px 가로 넘침·핵심 도구 확인.
• git diff --check PASS. 원래 CRLF 전환 안내는 공백 오류와 구분.
• 원본 Guard: PARTIAL/STORYBOOK profile, staticStatus PASS, 원본 status PASS, issues 0. Runtime은 자체 수행하지 않으므로 NOT VERIFIED.
• CSS 원본 styleEvidence: STATIC PASS, RUNTIME NOT VERIFIED, DESIGN_INTENT NOT VERIFIED, FINAL NOT VERIFIED.
• 별도 browser/runtime 증거 연결: fingerprint 일치 linked=true. 결합 status와 styleVerification은 NOT VERIFIED 유지. STORYBOOK profile에는 Production --result bootstrap 판정이 없으며 최종 디자인 승인·개별 CSS 적용 전 상태 검증도 미완료. 직접 실행된 React 브라우저 결과 PASS와 혼동하지 않음.
• Guard는 Story host 소비 범위이며 Core 내부의 모든 CSS를 승인하는 검사가 아니다. Core 연결 방향·색상·좌표는 별도 브라우저 근거에 기록.
• P5-1B 879/879 PASS 기록 보존. 과거 전체 회귀·기존 미검증 결과를 새 결과로 덮어쓰지 않음.

자동 승인 검토는 0.0.0.0 Storybook 실행을 LAN 노출 위험으로 거부했다. 127.0.0.1로만 바인딩한 안전한 실행은 승인·검증됐으며, 초기 sandbox 서버는 종료했다. 기능·작업에 남은 승인 차단 없음.

실행 URL·캡처·원시 근거

• Expanded OrgChart
• HTML 예시
• test-results/org-chart-p5-23/browser.json, guard.json, runtime.json, combined.json
• storybook-large-1440.png: 7회사·300명 Fit 전체 화면.
• storybook-small-hanmac-100.png: 한맥기술·100%·상단/좌측/우측 Border와 연결선.
• storybook-{390,768,1280,1440}.png: 반응형 실제 React 화면.
• html-{small,medium,large}-fit.png, fixed-1440.png: HTML Fixture 및 최소 Fixed 회귀.

이번 추가·수정 파일

기존 P5-1B 변경 전체를 이번 변경으로 주장하지 않는다. P5-1B의 data-expanded.json, expanded-layout.test.ts, verify-p5-1b.mjs는 그대로 보존했다.

• Core: packages/org-chart/src/core/{index,types,render,employee-card,expanded-content,expanded-layout}.ts; 신규 expanded-company.ts, expanded-company.test.ts, expanded-viewport.ts.
• 데이터 계약: packages/org-chart/src/data/{types,validate}.ts, packages/org-chart/src/index.ts, docs/org-chart/data-contract.md.
• 스타일: packages/org-chart/src/styles/org-chart-expanded.css.
• React: packages/org-chart-react/src/OrgChart.tsx.
• Story: src/org-chart/org-chart-expanded.stories.tsx, org-chart-stories.css.
• HTML/Fixture: examples/org-chart/prepare.mjs; 신규 expanded.html, expanded-app.js, expanded.css, create-expanded-fixtures.mjs, data-expanded-small.json, data-expanded-medium.json, data-expanded-large.json, verify-p5-23.mjs.
• 문서: packages/org-chart/README.md, packages/org-chart-react/README.md, 이 보고서.
• generated dist·검증 JSON·스크린샷·비교본은 기존 gitignore의 test-results/dist 경로. 소스 Stage 없음.

남은 미검증·Git 상태

참고 Group 3391.svg, Group 1171288761.svg의 원본 구조·최종 디자인 일치, 물리적 터치, 스크린리더 음성, 다른 브라우저·운영 소비자, 전체 heap/GC 회수, 전체 과거 회귀는 NOT VERIFIED. 최상위 profileImage 변경의 별도 시각 검증도 NOT VERIFIED. 기존 미검증을 기능 PASS로 제거하지 않았다.

Commit·Push·Merge·Stage 미진행. Reset/Rebase/Force Push/Clean 미진행. main·운영 프로젝트·Fixed SVG/CSS 미수정. P5-4 미시작.