로컬푸드 직매장 정산 자동화 기능 요구사항 문서

1. 문서 목적

약 30개 농가 상품을 위탁 판매하는 로컬푸드 직매장이 계산대 판매 파일과 정산 규칙을 이용해 농가별 주간 정산서를 만들고 정산 마감하는 웹 서비스의 첫 개발 범위를 정의한다.

정산 담당자는 판매 항목과 농가·품목을 연결하고 오류와 매장 매출 차이를 처리한다. 점장 또는 마감 권한자는 목요일에 정산을 마감한다. 농가는 스마트폰에서 본인 정산서와 입금 예정일을 확인하고 이의 제기와 증빙 사진을 제출한다.

2. 첫 개발 범위

포함

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

제외

실제 은행 이체
은행 이체용 지급 파일 생성
문자·카카오톡 등 별도 알림
여러 로컬푸드 직매장 선택 및 통합 관리
처음 보는 상품코드를 외부 정보로 자동 판별하는 기능
마감된 정산서를 다시 열어 직접 수정하는 기능
별도 모바일 앱과 앱 스토어 배포

3. 사용자와 권한

사용자	주요 권한
정산 담당자	농가·품목·정산 규칙 관리, 계산대 판매 파일 업로드, 상품 연결, 반품·폐기 등록, 오류 처리, 정산서 생성, 정정 항목 작성
점장 또는 마감 권한자	정산 결과와 대조 상태 확인, 정산 마감
매장 운영자	담당자 계정과 권한 관리, 전체 운영 내역 조회
농가	본인 정산서 조회·내려받기, 본인 내역에 대한 이의 제기와 증빙 사진 제출

권한 원칙

농가는 본인에게 연결된 정산서와 이의 제기만 볼 수 있다.
정산 담당자는 정산서를 생성할 수 있지만 마감 권한이 없으면 정산 마감할 수 없다.
마감된 정산 주차의 판매·수수료·정산 금액은 어떤 운영자도 직접 수정할 수 없다.
정정은 원 정산서를 변경하지 않는 별도 정정 항목으로 처리한다.

4. 정산 상태

상태	의미	가능한 작업
준비 중	정산 주차만 생성된 상태	파일 업로드, 규칙 등록
처리 중	판매 원장과 상품 연결을 처리하는 상태	직접 연결, 거래 확인, 반품·폐기 등록
오류 있음	미연결 상품이나 규칙 오류 등이 남은 상태	오류 처리, 대조
마감 가능	필수 오류가 없고 대조 차이가 0원인 상태	정산서 생성, 마감 검토
정산서 생성	농가별 정산서가 생성된 미마감 상태	재계산, 정산서 확인, 마감
마감 완료	권한자가 정산 마감한 상태	조회, 내려받기, 정정 항목 작성
정정 반영 예정	다음 정산에 반영할 정정 항목이 있는 상태	정정 내역 조회

5. 정산 계산 기준

5.1 규칙 적용 기준

정산 규칙은 판매일에 유효한 규칙을 적용한다. 현재 등록된 최신 규칙을 과거 판매에 소급 적용하지 않는다.

여러 규칙이 동시에 해당할 때는 다음 순서로 더 구체적인 규칙을 적용한다.

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

적용할 규칙이 없으면 임의 수수료율을 적용하지 않고 정산 오류로 처리한다.

5.2 수수료 계산

수수료 = 수수료 계산 기준 금액 × 수수료율

할인 판매의 수수료 계산 기준은 정산 규칙에 따라 다음 중 하나를 사용한다.

할인 전 금액
할인 후 실제 판매금액

수수료 계산 결과의 원 단위 반올림 방식은 로컬푸드 직매장 전체에 동일하게 적용한다.

5.3 농가 지급액

농가 지급액
= 해당 주차의 순 판매액
- 수수료
- 농가 부담 반품 금액
- 농가 부담 폐기 금액
+ 확정된 매장 부담 보전 금액
± 정정 항목

매장 부담 보전 금액의 발생 조건과 계산 방식은 확정된 정산 규칙에 등록된 경우에만 적용한다. 규칙에 금액 계산 방식이 없으면 자동 계산하지 않는다.

5.4 매장 매출 대조

정정 항목은 이전 정산의 오류를 다음 정산에 반영하는 금액이므로 현재 정산 주차의 계산대 판매 파일 매출과 분리해 보여 준다.

조정된 순 판매액
= 계산대 판매 파일 순 판매액
± 확인된 수기 조정

현재 주차 정산 금액
= 농가 지급액 합계(정정 항목 제외)
+ 수수료 합계
+ 농가 부담 차감 합계
- 매장 부담 보전 합계

매출 대조 차이
= 조정된 순 판매액 - 현재 주차 정산 금액

매출 대조 차이가 0원이 아니면 정산 마감할 수 없다.

6. 기능 요구사항

FR-001 운영자 로그인

주체: 정산 담당자, 점장, 매장 운영자
시작 조건: 운영자 계정이 사용 가능 상태로 등록되어 있다.
정상 흐름:
1. 사용자가 아이디와 비밀번호를 입력한다.
2. 시스템이 계정 상태와 비밀번호를 확인한다.
3. 사용자 역할에 맞는 권한을 적용한다.
4. 주간 정산 현황 화면으로 이동한다.
예외 흐름:
- 계정이 없거나 비밀번호가 틀리면 구체적인 계정 존재 여부를 노출하지 않고 로그인 실패를 안내한다.
- 중지된 계정은 로그인할 수 없다.
- 비밀번호 복구 방식은 확인 필요다.
완료 조건: 로그인한 운영자의 역할과 권한이 서버 세션에 적용되고 로그인 시점이 기록된다.

