kwanghyun's Blog

OpenClaw + FastAPI 콜백으로 비동기 LLM 파이프라인 만들기

kwanghyun — Wed, 4 Feb 2026 17:32:11 +0900

Raspberry Pi에서 GPT 분석, 웹훅/콜백으로 결과 적재

이 글은 개발 인프라 개선 시리즈의 Infra-5편이다.

개발 인프라 개선 시리즈:

Infra-1편: Poetry에서 UV로 마이그레이션

Infra-2편: Python 3.13 업그레이드

Infra-3편: Python 3.14 업그레이드

Infra-4편: Ruff + Pyright 마이그레이션

Infra-5편: OpenClaw 통합 ← 현재 글

AI 자동매매 시리즈:

1편: 한투 API로 실시간 주식 데이터 수집하기

2편: yfinance로 애플·테슬라 분석하기

3편: Upbit으로 비트코인 24시간 분석하기

4편: AI 분석 결과 DB에 저장하기

5편: Upbit 웹 트레이딩 대시보드 구축하기

6편: 실전 운영을 위한 모니터링 시스템 구축

7편: 라즈베리파이 홈서버에 자동 HTTPS로 안전하게 배포하기

들어가며

배경: LLM 분석을 분리해야 하는 이유

기존 auto_trader 시스템은 Google Gemini API를 직접 호출해서 주식/암호화폐 분석을 수행했습니다. 하지만 몇 가지 문제가 있었습니다:

문제	설명
API 비용/제한	여러 API 키를 로테이션해도 429 에러 발생
운영 분리	분석 서비스 장애가 트레이딩 서비스에 영향
유연성	다른 LLM(GPT, Claude)으로 전환이 어려움
리소스	LLM 호출이 메인 서버 리소스 점유

해결책: 분석을 별도 서비스로 오프로딩

Raspberry Pi 5에서 운영 중인 OpenClaw를 활용하여:

auto_trader는 분석 요청만 보냄 (비동기)
OpenClaw가 GPT/Claude로 분석 수행
완료 후 콜백으로 결과 전송
auto_trader가 DB에 저장

OpenClaw란?

OpenClaw는 LLM 에이전트를 실행하고 관리하는 게이트웨이이다.:

웹훅 기반 실행: POST /hooks/agent로 에이전트 트리거
비동기 처리: 요청 즉시 202 반환, 백그라운드에서 처리
세션 관리: sessionKey로 대화 컨텍스트 유지
다양한 LLM 지원: OpenAI, Claude, 로컬 모델 등

아키텍처 개요

auto_trader → OpenClaw → callback → DB 파이프라인

핵심 흐름

① auto_trader: POST /hooks/agent (분석 요청)
    ├─ message: 프롬프트 + 콜백 URL + JSON 스키마
    ├─ sessionKey: auto-trader:openclaw:{request_id}
    └─ Authorization: Bearer {OPENCLAW_TOKEN}

② OpenClaw: 요청 수신, 즉시 202 반환

③ OpenClaw Agent: GPT/Claude로 분석 실행

④ OpenClaw: POST callback_url (분석 결과)
    ├─ JSON: decision, confidence, reasons, price_analysis
    └─ Authorization: Bearer {CALLBACK_TOKEN}

⑤ auto_trader: 콜백 수신, DB 저장 (StockAnalysisResult)

상관관계 키

요청과 응답을 매칭하기 위한 두 가지 키:

키	용도	예시
`request_id`	콜백 페이로드 식별	`550e8400-e29b-41d4-a716-446655440000`
`sessionKey`	OpenClaw 세션 추적	`auto-trader:openclaw:{request_id}`

구현 상세

1. OpenClaw 클라이언트 (요청 송신)

app/services/openclaw_client.py:

class OpenClawClient:
    """Client for OpenClaw Gateway webhook (POST /hooks/agent)."""

    async def request_analysis(
        self,
        prompt: str,
        symbol: str,
        name: str,
        instrument_type: str,
    ) -> str:
        """Send an analysis request to OpenClaw."""
        if not settings.OPENCLAW_ENABLED:
            raise RuntimeError("OpenClaw integration is disabled")

        request_id = str(uuid4())

        message = _build_openclaw_message(
            request_id=request_id,
            prompt=prompt,
            symbol=symbol,
            name=name,
            instrument_type=instrument_type,
            callback_url=self._callback_url,
            callback_token=settings.OPENCLAW_CALLBACK_TOKEN,
        )

        payload = {
            "message": message,
            "name": "auto-trader:analysis",
            "sessionKey": f"auto-trader:openclaw:{request_id}",
            "wakeMode": "now",
        }

        headers = {"Content-Type": "application/json"}
        if self._token:
            headers["Authorization"] = f"Bearer {self._token}"

        async with httpx.AsyncClient(timeout=10) as cli:
            res = await cli.post(self._webhook_url, json=payload, headers=headers)
            res.raise_for_status()

        return request_id

핵심 포인트:

uuid4()로 고유한 request_id 생성
sessionKey에 request_id 포함하여 추적 가능
wakeMode: "now"로 즉시 실행 요청

2. 메시지 빌더

def _build_openclaw_message(
    *,
    request_id: str,
    prompt: str,
    callback_url: str,
    callback_token: str | None,
    ...
) -> str:
    callback_schema = {
        "request_id": request_id,
        "symbol": symbol,
        "decision": "buy|hold|sell",
        "confidence": 0,  # 0-100 int
        "reasons": ["..."],
        "price_analysis": {
            "appropriate_buy_range": {"min": 0, "max": 0},
            ...
        },
        "detailed_text": "...",
        "model_name": "...",
    }

    callback_headers = "Content-Type: application/json\n"
    if callback_token:
        callback_headers += f"Authorization: Bearer {callback_token}\n"

    return (
        "Analyze the following trading instrument...\n\n"
        f"request_id: {request_id}\n"
        f"symbol: {symbol}\n"
        "USER_PROMPT:\n"
        f"{prompt}\n\n"
        "CALLBACK:\n"
        f"POST {callback_url}\n"
        f"{callback_headers}\n"
        "RESPONSE_JSON_SCHEMA (example):\n"
        f"{json.dumps(callback_schema)}\n"
    )

메시지 구조:

분석 대상 정보 (symbol, name, instrument_type)
원본 프롬프트 (USER_PROMPT)
콜백 엔드포인트와 인증 헤더
응답 JSON 스키마 (에이전트가 참조)

3. 콜백 라우터 (결과 수신)

app/routers/openclaw_callback.py:

router = APIRouter(prefix="/api/v1/openclaw", tags=["OpenClaw"])


class OpenClawCallbackRequest(BaseModel):
    request_id: str
    symbol: str
    name: str
    instrument_type: str

    decision: Literal["buy", "hold", "sell"]
    confidence: int = Field(ge=0, le=100)
    reasons: list[str] | None = None

    price_analysis: PriceAnalysis
    detailed_text: str | None = None
    model_name: str | None = None


@router.post("/callback")
async def openclaw_callback(
    payload: OpenClawCallbackRequest,
    _: None = Depends(_require_openclaw_callback_token),
    db: AsyncSession = Depends(get_db),
) -> dict:
    # 1. 종목 정보 생성/조회
    stock_info = await create_stock_if_not_exists(
        symbol=payload.symbol,
        name=payload.name,
        instrument_type=payload.instrument_type,
        db=db,
    )

    # 2. 분석 결과 저장
    record = StockAnalysisResult(
        stock_info_id=stock_info.id,
        model_name="openclaw-gpt",
        decision=payload.decision,
        confidence=payload.confidence,
        appropriate_buy_min=payload.price_analysis.appropriate_buy_range.min,
        ...
    )

    db.add(record)
    await db.commit()
    await db.refresh(record)

    return {
        "status": "ok",
        "request_id": payload.request_id,
        "analysis_result_id": record.id,
    }

4. 콜백 인증

2단계 토큰 인증: Gateway 토큰 + Callback 토큰

토큰 분리 설계:

토큰	용도	보관 위치
`OPENCLAW_TOKEN`	Gateway 접근	auto_trader만 보관
`OPENCLAW_CALLBACK_TOKEN`	콜백 인증	양쪽 보관

async def _require_openclaw_callback_token(request: Request) -> None:
    expected = settings.OPENCLAW_CALLBACK_TOKEN.strip()

    # Bearer 토큰 또는 커스텀 헤더에서 추출
    provided = _extract_bearer_token(request.headers.get("authorization"))
    if provided is None:
        provided = request.headers.get("x-openclaw-token")

    # 타이밍 공격 방지를 위한 상수 시간 비교
    if not provided or not hmac.compare_digest(provided, expected):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid OpenClaw callback token",
        )

5. 미들웨어 allowlist

콜백 엔드포인트는 세션 인증 우회가 필요한다.:

app/middleware/auth.py:

class AuthMiddleware(BaseHTTPMiddleware):
    # 공개 API 경로 (세션 인증 없이 접근 가능)
    PUBLIC_API_PATHS: ClassVar[list[str]] = [
        "/api/v1/openclaw/callback",
    ]

    def _is_public_api_path(self, path: str) -> bool:
        return any(
            path.startswith(public_api_path)
            for public_api_path in self.public_api_paths
        )

    async def dispatch(self, request: Request, call_next):
        path = request.url.path

      n    db.commit.assert_awaited_once()

인증 테스트

@pytest.mark.asyncio
async def test_callback_rejects_invalid_token():
    request = Mock()
    request.headers = {"authorization": "Bearer wrong_token"}

    with pytest.raises(HTTPException) as exc_info:
        await _require_openclaw_callback_token(request)

    assert exc_info.value.status_code == 401

클라이언트 테스트

@pytest.mark.asyncio
async def test_request_analysis_sends_correct_payload():
    with patch("httpx.AsyncClient") as mock_client:
        mock_response = Mock()
        mock_response.status_code = 202
        mock_client.return_value.__aenter__.return_value.post.return_value = mock_response

        client = OpenClawClient()
        request_id = await client.request_analysis(
            prompt="Analyze BTC",
            symbol="BTC",
            name="Bitcoin",
            instrument_type="crypto",
        )

        assert request_id  # UUID 형식 확인
        mock_client.return_value.__aenter__.return_value.post.assert_called_once()

트러블슈팅

405 Method Not Allowed

증상: /hooks/agent 호출 시 405 반환

원인: OpenClaw 설정에서 hooks 엔드포인트가 활성화되지 않음

해결:

# OpenClaw 설정 확인
hooks:
  enabled: true
  path: /hooks/agent

401 Unauthorized (콜백)

증상: 콜백 수신 시 401 반환

원인 1: OPENCLAW_CALLBACK_TOKEN 미설정

# .env 확인
OPENCLAW_CALLBACK_TOKEN=your_token_here

원인 2: 미들웨어 allowlist 누락

# auth.py PUBLIC_API_PATHS 확인
PUBLIC_API_PATHS = ["/api/v1/openclaw/callback"]

422 Unprocessable Entity (콜백)

증상: 콜백 페이로드 검증 실패

일반적인 원인:

# confidence가 float으로 전송됨
{"confidence": 0.62}  # ❌ 실패

# 올바른 형식: 0-100 정수
{"confidence": 62}    # ✅ 성공

스키마 확인:

confidence: int = Field(ge=0, le=100)  # 0-100 정수

5432 Connection Refused (DB)

증상: 콜백 수신은 성공, DB 저장 실패

원인: PostgreSQL 연결 불가

해결:

# Docker로 PostgreSQL 실행
docker compose up -d postgres

# 연결 테스트
docker compose exec postgres psql -U user -d database

보안 고려사항

현재 방식의 한계

# TODO(security): Replace OPENCLAW_CALLBACK_TOKEN with HMAC-signed callbacks.
# Why: the callback token is embedded into OpenClaw messages and may appear in
# logs/session history.

문제점:

토큰이 메시지에 평문으로 포함됨
OpenClaw 세션 히스토리에 토큰이 남을 수 있음
로그 시스템에 토큰 노출 가능성

향후 개선: HMAC 서명 방식

# 개선된 콜백 인증 (계획)
def verify_callback(request: Request) -> None:
    timestamp = request.headers.get("x-timestamp")
    signature = request.headers.get("x-signature")
    body = await request.body()

    # 1. 타임스탬프 검증 (5분 이내)
    if abs(time.time() - int(timestamp)) > 300:
        raise HTTPException(400, "Request too old")

    # 2. HMAC 서명 검증
    expected = hmac.new(
        SECRET_KEY.encode(),
        f"{timestamp}.{body.decode()}".encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        raise HTTPException(401, "Invalid signature")

장점:

토큰 대신 서명 전송 (비밀 키 노출 없음)
타임스탬프로 리플레이 공격 방지
본문 무결성 검증

체크리스트

환경 설정:

.env에 OPENCLAW_* 변수 설정
OPENCLAW_ENABLED=true 활성화
SSH 터널 설정 (개발 환경)

코드 배포:

app/services/openclaw_client.py 배포
app/routers/openclaw_callback.py 배포
app/middleware/auth.py allowlist 확인
app/main.py에 라우터 등록

테스트:

헬스체크 확인 (/health)
OpenClaw 훅 연결 테스트
콜백 수신 테스트
DB 저장 확인

보안:

OPENCLAW_TOKEN과 OPENCLAW_CALLBACK_TOKEN 분리
토큰 로테이션 계획 수립
HMAC 서명 방식 전환 계획 (TODO)

마치며

OpenClaw 통합의 장점

항목	Before	After
분석 실행	auto_trader에서 직접	OpenClaw로 오프로딩
LLM 선택	Gemini 고정	GPT, Claude 등 유연 선택
장애 격리	분석 실패 → 서비스 영향	분석 분리, 서비스 안정
확장성	단일 서버 제한	분석 서버 독립 스케일

다음 단계

HMAC 서명 방식으로 전환: 토큰 노출 위험 제거
재시도 로직 추가: 콜백 실패 시 자동 재시도
모니터링 대시보드: request_id로 분석 요청 추적
배치 분석: 여러 종목 동시 분석 요청

참고 자료:

프로젝트 저장소:

GitHub: github.com/mgh3326/auto_trader
PR: #113 - OpenClaw integration

질문이나 피드백은 이슈로 남겨주세요!

소개 페이지 (About)

kwanghyun — Sat, 31 Jan 2026 18:37:07 +0900

About

안녕하세요! 백엔드 개발자 광현입니다.

관심 분야

Python / FastAPI
AI 기반 자동매매 시스템
홈서버 / 라즈베리파이

연락처

GitHub: github.com/mgh3326
Email: mgh3326@gmail.com

블로그 소개

AI 자동매매 시스템 개발 과정과 개발 인프라
개선 경험을 공유합니다.

개인정보처리방침

kwanghyun — Sat, 31 Jan 2026 18:35:20 +0900

kwanghyun's Blog(이하 "블로그")는 방문자의 개인정보를
중요시하며, 개인정보보호법을 준수합니다.

1. 수집하는 개인정보

Google Analytics를 통한 방문 통계 (익명)
댓글 작성 시: 이름, 이메일 (선택)

2. 개인정보 이용 목적

블로그 운영 및 개선
댓글 알림

3. 개인정보 보유 기간

댓글 삭제 요청 시 즉시 삭제

4. 연락처

이메일: mgh3326@gmail.com

시행일: 2026년 1월 31일

Ruff + Pyright로 Python 코드 품질 도구 통합하기

kwanghyun — Sun, 25 Jan 2026 18:26:51 +0900

Ruff + Pyright 마이그레이션

Black, isort, flake8, mypy에서 Ruff + Pyright로 통합

이 글은 개발 인프라 개선 시리즈의 Infra-4편이다.

개발 인프라 개선 시리즈:

Infra-1편: Poetry에서 UV로 마이그레이션

Infra-2편: Python 3.13 업그레이드

Infra-3편: Python 3.14 업그레이드

Infra-4편: Ruff + Pyright 마이그레이션 ← 현재 글

AI 자동매매 시리즈:

1편: 한투 API로 실시간 주식 데이터 수집하기

2편: yfinance로 애플·테슬라 분석하기

3편: Upbit으로 비트코인 24시간 분석하기

4편: AI 분석 결과 DB에 저장하기

5편: Upbit 웹 트레이딩 대시보드 구축하기

6편: 실전 운영을 위한 모니터링 시스템 구축

7편: 라즈베리파이 홈서버에 자동 HTTPS로 안전하게 배포하기

들어가며

기존 도구들의 문제점

Python 코드 품질 관리를 위해 보통 여러 도구를 조합해서 사용한다.:

도구	역할	문제점
Black	코드 포맷터	설정 파일이 분산됨
isort	import 정렬	Black과 충돌 가능성
flake8	린터	느린 속도, 플러그인 관리
mypy	타입 체커	느린 속도, 복잡한 설정

우리 프로젝트의 기존 상태:

# Makefile (기존)
lint:
    uv run flake8 app/ tests/ --max-line-length=88 --extend-ignore=E203,W503
    uv run black --check app/ tests/
    uv run isort --check-only app/ tests/
    uv run mypy app/ --ignore-missing-imports

format:
    uv run black app/ tests/
    uv run isort app/ tests/

문제점:

4개의 도구를 별도로 실행 → 느린 CI 속도
설정이 여러 곳에 분산 → pyproject.toml, .flake8, setup.cfg 등
도구 간 버전/설정 충돌 → Black과 isort 스타일 불일치
mypy의 느린 속도 → 대규모 코드베이스에서 체감됨

원래 목표: ty (Astral의 타입 체커)

사실 처음에는 ty를 사용하고 싶었습니다.

ty란?

Astral에서 개발 중인 Rust 기반 타입 체커
Ruff, UV와 같은 회사에서 개발 (Astral)
mypy, Pyright보다 10-100배 빠름
향후 Ruff와 통합 예정

# ty 사용 예시 (향후)
uv run ty check app/

# 또는 Ruff 통합 후
uv run ruff check --select=TY app/

하지만 마이그레이션 시점(2025년 12월)에는:

ty가 아직 정식 릴리즈되지 않음
첫 릴리즈(v0.0.9)가 2026년 1월 5일에 나옴
현재(2026년 1월 25일) v0.0.13까지 릴리즈되었지만 여전히 초기 단계

그래서 Ruff + Pyright 조합을 선택했습니다. ty가 안정화되면 Pyright → ty로 전환할 계획이다.

Ruff와 Pyright란?

도구 비교

기존 4개 도구 → Ruff + Pyright 2개로 통합 (ty 안정화 전까지)

Ruff (Astral 개발):

Rust로 작성된 초고속 린터 + 포맷터
Black, isort, flake8, pyupgrade 등을 하나로 통합
기존 도구 대비 10-100배 빠름

Pyright (Microsoft 개발):

TypeScript로 작성된 고성능 타입 체커
VS Code Python 확장에 내장
mypy 대비 5-10배 빠름
임시 선택: ty가 안정화되면 교체 예정

마이그레이션 계획

Phase별 접근

안전한 마이그레이션을 위해 4단계로 진행했습니다:

Phase 1: Ruff 도입 (기존 도구와 병행)
    ↓
Phase 2: Pyright 도입 (기존 mypy와 병행)
    ↓
Phase 3: CI 개선 (Ruff + Pyright로 전환)
    ↓
Phase 4: 정리 (기존 도구 제거)

핵심 원칙:

각 단계에서 롤백 가능하도록 설계
기존 도구와 새 도구 결과 비교 후 전환
CI가 통과한 후에만 다음 단계 진행

Phase 1: Ruff 도입

1.1 설치 및 설정

# Ruff 설치
uv add --group dev ruff

pyproject.toml 설정:

[tool.ruff]
target-version = "py314"
line-length = 88
exclude = [
    ".venv",
    "alembic/versions",
    "__pycache__",
    "data/stocks_info",
    "data/coins_info",
]

[tool.ruff.lint]
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # Pyflakes
    "I",      # isort
    "B",      # flake8-bugbear
    "C4",     # flake8-comprehensions
    "UP",     # pyupgrade
]
ignore = [
    "E203",   # Whitespace before ':' (black compatible)
    "E501",   # Line too long (formatter handles this)
    "B008",   # FastAPI Depends() in default arguments
    "E712",   # SQLAlchemy == True comparison
    "B904",   # raise ... from err (FastAPI HTTPException pattern)
]

[tool.ruff.lint.per-file-ignores]
"app/core/celery_app.py" = ["E402"]  # Delayed import for Celery signals
"tests/conftest.py" = ["E402"]        # Delayed import after env setup

