HMDesign/docs/org-chart/consistency-review-p11-6.md

# HMDesign OrgChart P11.6 — 최종 정합성·병합 준비 검증

RESULT: **PARTIAL — 검증한 기능·정합성 PASS, 배포 플랫폼 일부 NOT VERIFIED.**
기술 판정: **CONDITIONALLY READY.** 아래 Feature Git 완료 확인을 전제로 하며 실제 main Merge·Push·배포 승인을 뜻하지 않는다.

## 1. 기준과 범위

- 작업 경로: `D:\디자인시스템\HMDesign-OrgChart`.
- 작업 시작: 2026-10-14 08:45:22 KST. 증거 생성·검토: 같은 날 08:45–08:51 KST.
- Feature: `feature/orgchart-package`, 검사 전 HEAD `cd7a0db916c3eed75e5ebf4155828bf3727d21d5`.
- 공식 origin: `https://gitea.hmac.kr/b25027/HMDesign.git`.
- 읽기 전용 원격 조회로 Feature HEAD 일치 및 main `c45d63a03b84eaac43f01bd400a16488a80e4229` 확인.
- 초기 Working Tree: P11.5 관련 5개 수정, Untracked 0. 기존 변경을 모두 보존했다.
- 초기 Git user.name은 `김수현`, email은 `shkim4@samaneng.com`. 이번 Commit에만 요청된 `b25027` / `shkim4@samaneng.com` 작성자를 지정한다.
- P11.4 `deployment-rollback-review-p11-4.md`는 없음. 재작성·Stage하지 않는다. 외부 보관 위치 NOT VERIFIED, 기존 롤백 PARTIAL 유지.

P11.6은 정합성 검사 및 같은 작업 범위의 Feature Commit·일반 Push 준비다. 신규 화면·Story·Props·기본 회사색·승인 디자인·Workflow·Docker 정의를 수정하지 않았다.

## 2. 변경 파일

이번 Commit 대상은 다음 6개로 한정한다.

1. `packages/org-chart/src/styles/org-chart-content.css` — Fixed interactive composition/stage 전용 입력, 투명 fallback.
2. `packages/org-chart/src/styles/org-chart-readonly.css` — Fixed readOnly composition/stage 전용 입력 및 기존 bg-content fallback.
3. `packages/org-chart/src/styles/org-chart-expanded.css` — Auto 내부 viewport 전용 입력 및 기존 bg-surface fallback.
4. `docs/org-chart/org-chart-usage-guide.md` — P11.5 배경 설정과 P11.6 한정 검증 근거.
5. `docs/org-chart/design-approval.md` — 사용자 확정 Expanded 내부 흰색 변경 기록.
6. `docs/org-chart/consistency-review-p11-6.md` — 이 보고서.

P11.6에서 추가 제품 오류를 발견하지 않아 제품 코드 추가 수정은 없다. `test-results`, `_local`, node_modules/dist, 캡처·로그·개인 설정·Cell 실험은 제외한다.

## 3. Core·React·데이터·사용 가이드 정합성

**PASS — 실제 소스·공개 exports·타입과 가이드의 관련 예제 대조.**

- Core의 주 Entry·CSS 2개·IIFE browser Entry 및 DataSource/Validator/집계/이동/모듈 export가 manifest와 일치한다. React/Vanilla 모두 같은 Core를 사용한다.
- Fixed 기본/interactive/readOnly, Auto TB/LR/Hybrid, 독립 interaction flags, Fit/Zoom/Pan, 그룹 접기, 직원 팝업, 기본 OFF Drag & Drop, 회사 선택과 데이터 갱신의 지원 범위·제약이 타입·구현과 일치한다.
- Chart Only는 Auto 전용 `presentationMode: 'chart-only'`, 초기 Fit·direct wheel 기본값. Fixed 조합은 TypeError로 거부하며 신규 Fixed Chart Only를 만들지 않았다.
- 데이터의 schemaVersion, Organization/Employee/affiliation 및 metadata, nullable 필드, 계층·조직장 참조 제약을 실제 타입/Validator와 대조했다. 문서 JSON 2개를 현재 빌드의 Validator로 실행해 통과했다.
- React 기본 Entry는 `OrgChart`와 UI-independent 타입을 제공한다. `/hm-dialog`만 HMEmployeeDialog를 연결하며 employeePopup의 명시적 선택이 필요하다. 과거 lazy HM UI MISSING_EXPORT 문제를 현재 미해결 상태로 해석하지 않는다.
- Core 옵션 전달 및 CSS URL 연결은 기존 Props 그대로다. 배경 입력은 class/style/외부 CSS 상속 경로이며 배경용 Props를 추가하지 않았다.
- optionKey 기반 값 비교와 stylesheet URL primitive 의존성, 데이터 identity reload, Auto setter를 실제 Wrapper에서 확인했다. 동일 값의 옵션 객체만 바뀌면 create/destroy를 반복하지 않는다. 이 생명주기 전체를 새 브라우저 검사했다고 확대하지 않는다.
- React peer `^19.0.0`, 실제 설치 React 19.3.0. 현재 소스·전체 타입/빌드와 기존 P11.5 React 브라우저 증거를 확인했다. 다른 React major/SSR 지원은 NOT VERIFIED.

