로컬푸드 직매장 정산 자동화 서비스 전체 개발 안내서

1. 서비스 개요

한 줄 설명

약 30개 농가 상품을 위탁 판매하는 비수도권 로컬푸드 직매장이 계산대 판매 파일과 농가·품목별 정산 규칙으로 주간 정산서를 만들고 목요일에 마감하며, 농가는 스마트폰에서 본인 정산 내역을 확인하는 웹 서비스입니다.

첫 도입 대상

비수도권 로컬푸드 직매장 1곳
입점 농가 약 30곳
매주 목요일 정산 마감
다음 주 월요일 입금 예정
계산대에서는 바코드를 사용하지만 농가별 정산은 종이와 엑셀로 처리하는 매장

제공 형태

Next.js 기반 웹 서비스
운영자·정산 담당자: PC 화면 중심
농가: 스마트폰 웹 화면 중심
모바일 앱 설치나 앱 스토어 등록은 하지 않음
첫 버전에서는 매장 1곳만 운영

2. 핵심 고객과 역할

사용자	주요 역할	반드시 끝내야 하는 일
정산 담당자	기초 정보와 거래를 관리하고 오류를 처리	계산대 판매 파일을 올리고 모든 판매 항목과 정산 규칙을 연결해 마감 가능한 상태로 만듦
점장·마감 권한자	최종 검토 및 정산 마감	매장 매출과 정산 합계를 확인하고 목요일에 정산을 마감
운영자	계정과 매장 운영 기준 관리	담당자 권한, 농가 계정, 정산 주차와 주요 설정을 관리
농가	본인 정산 조회 및 이의 제기	이번 주 판매금액, 수수료, 지급액, 입금 예정일을 확인하고 필요하면 증빙 사진과 함께 이의를 제기

권한 원칙

정산 담당자는 판매 파일, 거래 내역, 정산 규칙과 오류를 처리할 수 있습니다.
마감 권한이 있는 점장만 정산을 최종 마감할 수 있습니다.
농가는 본인에게 연결된 정산서와 증빙만 볼 수 있습니다.
농가가 주소의 정산서 번호를 바꾸더라도 다른 농가 자료에 접근할 수 없어야 합니다.
마감된 정산서는 화면뿐 아니라 서버에서도 수정 요청을 거부해야 합니다.

3. 해결할 문제

현재 업무

계산대에서 상품 바코드를 찍습니다.
농가·품목별 정산 정보는 종이나 별도 엑셀에 정리합니다.
품목과 농가별 수수료율을 찾아 수작업으로 계산합니다.
할인 판매, 반품, 폐기 내용을 별도로 확인합니다.
농가별 정산금액과 매장 매출을 직접 대조합니다.
목요일에 정산서를 확정하고 다음 주 월요일에 입금합니다.

발생하는 문제

종이 내용을 엑셀로 옮길 때 판매 누락이나 잘못된 입력이 발생할 수 있습니다.
채소, 가공식품, 계란 등 품목마다 수수료율이 다릅니다.
같은 품목도 농가별 약정에 따라 다른 수수료율이 적용될 수 있습니다.
할인 판매의 수수료를 할인 전 금액으로 계산할지 할인 후 금액으로 계산할지 약정이 다릅니다.
미회수 재고를 폐기했을 때 농가와 매장 중 누가 손해를 부담할지 다릅니다.
엑셀은 마감 후에도 수정할 수 있어 변경 사실을 확인하기 어렵습니다.
농가가 금액을 문의하면 정산 담당자가 다시 자료를 찾아 설명해야 합니다.

4. 사용자가 달성할 목표

정산 담당자 목표

계산대 판매 파일을 한 번 올립니다.
등록된 상품코드는 자동으로 농가와 품목에 연결합니다.
처음 보는 상품코드만 직접 연결합니다.
정산 규칙이 빠진 항목과 합계 불일치만 골라 처리합니다.
농가별 정산서를 자동으로 생성합니다.

점장 목표

마감 전에 아래 항목을 한 화면에서 확인합니다.
- 미연결 상품 수
- 규칙 미설정 거래 수
- 확인되지 않은 할인·반품·폐기 수
- 중복 가능성이 있는 거래 수
- 매장 매출 대조 차이
모든 오류가 해결된 경우에만 목요일 정산을 마감합니다.
마감 이후 원 정산서가 변경되지 않았음을 확인할 수 있습니다.

농가 목표

스마트폰 첫 화면에서 아래 내용을 바로 확인합니다.

