문제해결

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

원인: 하나로가 아직 코드서명 전이라 Windows가 모르는 앱으로 보고 띄우는 정상 현상이에요.

해결:

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

이 절차는 첫 설치 시 1회만 필요해요. 아직 코드서명 전이라 SmartScreen 경고가 떠요. 서명이 붙으면 사라져요.

원인: 받은 파일이 손상됐거나, 포터블 zip을 압축 해제하지 않고 zip 안에서 바로 실행했거나, 백신이 일부 파일을 격리한 경우예요.

해결:

1. 포터블 zip이면 폴더 전체를 압축 해제한 뒤 그 폴더에서 실행하세요.
2. 그래도 같으면 설치 파일(Hanaro-stable-Setup.exe) 또는 zip을 다시 받아 주세요.
3. 백신 격리 기록이 있으면 하나로 폴더를 예외로 넣어 주세요.

설치 파일과 포터블 zip은 실행 구성 요소를 함께 담아 배포해요(.NET 8 별도 설치 불필요).

해결:

1. 로그 확인 — %APPDATA%\Hanaro\logs\hanaro-<날짜>.log
2. 오류 보고가 켜져 있으면 오류가 운영팀에 자동으로 전달돼요.
3. 임시 우회: %APPDATA%\Hanaro\ 폴더의 hanaro.db를 다른 이름(hanaro.db.bak)으로 변경 → DB가 새로 생성돼요 (데이터 손실 주의).
4. 운영팀(hanalabs@hanapf.kr 또는 안내받은 카카오톡 채널)으로 로그 첨부해 문의.

원인: Windows는 아이콘을 따로 저장해 두고(아이콘 캐시) 다시 써요. 업데이트로 실행 파일의 아이콘이 바뀌어도 파일 위치가 같아서, Windows가 저장해 둔 옛 아이콘을 계속 보여 줄 수 있어요. 창 제목줄의 아이콘은 바로 바뀌는데 바탕화면·시작 메뉴 바로가기와 작업 표시줄만 옛 아이콘인 경우가 이거예요. 앱 동작에는 영향이 없어요.

자동 처리: (0.3.5 버전부터) 새 버전을 처음 켜고 몇 초 뒤 하나로가 Windows에 아이콘을 다시 읽으라고 한 번 요청해요. 이때 바탕화면 아이콘이 잠깐 깜빡일 수 있어요(버전마다 한 번).

그래도 옛 아이콘이면 아래를 순서대로 해 보세요.

1. 작업 표시줄의 하나로 아이콘을 오른쪽 클릭 → 작업 표시줄에서 제거 → 시작 메뉴에서 하나로를 찾아 다시 작업 표시줄에 고정.
2. PC를 다시 시작해요.
3. 그래도 그대로면 아이콘 캐시를 새로 만들어요. 🔴 이 방법은 탐색기를 잠시 끄므로 열어 둔 탐색기 창이 모두 닫히고 바탕화면·작업 표시줄이 잠깐 사라졌다가 돌아와요. 하던 작업을 저장한 뒤 하세요.
   1. 작업 관리자(Ctrl+Shift+Esc) → Windows 탐색기를 오른쪽 클릭 → 작업 끝내기.
   2. 작업 관리자 메뉴의 새 작업 실행 → cmd 입력 → 확인.
   3. 열린 창에 아래 두 줄을 차례로 붙여 넣고 Enter.

      del /a /q "%LOCALAPPDATA%\IconCache.db"
      del /a /q "%LOCALAPPDATA%\Microsoft\Windows\Explorer\iconcache_*.db"
      

   4. 다시 새 작업 실행 → explorer 입력 → 확인. 바탕화면과 작업 표시줄이 돌아와요.

하나로는 아이콘 캐시 파일을 스스로 지우지 않아요 — 탐색기를 강제로 껐다 켜야 해서, 작업 중인 화면이 갑자기 사라질 수 있기 때문이에요.

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

해결:

1. 설정 → 마켓 계정(F12) → 해당 마켓 카드의 [재인증].
2. 카드 아래에 펼쳐지는 폼에 자격증명을 다시 입력해요 (카페24는 [카페24 연결하기] 로 OAuth 재인증).
3. [저장] — 저장할 때 연결을 확인하고, 실패하면 사유가 표시돼요.

