docs(wbs): completely purge and replace all deprecated Blazor and MudBlazor references with Razor Pages and Tabler standards
This commit is contained in:
@@ -142,22 +142,15 @@
|
||||
- 클라우드 서버(hz-prod-01)는 `/usr/bin/python3`를 사용하므로 `.gitea/workflows/ci.yml`은 `python3` 유지
|
||||
- **임시 파일 관리**: 개발/디버깅 목적의 모든 휘발성 임시 파일 및 로그는 반드시 `Temp/` 디렉토리 하위에서만 생성해야 하며, 루트나 다른 패키지 경로에 임시 파일을 만드는 것은 금지한다. 불가피하게 생성할 경우 반드시 접두사/접미사 규칙(`debug_*`, `tmp_*`, `mock_*`, `*_temp.*`)을 준수하여 `.gitignore`에 필터링되도록 한다.
|
||||
|
||||
## 5b. Blazor & API-First 개발 규칙 (TaxBaik 참조 모델 적용)
|
||||
- **핵심 아키텍처 원칙**: Blazor WASM 개발은 **패턴화(Pattern), 템플릿화(Template), 컴포넌트화(Component), MVVM 패턴, API-First 아키텍처**를 최우선 가치로 준수한다.
|
||||
- **렌더 모드 표준**: Blazor **Interactive WebAssembly** 를 기본 렌더 모드로 한다. InteractiveServer 는 사용하지 않으며, UI 컴포넌트는 **MudBlazor** 로 통일한다 (Fluent UI 는 폐기).
|
||||
- **API-First 아키텍처 (MVVM + FastEndpoints)**:
|
||||
- **백엔드(Server)**: 기존 컨트롤러 구조를 전면 배제하고, REPR(Request-Endpoint-Response) 패턴을 보장하는 **FastEndpoints** 프레임워크를 기반으로 백엔드 API 엔드포인트를 구현하여 단일 책임 원칙(SRP)을 준수한다.
|
||||
- **프론트엔드(Client)**: Blazor WASM 클라이언트는 Razor 컴포넌트(View)와 상태/검증/로직을 갖춘 DTO 및 StateService(ViewModel) 구조의 **MVVM 패턴**을 지향하여 화면 바인딩 정합성을 극대화한다. UI 계층은 비즈니스 로직이나 DB에 직접 결합되지 않고, `IXxxBrowserClient` 또는 추상화된 HttpClient API 클라이언트를 통해서만 백엔드 API와 통신한다.
|
||||
- **이중 토큰 인증 패턴**: Access Token(15분) 및 Refresh Token(7일) 이중 토큰 패턴을 적용하며, HttpClient 요청 시 401 Unauthorized를 가로채어 자동으로 localStorage의 Refresh Token으로 토큰을 자동 갱신 및 재시도하는 `TokenRefreshHandler` (DelegatingHandler) 구조를 준수한다.
|
||||
- **실시간 알림 (SignalR)**: 실시간 알림 기능은 상태를 직접 동기화하는 용도가 아닌 단순 Event-driven 브로드캐스트 알림으로 설계하며, 클라이언트는 알림 수신 후 API 호출을 통해 최종 데이터를 검증 및 동기화한다.
|
||||
## 5b. Razor Pages 개발 규칙 (Tabler 참조 모델 적용)
|
||||
- **핵심 아키텍처 원칙**: 어드민 웹 개발은 ASP.NET Core Razor Pages 패턴 및 단일 책임 원칙(SRP)을 따르는 비즈니스 서비스 분리를 최우선 가치로 준수한다.
|
||||
- **렌더 모드 표준**: 순수 서버 사이드 렌더링(SSR) 및 Razor 뷰 엔진을 활용하며, UI 디자인은 Tabler CSS/JS 프레임워크 표준에 맞추어 구현한다.
|
||||
- **보안 및 CSRF 방어**: 모든 POST/CUD 액션 처리 시 안티포저리 토큰(`@Html.AntiForgeryToken()`) 유효성 검증을 필수로 수행하여 CSRF 공격을 전면 차단한다.
|
||||
- **UI/UX 구현**:
|
||||
- MudBlazor 컴포넌트(MudDataGrid Dense + Virtualize)를 사용하여 고밀도(행높이 32px 수준) 및 대량 데이터 성능을 보장한다.
|
||||
- CRUD 생성 및 수정 작업 시 화면 플래시를 제거하기 위해 MudDialog 모달 대화상자 패턴을 사용하며, 삭제 작업에는 `ConfirmDialog` 등을 이용해 명시적 사용자 확인을 거친다.
|
||||
- Tabler 기반 테이블 뷰와 모달 대화상자(Modal Dialog) 패턴을 일관되게 활용하여 CRUD 및 데이터 수정 저장을 플래시 없이 유연하게 연동한다.
|
||||
- 상태 및 등급 구분에는 시각적 가시성을 위한 Status Color Chips(Success, Warning, Error)를 적용한다.
|
||||
- **DTO 및 유효성 검증 규칙**: API 입력 모델 및 데이터 전송 객체(DTO) 유효성 검증 시 데이터 어노테이션(DTO Annotation) 방식을 기본적으로 사용하되, 복잡한 비즈니스 조건부 유효성 검증이나 데이터베이스 연동 유효성 검사 등 어노테이션만으로 부족한 영역은 **FluentValidation**을 상호 보완적으로 적용하여 유효성 규칙을 중앙 집중식으로 엄격히 관리한다.
|
||||
- **엔지니어링 표준화 지침**:
|
||||
- **표준화 & 컴포넌트화**: UI 요소와 재사용 가능한 비즈니스 코어는 컴포넌트 단위로 구조화하며, 파편화된 개별 커스텀 스타일이나 인라인 데이터 변환을 배제하고 MudBlazor 및 표준 헬퍼 클래스를 공통 활용한다.
|
||||
- **정규화 & 비정규화**: DB 스키마 설계 시에는 정규화 모델을 준수하여 중복과 파편화를 방지하고, 화면 조회 성능이나 BFF 통합 렌더링을 위한 데이터 구조화 단계에서만 안전하게 비정규화된 DTO/뷰 모델을 빌드하여 전송한다.
|
||||
- **표준화 & 컴포넌트화**: 공통 레이아웃(`_AdminLayout.cshtml`)과 부분 뷰(Partial View)를 적극적으로 분리/재사용하고, 파편화된 개별 스타일을 지양하여 Tabler 및 표준 유틸리티 클래스를 공통 활용한다.
|
||||
- **데이터 정합성 & 리팩토링**: 모든 비즈니스 도메인의 상태 전이는 ACID 트랜잭션 단위 및 인프라 레이어의 일관성 제어 규칙을 보장하며, 복잡도가 과한 하드코딩 영역은 SRP(단일 책임 원칙) 및 인터페이스 기반 구조로 점진적 리팩토링한다.
|
||||
- **파편화 & 바이브 코드 방지**: provenance(근거) 없는 암묵적 룰이나 감에 의존한 구조(Vibe Code)의 무분별한 탑재를 금지하고, 모든 상태 및 에러 코드는 코드북에 엄격히 등록된 정방형 정규 값만 할당한다.
|
||||
- **하네스 & 테스트 안정성**: 모든 패치는 `Temp/` 및 하네스 테스트 스위트의 빌드 및 통과 로그를 통해 데이터로 증빙한다. 하네스 실패 시 빌드 승격을 전면 차단한다.
|
||||
|
||||
Reference in New Issue
Block a user