[tool.ruff.lint.isort]
known-first-party = ["app"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

1.2 주요 설정 설명

lint.select - 활성화할 규칙:
| 코드 | 기존 도구 | 역할 |
|------|----------|------|
| E, W | pycodestyle | PEP 8 스타일 검사 |
| F | Pyflakes | 논리 오류 검출 |
| I | isort | import 정렬 |
| B | flake8-bugbear | 버그 가능성 검출 |
| C4 | flake8-comprehensions | 컴프리헨션 최적화 |
| UP | pyupgrade | 최신 문법으로 자동 변환 |

lint.ignore - 예외 처리:

# E712: SQLAlchemy에서는 == True 비교가 필요
query.filter(User.is_active == True)  # noqa 없이 허용

# B008: FastAPI Depends()는 기본값에 사용해도 됨
def get_user(db: Session = Depends(get_db)):  # OK

# B904: FastAPI HTTPException은 from err 없이 사용
raise HTTPException(status_code=404)  # OK

1.3 Makefile 업데이트 (병행 기간)

# 기존 명령어 유지
lint-legacy:
    uv run flake8 app/ tests/
    uv run black --check app/ tests/
    uv run isort --check-only app/ tests/

# 새 명령어 추가
lint-ruff:
    uv run ruff check app/ tests/
    uv run ruff format --check app/ tests/

1.4 코드 자동 수정

# 린트 에러 자동 수정
uv run ruff check --fix app/ tests/

# 코드 포맷팅
uv run ruff format app/ tests/

pyupgrade (UP) 규칙으로 자동 변환된 예시:

# Before (Python 3.9 스타일)
from typing import Optional, List, Dict, Union

def get_users(ids: Optional[List[int]] = None) -> Dict[str, Union[int, str]]:
    pass

# After (Python 3.10+ 스타일)
def get_users(ids: list[int] | None = None) -> dict[str, int | str]:
    pass

Phase 2: Pyright 도입

2.1 설치 및 설정

# Pyright 설치
uv add --group dev pyright

pyproject.toml 설정:

[tool.pyright]
pythonVersion = "3.14"
pythonPlatform = "All"
typeCheckingMode = "basic"

include = ["app"]
exclude = [
    "**/__pycache__",
    ".venv",
    "alembic",
    "tests",
    "data",
]

# 점진적 마이그레이션 설정
reportMissingImports = "warning"
reportMissingTypeStubs = false
reportUnknownMemberType = false
reportUnknownParameterType = false
reportUnknownVariableType = false
reportUnknownArgumentType = false

# 특정 라이브러리 이슈 완화
reportAttributeAccessIssue = false  # ta library (no type stubs)
reportGeneralTypeIssues = false     # SQLAlchemy async session
reportArgumentType = false          # dict.get() returns Unknown | None
reportCallIssue = false             # Pydantic Field overloads

2.2 typeCheckingMode 이해

모드	엄격도	용도
off	검사 없음	타입 검사 비활성화
basic	낮음	점진적 도입 시작점
standard	중간	일반적인 프로젝트
strict	높음	완벽한 타입 안전성
all	최고	모든 규칙 활성화

basic 모드 선택 이유:

외부 라이브러리에 타입 스텁이 없는 경우가 많음
점진적으로 strict 모드로 전환 가능
주요 타입 에러만 잡으면서 생산성 유지

2.3 주요 타입 에러 수정

수정 전:

# app/services/upbit.py
async def get_candles(self, market: str, count: int = 200):
    response = await self.client.get(url, params=params)
    return response.json()  # Unknown type

수정 후:

async def get_candles(self, market: str, count: int = 200) -> list[dict]:
    response = await self.client.get(url, params=params)
    data: list[dict] = response.json()
    return data

2.4 타입 무시 주석

어쩔 수 없이 타입 에러를 무시해야 하는 경우:

# 특정 줄만 무시
from app.services.telegram import TelegramService  # type: ignore[import-not-found]

# 또는 pyright 전용
from external_lib import something  # pyright: ignore[reportMissingImports]

Phase 3: CI 개선

3.1 GitHub Actions 워크플로우

# .github/workflows/test.yml
name: Test

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  lint:
    runs-on: ubuntu-latest
    env:
      PYTHON_VERSION: "3.14"

    steps:
    - uses: actions/checkout@v4

    - name: Set up Python ${{ env.PYTHON_VERSION }}
      uses: actions/setup-python@v6
      with:
        python-version: ${{ env.PYTHON_VERSION }}

    - name: Install UV
      run: pip install uv

    - name: Load cached venv
      uses: actions/cache@v3
      with:
        path: .venv
        key: venv-${{ runner.os }}-${{ env.PYTHON_VERSION }}-${{ hashFiles('**/uv.lock') }}

    - name: Install dependencies
      run: uv sync --group dev

    - name: Run Ruff linter
      run: uv run ruff check app/ tests/

    - name: Run Ruff formatter check
      run: uv run ruff format --check app/ tests/

    - name: Run Pyright
      run: uv run pyright app/

  test:
    needs: lint  # lint 통과 후 테스트 실행
    runs-on: ubuntu-latest
    # ... 기존 테스트 설정 ...

3.2 lint → test 의존성

test:
  needs: lint  # 핵심!

효과:

린트 실패 시 테스트 실행 안 함 (리소스 절약)
빠른 피드백 (린트는 테스트보다 훨씬 빠름)
PR에서 명확한 실패 지점 파악

CI 파이프라인

lint → test → security 순서로 실행되는 CI 파이프라인

Phase 4: 정리

4.1 기존 도구 제거

# 기존 도구 제거
uv remove --group dev black isort flake8 mypy

4.2 최종 Makefile

.PHONY: lint format typecheck

lint: ## Run linting checks (Ruff + Pyright)
    uv run ruff check app/ tests/
    uv run ruff format --check app/ tests/
    uv run pyright app/

format: ## Format code with Ruff
    uv run ruff format app/ tests/
    uv run ruff check --fix app/ tests/

typecheck: ## Run Pyright type checking
    uv run pyright app/

4.3 최종 의존성

[dependency-groups]
dev = [
    "ruff>=0.14.10",
    "pyright>=1.1.407",
    "bandit>=1.7.0,<2.0.0",
    "safety>=3.7.0,<3.8.0",
    "playwright>=1.56.0",
]

Before (6개 도구):

black, isort, flake8, mypy, bandit, safety

After (4개 도구):

ruff, pyright, bandit, safety

성능 비교

린트 속도 비교

# 기존 도구 (flake8 + black + isort)
time make lint-legacy
# real    0m4.823s

# Ruff
time uv run ruff check app/ tests/
# real    0m0.312s

결과: 15배 빠름!

타입 체크 속도 비교

# mypy
time uv run mypy app/
# real    0m12.456s

# Pyright
time uv run pyright app/
# real    0m2.134s

결과: 6배 빠름!

CI 실행 시간

단계	Before	After	개선
lint job	42초	18초	57% 감소
전체 CI	3분 12초	2분 28초	23% 감소

성능 비교

기존 도구 vs Ruff + Pyright 속도 비교

마이그레이션 결과

변경된 파일 수

항목	수량
변경된 파일	101개
추가된 라인	5,000+
삭제된 라인	3,200+
타입 힌트 개선	200+ 곳

pyupgrade로 현대화된 코드

Union → | 연산자:

# 101개 파일에서 자동 변환
Optional[str] → str | None
Union[int, str] → int | str
List[dict] → list[dict]
Dict[str, Any] → dict[str, Any]

새로 발견된 잠재적 버그

Ruff의 B (bugbear) 규칙으로 발견:

# 발견된 이슈: 가변 기본 인자
def process(items: list = []):  # B006: 위험!
    items.append(1)
    return items

# 수정
def process(items: list | None = None):
    if items is None:
        items = []
    items.append(1)
    return items

향후 계획

1. ty로 전환 (최우선)

ty가 안정화되면 Pyright에서 ty로 전환할 계획이다.

ty의 장점:
| 특징 | Pyright | ty |
|------|---------|-----|
| 언어 | TypeScript | Rust |
| 속도 | 빠름 | 10-100배 더 빠름 |
| Ruff 통합 | 별도 실행 | 향후 통합 예정 |
| 개발사 | Microsoft | Astral (Ruff, UV와 동일) |

ty의 주요 기능:

교집합 타입(Intersection types): 더 정밀한 타입 표현
정교한 타입 좁히기: 조건문에서 더 스마트한 타입 추론
도달성 분석: 도달 불가능한 코드 감지
풍부한 진단: 컨텍스트 정보가 포함된 에러 메시지
언어 서버: 코드 네비게이션, 자동완성, 자동 임포트

전환 타이밍:

ty가 v1.0 또는 안정 버전에 도달하면 전환
현재 v0.0.13 (2026년 1월 21일 기준)으로 빠르게 개발 중
Ruff 통합이 완료되면 도구 하나로 린트 + 타입 체크 가능

# 현재 (Ruff + Pyright)
uv run ruff check app/ tests/
uv run pyright app/

# 향후 (Ruff + ty 통합)
uv run ty check app/
# 또는
uv run ruff check app/ tests/  # 린트 + 타입 체크 통합

마이그레이션 계획:

현재: Ruff + Pyright (안정적)
    ↓ ty v1.0 릴리즈 시
중간: Ruff + ty (Pyright 대체)
    ↓ Ruff-ty 통합 완료 시
최종: Ruff (올인원)

2. Pyright strict 모드 전환 (ty 전환 전까지)

ty 전환 전까지 Pyright를 점진적으로 강화:

# 현재
[tool.pyright]
typeCheckingMode = "basic"

# 중간 목표
typeCheckingMode = "standard"

# 최종 목표 (ty 전환 전)
typeCheckingMode = "strict"

3. pre-commit 훅 추가

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.10
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

체크리스트

마이그레이션 전:

기존 린트/타입 체크 모두 통과 확인
CI 파이프라인 정상 동작 확인
롤백 계획 수립

Phase 1 (Ruff):

Ruff 설치 및 pyproject.toml 설정
기존 도구와 결과 비교
린트 에러 수정 또는 ignore 설정
Makefile 병행 명령어 추가

Phase 2 (Pyright):

Pyright 설치 및 pyproject.toml 설정
기존 mypy와 결과 비교
타입 에러 수정 또는 ignore 설정

Phase 3 (CI):

GitHub Actions 워크플로우 업데이트
lint job 추가 (Ruff + Pyright)
test job에 needs: lint 추가

Phase 4 (정리):

기존 도구 의존성 제거
pyproject.toml 정리
Makefile 최종 버전 적용
문서 업데이트 (CLAUDE.md, README.md)

마치며

Ruff + Pyright 마이그레이션 소감

가장 좋았던 점:

압도적인 속도 향상 - 린트 15배, 타입 체크 6배 빠름
설정 통합 - pyproject.toml 하나로 모든 설정 관리
자동 코드 현대화 - pyupgrade 규칙으로 최신 문법 적용
잠재적 버그 발견 - bugbear 규칙으로 위험한 패턴 검출

주의할 점:

점진적 도입 권장 - 한 번에 모든 규칙 적용하면 수정량이 폭발
팀원 합의 필요 - 새 도구 도입은 팀 전체 동의 필수
IDE 설정 동기화 - VS Code에서 Ruff/Pyright 확장 설치 필요

권장 사항

✅ Ruff + Pyright 도입 추천:

Python 3.10+ 프로젝트
CI 속도 개선이 필요한 경우
설정 파일 분산이 복잡한 경우
최신 Python 문법을 적용하고 싶은 경우

⚠️ 신중히 검토:

Python 3.9 이하 프로젝트 (pyupgrade 규칙 조정 필요)
mypy 플러그인을 많이 사용하는 경우
기존 CI에 강하게 결합된 lint 설정이 있는 경우

다음 단계

이제 우리 프로젝트는:

✅ UV로 의존성 관리 (Infra-1편)
✅ Python 3.13 (Infra-2편)
✅ Python 3.14 (Infra-3편)
✅ Ruff + Pyright (Infra-4편)

다음 인프라 개선으로는 pre-commit 훅 설정과 Pyright strict 모드 전환을 검토 중이다.

참고 자료:

Ruff Documentation
Ruff Rules Reference
Pyright Documentation
ty Documentation - Astral의 Rust 기반 타입 체커
ty GitHub Repository
UV Documentation

프로젝트 저장소:

GitHub: github.com/mgh3326/auto_trader

질문이나 피드백은 이슈로 남겨주세요!

프릳츠 디카페인 원두 V60 드립 레시피 | Kingrinder K6 + 하리오 V60-02

kwanghyun — Sun, 25 Jan 2026 12:41:19 +0900

카페인 없이도 맛있는 커피를 즐기고 싶을 때, 프릳츠의 디카페인 원두는 좋은 선택이다. "FULL TIME COFFEE LOVER"라는 문구가 적힌 파란색 패키지처럼, 하루 종일 커피를 마시고 싶은 사람들을 위한 원두다.

이 글에서는 Kingrinder K6 그라인더와 하리오 V60-02 드리퍼로 프릳츠 디카페인을 맛있게 추출하는 레시피를 정리한다.

디카페인 원두의 특성

디카페인 원두는 일반 원두와 추출 특성이 다르다. 카페인 제거 과정에서 원두의 셀룰로스 구조가 변하면서 물이 더 빠르게 침투하고, 추출도 빨리 진행된다. 같은 세팅으로 내리면 과다추출되기 쉽다.

이를 보정하려면 두 가지를 조정한다:

물 온도를 낮추기 (92~94°C)
분쇄도를 굵게 잡기

기본 레시피

목표: 깔끔하고 단맛 중심, 쓴맛 과다 방지

항목	세팅
원두	20g
물	300g (비율 1:15)
물 온도	92~94°C
분쇄도 (K6)	85~95 클릭
목표 시간	2:45 ~ 3:15

V60 기준 중간에서 약간 굵은 정도의 분쇄도다. K6 기준 90 클릭 근처에서 시작해서 맛을 보고 조정하면 된다.

푸어링 스케줄

준비

필터를 충분히 린스해서 종이 냄새를 제거하고, 서버와 드리퍼를 예열한다. 예열에 쓴 물은 버린다.

1. 블루밍 (0:00)

50g 투입
원두 전체를 골고루 적신 뒤 가볍게 스월 한 번 (또는 젓기 1~2회)
0:40까지 가스 배출 대기

2. 1차 푸어 (0:40)

150g까지 천천히, 가는 물줄기로 투입
수위를 너무 높이지 않도록 주의
끝나면 가볍게 드리퍼를 톡 치거나 스월 (선택)

3. 2차 푸어 (1:20)

230g까지 투입

4. 마무리 푸어 (1:55)

300g까지 투입
마지막에 아주 가볍게 스월 한 번 (벽면 가루 정리 + 평탄화)
완전 드립 종료: 2:45~3:15

맛으로 튜닝하기

추출 결과가 마음에 안 들면 아래 기준으로 조정한다.

쓴맛/텁텁/탄 느낌 (과다추출)

분쇄 더 굵게 (+5 클릭)
물 온도 낮추기 (-1~2°C)
스월/교반 줄이기

시큼/밍밍/바디 얇음 (과소추출)

분쇄 더 곱게 (-5 클릭)
물 온도 높이기 (+1~2°C)
총 물량 늘리기 (310~~320g, 비율 1:15.5~~1:16)

바디는 괜찮은데 단맛 부족

분쇄도는 유지
붓는 속도를 더 천천히
마지막 스월은 "아주 살짝"만

마무리

프릳츠 디카페인은 저녁이나 카페인에 민감한 날에도 커피를 즐길 수 있게 해주는 원두다. 디카페인 특유의 추출 특성만 이해하고 세팅을 조금 조정하면, 일반 원두 못지않은 맛을 뽑아낼 수 있다.

로스팅 프로파일(초콜릿/너티 계열인지 과일향 계열인지)과 현재 추출 결과(쓴쪽/신쪽/밍밍)에 따라 K6 클릭을 더 정밀하게 맞출 수 있으니, 몇 번 내려보면서 본인 취향에 맞는 스윗스팟을 찾아보자.

사용 장비: Kingrinder K6, 하리오 V60-02, 프릳츠 디카페인 200g

Python 3.14 업그레이드: t-strings, Free-threading, 그리고 성능 개선

kwanghyun — Fri, 19 Dec 2025 18:05:39 +0900

Python 3.14 업그레이드

Python 3.14 "Pi Release" - t-strings, Free-threading, 성능 개선

이 글은 개발 인프라 개선 시리즈의 Infra-3편이다.

개발 인프라 개선 시리즈:

Infra-1편: Poetry에서 UV로 마이그레이션

Infra-2편: Python 3.13 업그레이드

Infra-3편: Python 3.14 업그레이드 ← 현재 글

AI 자동매매 시리즈:

1편: 한투 API로 실시간 주식 데이터 수집하기

2편: yfinance로 애플·테슬라 분석하기

3편: Upbit으로 비트코인 24시간 분석하기

4편: AI 분석 결과 DB에 저장하기

5편: Upbit 웹 트레이딩 대시보드 구축하기

6편: 실전 운영을 위한 모니터링 시스템 구축

7편: 라즈베리파이 홈서버에 자동 HTTPS로 안전하게 배포하기

들어가며

Python 3.14 - "Pi Release"

Python 3.14가 2025년 10월에 정식 릴리즈되었습니다. 버전 번호가 원주율(π ≈ 3.14159...)과 같아서 "Pi Release"라는 별명이 붙었습니다!

Python 버전 타임라인

Python 버전별 릴리즈 및 EOL 타임라인 (3.14 추가)

왜 3.13에서 바로 3.14로?

지난 Infra-2편에서 Python 3.13으로 업그레이드한 지 1년밖에 되지 않았는데, 왜 벌써 3.14로 업그레이드한다.

이번 업그레이드를 결정한 이유:

t-strings: SQL 인젝션 방지 등 보안 강화에 유용
Free-threading 공식 지원: GIL 없이 멀티스레딩 성능 극대화
3-5% 성능 향상: Tail-call interpreter로 체감 가능한 속도 개선
지연된 어노테이션 평가: 순환 참조 없이 타입 힌팅 가능
Zstandard 압축: 기본 라이브러리로 고성능 압축 지원

Python 3.14의 주요 변경사항

1. Template Strings (t-strings) - PEP 750

Python 3.14의 가장 혁신적인 기능이다. f-string과 비슷하지만, 문자열 처리를 커스터마이징할 수 있다.

기본 사용법:

from string.templatelib import Template, Interpolation

name = "Alice"
template = t"Hello, {name}!"

# Template 객체 반환 (문자열이 아님!)
print(type(template))  # <class 'string.templatelib.Template'>

# 정적/동적 부분에 개별 접근 가능
for part in template:
    print(part)
# 출력:
# Hello,
# Interpolation('Alice', 'name', None, '')
# !

실전 활용 - SQL 인젝션 방지:

from string.templatelib import Template, Interpolation

def safe_sql(template: Template) -> tuple[str, list]:
    """SQL 인젝션을 방지하는 안전한 쿼리 생성"""
    query_parts = []
    params = []

    for part in template:
        if isinstance(part, Interpolation):
            query_parts.append("?")  # placeholder
            params.append(part.value)
        else:
            query_parts.append(part)

    return "".join(query_parts), params

# 사용 예시
user_input = "'; DROP TABLE users; --"  # 악의적인 입력
query, params = safe_sql(t"SELECT * FROM users WHERE name = {user_input}")

print(query)   # SELECT * FROM users WHERE name = ?
print(params)  # ["'; DROP TABLE users; --"]
# SQL 인젝션 완전 차단!

HTML 이스케이프:

import html
from string.templatelib import Template, Interpolation

def safe_html(template: Template) -> str:
    """XSS를 방지하는 안전한 HTML 생성"""
    parts = []
    for part in template:
        if isinstance(part, Interpolation):
            parts.append(html.escape(str(part.value)))
        else:
            parts.append(part)
    return "".join(parts)

user_comment = "<script>alert('XSS')</script>"
safe_output = safe_html(t"<div>{user_comment}</div>")
# <div>&lt;script&gt;alert('XSS')&lt;/script&gt;</div>

2. Free-threaded Python 공식 지원 (PEP 779)

Python 3.13에서 실험적이었던 Free-threading이 공식 지원으로 승격되었습니다.

GIL(Global Interpreter Lock) 없이 진정한 병렬 처리:

import threading
import time

def cpu_intensive(n: int) -> int:
    """CPU 집약적인 작업"""
    total = 0
    for i in range(n):
        total += i * i
    return total

# Free-threaded 빌드에서는 진정한 병렬 처리!
threads = []
start = time.time()

for _ in range(4):
    t = threading.Thread(target=cpu_intensive, args=(10_000_000,))
    threads.append(t)
    t.start()

for t in threads:
    t.join()

print(f"실행 시간: {time.time() - start:.2f}초")
# Free-threaded: ~1초 (4배 빠름)
# 일반 Python: ~4초 (순차 실행과 동일)

InterpreterPoolExecutor로 더 간단하게:

from concurrent.futures import InterpreterPoolExecutor

def analyze_stock(symbol: str) -> dict:
    # CPU 집약적인 분석 작업
    return {"symbol": symbol, "result": "..."}

symbols = ["005930", "000660", "035420", "068270"]

# 각 인터프리터가 독립적인 GIL을 가짐 (또는 GIL 없음)
with InterpreterPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(analyze_stock, symbols))

