feat: 프로젝트 개요 및 컴포넌트별 명세, 로드맵 등 문서 추가

2026-01-11 21:01:34 +09:00
parent 8553f586c9
commit 6c6ca894cf
23 changed files with 8388 additions and 0 deletions
--- a/components/phase3/audit.md
+++ b/components/phase3/audit.md
@@ -0,0 +1,165 @@
+# audit - 감사 및 로깅
+
+## 개요
+
+**audit** 컴포넌트는 불변 감사 로그와 규제 리포팅을 담당합니다.
+
+### 책임
+
+- 중요 이벤트 불변 저장 및 해시 체인 관리
+- 변경 이력 추적 및 감사 추적 제공
+- 규제 리포트 생성 및 데이터 экспорт
+- 데이터 보존 정책 적용 및 무결성 검증
+
+### 의존성
+
+```mermaid
+graph LR
+    Audit[audit] --> DB[(Database)]
+    Audit --> Storage[(Archive Storage)]
+
+    Balance[balance] --> Audit
+    Mgmt[mgmt] --> Audit
+    Strategy[strategy] --> Audit
+    Scheduler[scheduler] --> Audit
+
+    style Audit fill:#795548,color:#fff
+```
+
+## 주요 기능
+
+### 1. 감사 로그 기록
+
+```typescript
+logEvent(event: AuditEvent): void
+logOrderActivity(order: Order, action: OrderAction): void
+```
+
+### 2. 변경 이력 추적
+
+```typescript
+trackConfigChange(entity: string, entityId: string, changes: any): void
+getChangeHistory(entity: string, entityId: string): ChangeLog[]
+```
+
+### 3. 규제 리포팅
+
+```typescript
+generateComplianceReport(type: ComplianceReportType, period: DateRange): ComplianceReport
+exportAuditTrail(from: Date, to: Date, format: 'CSV' | 'JSON'): File
+```
+
+### 4. 데이터 보존 정책
+
+```typescript
+archiveOldData(cutoffDate: Date): ArchiveResult
+retainCriticalData(dataType: string, retentionYears: number): void
+```
+
+### 5. 무결성 검증
+
+```typescript
+verifyAuditIntegrity(from: Date, to: Date): IntegrityReport
+```
+
+## 데이터 모델
+
+```typescript
+interface AuditEvent {
+  id: string
+  timestamp: Date
+  eventType: 'ORDER' | 'CONFIG_CHANGE' | 'EXECUTION' | 'LOGIN' | 'DATA_EXPORT'
+  action: string
+  userId?: string
+  containerId?: string
+  entity: string
+  entityId: string
+  before?: any
+  after?: any
+  metadata: {
+    ipAddress?: string
+    userAgent?: string
+    reason?: string
+  }
+  hash: string
+  previousHash?: string
+}
+
+interface ChangeLog {
+  timestamp: Date
+  changedBy: string
+  field: string
+  oldValue: any
+  newValue: any
+  reason?: string
+}
+
+interface ComplianceReport {
+  type: 'TRADE_HISTORY' | 'POSITION_STATEMENT' | 'UNUSUAL_ACTIVITY'
+  period: DateRange
+  trades: {
+    date: Date
+    orderId: string
+    symbol: string
+    side: 'BUY' | 'SELL'
+    quantity: number
+    price: number
+    value: number
+  }[]
+  positions: {
+    symbol: string
+    quantity: number
+    averagePrice: number
+    marketValue: number
+    unrealizedPnL: number
+  }[]
+  unusualActivities: {
+    date: Date
+    type: string
+    description: string
+    resolution: string
+  }[]
+  generatedAt: Date
+  certifiedBy?: string
+}
+
+interface IntegrityReport {
+  period: DateRange
+  totalEvents: number
+  verification: {
+    hashChainValid: boolean
+    noGaps: boolean
+    noModifications: boolean
+  }
+  issues: {
+    eventId: string
+    issue: string
+    severity: 'LOW' | 'HIGH'
+  }[]
+  overall: 'PASS' | 'FAIL'
+  verifiedAt: Date
+}
+```
+
+## API 명세
+
+### GET /api/audit/events
+감사 이벤트 조회
+
+### POST /api/audit/reports
+규제 리포트 생성
+
+## 구현 고려사항
+
+- 해시 체인 단절 방지 및 재생성 불가 정책을 문서화합니다.
+- 민감 데이터 마스킹 규칙을 명확히 둡니다.
+
+## 관련 문서
+
+- [구현 로드맵](../../docs/05-roadmap.md)
+- [주요 워크플로우](../../docs/04-workflows.md)
+
+### 관련 컴포넌트
+- [scheduler - 실행 스케줄러](../phase1/scheduler.md)
+- [balance - 계좌 관리](../phase1/balance.md)
+- [risk - 리스크 관리](../phase1/risk.md)
--- a/components/phase3/simulation.md
+++ b/components/phase3/simulation.md
@@ -0,0 +1,207 @@
+# simulation - 시뮬레이션 환경
+
+## 개요
+
+**simulation** 컴포넌트는 Paper Trading, 시나리오 테스트, 파라미터 최적화를 제공하여 실전 전 검증을 지원합니다.
+
+### 책임
+
+- Paper Trading 계좌/주문 실행
+- 전략 시뮬레이션 및 비교
+- 파라미터 최적화 및 과최적화 검증
+- 몬테카를로 및 스트레스 테스트
+- 실계좌 전환 계획 생성
+
+### 의존성
+
+```mermaid
+graph LR
+    Simulation[simulation] --> Strategy[strategy]
+    Simulation --> Risk[risk]
+    Simulation --> Data[data]
+    Simulation --> Analytics[analytics]
+    Simulation --> DB[(Database)]
+
+    Audit[audit] --> Simulation
+
+    style Simulation fill:#607D8B,color:#fff
+```
+
+## 주요 기능
+
+### 1. Paper Trading
+
+```typescript
+createPaperAccount(config: PaperAccountConfig): PaperAccount
+executePaperTrade(order: Order): PaperOrderResult
+```
+
+### 2. 전략 시뮬레이션
+
+```typescript
+runSimulation(config: SimulationConfig): SimulationResult
+compareStrategies(strategyIds: string[], config: SimulationConfig): ComparisonResult
+```
+
+### 3. 파라미터 최적화
+
+```typescript
+optimizeParameters(strategyId: string, searchSpace: ParameterSpace): OptimizationResult
+validateOptimization(result: OptimizationResult, outOfSampleData: MarketData): ValidationResult
+```
+
+### 4. 시나리오 테스트
+
+```typescript
+testScenario(containerId: string, scenario: Scenario): ScenarioResult
+runMonteCarloSimulation(containerId: string, iterations: number): MonteCarloResult
+```
+
+### 5. 전환 지원
+
+```typescript
+promoteToProd(paperAccountId: string, realAccountId: string): MigrationPlan
+cloneContainer(sourceId: string, targetAccountId: string): Container
+```
+
+## 데이터 모델
+
+```typescript
+interface PaperAccount {
+  id: string
+  name: string
+  balance: {
+    initialCash: number
+    currentCash: number
+    positions: Position[]
+    totalEquity: number
+  }
+  settings: {
+    commissionModel: 'FIXED' | 'PERCENTAGE'
+    commissionRate: number
+    slippageModel: 'FIXED_BPS' | 'VOLUME_BASED'
+    slippageBps: number
+  }
+  isActive: boolean
+  createdAt: Date
+}
+
+interface SimulationConfig {
+  strategyId: string
+  startDate: Date
+  endDate: Date
+  initialCapital: number
+  universe: string[]
+  costs: {
+    commission: number
+    slippage: number
+    tax: number
+  }
+  constraints: RiskLimits
+  rebalanceFrequency: string
+}
+
+interface SimulationResult {
+  config: SimulationConfig
+  performance: PerformanceMetrics
+  equity: {
+    date: Date
+    value: number
+  }[]
+  trades: {
+    date: Date
+    symbol: string
+    action: 'BUY' | 'SELL'
+    quantity: number
+    price: number
+  }[]
+  drawdowns: {
+    start: Date
+    end: Date
+    depth: number
+    recovery: number
+  }[]
+  completedAt: Date
+}
+
+interface ParameterSpace {
+  parameters: {
+    name: string
+    type: 'INTEGER' | 'FLOAT' | 'CATEGORICAL'
+    min?: number
+    max?: number
+    step?: number
+    values?: any[]
+  }[]
+}
+
+interface OptimizationResult {
+  strategyId: string
+  searchSpace: ParameterSpace
+  bestParameters: Record<string, any>
+  bestMetric: number
+  trials: {
+    parameters: Record<string, any>
+    metrics: PerformanceMetrics
+  }[]
+  optimizationTime: number
+  warnings: {
+    overfitting: boolean
+    insufficientData: boolean
+    unstableParameters: string[]
+  }
+}
+
+interface MonteCarloResult {
+  iterations: number
+  returns: {
+    mean: number
+    median: number
+    std: number
+    percentiles: {
+      p5: number
+      p25: number
+      p75: number
+      p95: number
+    }
+  }
+  drawdowns: {
+    mean: number
+    max: number
+    percentiles: {
+      p95: number
+      p99: number
+    }
+  }
+  probabilities: {
+    profit: number
+    loss10pct: number
+    loss20pct: number
+  }
+  distribution: number[]
+}
+```
+
+## API 명세
+
+### POST /api/simulation/run
+시뮬레이션 실행
+
+### POST /api/simulation/optimize
+파라미터 최적화
+
+## 구현 고려사항
+
+- 과최적화 경고 기준을 명확히 정의합니다.
+- Paper Trading과 실계좌 체결 차이를 리포트에 표시합니다.
+
+## 관련 문서
+
+- [구현 로드맵](../../docs/05-roadmap.md)
+- [주요 워크플로우](../../docs/04-workflows.md)
+
+### 관련 컴포넌트
+- [strategy - 전략 관리](../phase1/strategy.md)
+- [risk - 리스크 관리](../phase1/risk.md)
+- [analytics - 성과 분석](../phase2/analytics.md)
+- [audit - 감사 및 로깅](./audit.md)