이번 주 판매금액
수수료
받을 금액
입금 예정일

필요한 경우 판매·할인·반품·폐기·정정 항목을 열어 보고 이의를 제기합니다.

5. 첫 개발 범위

반드시 포함

운영자 로그인과 권한 관리
농가 계정 발급·중지 및 농가 정보 연결
농가·품목·품목군·상품코드 관리
수수료율과 적용 시작일 관리
할인 수수료 기준 관리
반품·폐기 부담 규칙 관리
계산대 판매 파일 업로드
상품코드 자동 연결과 처음 보는 코드의 직접 연결
판매·할인·반품·폐기 내역 확인
농가별 정산 금액 계산
오류 목록과 매장 매출 합계 대조
오류가 남은 정산의 마감 차단
농가별 정산서 생성
정산 마감과 수정 불가 잠금
다음 정산의 정정 항목 처리
농가용 큰 글씨 정산 조회
농가 이의 제기와 증빙 사진 제출
운영자의 이의 처리 기록
농가 정산서 내려받기
정산 주차와 입금 예정일 설정

첫 버전에서 제외

실제 은행 이체
은행 이체용 지급 파일 생성
여러 로컬푸드 직매장 통합 운영
외부 계산대와 실시간 자동 연결
처음 보는 상품을 자동으로 추정해 연결하는 기능
문자나 카카오톡 알림
모바일 앱 설치 및 앱 스토어 배포

농가 정산서 내려받기는 포함하되, 은행 이체용 파일은 포함하지 않습니다.

6. 전체 이용 순서

6.1 최초 설정

운영자 로그인
→ 담당자 계정과 권한 등록
→ 농가 정보와 농가 로그인 계정 등록
→ 품목군·품목·상품코드 등록
→ 수수료율과 적용 시작일 등록
→ 할인 수수료 기준 등록
→ 반품·폐기 부담 규칙 등록
→ 정산 주차와 입금 예정일 설정

최초 설정 완료 조건

모든 입점 농가가 등록되어 있습니다.
계산대 판매 파일에 나오는 기존 상품코드가 품목과 농가에 연결되어 있습니다.
정산 대상 품목마다 적용 가능한 수수료 규칙이 있습니다.
할인 판매, 반품, 폐기 규칙은 확정된 약정만 등록되어 있습니다.
수수료 계산의 원 단위 처리 기준이 설정되어 있습니다.
정산 담당자와 마감 권한자가 구분되어 있습니다.

6.2 매주 정산 순서

정산 주차 확인
→ 계산대 판매 파일 업로드
→ 파일 형식 및 중복 검사
→ 상품코드 자동 연결
→ 처음 보는 상품코드 직접 연결
→ 판매·할인·반품·폐기 확인
→ 정산 규칙 적용 및 금액 계산
→ 오류 목록 처리
→ 매장 매출 합계 대조
→ 농가별 정산서 생성
→ 점장 검토
→ 목요일 정산 마감
→ 농가 스마트폰 조회

마감 후 오류 처리

마감된 정산에서 오류 발견
→ 원 정산서와 원 거래 선택
→ 정정 사유와 정정 전후 금액 등록
→ 다음 미마감 정산 주차에 정정 항목 연결
→ 다음 정산서에서 별도 항목으로 표시
→ 다음 정산 마감 시 함께 확정

마감된 원 정산서의 판매액, 수수료와 지급액은 변경하지 않습니다.

7. 주요 화면 안내

7.1 운영자 화면