3. Tail-call Interpreter (3-5% 성능 향상)

새로운 인터프리터 구현으로 전반적인 성능이 3-5% 향상되었습니다.

주요 최적화:

개별 Python opcode를 작은 C 함수로 구현
Tail call 최적화로 함수 호출 오버헤드 감소
Clang 19+, x86-64/AArch64에서 최적의 성능

모듈별 성능 개선:
| 모듈/함수 | 개선 폭 |
|----------|--------|
| base64.b16decode() | 6배 빠름 |
| uuid.uuid3/uuid5() | 40% 빠름 |
| uuid.uuid4() | 30% 빠름 |
| difflib.IS_LINE_JUNK() | 2배 빠름 |
| 파일 읽기 (캐시된) | 15% 빠름 |

4. 지연된 어노테이션 평가 (PEP 649, 749)

타입 힌팅에서 전방 참조 문자열이 더 이상 필요 없다.!

Before (Python 3.13 이하):

from __future__ import annotations  # 필수

class Node:
    def __init__(self, value: int):
        self.value = value
        self.next: "Node" = None  # 문자열로 감싸야 함

    def append(self, node: "Node") -> "Node":
        self.next = node
        return node

After (Python 3.14):

# from __future__ import annotations 불필요!

class Node:
    def __init__(self, value: int):
        self.value = value
        self.next: Node = None  # 그냥 사용 가능!

    def append(self, node: Node) -> Node:
        self.next = node
        return node

annotationlib으로 어노테이션 검사:

from annotationlib import get_annotations, Format

def greet(name: str) -> str:
    return f"Hello, {name}"

# 값으로 평가
annotations = get_annotations(greet, format=Format.VALUE)
print(annotations)  # {'name': <class 'str'>, 'return': <class 'str'>}

# 문자열로 가져오기
annotations = get_annotations(greet, format=Format.STRING)
print(annotations)  # {'name': 'str', 'return': 'str'}

5. Zstandard 압축 지원 (PEP 784)

표준 라이브러리에서 Zstandard 압축을 지원한다.!

from compression import zstd
import json

# 대용량 데이터 압축
data = json.dumps({"prices": list(range(100000))}).encode()

# 압축
compressed = zstd.compress(data)
print(f"원본: {len(data):,} bytes")
print(f"압축: {len(compressed):,} bytes")
print(f"압축률: {len(compressed) / len(data) * 100:.1f}%")

# 압축 해제
decompressed = zstd.decompress(compressed)
assert data == decompressed

tarfile, zipfile에서도 지원:

import tarfile

# .tar.zst 아카이브 생성
with tarfile.open("backup.tar.zst", "w|zst") as tar:
    tar.add("data/")

# .tar.zst 아카이브 읽기
with tarfile.open("backup.tar.zst", "r|zst") as tar:
    tar.extractall("restored/")

6. UUID v6, v7, v8 지원 (RFC 9562)

시간 기반 정렬이 가능한 UUID v7:

import uuid

# UUID v7: 시간 기반, 정렬 가능
id1 = uuid.uuid7()
id2 = uuid.uuid7()
id3 = uuid.uuid7()

# 생성 순서대로 정렬됨!
print(sorted([id3, id1, id2]) == [id1, id2, id3])  # True

# UUID v6: UUID v1의 개선 버전
id_v6 = uuid.uuid6()

# UUID v8: 커스텀 데이터 포함
custom_data = b"\x12\x34\x56\x78\x9a\xbc\xde\xf0\x12\x34\x56\x78\x9a\xbc\xde\xf0"
id_v8 = uuid.uuid8(custom_data)

데이터베이스 PK로 UUID v7 활용:

from sqlalchemy import Column
from sqlalchemy.dialects.postgresql import UUID
import uuid

class StockAnalysis(Base):
    __tablename__ = "stock_analysis"

    # UUID v7: 시간순 정렬 + 고유성
    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid7)
    # 인덱스 성능 향상: 시간순 삽입으로 B-tree 효율적

7. except 괄호 생략 가능 (PEP 758)

여러 예외를 괄호 없이 처리:

# Python 3.14
try:
    response = await fetch_data()
except TimeoutError, ConnectionError:  # 괄호 없이!
    print("네트워크 오류 발생")

# 기존 방식도 계속 지원
try:
    response = await fetch_data()
except (TimeoutError, ConnectionError):  # 괄호 사용
    print("네트워크 오류 발생")

8. 향상된 오류 메시지

더 친절한 SyntaxError:

# 키워드 오타 감지
whille True:  # typo!
    pass
# SyntaxError: invalid syntax. Did you mean 'while'?

# 잘못된 할당
x = 10
if x = 20:  # = 대신 ==
    pass
# SyntaxError: invalid syntax. Maybe you meant '==' instead of '='?

TypeError 명확화:

s = set()
s.add({"key": "value"})
# TypeError: cannot use 'dict' as a set element (unhashable type: 'dict')
# 이전: TypeError: unhashable type: 'dict'

9. pdb 원격 디버깅

실행 중인 프로세스에 디버거 연결:

# 실행 중인 Python 프로세스 PID 확인
ps aux | grep python
# PID: 12345

# 원격 디버거 연결
python -m pdb -p 12345

asyncio 태스크 내검:

# 실행 중인 asyncn

Deprecations 주의사항

3.14에서 제거된 API

# asyncio.get_event_loop() - RuntimeError 발생!
# Before (3.13 이하)
loop = asyncio.get_event_loop()
loop.run_until_complete(main())

# After (3.14)
asyncio.run(main())
# 또는
async with asyncio.Runner() as runner:
    runner.run(main())

향후 제거 예정

버전	제거 예정 API
3.15	`asyncio.iscoroutinefunction()`
3.16	asyncio 정책 시스템
3.17	`typing.ByteString`

체크리스트

업그레이드 전:

주요 의존성이 Python 3.14 지원하는지 확인
asyncio.get_event_loop() 사용 여부 확인
현재 환경에서 모든 테스트 통과

업그레이드 중:

.python-version 파일 업데이트 (3.13 → 3.14)
pyproject.toml의 requires-python 업데이트
uv lock으로 lockfile 재생성
GitHub Actions 워크플로우 업데이트

업그레이드 후:

로컬 환경에서 테스트 실행
CI/CD 파이프라인 통과 확인
프로덕션 배포 후 모니터링

마치며

Python 3.14 업그레이드 소감

Python 3.13에서 3.14로의 업그레이드는 예상보다 훨씬 수월했습니다.

가장 마음에 드는 기능:

t-strings: SQL 인젝션, XSS 방지가 언어 레벨에서 지원
성능 향상: 별도 최적화 없이 4-6% 빠름
지연된 어노테이션: from __future__ import annotations 안녕!

실제 적용할 기능:

UUID v7으로 DB PK 변경 검토
t-strings로 동적 SQL 쿼리 안전하게 생성
Zstandard로 대용량 로그 압축

권장 사항

✅ Python 3.14 업그레이드 추천:

이미 Python 3.13을 사용 중인 프로젝트
t-strings의 보안 기능이 필요한 경우
성능 개선이 필요한 경우

⚠️ 신중히 검토:

asyncio.get_event_loop() 를 많이 사용하는 레거시 코드
아직 3.14 미지원 라이브러리에 의존하는 경우

다음 단계

이제 우리 프로젝트는:

✅ UV로 의존성 관리 (Infra-1편)
✅ Python 3.13 (Infra-2편)
✅ Python 3.14 (Infra-3편)

참고 자료:

프로젝트 저장소:

GitHub: github.com/mgh3326/auto_trader

질문이나 피드백은 이슈로 남겨주세요!

다중 브로커 통합 포트폴리오: 토스 증권 수동 잔고 연동하기

kwanghyun — Mon, 1 Dec 2025 20:51:58 +0900

통합 포트폴리오 시스템

이 글은 AI 기반 자동매매 시스템 시리즈의 10편이다.

전체 시리즈:

1편: 한투 API로 실시간 주식 데이터 수집하기

2편: yfinance로 애플·테슬라 분석하기

3편: Upbit으로 비트코인 24시간 분석하기

4편: AI 분석 결과 DB에 저장하기

5편: Upbit 웹 트레이딩 대시보드 구축하기

6편: 실전 운영을 위한 모니터링 시스템 구축

7편: 라즈베리파이 홈서버에 자동 HTTPS로 안전하게 배포하기

8편: JWT 인증 시스템으로 안전한 웹 애플리케이션 구축하기

9편: KIS 국내/해외 주식 자동 매매 시스템 구축하기

10편: 다중 브로커 통합 포트폴리오 시스템 구축하기 ← 현재 글

들어가며

왜 통합 포트폴리오인가?

실제 투자를 하다 보면 여러 증권사에 분산 투자하는 경우가 많습니다.

나의 현실:
├── 한국투자증권 (KIS) - API 연동 ✅
│   ├── 삼성전자 50주 @ 68,200원
│   └── SK하이닉스 20주 @ 185,500원
│
└── 토스증권 - API 없음 ❌
    ├── 삼성전자 30주 @ 71,000원
    └── AAPL 10주 @ $180

문제점:

분산된 보유 현황: 같은 종목을 여러 브로커에서 보유
평단가 계산 불가: 통합 평단가를 알 수 없음
AI 분석 비효율: 실제 보유량을 모르면 정확한 분석 불가
수동 관리 필요: 토스 잔고 변경 시 수동으로 기록해야 함

이번 편에서 만들 것

통합 포트폴리오 시스템
├── 수동 잔고 등록 대시보드
│   ├── 브로커 계좌 관리 (토스, 한투, 업비트)
│   ├── 종목별 잔고 등록/수정/삭제
│   └── 대량 등록 (Bulk Import)
│
├── 통합 평단가 계산
│   ├── KIS 보유 + 토스 보유 = 통합 평단가
│   └── 브로커별 평단가 비교
│
├── 가격 전략 시스템
│   ├── 다양한 매수/매도 전략
│   └── 시뮬레이션 (Dry-run)
│
└── 토스 알림 서비스
    ├── 매수/매도 추천 알림
    └── 예상 수익 계산

시스템 아키텍처

통합 포트폴리오 아키텍처

다중 브로커 통합 포트폴리오 시스템 구조

핵심 설계 원칙

1. KIS는 API, 나머지는 수동

# KIS: 실시간 API로 자동 조회
kis_holdings = await kis_client.fetch_my_stocks()

# 토스: DB에 수동 등록된 데이터 조회
manual_holdings = await manual_service.get_holdings_by_user(user_id)

2. 통합 평단가 = 가중 평균

# 삼성전자 예시
# KIS: 50주 @ 68,200원
# 토스: 30주 @ 71,000원

total_value = (50 * 68,200) + (30 * 71,000)  # 5,540,000원
total_quantity = 50 + 30  # 80주
combined_avg = total_value / total_quantity  # 69,250원

3. 매도는 KIS 보유분만

# 토스는 API가 없으므로 주문 불가
# KIS 보유분 50주 내에서만 매도 가능
if requested_quantity > kis_quantity:
    raise Error("KIS 보유 수량 초과")

데이터베이스 설계

수동 잔고 ERD

수동 잔고 관리 ERD

브로커 계좌 테이블

# app/models/manual_holdings.py

class BrokerType(str, enum.Enum):
    """브로커 타입"""
    kis = "kis"      # 한국투자증권
    toss = "toss"    # 토스증권
    upbit = "upbit"  # 업비트 (암호화폐)


class MarketType(str, enum.Enum):
    """시장 타입"""
    KR = "KR"          # 국내주식
    US = "US"          # 해외주식
    CRYPTO = "CRYPTO"  # 암호화폐


class BrokerAccount(Base):
    """브로커 계좌 테이블

    사용자별 브로커 계좌를 관리
    """

    __tablename__ = "broker_accounts"
    __table_args__ = (
        UniqueConstraint(
            "user_id", "broker_type", "account_name",
            name="uq_broker_account"
        ),
    )

    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True
    )
    broker_type: Mapped[BrokerType] = mapped_column(
        Enum(BrokerType, name="broker_type"),
        nullable=False
    )
    account_name: Mapped[str] = mapped_column(
        Text, nullable=False, default="기본 계좌"
    )
    is_mock: Mapped[bool] = mapped_column(
        Boolean, default=False, nullable=False
    )  # 모의투자 계좌 여부
    is_active: Mapped[bool] = mapped_column(
        Boolean, default=True, nullable=False
    )

    # Relationships
    holdings: Mapped[list["ManualHolding"]] = relationship(
        back_populates="broker_account",
        cascade="all, delete-orphan"  # 계좌 삭제 시 보유 종목도 삭제
    )

수동 보유 종목 테이블

class ManualHolding(Base):
    """수동 등록 보유 종목 테이블

    외부 브로커의 보유 종목을 수동으로 등록
    """

    __tablename__ = "manual_holdings"
    __table_args__ = (
        UniqueConstraint(
            "broker_account_id", "ticker", "market_type",
            name="uq_holding_ticker"
        ),
    )

    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
    broker_account_id: Mapped[int] = mapped_column(
        ForeignKey("broker_accounts.id", ondelete="CASCADE"),
        nullable=False,
        index=True
    )
    ticker: Mapped[str] = mapped_column(Text, nullable=False, index=True)
    market_type: Mapped[MarketType] = mapped_column(
        Enum(MarketType, name="market_type"),
        nullable=False
    )
    quantity: Mapped[float] = mapped_column(
        Numeric(18, 8), nullable=False
    )
    avg_price: Mapped[float] = mapped_column(
        Numeric(18, 8), nullable=False
    )
    display_name: Mapped[str | None] = mapped_column(
        Text, nullable=True
    )  # "버크셔 해서웨이 B" 같은 사용자 정의 표시명

    # Relationships
    broker_account: Mapped["BrokerAccount"] = relationship(
        back_populates="holdings"
    )

종목 별칭 테이블

토스에서는 "버크셔 해서웨이 B"로 표시되지만, 실제 티커는 "BRK.B"이다.

class StockAlias(Base):
    """종목 별칭 테이블

    토스 등에서 사용하는 종목 별칭을 정규 티커에 매핑
    예: "버크셔 해서웨이 B" -> "BRK.B"
    """

    __tablename__ = "stock_aliases"
    __table_args__ = (
        UniqueConstraint("alias", "market_type", name="uq_alias_market"),
    )

    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
    ticker: Mapped[str] = mapped_column(Text, nullable=False, index=True)
    market_type: Mapped[MarketType] = mapped_column(
        Enum(MarketType, name="market_type"),
        nullable=False
    )
    alias: Mapped[str] = mapped_column(Text, nullable=False, index=True)
    source: Mapped[str] = mapped_column(
        Text, nullable=False, default="user"
    )  # toss, user, kis

사용 예시:

# 별칭 등록
await alias_service.create({
    "ticker": "BRK.B",
    "market_type": "US",
    "alias": "버크셔 해서웨이 B",
    "source": "toss"
})

# 별칭으로 티커 조회
ticker = await alias_service.resolve_alias(
    "버크셔 해서웨이 B", MarketType.US
)  # → "BRK.B"

통합 포트폴리오 서비스

핵심 데이터 구조

# app/services/merged_portfolio_service.py

@dataclass
class HoldingInfo:
    """단일 브로커의 보유 정보"""
    broker: str      # "kis", "toss" 등
    quantity: float
    avg_price: float


@dataclass
class ReferencePrices:
    """참조 평단가 정보"""
    kis_avg: float | None = None
    kis_quantity: int = 0
    toss_avg: float | None = None
    toss_quantity: int = 0
    combined_avg: float | None = None
    total_quantity: int = 0


@dataclass
class MergedHolding:
    """통합 보유 종목 정보"""
    ticker: str
    name: str
    market_type: str

    # 브로커별 보유 정보
    holdings: list[HoldingInfo]
    kis_quantity: int = 0
    kis_avg_price: float = 0.0
    toss_quantity: int = 0
    toss_avg_price: float = 0.0

    # 통합 정보
    combined_avg_price: float = 0.0
    total_quantity: int = 0
    current_price: float = 0.0
    evaluation: float = 0.0
    profit_loss: float = 0.0
    profit_rate: float = 0.0

    # AI 분석 정보
    analysis_id: int | None = None
    last_analysis_decision: str | None = None
    analysis_confidence: int | None = None

가중 평균 평단가 계산

class MergedPortfolioService:
    """통합 포트폴리오 서비스"""

    @staticmethod
    def calculate_combined_avg(holdings: list[HoldingInfo]) -> float:
        """가중 평균 평단가 계산

        공식: Σ(수량 × 평단가) / Σ(수량)
        """
        total_value = 0.0
        total_quantity = 0.0

        for h in holdings:
            total_value += h.quantity * h.avg_price
            total_quantity += h.quantity

        if total_quantity == 0:
            return 0.0

        return total_value / total_quantity

KIS + 수동 잔고 병합

async def _build_merged_portfolio(
    self,
    user_id: int,
    market_type: MarketType,
    kis_client: KISClient,
) -> list[MergedHolding]:
    """KIS 보유 종목과 수동 등록 종목을 병합"""
    merged: dict[str, MergedHolding] = {}

    # 1. KIS 보유 종목 조회 및 적용
    kis_stocks = await self._fetch_kis_holdings(kis_client, market_type)
    self._apply_kis_holdings(merged, kis_stocks, market_type)

    # 2. 수동 등록 보유 종목 적용
    await self._apply_manual_holdings(merged, user_id, market_type)

    # 3. 통합 정보 계산 (평단가, 수익률 등)
    self._finalize_holdings(merged)

    # 4. AI 분석 결과 및 거래 설정 첨부
    await self._attach_analysis_and_settings(merged)

    return list(merged.values())

수동 잔고 적용 로직

async def _apply_manual_holdings(
    self,
    merged: dict[str, MergedHolding],
    user_id: int,
    market_type: MarketType,
) -> None:
    """수동 등록 보유 종목 적용"""
    manual_holdings = await self.manual_holdings_service.get_holdings_by_user(
        user_id, market_type=market_type
    )

    for holding in manual_holdings:
        ticker = holding.ticker
        broker_type = holding.broker_account.broker_type.value  # "toss"
        qty = int(holding.quantity)
        avg_price = float(holding.avg_price)
        name = holding.display_name or ticker

        # 기존 MergedHolding에 추가하거나 새로 생성
        merged_holding = merged.get(ticker)
        if not merged_holding:
            n    reference_prices: ReferencePrices,
) -> dict[str, ExpectedProfit]:
    """예상 수익 계산 (각 평단가 기준별)"""
    ref = reference_prices
    results: dict[str, ExpectedProfit] = {}

    # 한투 평단가 기준 수익
    if ref.kis_avg and ref.kis_avg > 0:
        profit = (sell_price - ref.kis_avg) * quantity
        percent = (sell_price - ref.kis_avg) / ref.kis_avg * 100
        results["based_on_kis_avg"] = ExpectedProfit(
            amount=round(profit, 2),
            percent=round(percent, 2),
        )

    # 토스 평단가 기준 수익
    if ref.toss_avg and ref.toss_avg > 0:
        profit = (sell_price - ref.toss_avg) * quantity
        percent = (sell_price - ref.toss_avg) / ref.toss_avg * 100
        results["based_on_toss_avg"] = ExpectedProfit(
            amount=round(profit, 2),
            percent=round(percent, 2),
        )

    # 통합 평단가 기준 수익
    if ref.combined_avg and ref.combined_avg > 0:
        profit = (sell_price - ref.combined_avg) * quantity
        percent = (sell_price - ref.combined_avg) / ref.combined_avg * 100
        results["based_on_combined_avg"] = ExpectedProfit(
            amount=round(profit, 2),
            percent=round(percent, 2),
        )

    return results

