프로젝트 폴더가 준비되었다면 그 안에서 코드를 실행할 Python 환경을 만든다. 이 장의 결과는 프로젝트 전용 .venv, 설치할 패키지 목록, 실제 실행 경로를 확인하는 점검 기록이다. API 접속과 데이터베이스 연결은 다음 장에서 진행한다.

예시의 C:\Users\minjun\auto-trading-lab은 가상 경로다. 자신의 프로젝트 위치로 바꾸고, PowerShell 명령은 그 폴더에서 실행한다.

내 환경에서 시작할 곳 찾기

Windows에서 Python 가상환경을 만들려면 사용할 Python 실행 파일을 정한 뒤, 프로젝트 폴더에 .venv를 만들고 그 실행 파일로 패키지를 설치한다. (.venv) 표시만으로 완료를 판단하지 않고 실제 경로를 확인한다.

• Python 설치 여부나 경로를 모른다면: 설치 상태 확인에서 사용할 실행 파일과 버전을 확인한다.
• Python은 있지만 .venv가 없다면: 가상환경 만들기에서 프로젝트 안의 .venv\Scripts\python.exe를 만든다.
• .venv는 있지만 패키지를 못 찾는다면: 실행 경로 점검으로 Python과 pip가 같은 환경을 가리키는지 확인한다.
• 실행 정책 때문에 활성화가 막힌다면: 활성화와 직접 실행에서 프로젝트 Python을 직접 지정하는 방법을 확인한다.

완료 후에는 외부 연결 없는 import 확인을 거쳐 한국투자증권 API 인증과 조회로 이동한다.

1. 설치 전에 현재 상태 확인하기

먼저 이미 설치된 Python과 편집기를 확인한다. 여러 Python을 구분하지 않고 설치를 반복하면 패키지를 넣은 환경과 프로그램을 실행하는 환경이 달라질 수 있다.

Get-Location
Get-Command python, py, code -ErrorAction SilentlyContinue
python --version
py --version

명령을 찾지 못했다는 결과는 해당 명령이 현재 터미널에서 보이지 않는다는 뜻이다. Python 자체가 없는 경우도 있고, 설치 직후라 터미널의 경로 정보가 갱신되지 않은 경우도 있다. 설치를 마쳤다면 PowerShell을 새로 열고 확인한다.

Codex에는 다음처럼 요청한다.

현재 auto-trading-lab 프로젝트의 Windows 실행 환경을 확인해줘.
Python 실행 파일의 위치와 버전, py 명령, VS Code 설치 여부를 조사해줘.
설치하거나 설정을 바꾸지 말고, 이미 있는 Python 중 이 프로젝트에서
사용할 후보와 확인하지 못한 항목을 구분해줘.

정상 결과는 버전 번호 하나가 아니라 어떤 실행 파일을 사용할지를 설명할 수 있는 상태다. VS Code는 파일을 읽기 위한 선택 도구이며 Python 실행에 필수는 아니다.

2. 지원 중인 Python 버전 정하기

Python 공식 문서는 버전의 상태를 기능 개발, 사전 공개, 버그 수정, 보안 수정 등으로 나눈다. 이 책에서는 Python LTS라는 별도 배포판을 가정하지 않는다. 2026년 10월 28일 확인한 지원표에서 3.14와 3.15는 버그 수정 단계다. 이 실습은 Python 3.14 계열을 기준으로 하되, 설치 시점의 패키지 호환성과 공식 지원 상태를 함께 확인한다. Python 공식 버전 지원표

설치는 Python 공식 Windows 안내를 따른다. Windows의 Python 설치 관리자와 기존 런처는 제공 명령이 다를 수 있으므로, 현재 설치 방식의 안내를 확인한다. 공식 다운로드 페이지에서 안정 버전을 선택하는 방법도 사용할 수 있다.

이 장에서는 기존 Python을 제거하거나 전역 기본값을 바꿀 필요가 없다. 3.14를 사용할 수 있는 환경이라면 다음처럼 명시적으로 확인한다.

py -3.14 --version
py -3.14 -c "import sys; print(sys.executable)"

3.14.x와 해당 Python의 경로가 표시되면 다음 단계로 간다. py를 사용할 수 없다면 설치된 python.exe의 전체 경로로 같은 명령을 실행한다. 예를 들어 확인한 경로가 C:\Python314\python.exe라면 PowerShell에서는 & 'C:\Python314\python.exe' --version처럼 호출한다. 이 경로는 형식 예시이며 자신의 PC에 같은 폴더가 있다고 가정하지 않는다. 지원이 끝난 버전이나 시험 버전을 우연히 선택한 상태에서는 패키지를 설치하기 전에 실행 파일부터 정한다.

3. 프로젝트 전용 가상환경 만들기

venv는 프로젝트마다 패키지를 따로 설치하는 표준 도구다. 코드와 설정은 프로젝트에 두고, 실행 파일과 설치 패키지는 .venv에 둔다. .venv는 다른 컴퓨터에 복사하기보다 설치 목록으로 다시 만든다. Python 공식 venv 설명

Set-Location 'C:\Users\minjun\auto-trading-lab'
py -3.14 -m venv .venv
Test-Path '.\.venv\Scripts\python.exe'

마지막 결과가 True이면 실행 파일이 생성된 것이다. 이미 .venv가 있다면 덮어 만들기 전에 그 환경의 버전과 설치 목록을 확인한다. 프로젝트 소스는 .venv 안에 작성하지 않는다.

이후 명령은 활성화 상태와 관계없이 프로젝트 Python을 직접 지정한다.

.\.venv\Scripts\python.exe --version
.\.venv\Scripts\python.exe -c "import sys; print(sys.executable); print(sys.prefix != sys.base_prefix)"
.\.venv\Scripts\python.exe -m pip --version

예상 결과는 .venv\Scripts\python.exe 경로, 가상환경 여부 True, .venv 아래의 pip 설치 경로다. 이 세 가지가 일치하면 전역 Python과 구분할 수 있다.

Python과 pip의 실행 경로가 다를 때

pip install은 성공했는데 ModuleNotFoundError가 나오면, 패키지를 설치한 Python과 코드를 실행한 Python부터 비교한다. 프로젝트 루트에서 다음 세 줄을 실행한다.

Get-Location
.\.venv\Scripts\python.exe -c "import sys; print(sys.executable)"
.\.venv\Scripts\python.exe -m pip --version

Python 경로가 현재 프로젝트의 .venv\Scripts\python.exe이고 pip 경로도 같은 .venv 안이면 환경이 일치한다. 실행 파일을 찾지 못하면 현재 폴더와 .venv 생성 여부를 먼저 확인한다. 이 두 경로가 확인되기 전에는 전역 Python에 패키지를 반복 설치하지 않는다.

py 명령이 실패해도 기존 .venv\Scripts\python.exe가 정상 실행된다면 그 경로로 계속 사용할 수 있다. 런처가 찾는 설치 목록과 프로젝트 가상환경의 실행 가능 여부는 따로 확인한다.

4. 활성화와 직접 실행 구분하기

매번 전체 경로를 입력하기 번거롭다면 현재 터미널에서 활성화할 수 있다.

.\.venv\Scripts\Activate.ps1
python -c "import sys; print(sys.executable)"

터미널 앞에 (.venv)가 나타나더라도 출력된 실행 파일을 확인한다. 활성화는 현재 터미널이 Python을 찾는 순서를 바꾸는 편의 기능이다. 새 터미널이나 작업 스케줄러에는 그 상태가 자동으로 이어지지 않는다.

실행 정책 때문에 Activate.ps1이 차단되면 이 장의 직접 경로 명령으로 계속 진행할 수 있다. 활성화를 위해 컴퓨터 전체의 실행 정책을 바꿀 필요는 없다. 조직에서 관리하는 PC라면 현재 정책과 관리 규칙을 먼저 확인한다. PowerShell 실행 정책 설명

활성화한 터미널에서 원래 상태로 돌아갈 때는 deactivate를 실행한다. 프로젝트 작업이 끝나도 .venv 폴더 자체는 남아 있다.

5. 필요한 패키지와 설치 목록 준비하기

이 책은 HTTP 조회에 requests, 표 데이터 처리에 pandas, 설정 파일 읽기에 python-dotenv, MySQL 연결에 mysql-connector-python을 사용한다. 처음에는 이 네 가지로 시작한다. 실시간 웹소켓이나 차트 라이브러리는 해당 기능이 필요해질 때 추가한다.

프로젝트 루트의 requirements.in에 다음 내용을 저장한다. 이 파일은 직접 선택한 의존성 목록이다.

requests
pandas
python-dotenv
mysql-connector-python

프로젝트 가상환경에 설치한다. 기존 프로젝트에 검증된 requirements.txt가 있다면 새 목록을 만들기보다 그 파일을 우선 사용한다.

.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.in
.\.venv\Scripts\python.exe -m pip check

정상 결과는 의존성 충돌 없이 설치가 끝나는 것이다. pip check가 통과한 뒤 설치된 정확한 버전을 기록한다. PowerShell 5.1에서도 텍스트 인코딩이 명확하도록 다음처럼 저장한다.

.\.venv\Scripts\python.exe -m pip freeze | Set-Content -Encoding UTF8 requirements.txt
Get-Content -Encoding UTF8 requirements.txt

다른 컴퓨터에서는 같은 Python 계열로 .venv를 새로 만든 뒤 -m pip install -r requirements.txt로 설치한다. 운영체제와 Python 버전도 함께 기록해야 재현 범위를 이해할 수 있다. Python Packaging 공식 설치 안내

6. 외부 연결 없이 최소 실행 확인하기

패키지가 설치됐는지 확인하는 명령은 외부 API에 접속하지 않는다.

.\.venv\Scripts\python.exe -c "import requests, pandas, dotenv, mysql.connector; print('imports OK')"

imports OK가 출력되면 이번 장의 import 확인이 끝난다. 패키지 이름 python-dotenv와 Python에서 사용하는 모듈 이름 dotenv가 다른 점에 주의한다.

프로젝트에 이미 src의 Python 파일이 있다면 문법도 확인할 수 있다.

.\.venv\Scripts\python.exe -m compileall -q src

출력이 없고 종료 코드가 0이면 문법 검사에서 오류가 발견되지 않은 것이다. 이 검사는 API 인증, SQL 실행, 계산식의 정확성까지 증명하지 않는다. 각 단계의 실제 동작은 해당 장에서 별도로 확인한다.