화면	사용 목적	주요 내용	완료 조건
`[operator-login]` 운영자 로그인과 권한 관리	운영자와 담당자의 접근 권한 관리	로그인, 담당자 계정 등록, 역할 지정, 마감 권한 부여·회수	로그인한 사용자에게 허용된 메뉴만 표시되고 서버에서도 권한을 검사
`[settlement-dashboard]` 주간 정산 현황	이번 주 마감 상태와 다음 작업 확인	정산 기간, 입금 예정일, 파일 처리 상태, 미연결 상품 수, 오류 수, 대조 차이, 마감 가능 여부	마감에 필요한 모든 상태가 한 화면에 표시됨
`[farm-product-rules]` 농가·품목·정산 규칙 관리	정산 계산에 사용할 기초 정보 관리	농가, 품목군, 품목, 상품코드, 수수료율, 할인 수수료 기준, 반품·폐기 부담 규칙	적용 대상과 적용 기간이 겹치는 규칙 충돌을 방지
`[sales-upload-mapping]` 계산대 판매 파일 업로드와 상품 연결	판매 내역을 판매 원장으로 가져오기	파일 업로드, 미리보기, 오류 검사, 자동 연결, 처음 보는 코드 직접 연결	모든 유효 거래가 업로드되고 미연결 상품을 확인할 수 있음
`[transaction-history]` 판매·할인·반품·폐기 내역 확인	정산의 근거가 되는 거래 확인	판매, 할인, 반품, 폐기, 미회수 재고, 처리 담당자와 시점	확인되지 않은 할인·반품·폐기 항목이 0건
`[reconciliation-errors]` 오류 목록과 매장 매출 합계 대조	마감 전 오류 처리	미연결 거래, 규칙 누락, 중복 가능성, 금액 오류, 대조 차이	모든 차단 오류가 0건이고 대조 차이가 0원
`[settlement-close]` 농가별 정산서 생성·마감	정산서 생성과 최종 마감	농가별 판매액, 수수료, 차감, 정정 금액, 지급액, 마감 버튼	마감 권한자가 검토 후 마감하고 해당 주차가 잠김
`[correction-history]` 마감과 정정 이력	원 정산서와 이후 정정을 연결해 확인	원 정산 주차, 원 거래, 정정 전후 금액, 사유, 담당자, 반영 주차	모든 정정 항목이 원 정산서와 연결됨
`[dispute-management]` 농가 이의 제기 처리	농가 문의와 증빙을 처리	대상 정산서, 대상 내역, 사진, 처리 상태, 결과, 담당자, 처리일, 통지 기록	처리 결과와 농가에 알린 날짜·방법까지 저장됨

7.2 농가 스마트폰 화면

농가용 화면은 하나의 스마트폰 웹 영역 안에서 아래 화면으로 구성합니다.

화면	사용 목적	주요 내용	완료 조건
`[farmer-login]` 농가 로그인	본인 계정으로 접근	아이디, 비밀번호, 로그인	로그인한 농가와 연결된 자료만 접근 가능
`[farmer-settlement]` 농가 정산 첫 화면	이번 주 핵심 금액 확인	판매금액, 수수료, 지급액, 입금 예정일, 과거 정산 주차	지급액이 가장 먼저 큰 글씨로 표시됨
`[farmer-settlement-view]` 정산 상세	지급액 계산 근거 확인	상품별 판매, 수수료율, 할인, 반품, 폐기, 정정 항목	합계 항목에서 관련 세부 거래로 이동 가능
`[screen1]` 큰 글씨 조회와 이의 제기	정산 확인 후 문의 제출	정산서 내려받기, 대상 내역 선택, 문의 내용, 증빙 사진	이의 제기 접수 결과가 화면에 표시됨

농가 첫 화면 권장 배치

2026년 8월 4주차
입금 예정일: 2026년 8월 31일

받을 금액
213,200원

이번 주 판매금액       245,000원
수수료                  23,800원
반품·폐기 차감            3,000원
지난 정산 정정            2,000원

[정산 상세 보기]
[판매 내역]
[할인·반품·폐기]
[이의 제기]
[정산서 내려받기]

8. 기능별 구현 기준

8.1 농가·품목 정보 관리

농가 정보

농가명
대표 연락처
입점 상태
농가 로그인 계정
적용 중인 약정 규칙
내부 관리 메모

첫 버전에서 은행 이체를 하지 않으므로 계좌 정보는 필수 항목으로 두지 않습니다.

품목 정보

품목명
품목군
규격·포장 단위
출하 농가
상품코드
사용 상태
계산대 판매 파일에 표시되는 품목명

하나의 상품코드는 한 시점에 하나의 농가와 품목에 연결되어야 합니다.

8.2 정산 규칙 관리

수수료 규칙 필수 항목

규칙 이름
적용 농가
적용 품목 또는 품목군
수수료율
적용 시작일
적용 종료일
할인 수수료 기준
- 할인 전 금액
- 할인 후 금액
확정 상태
변경 사유
등록자와 등록 시점

규칙 적용 우선순위

아래 순서는 구현을 위한 가정입니다. 실제 약정 정리 시 최종 확인이 필요합니다.

농가와 개별 품목에 지정된 규칙
농가와 품목군에 지정된 규칙
농가 전체에 지정된 규칙
개별 품목 규칙
품목군 규칙
매장 공통 규칙

가장 구체적인 규칙 하나만 적용하고 여러 수수료율을 더하지 않습니다.

규칙 변경 원칙