매수/매도 API

시뮬레이션 (Dry-run) 모드

# app/routers/trading.py

@router.post("/api/buy", response_model=OrderSimulationResponse)
async def buy_order(
    data: BuyOrderRequest,
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(get_authenticated_user),
):
    """매수 주문

    dry_run=True: 시뮬레이션 (기본값)
    dry_run=False: 실제 주문 실행
    """
    kis_client = KISClient()
    portfolio_service = MergedPortfolioService(db)
    price_service = TradingPriceService()

    ticker = data.ticker.upper()

    # 1. KIS 보유 정보 조회
    kis_info = await get_kis_holding_for_ticker(
        kis_client, ticker, data.market_type
    )

    # 2. 현재가 조회
    current_price = await _get_current_price(
        kis_client, ticker, data.market_type
    )

    # 3. 참조 평단가 조회 (KIS + 수동 잔고 통합)
    ref = await portfolio_service.get_reference_prices(
        current_user.id, ticker, data.market_type,
        kis_holdings=kis_info if kis_info.get("quantity", 0) > 0 else None,
    )

    # 4. 매수 가격 계산 (선택한 전략에 따라)
    try:
        result = price_service.calculate_buy_price(
            reference_prices=ref,
            current_price=current_price,
            strategy=data.price_strategy,
            discount_percent=data.discount_percent,
            manual_price=data.manual_price,
        )
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))

    # 5. 시뮬레이션 모드면 결과만 반환
    if data.dry_run:
        return OrderSimulationResponse(
            status="simulated",
            order_price=result.price,
            price_source=result.price_source,
            current_price=current_price,
            reference_prices=ReferencePricesResponse(**ref.to_dict()),
        )

    # 6. 실제 주문 실행
    if data.market_type == MarketType.KR:
        order_result = await kis_client.order_korea_stock(
            stock_code=ticker,
            order_type="buy",
            quantity=data.quantity,
            price=int(result.price),
        )
    else:
        # 해외주식 주문...
        pass

    return OrderSimulationResponse(
        status="executed",
        order_price=result.price,
        price_source=result.price_source,
        order_result=order_result,
    )

매도 수량 검증

def validate_sell_quantity(
    self,
    kis_quantity: int,
    requested_quantity: int,
) -> tuple[bool, str | None]:
    """매도 수량 검증 (KIS 보유분 내에서만 매도 가능)

    토스는 API가 없으므로 KIS 보유분만 매도 가능
    """
    if requested_quantity <= 0:
        return False, "매도 수량은 0보다 커야 한다."

    if kis_quantity <= 0:
        return False, "KIS 보유분이 없어 매도할 수 없다."

    if requested_quantity > kis_quantity:
        return False, f"KIS 보유 수량({kis_quantity}주)을 초과할 수 없다."

    return True, None

토스 알림 서비스

매수/매도 추천 알림

토스에 보유 중인 종목에 대해 AI 분석 결과를 텔레그램으로 알림:

# app/services/toss_notification_service.py

@dataclass
class TossNotificationData:
    """토스 알림 데이터"""
    ticker: str
    name: str
    current_price: float
    toss_quantity: int
    toss_avg_price: float
    kis_quantity: int | None = None
    kis_avg_price: float | None = None
    recommended_price: float = 0.0
    recommended_quantity: int = 1
    expected_profit: float = 0.0
    profit_percent: float = 0.0
    currency: str = "원"
    market_type: str = "국내주식"


class TossNotificationService:
    """토스 보유 종목 알림 서비스"""

    async def should_notify_toss(
        self,
        user_id: int,
        ticker: str,
        market_type: MarketType,
        kis_holdings: dict | None = None,
    ) -> tuple[bool, ReferencePrices | None]:
        """토스 알림을 보내야 하는지 확인"""
        ref = await self.portfolio_service.get_reference_prices(
            user_id, ticker, market_type, kis_holdings
        )

        # 토스 보유분이 있으면 알림 대상
        if ref.toss_quantity > 0:
            return True, ref

        return False, None

    async def notify_buy_recommendation(
        self,
        data: TossNotificationData,
    ) -> bool:
        """토스 매수 추천 알림 발송"""
        if data.toss_quantity <= 0:
            return False

        notifier = get_trade_notifier()
        return await notifier.notify_toss_buy_recommendation(
            symbol=data.ticker,
            korean_name=data.name,
            current_price=data.current_price,
            toss_quantity=data.toss_quantity,
            toss_avg_price=data.toss_avg_price,
            kis_quantity=data.kis_quantity,
            kis_avg_price=data.kis_avg_price,
            recommended_price=data.recommended_price,
            recommended_quantity=data.recommended_quantity,
            currency=data.currency,
            market_type=data.market_type,
        )

AI 분석 결과 처리

async def process_analysis_result(
    self,
    user_id: int,
    ticker: str,
    name: str,
    market_type: MarketType,
    decision: str,  # buy/sell/hold
    current_price: float,
    recommended_buy_price: float | None = None,
    recommended_sell_price: float | None = None,
    recommended_quantity: int = 1,
    kis_holdings: dict | None = None,
) -> bool:
    """AI 분석 결과를 처리하여 토스 알림 발송"""

    # hold면 알림 안 함
    if decision.lower() == "hold":
        return False

    # 토스 보유 확인
    should_notify, ref = await self.should_notify_toss(
        user_id, ticker, market_type, kis_holdings
    )

    if not should_notify or not ref:
        return False

    # 알림 데이터 구성
    data = TossNotificationData(
        ticker=ticker,
        name=name,
        current_price=current_price,
        toss_quantity=ref.toss_quantity,
        toss_avg_price=ref.toss_avg or 0,
        kis_quantity=ref.kis_quantity if ref.kis_quantity > 0 else None,
        kis_avg_price=ref.kis_avg if ref.kis_avg else None,
        recommended_quantity=recommended_quantity,
        currency="$" if market_type == MarketType.US else "원",
        market_type="해외주식" if market_type == MarketType.US else "국내주식",
    )

    # 매수 추천
    if decision.lower() == "buy" and recommended_buy_price:
        data.recommended_price = recommended_buy_price
        return await self.notify_buy_recommendation(data)

    # 매도 추천
    elif decision.lower() == "sell" and recommended_sell_price:
        data.recommended_price = recommended_sell_price

        # 예상 수익 계산 (토스 평단가 기준)
        if ref.toss_avg and ref.toss_avg > 0:
            data.profit_percent = (
                (recommended_sell_price - ref.toss_avg)
                / ref.toss_avg * 100
            )
            data.expected_profit = (
                (recommended_sell_price - ref.toss_avg)
                * recommended_quantity
            )

        return await self.notify_sell_recommendation(data)

    return False

웹 대시보드

수동 잔고 관리 UI

수동 잔고 대시보드

수동 잔고 관리 대시보드

<!-- app/templates/manual_holdings_dashboard.html -->

<div class="container py-4">
    <h2 class="mb-3">
        <i class="bi bi-wallet2 text-primary"></i> 수동 잔고 관리
    </h2>
    <p class="text-muted">
        토스 증권 등 외부 브로커의 보유 종목을 수동으로 등록하여
        통합 포트폴리오를 관리한다.
    </p>

    <!-- 요약 카드 -->
    <div class="row mb-4">
        <div class="col-md-4">
            <div class="card">
                <div class="card-body text-center">
                    <h5 class="text-muted">등록된 브로커 계좌</h5>
                    <h3 id="account-count" class="fw-bold">-</h3>
                </div>
            </div>
        </div>
        <div class="col-md-4">
            <div class="card">
                <div class="card-body text-center">
                    <h5 class="text-muted">수동 등록 종목</h5>
                    <h3 id="holding-count" class="fw-bold">-</h3>
                </div>
            </div>
        </div>
        <div class="col-md-4">
            <div class="card">
                <div class="card-body text-center">
                    <h5 class="text-muted">시장별 종목</h5>
                    <h3 id="market-summary" class="fw-bold">-</h3>
                </div>
            </div>
        </div>
    </div>

    <!-- 브로커 계좌 관리 -->
    <div class="card">
        <div class="card-header d-flex justify-content-between">
            <span><i class="bi bi-bank"></i> 브로커 계좌</span>
            <button class="btn btn-sm btn-primary" onclick="showAddAccountModal()">
                <i class="bi bi-plus"></i> 계좌 추가
            </button>
        </div>
        <div class="card-body">
            <div id="accounts-list" class="row">
                <!-- 동적으로 계좌 카드 렌더링 -->
            </div>
        </div>
    </div>

    <!-- 수동 보유 종목 테이블 -->
    <div class="card">
        <div class="card-header d-flex justify-content-between">
            <span><i class="bi bi-list-ul"></i> 수동 등록 보유 종목</span>
            <div>
                <select id="market-filter" class="form-select form-select-sm">
                    <option value="">전체 시장</option>
                    <option value="KR">국내주식</option>
                    <option value="US">해외주식</option>
                </select>
                <button class="btn btn-sm btn-success" onclick="showAddHoldingModal()">
                    <i class="bi bi-plus"></i> 종목 추가
                </button>
            </div>
        </div>
        <div class="card-body">
            <table class="table table-hover">
                <thead>
                    <tr>
                        <th>종목</th>
                        <th>브로커</th>
                        <th class="text-end">수량</th>
                        <th class="text-end">평단가</th>
                        <th class="text-end">평가금액</th>
                        <th class="text-center">시장</th>
                        <th class="text-center">관리</th>
                    </tr>
                </thead>
                <tbody id="holdings-list">
                    <!-- 동적으로 보유 종목 렌더링 -->
                </tbody>
            </table>
        </div>
    </div>
</div>

브로커 배지 스타일

.broker-badge {
    font-size: 0.75rem;
    padding: 0.25rem 0.5rem;
}
.broker-toss {
    background-color: #0064FF;  /* 토스 브랜드 컬러 */
    color: white;
}
.broker-kis {
    background-color: #FF6B00;  /* 한투 브랜드 컬러 */
    color: white;
}
.broker-upbit {
    background-color: #093687;  /* 업비트 브랜드 컬러 */
    color: white;
}

JavaScript 구현

// 보유 종목 렌더링
function renderHoldings() {
    const tbody = document.getElementById('holdings-list');

    tbody.innerHTML = holdings.map(h => {
        const evaluation = h.quantity * h.avg_price;
        const currency = h.market_type === 'US' ? '$' : '원';

        return `
            <tr>
                <td>
                    <strong>${h.display_name || h.ticker}</strong>
                    ${h.display_name ? `<br><small class="text-muted">${h.ticker}</small>` : ''}
                </td>
                <td>
                    <span class="badge broker-${h.broker_type}">
                        ${getBrokerName(h.broker_type)}
                    </span>
                </td>
                <td class="text-end">${h.quantity.toLocaleString()}</td>
                <td class="text-end">${formatPrice(h.avg_price, h.market_type)}</td>
                <td class="text-end">${formatPrice(evaluation, h.market_type)}</td>
                <td class="text-center">
                    <span class="badge ${h.market_type === 'KR' ? 'bg-primary' : 'bg-success'}">
                        ${h.market_type === 'KR' ? '국내' : '해외'}
                    </span>
                </td>
                <td class="text-center">
                    <button class="btn btn-sm btn-outline-primary"
                            onclick="showEditHoldingModal(${h.id})">
                        <i class="bi bi-pencil"></i>
                    </button>
                </td>
            </tr>
        `;
    }).join('');
}

// 브로커명 변환
function getBrokerName(type) {
    const names = { toss: '토스', kis: '한투', upbit: '업비트' };
    return names[type] || type;
}

기존 대시보드 통합

KIS 트레이딩 대시보드에 브로커 표시 추가

<!-- 종목 행에 브로커 배지 추가 -->
<td>
    <strong>${stock.name}</strong>
    <div class="mt-1">
        <!-- KIS 보유분 -->
        {% if stock.kis_quantity > 0 %}
        <span class="badge broker-kis me-1">
            한투 ${stock.kis_quantity}주
        </span>
        {% endif %}

        <!-- 토스 보유분 -->
        {% if stock.toss_quantity > 0 %}
        <span class="badge broker-toss">
            토스 ${stock.toss_quantity}주
        </span>
        {% endif %}
    </div>
</td>

<!-- 통합 평단가 표시 -->
<td class="text-end">
    <div>${formatPrice(stock.combined_avg_price)}</div>
    {% if stock.kis_quantity > 0 and stock.toss_quantity > 0 %}
    <small class="text-muted">
        한투: ${formatPrice(stock.kis_avg_price)}
    </small>
    {% endif %}
</td>

테스트

단위 테스트

# tests/test_manual_holdings_service.py

@pytest.mark.asyncio
async def test_calculate_combined_avg():
    """가중 평균 평단가 계산 테스트"""
    from app.services.merged_portfolio_service import (
        MergedPortfolioService, HoldingInfo
    )

    holdings = [
        HoldingInfo(broker="kis", quantity=50, avg_price=68200),
        HoldingInfo(broker="toss", quantity=30, avg_price=71000),
    ]

    result = MergedPortfolioService.calculate_combined_avg(holdings)

    # 기대값: (50*68200 + 30*71000) / 80 = 69,250
    assert result == pytest.approx(69250, rel=1e-2)


@pytest.mark.asyncio
async def test_create_holding(db_session, test_user):
    """수동 잔고 생성 테스트"""
    service = ManualHoldingsService(db_session)

    # 계좌 생성
    account = await service.broker_service.create(test_user.id, {
        "broker_type": "toss",
        "account_name": "토스 계좌",
    })

    # 보유 종목 등록
    holding = await service.create_holding(
        user_id=test_user.id,
        data={
            "broker_type": "toss",
            "account_name": "토스 계좌",
            "ticker": "005930",
            "market_type": "KR",
            "quantity": 30,
            "avg_price": 71000,
        }
    )

    assert holding.ticker == "005930"
    assert holding.quantity == 30
    assert holding.avg_price == 71000


@pytest.mark.asyncio
async def test_sell_quantity_validation():
    """매도 수량 검증 테스트"""
    from app.services.trading_price_service import TradingPriceService

    service = TradingPriceService()

    # KIS 50주, 요청 30주 → OK
    valid, msg = service.validate_sell_quantity(50, 30)
    assert valid is True

    # KIS 50주, 요청 60주 → 초과
    valid, msg = service.validate_sell_quantity(50, 60)
    assert valid is False
    assert "초과" in msg

    # KIS 0주 → 매도 불가
    valid, msg = service.validate_sell_quantity(0, 10)
    assert valid is False
    assert "보유분이 없어" in msg

통합 테스트

# tests/test_trading_integration.py

@pytest.mark.asyncio
async def test_merged_portfolio_with_manual_holdings(
    db_session, test_user, mock_kis_client
):
    """통합 포트폴리오 테스트 (KIS + 수동 잔고)"""

    # 1. 수동 잔고 등록
    manual_service = ManualHoldingsService(db_session)
    await manual_service.create_holding(
        user_id=test_user.id,
        data={
            "broker_type": "toss",
            "ticker": "005930",
            "market_type": "KR",
            "quantity": 30,
            "avg_price": 71000,
        }
    )

    # 2. 통합 포트폴리오 조회
    portfolio_service = MergedPortfolioService(db_session)
    holdings = await portfolio_service.get_merged_portfolio_domestic(
        test_user.id, mock_kis_client
    )

    # 3. 삼성전자 확인
    samsung = next((h for h in holdings if h.ticker == "005930"), None)
    assert samsung is not None

    # KIS 50주 + 토스 30주 = 80주
    assert samsung.total_quantity == 80
    assert samsung.kis_quantity == 50
    assert samsung.toss_quantity == 30

    # 통합 평단가 계산 확인
    expected_avg = (50 * 68200 + 30 * 71000) / 80
    assert samsung.combined_avg_price == pytest.approx(expected_avg, rel=1e-2)

마이그레이션

# alembic/versions/xxx_add_manual_holdings.py

def upgrade() -> None:
    # 브로커 타입 Enum 생성
    op.execute("CREATE TYPE broker_type AS ENUM ('kis', 'toss', 'upbit')")
    op.execute("CREATE TYPE market_type AS ENUM ('KR', 'US', 'CRYPTO')")

    # 브로커 계좌 테이블
    op.create_table(
        'broker_accounts',
        sa.Column('id', sa.BigInteger(), primary_key=True),
        sa.Column('user_id', sa.BigInteger(),
                  sa.ForeignKey('users.id', ondelete='CASCADE')),
        sa.Column('broker_type',
                  postgresql.ENUM('kis', 'toss', 'upbit',
                                  name='broker_type', create_type=False)),
        sa.Column('account_name', sa.Text(), nullable=False,
                  server_default='기본 계좌'),
        sa.Column('is_mock', sa.Boolean(), server_default='false'),
        sa.Column('is_active', sa.Boolean(), server_default='true'),
        sa.Column('created_at', sa.TIMESTAMP(timezone=True),
                  server_default=sa.func.now()),
        sa.Column('updated_at', sa.TIMESTAMP(timezone=True),
                  server_default=sa.func.now()),
        sa.UniqueConstraint('user_id', 'broker_type', 'account_name',
                           name='uq_broker_account'),
    )

    # 수동 보유 종목 테이블
    op.create_table(
        'manual_holdings',
        sa.Column('id', sa.BigInteger(), primary_key=True),
        sa.Column('broker_account_id', sa.BigInteger(),
                  sa.ForeignKey('broker_accounts.id', ondelete='CASCADE')),
        sa.Column('ticker', sa.Text(), nullable=False),
        sa.Column('market_type',
                  postgresql.ENUM('KR', 'US', 'CRYPTO',
                                  name='market_type', create_type=False)),
        sa.Column('quantity', sa.Numeric(18, 8), nullable=False),
        sa.Column('avg_price', sa.Numeric(18, 8), nullable=False),
        sa.Column('display_name', sa.Text(), nullable=True),
        sa.Column('created_at', sa.TIMESTAMP(timezone=True),
                  server_default=sa.func.now()),
        sa.Column('updated_at', sa.TIMESTAMP(timezone=True),
                  server_default=sa.func.now()),
        sa.UniqueConstraint('broker_account_id', 'ticker', 'market_type',
                           name='uq_holding_ticker'),
    )

    # 인덱스 생성
    op.create_index('ix_broker_accounts_user_id', 'broker_accounts', ['user_id'])
    op.create_index('ix_manual_holdings_ticker', 'manual_holdings', ['ticker'])


def downgrade() -> None:
    op.drop_table('manual_holdings')
    op.drop_table('broker_accounts')
    op.execute('DROP TYPE market_type')
    op.execute('DROP TYPE broker_type')

실전 사용 예시

1. 토스 잔고 등록

# 1. 수동 잔고 관리 페이지 접속
https://your-domain.com/manual-holdings/

# 2. 토스증권 계좌 추가
# - 브로커: 토스증권
# - 계좌 이름: 토스 메인

# 3. 보유 종목 등록
# - 종목코드: 005930
# - 종목명: 삼성전자
# - 수량: 30주
# - 평단가: 71,000원

2. 통합 포트폴리오 확인

# 국내주식 트레이딩 페이지 접속
https://your-domain.com/kis-domestic-trading/

# 삼성전자 확인:
# - 한투: 50주 @ 68,200원
# - 토스: 30주 @ 71,000원 (뱃지 표시)
# - 통합 평단가: 69,250원
# - 총 보유: 80주

3. 토스 기준 매수 전략

매수 전략: "최저 평단가 -3%"

참조 평단가:
- 한투: 68,200원
- 토스: 71,000원
- 최저: 68,200원 (한투)

계산된 매수가: 68,200 × 0.97 = 66,154원
→ 한투에서 66,154원에 지정가 매수 주문

4. Telegram 알림

  **국내주식 AI 분석 완료**

종목: 삼성전자 (005930)
결정: BUY
신뢰도: 75%

  **토스 보유 알림**
토스 보유: 30주 @ 71,000원
한투 보유: 50주 @ 68,200원
통합 평단가: 69,250원

  추천 매수가: 66,154원 (최저 평단가 -3%)

마치며

배운 교훈

"여러 브로커를 통합하면 투자 판단이 달라진다"

처음에는 "그냥 한투 잔고만 보면 되지"라고 생각했습니다.

하지만 실제로는:

평단가가 다름: 토스에서 고점에 샀다면 평단가가 높음
물타기 전략 변화: 통합 평단가 기준으로 물타기해야 정확함
매도 타이밍 달라짐: 토스 평단가 기준으로는 이미 수익권

