# 🔤 인코딩 가이드 (필독!)

> ⚠️ **중요**: 한글 데이터 처리 시 반드시 이 가이드를 따를 것

---

## ✅ 현재 설정 (2025-06-30 적용됨)

```
환경변수: PYTHONIOENCODING=utf-8 (User 레벨)
```

이 설정으로 모든 Python 스크립트에서 UTF-8 출력이 기본 적용됩니다.

---

## 📋 문제 상황

### 증상
```
DB 실제 값: "안텔민뽀삐"
콘솔 출력:  "안텔민사사"  ← 깨져서 다른 글자로 보임!
```

### 원인
```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  DB (UTF-8)  │ ──► │    Python    │ ──► │ Windows 콘솔 │
│  "뽀삐"      │     │   stdout     │     │   (CP949)    │
│  U+BF40      │     │              │     │   "사사"     │
└──────────────┘     └──────────────┘     └──────────────┘
                                                  ↑
                                          인코딩 변환 실패!
```

- Windows 콘솔 기본 인코딩: **CP949** (한국어 완성형)
- CP949에서 지원하지 않거나 다르게 매핑되는 유니코드 문자 존재
- "뽀삐" 같은 글자가 "사사"로 잘못 표시됨

---

## ✅ 해결책

### 1. 스크립트 상단에 인코딩 설정 추가 (필수!)

```python
# -*- coding: utf-8 -*-
import sys
import io

# stdout을 UTF-8로 강제 설정
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8', errors='replace')
```

### 2. 환경변수 설정 (권장)

```powershell
# PowerShell에서 실행 전 설정
$env:PYTHONIOENCODING = "utf-8"

# 또는 시스템 환경변수로 영구 설정
[Environment]::SetEnvironmentVariable("PYTHONIOENCODING", "utf-8", "User")
```

### 3. Windows Terminal UTF-8 모드

```powershell
# 콘솔 코드페이지를 UTF-8로 변경
chcp 65001
```

### 4. JSON 출력 사용 (가장 안전)

```python
import json

# 콘솔 출력 대신 JSON으로 반환
result = {
    "product_name": "안텔민뽀삐",
    "apc": "0230237010107"
}
print(json.dumps(result, ensure_ascii=False, indent=2))
```

---

## 📝 스크립트 템플릿

모든 DB 조회 스크립트는 이 템플릿을 사용할 것:

```python
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
스크립트 설명
"""
import sys
import io
import json

# ═══════════════════════════════════════════════════════════
# 인코딩 설정 (Windows CP949 문제 방지)
# ═══════════════════════════════════════════════════════════
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8', errors='replace')

# ═══════════════════════════════════════════════════════════
# 메인 로직
# ═══════════════════════════════════════════════════════════

def main():
    # ... 로직 ...
    
    # 결과는 JSON으로 출력 (가장 안전)
    result = {"data": [...]}
    print(json.dumps(result, ensure_ascii=False, indent=2))

if __name__ == '__main__':
    main()
```

---

## 🔧 기존 스크립트 수정 목록

| 스크립트 | 상태 | 수정 필요 |
|----------|------|-----------|
| `scripts/query_mileage.py` | ⚠️ | 인코딩 설정 추가 |
| `scripts/query_sales.py` | ⚠️ | 인코딩 설정 추가 |
| `scripts/query_aniparm.py` | ⚠️ | 인코딩 설정 추가 |
| `scripts/search_mssql.py` | ⚠️ | 인코딩 설정 추가 |
| `scripts/check_*.py` | ⚠️ | 인코딩 설정 추가 |

---

## 🧪 테스트 방법

```python
# 인코딩 테스트 스크립트
# -*- coding: utf-8 -*-
import sys
import io

sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')

test_words = ["뽀삐", "킹", "안텔민뽀삐(5kg이하)", "다이로하트정M(12~22kg)"]

for word in test_words:
    print(f"원본: {word}")
    print(f"유니코드: {[f'U+{ord(c):04X}' for c in word]}")
    print()
```

---

## ⚠️ 주의사항

1. **절대 CP949 출력을 믿지 말 것** - 깨진 글자가 다른 글자로 보일 수 있음
2. **DB 데이터 확인 시** - 직접 DB 툴로 확인하거나 JSON 출력 사용
3. **AI 분석 시** - 유니코드 코드포인트로 확인 (U+XXXX)
4. **매핑 작업 시** - 반드시 양쪽 DB 직접 확인 후 진행

---

*작성일: 2025-06-30*
*사유: "뽀삐"가 "사사"로 잘못 표시되는 인코딩 문제 발생*