데이터 구조
이 시스템이 Supabase(PostgreSQL)에 두는 표를 역할별로 정리한 참고 문서입니다. KPI.와 같은 데이터베이스를 쓰며 이 시스템의 표와 함수는 kpis_로 시작합니다. 표 정의는 저장소 supabase/migrations/에 번호 순으로 있습니다.
공급 자료
| 표 | 담는 것 |
|---|---|
kpis_gap_rows | 작업본 갑지 줄. 보고 상태, 반송 사유, 접수번호, 정정·취소의 원 줄 연결을 함께 둡니다 |
kpis_eul_rows | 갑지 줄에 딸린 을지(일련번호·묶음번호) |
kpis_gap_rows_raw | 원천에서 읽은 그대로의 적재본. 원천 변경을 판정할 때 견줍니다 |
kpis_collection_logs | 날짜별 원천 조회 기록과 판정 |
kpis_supply_summary | KPIS 집계(MA110) 사본. 줄 데이터 보관 기간이 지난 달도 숫자는 끝까지 남깁니다 |
kpis_supply_summary_state | KPIS 집계를 받은 범위와 시각 |
줄 데이터(갑지·원본·을지)는 이번 달과 앞 12개월만 둡니다. 물류 마감 적재 뒤 오래된 줄을 정리하고, 결과 미확인·반송신청 진행 중인 날은 남깁니다.
보고 상태
| 표 | 담는 것 |
|---|---|
kpis_workspace_day | 날짜별 보고 상태 버전. 원천 판정만 담습니다 |
kpis_workspace_plans | 고정한 보고 계획 |
kpis_workspace_sent | 줄마다 마지막으로 보낸 내용의 지문. ‘고친 반송 줄’과 ‘API 접수 후 변경’을 판정합니다 |
kpis_workspace_downloads | 엑셀 다운로드 이력(대상·버전) |
kpis_workspace_completions | 수기보고 완료 표시와 그때의 내용 지문 |
kpis_report_runs | 보고 실행 이력(날짜, 서버, 갑지·을지, 접수·반송·전송 수) |
kpis_report_run_events | 실행의 단계 기록 |
kpis_report_records | 줄 결과 스냅샷 |
kpis_return_requests | 반송신청과 결과. 한 줄에 열린 신청은 하나뿐입니다 |
kpis_auto_report_attempts | 자동 보고 시도 표식. 같은 자료로 다시 보내지 않게 합니다 |
kpis_integrity_checks | 판매 마감 뒤 검사 결과(날짜별) |
kpis_reconciliation_reviews | 주문·KPIS 대조의 메모·문제없음 확인 기록. 보고 내용은 바꾸지 않습니다 |
kpis_flow_jobs | 작업 장부. 자동 보고, 집계 갱신, 반송 결과 조회, 판매 마감 검사의 예약·재시도 |
kpis_flow_day_state | 날짜별 적재·보고 흐름 상태 |
kpis_ops_log | 운영 기록. 화면 KPIS 보고 › 로그의 원본입니다 |
기준 자료
| 표 | 담는 것 |
|---|---|
kpis_standard_codes | 표준코드 마스터(규격, 포장, 일련번호 생략 여부). MA118로 갱신합니다 |
kpis_master_barcode, kpis_master_excel, kpis_master_erp, kpis_master_atc | 출처별 마스터. 마스터 DB 화면의 통합·바코드·코드매핑조회 건수의 원본입니다 |
kpis_code_mappings | 제품명·규격·포장과 표준코드의 짝 |
kpis_price_learn | 단가오류 학습 결과 |
규칙과 수정 이력은 데이터베이스가 아니라 각 사용자의 브라우저 저장소에 둡니다(수정 이력은 최근 1,000건). 마이그레이션에 있는 규칙·수정 이력 표는 지금 코드가 쓰지 않습니다.
설정과 사용자
| 표 | 담는 것 |
|---|---|
kpis_api_config | KPIS 보고 설정 한 줄(서버, 보고 사업자번호, 암호화한 자격증명, 조회 키, API 보고 시작일, 자동 보고 스위치) |
kpis_datasource_config | 바코드 서버 수집 경로 설정 |
kpis_vpn_logs | 수집 활동 로그 |
kpis_users | 사용자와 승인·역할 |
kpis_app_settings | 앱 설정 값(단가오류 자동채움 설정, 위탁창고 예외, 적기보고율 점검 상태) |
kpis_user_preferences | 사용자별 화면 설정(작업용 보기 열 설정). 본인 행만 읽고 씁니다 |
휴일은 이 시스템에 두지 않습니다. KPI.의 시스템 설정(공휴일, 회사 휴무, 거래 없는 평일)을 읽기만 합니다.
쓰기 권한 규칙
- 화면이 부르는 함수는 호출자가 승인 사용자인지(관리자 전용이면 관리자인지) 먼저 확인합니다.
- 날짜를 지우거나 다시 싣는 함수는 보고 흔적(접수, 포털 제출, 결과 미확인, 엑셀 다운로드)이 있는 날을 거절합니다.
- KPIS 자격증명과 토큰 표는 서버만, 줄 결과 스냅샷은 화면이 읽기만, 갑지 줄의 보고 상태 칸은 서버만 바꿉니다.
- 화면 저장은 불러온 값과 달라진 줄·칸만 불러온 수정 시각과 함께 보냅니다. 다른 곳에서 먼저 바뀐 줄은 저장하지 않고 데이터베이스 내용으로 되돌립니다.
- 하루 적재, 정정·취소 줄 만들기, 전송 예약, 결과 미확인 정리는 날짜 잠금 아래 한 트랜잭션으로 합니다.
로컬 SQLite
웹 서버는 로컬 SQLite 파일 하나를 씁니다. KPI. 권한증명의 일회용 값을 저장해 같은 증명을 두 번 받지 않게 합니다. 예전에 두던 공동인증서 설정 표는 2026-11-18에 지웠습니다.
확인 기준: 2026-11-18, KPIS-DSR-API 저장소(
supabase/migrations/,crates/kpis-server,AGENTS.md) 기준.