적용 중인 규칙을 덮어쓰지 않습니다.
기존 규칙에 종료일을 설정하고 새 규칙을 추가합니다.
새 규칙은 적용 시작일 이후의 미마감 거래에만 적용합니다.
이미 마감된 정산은 다시 계산하지 않습니다.
같은 적용 범위와 기간에 활성 규칙이 겹치면 저장을 차단합니다.
규칙이 없으면 임의의 기본 수수료를 적용하지 않고 오류로 처리합니다.

8.3 할인 판매 처리

할인 판매 건에는 다음 정보를 저장합니다.

농가와 품목
할인 유형
정상 판매가
할인액
할인 후 실제 판매가
할인 결정자
농가 부담 비율
매장 부담 비율
할인 수수료 기준
적용된 정산 규칙
처리 담당자와 시점

수수료 계산 예시

정상가 10,000원, 할인 후 실제 판매가 8,000원, 수수료율 10%인 경우입니다.

할인 수수료 기준	수수료
할인 전 금액 기준	1,000원
할인 후 금액 기준	800원

할인 부담 주체가 매장인 경우에는 농가 지급액에 매장 부담 할인 보전액을 별도 가산 항목으로 표시합니다.

8.4 반품·폐기·미회수 재고 처리

구분

종류	의미
반품	판매된 상품이 소비자에게 환불됨
회수	팔리지 않은 상품을 농가가 가져감
미회수 재고	회수 기한까지 농가가 가져가지 않음
폐기	기한 경과, 품질 저하, 파손 등의 이유로 처분
매장 과실	냉장·보관·진열 문제 등으로 손실 발생

필수 입력 정보

농가
품목
수량
처리 유형
처리 사유
정산에 반영할 기준 금액
부담 주체
- 농가
- 매장
- 공동 부담
공동 부담 비율
증빙 사진
처리 담당자
처리 시점
농가에 알린 날짜
농가에 알린 방법

사진은 약정에 따라 선택 또는 필수로 설정할 수 있습니다. 농가 부담 폐기의 경우 통지 기록이 없으면 경고를 표시합니다.

폐기 금액 처리

폐기 손해를 계산할 기준 금액은 약정 확인이 필요합니다. 첫 버전에서는 다음 방식으로 처리합니다.

운영자가 폐기 기록에 약정상 기준 금액을 입력합니다.
시스템이 등록된 부담 비율을 적용합니다.
농가 부담액만 해당 농가 정산서에서 차감합니다.
마감 전에는 권한자가 수정할 수 있습니다.
마감 후에는 원 기록을 수정하지 않고 정정 항목을 만듭니다.

8.5 계산대 판매 파일 업로드

첫 버전 지원 원칙

첫 매장에서 실제 사용하는 계산대 판매 파일 형식 1개를 우선 지원합니다.
실제 파일 확인 후 CSV 또는 엑셀 형식을 결정합니다.
파일의 상품코드가 등록 품목과 일치하면 자동 연결합니다.
처음 보는 상품코드는 운영자가 직접 농가와 품목에 연결합니다.
운영자가 확정한 연결은 이후 같은 상품코드에 다시 사용합니다.

업로드 검사 항목

필수 열 존재 여부
판매일시 형식
상품코드 존재 여부
판매 수량과 금액 형식
금액 쉼표와 빈 셀
취소·반품 등 음수 거래
대상 정산 기간 포함 여부
동일 파일 중복 업로드 여부
동일 거래 중복 여부
이미 마감된 기간의 거래 포함 여부

중복 방지

원본 파일의 식별값을 저장합니다.
거래번호가 있으면 거래번호를 중복 판별에 사용합니다.
거래번호가 없다면 판매일시, 상품코드, 수량, 금액 등의 조합을 사용해야 합니다.
거래번호가 없는 실제 파일의 최종 중복 판별 기준은 확인 필요입니다.

8.6 상품 연결

각 연결에는 아래 내용을 기록합니다.

계산대 판매 파일의 원래 상품코드
연결된 농가
연결된 품목
자동 연결 또는 운영자 직접 연결 여부
연결한 담당자
연결 시점
변경 전후 내용

미연결 상품이 한 건이라도 있으면 정산 마감을 차단합니다.

8.7 정산 금액 계산

금액 저장 원칙

모든 금액은 원 단위 정수로 저장합니다.
소수점 금액을 저장하지 않습니다.
수수료율은 소수 계산 오차가 없도록 0.01% 단위 정수로 저장할 수 있습니다.
- 10.00%는 1000으로 저장
- 15.00%는 1500으로 저장
반올림, 올림 또는 버림 기준은 매장 설정으로 고정합니다.
수수료를 거래 건별로 계산할지 농가 주간 합계로 계산할지는 기존 엑셀 방식 확인이 필요합니다.

