Platform Docs

Appearance

Ant Design Phase 2.0·2.1 초기 기준선 ​

1. 문서 목적 ​

이 문서는 main에서 분기한 feat/antd-phase-2-components 브랜치의 Phase 2.0 기준선과 Phase 2.1 AuthCard 전환 작업 범위를 고정한다. 목표는 기존 공개 API와 접근성 계약을 유지하면서 인증 화면을 Ant Design 기반으로 전환하는 것이다.

2. 기준 브랜치 ​

항목값
기준 브랜치main
작업 브랜치feat/antd-phase-2-components
단계Phase 2.0 기준선 및 Phase 2.1 AuthCard
대상 패키지@hohyun94/portal-foundation (packages/ui-react)
주요 기반antd, @ant-design/icons, PortalConfigProvider, theme-client

작업 브랜치는 PR #6의 병합 커밋 eaba7cd를 기준으로 생성했으며 현재 main과 동일한 상태다.

3. Phase 2 범위 ​

포함 범위 ​

Phase 2.0에서는 공개 API, 기존 컴포넌트 위치, CSS 및 접근성 계약을 기록한다. Phase 2.1에서는 AuthCard를 Card, Form, Input, Alert, Button 조합으로 전환한다.

제외 범위 ​

PortalShell, PortalAdminShell, 메뉴 권한 모델, 모바일 drawer, DirectoryManagement, AssetAttachmentList, 전체 데이터 테이블 전환은 이번 단계에서 다루지 않는다. 해당 항목은 레이아웃·데이터 전환 단계에서 별도 계획으로 진행한다.

4. Phase 2.0 기준선 체크리스트 ​

  • [x] main에서 Phase 2 작업 브랜치 생성
  • [x] PortalConfigProvider와 Ant Design 토큰 매핑이 main에 존재함
  • [x] PortalButton, PortalStatusBadge, PortalEmptyState, PortalBreadcrumbs 전환이 main에 존재함
  • [x] theme-client 기본 테마 계약 테스트가 현재 DEFAULT_PORTAL_THEME와 일치함
  • [x] ui-react 공개 진입점 및 기존 소스 파일 목록 확인
  • [ ] AuthCard의 실제 public export와 prop 사용 현황 확정
  • [ ] 기존 AuthCard markup, CSS class, selector, aria 속성 캡처
  • [ ] 소비 포털별 인증 callback 및 오류 표현 사용 현황 확인
  • [ ] Phase 2.1 컴포넌트 테스트 시나리오 추가

5. 현재 ui-react 구조 ​

현재 packages/ui-react/src에는 다음 공통 영역이 있다.

영역파일 또는 디렉터리Phase 2 처리
Providerproviders/사용, 변경 최소화
기본 컴포넌트PortalComponents.tsx기존 구현과 API 조사
포털 셸PortalShell.tsx, PortalAdminShell.tsx이번 단계 제외
테마 정책PortalThemePolicySettings.tsx이번 단계 제외
데이터 셸dataShells.tsx이번 단계 제외
콘텐츠contentComponents.tsx이번 단계 제외
메뉴menuManagement.tsx이번 단계 제외
아이콘iconCatalog.tsx, productMarks.tsxPhase 2.3 후보
테스트index.test.tsx, portalComponents.test.tsx, portalShell.test.tsx, dataShells.test.tsx회귀 기준

6. Phase 2.1 AuthCard 설계 기준 ​

6.1 목표 ​

기존 인증 화면의 외부 동작을 유지하면서 내부 렌더링과 입력 검증을 Ant Design 기반으로 교체한다. PortalConfigProvider 외부에서 별도의 ConfigProvider를 요구하지 않으며, 인증 정책이나 세션 처리는 AuthCard가 소유하지 않는다.

6.2 권장 내부 조합 ​

tsx
<Card>
  <Form>
    <Form.Item>
      <Input />
    </Form.Item>
    <Form.Item>
      <Input.Password />
    </Form.Item>
    <Alert />
    <Button htmlType="submit" />
  </Form>