원인: 하나로 0.4.1부터 카페24에 요청하는 권한이 2개에서 7개로 늘었어요. 이전에 연결한 계정은 옛 권한만 갖고 있어요.

해결: 설정 → 마켓 계정 → 그 카페24 계정의 [재인증] → 카페24 연결하기 → 카페24 화면에서 [허용]. 계정은 지우지 마세요. 주문 가져오기·송장 등록은 다시 연결하지 않아도 그대로 되고, 새 권한이 필요한 기능([쇼핑몰 추가]의 쇼핑몰 목록 등)만 멈춰요. 본인 카페24 개발자센터 앱(Client ID)으로 연결했다면 [재인증] 전에 그 앱에서 권한 7개를 먼저 모두 켜세요. 권한 목록

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

해결:

• Hanaro는 간격을 두고 자동으로 다시 시도해요. 잠시 기다리세요.
• 큰 동기화 직후 자주 발생해요. 잠시 뒤 [마켓 동기화] 를 다시 눌러 주세요. (호출 간격을 셀러가 조정하는 설정은 제공하지 않아요 — 재시도 간격은 하나로가 자동으로 늘려요.)

원인: 저장된 ESM 아이디·비밀번호가 맞지 않거나, 2단계 인증·보안문자를 끝내지 못했어요.

해결:

1. 같은 아이디·비밀번호로 자동 로그인이 두 번 실패하면, 계정이 잠기지 않도록 하나로가 자동 로그인을 멈춰요. 멈춘 원인에 따라 안내가 달라요 — “같은 아이디·비밀번호로 … 두 번 성공하지 못해”면 아이디·비밀번호를, “보안문자·2단계 인증을 요구했거나 로그인 화면이 응답하지 않아”면 창에서 인증을 마치는 것을 확인하세요. 푸는 방법은 아래 2번으로 같아요.
2. 설정 → 마켓 계정(F12) → ESM 카드의 [재인증] → 아이디·비밀번호를 확인하고 [저장]. 저장할 때의 로그인 확인에 성공하면 멈췄던 자동 로그인이 다시 켜져요(비밀번호를 바꿔 저장하거나 하나로를 다시 켜도 다시 시도해요). 로그인 창은 통과했는데 주문 화면에 들어가지 못하는 경우도 실패로 세어 두 번에서 멈춰요.
3. 2단계 인증이 나오면 로그인 창이 앞으로 떠요. 창을 닫지 말고 인증을 마쳐 주세요. 단, 자동으로 도는 수집(주기 수집)·접수 직전 배송지 확인 중에는 창을 띄우지 않고 “ESM 로그인 확인(2단계 인증·보안문자)이 필요해 주문을 받지 못했습니다 — …”로 끝나요. 이때 [마켓 동기화]를 누르면 창이 열려요(안내 문구 속 버튼 이름과 앱 화면의 실제 버튼 이름은 [마켓 동기화]예요). 로그인을 기다리는 시간은 최대 5분이에요. 자동 수집이 비밀번호를 넣기 전에 보안문자 때문에 멈춘 것은 위 “두 번”에 세지 않아요.

“ESM 판매자 정보가 지난번과 달라 주문을 저장하지 않았습니다”가 보이면 이 ESM 카드에 다른 계정의 로그인이 섞였을 수 있어요. 주문은 저장하지 않았어요. ESM 카드의 [재인증] → [저장]으로 계정을 확인하면 다시 받아 와요.

“다른 ESM 계정의 로그인으로 보여 주문을 받지 않았고 이 계정의 자동 로그인을 멈췄습니다”가 보이면 ESM 계정이 여러 개일 때 다른 계정의 로그인이 섞인 경우예요. 그 계정의 주문은 저장하지 않았고, 같은 일이 되풀이되지 않도록 이 카드의 자동 로그인을 멈춰요. 설정 → 마켓 계정 → 이 ESM 카드의 [재인증] → [저장]을 하면 다시 받아 와요(저장할 때 로그인을 확인해요). ESM 카드의 셀러센터 로그인 칸에서는 아이디를 바꿀 수 없어요(비밀번호와 로그인 방식만). 다른 ESM 계정은 [+ 마켓 추가]로 따로 등록하세요.