기본 계산 구조

순 판매액
= 할인 후 실제 판매금액
- 소비자 반품·취소 금액

현재 주차 농가 지급액
= 순 판매액
+ 매장 부담 할인 보전액
- 수수료
- 농가 부담 폐기·미회수 비용
- 그 밖의 확정된 농가 부담 금액

최종 지급액
= 현재 주차 농가 지급액
± 이전 정산의 정정 항목

소비자 반품이 이미 계산대 판매 파일에서 음수 거래로 반영되었다면 같은 금액을 다시 차감하지 않습니다.

계산 결과 복사본 보관

판매 건마다 다음 내용을 보관합니다.

적용한 규칙 번호
적용 당시 수수료율
할인 수수료 기준
부담 주체와 부담 비율
계산 전 금액
수수료 금액
최종 정산 반영 금액

이후 규칙이 바뀌어도 마감된 거래 계산 결과가 변하지 않아야 합니다.

8.8 매장 매출과 정산 합계 대조

농가 지급액만 매장 매출과 바로 비교하면 수수료와 조정 항목 때문에 차이가 발생합니다. 화면에서는 차이의 원인을 항목별로 보여줘야 합니다.

대조 기준

계산대 순 판매액
= 현재 주차 농가 지급액
+ 수수료
+ 농가 부담 폐기·미회수 금액
- 매장 부담 할인 보전액

이전 주차의 정정 항목은 현재 계산대 매출과 섞지 않고 별도 영역에 표시합니다.

마감 차단 조건

다음 중 하나라도 존재하면 마감할 수 없습니다.

계산대 판매 파일이 없음
미연결 상품이 있음
농가가 연결되지 않은 거래가 있음
적용할 수수료 규칙이 없음
할인 수수료 기준이 없음
확인되지 않은 반품·폐기 내역이 있음
부담 주체가 정해지지 않은 내역이 있음
중복 가능성이 해결되지 않음
매장 매출 대조 차이가 0원이 아님
농가별 정산서 생성이 완료되지 않음

8.9 정산서 생성과 마감

정산 상태

준비 중
→ 파일 반영
→ 오류 확인 중
→ 마감 가능
→ 마감 완료

오류가 남아 있으면 오류 확인 중 상태입니다.
모든 차단 항목이 해결되고 대조 차이가 0원이면 마감 가능 상태가 됩니다.
마감 권한자가 마감하면 마감 완료가 됩니다.
마감 완료 상태에서 이전 상태로 돌아갈 수 없습니다.

마감 처리 기준

마감 버튼을 누르면 서버에서 다시 아래 항목을 검사합니다.

사용자의 마감 권한
정산 주차 상태
미연결 거래 수
규칙 미설정 거래 수
미확정 반품·폐기 수
중복 거래 수
매출 대조 차이
농가별 정산서 생성 여부

모두 정상일 때 하나의 작업으로 다음 내용을 확정합니다.

농가별 정산서
판매·수수료·지급액
적용 규칙의 복사본
대조 결과
마감자
마감 시점
잠금 상태

중간에 오류가 발생하면 일부 농가만 마감된 상태가 남지 않도록 전체 처리를 취소합니다.

8.10 마감 후 정정

정정 항목 필수 정보

원 정산 주차
원 정산서
원 거래
정정 사유
정정 전 금액
정정 후 금액
농가 지급액 차이
등록 담당자
등록 시점
반영할 다음 정산 주차

정정 원칙

원 정산서를 수정하지 않습니다.
원 거래를 삭제하거나 덮어쓰지 않습니다.
정정 금액은 다음 미마감 정산서에 별도 항목으로 표시합니다.
다음 주차가 이미 마감되었다면 그다음 미마감 주차에 반영합니다.
정정 담당자와 처리 시점을 자동으로 기록합니다.
농가 정산서에는 원 정산 주차와 정정 사유를 보여 줍니다.

8.11 농가 이의 제기

농가 입력 항목

대상 정산 주차
대상 판매·할인·반품·폐기·정정 내역
이의 제기 내용
증빙 사진
원하는 연락 방법

처리 상태

접수
→ 확인 중
→ 처리 완료

운영자 기록 항목

처리 상태
처리 담당자
처리 결과
처리일
농가에 알린 날짜
농가에 알린 방법
관련 정정 항목