</Card>

6.3 유지할 외부 계약 ​

  • 제목 및 설명 영역
  • 로고 또는 branding 영역
  • 사용자 식별자 입력
  • 비밀번호 입력
  • submit callback
  • loading 상태
  • disabled 상태
  • 인증 오류 메시지
  • footer 또는 추가 action 영역
  • 기존 CSS class 및 테스트 selector
  • label, error, description의 접근성 연결

새 Ant Design 내부 타입을 소비 포털의 공개 API로 직접 노출하지 않는다. 기존 prop을 유지할 수 없는 경우에는 adapter 타입을 두고 변경 사유를 문서화한다.

6.4 상태 모델 ​

상태기대 동작
초기입력값과 submit action을 표시한다.
입력 오류필드별 validation과 accessible error를 표시한다.
인증 오류서버 또는 외부 callback이 전달한 오류를 Alert로 표시한다.
제출 중중복 제출을 차단하고 버튼 loading을 표시한다.
disabled입력, submit, 보조 action을 정책에 맞게 비활성화한다.
성공성공 후 이동·세션 처리는 소비 포털 callback이 담당한다.

7. Phase 2.1 테스트 계획 ​

최소 테스트 시나리오는 다음과 같다.

  1. 기본 제목, 설명, 입력, submit 버튼 렌더링
  2. 필수 입력값 누락 시 submit callback 미호출
  3. 정상 입력 시 { identifier, password } 또는 기존 계약에 맞는 값 전달
  4. loading 중 중복 submit 방지
  5. disabled 상태에서 입력과 action 비활성화
  6. 인증 오류의 Alert 표시 및 accessible description 연결
  7. 키보드 Tab 이동과 Enter 제출
  8. 비밀번호 표시/숨김 전환
  9. 기존 CSS class와 selector 유지
  10. PortalConfigProvider의 light/dark theme 아래 시각적 토큰 적용

8. 검증 명령 ​

Phase 2.0 기준선 및 Phase 2.1 구현 완료 시 다음 명령을 실행한다.

bash
pnpm install --frozen-lockfile
pnpm check
pnpm build
pnpm test
pnpm --filter @hohyun94/portal-foundation check
pnpm --filter @hohyun94/portal-foundation test

검증 결과는 PR description에 기록한다. pnpm install --frozen-lockfile이 실패할 경우 lockfile과 workspace manifest의 불일치 원인을 먼저 분리하고, 임의로 lockfile을 갱신하지 않는다.

9. 완료 기준 ​

Phase 2.0 완료 ​

  • [x] 작업 브랜치가 main에서 생성됨
  • [x] 본 기준선 문서가 작업 브랜치에 커밋됨
  • [ ] AuthCard의 기존 export와 prop 계약이 확정됨
  • [ ] 기존 접근성·CSS 계약이 확인됨
  • [ ] Phase 2.1 테스트 시나리오가 코드로 추가됨

Phase 2.1 완료 ​

  • [ ] AuthCard의 기존 public export가 유지됨
  • [ ] Ant Design Card, Form, Input, Alert, Button 기반 구현 완료
  • [ ] loading, disabled, validation, error 동작 정의 및 테스트 완료
  • [ ] keyboard 및 accessible name/error 연결 검증 완료
  • [ ] pnpm check, pnpm build, pnpm test 통과
  • [ ] 변경사항을 별도 PR로 리뷰 가능하게 정리

10. 다음 작업 순서 ​

  1. main의 실제 AuthCard export와 구현 위치 확인
  2. 소비 포털에서 사용하는 prop 및 callback 검색
  3. 기존 테스트와 접근성 selector를 기준선으로 추가
  4. AuthCard Ant Design 내부 구현 작성
  5. 컴포넌트 단위 테스트 및 ui-react 회귀 테스트 실행
  6. 전체 workspace check/build/test 실행
  7. Phase 2.1 PR 생성
  8. 이후 Phase 2.2 ThemePicker로 진행