문제 해결

시스템 운영 중 발생할 수 있는 주요 문제의 원인과 해결 방법을 안내합니다.

엑셀 업로드 실패

파일 형식 오류

인코딩 문제

파일 크기 제한

대용량 파일 업로드 시 타임아웃이 발생할 수 있습니다.

표준코드 매핑 오류

코드매핑이 적용되지 않는 경우

표준코드 조회 실패

KPIS API 연동 실패

인증서 관련

인증서 만료 예방

인증서 갱신 권장 일정:

네트워크 관련

IP 화이트리스트 확인

KPIS API는 등록된 IP에서만 호출 가능합니다.

# Oracle Cloud 서버에서 외부 IP 확인
curl -s ifconfig.me

표시된 IP가 KPIS에 등록한 IP와 일치하는지 확인합니다. 불일치 시 KPIS 관리자에게 IP 변경 신청이 필요합니다.

API 응답 코드

반송 처리 대응 (DC001~DC007)

MA112 결과에서 반송된 건의 코드별 대응 방법입니다.

DC001: 표준코드 불일치

원인: 존재하지 않거나 만료된 표준코드를 사용했습니다.

해결 절차:

1. MA101 API로 해당 제품의 올바른 표준코드 조회
2. cancel_date가 설정된 코드인지 확인
3. 표준코드 수정 후 MA113 반송신청

DC002: 미등록 거래처

원인: KPIS에 등록되지 않은 거래처 사업자번호입니다.

해결 절차:

1. MA102 API로 거래처 등록여부 확인
2. 사업자등록번호 오타 확인 (10자리)
3. 미등록 거래처면 KPIS 포털에서 거래처 등록 선행

DC003: 보고기간 외 공급일자

원인: 공급일자가 해당 분기 보고기간 범위를 벗어났습니다.

해결 절차:

1. MA116 API로 해당 분기의 보고기간 조회
2. 공급일자(N열)가 보고기간 내인지 확인
3. 기간 외 공급건은 해당 분기로 이동하여 재제출

DC004: 중복보고

원인: 이미 등록된 동일 데이터가 존재합니다.

해결 절차:

1. MA112로 기등록 건의 접수번호 확인
2. 재제출이 아닌 정정(공급구분 4) 또는 **취소(공급구분 5)**로 처리
3. MA113 반송신청은 사용하지 않음

DC004는 다른 반송코드와 달리 MA113이 아닌 정정/취소로 처리해야 합니다.

DC005: 수량/금액 오류

원인: 단가 x 수량 ≠ 금액 정합성이 맞지 않습니다.

해결 절차:

1. 해당 행의 단가(P열), 수량(M열), 금액(O열) 확인
2. 단가 x 수량 = 금액 (1원 이내 오차 허용) 검증
3. 불일치 시 단가 또는 수량 수정 (금액은 불변)

DC006: 을지 누락

원인: 일련번호구분(U열)이 0(부착)인데 을지 데이터가 없습니다.

해결 절차:

1. 해당 연번의 을지 데이터 존재 확인
2. 을지 파일이 누락되었으면 재업로드
3. 일련번호가 불필요한 품목이면 일련번호구분을 1(생략)로 변경

DC007: 요양기관기호 오류

원인: 공급형태가 9(요양기관)인데 요양기관기호가 누락되었거나 형식이 다릅니다.

해결 절차:

1. 공급형태(F열) = 9 확인
2. 요양기관기호(I열)가 8자리인지 확인
3. 건강보험심사평가원에서 올바른 요양기관기호 조회 후 수정

서버 장애 대응

서버 상태 확인

# PM2 프로세스 상태 확인
pm2 status
 
# Express 서버 로그 확인
pm2 logs kpis-dsr-api --lines 50
 
# 서버 리소스 확인
df -h          # 디스크 용량
free -m        # 메모리

서버 재시작

# PM2로 재시작
pm2 restart kpis-dsr-api
 
# 재시작 후 상태 확인
pm2 status
curl -s http://localhost:3002/api/health

Supabase 연결 장애

Supabase 셀프호스팅 서버(sb.dvsharp.com)에 접근 불가한 경우:

# Supabase 서버 응답 확인
curl -s https://sb.dvsharp.com/rest/v1/ -H "apikey: YOUR_ANON_KEY"
 
# Docker 컨테이너 상태 확인 (Supabase 서버에서)
docker ps

로컬 DB (cert_config) 장애

# local.db 파일 존재 확인
ls -lh data/local.db
 
# 파일 권한 확인
stat data/local.db

Nginx 관련

Vercel 프론트엔드 장애

공통 진단 절차

문제 발생 시 아래 순서로 진단합니다.

1. PM2 상태 확인: pm2 status — 서버가 실행 중인지 확인
2. 서버 로그 확인: pm2 logs kpis-dsr-api --lines 100 — 에러 메시지 확인
3. API 응답 테스트: curl http://localhost:3002/api/health — 서버 정상 동작 확인
4. Supabase 연결: 브라우저에서 sb.dvsharp.com 접근 가능 여부
5. 네트워크: curl -s ifconfig.me — 외부 IP 확인, KPIS 연결 테스트

다음 단계

• 배포 — Oracle Cloud/Vercel 배포 절차
• 데이터베이스 — DB 구조 및 백업
• API 레퍼런스 — 엔드포인트 상세