시스템의 강점

1. 유연한 수동 등록:

토스, 한투, 업비트 등 다양한 브로커 지원
종목별 별칭 관리로 편리한 입력
대량 등록 지원

2. 정확한 통합 분석:

가중 평균으로 정확한 평단가 계산
브로커별 보유 현황 한눈에 확인
AI 분석에 통합 정보 반영

3. 다양한 가격 전략:

현재가, 평단가 기반 등 8가지 전략
시뮬레이션 모드로 안전한 테스트
브로커별 예상 수익 계산

4. 실시간 알림:

토스 보유 종목 분석 시 자동 알림
매수/매도 추천 및 예상 수익 제공

다음 단계

이제 우리의 자동매매 시스템은:

✅ 데이터 수집 (한투/Upbit/yfinance)
✅ AI 분석 (Gemini)
✅ DB 저장 및 정규화
✅ 암호화폐 웹 대시보드
✅ 모니터링 (Grafana Stack)
✅ 프로덕션 배포 (HTTPS + 24시간)
✅ JWT 인증 + RBAC
✅ 국내/해외 주식 자동 매매
✅ 다중 브로커 통합 포트폴리오 ← 완성!

추가로 고려할 수 있는 기능:

토스 잔고 자동 동기화 (스크래핑)
포트폴리오 리밸런싱 제안
세금 계산 (양도소득세)
백테스팅 시스템

참고 자료:

KIS 국내/해외 주식 자동 매매 시스템 구축하기: Celery + AI 분석 기반 스마트 트레이딩

kwanghyun — Sun, 30 Nov 2025 15:34:17 +0900

KIS 자동 매매 시스템

이 글은 AI 기반 자동매매 시스템 시리즈의 9편이다.

전체 시리즈:

1편: 한투 API로 실시간 주식 데이터 수집하기

2편: yfinance로 애플·테슬라 분석하기

3편: Upbit으로 비트코인 24시간 분석하기

4편: AI 분석 결과 DB에 저장하기

5편: Upbit 웹 트레이딩 대시보드 구축하기

6편: 실전 운영을 위한 모니터링 시스템 구축

7편: 라즈베리파이 홈서버에 자동 HTTPS로 안전하게 배포하기

8편: JWT 인증 시스템으로 안전한 웹 애플리케이션 구축하기

9편: KIS 국내/해외 주식 자동 매매 시스템 구축하기 ← 현재 글

들어가며

지금까지의 여정

우리는 지금까지:

✅ 한투/yfinance/Upbit API로 데이터 수집
✅ AI 분석 자동화 (Gemini)
✅ DB 저장 및 정규화
✅ 웹 대시보드 구축 (암호화폐)
✅ Grafana 관찰성 스택으로 모니터링
✅ 라즈베리파이에 HTTPS 배포
✅ JWT 인증 + RBAC

까지 완성했습니다.

새로운 과제: 주식 자동 매매

이제 암호화폐 자동 매매 시스템을 주식으로 확장한다.!

현재 상태:

# Upbit 암호화폐: 자동 매매 가능 ✅
https://your-domain.com/upbit-trading/

# KIS 주식: 조회만 가능 ❌
# 매수/매도 자동화 없음

목표:

# 국내 주식 자동 매매 대시보드
https://your-domain.com/kis-domestic-trading/

# 해외 주식 자동 매매 대시보드
https://your-domain.com/kis-overseas-trading/

왜 주식 자동 매매인가?

암호화폐 vs 주식 매매의 차이:

항목	암호화폐 (Upbit)	주식 (KIS)
거래 시간	24/7	국내 9:00-15:30, 해외 23:30-06:00
최소 거래 단위	금액 기반 (5,000원~)	주 단위 (1주~)
주문 방식	즉시 체결 위주	지정가 주문 가능
API 복잡도	단순	매우 복잡 (국내/해외 별도)
시장 특성	변동성 높음	상대적 안정

주식 자동 매매의 핵심 과제:

분할 매수/매도: 목표 가격대에 분산 주문
종목별 설정: 종목마다 다른 매수 수량/금액
비동기 처리: 여러 종목 동시 분석 및 주문
진행 상황 추적: 긴 작업의 실시간 모니터링

시스템 아키텍처

KIS 자동 매매 아키텍처

Celery 기반 비동기 자동 매매 시스템 구조

전체 구조

사용자
  ↓
웹 대시보드 (FastAPI + Jinja2)
  ├─ /kis-domestic-trading/   (국내주식)
  └─ /kis-overseas-trading/   (해외주식)
  ↓
FastAPI 라우터
  ├─ 보유 주식 조회 API
  ├─ AI 분석 요청 API
  ├─ 매수/매도 주문 API
  └─ 종목별 설정 API
  ↓
Celery 비동기 태스크
  ├─ 전체 종목 분석 태스크
  ├─ 전체 종목 매수 태스크
  ├─ 전체 종목 매도 태스크
  ├─ 종목별 자동 실행 태스크
  │   (분석 → 매수 → 매도)
  └─ 개별 종목 태스크
      ├─ 분석
      ├─ 매수
      └─ 매도
  ↓
KIS API + AI 분석
  ├─ KISClient (한국투자증권 API)
  ├─ KISAnalyzer (국내주식 분석)
  └─ YahooAnalyzer (해외주식 분석)
  ↓
PostgreSQL + Redis
  ├─ StockAnalysisResult (분석 결과)
  └─ SymbolTradeSettings (종목별 설정)

핵심 컴포넌트

1. 웹 대시보드:

보유 주식 현황 표시
예수금/평가금액 표시
자동 매매 버튼 (분석/매수/매도)
진행 상황 실시간 표시
종목별 설정 관리

2. Celery 태스크:

백그라운드에서 오래 걸리는 작업 처리
진행 상황 실시간 업데이트
작업 실패 시 자동 재시도

3. 종목별 설정:

매수 수량 설정
주문할 가격대 수 설정 (1~4개)
활성화/비활성화

데이터베이스 설계

종목별 거래 설정 테이블

종목 설정 ERD

종목별 거래 설정 ERD

# app/models/symbol_trade_settings.py

class SymbolTradeSettings(Base):
    """종목별 거래 설정 테이블"""

    __tablename__ = "symbol_trade_settings"
    __table_args__ = (
        UniqueConstraint("user_id", "symbol", name="uq_user_symbol"),
    )

    id: Mapped[int] = mapped_column(BigInteger, primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True
    )
    symbol: Mapped[str] = mapped_column(Text, nullable=False, index=True)
    instrument_type: Mapped[InstrumentType] = mapped_column(
        Enum(InstrumentType), nullable=False
    )

    # 핵심 설정: 주문당 매수 수량
    buy_quantity_per_order: Mapped[float] = mapped_column(
        Numeric(18, 8), nullable=False
    )

    # 주문할 가격대 수 (1~4)
    # 1: appropriate_buy_min만
    # 2: appropriate_buy_min, appropriate_buy_max
    # 3: + buy_hope_min
    # 4: 전체 4개 가격대 (기본값)
    buy_price_levels: Mapped[int] = mapped_column(default=4, nullable=False)

    # 해외주식 거래소 코드 (NASD, NYSE 등)
    exchange_code: Mapped[str | None] = mapped_column(Text, nullable=True)

    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
    note: Mapped[str | None] = mapped_column(Text, nullable=True)

설계 포인트:

사용자별 종목 설정: user_id + symbol 유니크 제약
유연한 가격대 설정: buy_price_levels로 1~4개 가격대 선택
거래소 구분: 해외주식은 exchange_code로 NASDAQ/NYSE 구분

사용자 기본 설정 테이블

class UserTradeDefaults(Base):
    """사용자별 기본 거래 설정"""

    __tablename__ = "user_trade_defaults"

    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id"), unique=True, index=True
    )

    # 코인 기본 매수 금액 (KRW)
    crypto_default_buy_amount: Mapped[float] = mapped_column(
        Numeric(18, 2), default=10000
    )n    const data = await response.json();

    if (data.success) {
        // 진행 상황 폴링 시작
        pollTaskStatus(data.task_id, 'analyze');
    }
}

// 진행 상황 폴링
async function pollTaskStatus(taskId, type) {
    const progressBar = document.getElementById(`${type}-progress-bar`);
    const statusText = document.getElementById(`${type}-status`);

    const poll = async () => {
        const response = await fetch(`/kis-domestic-trading/api/analyze-task/${taskId}`);
        const result = await response.json();

        if (result.state === 'PROGRESS') {
            // 진행 상황 업데이트
            const progress = result.progress;
            progressBar.style.width = `${progress.percentage}%`;
            progressBar.textContent = `${progress.percentage}%`;
            statusText.textContent = progress.status;

            // 계속 폴링
            setTimeout(poll, 1000);
        } else if (result.state === 'SUCCESS') {
            // 완료
            progressBar.style.width = '100%';
            statusText.textContent = result.result.message;
            showAlert('success', '분석이 완료되었습니다.');
            loadMyStocks();  // 데이터 새로고침
        } else if (result.state === 'FAILURE') {
            // 실패
            showAlert('danger', `오류: ${result.error}`);
        }
    };

    poll();
}

진행 상황 표시

실시간 진행 상황 표시 UI

매수/매도 로직 구현

AI 분석 기반 분할 매수

매수 로직 플로우

AI 분석 기반 분할 매수 플로우

# app/services/kis_trading_service.py

async def process_kis_domestic_buy_orders_with_analysis(
    kis_client: KISClient,
    symbol: str,
    current_price: float,
    avg_buy_price: float
) -> Dict[str, Any]:
    """분석 결과 기반 국내 주식 분할 매수"""

    # 1. 기본 조건: 현재가가 평균 매수가보다 1% 낮아야 함
    if avg_buy_price > 0:
        target_price = avg_buy_price * 0.99
        if current_price >= target_price:
            return {
                'success': False,
                'message': f"1% 매수 조건 미충족: 현재가 {current_price} >= 목표가 {target_price}"
            }

    # 2. DB에서 최신 AI 분석 결과 조회
    analysis = await service.get_latest_analysis_by_symbol(symbol)
    if not analysis:
        return {'success': False, 'message': "분석 결과 없음"}

    # 3. 종목 설정 확인
    settings = await settings_service.get_by_symbol(symbol)
    if not settings or not settings.is_active:
        return {'success': False, 'message': "종목 설정 없음 - 매수 건너뜀"}

    # 4. AI가 제안한 매수 가격대 추출
    all_buy_prices = []
    if analysis.appropriate_buy_min:
        all_buy_prices.append(("적정매수(하한)", analysis.appropriate_buy_min))
    if analysis.appropriate_buy_max:
        all_buy_prices.append(("적정매수(상한)", analysis.appropriate_buy_max))
    if analysis.buy_hope_min:
        all_buy_prices.append(("희망매수(하한)", analysis.buy_hope_min))
    if analysis.buy_hope_max:
        all_buy_prices.append(("희망매수(상한)", analysis.buy_hope_max))

    # 5. 설정된 가격대 수만큼 선택 (1~4개)
    buy_prices = all_buy_prices[:settings.buy_price_levels]

    # 6. 조건에 맞는 가격 필터링
    # - 평균 매수가의 99%보다 낮고
    # - 현재가보다 낮은 가격
    threshold_price = avg_buy_price * 0.99 if avg_buy_price > 0 else float('inf')
    valid_prices = [
        (name, price) for name, price in buy_prices
        if price < threshold_price and price < current_price
    ]

    if not valid_prices:
        return {'success': False, 'message': "조건에 맞는 매수 가격 없음"}

    # 7. 분할 매수 주문 실행
    quantity = int(settings.buy_quantity_per_order)
    success_count = 0

    for name, price in valid_prices:
        result = await kis_client.order_korea_stock(
            symbol=symbol,
            order_type="buy",
            quantity=quantity,
            price=int(price)
        )

        if result and result.get('rt_cd') == '0':
            success_count += 1

        await asyncio.sleep(0.2)  # API 호출 간격

    return {
        'success': success_count > 0,
        'message': f"{success_count}개 주문 성공 (설정: {settings.buy_price_levels}개 가격대)"
    }

매수 가격대 설정 이해

AI 분석 결과에서 4가지 매수 가격대를 제공한다.:

가격대	의미	우선순위
`appropriate_buy_min`	적정 매수가 하한	1 (최우선)
`appropriate_buy_max`	적정 매수가 상한	2
`buy_hope_min`	희망 매수가 하한	3
`buy_hope_max`	희망 매수가 상한	4

buy_price_levels 설정 예시:

buy_price_levels = 2인 경우:
→ appropriate_buy_min, appropriate_buy_max 두 가격에만 주문

buy_price_levels = 4인 경우 (기본값):
→ 4개 가격대 모두에 주문

AI 분석 기반 분할 매도

async def process_kis_domestic_sell_orders_with_analysis(
    kis_client: KISClient,
    symbol: str,
    current_price: float,
    avg_buy_price: float,
    balance_qty: int
) -> Dict[str, Any]:
    """분석 결과 기반 국내 주식 분할 매도"""

    # 1. AI 분석 결과 조회
    analysis = await service.get_latest_analysis_by_symbol(symbol)
    if not analysis:
        return {'success': False, 'message': "분석 결과 없음"}

    # 2. AI가 제안한 매도 가격대 추출
    sell_prices = []
    if analysis.appropriate_sell_min:
        sell_prices.append(analysis.appropriate_sell_min)
    if analysis.appropriate_sell_max:
        sell_prices.append(analysis.appropriate_sell_max)
    if analysis.sell_target_min:
        sell_prices.append(analysis.sell_target_min)
    if analysis.sell_target_max:
        sell_prices.append(analysis.sell_target_max)

    # 3. 매도 조건 필터링
    # - 평균 매수가의 101% 이상 (최소 1% 수익)
    # - 현재가 이상
    min_sell_price = avg_buy_price * 1.01
    valid_prices = [
        p for p in sell_prices
        if p >= min_sell_price and p >= current_price
    ]
    valid_prices.sort()

    # 4. 조건 미충족 시 현재가로 전량 매도 시도
    if not valid_prices:
        if current_price >= min_sell_price:
            # 이미 목표 수익 달성 → 전량 매도
            result = await kis_client.order_korea_stock(
                symbol=symbol,
                order_type="sell",
                quantity=balance_qty,
                price=int(current_price)
            )
            if result and result.get('rt_cd') == '0':
                return {'success': True, 'message': "목표가 도달로 전량 매도"}
        return {'success': False, 'message': "매도 조건 미충족"}

    # 5. 분할 매도 주문 실행
    split_count = len(valid_prices)
    qty_per_order = balance_qty // split_count

    success_count = 0
    remaining_qty = balance_qty

    for i, price in enumerate(valid_prices):
        is_last = (i == len(valid_prices) - 1)
        qty = remaining_qty if is_last else qty_per_order

        if qty < 1:
            continue

        result = await kis_client.order_korea_stock(
            symbol=symbol,
            order_type="sell",
            quantity=qty,
            price=int(price)
        )

        if result and result.get('rt_cd') == '0':
            success_count += 1
            remaining_qty -= qty

        await asyncio.sleep(0.2)

    return {
        'success': success_count > 0,
        'message': f"{success_count}건 분할 매도 주문 완료"
    }

종목별 자동 실행 (All-in-One)

분석 → 매수 → 매도 순차 실행

@shared_task(name="kis.run_per_domestic_stock_automation", bind=True)
def run_per_domestic_stock_automation(self) -> dict:
    """국내 주식 종목별 자동 실행 (분석 → 매수 → 매도)"""

    async def _run() -> dict:
        kis = KISClient()
        analyzer = KISAnalyzer()

        my_stocks = await kis.fetch_my_stocks()
        results = []

        for index, stock in enumerate(my_stocks, 1):
            code = stock.get('pdno')
            name = stock.get('prdt_name')

            stock_steps = []

            # 1단계: AI 분석
            self.update_state(
                state='PROGRESS',
                meta={'status': f'{name} 분석 중...'}
            )
            try:
                await analyzer.analyze_stock_json(name)
                stock_steps.append({
                    'step': '분석',
                    'result': {'success': True}
                })
            except Exception as e:
                stock_steps.append({
                    'step': '분석',
                    'result': {'success': False, 'error': str(e)}
                })
                # 분석 실패 시 매수/매도 건너뜀
                results.append({'name': name, 'steps': stock_steps})
                continue

            # 2단계: 매수 주문
            self.update_state(
                state='PROGRESS',
                meta={'status': f'{name} 매수 주문 중...'}
            )
            try:
                buy_result = await process_kis_domestic_buy_orders_with_analysis(
                    kis, code, current_price, avg_price
                )
                stock_steps.append({'step': '매수', 'result': buy_result})
            except Exception as e:
                stock_steps.append({
                    'step': '매수',
                    'result': {'success': False, 'error': str(e)}
                })

            # 매수 후 잔고/평단가 최신화
            latest_holdings = await kis.fetch_my_stocks()
            latest = next((s for s in latest_holdings if s.get('pdno') == code), None)
            if latest:
                refreshed_qty = int(latest.get('hldg_qty'))
                refreshed_avg_price = float(latest.get('pchs_avg_pric'))
                refreshed_current_price = float(latest.get('prpr'))

            # 3단계: 매도 주문
            self.update_state(
                state='PROGRESS',
                meta={'status': f'{name} 매도 주문 중...'}
            )
            try:
                sell_result = await process_kis_domestic_sell_orders_with_analysis(
                    kis, code, refreshed_current_price,
                    refreshed_avg_price, refreshed_qty
                )
                stock_steps.append({'step': '매도', 'result': sell_result})
            except Exception as e:
                stock_steps.append({
                    'step': '매도',
                    'result': {'success': False, 'error': str(e)}
                })

            results.append({'name': name, 'code': code, 'steps': stock_steps})

        return {
            'status': 'completed',
            'message': '종목별 자동 실행 완료',
            'results': results
        }

    return asyncio.run(_run())

핵심 포인트:

순차 실행: 분석 → 매수 → 매도 순서 보장
잔고 최신화: 매수 후 평단가/수량 재조회하여 매도에 반영
단계별 결과: 각 단계의 성공/실패 기록

웹 대시보드 구현

국내주식 대시보드 UI

국내주식 대시보드

KIS 국내주식 자동 매매 대시보드

<!-- app/templates/kis_domestic_trading_dashboard.html -->

<div class="container py-4">
    <!-- 자산 요약 -->
    <div class="card">
        <div class="card-body">
            <div class="row text-center">
                <div class="col-md-4">
                    <h5 class="text-muted">예수금</h5>
                    <h3 id="krw-balance" class="fw-bold">- 원</h3>
                </div>
                <div class="col-md-4">
                    <h5 class="text-muted">보유 종목 수</h5>
                    <h3 id="stock-count" class="fw-bold">- 개</h3>
                </div>
                <div class="col-md-4">
                    <h5 class="text-muted">총 평가 금액</h5>
                    <h3 id="total-evaluation" class="fw-bold">- 원</h3>
                </div>
            </div>
        </div>
    </div>

    <!-- 자동 매매 제어 -->
    <div class="card">
        <div class="card-header">
            <i class="bi bi-robot"></i> 자동 매매 제어
        </div>
        <div class="card-body">
            <div class="row g-2">
                <div class="col-md-3">
                    <button class="btn btn-primary btn-action" onclick="analyzeStocks()">
                        <i class="bi bi-search"></i> 전체 종목 AI 분석
                    </button>
                    <div id="analyze-progress" class="progress mt-2" style="display: none;">
                        <div id="analyze-progress-bar" class="progress-bar" style="width: 0%">0%</div>
                    </div>
                </div>
                <div class="col-md-3">
                    <button class="btn btn-success btn-action" onclick="executeBuyOrders()">
                        <i class="bi bi-cart-plus"></i> 자동 매수 주문
                    </button>
                    <div id="total-estimated-cost" class="mt-2 small text-success">
                        <i class="bi bi-calculator"></i>
                        <span id="estimated-cost-text"></span>
                    </div>
                </div>
                <div class="col-md-3">
                    <button class="btn btn-danger btn-action" onclick="executeSellOrders()">
                        <i class="bi bi-cart-dash"></i> 자동 매도 주문
                    </button>
                </div>
                <div class="col-md-3">
                    <button class="btn btn-warning btn-action" onclick="runPerStockAutomation()">
                        <i class="bi bi-collection-play"></i> 종목별 분석→매수→매도
                    </button>
                </div>
            </div>
        </div>
    </div>

    <!-- 보유 종목 목록 -->
    <div class="card">
        <div class="card-header d-flex justify-content-between">
            <span><i class="bi bi-list-ul"></i> 보유 종목</span>
            <button class="btn btn-sm btn-outline-primary" onclick="loadMyStocks()">
                <i class="bi bi-arrow-clockwise"></i> 새로고침
            </button>
        </div>
        <div class="card-body">
            <div class="table-responsive">
                <table class="table table-hover">
                    <thead>
                        <tr>
                            <th>종목명</th>
                            <th class="text-end">수량</th>
                            <th class="text-end">현재가</th>
                            <th class="text-end">평균 매수가</th>
                            <th class="text-end">수익률</th>
                            <th class="text-center">AI 분석</th>
                            <th class="text-center">설정</th>
                            <th class="text-center">액션</th>
                        </tr>
                    </thead>
                    <tbody id="stocks-table-body">
                        <!-- JavaScript로 동적 생성 -->
                    </tbody>
                </table>
            </div>
        </div>
    </div>