하나로는 ESM 주문 상태 중 새 주문(결제 완료)·발주확인(ESM 발송 대기)·배송중·배송완료·구매확정(송금완료 포함)·취소를 구분해요. 하나로가 아직 모르는 ESM 상태는 하나로 업데이트 전까지 알수없음으로 보여요. 주문 자체는 정상으로 받아 와요. 정확한 상태는 ESM PLUS에서 확인해 주세요. 환불 승인일이 있는 주문은 취소요청으로 보여요(반품·교환은 아직 따로 구분하지 못해요). 취소 처리일만 있으면 ESM 상태 그대로 두고 클레임 확인 필요로 표시해요. ESM의 취소 표시(CN)는 옥션 진행 중 주문에도 붙어 판단에 쓰지 않아요. 이런 주문과 환불 승인일 없이 미수령·반품·교환 같은 클레임 표시만 있는 주문 중 발송 전 주문은 [택배 자동접수] 확인창에서 클레임 확인 필요 — ESM PLUS에서 확인으로 체크가 풀려 있어요.

[선택 주문 송장 등록]에서 ESM 주문은 로젠 송장만 자동으로 등록해요. [상태] 열의 문구로 원인을 확인하세요.

• 자동 등록 미지원 — ESM PLUS에서 발송처리 — 로젠이 아닌 택배사 송장이에요. ESM PLUS에서 직접 발송처리해 주세요.
• 등록 실패: ESM에서 이미 발송처리된 주문이라 보내지 않았습니다… — ESM에서 먼저 발송처리된 주문이에요. 송장번호를 바꾸려면 ESM PLUS에서 직접 수정하세요.
• 등록 실패: ESM에서 취소·환불된(또는 취소 중인) 주문…, …클레임 표시가 있거나 상태를 알 수 없는 주문… — 보내기 직전에 ESM에서 다시 확인한 결과예요. ESM PLUS에서 주문을 확인해 주세요.
• 등록 실패: ESM에서 아직 주문확인되지 않은 주문… — 확인 창에서 발주확인(주문확인)을 함께 진행해야 해요. 체크를 다시 켜고 [발주확인 후 송장 등록]으로 진행하세요.
• 등록 실패: ESM 처리 결과를 확인하지 못했습니다… — ESM 응답을 받지 못했거나, 일부만 실패했는데 어느 주문인지 가를 수 없었어요(그 묶음의 주문 전부에 붙어요). 처리됐을 수 있으니 요약 줄의 “다시 시도해 주세요”와 관계없이 ESM PLUS에서 먼저 확인하고, 처리되지 않았을 때만 다시 등록하세요.
• 등록 실패: …로그인… — ESM 로그인이 끊겼어요. 위 ESM 로그인이 계속 실패합니다를 참고하세요.

원인: 11번가는 오픈API 센터에 등록된 IP에서 온 요청만 받아요. 이 PC의 IP를 등록하지 않았거나, 공유기 재시작·통신사 사정 등으로 IP가 바뀌면 11번가가 요청을 거절해요. API 키가 틀려도 같은 안내가 뜰 수 있어요. 이때 하나로는 11번가의 원문(“인증된 IP가 아닙니다” 등)과 함께 다음 안내를 보여 드려요.

11번가 셀러오피스 > 오픈API 설정에서 API 키와 이 PC의 IP가 등록돼 있는지 확인해 주세요. IP가 바뀌면(공유기 재시작 등) 다시 등록해야 해요. (이 PC의 IP: 203.0.113.10)

해결:

1. 안내 끝의 “(이 PC의 IP: …)” 값을 확인해요(브라우저에서 “내 IP 주소”를 검색해도 같은 값이에요).
2. 11번가 오픈API 센터 → [API 관리] → 접속권한에서 IP 직접 입력 [사용]을 고르고, IP 칸에 그 값을 넣은 뒤 [수정하기]를 눌러요. PC가 여러 대면 한 칸에 ;로 이어서 넣을 수 있어요(예: 203.0.113.10;203.0.113.20).
3. 다시 등록하면 다음 수집부터 정상으로 받아 와요. 바로 확인하려면 [마켓 동기화]를 누르세요.
4. IP가 맞는데도 계속 실패하면 API 키를 확인해요 — [API 관리]의 API KEY 관리에서 [인증하기]로 키를 다시 보고, 설정 → 마켓 계정(F12) → 11번가 카드의 [재인증] → 오픈API 키에 붙여 넣은 뒤 [저장](저장할 때 연결을 확인해요).

