Phase 5 다음 작업 리팩토링 실행 계획

1. 현재 상태

menuManagement.tsx의 주요 관리 surface는 Ant Design 기반으로 전환되었다. 메뉴 생성과 편집은 Form, Form.Item, Input, Input.TextArea, Select, Switch, Collapse를 사용하고, validation은 Alert, quick link는 List, Form, Input, Switch, Button, Empty를 사용한다. 기존 PortalMenuManagementProps, onItemsChange, onQuickLinksChange, 권한 모델, 정렬 규칙, systemReserved 정책, locale fallback은 유지한다.

추가된 순수 adapter는 다음과 같다.

applyPortalMenuItemPatch(items, id, patch, updatedAt?)
applyPortalQuickLinkPatch(items, id, patch, updatedAt?)

현재 ui-react 검증 기준은 9개 test file, 36개 test 통과, typecheck 통과, workspace build 통과이다. antd의 기존 Phase 4 List deprecation 및 SSR Modal warning은 별도 후속 과제로 남아 있다.

2. 다음 작업 우선순위

우선순위	대상	목표	예상 소요
P0	PortalExploreDialog	탐색·질문 dialog의 native control 제거	1–1.5일
P0	PortalThemePolicySettings	Form validation·server error·dirty state 표준화	1–1.5일
P1	PortalMenuManagement 후속	access scope를 Select multiple adapter로 고도화, Listy 검토	0.5–1일
P1	public export 분리	index.tsx composite를 feature 파일로 분리하되 import 호환성 유지	0.5일
P2	token·legacy CSS 정리	Ant Design component token과 portal class 충돌 제거	1일
P2	통합 smoke test	실제 shell·form·directory·attachment 흐름 검증	1일

3. P0-1: PortalExploreDialog

현재 범위

packages/ui-react/src/index.tsx의 PortalExploreDialog는 검색 input, clear action, result action, ask action, answer/citation 표시를 하나의 public composite로 제공한다. public props는 변경하지 않는다.

기존 계약	목표 구현
open, onOpenChange	Modal controlled state
query, onQueryChange	Input 또는 Input.Search
results, onSelect	List, Button, Typography
onAsk, answerLoading	loading Button, Spin
answer, citations	Card, Typography, List
loading	Skeleton 또는 Spin
empty result	Empty

보존해야 할 동작

검색어 변경은 입력 문자열만 callback으로 전달한다. 결과 선택은 기존 result object를 전달하고, citation의 href와 ReactNode title은 그대로 렌더링한다. Escape와 close button은 onOpenChange(false)를 호출하며, loading 중 ask action은 중복 실행하지 않는다.

테스트

• open/close와 focus return
• query controlled value 및 onQueryChange
• empty, loading, answer, citation 상태
• result click의 payload
• ask click과 loading disabled
• accessible dialog name
• search input accessible name
• citation link keyboard activation

4. P0-2: PortalThemePolicySettings

목표

현재 Ant Design control 기반 구현을 실제 Form 계약으로 강화한다.

• Form과 Form.Item으로 field ownership 통일
• 초기값과 controlled value 우선순위 명시
• 필수값 및 허용 theme validation
• 서버 오류를 field-level error로 변환
• submit 중 중복 제출 방지
• 실패 시 입력값 보존
• reset/cancel 시 dirty state 처리
• 정책상 허용되지 않은 option disabled 처리
• aria-describedby와 help/error text 연결

adapter 설계

서버 또는 portal adapter가 반환하는 오류를 UI field 이름으로 변환하는 순수 함수를 둔다.

mapPortalThemePolicyErrors(
  errors: Record<string, string | string[]>
): Record<string, string[]>

UI는 오류 형식의 저장이나 전송을 담당하지 않고, onSubmit에는 기존 정책 payload를 그대로 전달한다.

테스트

• 초기값 렌더링
• theme option disabled 정책
• validation 실패 시 submit callback 미호출
• 정상 submit payload equality
• server error 표시
• retry 시 입력값 보존
• reset/cancel dirty state
• keyboard label과 error association

5. P1: menuManagement 후속 정리

