Platform Docs

Appearance

아이콘 전용 버튼 전환 — 인수인계 및 작업 계획 ​

이 문서는 "아이콘으로 충분한 동작은 아이콘만으로 심플하게" 규칙을 관리자·공용 화면 전체로 확장하기 위한 현재 상태와 다음 작업을 정리한다. 새 세션은 이 문서 + docs/BUTTON_INVENTORY.md만 읽고 이어서 진행할 수 있다.

1. 규칙 ​

동작 성격표기예
아이콘으로 의미가 분명한 도구 동작아이콘만 (테두리 없음) + 툴팁 + aria-label이동·수정·삭제(행/툴바)·초기화·복사·펼치기·검증
주 동작·확정 동작텍스트 유지저장·등록·반영·최종 삭제 확정·대화상자 footer
폼 라벨/안내텍스트필드 라벨, 설명
  • 아이콘 전용 버튼은 반드시 aria-label(접근성 이름) + PortalTooltip(시각 힌트)을 함께 둔다. 기존 테스트가 getByRole("button", { name: "..." })로 이름을 검증하므로 라벨을 지우면 깨진다.
  • 파괴적 동작은 PortalConfirm(Popconfirm) 확인 절차를 유지한다.
  • data-testid는 그대로 보존한다.

2. 이미 적용된 범위 (커밋 기준) ​

화면내용릴리스
관리자 프로세스관리 상세 액션 5개위로/아래로/수정/삭제(붉은 아이콘)/하위 노드 추가 → 아이콘 전용PC v1.0.20~21
첨부파일 다운로드/삭제 (AssetAttachmentList)텍스트 링크 → 아이콘 전용(툴팁 유지)PF v0.6.146
공용 버튼 CSS레거시 .pf-button 박스 스타일을 :not(.ant-btn)으로 스코프, 아이콘 전용 컴팩트 규칙 추가PF v0.6.147
관리자 콘솔(AdminConsole)템플릿·오류 리포트·CSV 내보내기 → 아이콘 전용, 업로드 오류 닫기에 툴팁 보강작업 트리(미릴리스)
전결 규정 관리(ApprovalPolicyManager)새 규정 → 아이콘 전용, 단계/적용 대상 삭제에 툴팁 보강작업 트리(미릴리스)
역할·시스템 마스터(RoleSystemMasterManager)템플릿·전체 내보내기 → 아이콘 전용, 행 수정/삭제에 툴팁 보강작업 트리(미릴리스)

현재 버전: portal-foundation v0.6.152, ProcessCenter v1.0.26.

3. 남은 작업 (목록은 docs/BUTTON_INVENTORY.md, 재생성 node scripts/buttonInventory.mjs) ​

총 130개 버튼: 아이콘만 후보 49 · 텍스트 유지 46 · 아이콘 전용인데 aria-label 없음 24 · 이미 아이콘 전용 5 · 툴팁 확인 6.

목록의 분류는 buttonInventory.mjs의 정규식 휴리스틱이라 화살표 함수(=>)가 있는 버튼을 "텍스트 있음"으로 오인한다. 후보는 참고값이고, 실제 전환 여부는 화면별 결정 기록을 따른다(결정 항목은 docs/BUTTON_INVENTORY.md를 직접 수정하지 않고 아래 표에 누적한다).

묶음대상 패널 (아이콘만 후보)
2NoticeBoard.tsx(3) · PortalGroupManagement.tsx(6) · PortalMenuManager.tsx(0)
3WorkflowEntityPropertyEditor.tsx(4) · WorkflowGatewayEntityDetail.tsx(4) · WorkflowEntityRelationshipEditor.tsx
4Directory*Panel.tsx · OrganizationAccessManager.tsx(2) · ConnectionHealthReport.tsx(1) · RetryQueuePanel.tsx
  • 각 묶음에서 "아이콘 전용인데 라벨 없는 24개"의 aria-label + 툴팁을 함께 채운다.
  • 화면별로 "아이콘만 / 텍스트 유지" 목록을 먼저 확정한 뒤 수정한다(대화상자 footer·저장/등록은 텍스트 유지).

묶음 1 결정 기록 (적용 완료) ​