FR-002 담당자 계정과 마감 권한 관리

주체: 매장 운영자
시작 조건: 매장 운영자가 로그인했다.
정상 흐름:
1. 담당자 이름과 로그인 정보를 등록한다.
2. 정산 담당자 또는 마감 권한을 선택한다.
3. 계정을 활성화하거나 중지한다.
4. 시스템이 변경 담당자와 처리 시점을 기록한다.
예외 흐름:
- 일반 정산 담당자가 다른 사용자의 마감 권한을 변경하려 하면 차단한다.
- 이미 사용 이력이 있는 계정은 삭제하지 않고 중지한다.
- 마지막 마감 권한자를 중지하려 하면 대체 권한자를 지정하도록 안내한다.
완료 조건: 담당자 계정의 상태와 권한이 저장되고 다음 요청부터 변경된 권한이 적용된다.

FR-003 농가 로그인 계정 연결

주체: 정산 담당자
시작 조건: 농가 정보가 등록되어 있다.
정상 흐름:
1. 농가에 로그인 계정을 연결한다.
2. 계정의 사용 상태를 설정한다.
3. 농가가 로그인하면 연결된 농가 식별값을 기준으로 조회 범위를 제한한다.
예외 흐름:
- 하나의 계정을 여러 농가에 연결하려 하면 저장을 차단한다.
- 중지된 농가 계정은 로그인할 수 없다.
- 첫 로그인과 비밀번호 복구 방식은 확인 필요다.
완료 조건: 농가 계정이 한 농가에 연결되고 해당 농가의 정산 정보에만 접근할 수 있다.

FR-004 정산 주차와 입금 예정일 설정

주체: 정산 담당자
시작 조건: 운영자가 로그인했다.
정상 흐름:
1. 정산 대상 시작일과 종료일을 입력한다.
2. 목요일 마감일과 입금 예정일을 입력한다.
3. 동일 기간의 정산 주차가 없는지 확인한다.
4. 정산 주차를 준비 중 상태로 생성한다.
예외 흐름:
- 다른 정산 주차와 판매 기간이 겹치면 저장을 차단한다.
- 종료일이 시작일보다 빠르면 저장할 수 없다.
- 공휴일에 따른 입금 예정일 변경 기준은 확인 필요다.
완료 조건: 판매 기간, 마감일, 입금 예정일이 포함된 정산 주차가 생성된다.

FR-005 농가·품목·품목군·상품코드 등록

주체: 정산 담당자
시작 조건: 운영자가 로그인했다.
정상 흐름:
1. 농가 정보와 이용 상태를 등록한다.
2. 품목군을 등록한다.
3. 품목명, 규격, 농가, 품목군을 등록한다.
4. 계산대 판매 파일에서 사용하는 상품코드를 품목에 연결한다.
예외 흐름:
- 같은 상품코드를 동시에 둘 이상의 사용 중인 품목에 연결할 수 없다.
- 정산 이력이 있는 농가와 품목은 삭제하지 않고 사용 중지한다.
- 별도 SKU 관리 여부는 확인 필요다.
완료 조건: 상품코드로 농가와 품목을 찾을 수 있는 상태가 된다.

FR-006 정산 규칙 등록과 변경 이력 관리

주체: 정산 담당자
시작 조건: 대상 농가, 품목 또는 품목군이 등록되어 있다.
정상 흐름:
1. 규칙 이름과 적용 대상을 선택한다.
2. 수수료율과 할인 수수료 기준을 입력한다.
3. 반품·폐기 부담 주체와 계산 기준을 입력한다.
4. 적용 시작일과 필요한 경우 종료일을 입력한다.
5. 확정된 약정임을 확인하고 저장한다.
6. 기존 규칙을 변경할 때는 기존 기록을 덮어쓰지 않고 종료일과 새 규칙을 저장한다.
예외 흐름:
- 동일한 적용 범위와 기간에 규칙이 중복되면 저장을 차단한다.
- 수수료율이나 적용 시작일이 없으면 저장할 수 없다.
- 마감된 정산에 적용된 규칙은 수정하거나 삭제할 수 없다.
- 확정되지 않은 약정은 적용 중 상태로 등록할 수 없다.
완료 조건: 판매일을 기준으로 적용할 규칙 하나를 결정할 수 있고 규칙 변경 이력이 남는다.

FR-007 계산대 판매 파일 업로드

주체: 정산 담당자
시작 조건: 대상 정산 주차가 마감 전 상태다.
정상 흐름:
1. 정산 주차를 선택한다.
2. 계산대 판매 파일을 업로드한다.
3. 시스템이 파일 형식, 열, 날짜, 금액과 거래 유형을 검사한다.
4. 정상 행과 오류 행을 구분한다.
5. 파일 식별값과 업로드 담당자, 업로드 시점을 저장한다.
예외 흐름:
- 지원하지 않는 형식이나 필수 열이 없는 파일은 반영하지 않는다.
- 판매일이 정산 주차 밖인 행은 오류로 표시한다.
- 같은 파일이 이미 반영되었으면 중복 업로드를 차단한다.
- 일부 행만 잘못된 경우 전체 파일 반영 여부는 실제 계산대 판매 파일 확인 후 결정한다.
완료 조건: 정상 거래가 판매 원장 처리 대상으로 등록되고 오류 행이 목록으로 제공된다.

FR-008 상품코드 자동 연결과 직접 연결