가이드의 TS/TSX 블록 **14개**를 공개 빌드 `.d.ts` 기준 strict·skipLibCheck=false로 통과시켰다. 문서에서 앞 절의 문맥을 요구하는 블록 2개에만 Import/데이터 문맥을 보충했다. JS 부분 예제는 실제 API와 수동 대조했으며 모든 예제를 별도로 브라우저 실행하지 않았다.

## 4. 배경·외부 테마·Shadow DOM

**PASS — CSS 대조, P11.5 증거 재사용 및 추가 Computed Style 검사.**

- `--hm-orgchart-fixed-canvas-background`는 Fixed composition/stage에 적용한다. readOnly는 기존 `--hm-orgchart-bg-content` → `#F5F8FB`, interactive는 기존 transparent를 유지한다.
- `--hm-orgchart-expanded-canvas-background`는 Auto 내부 viewport에 적용한다. 기존 `--hm-orgchart-resolved-bg-surface` 경로를 보존하고 기본은 `#FFFFFF`다. 외부 카드/프레임/Storybook 페이지와 직원 카드에는 전용 입력을 전파하지 않는다.
- 두 입력은 var 참조로 소비하며 내부 요소에 기본 custom property를 선언해 호스트 상속을 차단하지 않는다. bg-surface/bg-content 기존 외부 테마, host 상속·Shadow :host·소비자 inline의 우선순위를 유지한다.
- React/Vanilla 각각 기본/Fixed만 custom/Expanded만 custom/서로 다른 custom/제거 후 기본값 복구를 추가 검사했다. 같은 페이지의 Chart Only sibling과 다른 runtime에 영향이 없었다.
- Chart Only의 전용 Expanded custom 배경 및 제거 후 흰색 복구를 실제 viewport computed style로 확인했다.
- P11.5의 진짜 외부 CSS `@import + :host`, 반대 유형 입력 무영향, 같은 composition/stage 입력 결과를 재사용했다.
- 깨끗한 Core CSS와 P11.5 산출물은 줄바꿈 정규화 후 동일하다. Core/React 기본 JS 산출물은 byte 동일하다. 원본의 정상 dist를 수정하지 않았다.

## 5. Storybook·승인 디자인·Chart Only

**PASS — P11.5 한정 회귀 증거 재사용, 새 빌드의 4개 화면 렌더 확인.**

- Overview: 회사 로고·현황·카드·텍스트·외부 Container의 P11.5 주요 computed style/geometry 동일성 재사용.
- Department Colors: 6종 Gradient·그룹/직원·파견/휴직·`홍 길 동` 및 기존 프레임의 P11.5 동일성 재사용. Expanded 7개 회사색과 분리 유지.
- Full Composition: Fixed 기존 BG·배경 이미지/자산·카드·연결선/화살표·통계·중앙/반응형 구조에 추가 변경 없음. P11.5 before/after Full Composition PNG byte 동일성과 주요 스타일 동일성 재사용.
- Expanded OrgChart: 내부 viewport `rgb(255, 255, 255)`를 새 Storybook 빌드에서도 측정했다. P11.5 외부 배경·geometry·PNG 동일성 재사용. 회사별 20/100/300 선택, TB/LR/Hybrid, HM popup·Drag & Drop 컨트롤의 소스·구성은 변경 없음. 모든 조합을 새로 실행했다고 주장하지 않는다.
- 승인 Story ID 유지: `orgchart--logo-personnel-summary`, `orgchart--department-colors`, `orgchart--full-composition`, `orgchart--expanded-org-chart`. 새 Story 추가 없음.
- Chart Only: P11.5 React/Vanilla 초기 Fit·wheel Zoom·Pan·popup/focus 복귀·stable-ID 접기/펼치기 PASS 재사용. 외부 제목/요약/툴바 미생성·Fixed 미지원은 현재 코드 확인. 이번에는 custom BG와 제거·인스턴스 격리를 추가 실행했다.
- 승인 문서의 5개 대상 및 P11.5 변경 한정 범위가 구현과 일치한다. 7개 회사색 `#CB2E28`, `#F08300`, `#4580A6`, `#1D418D`, `#84338E`, `#0068B7`, `#0C367F` 및 흰색 그룹 제목은 그대로다.
- AGENTS.md·CLAUDE.md·AI 생성 정책의 Chart Only/Full Page 구분, 기본 승인 디자인·외부 CSS custom·정확한 사용자 데이터·Fixed Chart Only 미지원 정책에 충돌 없음.

