HMDesign/docs/guidelines/gitea-source-transfer-preparation-2026-10-11.md

# HMDesign 공식 Gitea 소스 이전 준비

2026-10-12 월요일에는 검증된 GitHub 최신 **추적 소스 전체**를 공식 Gitea의 기존 이력 위에 반영한다. 이번 작업은 소스 정합성과 준비 자료만 정리했으며 공식 Gitea 접근·Clone·Commit·Push·연결 전환은 실행하지 않았다. [최종 정합성 보고](../reports/pre-gitea-finalization-2026-10-11.md)와 [전체 소스 목록](../reports/gitea-source-inventory-2026-10-11.json)을 함께 사용한다. [10월 10일 준비 기록](gitea-source-transfer-preparation-2026-10-10.md)은 당시 기록으로 보존한다.

## 기준 소스와 전달 자료

현재 소스 기준은 GitHub `shkim25027/HMDesignSystemTest`의 main이다. 이번 작업 시작 Local/GitHub HEAD는 모두 `4fe549da01683c363b0715aedeb82a089717f685`, 작업 트리는 CLEAN이었다. 이 기준에서 실행 코드·CSS·Theme·의존성·Story는 바꾸지 않고 문서만 보완한다. 문서를 포함한 최종 commit SHA는 자기 커밋 파일에 넣을 수 없으므로 작업 종료 보고와 로컬 `_local/finalization-20261011/release-manifest.json`에 기록한다. 월요일에는 전달받은 **최종 전체 SHA**와 아래 실제 GitHub main 조회 결과를 비교해 대상 소스를 고정한다.

```powershell
git rev-parse HEAD
git branch --show-current
git status --porcelain=v1
git ls-remote https://github.com/shkim25027/HMDesignSystemTest.git HEAD refs/heads/main
git ls-files
```

최종 소스 목록은 595개 경로다(기존 592개 + 이번 준비/보고/목록 3개). JSON의 `paths`와 실제 `git ls-files`를 비교한다. 이후 새 commit이 생기면 SHA·목록·변경 영향 판정을 새로 확인한다. GitHub에서 일부 최근 변경 파일만 복사하면 기존 기반 파일을 누락할 수 있다.

Git 소스와 별도로 보관할 로컬 증거는 다음과 같다. 이 경로는 Clone에서 열 수 있는 문서 링크가 아니다.

- HMDesign: `_local/finalization-20261011/`의 최종 보고, release manifest, tracked-files.txt, 재사용/보존 근거, 검증 로그.
- 독립 실험: `D:/디자인시스템/HMDesign-AI-CrossModel-Test/finalization-20261011/`의 실행기 V3 후보와 21개 모의검사 근거.
- 과거 실험·접근성·보안 증거: 기존 폴더를 그대로 보관하며 소스 이전 commit에 추가하지 않는다.

## 프로젝트 진입점

| 영역 | 실제 경로와 역할 |
|---|---|
| workspace | `package.json`, `package-lock.json`, `packages/*` |
| UI 공개 API | `packages/ui/src/index.ts`, `packages/ui/package.json` |
| UI 구현과 Pattern | `packages/ui/src/components/ui/`, `packages/ui/src/patterns/` |
| Theme | `themes/default.json`, `packages/ui/src/theme/`, `packages/ui/src/theme.css`, `packages/ui/src/tailwind.css` |
| CENTER | `packages/center-graphic/src/index.ts`, `packages/center-graphic/package.json` |
| 기본 React 앱 | `index.html` → `src/main.tsx` → `src/App.tsx`, `src/index.css` → `src/hm-theme.css` |
| Storybook | `.storybook/main.ts`, `.storybook/preview.tsx`, `.storybook/manager.css`, `src/**/*.stories.tsx` |
| 새 목록 제작 예제 | `examples/publisher-list/README.md`, `main.tsx`, `vite.config.ts` |
| AI 규칙과 검사 | `AGENTS.md`, `docs/guidelines/ai-screen-contract.md`, `scripts/ai-generation-guard.mjs` |
| Windows 실행기 | `start-storybook.bat`, `scripts/start-storybook.mjs` |