주체: 정산 담당자
시작 조건: 계산대 판매 파일이 업로드되었다.
정상 흐름:
1. 상품코드가 기존 품목과 일치하면 자동 연결한다.
2. 처음 보는 상품코드는 미연결 상태로 표시한다.
3. 운영자가 해당 농가와 품목을 선택한다.
4. 직접 연결한 결과를 이후 같은 상품코드에 재사용한다.
5. 자동 연결과 직접 연결을 구분해 기록한다.
예외 흐름:
- 상품코드가 비어 있으면 판매 파일의 품목명과 원본 행을 보여 주고 직접 연결하도록 한다.
- 하나의 상품코드가 여러 품목과 충돌하면 자동 연결하지 않는다.
- 직접 연결을 변경할 때 기존 연결 이력을 삭제하지 않는다.
완료 조건: 모든 정상 판매 항목이 하나의 농가와 품목에 연결되거나 미연결 오류로 남는다.

FR-009 중복 거래 검사와 판매 원장 생성

주체: 시스템, 정산 담당자
시작 조건: 계산대 판매 파일의 정상 행이 분석되었다.
정상 흐름:
1. 거래 고유값과 원본 파일 식별값을 이용해 중복을 검사한다.
2. 판매·할인·반품 거래를 유형별로 구분한다.
3. 원본 행과 연결 정보를 보존한 판매 원장을 생성한다.
4. 중복 가능성이 없는 거래를 정산 대상으로 표시한다.
예외 흐름:
- 동일 거래 고유값이 이미 있으면 중복 오류로 처리한다.
- 거래 고유값이 없는 파일의 중복 판별 기준은 확인 필요다.
- 중복 가능성이 있지만 자동 판단할 수 없으면 운영자 확인 전까지 정산에서 제외한다.
완료 조건: 정산 계산에 사용할 판매 원장이 생성되고 중복 가능 거래가 구분된다.

FR-010 판매·할인·반품 내역 확인

주체: 정산 담당자
시작 조건: 판매 원장이 생성되었다.
정상 흐름:
1. 정산 주차, 농가, 품목, 거래 유형으로 내역을 조회한다.
2. 정상 판매금액, 실제 판매금액, 할인금액과 반품 금액을 확인한다.
3. 각 거래에 적용될 정산 규칙을 확인한다.
4. 원본 계산대 판매 파일의 행을 함께 확인한다.
예외 흐름:
- 할인 전 금액이나 할인 후 금액이 필요한데 원본에 없으면 확인 필요 오류로 표시한다.
- 반품이 원래 판매와 연결되지 않으면 미확인 오류로 표시한다.
- 마감된 거래는 조회만 가능하다.
완료 조건: 모든 판매·할인·반품 거래가 정산 가능 또는 오류 상태로 구분된다.

FR-011 폐기와 미회수 재고 등록

주체: 정산 담당자
시작 조건: 대상 정산 주차가 마감 전이며 농가와 품목이 등록되어 있다.
정상 흐름:
1. 농가, 품목, 수량과 처리 유형을 입력한다.
2. 유통기한 경과, 미회수 재고 등 폐기 사유를 선택한다.
3. 부담 주체와 정산 반영 금액을 입력하거나 적용 규칙으로 계산한다.
4. 필요한 경우 증빙 사진을 첨부한다.
5. 처리 담당자와 처리 시점을 기록한다.
6. 농가에 알린 날짜와 방법을 기록한다.
예외 흐름:
- 농가, 품목, 수량, 사유 또는 부담 주체가 없으면 확정할 수 없다.
- 적용할 폐기 규칙이 없으면 임의 계산하지 않고 오류로 남긴다.
- 농가 부담인데 통지 기록이 없으면 경고를 표시한다. 통지 기록을 마감 필수 조건으로 할지는 확인 필요다.
- 마감 후에는 원 기록을 수정할 수 없다.
완료 조건: 폐기 또는 미회수 재고가 판매 원장에 별도 내역으로 반영되고 정산 영향이 계산 가능하다.

FR-012 농가별 정산 금액 계산

주체: 시스템
시작 조건: 판매 항목이 농가·품목에 연결되고 적용 가능한 정산 규칙이 있다.
정상 흐름:
1. 판매일에 유효한 정산 규칙을 선택한다.
2. 할인 수수료 기준에 따라 수수료 계산 기준 금액을 결정한다.
3. 수수료를 계산한다.
4. 반품·폐기 부담 금액을 반영한다.
5. 다음 정산에 반영할 정정 항목을 더하거나 뺀다.
6. 농가별 판매액, 수수료, 공제액과 지급액을 계산한다.
7. 적용 규칙과 계산 결과의 복사본을 거래에 보관한다.
예외 흐름:
- 적용 규칙이 없거나 둘 이상 충돌하면 계산 완료로 처리하지 않는다.
- 할인 수수료 기준 금액이 없으면 오류로 처리한다.
- 지급액이 음수가 되는 경우 마감 허용 여부는 확인 필요다.
완료 조건: 모든 농가의 지급액과 계산 근거를 같은 조건으로 다시 확인할 수 있다.

FR-013 정산 오류 검사와 처리

주체: 시스템, 정산 담당자
시작 조건: 판매 원장 또는 정산 계산 결과가 존재한다.
정상 흐름:
1. 시스템이 미연결 상품을 검사한다.
2. 정산 규칙 누락과 충돌을 검사한다.
3. 중복 가능 거래를 검사한다.
4. 확인되지 않은 할인·반품·폐기 내역을 검사한다.
5. 오류별 대상 거래와 해결 방법을 보여 준다.
6. 운영자가 오류를 해결하면 다시 검사한다.
예외 흐름:
- 운영자가 오류를 단순 무시하고 해결 상태로 바꿀 수 없다.
- 원본 자료만으로 판단할 수 없는 항목은 확인 필요 상태로 유지한다.
- 마감된 거래에서 발견된 오류는 정정 항목 작성으로 연결한다.
완료 조건: 필수 오류 건수가 0건이거나 오류가 남아 마감 차단 상태가 된다.

