krx-hj3415 README

krx-hj3415는 KRX 유니버스(현재 krx300)를 수집하고, DB의 기존 최신 데이터와 비교(diff)해서 latest/snapshot을 갱신하는 CLI 프로젝트입니다.

pyproject.toml 기준:

• 패키지명: krx-hj3415
• 버전: 2.4.0
• Python: >=3.11
• CLI 엔트리포인트: krx = krx_hj3415.cli:app

1. 프로젝트 기능 설명

이 프로젝트의 핵심 기능은 krx sync 명령 하나로 정리됩니다.

1. 외부 소스에서 KRX300 종목 목록을 수집
2. DB의 기존 universe latest와 비교(diff)
3. universe latest 저장
4. 옵션에 따라 universe snapshot 저장
5. 옵션에 따라 제거된 종목을 NFS 저장소에서도 실제 삭제

즉, 유니버스 동기화와 정리 작업을 한 번에 수행하는 운영용 CLI입니다.

2. 프로젝트 구조 설명

krx-hj3415/
├─ pyproject.toml
└─ src/krx_hj3415/
   ├─ cli.py                       # krx CLI 엔트리
   ├─ app/
   │  ├─ settings.py               # .env / 환경변수 설정 로딩
   │  ├─ composition.py            # DB/리소스/어댑터 조립
   │  ├─ usecases/sync_universe.py # 유니버스 동기화 유스케이스
   │  ├─ provider/                 # 외부 KRX 데이터 수집 구현
   │  ├─ adapters/                 # db2 어댑터
   │  ├─ domain/                   # diff 등 도메인 로직
   │  └─ ports/                    # 포트 인터페이스
   └─ .env

사용자는 보통 cli.py의 krx sync만 실행하면 되고, 코드 재사용 시 app/usecases와 app/composition을 사용하면 됩니다.

3. CLI 명령어 사용법 (예시 포함)

설치:

cd packages/krx-hj3415
python -m pip install -e .

도움말:

krx --help
krx sync --help

기본 실행:

krx sync

옵션 예시:

# snapshot 저장 안 함
krx sync --no-snapshot

# 유효 엑셀 URL 탐색 범위를 30일로 확장
krx sync --max-days 30

# removed 종목을 NFS latest/snapshot에서도 실제 삭제
krx sync --apply

옵션 설명:

• --apply: removed 종목 NFS 삭제 적용
• --snapshot/--no-snapshot: universe snapshot 저장 여부 (기본: --snapshot)
• --max-days: 엑셀 URL 탐색 최대 일수

주의:

• --max-days는 MAX_DAYS_MIN~MAX_DAYS_MAX 범위를 벗어나면 실패합니다.
• --apply는 실제 삭제 작업이므로 운영 환경에서 주의해서 사용해야 합니다.

4. 다른 프로젝트에서 임포트해서 사용하는 예시

CLI 대신 코드로 직접 실행할 수 있습니다.

import asyncio

from krx_hj3415.app.composition import build_components
from krx_hj3415.app.domain.types import UniverseEnum
from krx_hj3415.app.settings import get_settings
from krx_hj3415.app.usecases.sync_universe import run_sync


async def main() -> None:
    settings = get_settings()
    components = build_components(settings)
    try:
        await components.resources.bootstrap()
        result = await run_sync(
            components.universe_store,
            universe=UniverseEnum(settings.default_universe),
            max_days=15,
            snapshot=True,
        )
        print(result.universe, len(result.added), len(result.removed))
    finally:
        await components.resources.aclose()


asyncio.run(main())

5. 환경변수 설정 예시

이 프로젝트는 src/krx_hj3415/.env와 OS 환경변수를 함께 읽습니다.

# app
APP_NAME=krx
APP_ENV=prod
LOG_LEVEL=INFO

# db
MONGO_URI=mongodb://localhost:27017
MONGO_DB_NAME=hj3415
MONGO_CONNECT_TIMEOUT_MS=5000
MONGO_SERVER_SELECTION_TIMEOUT_MS=5000
SNAPSHOT_TTL_DAYS=730

# krx
DEFAULT_UNIVERSE=krx300
DEFAULT_MAX_DAYS=15
MAX_DAYS_MIN=1
MAX_DAYS_MAX=60
SOURCE_NAME=samsungfund
PRINT_LIMIT=50

운영 시 핵심:

• DEFAULT_UNIVERSE는 현재 구현상 krx300만 유효합니다.
• MongoDB 연결 정보가 없거나 잘못되면 동기화가 실패합니다.

7. Dockerfile + docker-compose.yml 사용 예시

이 프로젝트는 CLI 기반 단독 실행이 가능하므로 컨테이너 실행 예시를 함께 제공합니다.

Dockerfile 예시 (packages/krx-hj3415/Dockerfile):

FROM python:3.11-slim

WORKDIR /app
COPY . /app

RUN python -m pip install --upgrade pip && \
    python -m pip install .

ENTRYPOINT ["krx"]

docker-compose.yml 예시 (모노레포 루트 기준):

version: "3.9"

services:
  mongo:
    image: mongo:7
    ports:
      - "27017:27017"
    volumes:
      - mongo_data:/data/db

  krx:
    build:
      context: ./packages/krx-hj3415
      dockerfile: Dockerfile
    environment:
      APP_NAME: krx
      APP_ENV: prod
      LOG_LEVEL: INFO
      MONGO_URI: mongodb://mongo:27017
      MONGO_DB_NAME: hj3415
      DEFAULT_UNIVERSE: krx300
      DEFAULT_MAX_DAYS: "15"
      MAX_DAYS_MIN: "1"
      MAX_DAYS_MAX: "60"
      PRINT_LIMIT: "50"
    depends_on:
      - mongo
    command: ["sync", "--max-days", "15", "--snapshot"]

volumes:
  mongo_data:

실행:

docker compose up --build

단발성 명령 실행:

docker compose run --rm krx sync --max-days 30 --no-snapshot
docker compose run --rm krx sync --apply