Storybook manager 스타일은 `main.ts`의 `managerHead`에서 CSS를 연결한다. 별도 `manager.ts/tsx` 파일은 필수 파일이 아니다. 생성 package dist·앱 dist·storybook-static·theme-dist는 Git에 없으며 설치 후 재빌드한다. Noto Sans KR는 `public/fonts/`의 추적 asset과 라이선스를 유지한다.

## 의존성과 실행 조건

Node.js 조건은 lockfile/Vite 기준 `^20.19.0 || >=22.12.0`이며 Node 21은 제외한다. 검증 환경은 Node **20.20.1**, npm **10.8.2**, Windows, React/ReactDOM 19.3.0, TypeScript 7.0.2, Vite 8.3.0, Storybook 10.6.1, Tailwind/@tailwindcss/vite 4.3.3이다. 공식 회사 환경의 버전·프록시·인증·레지스트리 접근은 NOT VERIFIED다.

정확한 전체 의존성은 `package-lock.json`으로 고정한다. root의 UI/CENTER workspace, UI의 Radix·cmdk·TanStack Table·lucide-react 등과 React/Tailwind peer 계약을 유지한다. `@tanstack/react-table`과 `@tanstack/table-core`는 모두 9.2.4다. 개발 `shadcn`과 CSS 복사 계약도 유지하며 이번에 업데이트하지 않았다.

최초 설치와 실행:

```powershell
node --version
npm --version
npm ci --no-audit --no-fund
npm run build:packages
npm run storybook
# http://localhost:6024/
# 별도 터미널의 실제 React 목록 예제:
npm run dev:publisher-example
```

Windows의 `start-storybook.bat`은 의존성/산출물이 없으면 준비하고 6024의 index/preview 응답을 확인한다. Node/npm/Git은 별도 설치 대상이며 포터블 Node나 ZIP을 제공하지 않는다. 공식 사내 실행 환경의 설치·호스팅 결과는 월요일 확인한다.

## 검증 명령과 선택 기준

소스 이전 후 package를 빌드하고 최종 타입과 build를 확인한다. `typecheck`의 prehook가 Theme defaults 확인과 package build를 수행한다. 같은 source/dependency 조건에서 이미 성공한 hook는 `--ignore-scripts`로 중복을 줄일 수 있다.

```powershell
npm run typecheck
npm run build --ignore-scripts
npm run build-storybook --ignore-scripts
node scripts/check-doc-links.mjs
node scripts/public-theme-tokens.mjs
```

변경 영향에 따라 아래 검사 중 필요한 것만 선택한다. 소스와 의존성·환경이 같은 기존 PASS를 재사용하고, 전체 292 Story 렌더를 무조건 반복하지 않는다. 회사 환경에서 새로운 설치/빌드 실패가 생기면 해당 실패를 해결·재검사한 뒤 진행한다.

```powershell
# Guard 또는 증거 계약이 달라졌을 때: 현재 75 + 20 + 5
node --test scripts/ai-generation-guard.test.mjs scripts/guard-evidence.test.mjs scripts/guard-requirements.test.mjs
# Component / 접근성 / Theme 영향이 있을 때:
npm run test:components
node --test scripts/accessibility-regression.test.mjs
node --test scripts/theme-verification.test.mjs
# 소비 예제 영향이 있을 때:
npm run build:publisher-example
npm run build:dashboard-export
node node_modules/vite/bin/vite.js build --config vite.recruit-export.config.ts
```

브라우저 QA는 별도 설치된 Playwright·Chrome을 `HM_PLAYWRIGHT_DIR`·`HM_CHROME_PATH`로 연결한다. `scripts/verify-accessibility-runtime.mjs`는 `HM_A11Y_URL`과 별도 `HM_A11Y_OUTPUT`에 명명된 선택 검사를 기록한다. 실제 SR 발화·실터치는 이 스크립트의 PASS로 대체하지 않는다.

