로컬푸드 직매장 정산 자동화 시스템 구성 문서

1. 시스템 목표

약 30개 농가가 입점한 로컬푸드 직매장에서 계산대 판매 파일을 매주 업로드해 농가별 주간 정산서를 만들고, 매장 매출과 정산 합계를 대조한 뒤 권한자가 목요일에 정산 마감하는 웹 서비스입니다.

농가는 스마트폰에서 본인 정산서, 지급액, 입금 예정일, 판매·할인·반품·폐기 내역을 확인하고 이의 제기와 증빙 사진을 제출합니다.

첫 버전은 로컬푸드 직매장 한 곳만 처리합니다. 여러 매장 관리, 실제 은행 이체, 은행 이체용 파일 생성은 포함하지 않습니다.

2. 사용자와 권한

사용자	할 수 있는 일	제한
정산 담당 직원	농가·품목·정산 규칙 등록, 계산대 판매 파일 업로드, 상품 연결, 반품·폐기 등록, 오류 처리, 정산서 생성	정산 마감 권한이 없으면 마감 불가
점장 또는 마감 권한을 가진 운영자	정산 담당자의 기능 전체, 매주 목요일 정산 마감, 담당자 계정과 권한 관리, 정정 항목 확인	오류 또는 매출 대조 차이가 남으면 마감 불가
농가	본인 정산서 조회, 판매·할인·반품·폐기 내역 확인, 이의 제기와 증빙 사진 제출	다른 농가의 정산서, 사진, 판매 내역 접근 불가

3. 첫 버전 범위

포함 기능

기능	사용 목적	완료 조건
운영자 로그인과 권한 관리	정산 담당자와 마감 권한을 구분한다.	권한 없는 사용자는 정산 마감과 권한 변경을 할 수 없다.
농가·품목 관리	농가, 품목군, 품목, 상품코드를 정산 대상에 연결한다.	판매 항목을 농가와 품목에 연결할 수 있다.
정산 규칙 관리	수수료율, 할인 수수료, 반품·폐기 부담 기준을 약정대로 등록한다.	적용 시작일과 종료일을 가진 규칙 이력이 저장된다.
계산대 판매 파일 업로드	주간 판매·할인·반품 내역을 판매 원장에 반영한다.	파일 형식과 필수 열을 검사하고, 중복 업로드를 막는다.
상품코드 자동·직접 연결	등록 상품코드는 자동 연결하고 처음 보는 상품코드는 직접 연결한다.	미연결 판매 항목이 오류 목록에 표시된다.
판매·할인·반품·폐기 관리	정산 계산 근거를 한곳에서 확인한다.	폐기·미회수 기록은 농가, 품목, 수량, 사유, 부담 주체 없이 확정할 수 없다.
정산 계산	농가별 판매액, 수수료, 공제액, 지급액을 계산한다.	계산 당시 적용한 정산 규칙과 계산 결과를 보관한다.
매출 대조와 오류 검사	매장 매출과 농가별 정산 계산 항목의 차이를 확인한다.	미연결 상품, 규칙 누락, 미확정 내역, 대조 차이를 모두 확인할 수 있다.
정산서 생성과 정산 마감	농가별 정산서를 생성하고 목요일에 마감한다.	오류 0건, 대조 차이 0원일 때만 마감할 수 있다.
마감 잠금	마감된 정산서와 계산 근거를 변경하지 못하게 한다.	서버가 수정 요청을 거부한다. 화면 버튼만 숨기는 방식은 사용하지 않는다.
정정 항목	마감 후 오류를 다음 정산 주차에 반영한다.	원 정산서, 원 거래, 정정 전후 금액, 처리 담당자, 다음 반영 주차가 저장된다.
농가 정산 조회	농가가 스마트폰에서 본인 지급액과 입금 예정일을 확인한다.	농가는 본인에게 연결된 정산서만 조회할 수 있다.
농가 이의 제기	농가가 정산 내역에 대한 문의와 증빙을 제출한다.	처리 결과, 담당자, 처리일, 농가 안내 날짜와 방법을 기록할 수 있다.