</div>

종목별 설정 모달

<!-- 종목 설정 모달 -->
<div class="modal fade" id="settingsModal" tabindex="-1">
    <div class="modal-dialog">
        <div class="modal-content">
            <div class="modal-header">
                <h5 class="modal-title">
                    <i class="bi bi-gear"></i> <span id="settings-stock-name"></span> 설정
                </h5>
            </div>
            <div class="modal-body">
                <form id="settings-form">
                    <input type="hidden" id="settings-symbol">

                    <div class="mb-3">
                        <label class="form-label">주문당 매수 수량 (주)</label>
                        <input type="number" class="form-control"
                               id="settings-quantity" min="1" step="1" required>
                        <small class="text-muted">
                            각 가격대에 이 수량만큼 주문한다.
                        </small>
                    </div>

                    <div class="mb-3">
                        <label class="form-label">주문할 가격대 수</label>
                        <select class="form-select" id="settings-price-levels">
                            <option value="1">1개 (적정매수 하한만)</option>
                            <option value="2">2개 (적정매수 하한/상한)</option>
                            <option value="3">3개 (+ 희망매수 하한)</option>
                            <option value="4" selected>4개 (전체 가격대)</option>
                        </select>
                        <small class="text-muted">
                            AI가 분석한 가격대 중 몇 개에 주문할지 선택한다.
                        </small>
                    </div>

                    <div class="mb-3">
                        <label class="form-label">메모</label>
                        <textarea class="form-control" id="settings-note" rows="2"></textarea>
                    </div>

                    <div class="form-check form-switch">
                        <input class="form-check-input" type="checkbox"
                               id="settings-active" checked>
                        <label class="form-check-label">자동 매매 활성화</label>
                    </div>
                </form>
            </div>
            <div class="modal-footer">
                <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">취소</button>
                <button type="button" class="btn btn-primary" onclick="saveSettings()">저장</button>
            </div>
        </div>
    </div>
</div>

예상 비용 계산

// 예상 매수 비용 계산
function calculateEstimatedCost(stocks) {
    let totalCost = 0;
    let configuredCount = 0;

    stocks.forEach(stock => {
        if (stock.settings_quantity && stock.settings_active) {
            const levels = stock.settings_price_levels || 4;
            // 현재가 기준으로 예상 비용 계산
            const estimatedCost = stock.current_price * stock.settings_quantity * levels;
            totalCost += estimatedCost;
            configuredCount++;
        }
    });

    if (configuredCount > 0) {
        document.getElementById('total-estimated-cost').style.display = 'block';
        document.getElementById('estimated-cost-text').textContent =
            `예상 최대 비용: ${totalCost.toLocaleString()}원 (${configuredCount}개 종목)`;
    }
}

해외주식 자동 매매

국내주식과의 차이점

항목	국내주식	해외주식
통화	KRW	USD
거래소	코스피/코스닥	NASDAQ/NYSE/AMEX
거래 시간	09:00-15:30	23:30-06:00 (미국)
소수점 거래	불가	일부 가능
API 엔드포인트	국내주식 전용	해외주식 전용

해외주식 라우터

# app/routers/kis_overseas_trading.py

router = APIRouter(prefix="/kis-overseas-trading", tags=["KIS Overseas Trading"])

@router.get("/api/my-stocks")
async def get_my_overseas_stocks(db: AsyncSession = Depends(get_db)):
    """보유 해외 주식 조회 API"""
    kis = KISClient()

    my_stocks = await kis.fetch_my_overseas_stocks()

    # 달러 예수금 조회
    margin = await kis.inquire_integrated_margin()
    usd_balance = margin.get("usd_balance", 0)

    # 분석 결과 및 설정 조회
    stock_service = StockAnalysisService(db)
    settings_service = SymbolTradeSettingsService(db)

    processed_stocks = []
    for stock in my_stocks:
        code = stock.get("ovrs_pdno")
        analysis = await stock_service.get_latest_analysis_by_symbol(code)
        settings = await settings_service.get_by_symbol(code)

        processed_stocks.append({
            "code": code,
            "name": stock.get("ovrs_item_name"),
            "quantity": float(stock.get("ovrs_cblc_qty", 0)),
            "current_price": float(stock.get("now_pric2", 0)),  # USD
            "avg_price": float(stock.get("pchs_avg_pric", 0)),
            "profit_rate": float(stock.get("evlu_pfls_rt", 0)) / 100.0,
            "analysis_decision": analysis.decision if analysis else None,
            "settings_quantity": float(settings.buy_quantity_per_order) if settings else None,
        })

    return {
        "success": True,
        "usd_balance": usd_balance,
        "stocks": processed_stocks
    }

해외주식 분석기

# 해외주식은 YahooAnalyzer 사용
async def _analyze_overseas_stock_async(symbol: str) -> Dict[str, object]:
    """단일 해외 주식 분석"""

    from app.analysis.service_analyzers import YahooAnalyzer
    analyzer = YahooAnalyzer()  # Yahoo Finance 데이터 기반

    try:
        result, _ = await analyzer.analyze_stock_json(symbol)

        # Telegram 알림
        if hasattr(result, 'decision'):
            notifier = get_trade_notifier()
            await notifier.notify_analysis_complete(
                symbol=symbol,
                korean_name=symbol,  # 해외주식은 한글명 없음
                decision=result.decision,
                confidence=result.confidence,
                market_type="해외주식",
            )

        return {"status": "completed", "symbol": symbol}
    finally:
        await analyzer.close()

Telegram 알림 연동

분석 완료 알림

# app/monitoring/trade_notifier.py

async def notify_analysis_complete(
    self,
    symbol: str,
    korean_name: str,
    decision: str,
    confidence: float,
    reasons: List[str],
    market_type: str,
):
    """AI 분석 완료 알림"""

    decision_emoji = {
        "buy": " ",
        "sell": " ",
        "hold": "⏸️"
    }.get(decision, "❓")

    message = f"""
{decision_emoji} **{market_type} AI 분석 완료**

종목: {korean_name} ({symbol})
결정: {decision.upper()}
신뢰도: {confidence}%

  근거:
{chr(10).join(f'• {r}' for r in reasons[:3])}
"""

    await self.send_telegram_message(message)

주문 체결 알림

async def notify_order_placed(
    self,
    symbol: str,
    order_type: str,  # "buy" or "sell"
    quantity: int,
    price: float,
    market_type: str,
):
    """주문 접수 알림"""

    emoji = " " if order_type == "buy" else " "
    action = "매수" if order_type == "buy" else "매도"

    message = f"""
{emoji} **{market_type} {action} 주문 접수**

종목: {symbol}
수량: {quantity:,}주
가격: {price:,.0f}원
"""

    await self.send_telegram_message(message)

테스트

단위 테스트

# tests/test_kis_trading_service.py

import pytest
from app.services.kis_trading_service import (
    process_kis_domestic_buy_orders_with_analysis
)

@pytest.mark.asyncio
async def test_buy_condition_not_met():
    """1% 매수 조건 미충족 테스트"""
    result = await process_kis_domestic_buy_orders_with_analysis(
        kis_client=mock_kis,
        symbol="005930",
        current_price=70000,  # 현재가
        avg_buy_price=70000   # 평단가 = 현재가 (조건 미충족)
    )

    assert result['success'] is False
    assert "1% 매수 조건 미충족" in result['message']

@pytest.mark.asyncio
async def test_no_settings_skip_buy():
    """종목 설정 없으면 매수 건너뜀"""
    result = await process_kis_domestic_buy_orders_with_analysis(
        kis_client=mock_kis,
        symbol="NO_SETTINGS_STOCK",
        current_price=50000,
        avg_buy_price=60000
    )

    assert result['success'] is False
    assert "종목 설정 없음" in result['message']

통합 테스트

# tests/test_kis_tasks.py

@pytest.mark.asyncio
async def test_celery_analyze_task():
    """Celery 분석 태스크 테스트"""
    from app.tasks.kis import analyze_domestic_stock_task

    result = analyze_domestic_stock_task.delay("삼성전자")

    # 태스크 완료 대기
    task_result = result.get(timeout=60)

    assert task_result['status'] == 'completed'
    assert '삼성전자' in task_result.get('name', '')

배포 및 운영

Celery 워커 실행

# 개발 환경
celery -A app.core.celery_app worker --loglevel=info

# 프로덕션 (systemd)
sudo tee /etc/systemd/system/celery-worker.service > /dev/null <<EOF
[Unit]
Description=Celery Worker
After=network.target redis.service

[Service]
Type=simple
User=autotrader
WorkingDirectory=/home/autotrader/auto_trader
ExecStart=/home/autotrader/.local/bin/uv run celery -A app.core.celery_app worker --loglevel=info
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable celery-worker
sudo systemctl start celery-worker

Flower 모니터링

# Celery 모니터링 대시보드
celery -A app.core.celery_app flower --port=5555

# 접속: http://localhost:5555

Flower 모니터링

Flower로 Celery 태스크 모니터링

실전 사용 예시

1. 종목 설정 후 자동 매매

# 1. 대시보드 접속
https://your-domain.com/kis-domestic-trading/

# 2. 삼성전자 설정
# - 매수 수량: 5주
# - 가격대: 2개 (적정매수 하한/상한)

# 3. "종목별 분석→매수→매도" 클릭
# - AI 분석 실행
# - 분석 결과 기반 분할 매수 주문
# - 수익 목표 기반 분할 매도 주문

2. 예상 결과

[삼성전자] AI 분석 완료
- 결정: BUY
- 신뢰도: 75%
- 적정매수가: 68,000원 ~ 70,000원

[삼성전자] 매수 주문 2건 접수
- 68,000원 x 5주
- 70,000원 x 5주
- 예상 비용: 690,000원

[삼성전자] 매도 주문 2건 접수
- 75,000원 x 5주
- 78,000원 x 5주
- 예상 수익: +8%

보안 주의사항

API 키 보호

# .env 파일
KIS_APP_KEY=your_app_key
KIS_APP_SECRET=your_app_secret
KIS_ACCOUNT_NO=12345678-01

# 절대 코드에 하드코딩하지 말 것!

주문 실행 권한

# 인증된 사용자만 주문 가능
@router.post("/api/buy-orders")
async def execute_buy_orders(
    current_user: User = Depends(require_role(UserRole.trader))
):
    """Trader 이상 권한 필요"""
    ...

Rate Limiting

# API 호출 간격 유지
await asyncio.sleep(0.2)  # 200ms 간격

# KIS API는 초당 10회 제한이 있음

마치며

배운 교훈

"자동 매매는 편리하지만, 설정이 핵심이다"

처음에는 "AI가 알아서 다 해주겠지"라고 생각했습니다.

하지만 실제로는:

종목별 특성이 다름: 삼성전자와 바이오주는 완전히 다른 전략 필요
리스크 관리 필수: 설정 없는 종목 자동 매수는 위험
분할 주문의 중요성: 한 번에 전량 매수/매도하면 슬리피지 발생

시스템의 강점

1. AI 기반 가격 분석:

단순 기술적 분석이 아닌 AI의 종합 판단
4가지 가격대 제안으로 분할 매수/매도

2. 종목별 세밀한 설정:

각 종목 특성에 맞는 수량/가격대 설정
활성화/비활성화로 유연한 관리

3. 비동기 처리:

여러 종목 동시 분석
실시간 진행 상황 확인

다음 단계

이제 우리의 자동매매 시스템은:

✅ 데이터 수집 (한투/Upbit/yfinance)
✅ AI 분석 (Gemini)
✅ DB 저장 및 정규화
✅ 암호화폐 웹 대시보드
✅ 모니터링 (Grafana Stack)
✅ 프로덕션 배포 (HTTPS + 24시간)
✅ JWT 인증 + RBAC
✅ 국내/해외 주식 자동 매매 ← 완성!

추가로 고려할 수 있는 기능:

정기 자동 실행 (크론 스케줄러)
포트폴리오 리밸런싱
손절/익절 조건 설정
백테스팅 시스템

참고 자료:

Python 3.13 업그레이드: 새로운 기능과 성능 개선 도입하기

kwanghyun — Mon, 24 Nov 2025 20:52:13 +0900

이 글은 개발 인프라 개선 시리즈의 Infra-2편이다.

개발 인프라 개선 시리즈:

Infra-1편: Poetry에서 UV로 마이그레이션

Infra-2편: Python 3.13 업그레이드 ← 현재 글

AI 자동매매 시리즈:

1편: 한투 API로 실시간 주식 데이터 수집하기

2편: yfinance로 애플·테슬라 분석하기

3편: Upbit으로 비트코인 24시간 분석하기

4편: AI 분석 결과 DB에 저장하기

5편: Upbit 웹 트레이딩 대시보드 구축하기

6편: 실전 운영을 위한 모니터링 시스템 구축

7편: 라즈베리파이 홈서버에 자동 HTTPS로 안전하게 배포하기

들어가며

왜 Python 3.13인가?

Python 3.13이 2024년 10월에 정식 릴리즈되었습니다. 새로운 버전은 항상 흥미롭지만, 프로덕션 환경에서 바로 도입해야 한다.

이번 업그레이드를 결정한 이유:

✅ 도입 이유:

성능 개선: 전역 인터프리터 락(GIL) 개선으로 멀티스레딩 성능 향상
새로운 기능: 개선된 에러 메시지, 타입 힌팅 강화
보안: 최신 보안 패치 및 취약점 수정
생태계: 주요 라이브러리들의 3.13 지원 완료
미래 대비: 3.11, 3.12는 2026~2027년 EOL (End of Life)

⚠️ 고려사항:

일부 라이브러리 호환성 문제 가능
CI/CD 파이프라인 수정 필요
팀원 로컬 환경 업데이트 필요

하지만 우리 프로젝트는:

UV를 사용하여 의존성 관리가 간단함
Docker 기반 배포로 환경 재현성 보장
테스트 커버리지가 높아 회귀 버그 조기 발견 가능

따라서 지금이 업그레이드하기 좋은 시기라고 판단했습니다!

Python 버전 타임라인

Python 버전별 릴리즈 및 EOL 타임라인

Python 3.13의 주요 변경사항

1. 성능 개선

JIT 컴파일러 실험적 지원 (PEP 744):

# Python 3.13부터 --enable-experimental-jit 옵션으로 활성화 가능
# 반복 실행되는 코드에서 최대 2배 성능 향상

def calculate_fibonacci(n):
    if n <= 1:
        return n
    return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)

# JIT 컴파일러가 핫스팟을 감지하여 네이티브 코드로 컴파일

GIL 개선 (PEP 703):

멀티스레딩 성능 향상
CPU 바운드 작업에서 체감 가능한 속도 향상

2. 타입 힌팅 강화

TypedDict의 읽기 전용 키 (PEP 705):

from typing import TypedDict, ReadOnly

class User(TypedDict):
    id: ReadOnly[int]  # 읽기 전용 필드
    name: str
    email: str

user: User = {"id": 1, "name": "Alice", "email": "alice@example.com"}
user["name"] = "Bob"  # OK
user["id"] = 2  # 타입 체커에서 에러!

@override 데코레이터 추가 (PEP 698):

from typing import override

class BaseAnalyzer:
    def analyze(self, symbol: str) -> dict:
        pass

class UpbitAnalyzer(BaseAnalyzer):
    @override
    def analyze(self, symbol: str) -> dict:
        # 부모 메서드를 오버라이드한다는 의도를 명시
        return {"symbol": symbol}

    @override
    def analyse(self, symbol: str) -> dict:
        # 오타! 타입 체커가 에러 발생
        pass

3. 에러 메시지 개선

더 명확한 에러 메시지:

# Python 3.12
>>> x = {"name": "Alice"}
>>> x["age"]
KeyError: 'age'

# Python 3.13
>>> x = {"name": "Alice"}
>>> x["age"]
KeyError: 'age'
Did you mean: 'name'?  # 제안 추가!

4. 보안 개선

SSL/TLS 기본 설정 강화
hashlib의 SHA-256 성능 개선
메모리 안전성 향상

업그레이드 과정

1. 호환성 확인

업그레이드 전에 프로젝트 의존성이 Python 3.13을 지원하는지 확인:

# 주요 라이브러리 호환성 확인
uv pip list | grep -E "fastapi|uvicorn|sqlalchemy|alembic|pytest"

# 결과:
# fastapi 0.116.1 - ✅ Python 3.13 지원
# uvicorn 0.35.0 - ✅ Python 3.13 지원
# sqlalchemy 2.0.36 - ✅ Python 3.13 지원
# alembic 1.14.0 - ✅ Python 3.13 지원
# pytest 8.3.4 - ✅ Python 3.13 지원

주요 라이브러리 3.13 지원 현황 (2024년 12월 기준):

라이브러리	버전	3.13 지원
FastAPI	0.116.1+	✅
SQLAlchemy	2.0+	✅
pytest	8.0+	✅
pandas	2.2+	✅
numpy	2.0+	✅
pydantic	2.10+	✅

2. 로컬 환경 업그레이드

Python 3.13 설치:

# macOS (Homebrew)
brew install python@3.13

# 또는 pyenv 사용
pyenv install 3.13.0
pyenv global 3.13.0

# Ubuntu/Debian
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.13 python3.13-dev

# 버전 확인
python3.13 --version
# Python 3.13.0

프로젝트 설정 업데이트:

# 1. .python-version 파일 업데이트
echo "3.13" > .python-version

# 2. UV 재설치 (최신 버전으로)
pip install --upgrade uv

# 3. 가상환경 재생성
rm -rf .venv
uv sync

3. pyproject.toml 업데이트

Before (Python 3.12):

[project]
name = "auto-trader"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.116.1,<0.117.0",
    # ...
]

After (Python 3.13):

[project]
name = "auto-trader"
version = "0.1.0"
requires-python = ">=3.13"  # ✅ 변경
dependencies = [
    "fastapi>=0.116.1,<0.117.0",
    # ... (동일)
]

4. uv.lock 업데이트

# UV가 Python 3.13용 의존성으로 자동 업데이트
uv lock

# 변경사항 확인
git diff uv.lock

# 주요 변경사항:
# - 모든 패키지의 wheel이 cp313으로 변경
# - Python 3.13에서만 사용 가능한 최적화된 바이너리 사용

lockfile 차이:

Python 3.12용 wheel: cp312-cp312-manylinux_2_17_x86_64.whl
Python 3.13용 wheel: cp313-cp313-manylinux_2_17_x86_64.whl

5. Dockerfile 업데이트

Dockerfile.api (Before):

FROM python:3.12-slim AS builder

# UV 설치
RUN pip install --upgrade pip && pip install uv

WORKDIR /app

# 의존성 설치
COPY pyproject.toml uv.lock README.md ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen

# 앱 코드 복사
COPY . .

# 런타임 스테이지
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app /app

CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Dockerfile.api (After):

FROM python:3.13-slim AS builder  # ✅ 3.13으로 변경

# UV 설치
RUN pip install --upgrade pip && pip install uv

WORKDIR /app

# 의존성 설치
COPY pyproject.toml uv.lock README.md ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen

# 앱 코드 복사
COPY . .

# 런타임 스테이지
FROM python:3.13-slim  # ✅ 3.13으로 변경
WORKDIR /app
COPY --from=builder /app /app

CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

동일하게 Dockerfile.ws도 업데이트:

FROM python:3.13-slim AS builder  # WebSocket 서버도 3.13
# ... (나머지 동일)

6. GitHub Actions 업데이트

.github/workflows/test.yml (Before):

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.12']  # 3.12만 지원

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install UV
        run: pip install uv

      - name: Install dependencies
        run: uv sync --group test

      - name: Run tests
        run: uv run pytest tests/ -v --cov

