HMDesign/docs/sw/sw-ai-template-integration-2026-10-19.md

# SW AI 재사용 템플릿 로컬 통합 기록 (2026-10-19)

> 범위: `@hm-design/sw`. `feature/sw-ai-template`을 `feature/sw-package`에 로컬 Merge만 했습니다. Push·PR·Publish·배포는 하지 않았습니다. 기존 [AI 템플릿 검증 기록](./ai-template/README.md)과 [Storybook Overview 검증 자료](./storybook-overview-qa/)는 수정하지 않았습니다. 이번 실행 결과는 [ai-template-integration-qa/](./ai-template-integration-qa/)에 따로 두었습니다.

## 1. 통합 전 상태 (실제 로컬 Git)

| 항목 | 값 |
|---|---|
| `feature/sw-package` HEAD | `bf16578226fe89e5d9a6ba904b7979bebb602661` (chore(sw): improve interactive header story preview) |
| `feature/sw-ai-template` HEAD | `e27385e0f07e6ad5d58d5ba81cfcbef800997ec6` (feat(sw): prepare reusable AI-friendly component package) |
| Merge Base | `50bf5bda8e956a4973b923d64131f2f2285bd38c` |
| 원본 Working Tree | Clean(Staged·Unstaged·Untracked 없음) |
| 원격 대비 미Push Commit(`origin/feature/sw-package` = `724c517`) | `0029cef`, `92830fe`, `50bf5bd`, `bf16578` — 4개 모두 보존 |
| Worktree | `HMDesign-SW`(`feature/sw-package`), `HMDesign-SW-AI-Template`(`feature/sw-ai-template`), `HMDesign-SW-Composition`(`wip/sw-header-composition-unverified`) 외 기존 OrgChart·main |

`left-right` 비교: `feature/sw-package`에만 `bf16578`, `feature/sw-ai-template`에만 `e27385e`.

## 2. 영향 분석

- 양쪽 브랜치가 함께 수정한 파일: **없음**. 삭제·이동: 없음.
- AI 브랜치 변경 26개: 신규 24(`packages/sw/ai/` 12, `packages/sw/tests/ai-*.mjs` 3, `docs/sw/ai-template/` 9), 수정 2(`packages/sw/package.json`의 `files`에 `ai` 추가, `packages/sw/README.md` 끝에 안내 1절).
- Storybook 브랜치의 런타임 외 변경(`src/sw/sw-header.stories.tsx`, `src/sw/sw-stories.css`, `src/sw/sw-header-overview.tsx`, Overview 테스트, QA 자료)과 겹치지 않습니다.
- `packages/sw/src`, `src/`, `.storybook/`, `packages/ui`, OrgChart 패키지, Center Graphic, 루트 `package.json`·`package-lock.json`: Merge 결과 diff 없음.
- 공개 API: 변경 없음(`exports` 그대로). 배포 설정: `files`만 `["dist", "ai"]`로 확장.

## 3. Merge

- 방식: `git merge --no-ff --no-commit feature/sw-ai-template` → 결과 검토 → 이 보고서와 이번 실행 증거를 추가 → Merge Commit.
- 충돌: 없음("Automatic merge went well"). 스테이징 26개 = AI 브랜치 변경 목록과 같음. `git diff --cached --check` 통과.
- 제외: `wip/sw-header-composition-unverified`(`1b2c3917376841da46a1e2bd4cc4913e41eeb77f`)는 Merge·Cherry-pick하지 않았습니다. 브랜치·Commit·`D:\디자인시스템\HMDesign-SW-Composition` 폴더 그대로이며, 그 Worktree의 Git Status는 Clean입니다.

## 4. 통합된 AI 템플릿 (실제 파일)

| 구분 | 파일 |
|---|---|
| AI 사용 가이드 | `packages/sw/ai/AI_USAGE.md` |
| 컴포넌트 카탈로그 | `packages/sw/ai/COMPONENT_CATALOG.md` |
| SW 디자인 규칙 | `packages/sw/ai/DESIGN_RULES.md` |
| 조합 규칙 | `packages/sw/ai/COMPOSITION_PATTERNS.md` |
| 재사용 예제 | `ai/examples/ExampleA-DefaultHeader.tsx`(완성형 `SWHeader`) |
| 새 Header 구성 예제 | `ExampleB-ViewerHeader.tsx`, `ExampleC-FeatureHeader.tsx`, `example-layout.css`, `sample-data.ts` |
| 없는 컴포넌트를 SW 스타일로 구현 | `SWSearchControl.tsx`, `sw-search-control.css`, `ExampleD-SearchExtension.tsx` |
| 검증 도구 | `packages/sw/tests/ai-docs.check.mjs`, `ai-template-consumer.mjs`, `ai-template-consumer.browser.mjs` |
| 독립 소비 검증 자료 | `docs/sw/ai-template/README.md`, `docs/sw/ai-template/evidence/` |