`audit-quality-contracts.mjs`는 과거 GitHub BASE와 로컬 절대 증거 경로 2개에 의존하는 **역사 비교 도구**다. 공식 Gitea 이력에 BASE commit을 가져와 실행하지 않는다. 공식 환경에서 그대로 실행하는 검증 목록에서 제외하고, 필요 시 별도 승인 범위에서 baseline 입력을 연결한다. 제품 앱·package manifest의 로컬 절대경로 의존성은 발견되지 않았다. CSS의 외부 Reference 경로 주석과 과거 QA 안내는 실행 의존성이 아니다.

## AI Guard 명령

현재 scope는 FULL_SCREEN/PARTIAL이고, STORYBOOK은 profile이다. Production `--result`는 실제 React bootstrap에 연결한다.

```powershell
node scripts/ai-generation-guard.mjs --target <앱> --scope FULL_SCREEN --mode GNB_ONLY --result index.html --json
node scripts/ai-generation-guard.mjs --target <앱> --scope PARTIAL --mode LNB_ONLY --files src/main.tsx --result index.html --json
node scripts/ai-generation-guard.mjs --target . --profile STORYBOOK --scope PARTIAL --files src/components/combobox.stories.tsx,src/patterns/gnb.stories.tsx,src/patterns/lnb.stories.tsx --json
node scripts/guard-evidence.mjs <guard.json> <runtime.json>
```

`--scope STORYBOOK`과 STORYBOOK profile의 `--result`는 설정 오류다. exit 0만으로 PASS로 판단하지 않는다. 원본 `status`, `staticStatus` 및 CSS의 STATIC/RUNTIME/DESIGN_INTENT/FINAL을 별도로 보고한다. 오래된 source/contract 해시를 새 값으로 덮어쓰지 않는다. STYLE-001 FAIL, 동적 Token 유한 후보 선언, 외부 입력 미검증과 recipe가 디자인 승인 근거가 아니라는 계약을 유지한다. 비신뢰 Storybook 설정·glob 입력은 개발 의존성 위험 때문에 제한한다.

## 보존할 디자인과 정책

- D-01 중첩 Panel 제거·`padding: 24px 0`, D-02 Primary 상단 White alpha 0.8, Secondary·Legacy 유지.
- 확정 목록 구성·조회 Solid Green/초기화 Outline Gray, Button Gray/Solid Red, Table 강조 20%, Progress 우측 radius, Accordion 제목 hover 5%, Sheet 안쪽 모서리, Drawer 모바일 버튼 순서.
- Green LNB 펼친 2Depth와 Storybook 왼쪽 목차 배경 Black 8%. 선택·Hover·Focus와 전체 opacity 유지.
- Theme 값의 원본은 `themes/default.json`. 공통 Color/Typography/Spacing/Token·Component API·대표 Story ID를 임의 변경하지 않는다. Sheet 최종 radius 등 미확정 값은 확정하지 않는다.
- 실제 HM React 공개 Component/Pattern을 사용한다. ONE PAGE = ONE NAVIGATION MODE, GNB mobile 동반, 공식 LNB ONLY 허용, 신규 GNB/Dashboard Sidebar 금지, Dashboard Header 48px·최소 960px 내부 스크롤.
- Storybook은 Reference다. 신규 업무 화면을 Story로 추가하지 않고 소비 bootstrap의 공개 Theme/Tailwind/status와 package font asset 연결을 유지한다.

## 남은 문제

| 분류 | 보존할 상태 |
|---|---|
| T03 Medium/High | 화면 생성 전 중단. 생성·품질·반응형·접근성 모두 NOT VERIFIED. 승인 12/12 사용, 추가 모델 호출 0 |
| T03 실행기 | V3 후보 로컬 21/21 PASS. 기존 실행기·launcher·승인·STOP 보존. 실제 모델 세션에서의 통합은 NOT VERIFIED; 별도 승인 후 새 manifest로 사용 |
| CSS Intent | T01 디자인 의도·미실행 동적 Theme/상태 NOT VERIFIED. 이전 contract는 역사적 결과만 재사용 |
| 보안 | 과거 감사 기준 개발 High 7·Critical 0, 운영 0. braces 전파 경로, 안전한 patch 미확인. 새 audit/업데이트 없음 |
| 접근성 | 활성 placeholder·일부 버튼/오류 대비 FAIL/DEFERRED. SR·실터치·Drawer drag·확대·모든 Theme/브라우저 NOT VERIFIED |
| 빌드 | 기존 500kB chunk와 Storybook bundler 성능 경고 보존 |
| 공식 환경 | Gitea 전용 파일·기존 소스 차이·분기/보호 정책·사내 Node/npm·호스팅·인증 NOT VERIFIED |

## 월요일 공식 이력을 유지하는 반영 순서

아래는 월요일 별도 승인된 작업의 절차이며 이번에는 실행하지 않았다.

1. 공식 Gitea checkout의 실제 branch/HEAD/working tree를 기록한다. 공식 저장소에만 있는 파일과 사용자 변경을 보존한다. 기존 이력 위에서 작업용 branch를 만들고 GitHub 소스와의 경로별 차이를 확인한다.
2. 고정한 최종 GitHub SHA의 **추적 파일만** 별도 소스 디렉터리에서 비교·복사한다. `.git`을 복사하거나 GitHub main을 공식 main에 merge/cherry-pick하지 않는다. ZIP을 배포 수단으로 만들지 않는다.
3. `.gitignore`, package/lock, `.storybook`, Component/Pattern/Theme, fonts/assets, scripts, examples/docs를 빠짐없이 반영한다. `node_modules`·dist·storybook-static·`_local`·실험 자료·개인 환경/비밀정보를 넣지 않는다.
4. GitHub에 없는 공식 파일은 삭제 대상으로 간주하지 않는다. 양쪽에서 같은 경로를 변경했거나 삭제 후보가 있으면 소스/회사 설정의 용도를 확인해 결정한다. 일괄 미러링 삭제나 사용자 변경 덮어쓰기는 하지 않는다.
5. 공식 작업 branch에서 설치·타입·build·Storybook과 변경 영향 검증을 수행한다. 실제 공식 assets/경로, 문서 링크와 staged diff를 확인한다. 필수 실패가 있으면 공식 반영을 보류한다.
6. 회사의 review/branch 정책에 따라 공식 저장소에서 별도 commit하고 공식 기존 이력에 반영한다. GitHub 임시 이력을 가져오거나 force push/reset/clean으로 맞추지 않는다. 공식 Local/Remote SHA와 working tree를 확인한다.
7. 공식 이전·검증·원격 확인이 모두 끝난 다음 **별도 지시**로 GitHub 원격 연결을 해제한다. 먼저 `git remote -v`로 실제 이름/URL을 기록하고 공식 remote를 확인한다. 공식 clone의 origin이 Gitea라면 origin을 제거하지 않는다. GitHub URL을 가리키는 정확한 remote만 `git remote remove <확인한 GitHub remote 이름>`으로 제거하고 `git remote -v`를 다시 확인한다. GitHub 저장소·이력 자체는 삭제하지 않는다.

## 작업 환경

- 1순위 추천: 공식 Gitea에 접근 가능한 로컬 Git·Node.js 개발 환경.
- 추천 이유: 공식 이력과 회사 전용 파일을 비교하고 설치·명령 실행·검증·staged diff 검토까지 같은 checkout에서 수행할 수 있다.
- 사용 방식: 별도 이전 지시와 함께 이 문서, 최종 전체 SHA, 소스 목록, 로컬 release manifest를 전달한다. 실제 회사 네트워크·권한·도구 가용성은 월요일 확인한다.