.github/workflows/test.yml (After):

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.13']  # ✅ 3.13으로 변경

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install UV
        run: pip install uv

      - name: Install dependencies
        run: uv sync --group test

      - name: Run tests
        run: uv run pytest tests/ -v --cov

test-monitoring-stack.yml도 동일하게 업데이트:

jobs:
  test:
    strategy:
      matrix:
        python-version: ['3.13']  # ✅ 변경

7. 문서 업데이트

CLAUDE.md 업데이트:

## 개발 환경 설정

### 필수 요구사항
- Python 3.13+  # ✅ 변경
- UV (의존성 관리)
- PostgreSQL (데이터베이스)
- Redis (캐싱)

테스트 및 검증

1. 로컬 테스트

# 1. 의존성 재설치
rm -rf .venv
uv sync --all-groups

# 2. 단위 테스트
make test-unit
# ✅ 118 passed, 0 failed

# 3. 통합 테스트 (선택사항)
make test-integration
# ✅ 12 passed, 0 failed

# 4. 전체 테스트 + 커버리지
make test-cov
# ✅ 130 passed
# Coverage: 87%

2. Docker 이미지 빌드

# API 서버 이미지 빌드
docker build -f Dockerfile.api -t auto-trader-api:3.13 .

# WebSocket 서버 이미지 빌드
docker build -f Dockerfile.ws -t auto-trader-ws:3.13 .

# 이미지 확인
docker images | grep auto-trader
# auto-trader-api   3.13   ...   150MB
# auto-trader-ws    3.13   ...   145MB

이미지 크기 비교:

Python 3.12: 148MB (API), 143MB (WS)
Python 3.13: 150MB (API), 145MB (WS)
차이: +2MB (약 1.4% 증가 - 무시 가능)

3. 로컬 Docker Compose 테스트

# 전체 스택 시작
docker compose up -d

# 서비스 상태 확인
docker compose ps
# NAME           IMAGE               STATUS
# postgres       postgres:16         Up
# redis          redis:7             Up
# api            auto-trader-api     Up
# websocket      auto-trader-ws      Up

# API 헬스체크
curl http://localhost:8000/health
# {"status": "healthy", "python_version": "3.13.0"}

# 로그 확인
docker compose logs api | grep -i "python"
# INFO:     Using Python 3.13.0

4. CI/CD 파이프라인 검증

GitHub Actions에서 자동 테스트:

# PR 생성 후 CI 실행
gh pr create --title "Python 3.13으로 업그레이드" \
             --body "Python 3.12에서 3.13으로 업그레이드"

# CI 상태 확인
gh pr checks

# 출력 예시:
# ✅ Tests (3.13) - All tests passed
# ✅ Lint - No issues found
# ✅ Security - No vulnerabilities
# ✅ Docker Build - Images built successfully

CI/CD 파이프라인 성공

GitHub Actions에서 Python 3.13 테스트 성공

발생한 이슈와 해결

이슈 1: Docker 이미지 캐시 무효화

문제:
Python 버전을 변경했지만 Docker가 이전 3.12 이미지를 캐시에서 사용.

에러 메시지:

docker build -f Dockerfile.api .
# Step 1/10 : FROM python:3.13-slim
# Using cache
# (실제로는 3.12 이미지 사용 중)

해결:

# 캐시 없이 재빌드
docker build --no-cache -f Dockerfile.api -t auto-trader-api:3.13 .

# 또는 기존 이미지 삭제 후 재빌드
docker rmi python:3.12-slim python:3.13-slim
docker build -f Dockerfile.api -t auto-trader-api:3.13 .

이슈 2: uv.lock 충돌

문제:
여러 팀원이 동시에 uv lock을 실행하여 lockfile 충돌 발생.

해결:

# 1. 최신 main 브랜치 pull
git checkout main
git pull origin main

# 2. 내 브랜치에 main merge
git checkout my-branch
git merge main

# 3. 충돌 시 main의 uv.lock 우선 사용
git checkout --theirs uv.lock

# 4. 로컬에서 uv lock 재생성
uv lock

# 5. 테스트 후 커밋
uv sync
make test
git add uv.lock
git commit -m "Resolve uv.lock conflict"

이슈 3: 일부 타입 힌팅 에러

문제:
Python 3.13의 타입 체커가 더 엄격해져서 기존 코드에서 경고 발생.

예시:

# Before (3.12에서는 OK)
def analyze(data: dict) -> dict:
    return {"result": data.get("value")}

# After (3.13에서 mypy 경고)
# error: Need type annotation for "data"

해결:

from typing import Dict, Any

def analyze(data: Dict[str, Any]) -> Dict[str, Any]:
    return {"result": data.get("value")}

이슈 4: GitHub Actions setup-python 캐시

문제:
GitHub Actions가 Python 3.12 캐시를 재사용하여 3.13 설치 실패.

해결:

- name: Set up Python 3.13
  uses: actions/setup-python@v5
  with:
    python-version: '3.13'
    cache: 'pip'  # pip 캐시는 자동으로 Python 버전별로 분리됨

또는 캐시 무효화:

# GitHub Actions 캐시 삭제
gh cache delete <cache-key>

# 또는 workflow에서 캐시 키에 Python 버전 포함
- uses: actions/cache@v3
  with:
    path: .venv
    key: venv-${{ runner.os }}-${{ hashFiles('**/uv.lock') }}-py313

성능 비교

1. 애플리케이션 시작 시간

측정 방법:

# Python 3.12
time uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 &
# real    0m2.341s

# Python 3.13
time uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 &
# real    0m2.298s

결과:

Python 3.12: 2.341초
Python 3.13: 2.298초
개선: 약 2% 빠름

2. 테스트 실행 시간

# Python 3.12
time uv run pytest tests/ -v
# 130 passed in 18.42s

# Python 3.13
time uv run pytest tests/ -v
# 130 passed in 17.91s

결과:

Python 3.12: 18.42초
Python 3.13: 17.91초
개선: 약 3% 빠름

3. API 응답 시간 (벤치마크)

Upbit 분석 API 벤치마크:

# Python 3.12
ab -n 100 -c 10 http://localhost:8000/api/upbit/analyze/BTC-KRW
# Requests per second: 12.34 [#/sec]
# Time per request: 81.03 [ms] (mean)

# Python 3.13
ab -n 100 -c 10 http://localhost:8000/api/upbit/analyze/BTC-KRW
# Requests per second: 12.71 [#/sec]
# Time per request: 78.67 [ms] (mean)

결과:

Python 3.12: 81.03ms (평균)
Python 3.13: 78.67ms (평균)
개선: 약 3% 빠름

4. 메모리 사용량

# Python 3.12
docker stats auto-trader-api
# CONTAINER      CPU %   MEM USAGE / LIMIT    MEM %
# api            0.5%    142.3MiB / 512MiB    27.8%

# Python 3.13
docker stats auto-trader-api
# CONTAINER      CPU %   MEM USAGE / LIMIT    MEM %
# api            0.4%    138.7MiB / 512MiB    27.1%

결과:

Python 3.12: 142.3MB
Python 3.13: 138.7MB
개선: 약 2.5% 메모리 절감

성능 비교 그래프

Python 3.12 vs 3.13 성능 비교

체크리스트

Python 버전 업그레이드를 고려 중이라면 다음 체크리스트를 참고하세요:

업그레이드 전:

주요 의존성이 새 Python 버전을 지원하는가?
팀원들에게 업그레이드 계획을 공유했는가?
현재 환경에서 모든 테스트가 통과하는가?
롤백 계획이 있는가?

업그레이드 중:

.python-version 파일 업데이트
pyproject.toml의 requires-python 업데이트
uv.lock 재생성 (uv lock)
Dockerfile에서 베이스 이미지 업데이트
GitHub Actions 워크플로우 업데이트
문서(README, CLAUDE.md 등) 업데이트

업그레이드 후:

로컬 환경에서 테스트 실행 확인
Docker 이미지 빌드 및 실행 확인
CI/CD 파이프라인 통과 확인
프로덕션 배포 후 모니터링

팀원 온보딩 가이드

팀원이 해야 할 작업

1. Python 3.13 설치:

# macOS
brew install python@3.13

# Ubuntu/Debian
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.13

# pyenv 사용자
pyenv install 3.13.0
pyenv global 3.13.0

2. 프로젝트 업데이트:

# 최신 코드 pull
git pull origin main

# 기존 가상환경 삭제
rm -rf .venv

# 새로운 가상환경 생성 및 의존성 설치
uv sync --all-groups

# Python 버전 확인
python --version
# Python 3.13.0

3. Docker 이미지 재빌드:

# 기존 이미지 삭제
docker compose down
docker rmi auto-trader-api auto-trader-ws

# 새로운 이미지 빌드
docker compose build

# 서비스 시작
docker compose up -d

4. IDE 설정 업데이트:

VSCode:

// .vscode/settings.json
{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.analysis.typeCheckingMode": "basic",
  "python.languageServer": "Pylance"
}

PyCharm:

Preferences > Project > Python Interpreter
기존 인터프리터 삭제
Add Interpreter > Existing Environment
.venv/bin/python 선택

롤백 계획

만약 Python 3.13으로 전환 후 문제가 발생하면:

방법 1: Git Revert

# 업그레이드 커밋 확인
git log --oneline | grep "Python 3.13"
# abc1234 Python 3.13으로 업그레이드

# 해당 커밋 revert
git revert abc1234

# 또는 브랜치 전체 롤백
git checkout main
git reset --hard <before-upgrade-commit>

방법 2: 수동 롤백

# 1. Python 버전 파일 복구
echo "3.12" > .python-version

# 2. pyproject.toml 복구
sed -i 's/>=3.13/>=3.12/' pyproject.toml

# 3. uv.lock 재생성
uv lock

# 4. 가상환경 재생성
rm -rf .venv
uv sync

# 5. Docker 이미지 재빌드
docker compose build

방법 3: 이전 Docker 이미지 사용

# 이전 이미지 태그로 롤백
docker pull your-registry/auto-trader-api:python3.12
docker pull your-registry/auto-trader-ws:python3.12

# docker-compose.yml에서 이미지 태그 변경
# image: auto-trader-api:python3.13 → auto-trader-api:python3.12

docker compose up -d

마치며

Python 3.13 업그레이드 소감

처음에는 "버전 업그레이드가 필요할까?"라는 의구심이 있었습니다.

하지만:

호환성 확인: 주요 라이브러리가 모두 3.13 지원
UV 덕분에 의존성 관리가 간단함
Docker 기반 배포로 환경 재현성 보장
테스트 커버리지 높아 회귀 버그 조기 발견

결과적으로 예상보다 훨씬 쉽게 업그레이드할 수 있었습니다!

체감한 효과

개발 경험 개선:

더 명확한 에러 메시지 (오타 제안 등)
타입 힌팅 강화로 버그 조기 발견
성능 향상 (2~3%)

미래 대비:

Python 3.11, 3.12는 2026~2027년 EOL
최신 보안 패치 적용
새로운 기능 활용 가능

권장 사항

✅ Python 3.13 업그레이드 추천:

주요 라이브러리가 3.13을 지원하는 프로젝트
UV, Poetry 같은 현대적 패키지 관리자 사용
Docker 기반 배포로 환경 재현성 보장
테스트 커버리지가 높은 프로젝트
Python 3.11 이하를 사용 중인 프로젝트 (EOL 임박)

⚠️ 신중히 검토:

레거시 라이브러리에 크게 의존하는 경우
팀원 대부분이 Python 3.13 전환을 원하지 않는 경우
프로덕션 환경에서 Python 버전 업그레이드가 어려운 경우

다음 단계

이제 우리 프로젝트는:

✅ UV로 의존성 관리 (Infra-1편)
✅ Python 3.13 최신 버전 (Infra-2편)

추가로 고려할 인프라 개선:

CI/CD 파이프라인 최적화 (캐싱, 병렬화)
멀티스테이지 Docker 빌드 개선
Pre-commit hooks 도입 (코드 품질 자동 검사)
Renovate/Dependabot으로 자동 의존성 업데이트

하지만 가장 중요한 것은:

"필요한 개선을 점진적으로 적용하며 프로젝트를 발전시키는 것"

이론보다 실전, 계획보다 실행!

참고 자료:

프로젝트 저장소:

GitHub: github.com/mgh3326/auto_trader
Python 3.13 업그레이드 PR: #77

질문이나 피드백은 이슈로 남겨주세요!

JWT 인증 시스템으로 안전한 웹 애플리케이션 구축하기: 회원가입부터 역할 기반 접근 제어까지

kwanghyun — Sun, 23 Nov 2025 21:45:07 +0900

JWT 인증 시스템

이 글은 AI 기반 자동매매 시스템 시리즈의 8편이다.

전체 시리즈:

1편: 한투 API로 실시간 주식 데이터 수집하기

2편: yfinance로 애플·테슬라 분석하기

3편: Upbit으로 비트코인 24시간 분석하기

4편: AI 분석 결과 DB에 저장하기

5편: Upbit 웹 트레이딩 대시보드 구축하기

6편: 실전 운영을 위한 모니터링 시스템 구축

7편: 라즈베리파이 홈서버에 자동 HTTPS로 안전하게 배포하기

8편: JWT 인증 시스템으로 안전한 웹 애플리케이션 구축하기 ← 현재 글

들어가며

지금까지의 여정

우리는 지금까지:

✅ 한투/yfinance/Upbit API로 데이터 수집
✅ AI 분석 자동화 (Gemini)
✅ DB 저장 및 정규화
✅ 웹 대시보드 구축
✅ Grafana 관찰성 스택으로 모니터링
✅ 라즈베리파이에 HTTPS 배포

까지 완성했습니다.

새로운 과제: 보안

시스템을 인터넷에 배포했으니 이제 누가 접근할 수 있는지 제어해야 한다.

현재 상태:

https://your-domain.com  # 아무나 접속 가능  
https://your-domain.com/api/stocks  # 아무나 API 호출 가능

실제로 마주한 보안 문제들

문제 1: 무방비한 API 엔드포인트

# 아무나 데이터 조회 가능
curl https://your-domain.com/api/stocks
# → 200 OK (모든 종목 데이터 노출)

# 아무나 분석 요청 가능
curl -X POST https://your-domain.com/api/analyze/비트코인
# → 200 OK (AI 분석 비용 발생)

문제점:

무제한 API 호출 → AI 비용 폭탄
민감한 거래 정보 노출
악의적인 사용자의 서비스 악용

문제 2: 사용자별 권한 구분 불가

누가 이 분석을 요청했나?
누가 이 거래를 실행했나?
→ 알 수 없음

문제점:

사용자 추적 불가
책임 소재 불분명
감사(Audit) 로그 부재

문제 3: 관리 기능 노출

# 아무나 시스템 설정 변경 가능?
# 아무나 다른 사용자 정보 조회 가능?
→ 이건 절대 안 됨!

해결책: JWT 기반 인증 + 역할 기반 접근 제어 (RBAC)

이번 글에서 구축할 시스템:

JWT (JSON Web Token) 인증
- 상태를 저장하지 않는(Stateless) 토큰 기반 인증
- Access Token (15분) + Refresh Token (7일)
- 토큰 블랙리스트로 강제 로그아웃
역할 기반 접근 제어 (RBAC)
- Admin: 모든 권한
- Trader: 거래 실행 가능
- Analyst: 분석 조회만 가능
- Viewer: 읽기 전용
보안 강화
- bcrypt 비밀번호 해싱
- Rate Limiting (분당 5회 제한)
- 세션 관리 (Redis)
- 보안 로깅

인증 시스템 아키텍처

JWT + Redis 기반 인증 시스템 구조

핵심 컴포넌트

사용자
  ↓