첫 버전 제외 기능

실제 은행 이체
은행 이체용 파일 생성
여러 로컬푸드 직매장 운영
상품코드 외 고도화된 자동 상품 연결
문자, 카카오톡 등 별도 알림 발송

4. 화면 구성

운영자 화면

화면	주요 내용	다음 행동
운영자 로그인과 권한 관리	로그인, 정산 담당자 계정, 마감 권한 관리	주간 정산 현황으로 이동
주간 정산 현황	정산 주차, 입금 예정일, 판매 파일 처리 상태, 미연결 상품 수, 오류 수, 매출 대조 차이, 마감 가능 여부	규칙 관리, 파일 업로드, 오류 처리, 정산 마감으로 이동
농가·품목·정산 규칙 관리	농가, 품목군, 품목, 상품코드, 수수료율, 할인 수수료, 반품·폐기 부담 규칙, 적용 기간 관리	규칙 저장 후 주간 정산 현황으로 복귀
계산대 판매 파일 업로드와 상품 연결	파일 업로드, 형식 검사, 상품코드 자동 연결, 처음 보는 상품코드 직접 연결	판매 원장과 오류 목록 확인
판매·할인·반품·폐기 내역 확인	판매 원장 조회, 반품·폐기 등록, 할인·반품·폐기 확인	오류 목록과 매출 대조로 이동
오류 목록과 매장 매출 합계 대조	미연결 상품, 규칙 누락, 중복 가능 거래, 미확정 처리 내역, 매출 대조 차이 확인	오류 해결 후 정산서 생성
농가별 정산서 생성·마감·정정 이력	농가별 정산서 미리보기, 마감 검토, 정산 마감, 정정 항목 조회	마감과 정정 이력으로 이동
마감과 정정 이력	원 정산서와 원 거래, 정정 사유, 정정 전후 금액, 다음 반영 주차 확인	정정 항목 등록 또는 관련 정산서 확인
농가 이의 제기 처리	이의 제기 내용과 증빙 사진 확인, 처리 결과와 농가 안내 기록	처리 완료 또는 정정 항목 연결

농가 스마트폰 화면

화면	주요 내용	완료 조건
농가 로그인	농가 계정으로 로그인	로그인 농가와 농가 정보가 연결된다.
농가용 스마트폰 정산 조회	이번 주 판매금액, 수수료, 지급액, 입금 예정일, 정산 주차별 목록	최종 지급액을 큰 글씨로 먼저 보여 준다.
농가용 큰 글씨 정산서 상세	판매·할인·반품·폐기·정정 항목별 상세 내역	각 금액의 계산 근거를 확인할 수 있다.
이의 제기	대상 내역 선택, 내용 작성, 증빙 사진 첨부	접수 상태와 이후 처리 결과를 조회할 수 있다.

5. 정산 계산 기준

기본 계산식

농가 지급액
= 농가 정산 대상 매출
- 판매수수료
- 농가 부담 반품액
- 농가 부담 폐기·미회수 비용
- 사전 합의된 별도 공제
+ 매장 부담 할인 보전액
± 다음 정산 정정액

규칙 적용 원칙

판매일에 유효한 정산 규칙을 적용합니다.
이미 정산 마감된 주차는 이후 규칙 변경의 영향을 받지 않습니다.
농가별 예외 규칙이 품목 또는 품목군 규칙보다 우선합니다.
같은 범위와 같은 적용 기간에 충돌하는 정산 규칙은 저장할 수 없습니다.
정산 규칙이 없는 거래는 임의 계산하지 않고 오류로 처리합니다.
판매 건에는 적용된 수수료율, 할인 수수료 기준, 부담 기준, 계산 결과의 복사본을 저장합니다.
금액은 원 단위 정수로 저장합니다.
수수료 계산의 반올림 기준은 매장 설정으로 정하고 변경 이력을 남깁니다.

수수료율 적용 우선순위