FR-014 매장 매출 합계 대조

주체: 정산 담당자, 점장
시작 조건: 정산 계산 결과가 생성되었다.
정상 흐름:
1. 계산대 판매 파일 순 판매액을 표시한다.
2. 수기 조정, 수수료, 농가 부담 금액과 매장 부담 금액을 구분해 표시한다.
3. 정정 항목은 현재 주차 매출과 분리한다.
4. 농가 지급액 합계와 차이 계산 근거를 보여 준다.
5. 매출 대조 차이가 0원인지 확인한다.
예외 흐름:
- 차이가 0원이 아니면 마감 가능 상태로 변경하지 않는다.
- 대조 근거가 없는 수동 차액 입력으로 0원을 만들 수 없다.
- 조정이 필요하면 대상 거래와 사유를 연결해야 한다.
완료 조건: 대조 차이가 0원이고 모든 구성 금액을 세부 거래까지 추적할 수 있다.

FR-015 주간 정산 현황 제공

주체: 정산 담당자, 점장, 매장 운영자
시작 조건: 운영자가 로그인했다.
정상 흐름:
1. 현재 정산 주차와 입금 예정일을 표시한다.
2. 파일 업로드 상태와 처리 건수를 표시한다.
3. 미연결 상품 수, 오류 수와 대조 차이를 표시한다.
4. 정산서 생성 및 마감 가능 여부를 표시한다.
5. 필요한 작업 화면으로 이동할 수 있게 한다.
예외 흐름:
- 정산 주차가 없으면 새 정산 주차 생성 안내를 표시한다.
- 오류가 있으면 마감 버튼 대신 해결할 오류를 표시한다.
완료 조건: 운영자가 현재 정산 진행 상태와 다음 작업을 한 화면에서 판단할 수 있다.

FR-016 농가별 정산서 생성

주체: 정산 담당자
시작 조건: 필수 오류가 0건이고 대조 차이가 0원이다.
정상 흐름:
1. 정산서 생성을 실행한다.
2. 농가별 판매금액, 수수료, 할인, 반품, 폐기, 정정 항목과 지급액을 집계한다.
3. 정산 주차와 입금 예정일을 포함한다.
4. 정산서 생성 시점과 생성 담당자를 기록한다.
5. 미마감 정산서를 농가별로 미리 확인한다.
예외 흐름:
- 오류 또는 대조 차이가 생기면 생성을 차단한다.
- 마감 전 판매 원장이나 규칙이 변경되면 기존 미마감 정산서를 무효화하고 다시 계산한다.
- 판매가 없는 농가의 정산서 생성 기준은 확인 필요다.
완료 조건: 대상 농가마다 같은 정산 주차의 정산서가 생성되고 합계가 대조 결과와 일치한다.

FR-017 정산 마감과 잠금

주체: 점장 또는 마감 권한자
시작 조건: 정산서가 생성되었고 오류가 0건이며 대조 차이가 0원이다.
정상 흐름:
1. 마감 권한자가 농가별 지급액 합계와 대조 결과를 확인한다.
2. 정산 마감을 실행한다.
3. 시스템이 조건을 서버에서 다시 검사한다.
4. 정산 주차와 정산서를 마감 완료 상태로 변경한다.
5. 마감자와 마감 시점을 기록한다.
6. 관련 판매 원장, 적용 규칙과 계산 결과를 잠근다.
예외 흐름:
- 마감 권한이 없으면 차단한다.
- 오류가 생겼거나 대조 차이가 0원이 아니면 차단한다.
- 마감일 전에는 마감을 차단한다.
- 목요일 이후 지연 마감을 허용하되 실제 마감 시점을 기록하는 것으로 가정한다.
- 이미 마감된 정산은 다시 마감하거나 열 수 없다.
완료 조건: 마감된 판매·수수료·정산 금액에 대한 수정 요청이 서버에서 거부된다.

FR-018 마감 후 정정 항목 작성과 다음 정산 반영

주체: 정산 담당자
시작 조건: 오류가 발견된 원 정산서가 마감 완료 상태다.
정상 흐름:
1. 원 정산서와 가능한 경우 원 거래를 선택한다.
2. 정정 사유와 증빙을 입력한다.
3. 정정 전 금액과 정정 후 금액을 입력한다.
4. 시스템이 정정 차액을 계산한다.
5. 다음 미마감 정산 주차를 반영 주차로 지정한다.
6. 정정 담당자와 처리 시점을 기록한다.
7. 다음 정산서에 일반 판매와 구분된 정정 항목으로 반영한다.
예외 흐름:
- 원 정산서를 연결하지 않으면 저장할 수 없다.
- 원 거래가 존재하는 오류인데 원 거래가 연결되지 않으면 확정할 수 없다.
- 반영 대상 정산 주차가 이미 마감되었으면 다른 미마감 주차를 지정한다.
- 정정 승인자를 별도로 둘지는 확인 필요다.
완료 조건: 원 정산서는 그대로 유지되고 정정 차액이 지정된 다음 정산에 한 번만 반영된다.

FR-019 마감과 정정 연결 이력 조회

주체: 정산 담당자, 점장, 매장 운영자
시작 조건: 마감된 정산서 또는 정정 항목이 있다.
정상 흐름:
1. 정산 주차 또는 농가를 선택한다.
2. 마감자와 마감 시점을 확인한다.
3. 정정 항목의 원 정산서와 원 거래를 확인한다.
4. 정정 전후 금액과 반영 주차를 확인한다.
5. 처리 담당자와 처리 시점을 확인한다.
예외 흐름:
- 삭제되거나 접근할 수 없는 원본 연결을 허용하지 않는다.
- 연결 자료가 불완전하면 데이터 오류로 표시한다.
완료 조건: 정정 금액이 어디에서 발생해 어느 정산 주차에 반영되었는지 추적할 수 있다.