Git을 사용한다면 .gitignore에 .venv/, config/.env, config/*token*, logs/를 포함한다. 공유할 결과 파일에 개인 정보가 없는지도 확인한다. 이 제외 목록은 나중에 만드는 파일의 비밀값 검토를 대신하지 않는다.

7. 오류를 실행 경로부터 좁히기

설치 오류를 해결하려고 TLS 검증을 끄거나 임의의 패키지 파일을 내려받지 않는다. 오류의 원인이 Python 버전, 네트워크, 패키지 호환성 중 어디에 있는지 나누어 확인한다.

8. 완료 기록 남기기

docs/environment-check.md에는 Python 버전, 실행 파일 경로, 패키지 설치 목록, pip check와 import 확인 결과를 적는다. 실제로 실행하지 않은 명령은 “미실행”으로 표시한다.

다음 네 가지가 맞으면 3장의 인증 준비로 넘어간다.

• 프로젝트 전용 .venv 실행 파일이 확인된다.
• 필요한 패키지를 같은 환경에서 import할 수 있다.
• requirements.txt에 설치 버전이 기록되어 있다.
• 비밀 설정과 .venv를 공유 대상에서 제외했다.

이 장의 명령은 환경 준비 예시다. 문서 자체가 독자의 컴퓨터에 Python이나 패키지를 설치하지 않으며, 설치 성공 여부는 자신의 실행 결과로 확인한다.

한국투자증권 Open API와 연결할 때 첫 결과는 주문 체결이 아니라 인증 성공과 시세 한 건의 조회다. 이 장에서는 개인 설정을 코드에서 분리하고, 인증과 정해진 시세 조회만 수행하는 클라이언트를 만든다.

앞 장의 .venv와 패키지가 준비되어 있어야 한다. 계좌 개설, Open API 서비스 신청, 모의투자 이용 조건은 한국투자증권의 현재 안내에서 확인한다. 문서에 나온 키·계좌 정보는 모두 자리표시자이며 실제 값을 채팅이나 Git에 붙여 넣지 않는다.

인증과 현재가 조회까지 가는 순서

처음 연결한다면 아래 세 단계를 차례로 진행한다. 이미 설정을 마쳤다면 한 종목 조회부터 실행하고, 실패한 단계가 있으면 오류 대응으로 이동한다.

1. 프로젝트 Python을 확인한다. 앞 장의 환경 점검으로 같은 .venv에서 requests와 dotenv를 import할 수 있는지 확인한다.
2. 조회 도구를 작성한다. 개인 설정과 인증·조회 코드를 만든다. 선택한 서버와 키의 환경이 같고 문법 검사에 통과하면 다음 단계로 간다.
3. 현재가 한 건을 확인한다. 프로젝트 루트에서 4절의 명령으로 src.check_kis를 실행한다. 환경·종목코드·양의 가격과 quotation OK가 표시되면 이번 장의 조회 확인이 끝난다.

이 장에서 만들 파일은 config/example.env, 개인용 config/.env, src/kis_readonly.py, src/check_kis.py다. 먼저 아래 본문을 따라 파일을 작성한 뒤 4절의 실행 명령을 사용한다. .venv가 없다면 Python 환경 준비로 돌아간다.

1. 서버 환경과 프로그램 실행 모드 구분하기

한국투자증권은 실전과 모의투자 환경을 구분한다. 공식 예제도 각 환경의 앱 키와 앱 시크릿을 따로 선택한다. 여기서는 서버 선택을 KIS_ENV, 프로젝트의 동작 범위를 RUN_MODE로 나눈다. 한국투자증권 공식 저장소

mock은 증권사 서버 환경이다. 뒤에서 만드는 paper는 우리 프로그램이 가상 주문을 장부에 기록하는 모드다. 둘은 같은 개념이 아니다. 모의투자 서버를 사용하더라도 주문 API를 호출하면 증권사 모의 주문이 발생할 수 있으므로, 이번 클라이언트에는 주문 메서드를 만들지 않는다.

실전 서버로 시세를 조회할 수 있다는 사실과 실전 주문을 허용한다는 것은 별개다. 이번 장의 예제는 서버 선택과 무관하게 인증 POST와 지정한 시세 GET만 제공한다.

2. 개인 설정 파일 만들기

공유용 config/example.env에는 다음 항목만 둔다.

RUN_MODE=read_only
KIS_ENV=mock
KIS_APP_KEY=REPLACE_WITH_YOUR_KEY
KIS_APP_SECRET=REPLACE_WITH_YOUR_SECRET

이 파일을 로컬의 config/.env로 복사하고, 자신이 발급받은 해당 환경의 값을 입력한다. 현재가 조회에는 계좌번호를 보내지 않으므로 이 장에서 계좌 정보를 추가할 필요가 없다.

if (-not (Test-Path -LiteralPath 'config/.env')) {
    Copy-Item -LiteralPath 'config/example.env' -Destination 'config/.env'
}

이미 config/.env가 있다면 복사로 덮어쓰지 말고 필요한 항목만 보완한다. 이 책은 dotenv_values로 지정 파일을 직접 읽는다. 운영체제 환경변수가 우연히 같은 이름으로 존재해도 자동으로 섞지 않는다. python-dotenv 공식 문서

Git의 제외 대상에 config/.env가 있는지 확인한다. 앱 시크릿을 잘못 공개했다면 파일에서 지우는 것만으로 끝내지 말고 발급처에서 폐기·재발급 절차를 진행한다. 토큰도 인증 수단이므로 화면이나 로그에 원문을 출력하지 않는다.

3. 인증과 시세 조회 코드 작성하기

src/kis_readonly.py에 다음 코드를 저장한다. 종목코드는 ASCII 숫자와 영문 대문자를 조합한 6자리 문자열로 받는다. 005930의 앞자리 0을 보존하고 0126Z0 같은 영문 포함 코드도 허용한다. 소문자나 다른 문자 체계의 숫자를 임의 변환하지 않는다. 예제는 한 프로세스 안에서 발급받은 토큰을 재사용한다. 호출할 때마다 새 토큰을 요청하지 않도록 클라이언트도 한 번 만들어 재사용한다.

인증 경로와 서버 주소는 공식 인증 예제를 확인했다. 토큰의 발급 제한·만료 정책은 바뀔 수 있으므로 반복 운영에 들어가기 전에는 공식 안내에 맞춰 만료 시각 관리와 안전한 캐시를 추가한다.

from pathlib import Path
import re

import requests
from dotenv import dotenv_values

ROOT = Path(__file__).resolve().parents[1]
SERVERS = {
    "mock": "https://openapivts.koreainvestment.com:29443",
    "live": "https://openapi.koreainvestment.com:9443",
}
QUOTATIONS = {
    "price": (
        "/uapi/domestic-stock/v1/quotations/inquire-price",
        "FHKST01010100",
    ),
    "daily": (
        "/uapi/domestic-stock/v1/quotations/inquire-daily-itemchartprice",
        "FHKST03010100",
    ),
}


def load_config():
    path = ROOT / "config" / ".env"
    if not path.is_file():
        raise FileNotFoundError("config/.env is missing")
    return dict(dotenv_values(path, encoding="utf-8-sig"))


class ReadOnlyKis:
    def __init__(self, config):
        mode = config.get("RUN_MODE", "read_only")
        if mode not in {"read_only", "paper"}:
            raise ValueError("This client is for read_only or local paper mode")
        env = config.get("KIS_ENV", "mock")
        if env not in SERVERS:
            raise ValueError("KIS_ENV must be mock or live")
        self.base_url = SERVERS[env]
        self.key = config.get("KIS_APP_KEY") or ""
        self.secret = config.get("KIS_APP_SECRET") or ""
        if any(not v or v.startswith("REPLACE_") for v in (self.key, self.secret)):
            raise ValueError("KIS credentials are not configured")
        self.session = requests.Session()
        self.token = None

    @staticmethod
    def _json(response):
        if response.status_code != 200:
            raise RuntimeError(f"KIS HTTP error: {response.status_code}")
        try:
            body = response.json()
        except ValueError as exc:
            raise RuntimeError("KIS returned non-JSON content") from exc
        if not isinstance(body, dict):
            raise RuntimeError("KIS returned an unexpected JSON structure")
        return body

    def authenticate(self):
        if self.token:
            return
        response = self.session.post(
            self.base_url + "/oauth2/tokenP",
            json={
                "grant_type": "client_credentials",
                "appkey": self.key,
                "appsecret": self.secret,
            },
            timeout=(5, 20),
        )
        body = self._json(response)
        token = body.get("access_token")
        if not isinstance(token, str) or not token:
            raise RuntimeError("KIS authentication failed; check the API portal")
        self.token = token

    def quotations(self, kind, params):
        if kind not in QUOTATIONS:
            raise ValueError("Unsupported quotation kind")
        self.authenticate()
        path, tr_id = QUOTATIONS[kind]
        response = self.session.get(
            self.base_url + path,
            headers={
                "authorization": f"Bearer {self.token}",
                "appkey": self.key,
                "appsecret": self.secret,
                "tr_id": tr_id,
                "custtype": "P",
            },
            params=params,
            timeout=(5, 20),
        )
        body = self._json(response)
        if body.get("rt_cd") != "0":
            code = str(body.get("msg_cd", "unknown"))[:40]
            raise RuntimeError(f"KIS quotation rejected: {code}")
        return body

    def current_price(self, symbol):
        if not re.fullmatch(r"[A-Z0-9]{6}", symbol):
            raise ValueError("A six-character uppercase ASCII stock symbol is required")
        body = self.quotations("price", {
            "FID_COND_MRKT_DIV_CODE": "J",
            "FID_INPUT_ISCD": symbol,
        })
        output = body.get("output")
        if not isinstance(output, dict):
            raise RuntimeError("Price output is missing")
        price = output.get("stck_prpr")
        if not isinstance(price, str) or not re.fullmatch(r"[0-9]+", price) or int(price) <= 0:
            raise RuntimeError("Price must be a positive integer")
        return output

    def close(self):
        self.session.close()

RUN_MODE=paper 허용은 뒤의 로컬 페이퍼 실행에서 같은 시세 조회기를 재사용하기 위한 것이다. 이 허용이 주문 기능을 추가하지는 않는다. URL을 외부 입력으로 받지 않고 QUOTATIONS의 두 경로만 선택하므로 코드의 동작 범위를 읽고 확인할 수 있다.

현재가 경로·거래 ID·필수 파라미터는 공식 현재가 조회 예제를 기준으로 했다. 이 예제의 J는 KRX 시장 구분이다. 다른 시장 구분을 사용할 때는 데이터의 시장 기준까지 함께 바꿔야 한다.

4. 한 종목만 조회하기

공식 예제에서 사용하는 005930은 종목코드 형식을 확인하기 위한 입력이다. 특정 종목에 대한 투자 제안이 아니다. src/check_kis.py를 다음처럼 작성한다.

from src.kis_readonly import ReadOnlyKis, load_config


def main():
    config = load_config()
    client = ReadOnlyKis(config)
    try:
        output = client.current_price("005930")
        price = int(output["stck_prpr"])
        print(f"env={config.get('KIS_ENV', 'mock')} symbol=005930 price={price}")
        print("quotation OK; credentials and token omitted")
    finally:
        client.close()


if __name__ == "__main__":
    main()

프로젝트 루트에서 먼저 문법을 확인하고, 설정을 준비한 뒤 조회를 실행한다.

.\.venv\Scripts\python.exe -m py_compile src/kis_readonly.py src/check_kis.py
.\.venv\Scripts\python.exe -m src.check_kis

실제 출력의 가격은 조회 시점에 따라 달라진다. 성공 기준은 양의 가격이 파싱되고, 환경과 종목코드가 표시되며, 키·토큰·요청 헤더가 출력되지 않는 것이다. HTTP 응답이 200이어도 업무 결과 코드가 실패일 수 있으므로 코드에서 rt_cd를 별도로 검사한다.

출력 형식은 다음과 같다. <조회한 양의 정수>는 실제로 표시될 가격을 설명하는 자리표시자이며 실행 결과나 현재 시세가 아니다.

env=mock symbol=005930 price=<조회한 양의 정수>
quotation OK; credentials and token omitted

문법 검사만 통과한 경우에는 인증 성공으로 기록하지 않는다. quotation OK가 표시되지 않으면 실패한 단계와 오류 코드를 확인하고, 토큰이나 전체 응답을 복사해 공유하지 않는다.

이 장에서는 조회 실패를 자동으로 무한 재시도하지 않는다. 네트워크 타임아웃은 요청이 끝나지 않은 상황, 인증 실패는 자격 증명 문제, 업무 오류는 서버가 요청을 거절한 상황으로 구분한다. Requests의 타임아웃과 예외 의미는 공식 Quickstart에서 확인할 수 있다.

5. Codex에 구현과 검증 범위 전달하기

auto-trading-lab에 한국투자증권 조회 클라이언트를 만들어줘.
config/.env를 직접 읽고 KIS_ENV=mock|live와 RUN_MODE를 구분해줘.
인증 POST, 현재가 GET, 기간별 일봉 GET만 허용하고 임의 URL 입력은 받지 마.
키·시크릿·토큰·전체 헤더와 전체 응답은 로그에 출력하지 마.
공식 예제에서 현재 파라미터와 거래 ID를 확인해 출처를 기록해줘.
먼저 가짜 응답으로 성공, HTTP 오류, rt_cd 실패, 빈 output을 검사해줘.
실제 접속을 실행했는지, 문법·가짜 응답만 검사했는지 구분해서 보고해줘.
주문 함수, 잔고 변경, 증권사 모의 주문도 이번 작업에 추가하지 마.

가짜 응답 검사는 실제 키 없이도 오류 처리와 파싱을 확인하는 방법이다. 인증이 실제로 성공했다는 증거는 자신의 계정으로 실행한 조회 결과여야 한다.

6. 오류 대응과 완료 기준

실패 원인을 확인하기 전에 모의 설정을 실전으로 바꾸거나 요청 수를 늘리지 않는다. 조회 가능 범위와 한도는 한국투자증권 API 포털의 현재 안내를 따른다.

완료 기록에는 사용 환경, 시세 조회 종류, 결과 코드, 확인 일시를 남긴다. 키와 토큰을 기록하지 않고도 인증과 조회가 어디까지 성공했는지 설명할 수 있어야 한다. 다음 장에서는 같은 클라이언트로 일봉 데이터를 수집한다.

시세 한 건을 읽었다면 코스피200 데이터 수집으로 이어간다. 여러 프로그램이 인증을 반복하는 문제가 생겼을 때는 토큰을 여러 실행기에서 공유한 개발 사례를 참고한다. 첫 조회를 마치기 전에 토큰 공유 구조부터 추가할 필요는 없다.

Codex 프로젝트 폴더 설정은 어느 로컬 폴더의 파일을 읽고 만들지 정하고, 실제 작업 경로를 확인하는 과정이다. Windows에서 전용 폴더를 연결한 뒤 경로와 파일 목록을 대조하면 된다. 이 장은 그 확인부터 기본 폴더 구조 만들기까지 안내한다.

이 책의 새 요청문에서는 프로젝트 이름을 auto-trading-lab으로 통일한다. 이 장의 화면에 보이는 kospi200_auto_trading도 같은 역할의 작업 폴더다. 이미 정한 폴더가 있다면 이름을 바꾸지 않고 실제 경로를 그대로 사용한다.

이 글은 《Codex로 시작하는 자동매매 시스템 만들기》 1장의 웹 편집본이다. Windows 로컬 프로젝트를 기준으로 설명한다. 예시 경로의 minjun은 가상 사용자명이므로 자신의 Windows 사용자명으로 바꾼다.

Codex 작업 폴더, 먼저 이렇게 확인하세요

설치와 로그인이 끝났다면 아래 세 단계부터 진행한다. 앱 준비가 필요하면 뒤의 설치 안내부터 읽는다.

1. Windows에서 자동매매 전용 폴더를 만들고 로컬 프로젝트에 연결한다. 예시는 C:\Users\minjun\auto-trading-lab이며 이미 쓰는 폴더가 있으면 그 실제 경로를 사용한다.
2. 여러 폴더가 연결돼 있다면 사용할 폴더를 가리켜 Make primary(기본 폴더)로 정한다. 연결 폴더를 추가하거나 바꾸려면 프로젝트의 Edit project를 연다. 메뉴가 다르면 공식 프로젝트 안내를 확인한다.
3. Codex에 아래 요청을 보내 기대한 경로와 보고된 경로가 같은지 확인한다. 다른 위치라면 파일을 만들기 전에 경로 문제 해결로 돌아간다.

현재 작업 폴더의 절대 경로와 바로 아래 파일·폴더 목록을 확인해줘.
기대한 경로는 C:\Users\minjun\auto-trading-lab 이야.
아직 파일을 만들거나 수정하지 말고, 실제 경로가 다른지 알려줘.

minjun은 가상 사용자명이다. 자신의 사용자명과 프로젝트 경로로 바꾼다. 이 블록은 터미널 명령이 아니라 Codex에 보내는 요청문이다.

경로가 맞으면 기본 구조 만들기로 이동한다. 이미 여섯 하위 폴더가 준비됐다면 완료 기준을 확인한 뒤 2장: Python 전용 가상환경 준비하기로 이어간다.

준비물과 이번 장의 결과

준비물은 Windows 컴퓨터, 인터넷 연결, ChatGPT 데스크톱 앱에서 Codex를 사용할 수 있는 계정이다. Python 설치와 API 계정 준비는 뒤의 장에서 다룬다.

완료 결과는 다음과 같다.

• 사용자가 위치를 정한 프로젝트 전용 폴더
• Codex가 보고한 현재 작업 경로와 폴더 목록
• docs, scripts, src, config, logs, outputs 기본 구조
• 파일 작업·민감정보·주문 기능에 대한 프로젝트 작업 규칙

1. 파일과 터미널을 함께 다루는 개발 도구

자동매매 시스템을 만들려면 Python 파일만 작성하는 것으로 끝나지 않는다. 설정 파일을 구분하고, 실행 스크립트를 만들고, 수집 결과와 오류 로그를 찾아야 한다. Codex는 프로젝트의 파일을 읽고 수정하며 명령을 실행하는 개발 작업에 사용할 수 있다. 이 책은 그 작업을 작은 단계로 나누어 진행한다.

처음부터 “자동매매 프로그램을 만들어줘”라고 요청하면 작업 범위가 너무 넓다. “현재 폴더를 확인해줘”, “폴더 구조만 제안해줘”, “아직 파일은 만들지 말고 계획만 설명해줘”처럼 결과가 분명한 요청부터 시작한다. 파일을 어디에 만들었는지, 어떤 명령을 실행했는지, 결과가 무엇인지 확인한 뒤 다음 단계로 넘어간다.

현재 앱 이름과 설치 경로

책 초안의 Codex Desktop은 당시 데스크톱 작업 환경을 가리키는 표현이다. 2026년 10월 26일 다시 확인한 공식 문서는 ChatGPT 데스크톱 앱에서 Codex를 선택하는 흐름으로 안내한다. 아래 순서로 준비한다.

1. OpenAI 공식 데스크톱 앱 안내에서 운영체제에 맞는 설치 안내를 연다.
2. 앱을 실행하고 ChatGPT 계정으로 로그인한다.
3. 새 작업에서 ChatGPT 선택 메뉴의 Codex를 선택한다.
4. 프로젝트 또는 폴더를 열고 이번 작업이 사용할 위치를 확인한다.

메뉴 이름이나 위치가 다르면 공식 시작 안내의 데스크톱 설정을 확인한다. 여기서 사용하는 것은 로컬 폴더의 파일을 다루는 작업이다.

2. 시작 전에 확인할 비용과 실행 조건

컴퓨터를 계속 켜두어야 하나요?

이번 장은 컴퓨터에서 프로젝트 폴더를 만들고 상태를 확인하는 작업이다. 작업하는 동안 앱과 컴퓨터가 실행 중이어야 한다. 자동매매 프로그램을 장중에 반복 실행하는 환경은 별도로 정한다. 개인 PC, 미니 PC, 서버 등 어느 환경을 사용하든 전원·인터넷·스케줄러·로그·중단 조건을 함께 관리해야 한다.

이 책에서 만드는 자동매매 프로그램의 일일 실행 환경과 Codex를 사용하는 개발 환경을 구분한다. 먼저 로컬 폴더, 데이터 조회, 저장과 검증을 준비하고 운영 환경은 뒤에서 다룬다.

유료 구독이 꼭 필요한가요?

사용 가능한 기능과 사용량은 로그인 방식, 계정의 플랜, 워크스페이스 설정과 제공 시점에 따라 달라진다. 현재 공식 가격·기능 안내에는 무료 플랜의 일부 Codex 제공도 안내되어 있으며 적용 여부는 계정에서 확인해야 한다. 이 장을 위해 특정 유료 상품을 먼저 구입할 필요가 있다고 가정하지 않는다.

앱에서 Codex 작업을 시작할 수 있는지 먼저 확인한다. 개발량이 늘어난 뒤 현재 사용량과 필요한 기능을 보고 이용 방식을 결정한다. 이 글에는 바뀔 수 있는 가격이나 고정된 작업 횟수를 적지 않는다.

토큰과 사용량은 어떻게 이해하면 되나요?

Codex는 요청, 파일, 대화 기록, 도구 결과를 읽고 답변을 생성하면서 사용량을 쓴다. 여러 파일을 비교하거나 오류 수정을 반복하면 작업량이 커질 수 있다. 필요한 파일과 성공 기준을 함께 전달하면 결과를 확인하기 쉽다.

구독의 포함 사용량과 API 사용료는 서로 다른 기준이다. 잔여 사용량과 초기화 시점은 자신의 계정에 표시되는 정보를 확인한다. 자세한 기준은 공식 가격 안내의 사용량 설명을 따른다.

ChatGPT 로그인과 API 키 로그인은 무엇이 다른가요?

공식 문서는 구독 접근을 위한 ChatGPT 로그인과 사용량 기반 접근을 위한 API 키 로그인을 구분한다. API 키로 사용하면 OpenAI Platform의 API 사용료가 적용되고 일부 기능의 제공 범위가 달라질 수 있다. 이 장은 ChatGPT 계정 로그인으로 설명하며 API 키를 발급하거나 문서에 입력하지 않는다. OpenAI 공식 인증 안내

Codex가 자동매매 프로그램을 계속 운영하나요?

이 책에서는 Codex를 설계·구현·오류 확인을 돕는 개발 도구로 사용한다. 매일 실행되는 자동매매 프로그램은 사용자가 정한 실행 환경에서 동작하도록 구성한다. 실행 환경이 켜져 있는지, 로그가 남는지, 오류가 났을 때 멈추는지는 프로그램의 운영 항목으로 확인한다.

3. 현재 작업 위치부터 확인하기

설치와 로그인이 끝났다면 현재 폴더를 먼저 확인한다. 아래 블록은 PowerShell 명령이 아니라 Codex에 입력할 요청문이다. 교육용 화면은 누르면 원본 크기로 열어 볼 수 있다.

현재 Codex가 보고 있는 작업 폴더 위치를 알려줘.
파일 생성이나 수정은 하지 말고, 현재 경로만 확인해줘.

화면 예시 1-A. 교육용 재현 화면이다. 현재 앱의 실제 캡처가 아니며, 응답과 화면 구성은 앱 버전 및 프로젝트 상태에 따라 달라질 수 있다.

현재 폴더를 모른 채 작업을 시작하면 파일이 예상하지 못한 곳에 생길 수 있다. 다음 세 가지를 확인한다.

공식 문서에 따르면 로컬 프로젝트에는 여러 폴더를 연결할 수 있다. 새 작업의 기본 위치는 기본 폴더에 영향을 받으므로, 처음에는 자동매매 전용 폴더 하나로 시작한다. 공식 프로젝트·폴더 안내

4. 전용 프로젝트 폴더의 위치 정하기

이 책에서는 사용자가 Windows 파일 탐색기에서 직접 폴더를 만들고 Codex의 로컬 프로젝트로 여는 방식으로 진행한다. 먼저 위치를 정해두면 파일을 찾거나 백업할 때 기준이 된다.

Windows 사용자 폴더의 예시는 다음과 같다.

C:\Users\사용자명\

가상 사용자 minjun의 프로젝트 위치는 다음과 같다.

C:\Users\minjun\auto-trading-lab

사용자 폴더 아래의 전용 경로를 쓰면 시스템 프로그램 폴더와 구분하기 쉽다. C:\Program Files처럼 프로그램 설치를 위한 경로는 이번 프로젝트 위치로 사용하지 않는다. 프로젝트를 백업할 때도 폴더 하나를 기준으로 관리할 수 있다. 실제 비밀값이 들어 있는 설정과 로그는 공유용 사본에 포함하지 않는다.

폴더를 연 뒤 작업 범위를 다음처럼 전달한다. 요청문에 적는 경로도 자신의 실제 작업 폴더로 바꾼다.

앞으로 모든 작업은 C:\Users\minjun\auto-trading-lab 폴더 안에서만 진행해줘.

화면 예시 1-B. 프로젝트 범위를 전달하는 교육용 재현 화면이다. 요청문은 작업 목적을 설명하는 예시이며 앱의 폴더 권한 설정을 대신하지 않는다.

5. 폴더를 만들고 Codex에서 확인하기

1. 파일 탐색기에서 자신의 Windows 사용자 폴더를 연다.
2. auto-trading-lab이라는 새 폴더를 만든다.
3. 앱에서 이 폴더를 로컬 프로젝트에 연결해 연다.
4. 여러 폴더가 연결되어 있다면 이번 폴더가 기본 작업 위치인지 확인한다.

현재 문서의 메뉴 안내와 앱이 다르면 공식 프로젝트 문서를 참고한다. Codex에 아래 확인을 요청한다.

현재 작업 폴더가 C:\Users\minjun\auto-trading-lab 인지 확인해줘.
파일 생성이나 수정은 하지 말고, 현재 경로와 폴더 안의 파일 목록만 알려줘.

화면 예시 1-C. 프로젝트 폴더와 파일 목록을 확인하는 교육용 재현 화면이다.

정상 결과는 사용자가 정한 경로와 실제 파일 목록이 함께 보고되는 것이다. 새 폴더라면 비어 있거나 사용자가 알고 있는 파일만 있어야 한다. 이미 파일이 있다면 삭제부터 하지 말고 어떤 자료인지 확인한다.

프로젝트 위치 확인 흐름

그림 1-1. 원고의 Mermaid 흐름도를 웹용 SVG로 다시 그렸다. 원하는 경로가 아니면 전용 폴더를 열고 경로 확인으로 돌아간다.

도표를 읽기 어려운 경우에는 로그인 → 현재 경로 확인 → 올바른 전용 폴더 열기 → 파일 목록 확인 → 기본 폴더 구조 제안 순서로 진행하면 된다.

6. 기본 폴더 구조를 제안받고 만들기

프로젝트 위치가 확인되었다면 필요한 기본 구조만 먼저 제안받는다.

이 폴더는 한국투자증권 Open API를 이용해 코스피200 자동매매 시스템을 만들기 위한 프로젝트 폴더다.
아직 파일을 만들지 말고, 필요한 기본 폴더 구조만 제안해줘.
각 폴더의 역할도 함께 설명해줘.

화면 예시 1-D. 폴더를 만들기 전에 구조를 검토하는 교육용 재현 화면이다.

초기 구조는 다음 정도면 충분하다.

공개 예시 설정에는 필요한 항목 이름만 담고, 실제 인증정보는 개인용 설정으로 구분한다. 이번 장에서는 인증정보를 만들거나 입력하지 않는다.

제안한 구조가 적절하고 작업 위치도 맞다면 폴더 생성을 요청한다. 이 예시의 생성 대상은 위의 여섯 하위 폴더다.

방금 제안한 구조대로 docs, scripts, src, config, logs, outputs 폴더를 생성해줘.
기존 파일은 덮어쓰지 말고, 생성 후 실제 폴더가 존재하는지 확인해줘.
새로 만든 폴더와 원래 있던 폴더를 구분해서 알려줘.

화면 예시 1-E. 생성 뒤 존재 여부를 확인하는 교육용 재현 화면이다. 화면의 문구는 앞선 원고 예시를 바탕으로 했으며 실제 결과 보고 형식은 달라질 수 있다.

탐색기에서도 여섯 폴더가 프로젝트 폴더 바로 아래에 있는지 확인한다. 생성했다고 답한 것과 실제 경로가 일치하는지 확인하는 과정까지가 이 단계의 완료 기준이다.

7. 프로젝트 작업 규칙을 전달하기

파일을 만들고 명령을 실행하는 작업에서는 범위와 완료 기준을 함께 전달해야 한다. 다음은 독자가 자신의 프로젝트에 맞춰 사용할 수 있는 요청문 예시다.

앞으로 이 프로젝트에서는 다음 규칙을 지켜줘.

1. 모든 작업은 C:\Users\minjun\auto-trading-lab 폴더 안에서 진행해줘.
2. 작업 목적과 수정할 범위를 설명하고, 요청한 범위의 결과를 확인해줘.
3. 읽기 전용으로 확인해 달라고 한 단계에서는 파일을 수정하지 마.
4. App Key, App Secret, 계좌번호, 비밀번호는 공개 예시와 로그에 직접 쓰지 마.
5. 이번 학습 단계에서는 실전 주문 기능을 구현하거나 주문 API를 호출하지 마.
6. 명령을 실행할 때는 실행 목적과 예상 결과를 알려줘.
7. 작업 후에는 수정한 파일, 실행한 명령, 확인 결과를 정리해줘.

화면 예시 1-F. 기존 원고에 포함된 교육용 재현 화면이다. 위 웹 요청문은 읽기 전용 확인과 승인된 파일 생성을 구분하도록 다듬었다. 화면에는 당시 원고의 확인 문구가 남아 있어 현재 요청문과 일부 다르다.

요청문으로 범위를 설명하는 것과 앱에서 허용한 접근 권한은 별개다. 프로젝트에 필요한 폴더만 연결하고 실제 실행 결과를 확인한다. 작업 규칙을 전달한 뒤 Codex가 작업 위치, 민감정보 처리, 이번 단계의 실행 범위와 결과 보고 방법을 이해했는지 확인한다.

8. 이 장의 완료 기준과 문제 해결

작업 경로가 다르거나 폴더가 보이지 않을 때

요청문에 경로를 적는 것만으로 앱의 접근 권한이나 연결 폴더가 바뀌지는 않는다. 폴더 연결과 권한은 앱에서 확인하고, 현재 대화의 위치는 다시 조회한다.

위치가 헷갈리면 다음 요청으로 돌아간다.

현재 Codex가 보고 있는 작업 폴더 위치를 알려줘.
파일 생성이나 수정은 하지 말고, 현재 경로와 폴더 안의 파일 목록만 확인해줘.

자주 막히는 질문

폴더 이름은 예시와 똑같아야 하나요?

아니다. 이미 쓰는 전용 폴더가 있다면 이름을 바꿀 필요가 없다. 예제의 경로를 실제 위치로 바꾸고 요청·응답·파일 탐색기에 표시된 경로가 같은지 확인한다.

기본 폴더를 바꾼 뒤에는 바로 작업해도 되나요?

새 대화가 시작하는 기본 위치와 현재 대화의 위치를 구분한다. 기본 폴더를 바꾼 뒤에도 파일을 만들기 전 경로를 확인한다. 기존 대화의 위치가 다르면 원하는 폴더에서 새 Codex 대화를 시작하는 편이 확인하기 쉽다.

이 장에서 Python이나 증권사 API 키도 준비하나요?

이 장의 완료 기준은 작업 위치와 기본 폴더 구조다. Python과 가상환경은 2장, 증권사 API 준비는 3장에서 진행한다. 아직 실행 코드가 없다는 이유로 이 단계에서 키나 계좌 정보를 입력할 필요는 없다.

지금 상태에 맞는 다음 문서

• 폴더와 기본 구조를 확인했다면: 2장: Python 실행 경로와 빈 venv 확인하기. 다음 장에서는 이 프로젝트에서 사용할 Python 환경을 준비한다.
• 결과를 읽는 순서부터 알고 싶다면: KOSPI200 백테스트의 기간·청산 거래·비용 읽기. 개발 환경 준비와 결과 해석을 구분해 볼 수 있다.
• 전체 읽기 경로를 보관하려면: 주간 읽기 01: 자동매매를 시작하는 순서. 준비·인증·검증 중 자신의 단계에 맞는 문서를 고를 수 있다.

출처와 웹 편집 기록

원고의 1장에 있던 작업 위치 확인, 폴더 구조, 오류 점검, 여섯 교육용 화면을 바탕으로 웹에서 읽을 수 있도록 편집했다. 프로젝트·시작·인증·사용량 공식 문서의 이번 확인일은 2026년 10월 26일이다. 앱 메뉴와 계정 안내는 아래 공식 문서를 대조했으며, 새 컴퓨터에서 설치부터 재현한 검증을 뜻하지 않는다.

• OpenAI 공식 데스크톱 앱 안내: 현재 앱 명칭과 시작 흐름.
• OpenAI 공식 시작 안내: 로그인, 폴더 선택, Codex 작업 시작.
• OpenAI 공식 프로젝트 안내: 로컬 폴더 연결과 기본 작업 위치.
• OpenAI 공식 인증 안내: ChatGPT 로그인과 API 키 로그인 구분.
• OpenAI 공식 가격·사용량 안내: 계정별 기능과 이용 범위 확인.

이번 웹 개정에서는 경로 확인 요청문을 앞에 두고, 폴더 문제 해결 표와 자주 묻는 질문, 단계별 다음 읽기를 추가했다. 기존의 앱 명칭 안내, 비용·로그인 구분, 여섯 교육용 화면과 흐름도, 완료 기준은 유지했다. 원본 출판 원고와 교육용 화면 파일은 수정하지 않았다.

이 책은 자동매매 시스템 개발을 설명하는 교육 자료다. 특정 금융상품의 매매를 권유하거나 수익을 보장하지 않는다.

CCI 신호를 계산했다면 이제 그 신호를 과거 가격에 적용해 본다. 이번 장의 결과는 수익 인증서가 아니라, 같은 입력으로 같은 진입·청산 기록을 다시 만들 수 있는 시뮬레이션이다.

이 장의 경로·종목·숫자·로그는 교육용 가상 예시다. 작업 폴더는 C:\Users\minjun\auto-trading-lab이며, 가격 원본은 앞 장의 daily_prices(symbol, trade_date, open, high, low, close, volume)을 사용한다. 주문 API를 호출하지 않는다.

1. 시뮬레이션의 질문부터 정하기

“얼마나 벌었는가”를 보기 전에 “그 시점에 알 수 있던 정보만 사용했는가”를 확인한다. T일 종가로 계산한 CCI는 T일 장이 끝난 뒤 확정된다. 그 값을 보고 T일 시가에 매수한 것으로 계산하면 미래 정보를 사용하게 된다.

여기서는 CCI 기간을 20으로 고정하고, 전 거래일 CCI가 -100 이하이며 당일 CCI가 -100을 초과하는 상향 돌파만 예제 신호로 삼는다. CCI가 낮다는 사실 자체를 매수 신호로 취급하지 않는다. 이 기준은 계산을 설명하기 위한 학습용 규칙이며 종목 추천이나 검증된 투자 전략이 아니다.

시뮬레이션에서 확인할 질문은 네 가지다. 신호 이후의 가격을 정확히 연결했는가, 보유 기간을 일관되게 셌는가, 비용과 제외 사유를 남겼는가, 재실행해도 결과가 중복되지 않는가. 모든 질문에 기록으로 답할 수 있어야 다음 장으로 넘어간다.

2. 진입·청산 규칙을 한 문서로 고정하기

config/simulation.json에 다음과 같이 저장하도록 설계한다. 아래 비용은 실제 증권사 요율이나 현행 세율이 아니라 계산을 연습하기 위한 가정값이다.

{
  "strategy_version": "cci20_cross_up_m100_v1",
  "cci_period": 20,
  "signal": "prev_cci <= -100 and cci > -100",
  "entry": "next_session_open",
  "holding_sessions": 5,
  "exit": "fifth_session_close",
  "same_symbol_overlap": "skip",
  "fee_bps_each_side": "5",
  "sell_tax_bps": "20",
  "slippage_bps_each_side": "0",
  "cost_model": "educational-assumption-v1"
}

“5거래일 보유”를 entry_index + 5로 구현하면 이 문서의 규칙보다 하루 늦어진다. 진입일을 포함하므로 청산 위치는 entry_index + 4다. 주말이나 공휴일을 단순히 날짜에 더하지 않는다.

또한 다음 행이 있다는 사실만으로 다음 거래일이 확인되지는 않는다. 원본에서 하루가 빠졌다면 그다음 행은 T+2일 수 있다. 거래 캘린더와 종목의 거래 가능 상태를 함께 확인하고, 원인 불명 누락은 MISSING_EXPECTED_SESSION으로 제외한다.

3. 데이터 묶음과 실행 식별자 보관하기

같은 기간이라도 원본 가격이 수정되거나 대상 종목이 바뀌면 결과가 달라진다. 실행마다 run_id, 코드 버전, 설정 해시, 데이터 스냅샷 식별자, 대상 종목 목록의 기준일을 보관한다. 오늘의 구성 종목을 과거 전체 기간에 적용했다면 구성 종목의 생존 편향 가능성도 보고서에 쓴다.

outputs/simulation/demo-20261020-01/
  manifest.json
  trades.csv
  skipped_signals.csv
  summary.json

manifest.json에는 비밀번호가 들어간 연결 문자열 대신 dataset_id, 조회 기간, 행 수, 정렬 기준을 남긴다. 날짜·종목순으로 정렬한 입력의 해시를 보관하면 재현에 도움이 된다. Python의 SHA-256 사용 방법은 공식 hashlib 문서에 나와 있다.

데이터 조회는 ORDER BY symbol, trade_date로 고정한다. 수정주가와 원주가를 섞거나, 분할 전후 가격을 조정 없이 이어 붙이지 않는다. 가격 조정 정책을 확인할 수 없다면 그 구간을 별도로 표시하고 성과 해석을 보류한다.

앞 장의 CSV 입력은 outputs/indicators/cci_20.csv이며 지표 열은 cci_20, 신호 열은 entry_signal이다. DB에 저장했다면 cci_daily_signals.cci_value를 cci_20으로 읽고 trade_date를 신호 날짜로 연결한다. DB의 period = 20, strategy_version = 'cci20_cross_up_m100_v1' 조건으로 같은 계산 버전만 선택한다.

SELECT symbol, trade_date, cci_value AS cci_20, entry_signal
FROM cci_daily_signals
WHERE period = 20 AND strategy_version = 'cci20_cross_up_m100_v1'
ORDER BY symbol, trade_date;

신호 후보는 entry_signal = true인 행이다. 가격과 연결할 때는 (symbol, trade_date)를 사용한다. CSV를 읽는 경우 불리언 열의 True·False 문자열을 엄격하게 해석하고, 문자열 "False"를 단순한 참값으로 변환하지 않는다. 이전 원고의 watch 신호와 이 장의 상향 돌파 신호를 섞지 않는다.

4. 손으로 맞출 수 있는 작은 사례 만들기

먼저 가상 종목 DEMO_A 한 개로 날짜 연결을 확인한다. 아래 날짜는 교육용 세션 목록이며 실제 거래일 캘린더를 대신하지 않는다.

10주를 샀다고 가정하면 매수 금액은 100,000, 매도 금액은 102,000이다. 비용 전 손익은 2,000이다. 예제 수수료는 매수 50, 매도 51이고, 가정 매도세금은 204이므로 비용 후 손익은 1,695다. 슬리피지는 이 사례에서 0으로 놓았다.

from decimal import Decimal

qty = Decimal("10")
entry = Decimal("10000") * qty
exit_value = Decimal("10200") * qty
buy_fee = entry * Decimal("0.0005")
sell_fee = exit_value * Decimal("0.0005")
sell_tax = exit_value * Decimal("0.0020")
net_pnl = exit_value - entry - buy_fee - sell_fee - sell_tax
print(net_pnl)  # 1695.0000

금액에는 문자열로 만든 Decimal을 사용하고 최종 반올림 위치를 별도로 정한다. 이는 소수 계산 오차를 관리하기 위한 선택이다. Python decimal 공식 문서는 정밀도와 반올림 방법을 설명한다. 실제 비용 처리 규칙은 이 예제와 다를 수 있다.

5. 일봉으로 알 수 없는 체결은 표시하기

일봉의 시가에 원하는 수량을 모두 체결했다고 보는 것은 단순한 가정이다. 거래정지, 유동성 부족, 가격 제한, 주문 지연을 재현하지 못한다. fill_model = daily_open_close_assumption을 결과에 명시하고, 거래량이 0이거나 가격이 비정상인 날은 체결로 만들지 않는다.

이번 규칙은 정해진 날의 종가 청산이므로 장중 손절·익절을 사용하지 않는다. 나중에 고가가 익절가를 넘고 저가가 손절가 아래인 일봉을 만나도 어느 가격에 먼저 도달했는지는 알 수 없다. 그때는 분봉 등 더 세밀한 데이터가 필요하며, 임의로 유리한 청산 순서를 택하지 않는다. 보수적인 우선순위를 가정하더라도 intraday_order_unknown을 기록해야 한다.

비용 전 결과와 비용 후 결과를 함께 저장한다. 슬리피지 0, 5, 10bp처럼 다른 가정을 비교할 수 있지만 가장 좋아 보이는 가정만 본문에 남기지 않는다. 이는 비용 민감도 확인이지 실제 체결 검증이 아니다.

6. 완료와 제외를 같은 무게로 저장하기

simulation_runs는 실행 단위, simulation_trades는 신호별 결과 단위로 나눈다. 결과의 고유 기준은 (run_id, symbol, signal_date)이며, 새 실험은 새 run_id를 사용한다. 동일 실행의 재시도는 기존 결과와 비교한 뒤 같은 결과이면 건너뛴다. 다른 결과이면 덮어쓰지 않고 불일치로 중단한다.

SQL 조회 예시는 다음과 같다. simulation_trades는 이번 장에서 새로 만드는 교육용 결과 테이블 이름이다.

SELECT status, COALESCE(skip_reason, 'NONE') AS reason, COUNT(*) AS cnt
FROM simulation_trades
WHERE run_id = 'demo-20261020-01'
GROUP BY status, COALESCE(skip_reason, 'NONE');

예를 들어 신호 21건 중 완료 15건, 기간 끝 미완료 4건, 보유 중 제외 2건이면 합계가 21건이어야 한다. 완료 15건만 보고 신호 처리율이 100%라고 표시하지 않는다. 제외가 없는 결과보다, 모든 제외를 설명할 수 있는 결과가 검토에 유용하다.

7. Codex에 구현과 확인을 나누어 요청하기

다음 요청문으로 파일 구조와 최소 재현 사례를 먼저 만든다. 실행 명령은 구현이 끝난 뒤 실제 파일 이름과 옵션을 확인하고 사용한다.

auto-trading-lab에서 과거 데이터 시뮬레이션만 구현해줘.
daily_prices와 앞 장의 CCI 결과를 읽고 CCI20 -100 상향 돌파를 사용해.
T+1 거래 세션 시가 진입, 진입일 포함 5번째 세션 종가 청산으로 고정해.
비용은 config/simulation.json의 학습용 가정을 사용하고 비용 전후를 구분해.
중복 보유, 누락 세션, 기간 끝 미완료를 사유별로 보관해.
src/simulate.py, scripts/run_simulation.ps1와 가상 데이터 예제를 만들어줘.
설정·데이터·코드 버전과 run_id를 남기고 재실행 시 중복을 방지해.
실제 주문, 증권사 모의주문, 외부 주문 전송 코드는 만들지 마.
한 종목 수동 계산과 날짜 경계·미완료 사례를 확인한 뒤 결과를 보고해.

정상 로그의 모양은 아래와 같다. 실제 실행 결과가 아니라 필요한 항목을 보여주는 예시다.

run_id=demo-20261020-01 mode=simulation dataset=fixture-v1
signals=21 completed=15 skipped=2 incomplete=4
check=entry_after_signal result=PASS
check=duplicate_result result=PASS duplicates=0
state=COMPLETED external_order_calls=0

8. 완료 기준과 문제 해결

완료 기준은 가상 사례의 날짜·비용이 손계산과 일치하고, 모든 신호가 완료·제외·미완료 중 하나에 속하며, 같은 실행을 다시 처리해도 행과 손익이 늘지 않는 것이다. 개별 거래 수익률의 평균은 자금 제약을 반영한 포트폴리오 수익률과 다르므로 별도로 표시한다.

문제가 생기면 전략 기준을 바꾸기 전에 해당 신호 한 건의 원본 가격·CCI·날짜 연결·계산식을 함께 출력한다. 다음 장에서는 이 기록을 바탕으로 페이퍼 실행을 시작할 기술적 준비가 되었는지 점검한다.

한 번 성공한 페이퍼 실행과 매일 반복해도 안전한 실행은 다르다. 반복 실행에서는 같은 날 두 번 시작되거나, 체결 기록을 저장하는 중에 프로그램이 끝나거나, 데이터 수집이 늦어지는 일이 생긴다. 이번 장은 그 상황을 기록하고 멈추는 방법을 다룬다.

예제는 auto-trading-lab의 로컬 paper 원장만 사용한다. 스케줄러를 켜는 것보다 중복 방지·완료 판정·복구 근거를 먼저 준비한다. 모든 시간과 로그는 가상 예시다.

1. 하루 실행을 단계별 상태로 남기기

실행 시작 때 run_id를 만들고 paper_runs에 기록한다. 단계가 끝날 때마다 마지막 확정 지점을 저장한다. 프로그램이 살아 있다는 사실과 해당 거래일의 처리가 끝났다는 사실은 별개다.

CREATED → VALIDATING → SIGNALS_READY → ORDERS_READY
        → SETTLING → RECONCILING → COMPLETED
어느 단계에서든 → BLOCKED 또는 FAILED
저장 상태 불명확 → RECOVERY_REQUIRED

BLOCKED는 데이터 지연이나 중단 파일처럼 정해진 조건에 걸린 상태다. FAILED는 예외로 정상 진행하지 못한 상태다. RECOVERY_REQUIRED는 DB 확정 여부를 다시 확인하기 전에는 처리 재개를 허용하지 않는 상태다. 이들을 모두 성공 종료 코드로 숨기지 않는다.

2. 거래일과 실행 시간을 구분하기

business_date는 처리할 거래 세션, started_at은 실제 실행을 시작한 시각이다. 6월 3일 데이터를 6월 4일 새벽에 처리할 수 있으므로 두 값을 같은 날짜로 가정하지 않는다. 시각에는 시간대를 보관하고 화면에는 한국 시간 기준임을 표시한다.

반복 실행의 입력은 daily_prices의 데이터 확정 상태와 거래 캘린더다. 컴퓨터의 오늘 날짜나 매주 월요일부터 금요일이라는 조건만으로 다음 세션을 정하지 않는다. 공식 거래일과 종목의 거래 가능 여부가 확인되지 않으면 CALENDAR_NOT_READY로 멈춘다.

일봉 기반 로컬 재생은 이미 확정된 과거 세션을 처리하는 작업이다. 실제 장 시작 시점의 주문 실행과 다르다. T일 종가 신호는 T+1 가상 OPEN 이벤트와 연결하고, 보고서에 가격의 관측 시각과 처리 시각을 나누어 적는다.

3. 중복 실행과 중복 주문을 각각 막기

스케줄러 설정에서 중복 실행을 제한해도 수동 실행이 겹칠 수 있다. 프로그램에도 계정·모드별 실행 잠금을 둔다. 동시에 두 실행이 시작되면 하나만 진행하고 나머지는 ALREADY_RUNNING으로 종료한다.

잠금은 실행을 겹치지 않게 하는 장치이며, 주문 중복을 영구적으로 막는 장치는 아니다. 주문에는 앞 장의 고유 의도키가 별도로 필요하다. 같은 (account_id, strategy_version, symbol, signal_date, action)은 다른 run_id에서 재처리해도 기존 주문을 찾아야 한다.

DB 연결이 끊기면 잠금도 사라질 수 있으므로 연결 상실 즉시 새 변경을 중단한다. 잠금을 다시 얻었다고 곧바로 주문 단계부터 반복하지 않는다. 먼저 이전 실행과 원장 상태를 대조한다. 계정 행 잠금과 원자적 변경은 MySQL 공식 잠금 읽기 문서를 따른다.

4. 중단 조건은 설정으로 고정하기

다음은 config/paper_runtime.json의 학습용 예시다. 실제 운영에서 사용할 지연 허용 시간은 데이터 출처와 수집 주기를 확인해 정해야 한다.

{
  "mode": "paper",
  "stop_file": "config/STOP_PAPER",
  "max_consecutive_failures": 2,
  "stop_on_unexplained_price_gap": true,
  "stop_on_reconciliation_difference": true,
  "stop_on_intent_conflict": true,
  "allow_external_order_calls": false,
  "resume_requires_reconciliation": true
}

중단은 원장 삭제나 가상 포지션 강제 청산을 뜻하지 않는다. 이미 확정한 기록을 보존하고 새 변경을 멈추는 기능이다. 다시 실행할 때는 멈춘 이유가 해소되었는지 확인한다.

5. PowerShell 실행 스크립트의 종료 상태 전달하기

scripts/run_paper.ps1은 경로와 Python 실행 파일을 고정하고 실패 종료 코드를 호출자에게 전달한다. 다음 예시는 대응하는 src.paper_runner 모듈을 만든 뒤 사용할 실행 래퍼다.

$ErrorActionPreference = 'Stop'
$projectRoot = Split-Path -Parent $PSScriptRoot
Set-Location -LiteralPath $projectRoot
$pythonExe = Join-Path $projectRoot '.venv\Scripts\python.exe'
$stopPath = Join-Path $projectRoot 'config\STOP_PAPER'

if (Test-Path -LiteralPath $stopPath) {
    Write-Output 'state=BLOCKED reason=STOP_FILE'
    exit 20
}
if (-not (Test-Path -LiteralPath $pythonExe)) {
    throw '프로젝트 가상환경 Python을 찾지 못했습니다.'
}
& $pythonExe -m src.paper_runner --config 'config/paper_runtime.json'
$runnerExitCode = $LASTEXITCODE
exit $runnerExitCode

Python은 파일 로그를 UTF-8로 쓰고 run_id, business_date, stage, state, reason을 포함한다. 한글 로그는 Get-Content -Encoding UTF8으로 읽는다. PowerShell 버전별 기본 인코딩은 다를 수 있으므로 Microsoft 공식 인코딩 문서를 참고해 명시적으로 맞춘다.

Get-Content -Encoding UTF8 '.\logs\paper_runner.log' -Tail 40

6. 실패 지점 세 곳을 재현하기

자동 반복을 등록하기 전에 가상 데이터로 실패를 주입한다. 실제 계좌나 외부 주문 서버는 필요 없다. 실패 시험은 복사한 테스트 DB에서 수행하고 정상 학습 원장을 지우지 않는다.

마지막 사례가 중요하다. 로그에 성공이 없다는 이유로 체결을 다시 반영하면 현금과 수량이 두 번 바뀐다. 복구의 기준은 영속 저장소의 주문·체결·원장이다. MySQL의 트랜잭션 경계는 공식 COMMIT·ROLLBACK 문서를 참고한다.

DB에 접근할 수 없어 확정 여부를 모르면 RECOVERY_REQUIRED로 남긴다. 확인되지 않은 상태를 “실패했으니 아무 일도 없었다”로 가정하지 않는다. 로컬 시뮬레이터의 복구가 통과해도 실제 외부 주문의 응답 유실 문제가 해결된 것은 아니다.

7. 복구 기록을 남기고 재개하기

복구 기록에는 이전 run_id, 원인, 마지막 확정 단계, 대조한 주문·체결 건수, 변경 내용, 새 실행 식별자를 넣는다. 결과를 손으로 고쳤다면 수정 전후 값과 이유를 별도로 보관한다. 가능하면 원장 사건을 근거로 상태를 다시 계산한다.

recovery_id=demo-recovery-01 previous_run=demo-paper-09
reason=PROCESS_EXIT_AFTER_COMMIT
orders=1 fills=1 cash_entries=1 duplicate_entries=0
cash_difference=0.00 quantity_difference=0
action=KEEP_COMMITTED_FILL next_run=demo-paper-10
decision=RESUME_LOCAL_PAPER

중단 파일은 원인을 고친 뒤 담당자가 제거하는 절차로 둔다. 프로그램이 “몇 분 지났으니 괜찮다”고 자동 삭제하지 않는다. 재개 직전에도 설정 버전, 중단 사유 해소, 원장 대조를 확인한다.

8. 스케줄러는 마지막에 연결하기

수동 실행과 실패 복구가 통과하면 Windows 작업 스케줄러에 등록한다. 실행 프로그램은 PowerShell, 인수는 프로젝트의 실행 스크립트 절대 경로로 지정하고, 작업 시작 위치도 프로젝트 폴더로 고정한다. 조건은 외부 데이터 확정 시간에 맞추어 정한다.

로그인 여부, 절전·전원 설정, 실행 계정의 폴더 권한이 결과에 영향을 줄 수 있다. 작업이 등록되었다는 사실보다 지정 시각에 실행 기록과 종료 코드가 남는지 확인한다. 명령줄 관리가 필요하면 Microsoft 공식 schtasks 문서를 참고한다.

책의 예시를 읽었다고 자동 등록이 완료되는 것은 아니다. 이번 실습에서는 수동 실행 → 중복 시작 → 중단 파일 → 실패 복구 순서를 확인한 뒤 자신이 정한 관찰 일정에 연결한다.

9. Codex 요청과 완료 기준

로컬 paper_runner의 반복 실행과 복구 절차를 구현해줘.
단계별 상태·종료 코드·계정 실행 잠금·영구 고유 의도키를 구분해.
중단 파일·데이터 미확정·잔고 불일치·의도 충돌에서 새 변경을 차단해.
주문 전, 체결 확정 전, 확정 후 로그 전의 실패를 가상 DB에서 재현해.
재시작 후 주문·체결·정산이 한 번씩만 남는지 확인해.
스케줄러 등록은 수동 검증 결과와 등록할 명령을 먼저 보고해.
외부 주문 기능은 추가하지 말고 운영 로그에서 비밀값을 제외해.

완료 기준은 같은 거래일을 두 번 처리해도 주문과 자금이 늘지 않고, 중간 실패 후 마지막 확정 상태에서 재개하며, 중단 조건이 실제로 차단되는 것이다. 로그가 두 번 남았다는 사실과 주문이 두 번 발생했다는 사실도 구분해서 집계한다.

다음 장에서는 페이퍼 성공을 실전 허가로 오해하지 않도록 별도의 차단 점검과 안전 기본값을 정리한다.

과거 시뮬레이션이 끝나도 바로 반복 실행을 시작하지 않는다. 이번 장에서는 결과가 재현되는지, 데이터 문제가 숨겨져 있지 않은지, 가상 자금과 주문 상태를 기록할 준비가 되었는지 확인한다.

이 책에서 paper는 로컬 프로그램이 가상 주문·체결·잔고를 기록하는 학습 모드다. 한국투자증권의 모의투자 서버를 이용하는 방식과 구분한다. 이번 장에서도 외부 주문 요청을 보내지 않으며, 예시 숫자는 실제 투자 결과가 아니다.

1. 성과 판단과 기술적 준비를 구분하기

시뮬레이션 수익률이 높다는 이유로 페이퍼 실행을 허용하면 계산 오류가 좋은 결과처럼 통과할 수 있다. 반대로 손실 결과라고 해서 날짜와 원장이 정확한 프로그램을 고장이라고 판단할 필요도 없다. 이번 점검은 프로그램의 처리·기록 품질을 대상으로 한다.

CCI20의 -100 상향 돌파, T+1 시가 진입, 진입일 포함 5번째 거래 세션 종가 청산이라는 예제 규칙을 유지한다. 준비 점검 중 결과를 좋게 만들려고 기간이나 청산 규칙을 바꾸면 비교 기준이 사라진다.

2. 재현 자료를 하나의 묶음으로 만들기

7장의 결과 폴더와 연결되는 readiness_id를 만든다. 원본 데이터 전체를 보고서에 복사할 필요는 없지만, 어떤 원본을 사용했는지 다시 찾을 수 있어야 한다.

outputs/readiness/demo-review-01/
  input_manifest.json
  checks.csv
  summary.json
  failed_cases.csv

input_manifest.json에 시뮬레이션 run_id, dataset_id, 코드 버전, 설정 해시, 대상 종목의 기준일, 조회 시작·끝 날짜를 적는다. checks.csv에는 점검 항목별 PASS, FAIL, NOT_EVALUATED와 증거 파일 경로를 기록한다.

증거가 없는 항목은 PASS가 아니다. 아직 만들지 않은 복구 시험을 “향후 확인 예정”이라고 적었다면 NOT_EVALUATED로 남기고 다음 단계 허용을 보류한다. 로그가 없거나 파일을 읽을 수 없는 경우도 같은 방식으로 다룬다.

3. 다섯 종목에서 전체 대상으로 확장하기

작은 사례가 통과하면 대상 목록을 확장하되 한 번에 계산 규칙까지 바꾸지 않는다. 처음 다섯 종목의 결과가 전체 실행에서도 동일한지 대조하고, 새로 추가된 종목의 가격 누락과 조정 정책을 확인한다.

daily_prices에서 다음 쿼리는 키 중복을 찾아낸다. 기본 키가 이미 중복을 막더라도 수집 전 임시 데이터와 수입 과정에도 같은 검사를 적용한다.

SELECT symbol, trade_date, COUNT(*) AS cnt
FROM daily_prices
GROUP BY symbol, trade_date
HAVING COUNT(*) > 1;

SELECT symbol, trade_date, open, high, low, close, volume
FROM daily_prices
WHERE open <= 0 OR close <= 0 OR volume < 0
   OR high < low OR high < GREATEST(open, close)
   OR low > LEAST(open, close);

이 쿼리가 0행이어도 데이터 검증이 끝난 것은 아니다. 아예 빠진 거래일은 행이 없어서 위 조건에 걸리지 않는다. 수집 대상·거래 캘린더·원본 조회 결과를 비교해 누락을 찾는다. 거래정지와 단순 수집 실패도 구분한다.

대상 목록을 “현재 코스피200”으로만 구했다면 과거 구성 종목 전체를 재현한 연구가 아니라 현재 목록에 대한 과거 계산이다. 이 제한을 보고서 첫 부분에 명시하고, 그 결과를 장기 성과 검증으로 표현하지 않는다.

4. 통과 조건을 점검 전에 작성하기

config/paper_readiness.json의 기준은 결과를 확인하기 전에 정한다. 다음 숫자는 교육용 기능 시험의 기준이며 투자 적합성을 나타내는 수치가 아니다.

{
  "review_version": "paper-gate-v1",
  "required_fixture_cases": 8,
  "max_duplicate_keys": 0,
  "max_unexplained_missing_sessions": 0,
  "max_reconciliation_difference": "0.00",
  "required_repeat_consistency": true,
  "required_failure_recovery": true,
  "require_all_checks_evaluated": true,
  "permit_mode": "paper"
}

8개 사례는 상승·하락·비용 후 손실·신호 없음·데이터 부족·중복 신호·재실행·중간 실패로 구성한다. 각 사례의 입력과 기대 상태를 따로 저장한다. 이미 나온 결과를 그대로 기대값으로 복사하는 방식은 오류를 찾지 못한다.

비용 후 손실 사례에는 예를 들어 매수가와 매도가가 모두 10,000인 거래를 넣는다. 비용 전 손익은 0이지만 수수료·가정 세금을 빼면 순손익은 음수여야 한다. “가격이 같으면 항상 보합”이라고 분류하는 오류를 잡을 수 있다.

5. 요약표에 분모와 제외 사유를 함께 넣기

다음은 가상 결과다. 숫자의 크기보다 같은 기준으로 집계했는지 살펴본다.

평균 손익과 승률에는 완료 건수라는 분모를 표시한다. 여러 종목의 거래 수익률 평균을 전체 자산 수익률로 쓰지 않는다. 최대 낙폭을 계산하려면 같은 시점별 현금, 보유 수량, 평가 가격을 사용한 자산 곡선이 별도로 필요하다.

현재 시뮬레이션이 종목별 독립 계산이라면 “동시에 모든 신호를 살 자금이 있었다”는 가정을 내포할 수 있다. 다음 장에서는 초기 가상 현금, 주문당 한도, 최대 보유 수, 현금 예약을 넣어 이 차이를 드러낸다.

6. 비용과 기간에 대한 민감도 확인하기

기준 실행을 보관한 채 비용만 바꾼 별도 실행을 만든다. 예를 들어 슬리피지 가정이 커질수록 순손익이 어떻게 달라지는지 확인한다. 요율은 소수로 읽는지 bp로 읽는지 함께 적는다. 5bp = 0.0005이므로 0.05와 혼동하면 비용이 100배가 된다.

기간도 학습 구간과 검토 구간을 시간순으로 나눈다. 검토 구간 결과를 본 뒤 매번 규칙을 고쳐 다시 검토하면 그 구간도 개발에 사용한 셈이다. 어떤 기간을 언제 보았는지 변경 기록에 남긴다.

일봉에서 장중 손절·익절 순서를 알 수 없다는 제한은 그대로 유지된다. 민감도 표에 가정만 추가했다고 체결 품질이 입증되지는 않는다. 고정 청산 예제의 범위와 데이터 해상도를 보고서에 함께 쓴다.

7. 준비 판정을 기계가 읽을 수 있게 남기기

단순히 “통과”라는 파일이 존재하는지만 검사하면 예전 결과가 새 설정에도 사용될 수 있다. 판정에는 입력의 버전과 허용 범위를 함께 넣고, 이후 실행이 달라지면 무효로 취급한다.

{
  "readiness_id": "demo-review-01",
  "decision": "READY_FOR_LOCAL_PAPER",
  "strategy_version": "cci20_cross_up_m100_v1",
  "dataset_id": "fixture-v1",
  "config_hash": "EXAMPLE_ONLY_REPLACE_WITH_COMPUTED_HASH",
  "checks_passed": 8,
  "checks_failed": 0,
  "not_evaluated": 0,
  "scope": "local_paper_only",
  "external_orders_permitted": false
}

이 예시 파일을 복사하는 것만으로 점검이 통과되지는 않는다. 실제 프로그램은 자신의 입력에서 해시를 계산하고 시험 결과로 판정을 생성해야 한다. 해시 계산의 기본 API는 Python 공식 hashlib 문서를 참고한다.

8. Codex에 검토 범위를 분명하게 전달하기

7장의 시뮬레이션을 로컬 paper 실행으로 확장할 준비가 되었는지 검토해줘.
소스·설정·데이터 식별자를 연결한 checks.csv와 summary.json을 만들어줘.
8개 가상 사례의 기대값을 먼저 정하고 날짜·비용·중복·중간 실패를 확인해.
종목 전체 확장에서는 처음 5개 결과의 일관성과 누락 사유를 대조해.
성과 지표와 기술 통과 조건을 구분하고 미검사 항목을 PASS로 처리하지 마.
파일 이름이나 실행 옵션은 현재 프로젝트에 맞게 제안하고 근거를 적어줘.
투자 적합성 판단, 실전 주문, 증권사 모의주문 요청은 수행하지 마.

검토 결과가 BLOCKED라면 모든 파일을 다시 만들지 않는다. 실패 항목과 관련된 가장 작은 입력을 재현하고, 수정 후 그 항목과 연관 검사를 다시 실행한다. 수정 전 결과도 남겨 원인을 비교한다.

9. 완료 기준과 문제 해결

이번 장을 마쳤다는 뜻은 준비 보고서가 존재하고 모든 기술 조건의 증거를 찾을 수 있다는 것이다. 보고서가 막힌 상태라면 다음 장을 읽을 수는 있지만 반복 실행을 허용하지 않는다. 기술 점검의 통과는 실전 거래 허가가 아니다.

한국투자증권의 모의투자나 실전 API 사용 조건은 이 로컬 준비 보고서의 범위 밖이다. 해당 환경을 별도로 검토할 때는 KIS Developers 공식 안내의 API 문서와 현재 공지를 확인한다. 다음 장에서는 외부 주문 연결 없이 가상 주문 원장을 만든다.

이번 장에서는 신호를 가상 주문으로 바꾸고, 가상 체결이 현금과 보유 수량에 미치는 영향을 기록한다. 시뮬레이션의 거래별 손익을 넘어 하나의 계정에서 자금이 실제로 모자랄 수 있다는 조건을 다룬다.

여기서 paper는 로컬 원장 시뮬레이션이다. 한국투자증권의 모의투자 서버에 접속하지 않으며 실제 계좌·주문 번호를 사용하지 않는다. 모든 코드와 금액은 auto-trading-lab의 학습 예시다.

1. 신호·주문·체결을 다른 사건으로 다루기

신호는 조건이 만족되었다는 계산 결과다. 주문은 특정 수량을 특정 조건으로 처리해 달라는 의도다. 체결은 그 주문이 가격과 수량을 가지고 실행되었다는 결과다. 이 셋을 같은 테이블의 한 행으로 처리하면 미체결과 실패를 구분하기 어려워진다.

예를 들어 T일 CCI20이 -100을 상향 돌파해도 T일에 바로 가상 매수하지 않는다. T일 종가 확정 후 다음 거래 세션의 진입 의도를 만들고, T+1의 가상 OPEN 이벤트에서만 체결을 계산한다. 주문을 만들었다고 보유 수량부터 늘리지 않는다.

이번 구현은 전량 체결 또는 전량 미체결의 단순 모델이다. 부분 체결, 정정·취소의 경합, 실제 주문 접수와 거래소 체결 차이는 재현하지 않는다. 보고서에 partial_fill_supported = false를 기록한다.

2. 가상 계정과 한도를 설정하기

실제 계좌번호 대신 PAPER_DEMO_01을 사용한다. config/paper.json을 예제로 만들되, 실전 API 키가 들어 있는 설정을 함께 읽지 않도록 분리한다.

{
  "mode": "paper",
  "account_id": "PAPER_DEMO_01",
  "initial_cash": "1000000.00",
  "max_order_notional": "100000.00",
  "max_open_positions": 3,
  "same_symbol_overlap": "skip",
  "allow_short": false,
  "allow_leverage": false,
  "fill_model": "fixture_next_open_and_fifth_close",
  "external_order_transport": "disabled",
  "strategy_version": "cci20_cross_up_m100_v1"
}

매수 수량은 거래 전 사용 가능 현금, 주문당 한도, 수수료와 가격 가정을 함께 고려해 정수로 계산한다. initial_cash는 실행마다 다시 지급하는 돈이 아니다. 계정을 최초 생성할 때 한 번 기록하고, 재시작은 저장된 현금과 원장을 읽는다.

7장의 same_symbol_overlap = skip을 유지한다. 같은 의도키의 재시도라면 먼저 기존 주문과 내용을 대조하고 새 주문을 만들지 않는다. 새 진입 의도는 계정 행 잠금 안에서 검사하며, 보유 수량이 양수이거나 PENDING 매수 주문이 있는 종목은 SKIPPED/OVERLAPPING_POSITION으로 제외한다.

max_open_positions는 보유 종목과 PENDING 매수 종목의 합집합에 속한 고유 종목 수로 계산한다. 새 종목을 더했을 때 한도를 넘으면 의도를 생성하지 않는다. 취소·거절된 미체결 매수는 현금 예약과 미체결 슬롯을 해제하며, 보유 수량은 매도 체결 전까지 보유 슬롯에 남긴다. 이 검사와 주문 생성·예약은 같은 계정 잠금과 트랜잭션 안에서 처리한다.

동시에 여러 신호가 있으면 처리 순서도 고정한다. 예를 들어 (signal_date, symbol) 순서로 처리하면 재현하기 쉽지만 특정 종목 우선 효과가 생긴다. 이 정책을 문서에 남기고, 전략 성과로 오해하지 않는다.

3. 원장 구조와 고유키 정하기

최소 저장 구조는 paper_accounts, paper_orders, paper_fills, paper_cash_ledger, paper_positions다. 각 기록은 account_id, run_id, strategy_version으로 연결한다. 금액은 SQL의 DECIMAL, 수량은 허용하는 단위에 맞는 타입으로 저장한다.

CREATE TABLE paper_orders (
  order_id CHAR(36) PRIMARY KEY,
  account_id VARCHAR(40) NOT NULL,
  run_id VARCHAR(80) NOT NULL,
  strategy_version VARCHAR(40) NOT NULL,
  client_order_key VARCHAR(180) NOT NULL,
  symbol VARCHAR(20) NOT NULL,
  side VARCHAR(4) NOT NULL,
  quantity INT NOT NULL,
  scheduled_session DATE NOT NULL,
  scheduled_event VARCHAR(8) NOT NULL,
  status VARCHAR(20) NOT NULL,
  reserved_cash DECIMAL(18,2) NOT NULL DEFAULT 0,
  UNIQUE KEY uq_paper_intent (account_id, client_order_key)
) ENGINE=InnoDB;

교육용 키 예시는 cci20_cross_up_m100_v1|DEMO_A|2026-06-02|ENTRY다. 같은 실행을 재시도해도 이 의도 키는 바꾸지 않는다. 실행을 구별하는 run_id만 고유키로 삼으면 재시도할 때 같은 주문이 새 주문으로 생길 수 있다.

paper_orders.run_id는 주문을 최초 생성한 실행을, strategy_version은 그때의 전략 버전을 나타낸다. 재시도·복구에서는 이 최초 생성 정보를 덮어쓰지 않는다. 이후 실행의 처리 시도는 기존 order_id를 참조하는 paper_runs와 실행 로그에 별도로 남긴다. 의도의 고유 제약은 (account_id, client_order_key)로 유지하며 run_id를 포함하지 않는다.

체결 테이블에는 (order_id, fill_sequence) 고유 제약을, 현금 원장에는 체결별 정산 사건의 고유 제약을 둔다. 종료 주문은 원래 진입 포지션 식별자와 연결해, 매일 “보유 중”이라는 이유로 청산 주문이 여러 개 생기지 않도록 한다.

4. 주문을 만들 때 현금을 예약하기

예제에서 가상 현금이 1,000,000이고 10,000원 10주 매수와 수수료 50을 예상한다면 100,050을 예약한다. 총현금은 아직 1,000,000이지만 사용 가능 현금은 899,950이 된다. 다른 주문은 예약된 금액을 쓸 수 없다.

T일에는 T+1 시가를 알 수 없으므로 실제 구현의 예약액은 사전에 정한 가격 상한과 비용 여유를 이용해야 한다. T+1 가격으로 필요한 금액이 예약 한도를 넘으면 이번 단순 모델은 REJECTED/RESERVATION_LIMIT으로 처리하고 예약을 해제한다. 미래 시가를 T일에 미리 읽어 수량을 유리하게 정하지 않는다.

DB에서는 사용 가능 현금을 조회하고 주문을 삽입하고 예약을 갱신하는 과정을 한 트랜잭션으로 묶는다. 동시 실행 가능성이 있다면 계정 행을 SELECT ... FOR UPDATE로 잠그고 한도를 다시 확인한다. InnoDB 잠금 읽기의 동작은 MySQL 공식 문서를 참고한다.

고유키 충돌은 아무 오류나 무시하는 방식으로 처리하지 않는다. 기존 주문을 읽어 종목·방향·수량·예정 세션이 같은지 비교한다. 내용이 다르면 INTENT_CONFLICT로 중단한다. 같은 키에 다른 수량이 들어온 상황을 정상 재시도로 숨기지 않는다.

5. 체결과 잔고 변경을 함께 확정하기

가상 OPEN 이벤트에서 주문과 계정을 잠그고 상태가 PENDING인지 확인한다. 가격·거래량·예정 세션 조건이 맞으면 체결, 현금 차감, 수량 증가, 예약 해제, 주문 상태 변경을 하나의 트랜잭션으로 확정한다. 한 단계라도 실패하면 전체를 되돌린다.

BEGIN
  계정·주문 행 잠금
  기존 체결과 주문 상태 확인
  예정 세션·가격·수량·예약 한도 확인
  paper_fills에 가상 체결 삽입
  paper_cash_ledger에 현금 차감 삽입
  계정 현금과 paper_positions 갱신
  예약 해제 및 주문을 FILLED로 변경
COMMIT

실제 코드는 SQL 값을 문자열로 조합하지 않고 DB 드라이버의 파라미터 바인딩을 사용한다. 트랜잭션의 확정과 취소는 MySQL 공식 COMMIT·ROLLBACK 문서를 기준으로 구현한다. 로그 파일 한 줄이 성공했다는 이유만으로 DB 확정을 대신 판단하지 않는다.

청산도 같은 원칙이다. 진입 세션을 포함해 5번째 세션의 가상 CLOSE에서 보유 수량을 넘지 않는 매도만 허용한다. 매수 예약·매수 체결·매도 체결의 사건이 연결되어야 현금과 수량을 복원할 수 있다.

6. 가상 원장을 손으로 대조하기

7장의 가상 거래와 같은 가격·비용을 사용하면 다음 결과가 나와야 한다. 초기 예제와 대조할 때만 매수 가격 10,000, 매도 가격 10,200, 수량 10, 슬리피지 0으로 고정한다.

매도 정산 유입은 102,000에서 가정 수수료 51과 가정 세금 204를 뺀 101,745다. 이 숫자가 현금 원장과 계정 현금에 모두 반영되어야 한다. 보유 중 자산 평가는 평가 가격과 평가 시각도 함께 표시하고 실현손익과 구분한다.

대조식은 현재 현금 = 최초 입금 + 현금 원장 증감 합계와 현재 수량 = 매수 체결 수량 - 매도 체결 수량이다. 반올림 정책까지 동일하게 적용했는데도 차이가 있으면 다음 실행을 막는다.

7. 과거 재생과 앞으로의 관찰을 구분하기

일봉만으로 학습할 때는 가상 시계를 두고 과거의 CLOSE → 다음 OPEN → CLOSE 이벤트를 순서대로 재생한다. T+1 시가를 이미 갖고 있어도 T일 의도 생성 함수에는 전달하지 않는다. 전체 데이터가 메모리에 있다는 이유로 미래 열을 읽지 않도록 입력 경계를 나눈다.

앞으로의 데이터를 매일 관찰하는 방식이라면 아직 오지 않은 시가나 종가를 체결로 기록할 수 없다. 일봉이 확정된 뒤 뒤늦게 체결을 재구성한다면 replayed_after_close와 원본 가격 확정 시각을 표시한다. 이는 실시간 시장에서 그 가격에 주문이 체결되었다는 뜻이 아니다.

장중 고가·저가를 이용한 손절·익절은 이 모델에 추가하지 않는다. 한 일봉에서 두 조건이 모두 충족될 때 선후관계를 알 수 없기 때문이다. 원장의 정확성과 시장 체결의 현실성은 별도 문제로 평가한다.

8. Codex에 작은 원장 시험을 요청하기

외부 네트워크 주문 기능이 없는 로컬 paper 원장을 구현해줘.
config/paper.json을 읽고 계정 초기 입금은 한 번만 기록해.
T일 종가 신호로 PENDING 의도를 만들고 T+1 OPEN 이벤트에서만 가상 체결해.
진입일 포함 5번째 CLOSE 청산을 포지션 식별자와 연결해.
계정 잠금·고유 의도키·체결키·현금 예약·원자적 정산을 적용해.
같은 종목 보유·PENDING 매수의 중복 진입을 막고 보유·미체결 종목의 합집합으로 보유 한도를 검사해.
주문의 최초 run_id·strategy_version은 보존하고 재시도는 기존 order_id와 새 실행 로그로 연결해.
실제 계좌번호와 API 키를 읽지 말고 가상 fixture만 사용해.
매수 후 현금 899950, 청산 후 1001695가 되는 예제를 확인해.
같은 이벤트 재생·현금 부족·가격 누락·트랜잭션 중단도 확인하고 보고해.

정상 로그는 intent_created, fill_committed, reconciliation_passed처럼 사건을 구분한다. 가상 체결 번호에는 PAPER- 접두사를 넣어 실제 주문 번호와 혼동하지 않게 한다. 민감한 설정 전체를 로그로 출력하지 않는다.

9. 완료 기준과 문제 해결

완료 기준은 주문과 체결이 구분되고, 재실행해도 초기 자금·주문·체결이 늘지 않으며, 현금·수량 대조 차이가 0인 것이다. 가격이 없는 이벤트는 미체결로 남거나 사유와 함께 종료되어야 하며, 임의의 가격으로 채우지 않는다.

다음 장에서는 이 원장을 하루씩 반복 실행하고, 중간 실패 후 어디까지 확정되었는지 확인하며 복구하는 절차를 만든다.

자동매매 학습 프로젝트는 코드가 한 번 실행되었다고 끝나지 않는다. 데이터를 제때 읽었는지, 신호가 없었던 것인지 계산이 실패한 것인지, 현금·수량 기록이 맞는지 매일 구분해야 한다. 이번 장에서는 그 판단을 다음 실행과 연결하는 운영 기록을 만든다.

이 책의 운영 대상은 외부 주문이 없는 auto-trading-lab의 로컬 paper 환경이다. 아래 기록과 손익은 모두 가상 예시다. 운영 검토의 목적은 수익을 약속하거나 매매 결정을 대신하는 것이 아니라 실행 상태와 변경 근거를 보존하는 것이다.

1. 실행 결과와 운영 판단을 연결하기

paper_runs에는 프로그램이 실제로 한 일을 기록하고, operation_notes에는 사람이 그 결과를 어떻게 판단했는지 적는다. “오늘 이상 없음”이라는 메모만 남기면 어떤 데이터와 원장을 봤는지 알 수 없다. 실행 식별자와 증거 경로를 함께 기록한다.

판단과 사실이 다르면 사실을 먼저 확인한다. 예를 들어 로그에 오류가 없더라도 해당 거래일의 실행 행이 없다면 “문제 없음”이 아니라 “미실행 또는 기록 유실 의심”이다.

2. 하루 점검 순서를 고정하기

데이터 → 계산 → 의도 → 체결 → 원장 → 오류 → 다음 조치 순서로 점검한다. 매일 같은 순서로 보면 상류 단계의 실패가 하류의 신호 없음으로 위장하는 것을 줄일 수 있다.

1. 처리할 business_date와 데이터 확정 시각을 확인한다.
2. 대상 종목 수, 원본 행 수, 누락·가격 이상을 확인한다.
3. CCI 계산 대상과 결측 사유, 상향 돌파 신호 수를 확인한다.
4. 주문 의도·제외 사유와 기존 의도키 충돌을 확인한다.
5. 가상 체결과 예약현금, 보유 수량을 대조한다.
6. 실행 상태와 오류·중단·복구 기록을 확인한다.
7. 다음 실행을 허용할지 판단하고 근거를 적는다.

신호 0건은 정상일 수 있다. 하지만 계산 대상 0건, 수집 실패 200건, 신호 0건을 같은 정상 결과로 표시하면 안 된다. 기대 대상 수와 실제 처리 수를 함께 보고한다.

3. 운영 메모의 최소 구조 만들기

operation_notes에는 다음 필드를 둔다. 사실을 보정해야 할 때는 기존 메모를 지우지 않고 새 메모에서 이전 기록을 참조한다.

CREATE TABLE operation_notes (
  note_id CHAR(36) PRIMARY KEY,
  business_date DATE NOT NULL,
  run_id VARCHAR(80) NOT NULL,
  environment VARCHAR(20) NOT NULL,
  category VARCHAR(40) NOT NULL,
  decision VARCHAR(40) NOT NULL,
  evidence_path VARCHAR(255) NOT NULL,
  summary TEXT NOT NULL,
  follow_up TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB;

environment는 local_paper로 명시한다. 계좌번호나 토큰을 증거 경로와 메모에 넣지 않는다. 하루에 여러 실행이 있으면 각 실행과 일일 종합 메모를 연결해 재시도가 누락되지 않게 한다.

business_date=2026-06-09 environment=local_paper
run_id=demo-paper-12 state=COMPLETED
targets=5 calculated=5 signals=0 pending_orders=0
cash_difference=0.00 quantity_difference=0
decision=CONTINUE_LOCAL_PAPER
summary=데이터 확정·계산·원장 대조 완료, 신규 신호 없음

이 예시는 보고 형식이며 실제 프로젝트가 해당 날짜에 실행되었다는 증거가 아니다. 실제 보고서는 DB와 로그에서 읽은 값으로 생성한다.

4. 기술 실패·운영 차단·전략 결과를 구분하기

기술 실패는 프로그램이 정해진 처리를 수행하지 못한 경우다. 운영 차단은 미확정 데이터나 중단 파일처럼 미리 정한 조건에 따라 멈춘 경우다. 전략 결과는 프로그램이 정상 처리했지만 가상 손익이 좋거나 나빴던 경우다.

손실을 모두 버그로 보거나 오류를 모두 전략 탓으로 돌리면 원인을 찾기 어렵다. 먼저 같은 입력의 수동 계산과 상태 전이를 확인하고, 처리 자체가 정확한 경우에 전략 검토 후보로 분류한다.

5. 장애 기록은 원인보다 증거부터 적기

장애 발생 시 첫 기록에는 관측 사실, 영향 범위, 마지막 정상 시각, 중단 상태를 적는다. 원인을 아직 모르면 UNKNOWN이라고 쓴다. “아마 네트워크 문제”라는 추정을 확정 원인처럼 기록하지 않는다.

incident_id=demo-incident-03 severity=BLOCKING
observed=현금 원장 합계와 계정 현금 차이 50.00
affected_run=demo-paper-13 last_known_good=demo-paper-12
new_processing=BLOCKED root_cause=UNKNOWN
evidence=outputs/incidents/demo-incident-03/
next_action=체결별 수수료 정산 사건과 반올림 정책 대조

기록을 맞추려고 원장 행을 삭제하거나 현금을 임의로 바꾸지 않는다. 불변 체결과 현금 사건으로 기대 상태를 다시 계산한다. 정정이 필요하면 수정 사유·원본 참조·정정 사건을 남기고 대조를 다시 수행한다. 새 상태가 맞았다는 근거를 복구 기록에 연결한다.

운영 로그를 읽을 때는 프로젝트의 UTF-8 로그 도구가 있으면 그것을 사용하고, PowerShell에서는 Get-Content -Encoding UTF8을 사용한다. 인코딩에 따른 표시 차이는 Microsoft 공식 문서에서 확인할 수 있다.

6. 전략 변경을 실험 단위로 관리하기

손실 한 건을 본 직후 CCI 기준을 바꾸지 않는다. 바꾸고 싶은 이유를 먼저 가설로 적고, 현재 기준 실행을 보관한다. CCI 기간·돌파 수준·진입·청산·비용 중 무엇을 바꾸는지 한 번에 구분할 수 있어야 한다.

{
  "change_id": "demo-change-02",
  "status": "PROPOSED",
  "baseline_version": "cci20_cross_up_m100_v1",
  "candidate_version": "cci20_cross_up_m100_v2_experiment",
  "hypothesis": "가격 누락 처리 변경이 미완료 분류를 더 정확하게 만드는가",
  "changed_component": "missing_session_classification",
  "evaluation_dataset": "fixture-v2",
  "paper_restart_required": true,
  "live_permission": false
}

이 예시는 수익 규칙 변경보다 데이터 처리 개선을 먼저 비교한다. 실제 전략 조건을 실험하더라도 가설, 평가 기간, 비용 가정, 제외 기준을 결과를 보기 전에 정한다. 여러 후보를 시도했다면 가장 좋은 하나뿐 아니라 시도한 후보 수와 탈락 결과도 남긴다.

변경 상태는 PROPOSED → UNDER_REVIEW → SIMULATION_CHECKED → PAPER_CHECKED → ACCEPTED로 관리한다. 실패나 보류는 REJECTED, DEFERRED로 남긴다. ACCEPTED는 이 책의 로컬 학습 기준에 반영했다는 뜻이며 실전 전송 허가가 아니다.

7. 주간 리뷰에서 처리 품질과 결과를 나누기

주간 리뷰에는 예정 세션 수와 실제 실행 수, 차단 횟수와 사유, 오류 재발, 복구 시간, 미해결 항목을 먼저 적는다. 그다음 비용 후 가상 손익과 포지션 변화를 본다. 단순 수익률 표만으로 운영 상태를 판단하지 않는다.

4회 완료를 80% 성공이라고만 표현하면 정상적인 데이터 보호 차단과 기술 실패가 섞인다. 차단의 이유와 적절성을 함께 해석한다. 예시의 횟수는 운영 품질 기준을 설명할 뿐 실제 서비스 안정성을 입증하지 않는다.

8. 백업은 복구 시험까지 수행하기

보관 대상은 소스 버전, 비밀값 없는 설정 예제, DB 스키마, 원장 데이터, 실행 식별자와 검토 기록이다. 접근 권한이 필요한 원본 데이터와 비밀 설정은 별도 보호하고 공개 저장소나 위키에 올리지 않는다.

복구 시험은 빈 테스트 DB에서 수행한다. 백업을 복원한 뒤 원장 건수, 마지막 run_id, 현금·수량 대조, 미완료 주문과 예약액을 확인한다. 복구본을 실제 반복 스케줄러에 연결하지 않도록 환경 이름과 DB 이름을 구분한다.

기록의 해시를 비교하면 파일 변경을 확인하는 데 도움이 되지만, 해시가 같다는 이유로 데이터의 정확성까지 보장되지는 않는다. 해시 계산은 Python 공식 hashlib 문서를 참고하고, 기능 대조와 함께 사용한다.

9. Codex에 운영 증거를 요약하도록 요청하기

이번 주 local_paper 운영을 읽기 전용으로 점검해줘.
paper_runs·주문·체결·현금 원장·operation_notes를 run_id로 연결해.
예정 세션, 완료, 정상 차단, 기술 실패, 재시도, 복구를 구분해.
현금·수량 불일치와 미해결 장애를 먼저 보고하고 근거 경로를 적어줘.
가상 손익은 비용과 평가 시각을 표시하고 실제 성과처럼 표현하지 마.
전략 변경 로그 없이 달라진 설정이 있는지 확인해.
파일·DB 수정, 실제 주문, 외부 메시지 발송은 수행하지 마.

읽기 전용 검토가 끝나면 해결할 항목 하나를 정해 별도 수정 작업으로 이어간다. 수정 시 기존 결과를 보존하고 관련 시뮬레이션·페이퍼·차단 시험을 다시 확인한다. 모르는 값을 추정해 보고서 빈칸을 채우지 않는다.

10. 완료 기준과 계속 유지할 원칙

이 장의 완료 기준은 하루 메모가 실행·증거와 연결되고, 장애와 전략 관찰이 구분되며, 변경이 검토 단계를 거치고, 복구 시험 결과가 남는 것이다. 처음 한 번 작성한 운영 문서를 영구적으로 완료된 상태로 보지 않는다.

데이터를 확인하고, 규칙을 기록하고, 이상 상태에서 멈추고, 근거가 있을 때만 변경한다. 이 절차를 반복할 수 있는 로컬 학습 시스템이 이 책의 최종 산출물이다. 실제 시장 연결과 운영 판단은 별도의 검토 과제로 남긴다.

검증된 CSV를 MySQL에 저장하면 종목과 기간을 조건으로 필요한 행을 다시 읽을 수 있다. 이 장에서는 종목마다 테이블을 만들지 않고 daily_prices 하나에 모든 종목의 일봉을 모은다. 종목코드와 거래일을 기본 키로 지정해 같은 자료를 재실행해도 행이 계속 늘어나지 않게 한다.

MySQL 서버 설치와 사용자 관리는 독자의 실행 환경에 따라 다르다. 여기서는 별도의 학습용 MySQL 8.4 데이터베이스에 접속할 수 있다고 가정한다. 실제 서비스 DB에 예제를 그대로 실행하지 않고, 준비된 학습용 저장소에서 진행한다. MySQL 공식 설치 안내

1. 저장과 조회의 단위 정하기

한 종목의 1일 일봉을 한 행으로 저장한다. 이렇게 하면 종목이 늘어도 테이블 이름을 동적으로 만들 필요가 없고, 다음 장에서 같은 SQL로 모든 종목을 읽을 수 있다.

가격에 DECIMAL을 사용하면 금액을 십진수 단위로 보관할 수 있다. 이번 CSV 예제는 원 단위 정수지만, SQL 구조는 소수 네 자리까지 허용한다. 이것이 지표 계산을 반드시 Decimal로 해야 한다는 뜻은 아니다. 금액 저장과 통계 계산의 숫자 정책은 목적에 맞게 구분한다. MySQL 공식 고정소수점 설명

현재 파일의 수정주가와 다른 가격 체계를 같은 키에 섞으면 출처를 구분하기 어렵다. 학습용 daily_prices는 4장에서 정한 KRX 수정주가 일봉만 담는다. 다른 시장·원주가 자료는 별도 데이터셋으로 관리한다.

2. 학습용 데이터베이스와 테이블 준비하기

DB를 관리하는 계정으로 auto_trading_lab을 만들고 아래 SQL을 실행한다. SQL은 config/schema.sql에 저장해 변경 이력을 남길 수 있다. CREATE TABLE IF NOT EXISTS는 기존 테이블의 구조를 자동으로 바꾸지 않으므로 이미 테이블이 있다면 SHOW CREATE TABLE로 확인한다.

CREATE DATABASE IF NOT EXISTS auto_trading_lab
  CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;

USE auto_trading_lab;

CREATE TABLE IF NOT EXISTS universe_snapshots (
  snapshot_date DATE NOT NULL,
  symbol CHAR(6) NOT NULL,
  name VARCHAR(100) NOT NULL,
  source VARCHAR(500) NOT NULL,
  PRIMARY KEY (snapshot_date, symbol)
) ENGINE=InnoDB;

CREATE TABLE IF NOT EXISTS daily_prices (
  symbol CHAR(6) NOT NULL,
  trade_date DATE NOT NULL,
  open DECIMAL(18,4) NOT NULL,
  high DECIMAL(18,4) NOT NULL,
  low DECIMAL(18,4) NOT NULL,
  close DECIMAL(18,4) NOT NULL,
  volume BIGINT UNSIGNED NOT NULL,
  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
    ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (symbol, trade_date),
  CONSTRAINT chk_daily_prices_positive
    CHECK (open > 0 AND high > 0 AND low > 0 AND close > 0),
  CONSTRAINT chk_daily_prices_range
    CHECK (high >= open AND high >= close AND high >= low
           AND low <= open AND low <= close)
) ENGINE=InnoDB;

universe_snapshots는 종목 목록의 기준일을 보존하는 구조다. 이번 실습의 가격 적재 코드는 daily_prices만 다룬다. 구성 종목 목록을 적재할 때도 (snapshot_date, symbol)을 기준으로 검증·매개변수 바인딩을 적용한다.

DDL은 데이터 적재 트랜잭션과 분리해서 실행한다. MySQL에서는 일부 DDL 문이 암묵적 커밋을 일으킨다. 프로그램에서 테이블 생성과 가격 입력을 한 트랜잭션처럼 취급하지 않는다. MySQL 공식 암묵적 커밋 문서

3. 접속 설정과 권한 구분하기

config/example.env와 개인용 config/.env에 다음 항목을 추가한다. 기존 KIS 설정을 지우거나 덮어쓰지 않는다.

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=lab_writer
MYSQL_PASSWORD=REPLACE_WITH_LOCAL_PASSWORD
MYSQL_DATABASE=auto_trading_lab

서버 설치 때 쓰는 관리자 계정과 일봉을 적재하는 계정을 구분한다. 적재 계정에는 해당 학습용 테이블의 SELECT, INSERT, UPDATE 등 필요한 권한만 부여하고, 지표 조회용 계정은 읽기 권한으로 좁힐 수 있다. 원격 서버에 연결한다면 인증서 검증을 포함한 TLS 설정도 환경에 맞게 준비한다.

명령줄 클라이언트에서는 비밀번호를 명령 인수에 직접 쓰지 않고 프롬프트로 입력한다.

mysql --host=127.0.0.1 --port=3306 --user=lab_writer --password auto_trading_lab

접속한 뒤 SELECT DATABASE(), VERSION();와 SHOW TABLES;를 실행한다. 접속 성공과 테이블 쓰기 권한은 별도이므로 작은 CSV를 적재하는 단계에서 다시 확인한다.

4. CSV를 검사한 뒤 트랜잭션으로 저장하기

src/load_prices.py는 이미 수집 완료가 확인된 CSV 하나를 인수로 받는다. 폴더의 모든 CSV를 무조건 읽으면 이전 실패 실행의 파일이나 요약 파일까지 섞일 수 있다. 4장의 실행 요약에서 성공한 파일을 선택한다.

import argparse
from decimal import Decimal
from pathlib import Path

import mysql.connector
import pandas as pd

from src.kis_readonly import load_config

REQUIRED = ["symbol", "trade_date", "open", "high", "low", "close", "volume"]
SQL = """
INSERT INTO daily_prices
  (symbol, trade_date, open, high, low, close, volume)
VALUES (%s, %s, %s, %s, %s, %s, %s) AS incoming
ON DUPLICATE KEY UPDATE
  open = incoming.open, high = incoming.high, low = incoming.low,
  close = incoming.close, volume = incoming.volume
"""


def read_rows(path):
    frame = pd.read_csv(path, dtype="string", encoding="utf-8-sig")
    if set(REQUIRED) - set(frame.columns) or frame.empty:
        raise ValueError("The CSV is empty or missing required columns")
    if frame[REQUIRED].isna().any().any():
        raise ValueError("The CSV contains missing values")
    if not frame.symbol.str.fullmatch(r"[A-Z0-9]{6}").all():
        raise ValueError("Invalid stock symbol")
    frame["trade_date"] = pd.to_datetime(
        frame.trade_date, format="%Y-%m-%d", errors="raise"
    ).dt.date
    if frame.duplicated(["symbol", "trade_date"]).any():
        raise ValueError("Duplicate symbol/date in the input")
    rows = []
    for record in frame[REQUIRED].itertuples(index=False, name=None):
        symbol, trade_date, *numbers = record
        prices = [Decimal(value) for value in numbers[:4]]
        volume_value = Decimal(numbers[4])
        if not all(p.is_finite() and p > 0 for p in prices):
            raise ValueError("Invalid price")
        if any(p != p.quantize(Decimal("0.0001")) for p in prices):
            raise ValueError("A price exceeds four decimal places")
        if (not volume_value.is_finite() or volume_value < 0
                or volume_value != volume_value.to_integral_value()):
            raise ValueError("Invalid volume")
        open_, high, low, close = prices
        if high < max(open_, low, close) or low > min(open_, high, close):
            raise ValueError("Invalid OHLC range")
        rows.append((symbol, trade_date, *prices, int(volume_value)))
    return rows


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("csv", type=Path)
    args = parser.parse_args()
    rows = read_rows(args.csv)
    config = load_config()
    required = ["MYSQL_HOST", "MYSQL_USER", "MYSQL_PASSWORD", "MYSQL_DATABASE"]
    if any(not config.get(key) for key in required):
        raise ValueError("MySQL settings are incomplete")
    connection = mysql.connector.connect(
        host=config["MYSQL_HOST"],
        port=int(config.get("MYSQL_PORT", "3306")),
        user=config["MYSQL_USER"],
        password=config["MYSQL_PASSWORD"],
        database=config["MYSQL_DATABASE"],
        charset="utf8mb4",
        connection_timeout=10,
        autocommit=False,
    )
    cursor = None
    try:
        cursor = connection.cursor()
        for row in rows:
            cursor.execute(SQL, row)
        connection.commit()
        print(f"committed input_rows={len(rows)} file={args.csv.name}")
    except Exception:
        connection.rollback()
        raise
    finally:
        if cursor is not None:
            cursor.close()
        connection.close()


if __name__ == "__main__":
    main()

SQL의 %s는 문자열 조합으로 채우는 자리가 아니라 Connector가 값을 바인딩하는 자리다. 종목코드나 날짜를 f-string으로 SQL에 붙이지 않는다. Connector/Python 공식 execute 문서

기본 키가 이미 있으면 새 가격으로 갱신한다. 이 예제의 행 별칭 문법은 MySQL 8.4를 기준으로 하며, 같은 파일의 재실행 시 행 수가 중복 증가하지 않는 것이 목적이다. 수정주가가 변경되면 값은 갱신될 수 있으므로 원본 CSV와 적재 일시를 남긴다. MySQL 공식 중복 키 갱신 문서

5. 적재 후 다시 조회하기

아래 파일명은 실제 수집 성공 파일명으로 바꾼다.

.\.venv\Scripts\python.exe -m py_compile src/load_prices.py
.\.venv\Scripts\python.exe -m src.load_prices outputs/daily/005930_2026-01-01_2026-10-16.csv

출력의 input_rows는 커밋한 입력 건수다. 새로 추가된 DB 행 수와 같다고 해석하지 않는다. 중복 키 갱신이 포함되면 추가·변경·동일값 처리의 행 수 의미가 달라질 수 있다.

다음 SQL로 저장 상태를 다시 읽는다.

SELECT symbol, COUNT(*) AS rows_count,
       MIN(trade_date) AS first_date, MAX(trade_date) AS last_date
FROM daily_prices
GROUP BY symbol
ORDER BY symbol;

SELECT symbol, trade_date, open, high, low, close, volume
FROM daily_prices
WHERE symbol = '005930'
ORDER BY trade_date DESC
LIMIT 5;

같은 파일을 한 번 더 적재한 뒤 대상 종목의 행 수가 늘지 않는지 확인한다. 하나라도 실패하면 rollback()으로 해당 CSV의 트랜잭션을 되돌린다. 이미 성공한 다른 파일의 커밋까지 되돌리는 구조는 아니다. Connector/Python 공식 트랜잭션 예제

6. Codex에 저장 기능 요청하기

검증된 일봉 CSV를 auto_trading_lab.daily_prices에 적재해줘.
종목별 테이블을 만들지 말고 (symbol, trade_date)를 기본 키로 사용해줘.
테이블 생성 DDL과 데이터 적재 트랜잭션을 분리하고, 값은 매개변수로 바인딩해줘.
입력 검증을 먼저 끝낸 뒤 파일 단위로 commit/rollback해줘.
같은 CSV를 두 번 적재해 행 수가 중복 증가하지 않는지 검증해줘.
DB 접속이 준비되지 않았다면 CSV 검증·문법 검사까지만 실행했다고 명시해줘.
기존 테이블 삭제, 운영 DB 수정, 주문 기능 추가는 이 요청의 범위에 넣지 마.

7. 오류 대응과 완료 기준

완료 기준은 입력 검증 → 커밋 → 다시 조회 → 동일 파일 재실행이 모두 설명되는 것이다. DB 연결을 실행하지 않았다면 저장 성공으로 기록하지 않는다. 다음 장에서는 daily_prices를 종목별 거래일 순서로 읽어 CCI를 계산한다.

페이퍼 원장이 정확해도 실제 시장에서 같은 가격으로 체결되거나 같은 방식으로 복구된다는 보장은 없다. 이번 장의 목표는 실전 주문을 켜는 것이 아니라, 필요한 검토가 빠지면 진행을 차단하는 구조와 확인 기록을 만드는 것이다.

이 책의 교육용 구현은 기본값이 live_enabled = false이며 외부 실전 주문 전송 코드를 제공하지 않는다. 모든 점검이 통과해도 로컬 안전 점검까지만 끝난다. 예제에는 실계좌 번호·주문 비밀번호·실전 주문 요청이 없다.

1. 실행 환경의 의미를 다시 확인하기

simulation, paper, 증권사 모의투자, 실전은 서로 다른 환경이다. 모드 문자열 하나를 바꾸어 같은 연결을 쓰는 구조를 피하고, 데이터 조회와 주문 권한도 분리한다.

한국투자증권의 현재 API 문서와 공지는 KIS Developers 공식 개발자센터에서 확인한다. 모의투자 지원 범위, 인증·요청 규격, 호출 제한을 기억에 의존해 실전 코드에 복사하지 않는다. 이 책의 로컬 판정은 증권사의 서비스 승인이나 투자 적합성 검증을 대신하지 않는다.

2. 실전 검토 전 필요한 증거를 정하기

체크리스트는 “예” 표시를 모으는 문서가 아니다. 코드·설정·실행 기록과 연결된 증거 목록이다. 확인하지 않은 항목은 NOT_EVALUATED, 하나라도 실패한 항목은 FAIL로 두며 기본 상태를 통과로 만들지 않는다.

“문제 없이 며칠 돌았다”라는 문장만으로 통과시키지 않는다. 몇 세션을 어떤 데이터로 처리했는지, 신호가 없던 날에도 중단 조건을 실제로 시험했는지 함께 쓴다. 정해진 횟수의 성공이 미래 안전을 증명하지는 않는다.

3. 설정은 기본 차단으로 읽기

config/safety.json 예시는 다음과 같다. 값이 없거나 타입이 다르거나 모르는 모드가 들어오면 오류로 종료한다. 환경변수의 문자열 "false"를 Python의 참값으로 잘못 처리하지 않도록 JSON의 불리언을 엄격하게 검사한다.

{
  "mode": "paper",
  "live_enabled": false,
  "order_transport": "none",
  "require_current_evidence": true,
  "block_on_unknown_state": true,
  "max_order_notional": "100000.00",
  "max_open_positions": 3,
  "kill_switch_path": "config/STOP_ALL"
}

한도는 의도 생성 전에 검사하고, 체결 또는 전송 직전에도 현재 상태로 다시 검사하는 항목이다. 다만 이 장의 한도는 로컬 가상 자금 시험에만 쓰인다. 한도를 작게 적었다고 실전 주문 전송을 안전하게 구현한 것이 아니다.

mode = live를 오타로 쓴 상황, live_enabled를 문자열로 준 상황, 설정 파일을 읽지 못한 상황 모두 차단되어야 한다. 읽기 실패 시 “편의를 위해 기본 실전 설정 사용” 같은 대체 경로를 만들지 않는다.

4. 해제 기능 없는 교육용 차단 코드 만들기

아래 코드는 모드 검증의 방향을 보여주는 최소 예제다. 실전 전송 함수나 주문 URL이 없으며, live 요청은 어떤 설정에서도 종료된다. 실제 서비스에 필요한 위험 통제 전체를 구현한 코드는 아니다.

class SafetyBlocked(RuntimeError):
    pass

def validate_educational_mode(config):
    mode = config.get("mode")
    enabled = config.get("live_enabled")
    transport = config.get("order_transport")
    if type(enabled) is not bool:
        raise SafetyBlocked("live_enabled must be a JSON boolean")
    if mode not in {"simulation", "paper", "live"}:
        raise SafetyBlocked("unknown execution mode")
    if mode == "live":
        raise SafetyBlocked("live transport is not provided in this book")
    if enabled or transport != "none":
        raise SafetyBlocked("external order configuration is forbidden")
    return mode

def educational_order_entry(config, paper_engine, intent):
    mode = validate_educational_mode(config)
    if mode != "paper":
        raise SafetyBlocked("paper order entry requires paper mode")
    return paper_engine.record_local_intent(intent)

paper_engine에도 실제 HTTP 주문 호출을 넣지 않는다. 의존성을 로컬 원장 객체로 제한하고, 주문 연결 라이브러리를 가져오지 않는지 검사한다. 이름만 paper_engine인 실제 주문 클라이언트를 전달하면 설계 의도가 무너지므로 생성 위치와 의존성도 함께 검토한다.

검토 증거를 확인하는 절차는 이 함수 앞에 추가할 수 있다. 그러나 증거가 모두 PASS여도 이 예제의 live 차단은 그대로 유지한다. 이 장을 마친 뒤의 정상 상태는 실전 전송 기능 없음이다.

5. 통과 기록은 버전과 유효 범위를 묶기

safety_checks에는 개별 점검을, safety_reviews에는 전체 판단을 남긴다. 기록에는 review_id, 코드 버전, 설정 해시, 데이터 식별자, 생성 시각, 검토 범위, 증거 경로를 포함한다. 원래 기록을 덮어쓰지 않고 재검토를 새 기록으로 추가한다.

review_id=demo-safety-01 scope=educational_local_paper
code_version=demo-v1 strategy_version=cci20_cross_up_m100_v1
check=ledger_reconciliation result=PASS evidence=reconcile-demo.json
check=restart_after_commit result=PASS evidence=recovery-demo.json
check=live_transport_available result=NOT_PROVIDED
decision=LOCAL_PAPER_ONLY external_orders_permitted=false

설정이나 코드가 바뀌면 이전 검토의 해시와 달라진다. 그 경우 새 실행을 허용할지 다시 검토한다. 체크리스트를 한 번 작성하고 영구 허가증으로 사용하지 않는다. 오래된 증거의 허용 기간도 운영 문서에서 정하되 유효 기간만 지나지 않았다는 이유로 현재 상태 점검을 생략하지 않는다.

별도 실전 시스템을 설계한다면 실제 주문 접수·체결·잔고 조회·정정·취소·응답 유실의 정합성을 각각 검토해야 한다. 이번 원고에는 그 연결이 없으므로 관련 항목을 완료했다고 표시하지 않는다.

6. 응답이 없을 때 재주문하지 않는 이유 이해하기

로컬 원장에서는 같은 DB 트랜잭션으로 상태를 묶을 수 있었다. 외부 주문 시스템은 네트워크 너머에 있으므로 요청 결과를 받지 못했어도 주문이 접수되었을 가능성이 있다. 단순 재시도는 중복 주문을 만들 수 있다.

실전 연결을 별도로 개발할 때 필요한 상태는 SUBMISSION_UNKNOWN, 대조 절차, 재주문 금지 규칙이다. 실제 주문 내역과 체결 내역을 조회해 결과를 확인하기 전에는 “실패했으니 다시 보내기”를 하지 않아야 한다. 이번 교육용 코드에서는 외부 전송 자체를 막아 이 상황을 만들지 않는다.

가상 시험으로는 외부 서버를 호출하지 않고 “결과 불명” 사건을 주입할 수 있다. 기대 결과는 새 의도 생성 차단, 기존 상태 보존, 담당자 확인 요청 기록이다. 가상 시험이 실제 증권사 API의 동작을 검증한 것은 아니라고 보고서에 쓴다.

7. 중단 수단과 복구 수단을 함께 준비하기

중단 파일 config/STOP_ALL은 새 원장 변경 전에 확인한다. 모니터링 화면에 중단 버튼이 있더라도 프로그램이 실제로 신호를 읽고 종료하는지 시험한다. 화면에 “중단”이라고 보이는 것과 진행 중 작업이 정지한 것은 다를 수 있다.

중단 시 로그에는 마지막 확정 단계, 미완료 의도 수, 예약현금, 마지막 대조 시각을 남긴다. 예제의 중단은 가상 포지션 청산을 의미하지 않는다. 유지된 포지션과 미처리 이벤트가 무엇인지 보고하고 이후 대조 절차를 거친다.

복구할 수 있는 백업과 재현 자료가 있어야 중단 뒤 상태를 확인할 수 있다. 비밀값을 제거한 코드·설정 예제·스키마·실행 증거를 보관하고, DB 복구는 별도 테스트 환경에서 시험한다. 백업 파일의 존재와 복구 성공을 구분한다.

8. Codex에는 차단 점검을 요청하기

교육용 자동매매 프로젝트의 안전 기본값과 차단 경로를 점검해줘.
실전 주문 전송 코드는 추가하거나 실행하지 마.
mode 누락, 오타, 문자열 false, live 모드, 외부 transport 설정을 모두 차단해.
paper 경로가 로컬 원장만 사용하며 실제 주문 클라이언트를 읽지 않는지 확인해.
중단 파일·오래된 증거·설정 해시 변경·대조 불일치를 가상 데이터로 시험해.
확인한 증거와 미검사 항목을 구분하고 결론은 LOCAL_PAPER_ONLY로 남겨.
계좌번호·토큰·비밀값을 읽거나 로그에 표시하지 마.

학습용 시험에서 정상인 결과는 mode=live → SafetyBlocked다. 모든 체크리스트가 채워졌다는 이유로 전송 기능을 자동 생성하거나 실전 설정을 채우지 않는다. 별도 개발이 필요한 항목은 문서에 남긴다.

9. 완료 기준과 문제 해결

완료 기준은 기본 설정이 로컬 paper이고, 누락·오타·실전 요청이 차단되며, 점검 기록이 코드·설정 버전과 연결되는 것이다. 이번 장의 산출물은 체크리스트와 차단 시험 결과이며 실제 주문 성공 기록이 아니다.

다음 장에서는 이 제한을 유지하면서 운영 기록과 변경 검토를 반복하는 방법을 정리한다.

시세 한 건을 조회했다면 다음 목표는 계산에 쓸 일봉 자료를 일정한 형식으로 모으는 것이다. 이 장에서는 대상 종목 목록 고정 → 기간별 시세 조회 → 검증 → CSV와 실행 요약 저장 순서로 진행한다. 먼저 실제 종목 1개, 다음 5개를 확인한 뒤 범위를 넓힌다.

이 책의 CSV와 다음 장의 SQL은 symbol, trade_date, open, high, low, close, volume이라는 공통 컬럼을 사용한다. 모든 날짜는 거래소의 거래일 기준이며, 일봉은 해당 거래일의 수집을 마친 데이터만 사용한다.

1. 코스피200 목록의 기준일 보관하기

코스피200은 분석 범위를 일정하게 정하기 위한 출발점이다. 구성 종목은 바뀔 수 있다. 현재 구성 종목만 골라 과거 성과를 계산하면 당시 제외되었거나 상장폐지된 종목을 놓치는 생존 편향이 생길 수 있다. 이 문제는 수집 성공 여부와 별도로 기록한다.

KRX Data Marketplace에서 지수의 구성 종목과 조회 기준일을 확인하고, 제공되는 내려받기 기능으로 원본을 보관한다. 화면의 메뉴와 다운로드 조건은 바뀔 수 있으므로 비공식 URL이나 로그인 우회 방식에 의존하지 않는다.

원본을 outputs/universe/raw/에 두고, 프로젝트가 읽는 outputs/universe/kospi200.csv를 다음 컬럼으로 정리한다.

종목코드는 숫자만 있다고 가정하지 않는다. 예를 들어 삼성에피스홀딩스 공식 주식정보는 0126Z0을 사용한다. 이 책은 [A-Z0-9]{6}을 공통 형식으로 사용하며, 소문자·Unicode 유사 문자는 거부한다.

종목 수가 예상과 다르면 단순히 200개에 맞추려고 행을 삭제하지 않는다. 조회한 지수·기준일·중복·빈 코드를 확인한다. 현재 목록만 확보한 상태라면 결과 문서에도 “현재 구성 종목을 과거에 적용한 탐색”이라고 명시한다.

2. 일봉 조회의 기준 정하기

기간별 일봉은 고가·저가·종가뿐 아니라 다음 장에서 사용할 시가도 함께 저장한다. 거래량 0은 가능하지만 가격이 0인 행을 정상 거래일 가격으로 임의 보정하지 않는다. 거래 정지나 공급자 표시 방식인지 확인하고 별도 점검 대상으로 둔다.

이번 실습의 기준은 다음과 같다.

• 시장 구분 J: KRX 기준 시세
• 기간 구분 D: 일봉
• 가격 구분 0: 수정주가
• 한 행의 식별자: (symbol, trade_date)
• 계산 순서: 종목별 거래일 오름차순

이 값과 응답 필드는 한국투자증권 공식 기간별시세 예제를 기준으로 했다. 공식 예제는 한 번의 호출에서 최대 100건을 안내한다. 여기서는 달력 기준 80일 이하로 구간을 잘라 그 제한 안에서 요청한다. 긴 기간을 한 번 호출하고 전체를 받았다고 가정하지 않는다.

수정주가는 기업행사에 따라 과거 값이 바뀔 수 있다. 수집 일시, 가격 구분과 원본을 함께 기록한다. 일봉 지표 계산과 주문 수량·현금 정산의 가격 체계가 다르면 시뮬레이션도 달라지므로, 실제 체결을 재현하는 단계에서는 기업행사 처리까지 별도로 설계한다.

3. 응답을 공통 컬럼으로 정리하기

src/collect_daily.py에 다음 내용을 작성한다. 3장의 ReadOnlyKis를 그대로 사용한다. 공급자 필드와 프로젝트 필드를 바꾸는 부분을 별도 함수로 두면 가짜 응답으로도 검증할 수 있다.

import argparse
from datetime import date, timedelta
from pathlib import Path
import time

import pandas as pd

from src.kis_readonly import ROOT, ReadOnlyKis, load_config

FIELDS = {
    "stck_bsop_date": "trade_date",
    "stck_oprc": "open",
    "stck_hgpr": "high",
    "stck_lwpr": "low",
    "stck_clpr": "close",
    "acml_vol": "volume",
}
PRICE_COLUMNS = ["open", "high", "low", "close"]
COLUMNS = ["symbol", "trade_date", *PRICE_COLUMNS, "volume"]


def normalize(symbol, records):
    if not records:
        raise ValueError("No daily records returned")
    frame = pd.DataFrame(records)
    missing = set(FIELDS) - set(frame.columns)
    if missing:
        raise ValueError(f"Missing daily fields: {sorted(missing)}")
    frame = frame.loc[frame["stck_bsop_date"].fillna("").ne(""), list(FIELDS)]
    frame = frame.rename(columns=FIELDS).copy()
    if frame.empty:
        raise ValueError("All returned dates are empty")
    frame["trade_date"] = pd.to_datetime(
        frame["trade_date"], format="%Y%m%d", errors="raise"
    ).dt.date
    for column in [*PRICE_COLUMNS, "volume"]:
        values = pd.to_numeric(frame[column], errors="raise")
        if values.isna().any() or values.mod(1).ne(0).any():
            raise ValueError(f"Non-integer value in {column}")
        frame[column] = values.astype("int64")
    invalid = (
        frame[PRICE_COLUMNS].le(0).any(axis=1)
        | frame["volume"].lt(0)
        | frame["high"].lt(frame[["open", "close", "low"]].max(axis=1))
        | frame["low"].gt(frame[["open", "close", "high"]].min(axis=1))
    )
    if invalid.any():
        raise ValueError(f"Invalid OHLCV rows: {int(invalid.sum())}")
    frame["symbol"] = symbol
    frame = frame.drop_duplicates()
    if frame.duplicated(["symbol", "trade_date"]).any():
        raise ValueError("Conflicting rows for the same symbol and date")
    return frame[COLUMNS].sort_values(["symbol", "trade_date"]).reset_index(drop=True)


def collect_symbol(client, symbol, start, end):
    records = []
    cursor = start
    while cursor <= end:
        window_end = min(cursor + timedelta(days=79), end)
        body = client.quotations("daily", {
            "FID_COND_MRKT_DIV_CODE": "J",
            "FID_INPUT_ISCD": symbol,
            "FID_INPUT_DATE_1": cursor.strftime("%Y%m%d"),
            "FID_INPUT_DATE_2": window_end.strftime("%Y%m%d"),
            "FID_PERIOD_DIV_CODE": "D",
            "FID_ORG_ADJ_PRC": "0",
        })
        output = body.get("output2")
        if not isinstance(output, list):
            raise ValueError("output2 must be a list")
        records.extend(output)
        cursor = window_end + timedelta(days=1)
        time.sleep(1.0)
    frame = normalize(symbol, records)
    if frame["trade_date"].lt(start).any() or frame["trade_date"].gt(end).any():
        raise ValueError("The response contains a date outside the requested range")
    return frame


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--start", type=date.fromisoformat, required=True)
    parser.add_argument("--end", type=date.fromisoformat, required=True)
    parser.add_argument("--limit", type=int, default=1)
    args = parser.parse_args()
    if args.start > args.end or args.limit < 1:
        parser.error("Check the date range and limit")
    universe = pd.read_csv(
        ROOT / "outputs/universe/kospi200.csv", dtype={"symbol": "string"}
    )
    symbols = universe["symbol"]
    if symbols.isna().any() or not symbols.str.fullmatch(r"[A-Z0-9]{6}").all():
        raise ValueError("Universe contains invalid symbols")
    if symbols.duplicated().any():
        raise ValueError("Universe contains duplicate symbols")
    target = ROOT / "outputs/daily"
    target.mkdir(parents=True, exist_ok=True)
    manifest = []
    client = ReadOnlyKis(load_config())
    try:
        for symbol in symbols.head(args.limit):
            try:
                frame = collect_symbol(client, symbol, args.start, args.end)
                name = f"{symbol}_{args.start}_{args.end}.csv"
                frame.to_csv(target / name, index=False, encoding="utf-8-sig")
                manifest.append({"symbol": symbol, "status": "ok", "rows": len(frame),
                                 "first": frame.trade_date.min(), "last": frame.trade_date.max()})
            except Exception as exc:
                manifest.append({"symbol": symbol, "status": "failed", "rows": 0,
                                 "error_type": type(exc).__name__})
    finally:
        client.close()
    summary = pd.DataFrame(manifest)
    summary.to_csv(target / "collection_manifest.csv", index=False, encoding="utf-8-sig")
    print(summary.to_string(index=False))
    if summary["status"].ne("ok").any():
        raise SystemExit(1)


if __name__ == "__main__":
    main()

CSV를 읽을 때 symbol을 문자열로 지정해야 005930의 앞자리 0이 유지된다. CSV 인코딩은 Windows에서 열기 편한 utf-8-sig로 맞췄다. pandas 공식 read_csv 문서

4. 한 종목부터 수집하기

다음은 이미 끝난 기간을 지정한 실행 예시다. 자신의 수집 목적에 맞게 날짜를 바꾸되 아직 끝나지 않은 당일 일봉은 완료 자료와 섞지 않는다.

.\.venv\Scripts\python.exe -m py_compile src/collect_daily.py
.\.venv\Scripts\python.exe -m src.collect_daily --start 2026-01-01 --end 2026-10-16 --limit 1

성공하면 outputs/daily/종목코드_시작일_종료일.csv와 collection_manifest.csv가 생긴다. rows가 양수이고 first·last가 요청 범위 안에 있어야 한다. 시작일이 휴일이거나 상장일보다 빠르면 첫 거래일이 시작일보다 늦을 수 있다.

한 종목의 CSV를 열어 순서와 숫자를 확인한 뒤 --limit 5로 확장한다. 전체 종목을 수집할 때도 정상 종목 수, 실패 종목 수, 범위별 행 수를 확인한다. 코드의 1초 간격은 교육용 기본값이며 현재 호출 한도를 보장하는 값이 아니다. 서버 환경별 한도와 오류 안내는 한국투자증권 API 포털에서 확인한다.

응답이 빈 구간은 상장 전·휴일·API 이상 여부를 확인한다. 위 예제는 모든 구간이 합쳐진 최종 결과만 검사하므로 거래일 누락을 완전히 검출하지는 않는다. 거래소 영업일 달력과 대조하고 거래 정지·신규 상장 사유를 기록하는 검사를 운영 전에 추가한다.

5. 부분 성공을 전체 성공으로 보지 않기

collection_manifest.csv의 실패 행은 해당 실행에서 완성된 CSV로 인정하지 않는다. 같은 파일명이 이전 실행에서 이미 존재할 수 있으므로 파일 존재 여부만으로 성공을 판단하지 않는다. 운영용으로 확장할 때는 실행 ID별 폴더와 완료 표시를 사용하고, 이번 실행에서 성공한 파일만 다음 단계가 읽도록 한다.

정상 데이터의 확인 순서는 요청 목록 → 성공 목록 → 파일 → 필수 컬럼 → 중복 → 가격 범위 → 거래일 누락이다. 휴일을 채우려고 전날 가격으로 새로운 일봉을 만들지 않는다. 원본 자료를 남겨야 누락 원인이 수집인지 공급자 데이터인지 다시 확인할 수 있다.

6. Codex에 수집 품질 검사 요청하기

auto-trading-lab의 코스피200 일봉 수집기를 점검해줘.
구성 종목 목록의 기준일과 원본 출처를 남기고 symbol은 ASCII 숫자·영문 대문자 6자리 문자열로 처리해줘.
공식 기간별시세 API의 건수 제한 안에서 기간을 분할해줘.
symbol/trade_date/open/high/low/close/volume 형식을 고정하고,
중복 충돌·음수 거래량·잘못된 OHLC·미완료 일봉을 검사해줘.
실패 종목이 있으면 전체 성공으로 보고하지 말고 실행 요약에 구분해줘.
가짜 응답으로 빈 결과, 역순 날짜, 중복 충돌을 검사하고 실제 API 실행 여부를 명시해줘.
이번 작업은 CSV까지만이며 DB 저장과 주문은 다음 단계로 남겨줘.

7. 오류 대응과 완료 기준

이번 장을 마치면 기준일이 있는 종목 목록, 검증된 일봉 CSV, 성공·실패 요약이 있어야 한다. 가짜 응답 검사를 통과했다는 것과 실제 전체 종목 수집을 마쳤다는 것은 서로 다른 검증 결과다. 다음 장에서는 이번 실행에서 검증된 CSV만 MySQL에 저장한다.

MySQL에 저장한 일봉을 이용해 CCI를 계산하고, 정해진 경계선을 넘는 날을 신호로 기록한다. 이번 장의 결과는 종목별 20거래일 CCI와 진입 후보 신호다. 이 신호를 주문으로 전환하지 않으며, 다음 장에서 과거 데이터로 동작과 한계를 확인한다.

예제 규칙은 전일 CCI <= -100이고 당일 CCI > -100일 때 신호를 한 번 기록하는 것이다. 이는 계산과 시뮬레이션을 연결하기 위한 학습 규칙이며, 특정 종목이나 매매 방법의 수익성을 추천하는 뜻이 아니다.

1. CCI 계산식 이해하기

CCI는 오늘의 대표가격이 최근 대표가격 평균에서 얼마나 떨어져 있는지를 평균절대편차로 나눈 지표다. 대표가격 TP는 고가·저가·종가의 평균이다. 기간을 20거래일로 정하면 오늘을 포함한 최근 20개 관측값을 한 창으로 계산한다.

TP[t] = (high[t] + low[t] + close[t]) / 3
SMA[t] = 최근 20개 TP의 평균
MD[t] = 최근 20개 각각의 TP와 동일한 SMA[t] 간 절대 차이의 평균
CCI[t] = (TP[t] - SMA[t]) / (0.015 × MD[t])

MD[t]를 구할 때는 그 창 안의 모든 값에서 같은 창의 평균을 뺀다. 각 날짜의 별도 이동평균을 먼저 빼고 그 차이에 다시 이동평균을 적용하면 다른 계산이 된다. CCI의 대표가격·평균절대편차 공식은 Fidelity의 지표 설명을 참고했다.

CCI는 -100과 100 사이에 제한된 지표가 아니다. 범위 밖으로 크게 움직일 수 있고 낮은 값이 계속 유지될 수도 있다. 따라서 CCI <= -100이라는 상태와 -100을 위로 통과했다는 사건을 구분한다. 이번 규칙은 두 번째 사건만 기록한다.

2. 계산 전 데이터와 예외 기준 정하기

5장의 daily_prices에서 symbol, trade_date, open, high, low, close, volume을 읽는다. 최소한 다음 조건을 통과해야 한다.

• 종목코드는 ASCII 숫자·영문 대문자 6자리이며, 종목코드와 거래일 조합이 중복되지 않는다.
• 각 종목 안에서 거래일이 오름차순이다.
• 가격은 유한한 양수이고 OHLC의 범위가 맞는다.
• 종목이 바뀌면 이동 계산과 전일 비교도 새로 시작한다.
• 계산 시작일 전에 필요한 준비 기간을 함께 읽는다.

처음 19개 관측값은 20개가 모이지 않았으므로 CCI가 없다. 20개가 모두 같은 대표가격이면 평균절대편차가 0이므로 역시 계산 불가로 둔다. 두 경우 모두 NaN으로 유지하며 DB에서는 NULL로 저장한다. 0으로 바꾸면 실제 중립값처럼 보일 수 있다.

신호에는 전일과 당일의 유효한 CCI가 모두 필요하다. 따라서 처음 유효한 CCI가 생긴 날은 신호를 만들지 않는다. 거래 정지나 누락으로 관측일 간격이 벌어진 경우, 이번 장의 계산은 존재하는 20개 거래 관측값을 사용한다. 데이터 품질 검사는 계산기 밖에서 별도로 유지한다.

3. 종목별 CCI 계산 함수 작성하기

src/calculate_cci.py에 다음 코드를 작성한다. 이동 창의 min_periods=period를 지정해 준비 기간을 명확히 하고, 미래 값이 들어오는 중앙 정렬은 사용하지 않는다. 창과 최소 관측수의 의미는 pandas 공식 rolling 문서를 참고한다.

import argparse
import math
import re

import mysql.connector
import pandas as pd

from src.kis_readonly import ROOT, load_config


def cross_up(values, threshold=-100.0):
    previous = values.shift(1)
    return (previous.le(threshold) & values.gt(threshold)).fillna(False).astype(bool)


def calculate_cci(frame, period=20):
    if period < 2:
        raise ValueError("period must be at least 2")
    required = {"symbol", "trade_date", "open", "high", "low", "close"}
    if required - set(frame.columns) or frame.empty:
        raise ValueError("Prices are empty or missing required columns")
    data = frame.copy()
    if data[["symbol", "trade_date"]].isna().any().any():
        raise ValueError("Missing symbol or trade date")
    data["trade_date"] = pd.to_datetime(data.trade_date, errors="raise")
    if data["trade_date"].isna().any():
        raise ValueError("Missing trade date")
    if data.duplicated(["symbol", "trade_date"]).any():
        raise ValueError("Duplicate symbol/date")
    for column in ["open", "high", "low", "close"]:
        data[column] = pd.to_numeric(data[column], errors="raise").astype(float)
        if not data[column].map(lambda x: math.isfinite(x) and x > 0).all():
            raise ValueError(f"Invalid price in {column}")
    invalid = (
        data.high.lt(data[["open", "low", "close"]].max(axis=1))
        | data.low.gt(data[["open", "high", "close"]].min(axis=1))
    )
    if invalid.any():
        raise ValueError("Invalid OHLC range")
    data = data.sort_values(["symbol", "trade_date"]).reset_index(drop=True)
    results = []
    for symbol, group in data.groupby("symbol", sort=False):
        group = group.copy()
        typical = (group.high + group.low + group.close) / 3.0
        window = typical.rolling(window=period, min_periods=period)
        average = window.mean()
        deviation = window.apply(lambda values: abs(values - values.mean()).mean(), raw=True)
        denominator = (0.015 * deviation).where(deviation.gt(0))
        cci = (typical - average) / denominator
        group["typical_price"] = typical
        group["mean_deviation"] = deviation
        group[f"cci_{period}"] = cci
        group["entry_signal"] = cross_up(cci)
        results.append(group)
    return pd.concat(results, ignore_index=True)


def read_prices(symbols):
    config = load_config()
    connection = mysql.connector.connect(
        host=config["MYSQL_HOST"],
        port=int(config.get("MYSQL_PORT", "3306")),
        user=config["MYSQL_USER"],
        password=config["MYSQL_PASSWORD"],
        database=config["MYSQL_DATABASE"],
        connection_timeout=10,
    )
    cursor = None
    try:
        cursor = connection.cursor(dictionary=True)
        marks = ",".join(["%s"] * len(symbols))
        sql = (
            "SELECT symbol, trade_date, open, high, low, close, volume "
            f"FROM daily_prices WHERE symbol IN ({marks}) "
            "ORDER BY symbol, trade_date"
        )
        cursor.execute(sql, tuple(symbols))
        return pd.DataFrame(cursor.fetchall())
    finally:
        if cursor is not None:
            cursor.close()
        connection.close()


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--symbols", nargs="+", required=True)
    args = parser.parse_args()
    if any(not re.fullmatch(r"[A-Z0-9]{6}", s) for s in args.symbols):
        parser.error("Use six-character uppercase ASCII stock symbols")
    frame = read_prices(args.symbols)
    if frame.empty or set(args.symbols) - set(frame["symbol"]):
        raise ValueError("One or more requested symbols have no stored prices")
    result = calculate_cci(frame, period=20)
    target = ROOT / "outputs/indicators"
    target.mkdir(parents=True, exist_ok=True)
    result.to_csv(target / "cci_20.csv", index=False, encoding="utf-8-sig")
    summary = result.groupby("symbol").agg(
        rows=("trade_date", "size"),
        valid_cci=("cci_20", "count"),
        signals=("entry_signal", "sum"),
    )
    print(summary.to_string())


if __name__ == "__main__":
    main()

read_prices는 SQL의 자리표시자 개수만 만들고 종목코드 값은 별도로 바인딩한다. CCI 계산 중 다른 종목의 직전 행을 읽지 않도록 그룹 안에서 shift(1)을 수행한다. 이 예제의 집계와 정렬은 pandas 공식 GroupBy 안내의 데이터 분리 원리를 따른다.

4. 인공 데이터로 계산과 신호 경계 확인하기

실제 주가를 보기 전에 손으로 답을 구할 수 있는 자료를 사용한다. 아래 코드는 scripts/check_cci.py로 저장하고 프로젝트 루트에서 모듈로 실행한다. 가짜 가격은 특정 종목의 실제 수익률 자료가 아니다.

import pandas as pd

from src.calculate_cci import calculate_cci, cross_up


def prices(symbol, values):
    return pd.DataFrame({
        "symbol": symbol,
        "trade_date": pd.date_range("2026-01-01", periods=len(values), freq="D"),
        "open": values, "high": values, "low": values, "close": values,
    })


rising = calculate_cci(prices("000001", list(range(1, 21))))
assert rising.cci_20.iloc[:19].isna().all()
assert abs(rising.cci_20.iloc[19] - 126.6666666667) < 1e-8
assert not rising.entry_signal.any()

flat = calculate_cci(prices("000002", [10] * 25))
assert flat.cci_20.isna().all()
assert not flat.entry_signal.any()

mixed = calculate_cci(pd.concat([
    prices("000001", list(range(1, 26))),
    prices("000002", [10] * 25),
]).sample(frac=1, random_state=7))
assert mixed.groupby("symbol").cci_20.count().to_dict() == {"000001": 6, "000002": 0}

values = pd.Series([float("nan"), -120, -100, -99, -80, -110, -90])
assert cross_up(values).tolist() == [False, False, False, True, False, False, True]
print("synthetic CCI checks OK")

.\.venv\Scripts\python.exe -m scripts.check_cci

첫 예제는 평균 10.5, 평균절대편차 5, 마지막 대표가격 20이므로 CCI가 약 126.6667이다. 두 번째는 0으로 나누는 경우를, 세 번째는 정렬과 종목 간 분리를 확인한다. 마지막 예제에서 정확히 -100에 도착한 날은 신호가 없고 -100보다 커진 날에만 신호가 발생한다.

5. 실제 DB 자료로 결과 확인하기

수집·저장이 끝난 종목 하나부터 실행한다. 실제 보유 종목이나 매수 대상으로 선정하는 절차는 아니다.

.\.venv\Scripts\python.exe -m src.calculate_cci --symbols 005930

outputs/indicators/cci_20.csv를 열어 앞부분의 결측값, 날짜 순서, 대표가격과 평균절대편차를 확인한다. rows는 읽은 일봉 수, valid_cci는 계산 가능한 행 수, signals는 경계 통과 횟수다. 신호가 0건이어도 규칙에 맞는 데이터라면 정상 결과다.

특정 검토 기간만 계산할 때는 그 기간 이전 자료를 충분히 읽고, 계산을 마친 다음 보고할 날짜를 자른다. 처음부터 검토 시작일 이후 행만 읽으면 준비 기간이 잘려 앞부분의 신호가 달라진다. 마지막 일봉은 거래일 종료 후 확정된 자료인지도 확인한다.

6. 계산 결과의 저장 키와 버전 정하기

CSV로 계산을 확인한 뒤 DB에 결과를 보관할 수 있다. 다음 스키마는 지표 값과 신호 규칙의 버전을 함께 남기는 예시다.

CREATE TABLE IF NOT EXISTS cci_daily_signals (
  symbol CHAR(6) NOT NULL,
  trade_date DATE NOT NULL,
  period SMALLINT UNSIGNED NOT NULL,
  strategy_version VARCHAR(40) NOT NULL,
  cci_value DOUBLE NULL,
  entry_signal BOOLEAN NOT NULL,
  calculated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (symbol, trade_date, period, strategy_version)
) ENGINE=InnoDB;

이번 버전 이름은 cci20_cross_up_m100_v1로 정한다. cci_20을 cci_value에 저장하고, NaN은 None으로 변환해 SQL의 NULL로 바인딩한다. 같은 키를 재계산하면 갱신하고, 공식이나 신호 규칙이 바뀌면 버전 이름을 바꾼다. 적재의 트랜잭션과 중복 처리 방식은 5장과 같다.

값을 NULL로 저장하는 것과 값이 0인 것은 다르다. DB를 다시 읽을 때도 결측 의미를 보존한다. MySQL 공식 NULL 설명

7. Codex에 계산 검증 요청하기

daily_prices를 읽어 20거래일 CCI와 -100 상향 돌파 신호를 계산해줘.
MD는 같은 창의 평균에 대한 평균절대편차로 계산해줘.
첫 19개 행과 MD=0은 결측, 전일 값이 없으면 신호 False로 유지해줘.
종목별 정렬·그룹 분리·중복 검사를 하고 미래 값을 사용하지 마.
손계산 가능한 상승 자료, 일정한 가격, 섞인 두 종목, 경계값 사례를 검사해줘.
신호는 전일 <= -100 이면서 당일 > -100일 때만 True로 기록해줘.
결과 CSV와 요약을 만들고, 실제 DB 접속 여부와 합성 검사 결과를 구분해줘.
주문이나 성과 주장은 추가하지 말고 계산 근거와 남은 검증 범위를 보고해줘.

8. 오류 대응과 다음 장의 연결

완료 기준은 계산식, 준비 기간, MD=0 처리, 상향 돌파 규칙을 코드와 결과로 설명할 수 있는 상태다. 신호가 발생한 날의 종가를 이미 알고 계산했으므로 그 종가에 즉시 체결된 것으로 가정하지 않는다. 다음 장에서는 T일 신호 → 다음 거래일 시가라는 시간 순서를 고정해 시뮬레이션한다.