우선순위	적용 범위
1	농가 × 개별 품목
2	농가 × 품목군
3	농가 전체
4	개별 품목
5	품목군
6	매장 기본 규칙

6. 정산 상태와 마감 기준

정산 주차 상태

상태	의미	가능한 작업
준비 중	정산 기간과 입금 예정일을 설정한 상태	규칙 확인, 파일 업로드
판매 원장 확인 중	계산대 판매 파일을 올리고 상품을 연결하는 상태	직접 연결, 반품·폐기 등록
오류 처리 중	규칙 누락, 미연결 항목, 대조 차이가 있는 상태	오류 해결
마감 검토 가능	오류 0건, 매출 대조 차이 0원인 상태	정산서 생성, 마감 검토
마감 완료	권한자가 정산 마감을 완료한 상태	조회와 정정 연결만 가능
다음 주 정정 반영	마감 후 오류를 다음 정산 주차에 반영하는 상태	정정 항목 생성 및 반영

정산 마감 차단 조건

아래 항목 중 하나라도 남아 있으면 정산 마감을 허용하지 않습니다.

계산대 판매 파일의 대상 기간 누락
중복 업로드 또는 중복 거래 의심
미연결 상품코드
농가 또는 품목이 연결되지 않은 판매 항목
적용할 수수료율, 할인 수수료, 반품·폐기 부담 규칙이 없는 거래
확인되지 않은 할인 판매
확인되지 않은 반품 또는 폐기 내역
매장 매출과 정산 합계의 대조 차이
정산 마감 권한이 없는 사용자 요청

7. 시스템 구성도

그림을 그리는 중…

운영자와 농가는 각각 웹 브라우저에서 서비스를 이용합니다. 서버는 로그인 권한, 계산대 판매 파일 처리, 정산 계산, 정산 마감, 파일 접근을 처리하며, 정산 데이터와 변경 기록은 분리해 저장합니다.

증빙 사진과 계산대 판매 파일은 비공개 파일 저장소에 보관합니다. 파일을 보여 주거나 내려줄 때마다 서버가 로그인과 농가·운영자 권한을 확인합니다.

8. 핵심 기능 흐름도: 계산대 판매 파일 업로드부터 정산 마감까지

그림을 그리는 중…

계산대 판매 파일을 올린 뒤 서버는 파일 오류와 중복 여부를 먼저 검사하고 판매 원장을 만듭니다. 상품코드가 연결되지 않은 항목은 정산 담당 직원이 직접 연결해야 합니다.

정산 마감 직전에도 서버가 권한, 오류 수, 매출 대조 차이를 다시 검사합니다. 따라서 화면을 우회하거나 버튼을 숨기는 방식만으로는 마감된 정산서를 변경할 수 없습니다.

9. 데이터 저장 구조

데이터	주요 저장 항목	보관 목적
운영자 계정	이름, 로그인 정보, 역할, 마감 권한, 사용 상태	정산 담당자와 마감 권한 구분
농가	농가명, 연락처, 로그인 계정 연결, 입점 상태	정산 대상과 농가 조회 권한 관리
품목군	품목군명, 사용 상태	공통 정산 규칙 적용
품목	품목명, 규격, 품목군, 출하 농가, 상품코드, 사용 상태	계산대 판매 파일 항목 연결
정산 규칙	적용 대상 농가·품목·품목군, 수수료율, 할인 수수료, 반품·폐기 부담 기준, 적용 시작일, 종료일	약정에 따른 계산 기준 관리
계산대 판매 파일	파일 식별값, 업로드 일시, 업로드 담당자, 파일 기간, 처리 결과	원본 파일 추적과 중복 업로드 방지
판매 원장	거래 고유값, 판매일시, 상품코드, 품목, 농가, 수량, 정상가, 실제 판매가, 할인·반품 여부	정산 계산 근거
상품 연결 기록	상품코드, 연결 품목, 자동·직접 연결 구분, 처리 담당자, 처리 시점	연결 결과 재사용과 변경 이력
할인 판매 기록	정상가, 할인액, 실제 판매가, 할인 부담 주체, 분담 비율, 할인 수수료 기준	할인 판매 정산 근거
반품 기록	반품일, 반품 사유, 환불액, 부담 주체	순 판매액 계산
폐기 기록	농가, 품목, 수량, 사유, 부담 주체, 사진, 처리 담당자, 농가 통지 기록	폐기·미회수 정산 근거
정산 주차	시작일, 종료일, 목요일 마감일, 입금 예정일, 상태	주간 정산 단위 관리
정산서	농가, 정산 주차, 판매액, 수수료, 공제액, 정정 금액, 지급액, 상태	농가별 정산 결과
정정 항목	원 정산서, 원 거래, 정정 사유, 정정 전후 금액, 다음 반영 주차, 처리 담당자	마감 후 오류 처리
이의 제기	농가, 대상 정산서 또는 거래, 내용, 증빙 사진, 상태, 처리 결과, 안내 기록	농가 문의와 처리 이력
변경·마감 기록	작업 유형, 대상 데이터, 담당자, 처리 시점, 변경 전후 값	변경 추적과 정산 마감 근거

