# Korea Investment Stock API Project Rules

## 환경 변수 사용 규칙

### 1. API 인증 정보 관리
- **절대로 .env 파일을 사용하지 않습니다**
- 모든 API 인증 정보는 OS 환경 변수로 관리합니다
- 다음 환경 변수들이 필수로 설정되어야 합니다:
  - `KOREA_INVESTMENT_API_KEY`: 한국투자증권 API 키
  - `KOREA_INVESTMENT_API_SECRET`: 한국투자증권 API 시크릿
  - `KOREA_INVESTMENT_ACCOUNT_NO`: 계좌번호

### 2. 환경 변수 설정 방법
```bash
# ~/.zshrc 또는 ~/.bashrc에 추가
export KOREA_INVESTMENT_API_KEY="your-api-key"
export KOREA_INVESTMENT_API_SECRET="your-api-secret"
export KOREA_INVESTMENT_ACCOUNT_NO="your-account-number"
```

### 3. 환경 변수 명명 규칙
- **일관성 유지**: 항상 `KOREA_INVESTMENT_` 접두사 사용
  - ✅ 올바른 예: `KOREA_INVESTMENT_API_KEY`
  - ❌ 잘못된 예: `KI_API_KEY`, `KOREA_INVESTMENT_ACC_NO`
- 계좌번호는 `KOREA_INVESTMENT_ACCOUNT_NO` 사용 (ACC_NO 아님)
- 단어 구분은 언더스코어(_) 사용
- 모두 대문자로 작성

### 4. 코드에서 환경 변수 사용
```python
import os

# 필수 환경 변수
api_key = os.getenv('KOREA_INVESTMENT_API_KEY')
api_secret = os.getenv('KOREA_INVESTMENT_API_SECRET')
account_no = os.getenv('KOREA_INVESTMENT_ACCOUNT_NO')
```

### 5. 주의사항
- 환경 변수를 하드코딩하지 마세요
- 코드 커밋 시 실제 API 키나 시크릿이 포함되지 않도록 주의하세요
- python-dotenv 패키지를 사용하지 마세요
- .env 파일을 생성하지 마세요
- 환경 변수가 설정되지 않은 경우 명확한 에러 메시지를 제공하세요

### 6. 환경 변수 검증
```python
# 프로그램 시작 시 필수 환경 변수 검증
required_env_vars = {
    'KOREA_INVESTMENT_API_KEY': 'API 키',
    'KOREA_INVESTMENT_API_SECRET': 'API 시크릿',
    'KOREA_INVESTMENT_ACCOUNT_NO': '계좌번호'
}

missing_vars = []
for var, description in required_env_vars.items():
    if not os.getenv(var):
        missing_vars.append(f"{var} ({description})")

if missing_vars:
    print("❌ 다음 환경 변수가 설정되지 않았습니다:")
    for var in missing_vars:
        print(f"  - {var}")
    print("\n💡 설정 방법:")
    print("~/.zshrc 또는 ~/.bashrc 파일에 다음을 추가하세요:")
    for var in missing_vars:
        var_name = var.split(' ')[0]
        print(f"export {var_name}='your-value'")
    raise ValueError("필수 환경 변수가 설정되지 않았습니다.")
```

### 7. 문서화
- README.md에 환경 변수 설정 방법을 명확히 기재하세요
- 예제 코드에서도 환경 변수 사용을 일관되게 유지하세요
- 새로운 환경 변수 추가 시 이 문서를 업데이트하세요

### 8. 테스트 환경
- 테스트 코드에서는 mock 환경 변수 사용 가능
- 단, 실제 API 호출 테스트 시에는 실제 환경 변수 필요
- CI/CD 환경에서는 별도의 테스트용 환경 변수 설정

## Python 개발 환경

### 1. 가상환경 사용
- 모든 Python 스크립트는 `.venv` 가상환경을 활성화하여 실행합니다
- 프로젝트별 의존성 격리를 위해 가상환경 사용을 필수로 합니다

### 2. 가상환경 설정 및 활성화
```bash
# 가상환경 생성 (프로젝트 루트에서)
python -m venv .venv

# 가상환경 활성화 (macOS/Linux)
source .venv/bin/activate

# 가상환경 활성화 (Windows)
.venv\Scripts\activate

# 의존성 설치
pip install -e .
```

### 3. 스크립트 실행 규칙
```bash
# ❌ 잘못된 실행 방법
python examples/ipo_schedule_example.py

# ✅ 올바른 실행 방법
source .venv/bin/activate && python examples/ipo_schedule_example.py

# 또는 가상환경의 Python 직접 사용
.venv/bin/python examples/ipo_schedule_example.py
```

### 4. IDE 설정
- VSCode, PyCharm 등의 IDE에서 인터프리터를 `.venv/bin/python`으로 설정
- 터미널을 열 때 자동으로 가상환경이 활성화되도록 설정

### 5. 의존성 관리
- **requirements.txt를 사용하지 않습니다**
- 모든 의존성은 `pyproject.toml`에서 관리합니다
- 프로젝트 메타데이터와 의존성을 한 곳에서 관리하여 일관성 유지

```toml
# pyproject.toml 예시
[project]
name = "korea-investment-stock"
version = "0.4.1"
dependencies = [
    "requests",
    "pandas",
    "websockets",
    # ... 기타 의존성
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black",
    "mypy",
]
```

```bash
# 의존성 설치
pip install -e .

# 개발 의존성 포함 설치
pip install -e ".[dev]"
```

## 코드 스타일
- Python 3.11+ 문법을 사용합니다
- Type hints를 적극 활용합니다
- 한글 주석과 문서화를 권장합니다
- 에러 메시지는 한글로 작성하여 사용자 친화적으로 만듭니다 