docs: 이미지 교체 바코드 전달 오류 트러블슈팅 문서 추가

docs/troubleshooting/2026-03-02_이미지교체_바코드전달오류.md

@@ -0,0 +1,109 @@
+# 트러블슈팅: 이미지 교체 시 바코드 전달 오류
+
+**날짜:** 2026-03-02  
+**해결 상태:** ✅ 해결됨
+
+---
+
+## 증상
+
+제품 이미지 관리 페이지에서 "교체" 버튼을 눌러 이미지 URL을 입력하면:
+- 기존 제품의 이미지가 교체되지 않음
+- 대신 새로운 레코드가 생성됨
+- 새 레코드의 barcode, product_name이 `null`로 저장됨
+
+## 원인
+
+### 1차 원인: JavaScript 템플릿 리터럴에서 escapeHtml 문제
+
+```javascript
+// 문제 코드
+onclick="openReplaceModal('${item.barcode}', '${escapeHtml(item.product_name)}')"
+```
+
+제품명에 특수문자(따옴표 등)가 포함되면 `escapeHtml` 함수가 문자열을 변환하면서 onclick 속성이 깨짐.
+
+### 2차 원인: 전역 변수 참조 문제
+
+`replaceTargetBarcode` 변수가 모달 제출 시 `undefined` 또는 `"null"` 문자열로 전달됨.
+
+---
+
+## 해결 방법
+
+### 1. data 속성으로 바코드 전달 (HTML)
+
+```javascript
+// 수정 후
+<button class="btn btn-primary btn-sm" 
+        data-barcode="${item.barcode}" 
+        data-name="${item.product_name || ''}" 
+        onclick="openReplaceModal(this.dataset.barcode, this.dataset.name)">교체</button>
+```
+
+`data-*` 속성을 사용하여 값을 안전하게 저장하고, `this.dataset`으로 접근.
+
+### 2. 바코드 유효성 검증 추가 (JavaScript)
+
+```javascript
+function openReplaceModal(barcode, productName) {
+    console.log('openReplaceModal called with:', barcode, productName);
+    
+    // 바코드 검증
+    if (!barcode || barcode === 'null' || barcode === 'undefined') {
+        showToast('바코드 정보가 없습니다', 'error');
+        return;
+    }
+    
+    replaceTargetBarcode = barcode;
+    // ...
+}
+
+async function submitReplace() {
+    // 바코드 검증
+    if (!replaceTargetBarcode || replaceTargetBarcode === 'null' || replaceTargetBarcode === 'undefined') {
+        showToast('바코드 정보가 없습니다. 다시 시도해주세요.', 'error');
+        return;
+    }
+    
+    const barcode = replaceTargetBarcode;  // 로컬 변수에 복사
+    // ...
+}
+```
+
+### 3. 백엔드 UPDATE 쿼리 수정 (Python)
+
+```python
+# 기존 레코드 확인 후 이미지만 업데이트 (product_name, drug_code 유지)
+cursor.execute("SELECT product_name, drug_code FROM product_images WHERE barcode = ?", (barcode,))
+existing = cursor.fetchone()
+
+if existing:
+    # 기존 레코드 있으면 이미지만 업데이트
+    cursor.execute("""
+        UPDATE product_images 
+        SET image_base64 = ?, thumbnail_base64 = ?, image_url = ?, 
+            status = 'manual', error_message = NULL, updated_at = datetime('now')
+        WHERE barcode = ?
+    """, (image_base64, thumbnail_base64, image_url, barcode))
+```
+
+---
+
+## 관련 커밋
+
+- `4a06e60` - feat: 이미지 교체 기능 추가
+- `4a3ec38` - fix: 이미지 교체 시 바코드 전달 오류 수정
+- `65754f5` - fix: 이미지 교체 시 바코드 검증 강화
+
+---
+
+## 교훈
+
+1. **onclick에 동적 값 전달 시 주의**: 템플릿 리터럴 + escapeHtml 조합은 예상치 못한 오류 발생 가능. `data-*` 속성 사용 권장.
+
+2. **전역 변수 의존 최소화**: 모달 등 비동기 흐름에서 전역 변수 사용 시 값이 바뀔 수 있음. 로컬 변수에 복사 후 사용.
+
+3. **입력 검증은 프론트/백 양쪽에서**: null, undefined, "null" 문자열 등 예외 케이스 모두 검증.
+
+4. **디버깅 로그 활용**: `console.log`로 실제 전달되는 값 확인하면 원인 파악이 빠름.