kjh2064/QuantEngineByItz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bd293d6f48d6bfd06248166cf4d43289aa02d5cc
QuantEngineByItz/CLAUDE.md
T
kjh2064 5c68e9526c docs(phase2): Stage 2 (KIS API 포팅) 완료 상태 문서화 
**이 커밋 기준 현황:**

Phase 1: Web UI 마이그레이션 ✅ COMPLETE
- MudBlazor → Fluent UI v5 (RC) 완전 전환
- 모든 페이지 마이그레이션 완료 (0% MudBlazor 잔존)

Phase 2: KIS API 및 데이터 수집 파이프라인 🔄 IN PROGRESS
✅ 완료된 작업:
- KisApiClient: 5가지 quotation 메서드 (읽기 전용)
- 보안: AssertReadOnly enforcement (trading API 차단)
- PostgreSQL: TokenCache, CollectionRepository 구현
- Web API: 6가지 Collection 엔드포인트
- Blazor UI: Collection.razor 대시보드 완성
- Build: 0 에러 (6개 RC 경고는 패키지 RC 버전 이슈)

📋 진행 중:
- Collection 엔드포인트 통합 테스트
- Python subprocess 임시 연계 (Phase 2 단계별 구현)

**CLAUDE.md 업데이트 내용:**
- Phase 1~3 상태 요약
- KIS API 보안 정책 문서화
- Collection API 엔드포인트 명세
- 개발 커맨드 추가 (Phase 2 테스팅 가이드)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-06-29 23:23:25 +09:00

213 lines
8.3 KiB
Markdown
Raw Blame History

# 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+
### Migration Phases Status (2026-06-29)
**Phase 1: Web UI Migration** ✅ COMPLETE
- Blazor WebAssembly with Fluent UI v5 (RC: 5.0.0-rc.4-26177.1)
- MudBlazor completely deprecated (0% remaining)
- Pages: Home, Workspace, Collection, Tables, MainLayout
- Build: 0 errors, 6 Razor RC warnings (acceptable)
**Phase 2: KIS Data Collection Pipeline** 🔄 IN PROGRESS
- ✅ KIS API Client: Full implementation complete
- IKisApiClient interface (5 quotation methods)
- KisApiClient (with security enforcement, token caching)
- All governance rules enforced (no trading APIs)
- Windows env var + registry fallback for credentials
- ✅ PostgreSQL Infrastructure: Complete
- ITokenCache → PostgresTokenCache (token management)
- ICollectionRepository → CollectionRepository (data storage)
- IDataCollectionStore (abstraction layer)
- ✅ Web API Endpoints: Complete
- CollectionEndpoints (6 endpoints: state, runs, snapshots, errors, latest, start)
- ApiClient for Blazor consumption
- ✅ Blazor UI: Complete
- Collection.razor dashboard with real-time monitoring
- Summary cards, recent errors table, runs history
- Start/refresh functionality
- 🔄 Integration Testing: Pending (Python subprocess fallback active)
**Phase 3: Node.js→.NET CLI Tools** 📋 PLANNED
- Makefile created (npm → make mappings)
- np operations documented
**Status Summary**:
- Python codebase: Operational (1,140 files)
- .NET 9 coverage: Core (✅), Infrastructure (✅), API (✅), Web UI (✅)
- Database: PostgreSQL fully migrated
- Release gates: Python gates remain authority until Phase 2 integration testing 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 (Phase 1 + 2)
### Python / Node.js (Legacy & Release Gates)
```powershell
npm install
npm run ops:validate # Warn-only validation
npm run full-gate # Strict validation (all gates PASS)
npm run ops:data-collect # KIS collection (Python subprocess)
npm run ops:release # Full release DAG
```
### .NET (Primary - Phase 1 + 2)
```powershell
cd dotnet
dotnet restore
dotnet build # Debug build
dotnet build -c Release # Release build (recommended)
dotnet watch run --project src/QuantEngine.Web # Hot-reload (http://localhost:5000)
dotnet run --project src/QuantEngine.Web # Run API server
```
### Collection Pipeline Testing (Phase 2)
```powershell
# Set credentials (Windows environment variables)
$env:KIS_APP_Key_TEST = "mock_key"
$env:KIS_APP_Secret_TEST = "mock_secret"
# Verify Blazor Collection page
# Navigate to http://localhost:5000/collection
# - Click "Start Collection" to trigger async run
# - API initiates Python subprocess (temporary Phase 2 design)
# - Dashboard updates with run status, snapshots, errors
# Verify API directly
curl http://localhost:5000/api/collection/state
curl http://localhost:5000/api/collection/runs
```
## API Endpoints (Phase 1 + 2)
### Workspace & History (Phase 1)
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 |
### Collection Pipeline (Phase 2)
| Route | Purpose |
|-------|---------|
| `GET /collection/state` | Dashboard summary (runs, snapshots, errors) |
| `GET /collection/runs` | Recent collection runs (paginated) |
| `GET /collection/runs/{runId}/snapshots` | Snapshots from a run |
| `GET /collection/runs/{runId}/errors` | Errors from a run |
| `GET /collection/latest/{ticker}` | Latest snapshots for ticker |
| `POST /collection/run` | Start new collection run (async) |
## KIS API Client Security (Phase 2)
### Governance Enforcement
- **Read-Only Mandate**: `AssertReadOnly(path, trId)` blocks all trading-related endpoints
- **Forbidden Paths**: `/trading/` substring triggers 🚫 immediate exception
- **Forbidden TR_IDs**: TTTC* / VTTC* prefixes (buy/sell order codes) blocked
- **Source**: `governance/rules/06_no_direct_api_trading.yaml`
### Token Management
- **ITokenCache** abstraction: PostgreSQL-backed in production
- **Credential Loading**:
- Windows environment variables: `KIS_APP_Key`, `KIS_APP_Secret`, `KIS_APP_Key_TEST`, `KIS_APP_Secret_TEST`
- Fallback: `HKCU\Environment` registry (Windows only)
- Account modes: `"real"` (prod) vs `"mock"` (sandbox)
### Quotation Methods (All Read-Only)
1. **GetCurrentPriceAsync** (FHKST01010100) — Current price inquiry
2. **GetAskingPrice10LevelAsync** (FHKST01010200) — Order book (10-level)
3. **GetDailyShortSaleAsync** (FHPST04830000) — Short-sale trends
4. **GetDailyItemChartPriceAsync** (FHKST03010100) — Daily OHLCV data
5. **GetInvestorTrendAsync** (FHKST01010900) — Investor sentiment (개인/외국인/기관)
## 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
Reference in New Issue View Git Blame Copy Permalink