BitGet_API/README.md

# Bitget_Server

기존 WinForms 기반 `BitgetApi` 프로젝트(.NET Framework 4.7.2 + DevExpress)의 **거래·신호 비즈니스 로직**을 추출해 ASP.NET Core 8.0 REST API 서버로 이식한 단일 사용자용 백엔드입니다. 기존 UI 코드는 전부 제외되었고, 외부 Bitget REST/WebSocket 통신 규약과 신호 판정 로직은 원본과 동일하게 유지됩니다.

---

## 1. 기술 스택

- .NET 8.0 (ASP.NET Core Web API, `Microsoft.NET.Sdk.Web`)
- Kestrel HTTP 전용, 포트 **5000** (HTTPS 미사용)
- Serilog (Console + 일자 롤링 파일, `Sinks.Map` 으로 SourceContext 분리)
- Swashbuckle Swagger (환경 불문 항상 활성화, `/swagger`)
- Newtonsoft.Json (원본 직렬화 규약 유지)
- Docker (Ubuntu 24.04 noble 이미지 기반)

---

## 2. 아키텍처

Clean Layered 구조. 의존 방향은 `Api → Application → Domain`, 그리고 `Infrastructure → Domain` 만 허용.

```
Bitget_Server/
├── Api/                          REST 진입점 (Controller + DTO)
│   ├── Controllers/
│   │   ├── SettingsController.cs      /api/settings/*
│   │   ├── CoinsController.cs         /api/coins
│   │   ├── SignalsController.cs       /api/signals, /api/signals/conditions
│   │   ├── TradingController.cs       /api/trading/*
│   │   ├── WebSocketController.cs     /api/websocket/*
│   │   └── HealthController.cs        /api/health
│   └── Dtos/
├── Application/
│   ├── Options/                  BitgetOptions, GlobalOptions
│   ├── State/                    MarketState (공유 가변 상태)
│   ├── Services/                 SettingsService, BitgetTradingService,
│   │                             SignalProcessService, PriceLevelTracker,
│   │                             InitialCandleLoader
│   └── BackgroundServices/       MarketInfoBackgroundService,
│                                 WebSocketCalcBackgroundService,
│                                 SignalProcessBackgroundService
├── Domain/                       엔티티 / Enum / 상수 엔드포인트
├── Infrastructure/
│   ├── Bitget/                   BitgetClient, BitgetWebSocketClient,
│   │                             BitgetRateLimiter
│   └── Utils/                    BaseSettings<T>, Convertor 등
├── Program.cs                    DI + 미들웨어 파이프라인
├── appsettings.json
├── appsettings.Development.json
└── Dockerfile
```

DI 수명 정책: 상태를 보유하거나 BackgroundService 에서 캡처되는 모든 서비스는 **Singleton** 으로 통일. Bitget 단일 엔드포인트를 공유하므로 `HttpClient` 와 `BitgetClient` 도 Singleton.

---

## 3. 실행 방법

### 3.1. 로컬 실행 (개발)

사전 요구: .NET SDK 8.0

```bash
cd Bitget_Server
dotnet restore
dotnet run
```

기동 후 브라우저에서 `http://localhost:5000/swagger` 로 진입하면 전체 API 명세를 확인할 수 있습니다. 루트 `http://localhost:5000/` 는 Swagger UI 로 리다이렉트됩니다.

개발 환경 설정은 `appsettings.Development.json` 이 덮어쓰며 기본으로 `LogDebugWrite: true` 입니다.

### 3.2. Docker 단독 실행

```bash
# 솔루션 루트에서
docker build -f Bitget_Server/Dockerfile -t bitget-server:latest .
docker run -d --name bitget-server \
  -p 5000:5000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/appsettings.Production.json:/app/appsettings.Production.json:ro \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e TZ=Asia/Seoul \
  bitget-server:latest
```

### 3.3. docker-compose 실행 (권장)

```bash
# 솔루션 루트에서
docker compose up -d --build
docker compose logs -f bitget-server
```

첫 실행 전에 반드시 `appsettings.Production.json` 의 `Bitget.ApiKeys[].AccessKey / SecretKey / PassphraseKey` 값을 실제 Bitget API 자격증명으로 교체해야 합니다. 해당 파일은 read-only 볼륨으로 마운트되므로 이미지에 시크릿이 포함되지 않습니다.

---

## 4. 설정 (`appsettings.json` → `Bitget` 섹션)

| 키 | 기본값 | 설명 |
|---|---|---|
| `DefaultApiId` | `0` | 최초 기동 시 GlobalOptions.SelectAPI 로 로드할 키의 Id |
| `RateLimitPerSecond` | `20` | 클라이언트 사이드 요청 한도 (0 또는 음수 시 무제한) |
| `DataDirectory` | `./data` | BaseSettings JSON 영속화 경로. Docker 에서는 `/app/data` |
| `LogDirectory` | `./logs` | Serilog 파일 싱크 경로. Docker 에서는 `/app/logs` |
| `LogDebugWrite` | `false` | 최소 로그 레벨을 Debug 로 낮출지 여부 |
| `MarketInfoUpdateIntervalMs` | `300` | 시세/계정 정보 폴링 주기 |
| `WebSocketCalcIntervalMs` | `1000` | WebSocket 계산 루프 주기 |
| `WebSocketPingIntervalMs` | `25000` | WebSocket Ping 전송 주기 |
| `ApiKeys[]` | — | 복수 API 키. 각 항목은 `Id / Name / AccessKey / SecretKey / PassphraseKey` 필드 구성 |