FR-020 농가의 이번 주 정산 조회

주체: 농가
시작 조건: 농가가 로그인했고 본인 정산서가 생성되어 있다.
정상 흐름:
1. 이번 정산 주차를 먼저 보여 준다.
2. 최종 지급액을 가장 크게 표시한다.
3. 판매금액, 수수료, 공제·차감, 정정 금액을 표시한다.
4. 입금 예정일을 표시한다.
5. 이전 정산 주차를 선택할 수 있게 한다.
예외 흐름:
- 아직 정산서가 없으면 조회할 정산서가 없음을 안내한다.
- 미마감 정산서를 농가에게 공개할지는 확인 필요다. 기본 구현은 마감 완료 정산서만 공개한다.
- 다른 농가의 정산서 주소로 접근하면 요청을 거부한다.
완료 조건: 농가가 본인의 지급액과 입금 예정일을 한 화면에서 확인한다.

FR-021 농가 정산서 상세 조회와 내려받기

주체: 농가
시작 조건: 농가가 본인 정산서를 열었다.
정상 흐름:
1. 품목별 판매 수량과 판매금액을 표시한다.
2. 적용 수수료율과 수수료 금액을 표시한다.
3. 할인 전 금액, 할인 후 금액과 할인 수수료 기준을 표시한다.
4. 반품·폐기 사유와 부담 금액을 표시한다.
5. 정정 항목의 원 정산 주차와 사유를 표시한다.
6. 정산서를 파일로 내려받는다.
예외 흐름:
- 다른 농가의 내역이나 증빙 파일을 요청하면 거부한다.
- 내려받기 파일이 아직 준비되지 않았으면 다시 생성한다.
- 은행 이체용 지급 파일은 생성하지 않는다.
완료 조건: 농가가 지급액의 계산 근거를 세부 내역으로 확인하고 본인 정산서를 내려받을 수 있다.

FR-022 농가 이의 제기와 증빙 사진 제출

주체: 농가
시작 조건: 농가가 본인 정산서 또는 세부 내역을 조회하고 있다.
정상 흐름:
1. 이의 대상 정산서 또는 세부 내역을 선택한다.
2. 이의 제기 내용을 입력한다.
3. 필요한 경우 증빙 사진을 첨부한다.
4. 제출하면 접수 상태로 저장한다.
5. 제출 시점과 제출 농가를 기록한다.
예외 흐름:
- 이의 내용이 없으면 제출할 수 없다.
- 허용되지 않은 파일 형식이나 크기의 사진은 거부한다.
- 다른 농가의 내역을 이의 대상으로 선택할 수 없다.
완료 조건: 이의 제기가 관련 정산서 또는 세부 내역에 연결되어 운영자 화면에 나타난다.

FR-023 농가 이의 제기 처리

주체: 정산 담당자, 점장
시작 조건: 접수된 이의 제기가 있다.
정상 흐름:
1. 이의 내용과 증빙 사진을 확인한다.
2. 관련 정산서와 세부 거래를 확인한다.
3. 처리 상태를 접수, 확인 중, 처리 완료 중 하나로 변경한다.
4. 처리 결과, 담당자와 처리일을 기록한다.
5. 농가에 알린 날짜와 방법을 기록한다.
6. 정산 금액 수정이 필요하고 원 정산이 마감된 경우 정정 항목을 작성한다.
예외 흐름:
- 처리 결과가 없으면 처리 완료로 변경할 수 없다.
- 농가 안내 날짜와 방법이 없으면 처리 완료 시 경고한다. 이를 필수 조건으로 할지는 확인 필요다.
- 이의 처리 화면에서 마감된 원 정산서를 직접 수정할 수 없다.
완료 조건: 처리 결과와 담당자, 처리일, 농가 안내 기록이 보존되고 필요한 정정 항목이 연결된다.

FR-024 주요 작업 이력 기록

주체: 시스템
시작 조건: 로그인 또는 정산 관련 주요 작업이 발생한다.
정상 흐름:
1. 로그인, 규칙 등록·변경, 파일 업로드, 직접 상품 연결을 기록한다.
2. 반품·폐기 등록, 오류 처리, 정산서 생성과 정산 마감을 기록한다.
3. 정정 항목과 이의 처리 작업을 기록한다.
4. 작업자, 처리 시점, 대상 자료와 변경 내용을 보관한다.
예외 흐름:
- 작업 이력 저장에 실패하면 마감, 규칙 변경, 정정 등 중요 작업을 완료 처리하지 않는다.
- 일반 사용자가 작업 이력을 수정하거나 삭제할 수 없다.
완료 조건: 주요 정산 결과가 어떤 작업으로 만들어졌는지 담당자와 시점 기준으로 확인할 수 있다.

7. 화면 요구사항

화면 중복 이름 처리

제품 자료의 다음 화면 이름은 별도 화면이 아니라 같은 화면의 중복 이름으로 관리한다.

중복 이름	기준 화면
screen2	farmer-settlement
screen3	correction-history
screen4	farmer-settlement-view
screen5	farmer-login
screen6	settlement-dashboard
screen7	dispute-management

screen1은 농가가 로그인 직후 보는 큰 글씨 중심 화면으로 유지한다. farmer-settlement은 정산 주차 목록과 요약, farmer-settlement-view는 정산서 상세로 구분한다.

UIR-001 운영자 로그인과 권한 관리

화면 이름: operator-login
사용 목적: 운영자 로그인과 담당자 계정·마감 권한 관리
주요 구성:
- 아이디, 비밀번호
- 로그인 버튼
- 담당자 목록
- 역할과 마감 권한
- 계정 활성화·중지
주요 상태: 로그인 전, 로그인 실패, 계정 중지, 로그인 완료
완료 조건: 권한이 확인된 사용자가 주간 정산 현황으로 이동한다.
연결 기능: FR-001, FR-002

UIR-002 주간 정산 현황

화면 이름: settlement-dashboard
사용 목적: 현재 정산 진행 상태와 다음 작업 확인
진입 경로: operator-login, 운영자 공통 메뉴
주요 구성:
- 정산 주차와 입금 예정일
- 파일 업로드 상태
- 전체 거래 수와 처리 건수
- 미연결 상품 수
- 오류 수
- 매출 대조 차이
- 정산서 생성 및 마감 가능 여부
- 농가 이의 제기 미처리 수
주요 동작: 파일 업로드, 오류 처리, 대조, 정산서 생성, 이의 처리 화면으로 이동
완료 조건: 운영자가 정산 마감까지 남은 작업을 바로 판단할 수 있다.
연결 기능: FR-004, FR-015

UIR-003 농가·품목·정산 규칙 관리

화면 이름: farm-product-rules
사용 목적: 농가·품목·상품코드와 정산 규칙 등록
진입 경로: settlement-dashboard
주요 구성:
- 농가 목록과 이용 상태
- 농가 계정 연결 상태
- 품목군·품목·상품코드
- 수수료율
- 할인 전·후 수수료 기준
- 반품·폐기 부담 주체
- 적용 시작일·종료일
- 규칙 충돌 및 변경 이력
주요 동작: 등록, 새 규칙으로 변경, 사용 중지, 이력 조회
완료 조건: 판매일에 적용할 확정된 정산 규칙을 결정할 수 있다.
연결 기능: FR-003, FR-005, FR-006

UIR-004 계산대 판매 파일 업로드와 상품 연결

화면 이름: sales-upload-mapping
사용 목적: 계산대 판매 파일 업로드와 처음 보는 상품코드 연결
진입 경로: settlement-dashboard
주요 구성:
- 정산 주차 선택
- 파일 선택 영역
- 파일 분석 결과
- 정상·오류 행 수
- 자동 연결·직접 연결 표시
- 미연결 상품코드, 품목명, 거래 예시
- 농가와 품목 선택
주요 동작: 업로드, 직접 연결, 재검사, 판매 원장 이동
완료 조건: 모든 정상 행이 판매 원장에 반영되고 미연결 항목이 명확히 구분된다.
연결 기능: FR-007, FR-008, FR-009

UIR-005 판매·할인·반품·폐기 내역 확인

화면 이름: transaction-history
사용 목적: 판매 원장 확인과 반품·폐기 내역 등록
진입 경로: settlement-dashboard, sales-upload-mapping
주요 구성:
- 농가·품목·거래 유형 필터
- 판매일시, 수량, 정상가, 실제 판매금액
- 할인과 반품 내역
- 적용 정산 규칙
- 폐기·미회수 등록 양식
- 증빙 사진과 농가 통지 기록
주요 동작: 거래 확인, 폐기 등록, 오류 내역 이동
완료 조건: 정산에 포함되는 거래와 계산 근거를 운영자가 확인할 수 있다.
연결 기능: FR-010, FR-011

UIR-006 오류 목록과 매장 매출 합계 대조

화면 이름: reconciliation-errors
사용 목적: 오류를 해결하고 매장 매출 대조 차이를 0원으로 맞춤
진입 경로: settlement-dashboard, sales-upload-mapping, transaction-history
주요 구성:
- 미연결 상품
- 중복 가능 거래
- 정산 규칙 누락·충돌
- 미확인 할인·반품·폐기
- 계산대 판매 파일 순 판매액
- 수기 조정과 정산 구성 금액
- 농가 지급액 합계
- 매출 대조 차이
주요 동작: 오류별 대상 열기, 재검사, 정산서 생성 화면 이동
완료 조건: 필수 오류가 0건이고 매출 대조 차이가 0원이다.
연결 기능: FR-013, FR-014

UIR-007 농가별 정산서 생성·마감·정정 이력

화면 이름: settlement-close
사용 목적: 정산서 생성, 합계 검토와 정산 마감
진입 경로: settlement-dashboard, reconciliation-errors
주요 구성:
- 농가별 판매금액, 수수료, 차감, 정정, 지급액
- 전체 지급액과 수수료 합계
- 오류 수와 매출 대조 차이
- 정산서 생성 버튼
- 마감 가능 조건 목록
- 정산 마감 버튼
- 마감자와 마감 시점
- 정정 이력 이동
주요 동작: 정산서 생성, 농가별 미리보기, 정산 마감
완료 조건: 권한자가 조건을 확인한 뒤 마감하고 해당 정산 주차가 잠긴다.
연결 기능: FR-016, FR-017

UIR-008 마감과 정정 이력

화면 이름: correction-history
사용 목적: 원 정산서와 다음 정산의 정정 항목 연결 확인
진입 경로: settlement-close
주요 구성:
- 원 정산 주차와 원 정산서
- 원 거래
- 정정 사유
- 정정 전후 금액
- 정정 차액
- 다음 반영 주차
- 처리 담당자와 처리 시점
주요 동작: 정정 항목 작성, 원본 조회, 반영 정산서 조회
완료 조건: 정정의 발생 원인과 반영 결과를 한 흐름으로 추적할 수 있다.
연결 기능: FR-018, FR-019

