문제 해결

CSO 정산 포털 운영 중 발생할 수 있는 주요 문제와 해결 방법을 설명합니다.

엑셀 업로드 실패

파일 형식 오류

증상: “지원하지 않는 파일 형식입니다” 메시지가 표시됩니다.

원인 및 해결:

컬럼 구조 불일치

증상: “필수 컬럼이 누락되었습니다” 메시지가 표시됩니다.

필수 컬럼: 사업자번호, 정산월

해결 절차:

1. “컬럼 매핑 확인” 버튼을 클릭합니다.
2. 매핑 다이얼로그에서 엑셀 컬럼과 DB 컬럼의 대응 관계를 확인합니다.
3. 자동 매핑이 실패한 컬럼을 수동으로 지정합니다.
4. 필수 컬럼이 모두 매핑되었는지 확인 후 업로드합니다.

자동 매핑 기준: 컬럼명 유사도 점수 0.6 이상이면 자동 매핑됩니다. SIT 솔루션 버전에 따라 컬럼명이 미세하게 다를 수 있으므로 수동 확인을 권장합니다.

인코딩 문제

증상: 업로드 후 한글이 깨져서 표시됩니다.

해결:

• SIT 솔루션에서 .xlsx 형식으로 내보내기합니다 (.xls보다 권장).
• Excel에서 파일을 열고 “다른 이름으로 저장” → “Excel 통합 문서(*.xlsx)“로 저장합니다.
• 포털은 xlsx 라이브러리로 파싱하므로 UTF-8 인코딩된 .xlsx 파일이 가장 안정적입니다.

같은 정산월 재업로드

주의: 같은 정산월 데이터를 다시 업로드하면 해당 월의 기존 데이터가 모두 삭제된 후 새 데이터로 교체됩니다. 이는 정상 동작이며, 부분 업데이트는 지원하지 않습니다.

CSO 매칭 오류

업체명과 사업자번호 불일치

증상: 회원이 로그인했지만 정산 데이터가 보이지 않습니다.

원인: 정산서의 CSO관리업체와 회원의 사업자번호 간 매칭이 없습니다.

확인 절차:

1. /admin/integrity 페이지에서 무결성 검사를 실행합니다.
2. missing_match 상태의 업체를 확인합니다.
3. 해당 업체의 실제 사업자번호를 확인합니다.
4. 매칭 데이터를 추가합니다 (사업자번호 입력).

매칭 상태별 조치

업체명 변경

SIT 솔루션에서 업체명이 변경된 경우, cso_matching 테이블의 cso_company_name도 새 이름으로 추가해야 합니다. 이전 이름의 매칭은 과거 데이터 조회를 위해 삭제하지 않는 것을 권장합니다.

한 업체에 여러 업체명

하나의 CSO 업체가 정산서에서 여러 이름으로 등장할 수 있습니다 (예: “A제약”, “A제약(주)”, “(주)A제약”). 이 경우 cso_matching 테이블에 각 이름을 동일한 사업자번호로 매핑합니다.

이메일 발송 실패

Resend API 한도 초과

증상: 이메일 발송 시 429 Too Many Requests 에러가 발생합니다.

원인: Resend 무료 플랜 기준 일일 100건, 초당 2건 제한이 있습니다.

해결:

SMTP 설정 오류

증상: SMTP 프로바이더로 전환 후 이메일이 발송되지 않습니다.

확인 사항:

연결 테스트: /admin/email-settings에서 “연결 테스트” 버튼을 클릭하면 test_recipient_email로 테스트 이메일이 발송됩니다. 실패 시 에러 메시지에서 원인을 확인합니다.

이메일 미수신

발송 성공(sent)으로 기록되었으나 수신자가 이메일을 받지 못한 경우:

1. 스팸함 확인: 수신자의 스팸/정크 메일함을 확인합니다.
2. 수신 주소 확인: /admin/members에서 해당 회원의 이메일 주소가 정확한지 확인합니다.
3. 발신 도메인: Resend 사용 시 발신 도메인의 SPF/DKIM 설정이 올바른지 확인합니다.

빌드/배포 실패

Vercel 빌드 에러 확인

1. Vercel 대시보드 → csoweb 프로젝트 → Deployments 탭
2. 실패한 배포 클릭 → Build Logs 확인
3. 에러 메시지를 분석하여 원인 파악

흔한 빌드 에러

환경변수 누락

배포 환경에서 필수 환경변수가 없으면 빌드 또는 런타임에서 에러가 발생합니다.

필수 환경변수 목록:

Vercel 대시보드 → Settings → Environment Variables에서 프로덕션 환경에 모든 변수가 설정되었는지 확인합니다.

배포 롤백

문제가 있는 배포를 이전 버전으로 롤백하려면:

1. Vercel 대시보드 → Deployments
2. 정상 작동하던 이전 배포를 찾습니다.
3. 해당 배포의 ⋯ 메뉴 → Promote to Production 클릭
4. 즉시 이전 버전으로 프로덕션이 전환됩니다.

인증 문제

JWT 만료

증상: 사용자가 갑자기 로그아웃되거나, API 요청이 401로 실패합니다.

원인: JWT 토큰의 유효기간(24시간)이 만료되었습니다.

해결: 다시 로그인합니다. 현재 토큰 자동 갱신(Refresh Token)은 구현되어 있지 않으므로, 24시간마다 재로그인이 필요합니다.

쿠키 문제

증상: 로그인 성공 메시지가 표시되지만 페이지 이동 후 로그인이 풀립니다.

확인 사항:

계정 잠금

증상: “계정이 잠겼습니다” 메시지가 표시됩니다.

원인: 비밀번호를 15회 연속 틀린 경우 계정이 자동 잠금됩니다.

해결:

1. 등록된 이메일로 발송된 비밀번호 변경 링크를 클릭합니다.
2. 새 비밀번호를 설정하면 잠금이 해제됩니다.
3. 이메일을 받지 못한 경우, 관리자가 /admin/members에서 비밀번호를 초기화합니다.

관리자 권한 없음

증상: 관리자 페이지에 접근할 수 없습니다.

확인: 해당 계정의 is_admin 필드가 true인지 확인합니다. 다른 관리자가 /admin/members에서 해당 회원의 “관리자 권한”을 활성화해야 합니다.

성능 문제

대시보드 로딩 느림

원인: 정산 데이터가 대량인 경우 조회 시간이 길어질 수 있습니다.

조치:

• /admin/columns에서 불필요한 컬럼을 숨겨 조회 데이터량을 줄입니다.
• 특정 정산월만 선택하여 조회합니다.
• 일반회원은 CSO 매칭 기반으로 자기 데이터만 조회하므로 상대적으로 빠릅니다.

메일머지 발송 지연

대량 이메일 발송 시 발송 간격(기본 6초) 때문에 전체 소요 시간이 길어집니다.

예상 소요 시간: 업체 수 × 발송 간격

발송 간격을 줄이면 Resend API Rate Limit에 걸릴 수 있으므로, 대량 발송 시 SMTP 프로바이더 사용을 권장합니다.