자세한 등록 절차는 마켓 추가하기 — 11번가를 보세요.

주문 행의 [⚠ 마켓 불일치] 배지를 누르면 두 가지가 나와요. 기준은 실물 택배에 붙은 번호예요.

자세한 흐름은 발송처리 — 송장번호 불일치 처리 참조.

확인사항:

• 하나로는 송장번호가 숫자만인지 확인해요. 하이픈·공백은 손으로 입력할 때 자동으로 지워 줘요. 엑셀 파일은 숫자만 있어야 받아요.
• 택배사별 자릿수는 하나로가 확인하지 않아요. 택배사 화면이나 송장 용지의 번호와 한 자리씩 맞는지 직접 비교해 주세요.

해결:

• 로젠 결과에서 받아온 번호는 형식이 이미 맞아요. 위 규칙과 다른 번호가 보이면 운송장 실물의 번호와 대조해 주세요.

증상: 운송장 인쇄 창이 뜬 채 멈추고, 하나로 화면에 “인쇄 창의 [확인]을 직접 눌러 주세요” 안내가 보여요.

원인: 대표적인 원인은 인쇄 프로그램(오즈 뷰어)이 관리자 권한으로 실행되는 경우예요. 이때는 Windows 보안 규칙 때문에 일반 권한으로 실행된 하나로가 그 창의 버튼을 누를 수 없어요. 하나로도 관리자 권한으로 실행되면 같은 권한이 되어 자동으로 누를 수 있어요.

해결:

1. 설정 → 일반 → 실행 권한에서 “하나로를 관리자 권한으로 실행” 이 켜져 있는지 확인해요(처음에는 켜져 있어요). 같은 칸에 “지금: 관리자 권한으로 실행 중” 이라고 나오면 적용된 상태예요. 스위치를 바꾸면 다음에 하나로를 켤 때부터 적용돼요.
   • 켜 두면 하나로를 켤 때마다 Windows가 이 앱의 변경을 허용할지 묻는 사용자 계정 컨트롤(UAC) 창을 띄워요. [예] 를 누르면 하나로가 관리자 권한으로 다시 켜져요. 업데이트 뒤 다시 켜질 때도 한 번 더 물을 수 있어요.
   • 하나로는 아직 코드서명 전이라 Windows 확인 창에 ‘게시자: 알 수 없음’ 이 노랗게 뜰 수 있어요 — 정상이에요.
   • [아니요] 를 누르면 하나로는 평소처럼(일반 권한으로) 켜지고, 화면 위에 그 안내가 나와요. 이때는 인쇄 창의 [확인]을 직접 눌러야 할 수 있어요. 매번 묻는 것이 싫으면 위 스위치를 끄면 돼요.
2. 이번에는 인쇄 창의 [확인] 을 직접 눌러요. 하나로가 창이 닫힌 것을 알아채고 결과 반영·송장번호 입력까지 이어서 진행해요. 5분 안에 누르지 않으면 자동 진행을 멈춰요.
3. 하나로를 관리자 권한으로 켤 수 없는 PC(아래 표준 사용자 계정)라면, 오즈 뷰어가 관리자 권한으로 실행되도록 설정돼 있는지 확인해 보세요. 오즈 뷰어 실행 파일의 속성 → 호환성 탭에서 “관리자 권한으로 이 프로그램 실행” 이 켜져 있으면 끄면 돼요. 같은 탭의 [모든 사용자에 대한 설정 변경] 안에 켜져 있을 수도 있으며, 이 경우 끄려면 PC 관리자 권한이 필요해요.