FastAPI 애플리케이션
  ├─ 인증 라우터 (/auth)
  │   ├─ POST /register (회원가입)
  │   ├─ POST /login (로그인)
  │   ├─ POST /refresh (토큰 갱신)
  │   └─ POST /logout (로그아웃)
  │
  ├─ 인증 미들웨어
  │   ├─ JWT 토큰 검증
  │   ├─ 사용자 인증
  │   └─ 역할 권한 확인
  │
  ├─ 보호된 API 엔드포인트
  │   ├─ /api/stocks (읽기: Viewer+)
  │   ├─ /api/trade (거래: Trader+)
  │   └─ /admin/* (관리: Admin)
  │
  └─ 보안 계층
      ├─ bcrypt (비밀번호 해싱)
      ├─ Redis (토큰 저장)
      └─ Rate Limiting

인증 흐름

1. 회원가입 및 로그인:

[사용자] → POST /auth/register
           ├─ 이메일, 사용자명, 비밀번호
           ├─ bcrypt로 비밀번호 해싱
           └─ User 테이블에 저장

[사용자] → POST /auth/login
           ├─ 사용자명, 비밀번호
           ├─ 비밀번호 검증
           ├─ Access Token 생성 (15분)
           ├─ Refresh Token 생성 (7일)
           └─ Redis에 Refresh Token 저장

2. 인증된 요청:

[사용자] → GET /api/stocks
           ├─ Authorization: Bearer <access_token>
           ├─ JWT 토큰 검증
           ├─ 사용자 권한 확인
           └─ 응답 반환

3. 토큰 갱신:

[사용자] → POST /auth/refresh
           ├─ refresh_token 전송
           ├─ Redis에서 토큰 검증
           ├─ 새 Access Token 발급
           └─ Refresh Token 재발급 (선택)

4. 로그아웃:

[사용자] → POST /auth/logout
           ├─ Refresh Token 전송
           ├─ Redis에서 토큰 삭제 (블랙리스트)
           └─ 강제 로그아웃

JWT (JSON Web Token) 이해하기

JWT란?

JSON 형태의 데이터를 안전하게 전송하기 위한 토큰 표준 (RFC 7519)

JWT 구조:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJib2IiLCJleHAiOjE3MDk1MTIxNjd9.jKVUwDEHNWLkoDcJZvtgnxCyVbEN1Ulq0vZcxAJvSSk

↓ 디코딩하면

Header (헤더):
{
  "alg": "HS256",
  "typ": "JWT"
}

Payload (페이로드):
{
  "sub": "bob",        # 사용자명
  "exp": 1709512167,   # 만료 시간
  "type": "access"     # 토큰 타입
}

Signature (서명):
HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  SECRET_KEY
)

Access Token vs Refresh Token

특성	Access Token	Refresh Token
목적	API 요청 인증	Access Token 갱신
유효기간	15분 (짧음)	7일 (길음)
저장 위치	메모리/LocalStorage	HttpOnly Cookie
노출 위험	높음 (매 요청마다 전송)	낮음 (갱신 시에만)
탈취 시 피해	15분 내로 제한	7일 내로 제한
저장소	없음 (Stateless)	Redis (검증 필요)

왜 두 개의 토큰을 사용하나?

보안과 편의성 균형:
- Access Token이 짧으면 → 안전하지만 자주 로그인 필요
- Refresh Token으로 → 로그인 유지하면서도 안전
탈취 시 피해 최소화:
- Access Token 탈취 → 최대 15분간만 사용 가능
- Refresh Token 탈취 → Redis에서 즉시 무효화 가능

구현: 회원가입 및 로그인

1. 비밀번호 해싱 (bcrypt)

# app/auth/security.py
from passlib.context import CryptContext

# bcrypt로 비밀번호 해싱 (강력한 암호화)
PASSWORD_CONTEXT = CryptContext(schemes=["bcrypt"], deprecated="auto")

def get_password_hash(password: str) -> str:
    """비밀번호를 bcrypt로 해싱"""
    return PASSWORD_CONTEXT.hash(password)

def verify_password(plain_password: str, hashed_password: str) -> bool:
    """비밀번호 검증"""
    return PASSWORD_CONTEXT.verify(plain_password, hashed_password)

bcrypt의 특징:

느린 해싱: 무차별 대입 공격(Brute Force) 방어
Salt 자동 생성: 동일한 비밀번호도 다른 해시값
Work Factor: 해싱 횟수 조절 가능 (기본 12 rounds)

2. JWT 토큰 생성

# app/auth/security.py
import jwt
from datetime import datetime, timedelta, timezone
from app.core.config import settings

def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
    """Access Token 생성 (15분)"""
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + timedelta(
        minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES  # 15
    )
    to_encode.update({"exp": expire, "type": "access"})

    # SECRET_KEY로 서명
    encoded_jwt = jwt.encode(
        to_encode,
        settings.SECRET_KEY,
        algorithm=settings.ALGORITHM  # HS256
    )
    return encoded_jwt

def create_refresh_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
    """Refresh Token 생성 (7일)"""
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + timedelta(
        days=settings.REFRESH_TOKEN_EXPIRE_DAYS  # 7
    )
    to_encode.update({"exp": expire, "type": "refresh"})

    encoded_jwt = jwt.encode(
        to_encode,
        settings.SECRET_KEY,
        algorithm=settings.ALGORITHM
    )
    return encoded_jwt

3. 회원가입 API

# app/auth/router.py
from fastapi import APIRouter, HTTPException, status
from app.auth.schemas import UserCreate, UserResponse
from app.auth.security import get_password_hash

router = APIRouter(prefix="/auth", tags=["authentication"])

@router.post("/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
@limiter.limit("5/minute")  # Rate Limiting: 분당 5회
async def register(
    user_data: UserCreate,
    db: AsyncSession = Depends(get_db),
) -> UserResponse:
    """
    회원가입

    - 이메일, 사용자명 중복 확인
    - 비밀번호 bcrypt 해싱
    - 기본 역할: Viewer
    """
    # 중복 확인
    result = await db.execute(select(User).where(User.username == user_data.username))
    if result.scalar_one_or_none():
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Username already registered",
        )

    # 사용자 생성
    hashed_password = get_password_hash(user_data.password)
    db_user = User(
        email=user_data.email,
        username=user_data.username,
        role=UserRole.viewer,  # 기본 역할
        hashed_password=hashed_password,
        is_active=True,
    )

    db.add(db_user)
    await db.commit()
    await db.refresh(db_user)

    return UserResponse.model_validate(db_user)

보안 포인트:

Rate Limiting으로 무차별 가입 방지
비밀번호는 절대 평문 저장하지 않음
기본 역할은 최소 권한 (Viewer)

4. 로그인 API

@router.post("/login", response_model=Token)
@limiter.limit("5/minute")
async def login(
    form_data: OAuth2PasswordRequestForm = Depends(),
    db: AsyncSession = Depends(get_db),
) -> Token:
    """
    로그인

    - 사용자명, 비밀번호 검증
    - Access Token + Refresh Token 발급
    - Refresh Token을 Redis에 저장
    """
    # 사용자 조회
    result = await db.execute(
        select(User).where(User.username == form_data.username)
    )
    user = result.scalar_one_or_none()

    # 사용자 없음 또는 비밀번호 불일치
    if not user or not verify_password(form_data.password, user.hashed_password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
            headers={"WWW-Authenticate": "Bearer"},
        )

    # 비활성화된 사용자
    if not user.is_active:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Inactive user"
        )

    # JWT 토큰 생성
    access_token = create_access_token(data={"sub": user.username})
    refresh_token = create_refresh_token(data={"sub": user.username})

    # Refresh Token을 Redis에 저장 (토큰 검증 및 무효화용)
    await save_refresh_token(
        user_id=user.id,
        refresh_token=refresh_token,
        expires_in=settings.REFRESH_TOKEN_EXPIRE_DAYS * 86400  # 7일 (초 단위)
    )

    return Token(
        access_token=access_token,
        refresh_token=refresh_token,
        token_type="bearer"
    )

Redis 기반 토큰 관리

왜 Redis인가?

Refresh Token은 왜 DB/Redis에 저장해야 하나?

강제 로그아웃 필요:
- JWT는 Stateless → 발급 후 서버에서 제어 불가
- Redis에 저장 → 로그아웃 시 삭제하여 무효화
보안 강화:
- 탈취된 토큰 즉시 차단
- 사용자별 활성 세션 관리
빠른 조회:
- Redis의 O(1) 조회 속도
- 매 API 요청마다 검증하므로 속도 중요

Redis 토큰 저장 구조

# app/auth/token_repository.py
from app.core.redis_client import get_redis
import hashlib

async def save_refresh_token(
    user_id: int,
    refresh_token: str,
    expires_in: int
) -> None:
    """Refresh Token을 Redis에 저장"""
    redis = await get_redis()

    # 토큰 해시 (보안 강화)
    token_hash = hashlib.sha256(refresh_token.encode()).hexdigest()

    # Redis 키: refresh_token:{user_id}:{token_hash}
    key = f"refresh_token:{user_id}:{token_hash}"

    # 저장 (TTL: 7일)
    await redis.setex(key, expires_in, refresh_token)

async def get_valid_refresh_token(
    user_id: int,
    refresh_token: str
) -> bool:
    """Redis에서 Refresh Token 검증"""
    redis = await get_redis()
    token_hash = hashlib.sha256(refresh_token.encode()).hexdigest()
    key = f"refresh_token:{user_id}:{token_hash}"

    # 토큰 존재 여부 확인
    stored_token = await redis.get(key)
    return stored_token is not None

async def revoke_refresh_token(
    user_id: int,
    refresh_token: str
) -> None:
    """Refresh Token 무효화 (로그아웃)"""
    redis = await get_redis()
    token_hash = hashlib.sha256(refresh_token.encode()).hexdigest()
    key = f"refresh_token:{user_id}:{token_hash}"

    # Redis에서 삭제
    await redis.delete(key)

Redis 키 구조:

refresh_token:1:abc123def456...  → "eyJhbGciOiJIUzI1NiIs..."
refresh_token:1:789xyz012abc...  → "eyJhbGciOiJIUzI1NiIs..."
refresh_token:2:def456ghi789...  → "eyJhbGciOiJIUzI1NiIs..."

TTL: 604800 seconds (7일)

역할 기반 접근 제어 (RBAC)

역할 정의

# app/models/trading.py
from enum import Enum

class UserRole(str, Enum):
    """사용자 역할 (계층 구조)"""
    admin = "admin"      # 최고 권한 (모든 것)
    trader = "trader"    # 거래 실행 가능
    analyst = "analyst"  # 분석 조회만
    viewer = "viewer"    # 읽기 전용

class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True, index=True)
    email: Mapped[str] = mapped_column(unique=True, index=True)
    username: Mapped[str] = mapped_column(unique=True, index=True)
    hashed_password: Mapped[str]
    role: Mapped[UserRole] = mapped_column(default=UserRole.viewer)
    is_active: Mapped[bool] = mapped_column(default=True)

역할 계층 구조

Admin → Trader → Analyst → Viewer 권한 상속

# app/auth/role_hierarchy.py
class RoleHierarchy:
    """
    역할 계층 구조

    Admin → Trader → Analyst → Viewer
    (상위 역할은 하위 역할의 권한 포함)
    """
    HIERARCHY = {
        UserRole.viewer: 0,
        UserRole.analyst: 1,
        UserRole.trader: 2,
        UserRole.admin: 3,
    }

    @classmethod
    def has_permission(cls, user_role: UserRole, required_role: UserRole) -> bool:
        """사용자 역할이 요구 역할 이상인지 확인"""
        return cls.HIERARCHY[user_role] >= cls.HIERARCHY[required_role]

예시:

Trader 역할은 Analyst, Viewer 권한도 가짐
Admin 역할은 모든 권한 가짐

권한 데코레이터

# app/auth/dependencies.py
from fastapi import Depends, HTTPException, status
from app.auth.security import verify_token

async def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: AsyncSession = Depends(get_db),
) -> User:
    """JWT 토큰에서 현재 사용자 조회"""
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )

    try:
        # JWT 토큰 디코딩
        payload = jwt.decode(
            token,
            settings.SECRET_KEY,
            algorithms=[settings.ALGORITHM]
        )
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
    except JWTError:
        raise credentials_exception

    # 사용자 조회
    result = await db.execute(select(User).where(User.username == username))
    user = result.scalar_one_or_none()

    if user is None:
        raise credentials_exception

    return user

def require_role(required_role: UserRole):
    """특정 역할 이상 요구하는 의존성"""
    async def role_checker(
        current_user: User = Depends(get_current_user)
    ) -> User:
        if not RoleHierarchy.has_permission(current_user.role, required_role):
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail=f"Requires {required_role.value} role or higher"
            )
        return current_user

    return role_checker

API 엔드포인트에 권한 적용

# app/routers/stocks.py
from fastapi import APIRouter, Depends
from app.auth.dependencies import require_role
from app.models.trading import UserRole

router = APIRouter(prefix="/api/stocks", tags=["stocks"])

@router.get("/")
async def get_stocks(
    current_user: User = Depends(require_role(UserRole.viewer))  # Viewer 이상
):
    """
    모든 종목 조회

    권한: Viewer 이상 (모든 사용자)
    """
    return {"stocks": [...]}

@router.post("/analyze")
async def analyze_stock(
    symbol: str,
    current_user: User = Depends(require_role(UserRole.analyst))  # Analyst 이상
):
    """
    종목 분석 요청

    권한: Analyst 이상 (AI 비용 발생)
    """
    return {"analysis": {...}}

@router.post("/trade")
async def execute_trade(
    order_data: dict,
    current_user: User = Depends(require_role(UserRole.trader))  # Trader 이상
):
    """
    거래 실행

    권한: Trader 이상 (실제 거래 실행)
    """
    return {"order_id": "..."}

@router.delete("/users/{user_id}")
async def delete_user(
    user_id: int,
    current_user: User = Depends(require_role(UserRole.admin))  # Admin만
):
    """
    사용자 삭제

    권한: Admin 전용
    """
    return {"deleted": user_id}

Rate Limiting으로 무차별 공격 방어

SlowAPI를 사용한 Rate Limiting

# app/auth/router.py
from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

@router.post("/register")
@limiter.limit("5/minute")  # IP당 분당 5회 제한
async def register(...):
    ...

@router.post("/login")
@limiter.limit("5/minute")  # IP당 분당 5회 제한
async def login(...):
    ...

@router.post("/refresh")
@limiter.limit("10/minute")  # IP당 분당 10회 제한
async def refresh_token(...):
    ...

Rate Limiting 전략:

회원가입/로그인: 분당 5회 (무차별 대입 방지)
토큰 갱신: 분당 10회 (정상 사용 허용)
API 호출: 분당 60회 (서비스 악용 방지)

효과:

Brute Force 공격 차단
DDoS 공격 완화
서버 리소스 보호

보안 로깅

구조화된 보안 로그

# app/auth/router.py
import logging

logger = logging.getLogger(__name__)

def _security_log_extra(request: Request, **kwargs) -> dict:
    """보안 로그 메타데이터"""
    return {
        "client_ip": request.client.host if request.client else None,
        "user_agent": request.headers.get("user-agent"),
        **kwargs,
    }

@router.post("/login")
async def login(request: Request, ...):
    # ... 로그인 로직 ...

    # 성공 로그
    logger.info(
        f"User '{user.username}' logged in successfully",
        extra=_security_log_extra(
            request,
            user_id=user.id,
            username=user.username,
            event="login_success"
        )
    )

    # 실패 로그
    logger.warning(
        f"Failed login attempt for username: {form_data.username}",
        extra=_security_log_extra(
            request,
            username=form_data.username,
            event="login_failed"
        )
    )

로그 예시:

{
  "timestamp": "2025-01-15T10:30:45Z",
  "level": "INFO",
  "message": "User 'bob' logged in successfully",
  "client_ip": "192.168.1.100",
  "user_agent": "Mozilla/5.0...",
  "user_id": 42,
  "username": "bob",
  "event": "login_success"
}

보안 이벤트 추적:

로그인 성공/실패
토큰 갱신
권한 없는 접근 시도
비정상적인 활동 패턴

테스트

인증 흐름 테스트

# tests/test_auth.py
import pytest
from httpx import AsyncClient

@pytest.mark.asyncio
async def test_register_login_flow(client: AsyncClient):
    """회원가입 → 로그인 흐름 테스트"""

    # 1. 회원가입
    register_response = await client.post(
        "/auth/register",
        json={
            "email": "test@example.com",
            "username": "testuser",
            "password": "SecurePass123!"
        }
    )
    assert register_response.status_code == 201

    # 2. 로그인
    login_response = await client.post(
        "/auth/login",
        data={
            "username": "testuser",
            "password": "SecurePass123!"
        }
    )
    assert login_response.status_code == 200
    tokens = login_response.json()
    assert "access_token" in tokens
    assert "refresh_token" in tokens

    # 3. 인증된 요청
    access_token = tokens["access_token"]
    protected_response = await client.get(
        "/api/stocks",
        headers={"Authorization": f"Bearer {access_token}"}
    )
    assert protected_response.status_code == 200

@pytest.mark.asyncio
async def test_invalid_credentials(client: AsyncClient):
    """잘못된 인증 정보 테스트"""
    response = await client.post(
        "/auth/login",
        data={
            "username": "nonexistent",
            "password": "wrongpassword"
        }
    )
    assert response.status_code == 401

@pytest.mark.asyncio
async def test_unauthorized_access(client: AsyncClient):
    """인증 없이 보호된 엔드포인트 접근"""
    response = await client.get("/api/stocks")
    assert response.status_code == 401  # Unauthorized

@pytest.mark.asyncio
async def test_role_based_access(client: AsyncClient):
    """역할 기반 접근 제어 테스트"""

    # Viewer 계정으로 로그인
    login_response = await client.post(
        "/auth/login",
        data={"username": "viewer", "password": "password"}
    )
    viewer_token = login_response.json()["access_token"]

    # 읽기 권한: 성공
    read_response = await client.get(
        "/api/stocks",
        headers={"Authorization": f"Bearer {viewer_token}"}
    )
    assert read_response.status_code == 200

    # 거래 권한: 실패 (Viewer는 거래 불가)
    trade_response = await client.post(
        "/api/trade",
        headers={"Authorization": f"Bearer {viewer_token}"},
        json={"symbol": "BTC", "amount": 100}
    )
    assert trade_response.status_code == 403  # Forbidden

Rate Limiting 테스트

# 로그인 5회 시도 (성공)
for i in {1..5}; do
  curl -X POST http://localhost:8000/auth/login \
    -d "username=test&password=test"
done

# 6번째 시도 (실패 - Rate Limit)
curl -X POST http://localhost:8000/auth/login \
  -d "username=test&password=test"
# → 429 Too Many Requests

실전 사용 예시

1. 웹 브라우저에서 사용

프론트엔드 (JavaScript):

// 로그인
async function login(username, password) {
  const response = await fetch('https://your-domain.com/auth/login', {
    method: 'POST',
    headers: {'Content-Type': 'application/x-www-form-urlencoded'},
    body: `username=${username}&password=${password}`
  });

  const data = await response.json();

  // Access Token은 메모리에 저장
  localStorage.setItem('access_token', data.access_token);

  // Refresh Token은 HttpOnly Cookie에 저장 (보안)
  // (백엔드에서 Set-Cookie 헤더로 설정)
}

// 인증된 API 요청
async function getStocks() {
  const token = localStorage.getItem('access_token');

  const response = await fetch('https://your-domain.com/api/stocks', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  if (response.status === 401) {
    // Access Token 만료 → Refresh Token으로 갱신
    await refreshToken();
    return getStocks();  // 재시도
  }

  return response.json();
}

// 토큰 갱신
async function refreshToken() {
  const refresh_token = getCookie('refresh_token');  // HttpOnly Cookie

  const response = await fetch('https://your-domain.com/auth/refresh', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({refresh_token})
  });

  const data = await response.json();
  localStorage.setItem('access_token', data.access_token);
}

// 로그아웃
async function logout() {
  const refresh_token = getCookie('refresh_token');

  await fetch('https://your-domain.com/auth/logout', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({refresh_token})
  });

  localStorage.removeItem('access_token');
  // Refresh Token은 서버에서 삭제됨
}

2. 명령줄 (curl)에서 사용

# 1. 로그인
curl -X POST https://your-domain.com/auth/login \
  -d "username=bob&password=SecurePass123!" \
  | jq -r '.access_token' > token.txt

# 2. 인증된 요청
ACCESS_TOKEN=$(cat token.txt)
curl https://your-domain.com/api/stocks \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. 토큰 갱신
REFRESH_TOKEN=$(cat refresh_token.txt)
curl -X POST https://your-domain.com/auth/refresh \
  -H "Content-Type: application/json" \
  -d "{\"refresh_token\": \"$REFRESH_TOKEN\"}" \
  | jq -r '.access_token' > token.txt

# 4. 로그아웃
curl -X POST https://your-domain.com/auth/logout \
  -H "Content-Type: application/json" \
  -d "{\"refresh_token\": \"$REFRESH_TOKEN\"}"

환경 변수 설정

# JWT 설정
SECRET_KEY=your-super-secret-key-change-this-in-production!  # 반드시 변경!
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=15
REFRESH_TOKEN_EXPIRE_DAYS=7

# Rate Limiting
RATELIMIT_ENABLED=true
RATELIMIT_STORAGE_URL=redis://localhost:6379/0

# Redis (토큰 저장)
REDIS_URL=redis://localhost:6379/0

보안 주의사항:

SECRET_KEY는 반드시 강력한 무작위 문자열로 변경
```
# 안전한 SECRET_KEY 생성
openssl rand -hex 32
```
프로덕션에서는 환경 변수로 주입 (코드에 하드코딩 금지)

보안 체크리스트

필수 보안 사항

비밀번호 해싱: bcrypt 사용 (평문 저장 절대 금지)
JWT 서명: SECRET_KEY로 토큰 서명 (위조 방지)
HTTPS: 모든 통신 암호화 (Caddy 자동 HTTPS)
Rate Limiting: 무차별 대입 공격 방어
Refresh Token 저장: Redis에 저장하여 강제 로그아웃 가능
Role-Based Access Control: 최소 권한 원칙
보안 로깅: 의심스러운 활동 추적

추가 보안 강화

2FA (Two-Factor Authentication): OTP 추가 인증
IP Whitelisting: 특정 IP만 접근 허용
API Key: 서비스 간 인증
CORS 설정: 허용된 도메인만 요청 허용
SQL Injection 방어: SQLAlchemy ORM 사용 (자동 방어)
XSS 방어: 입력 값 검증 및 이스케이프

마치며

배운 교훈

이번 인증 시스템 구축을 통해 가장 크게 배운 점:

"보안은 선택이 아니라 필수다"

처음에는 "로컬에서만 쓸 건데 굳이 인증이 필요한가?"라고 생각했습니다.

하지만 인터넷에 배포하는 순간:

무작위 IP에서 API 호출 시도
알 수 없는 사용자의 무차별 대입 공격
서비스 악용으로 인한 비용 폭탄

이 모든 것을 경험하면서 보안의 중요성을 뼈저리게 느꼈습니다.

JWT vs Session 비교

왜 JWT를 선택했나?

특성	JWT	Session
상태	Stateless (서버에 저장 안 함)	Stateful (서버에 세션 저장)
확장성	높음 (서버 간 공유 불필요)	낮음 (세션 공유 필요)
성능	빠름 (DB 조회 불필요)	느림 (매 요청마다 DB 조회)
보안	토큰 탈취 시 위험	서버에서 즉시 무효화 가능
크기	큰 편 (모든 정보 포함)	작음 (ID만 저장)

우리의 선택:

JWT의 장점 (Stateless, 확장성)
Session의 장점 (강제 로그아웃)
→ 하이브리드: JWT + Redis (Refresh Token 저장)

실전에서 체감한 효과

Before (인증 없음):

[새벽 3시] 알 수 없는 IP에서 AI 분석 API 1000회 호출
→ Google Gemini API 비용 $50 발생  
→ 누가 호출했는지 모름
→ 차단 방법 없음

After (JWT 인증 + Rate Limiting):

[새벽 3시] 알 수 없는 IP에서 로그인 시도
→ Rate Limiting: 분당 5회 제한
→ 5번 실패 후 차단
→ 보안 로그 기록
→ 비용 발생 없음 ✅

비용 절감 효과

인증 시스템 구현 전후:

AI API 비용: $100/월 → $20/월 (80% 절감)
서버 리소스: CPU 80% → 20% (정상 사용자만)
관리 시간: 주 5시간 → 주 1시간 (자동화)

다음 단계

이제 우리의 자동매매 시스템은:

✅ 데이터 수집 (한투/Upbit/yfinance)
✅ AI 분석 (Gemini)
✅ DB 저장 및 정규화
✅ 웹 대시보드
✅ 모니터링 (Grafana Stack)
✅ 프로덕션 배포 (HTTPS + 24시간)
✅ JWT 인증 + RBAC ← 완성!

추가로 고려할 수 있는 기능:

OAuth 2.0 소셜 로그인 (Google, GitHub)
2FA (TOTP, SMS)
API Key 관리 (서비스 간 인증)
Webhook 인증
감사 로그 대시보드

참고 자료: