Phase 5 컴포넌트 리팩토링 계획 및 전체 마이그레이션 현황
1. 결론
현재 feat/antd-phase-2-components 브랜치에서는 Ant Design 도입의 기반 구축부터 데이터·콘텐츠·첨부파일 컴포넌트 전환까지 완료되었다. 다음 작업은 업무 화면과 남은 고복잡도 primitive의 전환, 공개 API 정리, 소비 포털 통합 검증을 묶은 Phase 5로 진행한다.
저장소의 기존 마스터 문서는 데이터 표시·피드백 전환을 공식 Phase 5, Form 및 업무 화면 전환을 공식 Phase 6으로 정의한다. 현재 세션의 실행 번호인 Phase 4는 이 두 공식 범위의 대부분을 선행 처리했다. 따라서 이 문서의 Phase 5는 저장소 실행 흐름 기준의 다음 단계이며, 마스터 계획 기준으로는 공식 Phase 6 후반부터 Phase 7·8까지를 포함하는 통합·정리 단계에 해당한다.
2. 현재까지의 완료 현황
| 실행 단계 | 주요 범위 | 상태 | 핵심 반영 내용 |
|---|---|---|---|
| Phase 0 | 기준선과 공개 API 조사 | 완료 | workspace build, typecheck, test 기준선과 public export 조사 |
| Phase 1 | Ant Design 기반 구축 | 완료 | antd, @ant-design/icons, provider, token mapping, theme-client 계약 정리 |
| Phase 2.0 | 전환 브랜치와 기준선 | 완료 | feat/antd-phase-2-components 생성 및 기준선 확보 |
| Phase 2.1 | AuthCard | 완료 | Card, Button, Alert, Typography 기반 내부 구현, 기존 props와 class 유지 |
| Phase 2.2 | ThemePicker | 완료 | Ant Design control 기반 theme 선택과 theme-client 연동 |
| Phase 2.3 | BrandMark와 icon facade | 완료 | Ant Design icon facade와 제품 mark 호환 계층 구축 |
| Phase 3.1 | 메뉴 adapter와 icon facade | 완료 | 권한 메뉴를 Ant Design items 형식으로 변환하고 icon fallback 정책 추가 |
| Phase 3.2 | PortalShell과 관리자 shell | 완료 | Layout, Sider, Header, Content, Menu 중심 구조로 전환 |
| Phase 3.3 | PortalThemePolicySettings | 완료 | 정책 control과 상태 표시를 Ant Design primitive 조합으로 전환 |
| Phase 3.4 | DirectoryManagement | 완료 | Tabs, Tree, Table, Select, Spin, Empty, Alert 기반 전환 |
| Phase 4.1 | dataShells | 완료 | Table, Descriptions, Card, Empty, Spin, Alert, Tag 기반 상태·데이터 표시 |
| Phase 4.2 | contentComponents field·tabs·table | 완료 | Input, Input.TextArea, Select, Tabs, Table, Space 기반 전환 |
| Phase 4.3 | PortalDialog와 PortalTree | 완료 | Modal, Tree, controlled/uncontrolled 변환 adapter, legacy wrapper 유지 |
| Phase 4.4 | assetAttachments | 완료 | List, Typography, Button, Empty, Space 기반 첨부 목록 전환 |
| Phase 4.5 | 통합 회귀 검증 | 완료 | Phase 4 통합 테스트 포함 8개 test file, 32개 test 통과 |
현재 브랜치는 Phase 4 구현 커밋을 포함하여 main보다 16개 커밋 앞서 있으며, 최신 확인 커밋은 150993e이다.
3. 컴포넌트별 현재 상태
| 컴포넌트 또는 영역 | 현재 구현 | 남은 작업 |
|---|---|---|
PortalConfigProvider | Ant Design provider와 portal token mapping 완료 | 실제 소비 포털 light/dark 시각 검증, token drift 점검 |
PortalButton, PortalStatusBadge, PortalEmptyState, PortalBreadcrumbs | Ant Design 기반 완료 | 공통 token과 접근성 최종 정리 |
AuthCard | Ant Design Card, Button, Alert, Typography 기반 | form validation과 focus 회귀 범위 확장 |
ThemePicker | Ant Design control과 theme-client 연동 완료 | 저장·복원·정책 조합 통합 검증 |
BrandMark, icon facade | facade와 fallback 완료 | 사용하지 않는 catalog와 legacy icon 경로 정리 |
PortalShell, PortalAdminShell | Layout 계열 전환 완료 | mobile viewport, URL active state, focus return 검증 |
PortalThemePolicySettings | 정책 화면 전환 완료 | Form 표준화, 서버 오류 field mapping, dirty state 검증 |
DirectoryManagement | 데이터 화면 전환 완료 | mutation 실패 복원, pagination/filter 통합 검증 |
dataShells | 상태·목록·상세 Ant Design 전환 완료 | Result/Skeleton 정책 통일 및 pagination public contract 문서화 |
contentComponents | field, tabs, table, dialog, tree 전환 완료 | callback compatibility 정밀 검증, focus/keyboard 보강 |
assetAttachments | Ant Design List와 action 전환 완료 | 실제 upload flow는 별도 API 없이는 추가하지 않음; List deprecation 대응 검토 |
menuManagement | 상당 부분 native input, button, label 유지 | Phase 5의 최우선 전환 대상 |
PortalExploreDialog | native search input·button·result action 유지 | Ant Design Modal, Input.Search, List, Button, Typography 전환 |
index.tsx legacy public composites | public API 유지 | component-level export와 내부 파일 분리, legacy import 경로 유지 |
4. Phase 5 대상 컴포넌트
4.1 P0 — menuManagement.tsx 업무 편집 화면
menuManagement.tsx는 현재 가장 큰 native control 잔여 영역이다. 메뉴 항목 편집, 순서 변경, 삭제, quick link, icon picker, enabled toggle, audit history를 포함하므로 단순 primitive 교체가 아니라 상태·권한·callback 계약을 먼저 고정해야 한다.
전환 대상은 다음과 같다.
| 현재 역할 | 목표 primitive | 보존할 계약 |
|---|---|---|
| 메뉴 목록 | List 또는 Table | 순서, id, label, active 상태 |
| 메뉴 항목 입력 | Input, Input.TextArea | locale별 label, URL, 변경 callback |
| icon 선택 | Select 또는 Dropdown | icon key, fallback, locale |
| enabled toggle | Switch | boolean payload, disabled 정책 |
| 순서 변경 | Button 또는 Space.Compact | 첫 항목·마지막 항목 disabled 규칙 |
| 삭제 | danger Button, optional Popconfirm | systemReserved 차단, 삭제 payload |
| audit history | List, Typography, Tag | 최근 8개, locale별 문구와 timestamp |
| empty state | Empty | 기존 empty 문구와 class |
권한 판단과 systemReserved 정책은 UI에서 새로 정의하지 않는다. 기존 callback과 입력 모델을 유지하고, Ant Design은 편집·표시 계층으로만 사용한다.
4.2 P0 — PortalThemePolicySettings Form 계약 강화
현재 구현은 Ant Design control 기반으로 전환되었지만, Phase 5에서는 실제 업무 화면 기준의 Form 계약을 완성한다.
다음 항목을 고정한다.
- 초기값과 controlled value의 우선순위
- 필수값 및 형식 검증
- 서버 오류를 field-level error로 변환하는 adapter
- 제출 중 중복 제출 차단
- 실패 시 입력값 보존
- 취소·reset 시 dirty state 처리
- 허용되지 않은 theme option의 표시 및 선택 차단
- keyboard label과 help text 연결
4.3 P1 — PortalExploreDialog
index.tsx에 남아 있는 탐색 dialog는 검색 input, clear button, ask action, result button, citation link를 native element로 구현하고 있다. 다음 조합으로 전환한다.
ModalInput.Search또는InputButtonListTypographyTag또는Empty- 필요한 경우
Spin
open, onOpenChange, query, onQueryChange, onSelect, onAsk, answerLoading, answer, citations API는 유지한다. 검색 결과 권한 범위와 citation 표시 규칙은 변경하지 않는다.
4.4 P1 — AuthCard와 전체 Form 접근성 보강
AuthCard 내부 구현은 이미 전환되었으므로 신규 구조 변경보다 다음 회귀 검증을 우선한다.
- label과 input id 연결
- error와
aria-describedby연결 - submit loading 중 중복 제출 차단
- password field의 keyboard 동작
- error alert의 live region
- dark theme focus ring
4.5 P2 — PortalComponents와 provider token 정리
이미 전환된 primitive 사이의 시각적·토큰 차이를 정리한다.
Tag,Alert,Empty,Card,Table,Modaltone 일관성Input,Select,Tabscontrol height 일관성- legacy
pf-*wrapper와 Ant Design 내부 selector의 중복 CSS 제거 PortalConfigProvider로 이동 가능한 component token 식별- light/dark theme에서 disabled, hover, focus 색상 확인
4.6 P2 — export와 파일 구조 정리
현재 루트 index.tsx에 남아 있는 대형 public composite는 당장 import 경로를 깨지 않는 범위에서 분리한다.
explore/PortalExploreDialog.tsxauth/AuthCard.tsxbranding/BrandMark.tsxnavigation/menuManagement.tsx- 각 디렉터리의 barrel export
- 기존
src/index.tsx에서 re-export
이 작업은 소비 포털의 import 변경을 요구하지 않아야 한다. legacy 경로는 deprecation 기간 동안 유지한다.
5. 실행 순서와 예상 일정
예상 일정은 순차 작업 기준 4~6 작업일이다. 각 단계는 독립적으로 build와 test를 통과한 뒤 다음 단계로 진행한다.
| 일정 | 작업 패키지 | 결과물 | 완료 기준 |
|---|---|---|---|
| Day 1 | Phase 5.0 기준선과 계약 고정 | menu, theme policy, explore, AuthCard 테스트 | 기존 테스트와 신규 기준선 통과 |
| Day 1–2 | Phase 5.1 menuManagement adapter·field 전환 | List/Table, Input, Select, Switch, Button | callback, 권한, 순서, 삭제 정책 보존 |
| Day 2 | Phase 5.2 PortalThemePolicySettings Form 정리 | Form.Item, validation, server error adapter | 성공·실패·reset·dirty state 통과 |
| Day 3 | Phase 5.3 PortalExploreDialog 전환 | Modal, Search, List, result action | open/close, search, ask, citation, loading 통과 |
| Day 3–4 | Phase 5.4 접근성 및 token 정리 | axe/keyboard/focus 보강, provider token 정리 | 주요 accessibility rule 통과 |
| Day 4–5 | Phase 5.5 export·문서·legacy CSS 정리 | barrel export, migration note, CSS 정리 | public export snapshot과 build 통과 |
| Day 5–6 | Phase 5.6 통합 검증 | workspace 검증과 소비 포털 smoke test | 전체 typecheck/test 및 회귀 목록 통과 |
6. 테스트 계획
6.1 단위 테스트
| 대상 | 필수 검증 |
|---|---|
menuManagement | label/url/icon 변경, locale, add/delete, reorder, systemReserved, enabled, quick links |
PortalThemePolicySettings | 초기값, validation, submit, retry, reset, server field error, disabled option |
PortalExploreDialog | open/close, clear, query change, result select, ask, answer loading, citation |
AuthCard | submit, loading, error, label, focus, password field |
| token/provider | light/dark, component token, locale, theme persistence |
| exports | 루트 export, legacy import path, type-only export |
6.2 접근성 검증
Phase 5에서는 정적 markup만으로 충분하지 않은 keyboard와 focus 이동을 React Testing Library 기반으로 검증한다.
- 메뉴 편집 input과 label의 accessible name
- Switch의 checked state와 label 연결
- 삭제 버튼의 목적과 danger 상태
- Modal의 accessible name, Escape close, focus return
- 검색 input과 clear button의 accessible name
- 결과 목록의 keyboard activation
- Form error의
aria-describedby - loading 중 버튼의
aria-busy또는 disabled 상태 role="alert",role="status",aria-live정책- focus outline이 token과 CSS에 의해 제거되지 않는지 확인
6.3 통합 검증
최종 단계에서는 다음 명령을 기준으로 검증한다.
pnpm -r build
pnpm -r check
pnpm -r test추가로 packages/ui-react에서 light/dark theme, SSR static render, keyboard interaction, legacy class contract를 확인한다. 가능한 경우 세 소비 포털의 대표 화면에서 provider, shell, form, directory, attachment 흐름을 smoke test한다.
7. 위험과 대응
| 위험 | 영향 | 대응 |
|---|---|---|
| native callback과 Ant Design callback payload 차이 | 소비 포털 동작 변경 | compatibility adapter와 기존 callback 계약 테스트 유지 |
| 메뉴 편집 상태의 controlled/uncontrolled 혼용 | 입력값 유실 | value와 callback 조합을 먼저 문서화하고 mode별 테스트 작성 |
| Modal portal과 SSR 차이 | hydration·테스트 불일치 | client portal 동작과 static render를 분리 검증 |
List deprecation 안내 | 향후 major 업그레이드 비용 | 현재 API 안정성을 유지하고 Listy 대체 가능성을 별도 spike로 기록 |
| legacy CSS와 Ant Design selector 충돌 | 시각 회귀 | wrapper descendant selector와 component token 우선 |
| public export 분리 중 import 파손 | 소비 포털 빌드 실패 | 기존 루트 export를 re-export facade로 유지 |
| 서버 오류와 UI 오류 모델 불일치 | 재시도·입력 보존 실패 | field error adapter를 별도 함수로 두고 서버 계약 변경 금지 |
8. Phase 5 완료 기준
Phase 5는 다음 조건을 모두 만족할 때 완료로 판정한다.
| 기준 | 완료 조건 |
|---|---|
| 업무 화면 | menu management, theme policy, explore dialog의 native 주요 control이 Ant Design 기반이다. |
| API 안정성 | 기존 public export, prop, callback 이름과 payload가 유지된다. |
| 상태 정책 | loading, empty, error, success, disabled, submitting 상태가 공통 규칙을 따른다. |
| 접근성 | keyboard, focus, accessible name, live region 검증이 통과한다. |
| 토큰 | 색상·간격·radius·control height의 소유권이 design tokens와 provider에 있다. |
| 문서 | component migration note, callback adapter, legacy import 정책이 기록된다. |
| 품질 | 전체 workspace build, check, test가 통과한다. |
| 통합 | 대표 소비 포털 흐름에서 shell·form·directory·attachment가 함께 동작한다. |
9. 남은 일정 요약
단기적으로는 Phase 5.0 기준선 테스트와 menuManagement 전환을 시작한다. 이어서 theme policy form과 explore dialog를 전환하고, 마지막으로 token·export·legacy CSS를 정리한다. Phase 5 이후에는 공식 마스터 계획의 Phase 7 공개 API·문서 정리와 Phase 8 소비 포털 통합·릴리스 검증으로 이동한다.
| 순서 | 다음 단계 | 예상 소요 |
|---|---|---|
| 1 | menuManagement Ant Design 전환 | 1.5–2일 |
| 2 | PortalThemePolicySettings Form 계약 강화 | 0.5–1일 |
| 3 | PortalExploreDialog 전환 | 0.5–1일 |
| 4 | 접근성·token·legacy CSS 정리 | 1일 |
| 5 | export·문서·통합 smoke test | 1–1.5일 |
| 6 | 릴리스 후보 검증 및 migration note | 0.5–1일 |