현재 상세 field와 quick link는 Ant Design으로 전환되었지만 access scope 입력은 comma-separated Input을 유지한다. 다음 단계에서 선택지가 제공되는 경우에만 Select mode="multiple" adapter를 적용한다.

portalAccessRuleToSelectValues(rule, field)
selectValuesToPortalAccessRule(rule, field, values)

선택지가 서버에서 제공되지 않는 경우 자유 입력을 유지하여 기존 포털의 권한 문자열을 잃지 않는다. availableScopes, availableRoles, availableGroupIds가 비어 있을 때도 기존 입력·callback 계약이 동작해야 한다.

추가 검증 대상:

• group parent 자기참조 차단
• system reserved disabled/deletion 차단
• quick link 삭제 payload
• reorder 후 sortOrder
• validation Alert의 role과 focus 이동
• List에서 Listy로 교체 가능한지 Ant Design 버전별 spike

6. P1: public export 분리

대형 packages/ui-react/src/index.tsx에서 다음 composite를 별도 파일로 이동한다.

src/auth/AuthCard.tsx
src/branding/BrandMark.tsx
src/explore/PortalExploreDialog.tsx
src/navigation/menuManagement.tsx
src/index.tsx                  # compatibility re-export facade

기존 소비 포털의 import path는 깨지지 않아야 한다. 분리 시 다음 계약을 snapshot 또는 typecheck로 확인한다.

• root export name
• props type export
• legacy class names
• callback names and payloads
• package dist/index.d.ts

7. P2: token과 CSS 정리

목표

Ant Design DOM class에 직접 의존하는 전역 CSS를 늘리지 않고 PortalConfigProvider와 design token을 우선 사용한다.

점검 대상	기준
control height	portal density와 Ant Design size mapping 일치
focus ring	keyboard focus에서 항상 보임
disabled	text/background/opacity 대비 유지
danger	delete와 validation 상태의 의미 구분
dark theme	Alert, Input, Select, Modal, List의 대비 검증
legacy class	wrapper layout·spacing만 보존, primitive styling은 Ant Design으로 위임

정리 후 styles.css에서 중복된 native input, select, button 규칙을 제거하되 pf-* layout contract는 보존한다.

8. P2: 통합 검증

다음 흐름을 소비 포털 관점에서 smoke test한다.

1. PortalConfigProvider에서 light/dark theme 설정
2. PortalShell에서 메뉴 navigation 및 active state 확인
3. PortalMenuManagement에서 메뉴 생성·편집·validation
4. PortalThemePolicySettings에서 정책 저장 실패·재시도
5. DirectoryManagement에서 filter·pagination·mutation
6. PortalExploreDialog에서 검색·결과 선택·citation
7. AssetAttachmentList에서 empty·download action

최종 명령:

pnpm -r build
pnpm -r check
pnpm -r test

추가로 SSR static render, keyboard-only navigation, light/dark theme, legacy CSS class contract를 확인한다.

9. Phase 5 완료 기준

Phase 5는 다음 조건을 모두 충족할 때 완료한다.

• menuManagement의 주요 native control이 Ant Design 기반이다.
• PortalExploreDialog와 PortalThemePolicySettings가 Ant Design Modal/Form 계약을 사용한다.
• 기존 public props, exports, callback payload가 유지된다.
• loading, empty, error, success, disabled, submitting 상태가 표준화된다.
• field label, dialog role, focus return, live region, keyboard interaction이 검증된다.
• provider token과 legacy wrapper class의 책임이 분리된다.
• 전체 workspace build, check, test가 통과한다.
• 대표 소비 포털 smoke test가 통과한다.
• migration note와 다음 major upgrade의 List/Listy 전략이 문서화된다.

10. 실행 순서

순서	작업	완료 산출물
1	PortalExploreDialog 기준선 테스트와 Ant Design 전환	dialog source와 contract tests
2	PortalThemePolicySettings Form·error adapter	policy source와 validation tests
3	menu access multi-select spike 및 Listy 검토	adapter 또는 유지 결정 기록
4	public composite export 분리	compatibility re-export와 typecheck
5	provider token·legacy CSS 정리	token audit와 visual contract tests
6	전체 통합 검증 및 migration note	release checklist와 smoke test 결과