가이드는 "검색 → 재사용 → 조합 → 없을 때만 소비 프로젝트에서 SW 규칙으로 신규 작성" 순서를 지시합니다. 패키지가 AI 기능을 실행한다고 쓰지 않습니다. 기존 `SWHeader`를 공식 기본 템플릿으로 두며, 예제 Header는 제품 Header를 대체하지 않습니다.

## 5. 이번에 실행한 검증 (통합 Working Tree, Merge Commit 직전 상태)

| 항목 | 결과 |
|---|---|
| `npm run typecheck:sw` | PASS |
| `npm exec -- tsc -p tsconfig.app.json --noEmit`(Storybook·Demo 소스) | PASS |
| `npm run build:sw` | PASS — `dist/index.js`·`styles.css`·`index.d.ts` SHA-256이 Merge 전 산출물과 같음 |
| `npm exec -- storybook build -o storybook-static --disable-telemetry` | PASS |
| Story ID 비교 | 28개. ID·이름·importPath·순서가 [after-index.json](./storybook-overview-qa/after-index.json)과 같음. 삭제된 Default·Controls·Responsive·Text Stroke·Dynamic Data는 없음. AI 예제는 Story로 수집되지 않음 |
| Storybook 소스 해시 | `sw-header.stories.tsx`·`sw-header-overview.tsx`·`sw-stories.css`가 Overview 검증 기록의 `sourceSha256`과 같음 |
| Overview Chrome(`overview.browser.mjs`, 통합 Storybook 빌드) | 53/53 PASS — 16:9 Stage, 49px, Dropdown, 속성Bar 동적 편집·확정, 속성창 열기·닫기·Focus 복귀, 입력 검증, Enter/Escape, Disabled/ReadOnly 포함([결과](./ai-template-integration-qa/chrome-result.json)) |
| Overview Overlay(`overview.browser.mjs overlays`) | 19/19 PASS([결과](./ai-template-integration-qa/chrome-overlays-result.json)) |
| Window Move Motion Story | "단계별 진행 (3배 확대)" 한 구성만 존재, 이동 영역 9개, 이미지 디코드, 창 이동 애니메이션 24개 실행, 오류 0([화면](./ai-template-integration-qa/window-move-motion.png)) |
| `ai-docs.check.mjs` | 19/19 PASS — 문서·예제 Import와 공개 Export 일치, 패키지 내부 링크 정상 |
| Tarball(`npm pack`, 통합 브랜치) | 40개 파일, `ai/` 12개 포함, `src`·`tests` 미포함 |
| 독립 소비 프로젝트(기존 프로젝트 재사용, 통합 Tarball 재설치) | 설치된 `ai/examples` = 저장소 예제, `tsc` PASS, `vite build` PASS, 브라우저 27/27 PASS([결과](./ai-template-integration-qa/ai-consumer-report.json)) |

Overview 스크립트는 결과를 출력 폴더에 쓰므로 기존 `storybook-overview-qa/`가 아니라 임시 폴더에서 실행한 뒤 결과 JSON만 `ai-template-integration-qa/`로 복사했습니다.

## 6. 기존 PASS 재사용 근거

런타임 소스(`packages/sw/src`)와 Storybook 소스(`src/`, `.storybook/`)가 Merge로 바뀌지 않았고 SW 산출물 해시도 같습니다. 그래서 아래 기존 결과는 다시 실행하지 않고 이전 기록으로 남깁니다(이번에 새 PASS로 기록하지 않음): Overview Firefox 9/9, 기존 필드 77/77, Header 관련 257 checks, Header 10개 폭·반응형 More 전체·Colorize·게이지바(Chrome/Firefox)·속성창 4상태·속성 필드 13개 개별 검증.

## 7. NOT VERIFIED

- Firefox: 이번 통합 후 실행하지 않음(기존 9/9 기록만).
- Overview 외 27개 Story의 전체 인터랙션 회귀(Story 선언·소스 해시 동일만 확인).
- 저장소 루트 전체 `npm run typecheck`(`tsc -b` + 모든 workspace)와 `npm run build-storybook`의 `prebuild`(전체 패키지 build). SW 범위 명령과 직접 `storybook build`만 실행했습니다.
- AI 소비 예제의 Firefox·Safari, 소비 검증 범위 밖 공개 컴포넌트(기존 AI 기록 §6 그대로).
- CAD·파일·운영체제 연동, 접근성 인증.

## 8. 로컬 Merge Commit

- 메시지: `merge(sw): integrate AI reusable component template`
- Parents: `bf16578`(feature/sw-package) + `e27385e`(feature/sw-ai-template)
- Push·Force Push·원격 갱신·PR·Publish·배포: 진행하지 않음.
- Commit SHA·Parents·Status는 Commit 직후 확인 결과를 최종 보고에 적습니다(이 문서는 Commit 안에 포함되므로 자기 SHA를 담을 수 없음).