자동 보고 흐름
자동 적재, 보내기 전 준비, 보고, 보낸 뒤 검사가 언제 무엇을 하는지 정리한 참고 문서입니다. 화면에서 하는 절차는 사용자 매뉴얼을 봅니다.
하루 시간표
시각은 모두 한국 시간입니다.
| 시점 | 하는 일 |
|---|---|
| 물류 마감 | KPI. 마감 감시가 요청을 남기면 물류 마감 적재기가 마감일과 앞 14일을 바코드 원천과 대조해 달라진 날만 싣습니다 |
| 적재 직후 | 적재에 성공한 날짜가 하나라도 있으면 자동 보고 작업을 등록합니다 |
| 보고 1분 뒤 | KPIS 집계(MA110)를 다시 받아 주문·바코드·KPIS를 날짜별로 대조합니다 |
| 09:40, 13:40, 17:40 | 심평원 반송 승인(09:30, 13:30, 17:30) 10분 뒤 열린 반송신청 결과(MA114)를 받습니다 |
| 판매 마감 | KPI. 마감 발행기가 요청을 남기면 최근 30일 보고 무결성 검사를 합니다 |
| 23:00 | 서버가 오늘 물류 마감 요청을 스스로 넣습니다. 물류 마감이 없는 날과 주말도 싣고 보고합니다 |
| 하루 한 번 | 요청이 오지 않아도 판매 마감 뒤 검사와 적기보고율 점검을 예비로 겁니다 |
자동 적재
- 원천은 바코드 서버의 공급내역 보고 뷰와 일련번호 뷰입니다. 변환 규칙은 바코드 프로그램의 파일 생성 프로시저를 옮긴 것이고, 바코드 서버는 읽기만 합니다.
- 사람이 고쳤거나 제출한 날은 덮지 않고 ‘원천 바뀜’으로 남깁니다.
- 원천이 0줄인데 적재본이 있으면 지우지 않고 ‘원천 바뀜’으로 남깁니다. 전표가 모두 취소된 경우에만 날짜 자료를 지웁니다.
- 날짜마다 결과를 보고 가능, 보류(원천 0줄), 실패(원천 조회 실패)로 남깁니다. 한 날짜가 실패해도 성공한 날짜의 자동 보고는 계속됩니다.
- 원천을 읽지 못하면 5분 뒤 다시 돌고, 요청마다 세 번까지 시도합니다. 그래도 실패한 요청은 남겨 두었다가 다음 물류 마감 때 함께 처리합니다.
- 하루 적재는 날짜 잠금 아래 한 트랜잭션으로 하고, 읽는 사이 작업본이 바뀌었으면 거절합니다.
- 한 줄에 일련번호가 1만 개를 넘으면 박스 경계로 수량을 나눈 여러 줄로 싣습니다. KPIS 요청 크기 한도 때문입니다. 공급금액은 수량 비율로 나눠 합계를 유지합니다.
- 줄 데이터(갑지·원본·을지)는 이번 달과 앞 12개월만 둡니다. 결과 미확인이나 반송신청이 진행 중인 날은 남깁니다. 그 앞 기간은 KPIS 집계(숫자만 보관)로 봅니다.
보고 범위와 계산 규칙
| 항목 | 규칙 |
|---|---|
| 보고하지 않는 줄 | 수탁·수출 건, 자사에 준 견본품(공급형태 7), 공급받은자 사업자번호가 없는 줄. 수출은 수출팀이, 사업자번호 없는 줄은 따로 보고합니다 |
| 공급자 영업형태 | 7(제조+수입+도매)로 고정합니다 |
| 공급단가·공급금액 | 부가세 포함. 공급금액 = 공급수량 × 공급단가 |
| 금액 차이 | 1~2원 반올림 차이는 그대로 보냅니다. 2원을 넘고 2%를 넘게 다르면 사전점검이 보류합니다 |
| 낱개로 등록한 주사제 | 수량 ×10, 단가 ÷10(원 단위 반올림). 등록한 주사제에만 적용합니다 |
| 폐기 | 공급단가·공급금액 0원. 공급받은자는 자사(자체폐기) 또는 폐기업체·보건소 |
| 공급일자 예외 | 출고 줄은 배송일이 명세서 일자보다 빠르면 공급일자 = 배송일, 비고 ZQ. 늦으면 공급일자 = 명세서 일자, 비고 ZC와 배송일 |
| 정정·취소 기한 | 공급월 다음 달 말일. 그 뒤는 반송신청 |
| 쉬는 날 | 영업일이라도 갑지가 없으면 공급이 없는 날입니다 |
보내기 전 준비
화면의 보고, 빠진 줄 보고, 자동 보고 모두 보고 계획을 만들기 전에 같은 준비를 거칩니다.
- 규격보정. 미보고·반송 줄의 공급규격을 표준코드 마스터에 맞춥니다. 바뀐 수량이 정수가 아니면 고치지 않고 검토로 남깁니다.
- 주문 대조. 주문 내역(KPI. 판매 상세)과 공급구분·거래처·표준코드 묶음별 낱개 수와 부가세 포함 금액을 견줍니다. 다르면 주문 값으로 고칩니다. 주문에 없는 줄, 그날 주문 자료가 아직 없는 날, 같은 비율로 고칠 수 없는 로트 줄은 빼 두고 다음 보고 때 다시 견줍니다.
- 보고 계획. 날짜별 대상과 제외·보류 사유를 정합니다. 반송신청이 진행 중이거나 반송보고를 마친 줄은 뺍니다. 기한이 지난 새 줄은 줄 수·수량을 보여 주고 늦은 보고 확인 없이는 시작하지 않습니다. 자동 보고는 그런 날을 보내지 않습니다.
- 사전점검. 필수값, 표준코드 13자리·마스터 존재, 일련번호 부착 품목의 을지, 정정·취소의 원 출고 줄, 같은 줄 중복, 정정·취소 기한, 공급받은자 사업자번호, 요양기관기호를 봅니다.
- 이미 접수 검사. 그 공급일자·공급구분에 KPIS 접수가 있으면, 거래처마다 KPIS 줄 수·수량·금액이 우리 보고분과 정확히 같을 때만 보냅니다. 결과 미확인 줄이 있는 거래처나 집계를 받지 못한 거래처는 보내지 않습니다.
보내기
- 공급구분마다 한 요청에 최대 500줄, 본문 2MB 이하로 묶어 보냅니다.
- KPIS는 묶음 안 한 줄만 틀려도 묶음 전체를 받지 않습니다(부분 접수 없음). 그래서 세 단계로 보냅니다.
- 공급구분별 전체 보고
- 틀린 줄만 반송으로 빼고 다시 전체 보고(1단계 포함 최대 3회)
- 그래도 새 오류가 나오면 남은 줄을 한 줄씩 보고
- 보내기 직전에 줄을 결과 미확인으로 먼저 기록하고, 접수번호를 받으면 곧바로 다시 기록합니다. 서버가 어디서 멈춰도 그 줄은 다시 나가지 않습니다.
- 보고 저장이 시간 초과, 통신 끊김, 5xx 응답이면 결과 미확인으로 둡니다. 4xx나 KPIS 업무 오류처럼 확실히 거절된 경우만 미보고로 되돌립니다.
- 접수 여부를 모르는 끊김이 한 번이라도 나면 남은 공급구분도 보내지 않고 실행을 멈춥니다.
- 같은 날짜는 한 번에 한 실행만 돕니다.
자동 보고만의 규칙
- KPIS 연동 키의 자동 보고가 켜져 있을 때만 보냅니다. 기본은 꺼짐입니다.
- 보내는 줄은 미보고 줄(정정·취소 포함)과 고친 지 20분이 지난 반송 줄입니다.
- 결과 미확인 줄이 있는 날은 보내지 않고 KPIS에 결과부터 다시 묻습니다.
- 같은 내용 지문과 줄 상태로 시도한 날은 다시 보내지 않습니다. 서버가 다시 켜져도 같습니다. KPIS에 한 번도 보내지 않고 끝난 시도(토큰 실패 등)만 다음 보고 때 다시 봅니다.
- 다시 반송된 줄은 사람이 고칠 때까지 보내지 않습니다.
- 보고한 날의 원천이 바뀌었으면 새 줄·정정·취소를 만들어 보냅니다. 정정 값은 원천이 바꾼 칸만 원천 값을 쓰고, 이미 보고한 값과 같으면 정정하지 않습니다.
- 정정 기한이 지난 줄, 정정할 수 없는 칸(거래처, 공급일 등)이 바뀐 줄은 만들지 않고 로그에 남깁니다. 그런 줄이 남은 날은 사람이 볼 때까지 보내지 않습니다.
- 한 날짜에서 오류가 나면 기록하고 다음 날짜로 갑니다.
보낸 뒤 검사
보고 1분 뒤. KPIS 집계를 다시 받아 주문 내역과 날짜·공급구분·거래처마다 수량(박스)과 부가세 포함 금액을 견줍니다. 결과는 대시보드의 날짜별 대조와 주문·KPIS 대조 화면, KPI. 영업지원 홈에 보입니다.
판매 마감 뒤(최근 30일).
- KPIS 집계를 새로 받습니다. 받지 못하면 오래된 값으로 판정하지 않고 다시 시도합니다.
- 정정 기한이 남은 보고한 날 가운데 원천 판정이 ‘바뀜’인 날은 정정·취소·새 줄을 만들어 자동 보고로 보냅니다.
- 보고 뒤 주문만 바뀐 날은 API로 접수한 줄만 있는 묶음을 주문 값으로 정정·취소합니다. 거래처를 확실히 맞출 수 없으면 알리기만 합니다.
- 그 날들을 KPIS 집계와 견주고 미접수 줄을 셉니다. 원천은 다시 읽지 않습니다.
폐기. 폐기는 주문에 없으므로 KPIS 폐기를 바코드 서버 원천과 날짜·거래처로 견줍니다.
작업 장부와 재시도
- 시점마다 데이터베이스 작업 장부에 작업을 넣기만 하고, 웹 서버가 시작할 때와 1분마다 만기 작업을 집어 처리합니다. 서버가 다시 켜져도 남은 작업과 재시도 시각이 그대로 남습니다.
- 실패한 작업은 1, 5, 15, 30, 60분 간격으로 다시 시도한 뒤 사람 확인으로 남깁니다.
- 판매 마감 뒤 대조가 36시간 넘게 끝나지 않으면 로그에 알립니다.
- 자동 보고가 15분 넘게 진행 중이면 실패로 덮지 않고 5분 뒤 상태를 다시 봅니다.
- 이 시점들은 서버 설정의 보고 흐름 스위치가 켜져 있을 때만 돕니다. 끄면 화면과 조회만 하는 서버가 됩니다.
기록
알림은 메일로 보내지 않고 KPIS 보고 › 로그(운영 기록)에 남깁니다. 분류는 자동 보고, 물류 마감, 판매 마감 뒤 검사, 시스템이고 수준은 기록, 확인, 오류입니다. 로그 위쪽에 자동 보고 켜짐·꺼짐과 바코드 원천 연결 상태가 보입니다. 보고 실행마다의 단계 기록은 이력 탭에 있습니다.
확인 기준: 2026-11-18, KPIS-DSR-API 저장소(
crates/kpis-server,AGENTS.md,docs/kpis-report-api.md) 기준.