API 키 선택은 기동 직후 `ApiKeyBootstrapper` 가 `DefaultApiId` 로 자동 적용하며, 이후 런타임에는 `PUT /api/settings/api-key` 로 변경할 수 있습니다. 선택값은 `GlobalOptions` (BaseSettings JSON) 으로 영속화되어 재시작 시에도 유지됩니다.

---

## 5. REST API 요약

전체 계약 및 파라미터 스키마는 Swagger UI(`/swagger`) 를 참조하세요. 대략의 엔드포인트 구성은 다음과 같습니다.

**설정 (`/api/settings/*`)**: 캔들 주기, 선택 코인, 레버리지, 주문 수량, 선택 API 키의 GET/PUT. 선택 가능한 캔들 주기 목록은 `GET /api/settings/candle-interval/options`.

**마켓 (`/api/coins`)**: Bitget 선물 시장 전체 심볼 목록.

**신호 (`/api/signals`, `/api/signals/conditions`, `/api/signals/checked-markets`)**: 신호 조건 조회/갱신, 체크된 마켓 목록, 현재 산출된 롱/숏 진입·청산 신호.

**거래 (`/api/trading/*`)**: Bitget 사설 API 래퍼. 서버 timestamp, 선물 계정, 대기 주문, 주문 상세, 주문 실행(POST), 주문 취소(DELETE), 포지션 모드 변경(PUT).

**WebSocket 제어 (`/api/websocket/*`)**: 현재 연결 상태 조회, 수동 start/stop.

**헬스 (`/api/health`)**: 버전/타임스탬프 JSON. Docker healthcheck 가 호출.

오류 응답은 RFC 7807 ProblemDetails 로 통일되어 있습니다.

---

## 6. BackgroundService (WinForms 타이머 이식)

기존 WinForms 의 `Thread.Sleep` 루프가 다음 세 HostedService 로 대체되었습니다.

- **MarketInfoBackgroundService**: `MarketInfoUpdateIntervalMs` 주기로 Bitget 선물 시세/계정 스냅샷을 `MarketState` 에 기록
- **WebSocketCalcBackgroundService**: `WebSocketCalcIntervalMs` 주기로 WebSocket 으로부터 누적된 캔들 Tick 을 interval 별로 합산 계산
- **SignalProcessBackgroundService**: 200ms 주기로 `SignalProcessService.ProcessOnceAsync` 호출, 진입/청산 신호 리스트 갱신

HostedService 의 기동 순서는 DI 등록 순서를 따르며, `ApiKeyBootstrapper` 가 이들보다 먼저 실행되어 `SelectAPI` 초기화를 보장합니다.

---

## 7. Rate Limiter 동작

`BitgetRateLimiter` 는 1초 슬라이딩 윈도우 기반 클라이언트 사이드 스로틀입니다. 전 코드베이스에서 `HttpClient` 직접 사용은 `BitgetClient.SendWebServerAsync` 1곳으로 통일되어 있고, 이 메서드는 매 호출마다 `await _limiter.AcquireAsync(ct)` 로 슬롯을 확보합니다.

Bitget 서버가 429 TooManyRequests 를 반환하면 자동으로 500ms 대기 후 **1회에 한해** 재시도합니다. 재시도 후에도 429 면 일반 오류로 처리하고 null 을 반환합니다. `RateLimitPerSecond` 를 0 또는 음수로 설정하면 무제한 모드(즉시 통과)로 동작하고 기동 시 Warning 로그가 1회 출력됩니다.

---

## 8. 로그

Serilog Console 싱크와 `Sinks.Map` 을 통한 파일 싱크가 병렬 동작합니다. 파일은 `LogDirectory/bitget-YYYYMMDD.log` 형식의 일자 롤링이며 최대 30개 보관합니다. Docker 환경에서는 `json-file` 드라이버(10MB × 5 파일) 로 stdout 을 순환 보관합니다.

로그 레벨은 `Bitget.LogDebugWrite` 플래그로 Debug/Information 간을 전환합니다. `Microsoft.AspNetCore` 는 Warning 이상으로 고정 override 됩니다.

---

## 9. 원본 WinForms 대비 제외 사항

- DevExpress UI 컴포넌트 및 Form 계층 전체 (`Main.cs`, `*.Designer.cs`, `*.resx`)
- 화면 출력용 이벤트/델리게이트
- 개별 사용자 프로필 GUI (단일 사용자 서버로 통합)

제외되지 않은 이식 항목:
- HMAC-SHA256 서명 생성(`BitgetClient.GenerateSignString`)
- 전고점/전저점 dictionary state machine (`PriceLevelTracker`)
- 구름떼 / 영호조건식 상향·하향 돌파 판정 (`SignalProcessService`)
- 캔들 시계열 누적 및 WebSocket 통합 계산
- BaseSettings JSON 영속화 메커니즘

---

## 10. 문제 해결

| 증상 | 원인 및 조치 |
|---|---|
| `/api/health` 200 이지만 주문은 401/signature-invalid | `appsettings.Production.json` 의 `ApiKeys` 값이 자리표시자. 실제 키로 교체 후 컨테이너 재기동 |
| 컨테이너 기동 후 `/app/data` 내 json 이 재시작마다 초기화 | `./data` 볼륨 바인드가 누락되었거나 호스트 권한이 1654 사용자에게 없음. `chown` 또는 compose 재생성 |
| Debug 로그가 안 남음 | `Bitget.LogDebugWrite` 가 `false`. `appsettings.Development.json` 사용 또는 플래그 `true` 설정 |
| 잦은 throttle 로그 | `RateLimitPerSecond` 가 너무 낮거나 BackgroundService 주기가 과잉. 값 상향 또는 간격 늘리기 |

---

## 11. 라이선스 / 기여

사내 운영용 단일 사용자 서버입니다. 기여 정책 및 라이선스는 별도 내부 문서를 따릅니다.