P11.5 최초 검사 **33 PASS/선택자 harness FAIL 2** 및 실패 한정 보완 **15/15 PASS** 원본을 보존한다. 전체 48개 제품 PASS로 단순 합산하지 않는다. 별도 역사적 승인 PNG 비교와 모든 viewport/동작 조합의 신규 회귀는 NOT VERIFIED다.

## 6. 통합 검증과 증거

로컬 ignored 증거는 `test-results/org-chart-p11-6/`에 보존하며 Commit에서 제외한다. P11.5 증거는 `test-results/org-chart-p11-5/final-result.json`, `browser-result.json`, `recheck-result.json`, `baseline.json`, `after.json`, before/after PNG를 검토·재사용했다.

- `npm.cmd ci --offline --no-audit --no-fund`: 격리 복사본에서 PASS, 552 packages 설치. 첫 sandbox EPERM은 권한 문제이며 정상 허용 실행에서 해결했다. 신규 audit는 수행하지 않았다.
- main Docker 순서 그대로 `npm.cmd run build` → `npm.cmd run build-storybook`: 모두 PASS. prebuild의 패키지 빌드 반복도 Docker 실제 명령대로 수행했다. 로그 `build.log`, `build-storybook.log`.
- `npm.cmd run typecheck --ignore-scripts`: PASS, 전체 workspace. 이미 완료한 prebuild를 다시 실행하지 않았다. 로그 `typecheck.log`.
- `node test-results/org-chart-p11-6/audit.mjs` 및 격리 TypeScript의 `-p .../test-results/snippets`: PASS, 공개 선언 예제 14개·JSON 2개·JS/CSS/lockfile 정합성. `audit.json`, `snippet-typecheck.log`.
- `node test-results/org-chart-p11-6/browser.mjs`: 추가 **20/20 PASS**, 브라우저 오류 0. `browser.json`, `browser.log`. 실제 URL은 `http://127.0.0.1:6046/storybook-static/iframe.html?id=orgchart--<기존ID>&viewMode=story`, fixture는 `/_local/p11-6/fixture.html`이다.
- Guard: `node scripts/ai-generation-guard.mjs --target . --profile STORYBOOK --scope FULL_SCREEN --json`. `guard-full.json`: **FAIL 0, NOT VERIFIED 98**, status/staticStatus/runtimeStatus **NOT VERIFIED**. CSS phases **STATIC PASS / RUNTIME NOT VERIFIED / DESIGN_INTENT NOT VERIFIED / FINAL NOT VERIFIED**, 결합 styleVerification 미생성. 전체 Storybook import graph 범위이며 모든 package source CSS의 실행 검증을 뜻하지 않는다. 변경 CSS의 P11.5 scoped Guard FAIL 0도 재사용했다.
- 기존 `bg-[var(...)]` CSS 최적화, `host-context` minifier, 큰 bundle 경고는 보존했다. Build exit 0이며 이번 신규 제품 오류와 구분한다. 검사 규칙/예외를 변경하지 않았다.

전체 Core/browser 회귀·접근성·성능·SSR/hydration·다른 브라우저·전 화면 디바이스 재검증은 수행하지 않았다. 기존 정상 검사를 무조건 반복하지 않는다.

## 7. main 병합·배포 빌드 호환성