10. 서버 기능과 책임

서버 기능	책임	핵심 구현 기준
로그인과 권한 확인	운영자·농가 로그인, 역할 확인, 농가별 데이터 접근 제한	모든 조회와 수정 요청에서 권한을 검사한다.
농가·품목 관리	농가, 품목군, 품목, 상품코드 등록과 수정	이미 마감된 정산에 사용된 품목 연결 정보는 변경 영향이 없게 한다.
정산 규칙 관리	수수료율, 할인 수수료, 반품·폐기 부담 기준 이력 관리	같은 적용 대상·기간의 충돌 규칙 저장을 막는다.
파일 업로드 처리	CSV 또는 엑셀 파일 검사, 원본 보관, 판매 원장 생성	실제 계산대 판매 파일 형식 확인 후 지원 범위를 정한다.
중복 거래 검사	파일과 거래의 중복 업로드 방지	파일 식별값과 거래 고유값을 함께 사용한다. 거래 고유값이 없는 경우 기준은 확인 필요다.
상품 연결 처리	상품코드 자동 연결, 직접 연결 저장, 이후 재사용	자동 연결과 직접 연결 결과를 구분해 기록한다.
정산 계산	판매일 기준 규칙 적용, 지급액 계산, 계산 근거 보관	마감된 판매 건의 계산 결과를 다시 계산하지 않는다.
대조 처리	매장 매출, 수수료, 할인, 반품, 폐기, 지급액의 차이 원인 계산	대조 차이 0원 여부를 서버가 판단한다.
정산 마감	마감 조건 검사, 상태 변경, 잠금, 담당자 기록	오류가 하나라도 있으면 마감 완료 상태로 변경할 수 없다.
정정 처리	마감 후 오류를 다음 정산 주차에 정정 항목으로 생성	원 정산서와 원 거래를 수정하지 않는다.
농가 이의 제기 처리	증빙 저장, 처리 상태·결과·안내 기록	농가는 본인의 정산서와 거래에 대해서만 이의 제기할 수 있다.
파일 제한 접근	증빙 사진, 정산서 내려받기 파일 보호	공개 주소를 사용하지 않고 요청 시 권한을 확인한다.

11. 기술 구성 제안

