docs(wbs): completely purge and replace all deprecated Blazor and MudBlazor references with Razor Pages and Tabler standards

This commit is contained in:
2026-07-12 14:47:20 +09:00
parent c56dd7e35d
commit 2a46dd5503
2 changed files with 20 additions and 27 deletions
+6 -13
View File
@@ -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/` 및 하네스 테스트 스위트의 빌드 및 통과 로그를 통해 데이터로 증빙한다. 하네스 실패 시 빌드 승격을 전면 차단한다.
+14 -14
View File
@@ -24,10 +24,10 @@
모든 작업은 아래 7가지 증빙이 함께 충족되고, 하네스 검증을 통과할 때만 완료로 본다.
- **MudBlazor 9 UI 표준 준수**: 모든 UI 컴포넌트 개발 시 **MudBlazor 9.0.0 버전** 표준 및 Interactive WebAssembly를 렌더 모드로 강제한다. Fluent UI 및 구버전(8.x 이하) 요소와의 혼용을 엄격히 배제한다.
- **Tabler UI 표준 준수**: 모든 UI 개발 시 **Tabler CSS/JS** 표준 및 ASP.NET Core Razor Pages를 기본 렌더 모드로 한다. 타 프레임워크와의 혼용을 엄격히 배제한다.
- **컴파일/빌드 완료**: 빌드 시 컴파일 에러 및 **컴파일 경고(Warning)가 0개**여야 한다.
- **DTO 및 유효성 검증 규칙**: API 입력 모델 및 DTO 유효성 검증 시 **데이터 어노테이션(Data Annotation) 방식을 기본적으로 사용**하되, 복잡한 비즈니스 조건부 유효성 검증 등 어노테이션만으로 부족한 영역은 **FluentValidation을 상호 보완적으로 적용**하여 규칙을 중앙 집중식으로 엄격히 관리해야 한다.
- **MVVM 패턴**: Blazor 화면 바인딩 정합성을 극대화하기 위해 Razor 컴포넌트(View)와 상태/검증/로직을 갖춘 DTO 및 StateService(ViewModel) 구조의 **MVVM 패턴을 철저히 지향**해야 한다.
- **Razor Pages 패턴**: ASP.NET Core Razor Pages 표준 아키텍처에 맞게, `.cshtml` 뷰와 비즈니스 서비스 계층을 완벽히 분리하고 안티포저리 토큰(CSRF 방어) 유효성 검증을 필수로 수행해야 한다.
- **Playwright E2E 하네스 검증**: 사용자 입장에서 시나리오에 따라 서비스를 직접 호출(Playwright 실행)하여, 실제 반환된 DOM 값과 화면 캡처 결과가 예측한 데이터/화면과 완벽히 일치하여 데이터로 증빙되어야 성공으로 판정한다.
- **병렬 테스트 및 인증 키 공유**: CI 테스트 및 로컬 테스트 수행 시 선후관계(순차 종속성)로 인해 병목이 생기지 않도록, 인증 완료 후의 인증 키(Cookie, Bearer Token 등)를 테스트 간 상호 공유 및 재사용(storageState 등)하도록 구성하여 **반드시 병렬(Parallel) 작업**으로 실행되어야 한다.
- `YAML` 증빙: 관련 contract/spec/governance 문서가 일관되게 갱신되어야 한다.
@@ -170,7 +170,7 @@ Phase 10 ░░░░░░░░░░░░░░░░░░░░ C#/.NET
| **P5 완전 자동화** | ~2026-12 | CI/CD + Gitea, 자율 실행 | 수동 개입 0회/주 |
| **P6 비기계적 매도전략** | 2026-06 완료 | 5팩터 confluence 엔진, KIS 조회연동, SQLite 자체평가 | WBS-6 본문 하네스 PASS (잔류위험은 P7에서 해소) |
| **P7 보완·고도화** | ~2026-08 | 캘리브레이션 실증 전환, GAS 마이그레이션 완결, deprecated 정리, E2E 통합테스트 | WBS-7.1~7.8 하네스 전부 PASS |
| **P10 .NET 엔진 고도화** | ~2026-12 | C# Domain Parity, 테스트 100+건, Application 서비스, Blazor 대시보드, 보안 경화 | `dotnet test` 전체 PASS + parity JSON gate PASS |
| **P10 .NET 엔진 고도화** | ~2026-12 | C# Domain Parity, 테스트 100+건, Application 서비스, Razor Pages 어드민 대시보드, 보안 경화 | `dotnet test` 전체 PASS + parity JSON gate PASS |
---
@@ -1465,7 +1465,7 @@ WBS-8.8 (KIS 리팩터) — 독립적 (원격 병행)
> **📌 보강 문서(2026-06-30):** 본 WBS-10 의 다수 항목이 `완료` 표기되어 있으나 실측 결과 일부 괴리(10.6 파이프라인·10.9 보안 실질 미완성)가 확인되었다. 마이그레이션 완성 우선 + 상용화 잔여 작업의 재정의는 [WBS_10_DOTNET_MIGRATION_HARDENING_2026_06_30.md](./WBS_10_DOTNET_MIGRATION_HARDENING_2026_06_30.md) 참조.
> 현황 진단(2026-06-26): .NET 프로젝트는 Python 엔진(41 모듈, 14,500 LOC) 대비 5~10%(~1,400 LOC) 수준.
> Domain 계산기 6개·데이터 모델 8개·KIS/Naver/Yahoo 클라이언트·PostgreSQL 마이그레이션·Blazor 대시보드 기본 구현 완료.
> Domain 계산기 6개·데이터 모델 8개·KIS/Naver/Yahoo 클라이언트·PostgreSQL 마이그레이션·Razor Pages 어드민 대시보드 기본 구현 완료.
> **미구현**: Application 서비스 일부, 공식 엔진, 하네스 주입, 파이프라인 오케스트레이터.
> **발견된 결함 5건**: D1) Tests.csproj Core ProjectReference 누락, D2) Tests sln 미등록, D3) appsettings.json 비밀번호 하드코딩, D4) NU1510 불필요 패키지, D5) Class1.cs placeholder 2개.
@@ -1481,7 +1481,7 @@ WBS-10.1 (기반 결함 수정)
├──→ WBS-10.7 (Application 서비스)
│ └──→ WBS-10.8 (데이터 수집 오케스트레이터)
├──→ WBS-10.9 (보안 강화)
└──→ WBS-10.10 (Blazor 대시보드 고도화)
└──→ WBS-10.10 (Razor Pages 어드민 대시보드 고도화)
```
---
@@ -1720,11 +1720,11 @@ WBS-10.1 (기반 결함 수정)
---
#### WBS-10.10 Blazor 대시보드 고도화
#### WBS-10.10 Razor Pages 어드민 대시보드 고도화
| 항목 | 내용 |
|------|------|
| **작업** | Python snapshot_admin_server_v1.py의 편집/조회 기능을 Blazor SSR로 확장. 기본 템플릿 페이지 제거 |
| **작업** | Python snapshot_admin_server_v1.py의 편집/조회 기능을 Razor Pages 뷰 및 핸들러로 구현. 기본 템플릿 페이지 제거 |
| **현재 상태** | `Dashboard.razor`는 데이터 비의존형 상태표시로 단순화되었고, `Operations.razor``Temp/operational_report.json` 고정 렌더 경로를 제공하며, Counter/Weather 기본 페이지는 삭제됨. 공개 배포본은 아직 이전 빌드가 남아 있을 수 있으므로 CI/CD 동기화가 필요함 |
| **담당 파일** | `src/dotnet/QuantEngine.Web/Components/Pages/Dashboard.razor`, `Operations.razor`, `NavMenu.razor` |
| **상태** | 완료 |
@@ -1747,24 +1747,24 @@ WBS-10.1 (기반 결함 수정)
---
#### WBS-10.11 Blazor 및 API-First 개발 가이드라인 수립
#### WBS-10.11 Razor Pages 개발 가이드라인 수립
| 항목 | 내용 |
|------|------|
| **작업** | [Temp/CLAUDE.md](file:///C:/Temp/data_feed/Temp/CLAUDE.md)의 API-First 아키텍처, 이중 토큰 인증, SignalR, MudBlazor UX 패턴Blazor 관련 핵심 개발 지침을 [AGENTS.md](file:///C:/Temp/data_feed/AGENTS.md)에 차용/반영 |
| **작업** | [Temp/CLAUDE.md](file:///C:/Temp/data_feed/Temp/CLAUDE.md)의 API-First 아키텍처, 이중 토큰 인증, SignalR, Tabler UX 및 CSRF 방어Razor Pages 관련 핵심 개발 지침을 [AGENTS.md](file:///C:/Temp/data_feed/AGENTS.md)에 차용/반영 |
| **현재 상태** | [Temp/CLAUDE.md](file:///C:/Temp/data_feed/Temp/CLAUDE.md) 분석 후 [AGENTS.md](file:///C:/Temp/data_feed/AGENTS.md)의 Section 5b로 이식 완료 |
| **담당 파일** | [docs/ROADMAP_WBS.md](file:///C:/Temp/data_feed/docs/ROADMAP_WBS.md), [AGENTS.md](file:///C:/Temp/data_feed/AGENTS.md) |
| **상태** | 완료 |
| 세부 WBS | 작업 | 성공 판단 데이터 |
|----------|------|------------------|
| 10.11.1 | CLAUDE.md의 Blazor 참조 지침 핵심사항 추출 및 공식화 | [Temp/CLAUDE.md](file:///C:/Temp/data_feed/Temp/CLAUDE.md) 분석 내역 도출 |
| 10.11.2 | AGENTS.md에 Blazor 개발 규칙 5b 섹션 신설 및 적용 | [AGENTS.md](file:///C:/Temp/data_feed/AGENTS.md) 내 5b 섹션 코드 삽입 완료 |
| 10.11.1 | CLAUDE.md 및 실제 적용된 Razor Pages 지침 핵심사항 추출 및 공식화 | [Temp/CLAUDE.md](file:///C:/Temp/data_feed/Temp/CLAUDE.md) 분석 내역 도출 |
| 10.11.2 | AGENTS.md에 Razor Pages 개발 규칙 5b 섹션 신설 및 적용 | [AGENTS.md](file:///C:/Temp/data_feed/AGENTS.md) 내 5b 섹션 코드 삽입 완료 |
| 10.11.3 | 스펙 검증 스크립트 실행을 통한 구성 유효성 검증 | `validate_specs.py` 무오류 통과 |
**성공 하네스 (데이터 기준)**:
```
검증: python tools/validate_specs.py → EXIT 0
검증: C:\Temp\data_feed\AGENTS.md 내에 '5b. Blazor & API-First 개발 규칙' 및 'IXxxBrowserClient', 'TokenRefreshHandler' 키워드 존재
검증: C:\Temp\data_feed\AGENTS.md 내에 '5b. Razor Pages 개발 규칙' 및 'IXxxBrowserClient', 'TokenRefreshHandler' 키워드 존재
```
---
@@ -1827,8 +1827,8 @@ WBS-10.1 (기반 결함 수정)
| 10.7 Application 서비스 | 🟠 High | 중간 | 10.1 | 3시간 | 0% |
| 10.8 데이터 수집 오케스트레이터 | 🟡 Medium | 중간 | 10.7 | 4시간 | 0% |
| 10.9 보안 강화 | 🟠 High | 낮음 | 10.1 | 1시간 | 0% |
| 10.10 Blazor 대시보드 고도화 | 🟡 Medium | 중간 | 10.7 | 4시간 | 0% |
| 10.11 Blazor 개발 지침 차용 | 🟢 Low | 낮음 | 없음 | 1시간 | **100%** ✅ (2026-06-29) |
| 10.10 Razor Pages 어드민 대시보드 고도화 | 🟡 Medium | 중간 | 10.7 | 4시간 | 0% |
| 10.11 Razor Pages 개발 지침 수립 | 🟢 Low | 낮음 | 없음 | 1시간 | **100%** ✅ (2026-06-29) |
---