문제해결

문제가 발생하면 먼저 이 페이지를 확인하세요. 해결되지 않으면 앱 안의 도움말 (?) → 버그 신고 또는 운영팀(hanalabs@hanapf.kr 또는 안내받은 카카오톡 채널)으로 문의해 주세요.

시작 / 설치

프로그램이 시작되지 않습니다

증상 A: SmartScreen 경고

“Windows에서 PC를 보호했습니다. Microsoft Defender SmartScreen이 인식할 수 없는 앱의 시작을 차단했습니다.”

원인: 코드서명 인증서(EV)의 평판이 충분히 쌓이기 전 발생하는 정상 현상.

해결:

추가 정보 클릭.
실행 버튼 클릭.

이 절차는 첫 설치 시 1회만 필요합니다. Hanaro는 SSL.com EV 코드서명을 사용하며, 사용자 수 누적에 따라 평판이 쌓이면 경고가 자동으로 사라집니다.

증상 B: “.NET Runtime을 찾을 수 없음”

원인: .NET 8 Runtime 누락 (포터블 zip 사용 시).

해결: .NET 8 Runtime 다운로드 → “Run desktop apps” 항목.

정식 설치 파일(Hanaro-Setup-x.y.z.exe)은 .NET을 자동 포함합니다. 포터블 zip만 별도 설치 필요.

증상 C: 즉시 종료 / 무반응

해결:

로그 확인 — %APPDATA%\Hanaro\logs\hanaro-<날짜>.log
Sentry에 자동 보고됨 (DSN 설정 시).
임시 우회: %APPDATA%\Hanaro\ 폴더의 hanaro.db를 다른 이름(hanaro.db.bak)으로 변경 → DB가 새로 생성됩니다 (데이터 손실 주의).
운영팀(hanalabs@hanapf.kr 또는 안내받은 카카오톡 채널)으로 로그 첨부해 문의.

마켓 연결

마켓 연결이 안 됩니다

증상 A: “AUTH_EXPIRED” 또는 “401 Unauthorized”

원인: 자격증명 만료 (특히 OAuth refresh token 만료 — 카페24).

해결:

설정 → 마켓 계정 → 해당 마켓 → 편집.
자격증명 재입력 (카페24는 OAuth 재인증).
연결 테스트 → 성공 확인.

증상 B: “RATE_LIMIT” 또는 “429 Too Many Requests”

원인: 마켓 API 분당 호출 제한 초과.

해결:

Hanaro는 자동으로 백오프(Polly 정책) 후 재시도합니다. 잠시 기다리세요.
큰 동기화 직후 자주 발생 — 설정 → 동기화 → 호출 간격 늘리기 (기본 1초 → 2초).

증상 C: “RiskLevel 동의 필요”

원인: 세션 자동화(WebView2)를 사용하는 작업인데 사용자가 사전에 동의하지 않음.

해결:

다이얼로그가 떴을 때 위험 인지 후 동의를 클릭.
동의하지 않으려면 해당 작업은 마켓 웹사이트에서 직접 처리.

자세한 RiskLevel 설명은 FAQ — 공식 API와 세션 자동화의 차이 참조.

발송처리

송장 충돌 — 어떤 옵션을 선택해야 하나요?

상황	권장
Hanaro/엑셀 송장이 정답 (대부분)	셀러 기준 덮어쓰기
마켓에서 직접 입력한 값이 정답	마켓 기준 교정
어느 쪽이 맞는지 모르겠음	취소 → 출하 직원에게 확인 후 재처리

자세한 흐름은 발송처리 — 충돌 처리 참조.

“INVALID_TRACKING” 오류

원인: 송장번호 형식이 택배사 규칙에 맞지 않음.

확인사항:

CJ대한통운: 10~12자리 숫자
한진: 12자리 숫자
로젠: 11자리 숫자
우체국: xxxx-xxxx-xxxx 등기번호 또는 13자리 숫자
롯데: 12자리 숫자

해결:

엑셀 임포트 시 송장번호 컬럼이 텍스트가 아닌 숫자로 인식되어 앞 0이 사라진 경우 → 엑셀에서 컬럼 형식을 “텍스트”로 변경 후 재출력.

엑셀 임포트가 매칭되지 않습니다 (빨강 행 다수)

원인:

주문번호 형식 차이 (prefix 등).
다른 마켓의 주문 (Hanaro에 미등록 마켓).
마켓 동기화가 안 된 상태.

해결:

자동 정규화 옵션 켜기 (기본 ON).
임포트 전 주문 화면(F2)에서 [마켓에서 새 주문 받기] 실행.
한 번에 한 마켓씩 임포트해서 매칭 확인.

자세한 내용은 송장 임포트 — 매칭 실패 처리 참조.

데이터

데이터베이스가 손상된 것 같습니다

증상: “SQLite database is malformed”, 시작 시 무한 로딩.

원인: 클라우드 동기화 폴더에 DB가 있거나, 강제 종료 중 DB 쓰기.

해결:

Hanaro 종료.
%APPDATA%\Hanaro\hanaro.db 백업.

SQLite 복구 시도:

sqlite3 hanaro.db ".recover" | sqlite3 hanaro-recovered.db

복구가 어려우면 마지막 정상 백업 복원.
마지막 수단: 파일 삭제 후 재시작 (모든 로컬 데이터 손실 — 마켓에서 재동기화).