구분	선택	선택 이유	운영 시 주의점
사용자 화면과 서버	Next.js	운영자 화면과 농가용 스마트폰 화면을 하나의 웹 서비스로 만들기 쉽다.	화면 권한 처리와 서버 권한 처리를 분리하지 말고 서버를 최종 기준으로 둔다.
데이터 저장소	관계형 데이터베이스	농가, 품목, 판매 원장, 정산 규칙, 정산서, 정정 항목의 연결 관계를 안정적으로 관리하기 좋다.	정산서·판매 원장·규칙 간 참조 관계를 삭제로 끊지 않도록 한다.
파일 저장소	비공개 객체 저장소	계산대 판매 파일과 증빙 사진을 안전하게 저장한다.	공개 링크를 만들지 않고 제한된 시간만 접근 가능한 주소를 발급한다.
로그인	역할 기반 로그인	정산 담당자, 마감 권한자, 농가의 접근 범위를 나눈다.	농가 조회 요청마다 농가 식별값과 정산서 소유 관계를 검사한다.
변경 기록	변경·마감 기록 테이블	엑셀처럼 나중에 누가 무엇을 바꿨는지 모르는 문제를 막는다.	로그인, 규칙 변경, 파일 업로드, 직접 연결, 반품·폐기, 마감, 정정 작업을 자동 기록한다.
시간 기준	한국 시간 기준	판매일, 적용 시작일, 정산 주차, 목요일 마감 시각을 일관되게 처리한다.	서버와 데이터베이스의 시간대 설정을 한국 시간 기준으로 통일한다.

12. 보안과 데이터 보호 기준

접근 제한

농가는 본인 농가에 연결된 정산서, 판매 내역, 이의 제기, 증빙만 조회할 수 있어야 합니다.
주소의 정산서 번호나 파일 번호를 바꿔도 다른 농가의 정보가 보이면 안 됩니다.
정산 담당 직원은 정산 처리 기능을 사용할 수 있지만, 마감 권한은 점장 또는 마감 권한을 가진 운영자에게만 부여합니다.
마감된 정산 주차의 판매 원장, 정산 규칙 적용 결과, 정산서는 서버에서 수정 요청을 거부해야 합니다.

기록 보존

규칙을 수정할 때 기존 값을 덮어쓰지 않고 종료일을 설정한 뒤 새 규칙을 등록합니다.
판매 건에는 계산 당시 적용한 정산 규칙과 계산 결과를 복사해 보관합니다.
정정 항목은 원 정산서와 원 거래를 참조하되, 원 데이터를 변경하지 않는 별도 기록으로 저장합니다.
파일 업로드, 직접 상품 연결, 정산 마감, 이의 제기 처리 등 주요 작업에 담당자와 처리 시점을 남깁니다.

확인 필요

판매·정산 정보, 농가 연락처, 계좌 정보의 보관 기간
농가 로그인 첫 비밀번호 발급과 비밀번호 복구 방식
계산대 판매 파일에 거래 고유값이 없을 때의 중복 판별 기준
CSV와 엑셀 중 실제 계산대 판매 파일 형식
지급 완료 여부를 서비스에 표시할지 여부
세무·회계·개인정보 관련 보관 및 처리 기준

13. 첫 시범 운영 완료 기준

첫 로컬푸드 직매장에서 실제 한 주의 계산대 판매 파일을 사용해 아래 조건을 모두 만족하면 시범 운영의 핵심 목표를 달성한 것으로 봅니다.

계산대 판매 파일을 업로드할 수 있다.
판매 원장의 모든 판매 항목이 농가와 품목에 연결된다.
수수료율, 할인 수수료, 반품·폐기 부담 기준이 판매일 기준으로 적용된다.
정산 규칙이 없는 거래는 오류로 표시되고 임의 계산되지 않는다.
농가별 판매액, 수수료, 반품·폐기 공제액, 정정 금액, 지급액이 정산서에 표시된다.
매장 매출과 농가별 정산 계산 항목의 대조 차이가 0원이 된다.
오류가 남아 있으면 정산 마감이 차단된다.
점장 또는 마감 권한을 가진 운영자가 목요일에 정산 마감할 수 있다.
마감 후 기존 정산서와 판매 내역을 수정할 수 없다.
마감 후 발견된 오류를 다음 정산 주차의 정정 항목으로 연결할 수 있다.
농가가 스마트폰에서 본인 정산서, 지급액, 입금 예정일과 세부 내역을 확인할 수 있다.
농가가 이의 제기와 증빙 사진을 제출하고, 운영자가 처리 결과와 농가 안내 기록을 남길 수 있다.