⚠ Windows 계정이 표준 사용자인 PC(사용자 계정 컨트롤 창이 다른 관리자 계정의 비밀번호를 묻는 PC)에서는 스위치가 켜져 있어도 하나로를 관리자 권한으로 켜지 않아요. 그 PC에서 관리자 권한으로 켜면 다른 Windows 계정으로 실행돼 기존 주문·설정과 저장된 로그인 정보가 보이지 않기 때문이에요. 설정 화면의 스위치 옆에 이 안내가 보이고, 하나로를 켤 때 화면 위에도 안내가 나와요. 그 안내를 닫으면 설정을 바꾸기 전까지 다시 나오지 않아요. 이런 PC에서는 3번 방법을 쓰거나 [확인]을 직접 눌러 주세요. 하나로 아이콘을 오른쪽 클릭해 “관리자 권한으로 실행” 을 고르는 것도 같은 이유로 권하지 않아요.

증상: 자동 진행이 멈춰 로젠 화주센터 창이 앞으로 나왔고, 그 창에서 용지 선택·출력을 직접 마쳤어요. 운송장은 정상으로 나왔는데 하나로 주문 목록의 송장번호는 비어 있어요(미지정).

원인: 하나로는 로젠 창의 [엑셀저장] 으로 내려받는 결과 엑셀에서 송장번호를 읽어 와요. 출력만 하고 창을 닫으면 결과 엑셀이 없어 송장번호가 들어오지 않아요. 이때 하나로 화면에는 “창이 송장번호 결과 없이 닫혔습니다” 안내가 나와요.

해결:

1. 자동 진행이 멈춰 로젠 창이 뜨면, 출력을 마친 뒤 같은 창의 [엑셀저장]까지 눌러 주세요. 하나로가 내려받은 결과를 바로 읽어 송장번호를 채우고 창을 닫아요.
2. 이미 창을 닫았다면 택배 자동접수는 끝났는데 송장번호가 비어 있습니다의 순서대로 로젠 화주센터에서 번호를 확인해 [송장번호 입력/수정…] 으로 넣어 주세요.

⚠ 송장번호가 비어 있다고 [택배 자동접수]를 다시 누르지 마세요. 이미 접수된 주문이 로젠에 한 번 더 접수돼 운송장이 중복으로 나올 수 있어요. 먼저 로젠 화주센터의 접수 내역을 확인해 주세요.

원인: 접수 자체는 됐지만 결과 엑셀에서 송장번호를 읽지 못한 경우예요 (결과 파일 저장 실패, 양식 변경 등).

해결:

1. 해당 주문의 발행된 운송장번호를 확인해요. 결과 엑셀을 받았다면 접수 직후 뜨는 결과 엑셀 창의 [파일 열기] 로 바로 볼 수 있고(한 건도 자동으로 채우지 못했으면 창에 송장번호 자동 반영 실패 — 파일을 직접 확인하세요. 가 나와요), 창이 뜨지 않았다면 로젠 화주센터에서 확인해요.
2. 하나로 주문 화면(F2)에서 그 주문 행을 마우스 오른쪽 버튼으로 클릭 → [송장번호 입력/수정…] 에 번호와 택배사를 넣고 저장해요.
3. 그 주문을 선택해 [선택 주문 송장 등록] 으로 마켓에 전송해요 — 구매자에게 배송 정보가 나가는 것은 이 단계예요.

자세한 사용법은 발송처리 — 송장번호 직접 입력 / 수정 참조.

ⓘ 마켓 셀러센터에 직접 입력한 뒤 [마켓 동기화] 를 눌러도 하나로 목록이 채워져요. 다만 왕복이 길어 위 경로를 권해요.

하나로에서: 주문을 체크하고 [더보기 ▾] → [선택 주문 송장 다시 출력(새 번호)…] (로젠택배 송장번호가 있는 주문, 한 번에 10건까지). 로젠은 다시 출력할 때 같은 번호가 아니라 새 송장번호를 매기니, 먼저 뽑은 송장은 쓸 수 없으니 버리세요. 이미 마켓에 송장을 등록한 주문은 마켓에 옛 번호가 남으니 마켓 셀러센터에서 직접 고쳐야 해요. 처음에는 한두 건으로 해 보고, 끝난 직후 [송장번호 불러오기] 로 번호가 맞는지 확인하세요(프린터 PC 실기 확인 전).

