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