예방: 클라우드 동기화 폴더 사용 금지. 정기 수동 백업.

마이그레이션이 깨졌을 때 복구

EF Core 마이그레이션 파일(src/Hanaro.Infrastructure/Persistence/Migrations/)이 손상됐거나, dotnet ef migrations add가 기존 테이블을 다시 만들려는 conflicting 마이그레이션을 생성한 경우.

증상

Migrate() 시 SQLite Error 1: 'table sites already exists' 등.
dotnet ef migrations add Foo가 모든 기존 테이블의 CreateTable을 포함한 거대한 마이그레이션을 생성.
신규 테이블/컬럼이 마이그레이션에 빠지고 EnsureCreated로만 만들어짐.

원인

HanaroDbContextModelSnapshot.cs가 placeholder(빈) 상태이거나, 0001 Initial 이후 도메인이 변경됐는데 후속 마이그레이션이 없는 경우. EF Core 도구는 스냅샷을 baseline으로 모델 diff를 계산한다.

해결 — 정식 재생성

현재 DB 백업: %APPDATA%\Hanaro\hanaro.db → hanaro.db.bak.
재생성 스크립트 실행:
```
pwsh ./scripts/regen-migrations.ps1
```
- 기존 3 파일(Initial.cs, Initial.Designer.cs, HanaroDbContextModelSnapshot.cs)이 claudedocs/migrations-backup-<timestamp>/로 백업됨.
- dotnet ef migrations add Initial로 정식 재생성.
- 빌드 + 단위테스트로 자동 검증.
PR 리뷰: git diff src/Hanaro.Infrastructure/Persistence/Migrations/로 신/구 마이그레이션 SQL 차이점 검토.
사용자 데이터가 있는 DB: 정식 마이그레이션 SQL을 백업 DB와 호환되는지 확인 후 적용. 컬럼 타입/제약조건 변경 시 별도 데이터 마이그레이션 필요.

본 절차는 개발자 환경에서만 수행. 사용자 PC는 자동으로 이전 버전 → 새 버전 마이그레이션이 MigrateAsync로 적용된다.

Migrate vs EnsureCreated 비상 전환

증상: 시작 시 MigrateAsync 실패가 반복되어 앱이 정상 시작되지 않을 때.

# 자동 마이그레이션 끄고 EnsureCreated 폴백 모드로 시작.
$env:HANARO_DB_AUTO_MIGRATE = "false"
.\Hanaro.exe

→ 그 후 마이그레이션 파일을 수정/재생성하고 다시 HANARO_DB_AUTO_MIGRATE 환경변수를 제거.

마켓 자격증명을 백업했는데 다른 PC에서 안 됩니다

원인: DPAPI는 사용자/머신에 묶여 있어 이식 불가능합니다 (의도된 보안 설계).

해결: 새 PC에서 마켓 계정을 재등록하세요. 주문/송장 데이터는 hanaro.db로 그대로 옮겨집니다.

자세한 내용은 FAQ — 데이터를 다른 PC로 옮길 수 있나요 참조.

성능

동기화가 매우 느립니다

원인: 마켓 API 응답 지연 (특히 쿠팡 — 분당 60회 제한).

해결:

설정 → 동기화 → 기간 → 짧게 (기본 30일 → 7일).
설정 → 동기화 → 병렬도 → 높이기 (기본 1마켓 → 3마켓).
처음 동기화는 오래 걸려도 정상. 이후는 증분 동기화로 빨라집니다.

그리드가 느려요

원인: 표시 행 수가 너무 많음.

해결:

필터로 행 수 줄이기 (예: 최근 7일).
페이지네이션 활성화 — 설정 → UI → 페이지당 행 수 조정.

로그 / 진단

로그 파일 위치

%APPDATA%\Hanaro\logs\
  hanaro-2026-05-09.log
  hanaro-2026-05-08.log
  ...

매일 새 파일 생성.
7일 후 자동 삭제 (롤링).
로그 레벨: Information 이상.
설정 → 진단 → 로그 폴더 열기로 빠르게 접근.

로그 레벨 변경

상세 로그가 필요하면:

%APPDATA%\Hanaro\appsettings.user.json

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug"
    }
  }
}

Debug 레벨은 로그 양이 매우 많습니다. 문제 진단 후 다시 Information으로 되돌리세요.

Sentry 비활성화

HANARO_SENTRY_DSN 환경변수를 빈 값으로 설정 또는 삭제 → Hanaro 재시작.

또는 설정 → 진단 → 오류 보고 토글 OFF.

재현 절차 + 이슈 등록

이슈 등록 시 다음 정보를 포함해주세요:

## 환경
- Hanaro 버전: (설정 → 정보 — 예: 1.2.3)
- Windows 버전: (예: Windows 11 23H2)
- 마켓: (예: 스마트스토어, 쿠팡)
- 발생 시각: (예: 2026-05-09 14:30 KST)

## 재현 절차
1. ...
2. ...
3. 오류 발생

## 기대 동작
...

## 실제 동작
...

## 로그
(`%APPDATA%\Hanaro\logs\hanaro-<날짜>.log` 첨부 — 개인정보 제거 후)

문의하기 → hanalabs@hanapf.kr

그래도 해결되지 않으면

앱 안의 도움말 (?) → 버그 신고
이메일: hanalabs@hanapf.kr
안내받은 카카오톡 채널