멈추거나 거절될 때: 3번 다 출력함(로젠에서 이미 3번 출력)·이미 발송 처리됨·아직 출력 전인 주문은 다시 출력하지 않아요. 번호 다름이면 먼저 [송장번호 불러오기] 를 누른 뒤 다시 시도하세요. 이 PC에서 출력할 수 없다는 안내(프린터 없음·오프라인 등)가 나오면 프린터가 있는 PC에서 하세요. 프린터 PC의 [받은 파일로 송장 출력…]에서는 다시 출력되지 않아요.

로젠 화면에서 직접 다시 출력했다면: 하나로에서 [송장번호 불러오기] 로 새 번호를 가져오세요. 자세한 내용은 발송처리 — 송장을 다시 출력하고 싶을 때 (그 절 안의 접힌 “송장을 다시 출력하고 싶을 때” 설명).

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

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

해결:

1. Hanaro 종료.
2. %APPDATA%\Hanaro\hanaro.db 백업.
3. SQLite 복구 시도:

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

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

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

원인: 마켓 비밀번호는 Windows 암호화(DPAPI)로 사용자·PC에 묶여 있어 다른 PC로 옮길 수 없어요 (의도된 보안 설계).

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

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

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

해결:

• 주문 화면의 기간 버튼으로 조회 기간을 짧게 잡으세요(예: 최근 7일). 설정에는 동기화 기간·병렬도 항목이 없어요.
• 처음 동기화는 오래 걸려도 정상이에요. 이후는 증분 동기화로 빨라져요.

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

해결:

• 필터로 행 수 줄이기 (예: 최근 7일).
• 설정 → 일반의 압축 모드를 켜면 한 화면에 더 많은 행이 보여요.

%APPDATA%\Hanaro\logs\
  hanaro-20260509.log
  hanaro-20260508.log
  ...

• 매일 새 파일 생성.
• 최근 14일치(파일 14개)만 남기고 오래된 파일은 자동 삭제 (롤링).
• 로그 레벨: Information 이상.
• 로그 폴더 열기 버튼은 아직 없어요. 탐색기 주소창에 %APPDATA%\Hanaro를 붙여 넣어 열어 주세요.

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를 계산해요.

해결 — 정식 재생성

1. 현재 DB 백업: %APPDATA%\Hanaro\hanaro.db → hanaro.db.bak.
2. 재생성 스크립트 실행:

   pwsh ./scripts/regen-migrations.ps1
   

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

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

Migrate vs EnsureCreated 비상 전환

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

# 자동 마이그레이션 끄고 EnsureCreated 폴백 모드로 시작.
$env:HANARO_DB_AUTO_MIGRATE = "false"
# 설치본 실행 파일은 Hanaro.UI.exe 예요(기본 위치: %LocalAppData%\Hanaro\current\).
& "$env:LOCALAPPDATA\Hanaro\current\Hanaro.UI.exe"

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

하나로는 %APPDATA%\Hanaro 아래의 설정 파일을 읽지 않아요(appsettings.user.json 같은 파일을 만들어도 효과가 없어요). 로그 레벨은 HANARO_로 시작하는 환경변수로 바꿔요.

1. Windows 설정 → 시스템 → 정보 → 고급 시스템 설정 → 환경 변수에서 사용자 변수를 추가해요.
   • 이름: HANARO_Serilog__MinimumLevel__Default
   • 값: Debug
2. 하나로를 완전히 끄고 다시 켜요.
3. 진단이 끝나면 그 환경변수를 지우고 다시 켜요.

단, 하나로를 켤 때 맨 먼저 하는 업데이트 확인 단계의 로그는 이 환경변수와 상관없이 늘 Information 수준으로 남아요.

Debug 레벨은 로그 양이 매우 많아요. 문제 진단이 끝나면 꼭 환경변수를 지워 주세요.

오류 보고(Sentry)는 HANARO_SENTRY_DSN 환경변수가 있을 때만 켜져요. 이 환경변수를 빈 값으로 설정하거나 삭제한 뒤 Hanaro를 다시 켜면 꺼져요.

설정 화면에는 오류 보고를 켜고 끄는 항목이 없어요. 설정 화면에서는 끌 수 없어요.

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

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

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

## 기대 동작
...

## 실제 동작
...

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

문의하기 → hanalabs@hanapf.kr