이의 제기가 접수되더라도 마감된 정산서는 변경하지 않습니다. 금액 수정이 필요하면 정정 항목을 만들어 다음 정산에 반영합니다.

첫 버전에서는 별도 알림을 보내지 않습니다. 농가는 스마트폰 화면에서 처리 상태를 확인합니다.

9. 핵심 데이터 구조

구분	주요 항목
매장 설정	매장명, 한국 시간대, 기본 정산 요일, 입금 예정일, 수수료 원 단위 처리 기준
사용자	이름, 로그인 정보, 역할, 사용 상태, 마지막 로그인
농가	농가명, 연락처, 입점 상태, 연결된 농가 계정
품목군	채소, 과일, 계란, 가공식품 등
품목	품목명, 규격, 품목군, 출하 농가, 사용 상태
상품코드 연결	원 상품코드, 품목, 농가, 연결 방식, 연결 담당자
정산 규칙	규칙 종류, 적용 범위, 수수료율, 부담 기준, 적용 시작일·종료일, 확정 상태
정산 주차	시작일, 종료일, 마감 예정일, 입금 예정일, 상태
파일 업로드	원본 파일명, 파일 식별값, 업로드 담당자, 업로드 시점, 처리 결과
판매 원장	거래번호, 판매일시, 상품코드, 농가, 품목, 수량, 정상가, 실제 판매가, 거래 종류
할인 기록	할인 유형, 정상가, 할인액, 실제 판매가, 부담 주체, 수수료 기준
반품 기록	원 판매 거래, 반품일, 수량, 환불액, 사유, 부담 주체
폐기·미회수 기록	농가, 품목, 수량, 기준 금액, 사유, 부담 주체, 증빙, 통지 기록
농가별 정산서	정산 주차, 농가, 판매액, 수수료, 차감액, 정정액, 지급액, 상태
정산 상세 항목	원 거래, 적용 규칙, 계산 전후 금액, 정산서 연결
정정 항목	원 정산서, 원 거래, 정정 전후 금액, 사유, 반영 주차
이의 제기	농가, 대상 내역, 내용, 상태, 처리 결과, 담당자, 안내 기록
작업 기록	로그인, 규칙 변경, 업로드, 직접 연결, 거래 등록, 마감, 정정 작업의 담당자와 시점

10. 변경 방지와 작업 기록

다음 작업은 담당자와 처리 시점을 자동 기록합니다.

로그인
계정과 권한 변경
농가·품목 등록
정산 규칙 등록·변경
계산대 판매 파일 업로드
상품 직접 연결
할인·반품·폐기 등록
오류 처리
정산서 생성
마감
정정 등록
이의 제기 처리

마감 데이터 보호

화면에서 수정 버튼만 숨기는 방식으로 구현하지 않습니다.
마감 상태를 서버에서 매번 검사합니다.
마감된 거래, 정산서와 적용 규칙의 변경 요청을 서버에서 거부합니다.
마감된 기간에 새로운 판매 파일이 올라오면 기존 정산에 추가하지 않고 정정 대상으로 안내합니다.
작업 기록은 기존 기록을 수정하지 않고 새 기록을 추가하는 방식으로 보관합니다.

11. 기술 구현 방향

11.1 권장 구성

화면과 서버: Next.js, TypeScript
데이터베이스: 금액·거래·권한 관계를 안정적으로 관리할 수 있는 관계형 데이터베이스
파일 저장:
- 계산대 판매 원본 파일
- 증빙 사진
- 농가 정산서 내려받기 파일
파일 해석:
- 실제 계산대 판매 파일에 맞춘 CSV 또는 엑셀 처리
시간 기준:
- 모든 판매일시와 마감 시각은 한국 시간 기준
화면 구성:
- 운영자 화면은 PC에 맞춤
- 농가 화면은 스마트폰에 맞춘 반응형 웹

11.2 서버 작업 단위

다음 작업은 화면에서 직접 금액을 확정하지 않고 서버에서 처리합니다.

판매 파일 검증과 저장
상품코드 연결
적용 규칙 결정
수수료 계산
오류 수 계산
매장 매출 대조
농가별 정산서 생성
정산 마감
정정 항목 반영
농가별 접근 권한 검사

11.3 파일 보안

증빙 사진과 정산서 파일을 누구나 접근할 수 있는 공개 주소로 저장하지 않습니다.
로그인과 접근 권한을 확인한 후에만 파일을 제공합니다.
농가 정산서 내려받기 요청에서도 해당 농가 본인인지 다시 확인합니다.
허용할 사진 형식과 파일 크기 제한은 운영 환경 확정 시 정합니다.