- Merge Base: `d18e3c33801e165e17b6d971e2f6198eed483c3c`.
- 검사 전 main-only 3 / Feature-only 16 Commit. **Fast-forward 불가, Merge Commit 필요**.
- main-only 변경은 `.dockerignore`, `.gitea/workflows/deploy-storybook.yml`, `.gitignore`, `Dockerfile`, `README.md`, `compose.yaml` 6개다. Feature 변경 경로와 겹치지 않는다.
- 읽기 전용 `git merge-tree <base> origin/main HEAD` 결과에 changed-in-both/충돌 marker가 없다. 원본 `merge-tree.txt` 보존. 새 P11.6 6개 경로도 main 변경과 겹치지 않는다. 검토한 SHA 기준 **예상 텍스트 충돌 없음**.
- `.storybook/main.ts` 변경 없음, preview는 기존 승인 OrgChart 4개 순서 추가. main 쪽 설정 경쟁 변경 없음.
- Feature의 manifest/lockfile은 OrgChart workspace·엔진을 포함한다. **Core → UI → Center → React** 빌드 순서라 UI 타입 생성 전에 React가 빌드되는 과거 문제가 해결되어 있다.
- 격리 디렉터리는 `git archive HEAD`에 P11.5 현재 5개 파일과 main 전용 6개 파일을 복사한 예상 병합 source다. 입력 경로가 서로 겹치지 않음을 먼저 확인했고 Git 브랜치를 실제 병합하지 않았다.
- 설치 전에 4개 패키지에 dist/node_modules가 없음을 확인했다. 격리 `npm ci`로 별도 node_modules를 설치했다. root lockfile SHA-256 `fae6ace49f0cfb2c9fe606e2fdd2f1fdf9ef9f19139f9a8628a7719f0a75c9b9` 동일 유지. 원본 node_modules·dist 보존.
- main Docker 정의는 node:24-alpine에서 npm ci → npm run build → npm run build-storybook, nginx:1.29-alpine으로 Storybook 산출물 제공이다. main Workflow는 main Push/수동 실행 시 immutable source archive 전송 후 compose build/up 한다.
- **동일 명령의 clean source 빌드 호환성 PASS**. 실행 환경은 Windows Node 22.23.2/npm 10.9.8이다. Docker 실행 파일이 없으므로 Linux/Node 24 Alpine 컨테이너 build, nginx serving, 실제 Gitea runner/서버/SSH/복구는 **NOT VERIFIED**. 이를 Docker 배포 Runtime PASS로 올리지 않는다.

## 8. Git 완료 조건과 최종 판정

기능·문서·승인 디자인의 변경 범위 PASS, 추가 브라우저 20/20, clean build/typecheck PASS, 실행한 Guard FAIL 0, 예상 충돌 없음으로 Feature Commit·일반 Push 조건을 충족했다. 이번 Commit 메시지는 `fix(org-chart): separate fixed and expanded canvas backgrounds`다. Commit 직전 원격 main/Feature가 검사 기준에서 바뀌지 않았는지 다시 확인하며 위 6개 파일만 Stage·staged diff 검토한다.

이 문서를 포함하는 최종 Commit SHA·원격 일치·Working Tree·main 유지 여부는 작업 완료 응답 및 로컬 `test-results/org-chart-p11-6/git-final.json`에 기록한다. Git 실행 실패나 원격 변경이 있으면 완료로 간주하지 않는다. main 실제 Merge·Push·자동 배포는 이번 범위가 아니다.

**CONDITIONALLY READY**: 확인한 소스의 배포 명령 빌드와 정합성은 PASS다. Docker/운영 플랫폼 검증 제한을 남기고 별도의 사용자 병합·배포 지시를 기다린다. 실제 병합 직전에 최신 원격 SHA를 다시 조회하여 새 변경·충돌 여부를 확인해야 한다. 이번 검증으로 운영 위험 수용이 승인된 것은 아니다.

기존 위험은 유지한다: 자동 롤백 없음, P11.4 롤백 검토 PARTIAL, 서버 복구 Runtime NOT VERIFIED, 개발 의존성 High Advisory 7건 처리 방침 PENDING(이번 신규 audit 없음), 삼안 약 2.64:1·장헌산업 약 4.29:1 흰색 제목 대비 미달, Guard Runtime NOT VERIFIED. 디자인 승인은 WCAG AA 준수/조직 위험 수용 승인이 아니며 롤백 검증을 병합 필수 조건으로 두지 않는다는 방향도 복구 성공 보장이나 포괄 위험 수용을 의미하지 않는다.