UIR-009 농가 이의 제기 처리

화면 이름: dispute-management
사용 목적: 이의 제기 확인, 처리 결과와 농가 안내 기록
진입 경로: settlement-dashboard, settlement-close, 농가가 제출한 이의 제기
주요 구성:
- 처리 상태와 접수일
- 농가, 정산 주차, 대상 세부 내역
- 이의 내용과 증빙 사진
- 처리 결과
- 담당자와 처리일
- 농가에 알린 날짜와 방법
- 정정 항목 연결
주요 동작: 상태 변경, 결과 저장, 정정 항목 작성
완료 조건: 처리 결과와 안내 기록이 저장되고 필요한 정정이 연결된다.
연결 기능: FR-023

UIR-010 농가 로그인

화면 이름: farmer-login
사용 목적: 농가가 본인 계정으로 로그인
진입 경로: 농가가 직접 입력한 서비스 주소, 로그아웃 상태
주요 구성:
- 아이디
- 비밀번호
- 로그인 버튼
- 로그인 오류 안내
주요 상태: 로그인 전, 실패, 계정 중지, 성공
완료 조건: 로그인한 농가가 본인 정산 화면으로 이동한다.
연결 기능: FR-003

UIR-011 농가용 큰 글씨 정산 조회와 이의 제기

화면 이름: screen1
사용 목적: 농가가 로그인 직후 이번 주 핵심 정산 결과를 확인
진입 경로: farmer-login
주요 구성 순서:
1. 농가명과 정산 주차
2. 최종 지급액
3. 입금 예정일
4. 판매금액
5. 수수료와 공제·차감
6. 정정 금액
7. 정산서 상세
8. 이의 제기
주요 동작: 정산서 상세 보기, 이전 정산 보기, 이의 제기
완료 조건: 농가가 스크롤을 많이 하지 않고 지급액과 입금 예정일을 확인한다.
연결 기능: FR-020, FR-022

UIR-012 농가용 스마트폰 정산 조회

화면 이름: farmer-settlement
사용 목적: 농가가 본인 정산 주차 목록과 요약을 조회
진입 경로: farmer-login, screen1
주요 구성:
- 정산 주차 목록
- 주차별 지급액
- 입금 예정일
- 마감 상태
- 이의 제기 상태
주요 동작: 주차 선택, 정산서 상세 이동, 이의 제기 이동
완료 조건: 농가가 이번 주와 이전 정산서를 구분해 선택할 수 있다.
연결 기능: FR-020

UIR-013 농가용 큰 글씨 정산서 상세

화면 이름: farmer-settlement-view
사용 목적: 지급액 계산의 세부 근거 확인
진입 경로: farmer-settlement, screen1
주요 구성:
- 최종 지급액
- 품목별 판매 수량과 판매금액
- 수수료율과 수수료
- 할인 전·후 금액과 할인 수수료 기준
- 반품·폐기 내역과 사유
- 정정 항목과 원 정산 주차
- 정산서 내려받기
- 이의 제기 버튼
주요 동작: 항목 펼쳐 보기, 내려받기, 이의 제기
완료 조건: 농가가 지급액이 계산된 이유를 세부 내역으로 확인할 수 있다.
연결 기능: FR-021, FR-022

8. 비기능 요구사항

NFR-001 금액 계산 정확성

판매금액, 수수료, 지급액과 정정 금액은 원 단위 정수로 저장한다.
수수료율은 부동소수점 오차가 발생하지 않는 형식으로 저장한다.
수수료 계산의 절사·반올림·올림 기준을 매장 설정으로 하나만 확정한다.
같은 입력과 규칙으로 다시 계산했을 때 같은 원 단위 결과가 나와야 한다.
반올림 기준은 첫 실제 정산 규칙 확인 후 확정해야 한다.

NFR-002 날짜와 시간 기준

판매일시, 규칙 적용일, 정산 주차와 마감 시점은 한국 시간을 기준으로 처리한다.
적용 시작일의 시작 시각과 종료일의 종료 시각을 서버에서 동일하게 해석해야 한다.
화면, 내려받기 파일과 작업 이력의 날짜 기준이 일치해야 한다.

NFR-003 마감 자료 불변성

마감된 정산서, 판매 원장, 적용 규칙 복사본과 계산 결과는 서버에서 수정 요청을 거부해야 한다.
화면에서 수정 버튼만 숨기는 방식으로 구현하지 않는다.
마감 처리 중 일부 데이터만 잠기는 일이 없도록 전체 마감을 하나의 완료 작업으로 처리한다.
마감 실패 시 일부만 마감된 상태가 남아서는 안 된다.

NFR-004 접근 권한과 자료 격리

모든 정산서·거래·사진 조회 요청에서 로그인 사용자와 농가 연결을 다시 검사한다.
주소의 정산서 번호를 바꿔도 다른 농가 자료를 조회할 수 없어야 한다.
증빙 사진과 내려받기 파일은 공개 주소로 제공하지 않는다.
정산 마감과 권한 변경은 해당 권한이 있는 운영자만 실행할 수 있다.

NFR-005 로그인 보안

비밀번호는 원문으로 저장하지 않는다.
반복 로그인 실패에 대한 제한을 적용한다.
로그아웃 또는 세션 만료 후 이전 정산서 주소에 접근하면 다시 로그인하게 한다.
로그인 오류 메시지로 계정 존재 여부를 구분할 수 없게 한다.

NFR-006 계산대 판매 파일 안전성

