kjh2064
e5981769b9
TaxBaik CI/CD / build-and-deploy (push) Successful in 2m11s
- Admin: replace the global @rendermode on <Routes>/<Router> with per-page render mode. Login.razor now prerenders (form visible before WASM loads); every other [Authorize] page stays prerender: false to avoid the AuthorizeRouteView blank-render regression from earlier attempts. Adds a "준비 중" -> "로그인" splash tied to WASM boot completion, and lets the authenticated-shell loading overlay stay up until AdminShell actually renders. - Contact.cshtml: fix the "Agree" checkbox missing value="true" - a checked box sent the browser-default "on", which bool model binding can't parse, so ModelState.IsValid silently went false and OnPostAsync returned a blank form with no visible error on every submission. Validation summary widened from ModelOnly to All so this class of failure isn't silent again. - TelegramInquiryNotificationService: read Telegram:InquiryChatId (falling back to ChatId) instead of only ChatId, matching the channel routing CLAUDE.md documents and deploy.yml already provisions as separate secrets. - Reconcile CLAUDE.md's self-contradicting Phase 8 prerender notes (Phase 9), rewrite validate_admin_render.sh for the per-page design, and add a SmartAdmin 5.5 design reference section to DOUZONE_UX_GUIDE.md for future admin screens (existing screens unchanged, tracked as WBS P4-03). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
128 lines
6.3 KiB
Markdown
128 lines
6.3 KiB
Markdown
# DOUZONE UX Guide
|
|
|
|
이 문서는 TaxBaik 어드민 UX의 기준선이다. 목표는 더존 세무회계프로그램류의 고밀도 운영 화면을 구현하되, TaxBaik의 도메인과 검증 규칙을 유지하는 것이다.
|
|
|
|
## UX Principles
|
|
|
|
- 고밀도 우선: 한 화면에서 상태, 입력, 결과, 작업을 함께 본다.
|
|
- 표준 동선 우선: 목록 -> 상세 -> 수정 -> 저장 흐름을 기본으로 둔다.
|
|
- 빠른 입력 우선: 마우스 최소, 키보드/단축 동선 최대, 기본값 명확화.
|
|
- 상태 가시성 우선: 진행중/성공/실패/비활성/삭제됨을 즉시 구분 가능하게 한다.
|
|
- 회귀 최소화 우선: 같은 화면 패턴은 같은 컴포넌트와 같은 구조를 사용한다.
|
|
- 추측 금지: 의미가 불명확한 텍스트, 상태, 버튼, 색상은 새로 만들지 않는다.
|
|
|
|
## Layout Template
|
|
|
|
어드민 화면은 기본적으로 아래 구조를 따른다.
|
|
|
|
```text
|
|
PageHeader
|
|
FilterBar or ActionBar
|
|
ContentSurface
|
|
-> DenseGrid or DetailPanel
|
|
-> EmptyState when empty
|
|
-> Paging/Footer when needed
|
|
```
|
|
|
|
권장 규칙:
|
|
|
|
- 페이지 제목은 1개만 둔다.
|
|
- 보조 설명은 1줄만 둔다.
|
|
- 주요 액션은 우측 상단 또는 헤더 우측에 둔다.
|
|
- 목록은 `Dense`를 기본으로 한다.
|
|
- 상세/수정은 좌우 2열 또는 상단 요약 + 하단 폼 패턴을 우선한다.
|
|
|
|
## Component Template
|
|
|
|
### Page Header
|
|
|
|
- 구성: `Eyebrow`, `Title`, `Subtitle`, `Primary Action`
|
|
- 역할: 화면 맥락 고정, 다음 행동 제시
|
|
- 금지: 동일 화면에 헤더가 2개 이상 존재
|
|
|
|
### Dense Grid
|
|
|
|
- 행 간격은 좁게 유지한다.
|
|
- 컬럼은 우선순위 순으로 배치한다.
|
|
- 상태는 텍스트 대신 칩/색상/아이콘으로 함께 보여준다.
|
|
- 작업 버튼은 `보기`, `수정`, `삭제`처럼 짧고 일관되게 둔다.
|
|
|
|
### Form
|
|
|
|
- 기본값은 채워진 상태로 시작한다.
|
|
- 저장 전 필수 검증은 화면에서 즉시 보인다.
|
|
- 저장되지 않는 필드는 read-only로 바꾼다.
|
|
- 입력이 많은 폼은 섹션으로 나누되, 섹션 수는 최소화한다.
|
|
|
|
### Empty State
|
|
|
|
- 데이터 없음, 필터 결과 없음, 로드 실패를 구분한다.
|
|
- 단순 문구보다 다음 행동 버튼을 함께 둔다.
|
|
|
|
### Status Chip
|
|
|
|
- 상태는 문자열 그대로 노출하지 말고 칩으로 시각화한다.
|
|
- 색상은 의미를 유지한다.
|
|
- 동일 상태는 동일 색을 사용한다.
|
|
|
|
## SmartAdmin 5.5 Design Reference (2026-07-03, 신규 화면부터 적용)
|
|
|
|
이 섹션은 어드민의 **시각적 스킨**(색상, 카드 크롬, 로그인 화면 스타일, 셸 레이아웃) 기준이다. 위 UX Principles(고밀도, 표준 동선, 더존 정신)는 그대로 유지하고, SmartAdmin 5.5는 그 위에 입히는 룩앤필만 담당한다.
|
|
|
|
- 소스: `legacy/smartadmin/`(로컬에 이미 포함된 v5.5 HTML/CSS 데모 패키지, Bootstrap 5 기반). 정확한 색상/여백 값이 필요하면 이 디렉터리를 직접 참조한다(추측 금지).
|
|
- 적용 범위: **향후 신규 어드민 화면부터**. 기존 20개+ 화면(Dashboard, Blog, Inquiry, Client 등)은 이번엔 재단장하지 않는다. 기존 화면을 다른 이유로 수정할 때 자연스럽게 이 기준으로 수렴시킨다.
|
|
|
|
### 매핑 표
|
|
|
|
| SmartAdmin 5.5 참조 | 파일 | TaxBaik MudBlazor 대응 |
|
|
| --- | --- | --- |
|
|
| 상단 `<header>` 툴바 | `dashboard-control-center.html` | `AdminShell`의 `MudAppBar` |
|
|
| `<aside class="app-sidebar">` (로고 + 필터 입력 + 메뉴) | `dashboard-control-center.html` | `AdminShell`의 `MudDrawer` (검색/필터 입력 포함) |
|
|
| 로그인 카드 (`rounded-4`, 반투명 다크 글래스, `bg-dark bg-opacity-50`) | `auth-login.html` | `AdminLoginForm.razor`의 `MudPaper` 카드 — 반투명/블러 배경 톤 참고 |
|
|
| 색상 팔레트 | `colorpalette.html`, `css/smartapp.min.css` | `App.razor`의 `MudTheme.Palette` (Primary/Secondary/Tertiary 등) |
|
|
| 카드형 위젯 | `dashboard-*.html` | `AdminMetricCard`, `MudPaper` 기반 카드 |
|
|
|
|
### 적용 규칙
|
|
|
|
- 새 어드민 화면을 만들 때: 레이아웃/동선/밀도는 `DOUZONE_UX_GUIDE.md` 상단 원칙을 따르고, 색상·카드 모서리·그림자·로그인류 화면의 톤은 `legacy/smartadmin/`을 참조해 `MudTheme`/CSS 변수로 반영한다.
|
|
- SmartAdmin 원본은 jQuery/Bootstrap 5 기반이므로 JS/DOM 구조를 그대로 이식하지 않는다. **시각적 토큰(색, 반경, 여백, 타이포그래피)만** 가져오고, 동작은 MudBlazor 컴포넌트로 구현한다.
|
|
- 기존 화면을 SmartAdmin 스타일로 일괄 재단장하는 작업은 별도 WBS로 `docs/ADMIN_PATTERN_CRITIQUE_WBS.md`에 등록한 뒤 진행한다(이번 범위 아님).
|
|
|
|
## Text And Labels
|
|
|
|
- 라벨은 짧게 쓴다.
|
|
- 같은 개념은 같은 단어를 쓴다.
|
|
- 약어는 화면 전체에서 통일한다.
|
|
- 운영자가 오해할 수 있는 추상적인 표현은 금지한다.
|
|
|
|
## Serving Rules
|
|
|
|
- 공개 사이트는 SSR, 어드민은 Blazor WebAssembly 기준으로 본다.
|
|
- 어드민 화면은 API-first 경유를 기본으로 한다.
|
|
- JS는 불가피할 때만 사용하고, 모듈로 격리한다.
|
|
- 상태/메뉴/라우트/버튼은 문자열 흩뿌리기를 금지하고 공통 상수 또는 템플릿으로 묶는다.
|
|
|
|
## Reference Rules
|
|
|
|
- 이 문서를 어드민 UX의 1차 기준으로 사용한다.
|
|
- 세부 코드 규칙은 [ENGINEERING_HARNESS.md](./ENGINEERING_HARNESS.md)를 따른다.
|
|
- 콤보/선택/검색 규칙은 [COMBO_POLICY.md](./COMBO_POLICY.md)를 따른다.
|
|
- 공통코드/저장값 규칙은 [COMMON_CODE_POLICY.md](./COMMON_CODE_POLICY.md)를 따른다.
|
|
- 패턴 비판과 WBS는 [ADMIN_PATTERN_CRITIQUE_WBS.md](./ADMIN_PATTERN_CRITIQUE_WBS.md)를 따른다.
|
|
- 문서 인덱스는 [INDEX.md](./INDEX.md)를 따른다.
|
|
|
|
## Prohibited Patterns
|
|
|
|
- 목록마다 서로 다른 헤더 구조
|
|
- 버튼 색과 의미의 중복/충돌
|
|
- 저장 안 되는 필드를 편집 가능한 척 보여주기
|
|
- 전역 JS 상태에 의존하는 편집기
|
|
- 같은 CRUD 화면의 개별 구현체마다 다른 DOM/행 높이/행동 패턴
|
|
- 불필요한 중첩 컴포넌트와 과한 추상화
|
|
|
|
## Acceptance Criteria
|
|
|
|
- 신규 어드민 화면은 이 문서의 레이아웃/컴포넌트 규칙 중 최소 80%를 따른다.
|
|
- 기존 화면은 새로 건드릴 때 이 문서로 수렴한다.
|
|
- 화면 추가 시 `PageHeader`, `EmptyState`, `DenseGrid`, `Form` 패턴 중 하나 이상을 재사용한다.
|