12. 오류 표시 기준

마감을 막는 오류

미연결 상품
농가 미연결
품목 미연결
수수료 규칙 없음
할인 수수료 기준 없음
부담 주체 미확정
중복 거래 미해결
판매 파일 금액 오류
매출 대조 차이
마감된 기간에 포함된 신규 거래

경고만 표시할 수 있는 항목

폐기 사진 미첨부
농가 통지 기록 미입력
품목명 오타 가능성
농가 계정 미발급
이의 제기 미처리

폐기 사진과 농가 통지 기록을 마감 차단 조건으로 사용할지는 실제 약정 기준 확인이 필요합니다.

오류 표시 방식

오류는 건수뿐 아니라 영향을 받는 금액도 보여 줍니다.

수수료 규칙 미설정
3건 / 판매금액 42,000원

미연결 상품
2건 / 판매금액 18,000원

매출 대조 차이
5,000원

13. 화면 디자인 기준

운영자 화면

대시보드 상단에 마감 가능, 확인 필요, 마감 불가를 크게 표시합니다.
오류를 누르면 해당 거래 목록으로 바로 이동합니다.
마감 버튼 옆에 마감을 막는 이유를 표시합니다.
농가별 예외 규칙은 농가별 약정 적용으로 표시합니다.
금액은 천 단위 쉼표와 원을 함께 표시합니다.

농가 화면

최종 지급액을 화면의 첫 번째 정보로 표시합니다.
주요 금액은 큰 글씨와 높은 명암으로 표시합니다.
전문적인 회계 표현보다 다음 용어를 사용합니다.
- 판매금액
- 수수료
- 반품·폐기 차감
- 정정 금액
- 받을 금액
- 입금 예정일
버튼은 한 줄에 너무 많이 배치하지 않습니다.
정산 합계를 누르면 관련 상품과 거래 내역을 보여 줍니다.
농가가 확대하지 않아도 읽을 수 있는 크기로 작성합니다.

14. 개발 순서

1단계: 기초 구조와 접근 권한

매장 1곳 설정
운영자 로그인
정산 담당자와 마감 권한 구분
농가 로그인
농가가 본인 자료만 조회하는 권한 검사
작업 기록 저장

2단계: 농가·품목·규칙 관리

농가 등록
품목군과 품목 등록
상품코드 연결
수수료율과 적용 기간
할인 수수료 기준
반품·폐기 부담 규칙
규칙 기간 충돌 검사

3단계: 판매 파일과 판매 원장

실제 계산대 판매 파일 처리
파일 미리보기와 형식 검사
중복 업로드 방지
상품코드 자동 연결
처음 보는 코드 직접 연결
판매·할인·반품·폐기 내역 화면

4단계: 정산 계산과 대조

농가별 판매액 계산
수수료 계산
반품·폐기 차감
매장 부담 할인 보전
매장 매출 대조
차단 오류 관리
농가별 정산서 생성

5단계: 마감과 정정

마감 권한 검사
마감 전 최종 재검사
마감된 정산 잠금
마감자와 시점 기록
원 정산서를 유지하는 정정 항목
다음 정산서 반영

6단계: 농가 화면과 이의 제기

농가 큰 글씨 정산 첫 화면
상품별 상세 내역
정산서 내려받기
이의 제기와 증빙 사진
운영자 이의 처리
처리 결과 조회

7단계: 실제 매장 검증

실제 한 주 계산대 판매 파일 업로드
기존 엑셀 정산과 결과 비교
차이 원인 분류
목요일 마감 시험
다음 정산의 정정 반영 시험
농가 계정으로 본인 정산 조회 시험

15. 필수 시험 시나리오

시험 상황	기대 결과
채소에 10% 수수료율 적용	해당 판매 건과 정산서에 10% 규칙과 수수료가 표시됨
가공식품에 15% 적용	채소 규칙이 아닌 가공식품 규칙이 적용됨
특정 농가의 계란 예외 적용	일반 계란 규칙보다 농가별 약정이 적용됨
할인 전 금액 기준	정상 판매가를 기준으로 수수료 계산
할인 후 금액 기준	실제 판매가를 기준으로 수수료 계산
농가 부담 폐기	농가 지급액에서 약정 금액 차감
매장 부담 폐기	농가 지급액에서 차감하지 않음
처음 보는 상품코드	자동 연결하지 않고 운영자 확인 요청
동일 파일 재업로드	중복 업로드를 거부하거나 중복 사실을 명확히 표시
규칙이 없는 거래	임의 계산하지 않고 마감 차단
대조 차이가 1원이라도 존재	마감 차단
권한 없는 담당자가 마감 시도	서버에서 거부
정산 마감 후 수정 시도	화면과 서버 모두 거부
마감 후 판매 누락 발견	원 정산을 바꾸지 않고 다음 정산의 정정 항목으로 처리
농가가 다른 정산서 주소로 접근	접근 거부
농가가 사진과 함께 이의 제기	운영자 화면에 접수되고 처리 기록 저장
농가가 정산서를 내려받음	본인 정산서만 내려받을 수 있음