화면아이콘만 (도구 동작)텍스트 유지 (주 동작)툴팁·aria 보강
AdminConsole.tsx템플릿, 오류 리포트, CSV 내보내기UPLOAD EXCEL(파일 등록), IMPORT NOW(반영)업로드 오류 닫기
ApprovalPolicyManager.tsx새 규정비활성화, 기안·합의·결재·통보 추가, 대상 추가, 목록 행, 전결규정 저장단계 삭제, 적용 대상 삭제
RoleSystemMasterManager.tsx템플릿 다운로드, 전체 내보내기엑셀 가져오기, 추가/저장/취소행 수정·삭제(수정 중에는 취소)
  • 라벨을 지우는 버튼은 모두 PortalTooltip + aria-label을 함께 둔다. AdminConsole은 기존 테스트가 getByLabelText로 이름을 검증하므로 한국어 이름은 그대로 유지했다.
  • 아이콘 도구 버튼은 role-system-manager__icon-action(정사각형) 클래스와 새로 추가한 approval-policy-manager__primary--icon을 사용한다. 레거시 .pf-button과 무관한 네이티브 버튼이므로 박스 스타일 회귀 위험이 없다.
  • 파일 업로드/가져오기와 저장·등록·반영은 "주 동작"으로 보아 텍스트를 유지했다(인벤토리의 후보 표기와 다름).
  • ApprovalPolicyManager의 목록 행(ChevronRight)과 빠른 추가 버튼은 항목·요소 이름이 의미를 결정하므로 텍스트를 유지한다.
  • 검증: pnpm exec vitest run client/src/components/AdminConsole.test.tsx client/src/components/RoleSystemMasterManager.test.tsx client/src/components/ProcessManagementPanel.test.tsx (9 tests) · pnpm check.

4. 릴리스·검증 절차 (이 리포지토리 관례) ​

bash
# 1) 공용 패키지를 바꿀 때만 (portal-foundation/packages/ui-react)
#    패키지 이름은 @hohyun94/portal-foundation 이다(@portal-foundation/ui-react 가 아니다).
pnpm --filter @hohyun94/portal-foundation build
pnpm --filter @hohyun94/portal-foundation test
pnpm --dir packages/ui-react pack --pack-destination ../../ProcessCenter/vendor
# pack 산출물은 hohyun94-portal-foundation-<ver>.tgz 로 자동 생성된다(이름 변경 불필요)
# 2) ProcessCenter에서 의존성/락파일 갱신 (tarball은 .gitignore 때문에 -f 필수)
git add -f vendor/hohyun94-portal-foundation-<ver>.tgz
pnpm install --prefer-offline
node scripts/portalFoundationGuard.mjs      # 설치 버전·Vite 캐시 점검
# 3) 검증 후 커밋/태그/푸시 (PF와 PC 각각)
pnpm check && pnpm build && pnpm test:common-ui
pnpm exec vitest run <변경한 화면의 테스트 파일들>
git tag v<x.y.z> && git push origin main && git push origin v<x.y.z>
  • 앱만 바꿀 때는 PF 릴리스가 필요 없다(tone="ghost" 등은 이미 0.6.147에 있음).
  • 아이콘 전용 버튼의 실제 모양은 공용 CSS가 좌우한다. 박스처럼 보이면 레거시 .pf-button 규칙이 다시 덮고 있는지 확인한다(styles.css의 :not(.ant-btn) 스코프 유지).
  • vendor tarball 은 게시된 이름·버전을 쓴다. 0.6.131·0.6.155 tarball 은 내부 이름이 @portal-foundation/ui-react 인 리네임 이전 로컬 빌드였다(의존성 키와 내부 이름 불일치 — pnpm 이 키 경로로 설치해 동작은 했지만 lockfile 에 레거시 이름이 남았다). 0.6.156 부터 @hohyun94/portal-foundation 로 일치한다.

5. 환경 주의사항 ​

  • 개발 서버는 Docker Compose(docker-compose.dev.yml)의 process-center-dev이며 소스만 바인드 마운트, node_modules는 익명 볼륨이다. vendor 버전을 올린 뒤에는 docker restart process-center-dev 한 번이면 predev 가드가 설치를 자동 복구한다. 자세한 내용은 docs/DEV_TROUBLESHOOTING.md 1~8장.
  • 테스트는 vitest.config.ts에 @vitejs/plugin-react가 적용되어 있다. 컴포넌트를 새로 만들 때도 관례대로 React를 import 하면 안전하다.
  • 브라우저 반영 확인: document.documentElement.dataset.pfUiVersion(예: 0.6.147) 및 강력 새로고침(Ctrl+Shift+R).