docs: PAAI 자동인쇄 트러블슈팅 가이드 작성

- 자동인쇄 토글 문제 해결법
- Flask/브라우저 캐시 문제
- 프린터 출력 안 될 때
- 한글 깨짐 해결 (EUC-KR)
- WebSocket 연결 실패
- 디버깅 체크리스트
- 전체 플로우 요약

docs/PAAI_AUTO_PRINT_TROUBLESHOOTING.md

@@ -0,0 +1,232 @@
+# PAAI 자동인쇄 트러블슈팅 가이드
+
+## 개요
+
+PAAI(처방 AI 분석) 결과를 영수증 프린터로 자동 출력하는 기능의 트러블슈팅 가이드입니다.
+
+---
+
+## 시스템 구성
+
+```
+[처방 접수] → [WebSocket 감지] → [PAAI 분석] → [자동 인쇄]
+     ↓              ↓                ↓              ↓
+  POS 입력      ws://8765        Claude API    ESC/POS 프린터
+```
+
+### 관련 파일
+- `backend/templates/pmr.html` - 프론트엔드 (토글, WebSocket 클라이언트)
+- `backend/pmr_api.py` - API 엔드포인트 (`/pmr/api/paai/print`)
+- `backend/paai_printer.py` - ESC/POS 프린터 모듈
+
+---
+
+## 문제 1: 자동인쇄 토글이 작동하지 않음
+
+### 증상
+- "자동인쇄" 버튼 클릭해도 ON/OFF 전환 안 됨
+- 콘솔에 `showToast is not defined` 에러
+
+### 원인
+JavaScript 함수가 전역 스코프에 등록되지 않음
+
+### 해결
+모든 변수/함수를 `window.` 접두사로 전역 등록:
+
+```javascript
+// ❌ 잘못된 방식
+var autoPrintEnabled = true;
+function showToast() { ... }
+
+// ✅ 올바른 방식
+window.autoPrintEnabled = true;
+window.showToast = function() { ... };
+```
+
+### 체크리스트
+- [ ] `window.autoPrintEnabled` - boolean
+- [ ] `window.showToast` - function
+- [ ] `window.updateAutoPrintIndicator` - function
+- [ ] `window.printPaaiResult` - function
+
+브라우저 콘솔에서 확인:
+```javascript
+typeof window.showToast  // "function" 이어야 함
+```
+
+---
+
+## 문제 2: 새로고침 후 변경사항 미반영
+
+### 증상
+- 코드 수정 후 새로고침해도 이전 버전 실행
+- `showToast is not defined` 에러 지속
+
+### 원인
+1. Flask 서버가 템플릿을 캐시함 (개발 모드 아닐 때)
+2. 브라우저 캐시
+
+### 해결
+
+**Flask 재시작:**
+```powershell
+# app.py 프로세스 종료 후 재시작
+Get-Process -Name python | Where-Object {
+    (Get-WmiObject Win32_Process -Filter "ProcessId=$($_.Id)").CommandLine -match "app.py"
+} | Stop-Process -Force
+
+cd C:\Users\청춘약국\source\pharmacy-pos-qr-system\backend
+python app.py
+```
+
+**브라우저 강제 새로고침:**
+- `Ctrl + F5` (캐시 무시)
+- 또는 URL에 쿼리 파라미터 추가: `?v=2`
+
+---
+
+## 문제 3: 프린터 출력 안 됨
+
+### 증상
+- 콘솔에 `[AutoPrint] 인쇄 요청:` 로그는 보임
+- 프린터에서 출력 없음
+
+### 원인 및 해결
+
+**1. 프린터 연결 확인:**
+```powershell
+# USB 프린터 확인
+Get-WmiObject Win32_Printer | Select Name, PortName
+```
+
+**2. API 응답 확인:**
+```powershell
+# 직접 API 테스트
+curl -X POST http://localhost:7001/pmr/api/paai/print `
+  -H "Content-Type: application/json" `
+  -d '{"pre_serial":"test","patient_name":"테스트","result":{"analysis":{}}}'
+```
+
+**3. paai_printer.py 단독 테스트:**
+```powershell
+cd C:\Users\청춘약국\source\pharmacy-pos-qr-system\backend
+python paai_printer_cli.py test
+```
+
+---
+
+## 문제 4: 한글 깨짐
+
+### 증상
+- 프린터 출력에서 한글이 `????` 또는 깨진 문자로 출력
+
+### 원인
+프린터가 EUC-KR 인코딩 필요 (CP949)
+
+### 해결
+`paai_printer.py`에서 EUC-KR 인코딩 사용:
+
+```python
+def encode_korean(text):
+    """한글을 EUC-KR로 인코딩"""
+    try:
+        return text.encode('euc-kr', errors='replace')
+    except:
+        return text.encode('ascii', errors='replace')
+```
+
+ESC/POS 명령어:
+```python
+# 한글 모드 설정 (Code Page 949)
+printer.write(b'\x1b\x40')      # 초기화
+printer.write(b'\x1c\x43\x01')  # 한글 모드
+```
+
+---
+
+## 문제 5: WebSocket 연결 실패
+
+### 증상
+- "자동감지 OFF" 표시
+- 콘솔에 `WebSocket connection failed` 에러
+
+### 원인
+처방감지 서버 (`trigger_server.py`)가 실행되지 않음
+
+### 해결
+```powershell
+cd C:\Users\청춘약국\source\pharmacy-pos-qr-system\backend
+python trigger_server.py
+```
+
+정상 연결 시 콘솔 로그:
+```
+[Trigger] 연결 시도: ws://localhost:8765
+[Trigger] ✅ 연결됨
+```
+
+---
+
+## 디버깅 체크리스트
+
+### 브라우저 콘솔 확인
+```javascript
+// 전역 함수 확인
+typeof window.autoPrintEnabled    // boolean
+typeof window.showToast           // "function"
+typeof window.printPaaiResult     // "function"
+
+// 수동 인쇄 테스트
+window.printPaaiResult('test123', '테스트환자', {
+  analysis: { prescription_insight: '테스트' }
+});
+```
+
+### 서버 로그 확인
+```powershell
+# Flask 로그에서 인쇄 API 호출 확인
+# POST /pmr/api/paai/print 200
+```
+
+### localStorage 확인
+```javascript
+localStorage.getItem('pmr_auto_print')  // "true" 또는 "false"
+```
+
+---
+
+## 관련 커밋 히스토리
+
+| 커밋 | 설명 |
+|------|------|
+| `b4e4a44` | 자동인쇄 전역 변수/함수 완전 수정 |
+| `e33204f` | printPaaiResult 전역 함수로 변경 |
+| `0bbc8a5` | showToast 함수 추가 |
+| `0b17139` | PAAI 자동인쇄 기능 완성 (EUC-KR) |
+
+---
+
+## 전체 플로우 요약
+
+```
+1. 처방 접수 (POS)
+   ↓
+2. trigger_server.py가 감지 → WebSocket 브로드캐스트
+   ↓
+3. pmr.html이 WebSocket 메시지 수신
+   ↓
+4. 자동감지 ON이면 → PAAI 분석 요청 (/pmr/api/paai/analyze)
+   ↓
+5. 분석 완료 → analysis_completed 이벤트
+   ↓
+6. 자동인쇄 ON이면 → printPaaiResult() 호출
+   ↓
+7. /pmr/api/paai/print API → paai_printer.py
+   ↓
+8. ESC/POS 명령어로 영수증 프린터 출력 🖨️
+```
+
+---
+
+*문서 작성일: 2026-03-05*
+*작성자: 용림 🐉*