QuantEngineByItz/CLAUDE.md

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 ✅ 95% COMPLETE

• ✅ KIS API Client: Full implementation complete
  • IKisApiClient interface (5 quotation methods)
  • KisApiClient with real HTTP implementation + token caching
  • All governance rules enforced (no trading APIs)
  • Windows env var + registry fallback for credentials
  • Build: 0 errors, 0 warnings
• ✅ PostgreSQL Infrastructure: Complete
  • PostgresTokenCache (token management, 10-min skew)
  • CollectionRepository (full CRUD + dashboard aggregations)
  • Auto-creates kis_tokens, kis_collection_runs, kis_collection_snapshots, kis_collection_errors
  • Dapper ORM + parameterized SQL (injection-proof)
• ✅ 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
  • FluentSkeleton loading states
• 🔄 Pipeline Orchestration: Pending
  • Python kis_data_collection_v1.py → .NET (data fetching + validation)
  • Real KIS API data collection workflow integration
  • E2E test: API → DB → UI validation

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 for deployment procedures.

Quick Deploy (QuantEngine)

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
• 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)

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)

cd src/dotnet
dotnet restore
dotnet build                      # Debug build (0 errors, 0 warnings)
dotnet build -c Release           # Release build
dotnet watch run --project QuantEngine.Web  # Hot-reload (http://localhost:5265)
dotnet run --project QuantEngine.Web        # Run API server

Collection Pipeline Testing (Phase 2)

# Set KIS credentials (sandbox account)
$env:KIS_APP_Key_TEST = "your_kis_test_key"
$env:KIS_APP_Secret_TEST = "your_kis_test_secret"

# Start web server (http://localhost:5265)
dotnet run --project QuantEngine.Web

# Verify Collection dashboard
# Navigate to http://localhost:5265/collection
# - Click "Start Collection" to trigger async run
# - Backend uses PostgreSQL-backed data storage
# - Dashboard updates with run status, snapshots, errors

# Verify API endpoints
curl http://localhost:5265/api/collection/state
curl http://localhost:5265/api/collection/runs
curl "http://localhost:5265/api/collection/latest/005930"

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