docs: UI 디자인 원칙 추가 및 MudBlazor 폐기 정책 명시 (2026-06-29)

- Fluent UI Blazor v5 기본 템플릿 및 컴포넌트 매핑 - Skeleton을 기본 로딩 상태로 지정 - 데이터 먼저 스켈톤 렌더링 후 실제 UI 교체 패턴 - MudBlazor 완전 폐기: 신규 금지, 기존 코드 마이그레이션 필수 - 배포 환경 정보 (Hetzner 178.104.200.7) - Gitea 저장소 정보 (kjh2064/QuantEngineByItz) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-06-29 23:03:44 +09:00
parent cea1584c1e
commit aad4788e84
1 changed files with 126 additions and 0 deletions
@@ -0,0 +1,126 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**QuantEngine v0.1** — A comprehensive quantitative analysis and data collection system for retirement asset portfolio management.
+
+- **Architecture**: .NET 9 + C# (web UI + APIs), Python (legacy data collection/analysis)
+- **Web UI**: Blazor WebAssembly (Fluent UI Blazor v5) + ASP.NET Core Web API
+- **Database**: PostgreSQL (Npgsql 8.0), single unified database
+- **Data Source**: KIS Open API (quotations/ranking read-only), with fallbacks
+- **Key Runtimes**: .NET 9, Python 3.9+, Node.js 16+
+
+### Current Status (2026-06-29)
+
+- ✅ Python codebase operational (1,140 files)
+- ✅ .NET 9 migration in progress (Phase 1: Web UI)
+- ✅ Blazor WASM with Fluent UI v5 RC baseline
+- ✅ ASP.NET Core API endpoints operational
+- ✅ PostgreSQL migration complete
+
+## Deployment & Operations
+
+**Production Server**: Hetzner Cloud `178.104.200.7` (kjh2064@178.104.200.7)
+
+Projects on server:
+1. **TaxBaik** (홈페이지) — Nginx location `/taxbaik`
+2. **QuantEngine** (데이터 수집/분석) — Nginx location `/quantengine`
+
+See [Temp/DEPLOYMENT_GUIDE.md](Temp/DEPLOYMENT_GUIDE.md) for deployment procedures.
+
+### Quick Deploy (QuantEngine)
+
+```powershell
+ssh kjh2064@178.104.200.7
+systemctl status quantengine-api
+journalctl -u quantengine-api -f
+sudo systemctl restart quantengine-api
+```
+
+### Git Repository
+
+**Gitea Server** (동일 호스트):
+- **HTTP**: `http://178.104.200.7/kjh2064/QuantEngineByItz.git`
+- **SSH**: `git@178.104.200.7:2222/...`
+
+## UI Design Principles (2026-06-29)
+
+### Framework & Design System
+
+- **Primary Framework**: [Fluent UI Blazor v5](https://v5.fluentui-blazor.net/)
+- **Design System**: Microsoft Fluent Design System (WCAG 2.1 AA)
+- **Deprecation**: MudBlazor is deprecated. Migrate all existing pages to Fluent UI v5 progressively.
+
+### Component Development Rules
+
+1. **All UI Development** (New + Refactored):
+   - Use Fluent UI Blazor v5 components exclusively
+   - Fall back to pure HTML/CSS if Fluent v5 doesn't provide
+   - **Never introduce MudBlazor components** (deprecated)
+   - Progressively migrate existing MudBlazor to Fluent v5
+
+2. **Loading States** (Priority order):
+   - `<FluentSkeleton>` — **Default** for lists, cards, dashboards, detail pages
+   - Pure HTML `<div class="skeleton">` — For custom layouts
+   - `MudProgressCircular` / `MudProgressLinear` — Exception only (existing legacy)
+   - Blocking spinners — **Avoid**
+
+3. **Data Rendering Pattern**:
+   - First render: Skeleton placeholders only
+   - On data arrival: Replace skeleton with actual UI
+   - Never show blank states while loading
+
+4. **Component Mapping** (Fluent UI v5):
+
+| UI Element | Fluent UI Component | Alternative |
+|-----------|-------------------|-------------|
+| Button | `<FluentButton>` | - |
+| Input field | `<FluentTextField>` | HTML `<input>` |
+| Dropdown | `<FluentSelect>` | HTML `<select>` |
+| Data grid | `<FluentDataGrid>` | HTML `<table>` |
+| Card | `<FluentCard>` | HTML `<div class="card">` |
+| Badge/Status | `<FluentBadge>` | HTML `<span>` |
+| Layout container | `<FluentStack>` | HTML `<div>` |
+| Accordion | `<FluentAccordion>` | HTML `<details>` |
+| Navigation | `<FluentNavMenu>` | HTML `<nav>` |
+| Loading | `<FluentSkeleton>` | CSS skeleton animation |
+| Icons | `<FluentIcon>` | SVG inline |
+
+## Development Commands
+
+```powershell
+# NPM / Python validation
+npm install
+npm run ops:validate
+
+# .NET Development (if dotnet/ folder exists)
+cd dotnet
+dotnet restore
+dotnet build
+dotnet watch run --project src/DataFeed.Api
+```
+
+## API Endpoints
+
+All endpoints prefixed with `/api/`:
+
+| Route | Purpose |
+|-------|---------|
+| `GET /state` | Full UI state snapshot |
+| `GET /tables` | Browsable tables list |
+| `GET /table-rows` | Paginated rows |
+| `POST /settings/save` | Save settings |
+| `POST /account-snapshot/save` | Save snapshots |
+| `POST /bootstrap` | Seed DB from JSON |
+| `POST /account-snapshot/import-tsv` | Import TSV |
+| `POST /autofix` | Auto-correct data |
+
+## Notes for Contributors
+
+- **SQL Safety**: Whitelist-only table access (enum switch)
+- **KIS API**: Read-only quotations/ranking; no order/trade endpoints
+- **Blazor WASM**: No direct SQLite access; API-only
+- **Database**: PostgreSQL contract maintained during migration
+- **Release Authority**: Python gates (`full-gate`, `prepare-upload-zip`) remain authority until .NET fully operational