16. 첫 개발 완료 기준

기능 완료

실제 계산대 판매 파일을 업로드할 수 있습니다.
등록된 상품코드는 자동 연결됩니다.
처음 보는 상품코드는 운영자가 직접 연결할 수 있습니다.
농가·품목별 수수료율과 할인 수수료 기준을 적용할 수 있습니다.
반품·폐기 부담 주체와 금액을 정산에 반영할 수 있습니다.
농가별 판매금액, 수수료와 지급액이 자동 계산됩니다.
농가별 정산서가 생성됩니다.
농가가 스마트폰으로 본인 정산서를 확인하고 내려받을 수 있습니다.
농가가 이의를 제기하고 증빙 사진을 제출할 수 있습니다.

정산 정확성 완료

모든 유효 판매 거래가 농가와 품목에 연결됩니다.
규칙이 없는 거래는 계산에서 숨기지 않고 오류로 표시됩니다.
매장 매출 대조 차이가 0원일 때만 마감할 수 있습니다.
기존 엑셀 정산과 비교한 차이를 거래 단위로 설명할 수 있습니다.
할인, 반품, 폐기와 정정 금액이 중복 차감되지 않습니다.

마감 완료

마감 권한자만 마감할 수 있습니다.
오류가 한 건이라도 남으면 마감할 수 없습니다.
마감된 정산서는 수정할 수 없습니다.
마감된 정산의 적용 규칙과 계산 결과가 보존됩니다.
마감자와 마감 시점이 기록됩니다.
마감 후 오류는 다음 정산의 정정 항목으로만 처리됩니다.

접근 권한 완료

농가는 본인 정산서만 볼 수 있습니다.
운영자 권한과 마감 권한이 구분됩니다.
증빙 사진과 정산서 파일은 권한 확인 후 제공됩니다.
주요 작업의 담당자와 처리 시점이 기록됩니다.

현장 검증 완료

실제 한 주 판매 파일로 정산을 완료합니다.
목요일 마감을 실제 순서대로 시험합니다.
한 건 이상의 가상 정정 항목을 다음 주차에 반영합니다.
농가 계정으로 지급액, 입금 예정일과 상세 내역을 확인합니다.
농가 이의 제기부터 운영자 처리 완료까지 시험합니다.

17. 개발 시작 전 확인 필요 항목

아래 내용은 다시 설문할 항목이 아니라 실제 자료와 기존 약정에서 확정해야 할 작업 목록입니다.

계산대 판매 파일의 실제 형식과 열 이름
거래번호 포함 여부
정상 판매가와 할인 후 판매가가 모두 들어 있는지 여부
반품·취소가 음수 거래로 들어오는 방식
정산 주차의 정확한 시작일과 종료 시각
수수료의 원 단위 반올림·올림·버림 기준
수수료를 거래별로 계산할지 주간 합계로 계산할지 여부
농가·품목 규칙이 충돌할 때의 최종 우선순위
폐기 손해의 기준 금액 산정 방식
공휴일이 있는 주의 마감일과 입금 예정일 변경 기준
거래번호가 없는 경우의 중복 판별 기준
농가 계정의 최초 로그인과 비밀번호 복구 방식
지급액이 음수가 되는 정산의 처리 기준
정산서 내려받기 형식
- 가정: 첫 버전은 PDF
증빙 사진과 정산 자료의 보관 기간

18. 개인정보·운영 참고

농가 연락처, 로그인 정보, 정산 내역과 증빙 사진은 접근 권한을 구분해 보관해야 합니다.
첫 버전에서 필요하지 않은 계좌 정보는 수집하지 않는 편이 안전합니다.
자료 보관 기간, 삭제 기준, 백업 기준은 실제 운영 주체의 방침으로 정해야 합니다.
세무·회계상 정산서 보관 기준과 개인정보 처리 기준은 실제 도입 전에 관련 전문가 확인이 필요합니다.