오류 처리의 목표는 예외를 삼키는 것이 아니라 어느 계층에서 발생했는지 판단하는 것입니다. 계층을 명확히 판단하면 문제 해결이 훨씬 빨라집니다. 연결 문제 때문에 템플릿을 고치지 말고, 명령어 미지원은 재시도로 해결하려 하지 말며, 용지 없음은 BLE MTU 문제가 아닙니다.

오류 분류

유형	흔한 원인	처리 방향
연결 오류	블루투스 권한이 꺼져 있음, 디바이스 미페어링, service/characteristic UUID 불일치, 네트워크 도달 불가, 연결 타임아웃.	연결 흐름으로 돌아가 권한, 디바이스 선택, UUID, 주소, 플랫폼 상태를 점검합니다.
쓰기 오류	연결 중단, 플랫폼 write API 실패 반환, 과도한 분할 크기, write with/without response 모드 불일치.	분할을 줄이고, 쓰기 모드를 확인하며, 몇 번째 chunk에서 실패했는지 기록합니다.
흐름 제어 오류	BLE credit 미도착, MTU/credit notify 형식 불일치, credit 타임아웃, bypass-write 오용.	lane-credit 또는 signal-credit 필요 여부를 확인하고, notify가 구독되어 flow control로 라우팅되는지 점검합니다.
질의 오류	pending query 타임아웃, matcher 불일치, receive source 미시작, 디바이스가 해당 질의를 지원하지 않음.	질의 명령어, timeout, notify/read 출처, dialect parser를 점검합니다.
명령어 오류	디바이스가 현재 ESC, TSPL 또는 CPCL 명령을 지원하지 않거나 잘못된 dialect를 사용함.	디바이스가 지원하는 명령어 집합으로 전환하고, 디바이스가 지원하지 않는 확장 명령을 줄입니다.
콘텐츠 오류	용지 폭 불일치, 이미지 과도한 폭, 인코딩 비호환, 라벨 좌표가 페이지를 벗어남, payload 과대.	템플릿과 이미지 처리 계층으로 돌아가 폭, 인코딩, 좌표, 최종 바이트 크기를 확인합니다.

초보자 문제 해결 순서

다음 순서로 점검하면 보통 잘못된 계층 안에서 맴도는 일을 피할 수 있습니다.

1. 먼저 연결 확인: 디바이스가 실제로 connected인지, 권한, UUID, 주소, 시스템 블루투스 상태가 올바른지 확인합니다.
2. 다음으로 최소 콘텐츠 전송: 짧은 텍스트나 간단한 라벨 하나만 인쇄해 기본 쓰기가 가능한지 확인합니다.
3. 그 다음 분할과 BLE 확인: 작은 콘텐츠는 정상이고 큰 콘텐츠가 실패하면 chunk size, MTU, write mode, credit을 확인합니다.
4. 그 다음 상태 질의 확인: 인쇄는 되지만 상태를 읽지 못하면 receive source, notify/read, pending query timeout, parser를 확인합니다.
5. 마지막으로 템플릿 콘텐츠 확인: 특정 템플릿만 실패하면 용지 폭, 이미지 폭, 인코딩, 바코드/QR 코드 파라미터, 명령어 지원을 확인합니다.

로그 기록 방법

로그는 단계를 찾을 수 있어야 하지만 민감한 인쇄 내용을 기록해서는 안 됩니다. 다음을 권장합니다.

기록 가능	피해야 할 기록
SDK 언어와 버전, 플랫폼, 전송 방식.	영수증 본문, 수취인, 휴대폰 번호, 주소, 주문 상세 등 민감한 내용.
디바이스 이름 또는 비식별화된 디바이스 ID, service/characteristic UUID.	전체 비즈니스 payload 또는 비식별화되지 않은 사용자 데이터.
명령어 계열, 총 바이트 수, chunk size, chunk index, write mode.	인쇄 내용을 복원할 수 있는 raw bytes.
MTU, payload MTU, credit 전략, credit timeout, fallback mode.	프로덕션에서 장기간 켜 둔 지나치게 상세한 바이너리 dump.
질의 유형, timeout, raw response 수신 여부, parser 결과 유형.	고객 정보를 포함하는 parser 텍스트 필드.

디버깅 단계에서 raw bytes를 봐야 한다면 우선 길이, 앞부분 몇 바이트, hash 또는 비식별화한 hex 조각만 기록하고, 장기 프로덕션 로그에 들어가지 않도록 하세요.

증상 대조표

증상	가능한 계층	다음 점검
디바이스를 스캔하지 못함	연결	권한, 블루투스 스위치, 디바이스 광고 여부, 플랫폼 discovery filter.
스캔은 되지만 연결 실패	연결	주소/디바이스 객체가 만료되었는지, service UUID가 맞는지, 연결 타임아웃이 너무 짧은지.
연결 성공 후 전혀 인쇄하지 않음	쓰기 / 명령어	write characteristic이 올바른지, 최소 텍스트가 인쇄되는지, 명령어 계열을 지원하는지.
절반만 인쇄하거나 큰 이미지 실패	쓰기 / 흐름 제어 / 콘텐츠	chunk size, BLE MTU, credit, 이미지 폭, payload 총 크기.
credit 활성화 후 멈춤	흐름 제어	credit notify 구독 성공 여부, 알림이 lane-credit 또는 signal-credit로 들어가는지, timeout이 적절한지.
bypass-write는 인쇄되지만 fail 모드는 타임아웃	흐름 제어	디바이스가 credit을 필요로 하지 않거나, credit 특성값/알림 형식 설정이 잘못되었을 수 있습니다.
상태 질의가 계속 타임아웃	질의 / 수신	receive source 시작 여부, notify/read 데이터 존재 여부, matcher와 질의 명령어 일치 여부.
response를 받았지만 결과가 unknown	질의 / parser	raw bytes는 도착했습니다. dialect, 질의 유형, 펌웨어 응답 형식을 확인합니다.
영수증 글자가 깨짐	콘텐츠 / 명령어	문자 인코딩, 코드 페이지, 글꼴, 디바이스 언어 설정.
용지가 없는데 계속 쓰기	상태 / 제품 로직	디바이스가 용지 없음 상태를 지원하는지, 애플리케이션이 쓰기 전/중 상태를 읽고 처리하는지.

문제 해결 시 “어느 계층에서 발생했는지”에 대한 원시 오류 정보를 가능한 한 보존한 뒤, “프린터에 용지가 있는지 확인하세요” 또는 “프린터를 다시 연결하세요”처럼 사용자가 이해할 수 있는 안내로 변환하세요.