pharmacy-pos-qr-system/docs/ENCODING_GUIDE.md

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

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

---

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

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

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

---

📋 문제 상황

증상

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

원인

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

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

---

✅ 해결책

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

# -*- 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에서 실행 전 설정
$env:PYTHONIOENCODING = "utf-8"

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

3. Windows Terminal UTF-8 모드

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

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

import json

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

---

📝 스크립트 템플릿

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

#!/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	⚠️	인코딩 설정 추가

---

🧪 테스트 방법

# 인코딩 테스트 스크립트
# -*- 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 사유: "뽀삐"가 "사사"로 잘못 표시되는 인코딩 문제 발생