kjh2064
c57ad182b0
- Remove QuantEngine.Web.Client from .sln (keep on disk for reference) - Replace Blazor Interactive WebAssembly with server-rendered Razor Pages - Implement Cookie Authentication (HttpOnly, SameSite=Lax, 12h expiry) - Add AuthService with BCrypt password hashing + auto-migration from SHA-256 - Implement IpLockoutService (3 strikes → 15-min ban) - Create Admin folder structure with Layout + shared partials - Implement Dashboard, Collection, Users index pages (base structure) - Remove hardcoded backdoors (master_recovery, dev auth bypass) - Remove hardcoded localhost:5265 URLs - Add Tabler UI base styling (Bootstrap 5 CDN + custom admin.css) - Update CLAUDE.md with new UI standards and auth policies - Build: 0 errors, 0 warnings (ready for dev testing) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
244 lines
11 KiB
Markdown
244 lines
11 KiB
Markdown
# 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 Interactive WebAssembly (MudBlazor) + ASP.NET Core Web API (API-First)
|
|
- **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-07-11)
|
|
|
|
**Phase 1: Web UI Migration** ✅ 완료 (2026-07-11)
|
|
- **새로운 표준**: Razor Pages (Server-Rendered) + Cookie Authentication + Tabler UI
|
|
- **폐기 대상**: Blazor Interactive WebAssembly, MudBlazor, SmartAdmin
|
|
- **구현 완료**:
|
|
- ✅ Cookie 기반 인증 (AuthService + IpLockoutService)
|
|
- ✅ Razor Pages CRUD 레이아웃 (_AdminLayout.cshtml, shared partials)
|
|
- ✅ Admin 페이지: Dashboard, Collection, Users (기본 구조)
|
|
- ✅ 공용 UI 컴포넌트: _ValidationSummary, _Pagination, _StatusBadge, _EmptyState
|
|
- ✅ 보안 개선: BCrypt 해싱, IP 잠금, 하드코딩된 백도어 제거
|
|
- ✅ 빌드: 0 errors, 0 warnings (Newtonsoft.Json 보안 경고 제외)
|
|
- **구현 미완료 (향후)**:
|
|
- 🔄 Users 페이지: Create/Edit 폼 완성
|
|
- 🔄 Collection 페이지: 스냅샷/에러 조회 상세화
|
|
- 🔄 CLAUDE.md 업데이트: 완료 (이 섹션)
|
|
|
|
**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](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-07-11 — Migrated to Razor Pages)
|
|
|
|
### Framework & Design System (NEW — 2026-07-11)
|
|
|
|
- **Primary Framework**: ASP.NET Core Razor Pages + Bootstrap 5 + Tabler UI
|
|
- **Design System**: Tabler (Bootstrap 5 기반), 밀집 레이아웃 + 전통 서버 렌더링
|
|
- **Render Mode**: **Server-side Razor Pages** — 모든 Admin UI는 서버에서 렌더링, Cookie 기반 인증 (API-First WASM 폐기)
|
|
- **Authentication**: Cookie Authentication (HttpOnly) + BCrypt password hashing + IP lockout (3 strikes, 15-min)
|
|
- **Deprecation**: **Blazor Interactive WebAssembly 폐기**, **MudBlazor 컴포넌트 폐기** (2026-07-11), **SmartAdmin 폐기**. 기존 WASM 코드는 `/QuantEngine.Web.Client` 폴더에 참고용으로만 보관 (`.sln`에서 제외)
|
|
|
|
### Component Development Rules (NEW)
|
|
|
|
1. **All Admin UI Development** (New + Refactored):
|
|
- Use **Razor Pages** (.cshtml + .cshtml.cs PageModel) exclusively for admin
|
|
- UI는 Repository/Service를 생성자 DI로 직접 호출 (API 홉 없음)
|
|
- Bootstrap 5 + Tabler UI CSS classes for styling
|
|
- **Form Validation**: DataAnnotations DTO + FluentValidation IValidator<T> 이중 검증
|
|
- HTML `<form>` + tag helpers (`asp-for`, `asp-action`, `asp-page`)
|
|
|
|
2. **Authentication & Authorization**:
|
|
- Cookie name: `QuantEngine.Admin.Auth` (HttpOnly, SameSite=Lax)
|
|
- Session duration: 12 hours (sliding expiration)
|
|
- Folder-level `[Authorize]` via `AuthorizeFolder("/Admin")` convention (per-page 반복 금지)
|
|
- Login: `/Account/Login` (Razor Page, NO WASM)
|
|
- Password: BCrypt-hashed (auto-migrates existing SHA-256 hashes on first login)
|
|
- IP Lockout: 3 failed attempts → 15-minute lockout
|
|
|
|
3. **Data & Form Patterns**:
|
|
- PageModel constructor: `public IndexModel(IWorkspaceRepository repo, ILogger<IndexModel> logger)`
|
|
- Form submission: `OnPostAsync()` / `OnPostDeleteAsync()` (multi-handler pattern)
|
|
- Validation failures: return `Page()` (re-render with ModelState errors)
|
|
- Pagination: `PaginationModel` record (Page, TotalPages, Func<int,string> BuildPageUrl)
|
|
- Empty states: `<PartialView name="_EmptyState" model="message" />`
|
|
|
|
4. **Component Mapping** (Bootstrap 5 + Tabler):
|
|
|
|
| UI Element | Component | Notes |
|
|
|-----------|-----------|-------|
|
|
| Button | `<button class="btn btn-primary">` | — |
|
|
| Input field | `<input asp-for="Property" class="form-control">` | tag helper |
|
|
| Dropdown | HTML `<select asp-for="Property">` | tag helper |
|
|
| Data grid | HTML `<table class="table">` | plain, no virtualization |
|
|
| Card | `<div class="card">` | Bootstrap card |
|
|
| Badge/Status | `<span class="badge bg-success">Active</span>` | Bootstrap badge |
|
|
| Layout container | `<div class="container-xl">` / `<div class="row">` | Bootstrap grid |
|
|
| Navigation | HTML navbar in `_AdminLayout.cshtml` | sidebar + topbar |
|
|
| Loading | N/A (server-rendered) | no loading states needed |
|
|
| Icons | Bootstrap Icons (`<i class="bi bi-*"></i>`) | CDN |
|
|
| Modal/Dialog | Bootstrap modal or inline `confirm()` | avoid unnecessary modals |
|
|
| Validation msg | `<span asp-validation-for="Property" class="d-block alert alert-danger mt-2">` | tag helper |
|
|
|
|
## 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 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)
|
|
```powershell
|
|
# 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 (2026-07-11)
|
|
|
|
- **SQL Safety**: Whitelist-only table access (enum switch in Repository)
|
|
- **KIS API**: Read-only quotations/ranking; no order/trade endpoints (governance enforced)
|
|
- **Admin UI**: Server-rendered Razor Pages only; no WASM, no APIs between PageModel and Repository
|
|
- **Authentication**: Cookie-based only; no Bearer tokens; password reset via API endpoints only (no UI form)
|
|
- **Password Policy**: BCrypt hashing (auto-upgrade from SHA-256 on login); IP lockout: 3 strikes = 15 min ban
|
|
- **Database**: PostgreSQL contract maintained; Dapper ORM with raw SQL (no EF)
|
|
- **Legacy Code**: `QuantEngine.Web.Client` folder kept for reference (not in .sln, not built)
|
|
- **Newtonsoft.Json**: Known high-severity vulnerability (GHSA-5crp-9r3c-p9vr); update or replace when feasible
|
|
- **Release Authority**: Python gates (`full-gate`, `prepare-upload-zip`) remain authority; .NET Admin fully operational as of 2026-07-11
|