실제 파일 형식 확인 후 CSV 또는 엑셀 형식을 지원한다.
문자 인코딩, 날짜 형식, 금액 쉼표, 빈 셀과 음수 거래를 검증한다.
파일명만으로 중복을 판단하지 않고 원본 파일 식별값을 저장한다.
업로드 파일을 실행 파일로 처리하지 않는다.
잘못된 파일이 기존 판매 원장을 덮어쓰지 않게 한다.

NFR-007 작업 이력 보존

로그인, 규칙 변경, 파일 업로드, 직접 상품 연결, 폐기 등록, 오류 처리, 마감, 정정과 이의 처리를 기록한다.
작업 이력에는 작업자, 시각, 대상과 변경 전후 내용이 포함되어야 한다.
일반 운영자는 작업 이력을 수정하거나 삭제할 수 없다.

NFR-008 농가용 화면 접근성

농가용 화면은 스마트폰 세로 화면을 우선한다.
최종 지급액은 화면의 첫 주요 영역에 가장 큰 글씨로 표시한다.
주요 본문은 확대하지 않아도 읽을 수 있는 큰 글씨를 사용한다.
색상만으로 정상, 오류와 처리 상태를 구분하지 않는다.
버튼에는 확인, 정산서 보기, 이의 제기처럼 행동이 드러나는 문구를 사용한다.
입력 항목에는 화면에 보이는 이름표를 제공한다.

NFR-009 화면 오류 처리

저장 실패 시 사용자가 입력한 내용을 가능한 한 유지한다.
마감 차단 시 단순히 실패라고 표시하지 않고 남은 오류 수와 이동 경로를 보여 준다.
파일 오류는 원본 행 번호와 오류 이유를 함께 표시한다.
권한 오류와 존재하지 않는 자료 오류에서 다른 농가의 정보가 노출되지 않아야 한다.

NFR-010 처리 성능

다음 기준은 첫 매장 시범을 위한 가정이며 실제 계산대 판매 파일 규모 확인 후 확정한다.

가정: 농가 약 30곳, 정산 주차당 판매 원장 최대 50,000건
주간 정산 현황과 농가 정산 조회는 일반적인 매장 인터넷 환경에서 지속적으로 기다리지 않고 사용할 수 있어야 한다.
대용량 파일 분석 중에는 진행 상태를 표시하고 화면을 닫아도 중복 처리되지 않아야 한다.
정산 계산과 대조는 같은 작업이 중복 실행되지 않도록 제어한다.

NFR-011 백업과 복구

농가, 정산 규칙, 판매 원장, 마감 정산서, 정정 항목과 이의 제기 자료를 백업 대상에 포함한다.
백업 실패를 운영자가 확인할 수 있어야 한다.
보관 기간, 백업 주기와 복구 목표 시간은 확인 필요다.
마감된 정산서를 복구하더라도 잠금 상태와 작업 이력이 유지되어야 한다.

NFR-012 웹 서비스 구현 범위

서비스는 Next.js 기반 웹으로 제공한다.
운영자 화면은 데스크톱과 태블릿에서 사용할 수 있어야 한다.
농가 화면은 스마트폰 웹 브라우저에서 사용할 수 있어야 한다.
앱 설치를 필수로 요구하지 않는다.
여러 로컬푸드 직매장을 선택하는 화면이나 기능을 노출하지 않는다.

9. 주요 검수 시나리오

시나리오	통과 기준
등록된 상품코드 업로드	판매 항목이 해당 농가와 품목에 자동 연결된다.
처음 보는 상품코드 업로드	미연결 오류가 발생하고 운영자가 직접 연결할 수 있다.
할인 판매 정산	농가·품목별 규칙에 따라 할인 전 또는 할인 후 금액으로 수수료가 계산된다.
규칙 누락	임의 수수료율을 적용하지 않고 정산 마감을 차단한다.
매출 합계 불일치	차이가 0원이 될 때까지 정산 마감을 차단한다.
목요일 정산 마감	권한자가 마감하면 관련 판매·수수료·정산 금액의 수정 요청이 거부된다.
마감 후 오류 발견	원 정산서는 유지되고 다음 정산에 정정 항목으로 반영된다.
농가 조회 권한	농가는 본인 정산서만 보고 다른 농가 주소 접근은 거부된다.
농가 이의 제기	대상 내역과 내용·증빙 사진이 운영자 화면에 연결된다.
이의 처리 완료	처리 결과, 담당자, 처리일, 농가에 알린 날짜와 방법이 기록된다.
정산서 내려받기	농가가 본인 정산서는 내려받지만 은행 이체용 파일은 생성되지 않는다.
규칙 변경	새 적용 시작일 이후 미마감 판매에만 적용되고 마감된 정산은 바뀌지 않는다.

10. 개발 전 확인 필요 항목

계산대 판매 파일이 CSV인지 엑셀인지와 실제 열 구성
거래번호 등 거래 고유값 포함 여부
판매 파일에 정상가, 실제 판매금액, 할인금액이 각각 포함되는지
수수료 원 단위 절사·반올림·올림 기준
농가 부담 반품·폐기 금액의 구체적인 계산 방식
매장 부담 반품·폐기 시 농가 보전 금액 계산 방식
판매가 없는 농가도 0원 정산서를 생성할지 여부
지급액이 음수일 때 다음 정산으로 넘길지 별도로 처리할지 여부
농가 첫 로그인과 비밀번호 복구 방식
미마감 정산서를 농가에게 미리 공개할지 여부
정정 항목에 점장 승인을 별도로 요구할지 여부
폐기 농가 통지 기록과 이의 처리 안내 기록을 마감·완료의 필수 조건으로 할지 여부
공휴일이 월요일인 경우 입금 예정일 변경 기준
정산서와 증빙 사진의 보관 기간 및 삭제 기준