From 70951510918519479c7c0f08fee30878b7b65ecd Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Mon, 29 Jun 2026 09:48:48 +0900 Subject: [PATCH] docs: establish Blazor & API-First guidelines (WBS-10.11) --- AGENTS.md | 10 ++++++++++ docs/ROADMAP_WBS.md | 23 +++++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index bdeeb2c..44eee9c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -134,6 +134,16 @@ - 클라우드 서버(hz-prod-01)는 `/usr/bin/python3`를 사용하므로 `.gitea/workflows/ci.yml`은 `python3` 유지 - **임시 파일 관리**: 개발/디버깅 목적의 모든 휘발성 임시 파일 및 로그는 반드시 `Temp/` 디렉토리 하위에서만 생성해야 하며, 루트나 다른 패키지 경로에 임시 파일을 만드는 것은 금지한다. 불가피하게 생성할 경우 반드시 접두사/접미사 규칙(`debug_*`, `tmp_*`, `mock_*`, `*_temp.*`)을 준수하여 `.gitignore`에 필터링되도록 한다. +## 5b. Blazor & API-First 개발 규칙 (TaxBaik 참조 모델 적용) +- **API-First 아키텍처**: Blazor Server UI 계층은 비즈니스 로직이나 DB에 직접 결합되지 않고, `IXxxBrowserClient` 등의 추상화된 API 클라이언트(HTTP/RESTful)를 통해서만 백엔드 API와 통신한다. +- **이중 토큰 인증 패턴**: Access Token(15분) 및 Refresh Token(7일) 이중 토큰 패턴을 적용하며, HttpClient 요청 시 401 Unauthorized를 가로채어 자동으로 localStorage의 Refresh Token으로 토큰을 자동 갱신 및 재시도하는 `TokenRefreshHandler` (DelegatingHandler) 구조를 준수한다. +- **실시간 알림 (SignalR)**: 실시간 알림 기능은 상태를 직접 동기화하는 용도가 아닌 단순 Event-driven 브로드캐스트 알림으로 설계하며, 클라이언트는 알림 수신 후 API 호출을 통해 최종 데이터를 검증 및 동기화한다. +- **UI/UX 구현**: + - MudBlazor 컴포넌트(MudDataGrid Dense + Virtualize)를 사용하여 고밀도(행높이 32px 수준) 및 대량 데이터 성능을 보장한다. + - CRUD 생성 및 수정 작업 시 화면 플래시를 제거하기 위해 MudDialog 모달 대화상자 패턴을 사용하며, 삭제 작업에는 `ConfirmDialog` 등을 이용해 명시적 사용자 확인을 거친다. + - 상태 및 등급 구분에는 시각적 가시성을 위한 Status Color Chips(Success, Warning, Error)를 적용한다. +- **코드 및 다국어 규칙**: 모든 관리자 UI 레이블, 폼, 오류 메시지는 한국어로 작성하며, 소스 코드 주석 및 내부 예외 메시지는 영어 작성을 허용한다. 클래스, 메서드, 프로퍼티는 `PascalCase`를 사용하고 비동기 메서드에는 `Async` 접미사를 지정한다. + ## 6. 검증 규칙 - `python tools/validate_specs.py` - `python tools/validate_golden_coverage_100.py` diff --git a/docs/ROADMAP_WBS.md b/docs/ROADMAP_WBS.md index cae34c8..2636142 100644 --- a/docs/ROADMAP_WBS.md +++ b/docs/ROADMAP_WBS.md @@ -1661,6 +1661,28 @@ WBS-10.1 (기반 결함 수정) --- +#### WBS-10.11 Blazor 및 API-First 개발 가이드라인 수립 +| 항목 | 내용 | +|------|------| +| **작업** | [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) 분석 후 [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.3 | 스펙 검증 스크립트 실행을 통한 구성 유효성 검증 | `validate_specs.py` 무오류 통과 | + +**성공 하네스 (데이터 기준)**: +``` +검증: python tools/validate_specs.py → EXIT 0 +검증: C:\Temp\data_feed\AGENTS.md 내에 '5b. Blazor & API-First 개발 규칙' 및 'IXxxBrowserClient', 'TokenRefreshHandler' 키워드 존재 +``` + +--- + ## 3. 완성도 로드맵 매트릭스 | WBS | 우선순위 | 난이도 | 선행조건 | 예상 기간 | 현재 완성도 | @@ -1709,6 +1731,7 @@ WBS-10.1 (기반 결함 수정) | 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) | ---