wixon/jongryangje

Fork 0

Files

taekyoungc 06aa401048 docs: add project docs and test updates

2026-04-08 00:23:55 +09:00

14 KiB

Raw Blame History

종량제봉투 웹 플랫폼 개발 (노션 정리)

출처: 차장님 노션 정리. 업무 요구사항 정의, 기능 분석, 제어/데이터 흐름, UML.

업무 요구사항 정의 및 기능 분석

시스템의 웹 전환에서 가장 우선시되는 요구사항은 데이터의 중앙 집중화와 다중 접속 환경에서의 정합성 유지임. 기존의 데스크톱 기반 시스템은 특정 단말기에 종속되는 경향이 있었으나, 웹 기반 시스템은 구군청 담당자, 제작업체, 판매소 대행사가 각자의 권한에 따라 실시간으로 데이터를 상호작용하게 함.

기본 정보 관리 체계 (Master Data Management)

기본 정보 관리는 시스템의 근간이 되는 정적 데이터를 관리하는 모듈로, 시스템 전반에서 참조되는 코드 체계와 단가 구조를 정의함.

기능 ID	하위 기능명	핵심 요구사항 및 상세 명세
F-MD-01	기본 코드 관리	도/특별시/광역시 구분, 구군 코드, 봉투 구분(일반/재사용/음식물), 용량별 코드, 작업 권한 등 시스템 공통 코드의 CRUD 관리
F-MD-02	단가 관리	적용 일자별 발주 단가, 도매가, 소비자 가격 관리. 시계열 기반의 단가 이력 관리를 통해 과거 거래 기록의 소급 적용 방지
F-MD-03	포장 단위 관리	박스당 팩 수량, 팩당 낱장 수량 정의. 바코드 생성 및 재고 계산의 기본 단위로 사용되며, 총 수량의 자동 계산 로직 포함
F-MD-04	판매 대행소 관리	은행 목록과 연동된 대행소 정보 관리. 새마을금고, 우체국, 농협 등 결제 대행 기관의 코드 및 명칭 관리
F-MD-05	업체 및 담당자 관리	제작업체, 협회, 회수업체 정보와 각 업체별 소속 담당자의 연락처 및 권한 관리. 업체 수정 시 담당자 정보의 연동성 확보
F-MD-06	지정 판매소 관리	판매소의 신규 등록, 취소, 업태/업종 정보 관리. GIS 연동을 통한 지도 보기 및 바코드 출력 시스템과의 연계

지정 판매소 관리 기능은 단순히 텍스트 정보를 저장하는 것을 넘어, **판매소의 생애주기(지정 → 운영 → 취소/폐업)**를 관리해야 함. 특히 판매소 바코드 출력 기능은 PDF417 규격에 따라 판매소 고유 식별자를 포함해야 하며, 이는 이후 판매 및 반품 단계에서 스캐너를 통해 인식되는 핵심 데이터임.

발주 및 입고 프로세스 요구사항

발주 및 입고 관리는 지자체가 예산을 투입하여 자산을 형성하는 과정으로, 제작업체와의 데이터 연동이 필수임.

기능 ID	하위 기능명	핵심 요구사항 및 상세 명세
F-PO-01	발주 등록 및 변경	규격별 제작 주문서 생성. 규격, 수량, 제작 완료 예정일 등을 설정하며 발주 이후 수정 이력을 관리함
F-PO-02	LOT-No 생성 및 관리	발주 단위별 고유 LOT 번호 부여. PDF417 바코드에 포함될 원시 데이터를 생성하여 제작업체에 전달함
F-PO-03	스캐너 기반 입고 처리	제작업체로부터 납품된 박스 단위 바코드를 모바일 앱이나 스캐너로 인식하여 실제 입고량과 발주량의 매칭 검증
F-PO-04	일괄 입고 및 현황	대량 납품 시 엑셀 업로드 또는 대량 스캔을 통한 입고 처리. 인수자와 인계자의 서명 정보를 포함한 입고 현황 조회

입고 단계에서 발생하는 데이터 흐름은 실제 물류와 일치해야 함. 제작업체가 바코드를 부착하여 납품하면, 구군청 담당자는 이를 스캔함으로써 시스템상의 재고를 확정함. 이때 LOT 번호는 낱장 단위까지 추적할 수 있는 인덱스 역할을 수행하며, 이는 추후 불법 유통 방지를 위한 추적 시스템의 기반이 됨.

재고 및 실사 관리 요구사항

재고 관리는 시스템상의 장부 재고와 창고의 실물 재고를 일치시키는 과정임.

실시간 재고 가시화: 규격별, 창고별, 상태별(가용, 불출 대기, 파기 예정) 재고를 실시간으로 집계함.
다단계 실사 프로세스: 실사 대상을 선별하고, 박스 → 팩 → 낱장 순으로 상세 수량을 입력하여 오차를 분석함.
수급 계획 수립: 과거 판매 데이터를 기반으로 적정 재고 보유 일수를 설정하고, 부족분 발생 시 자동으로 발주 필요 수량을 제안함.
LOT 수불 추적: 특정 낱장 봉투 번호가 유출되거나 발견되었을 때, 해당 번호가 포함된 박스와 팩의 입출고 이력을 역추적(Tracking)함.

판매 및 결제 시스템 요구사항

판매 관리는 지정 판매소의 주문을 처리하고 대금을 정산함.

주문 채널의 다각화: 전화 접수뿐만 아니라 판매소 전용 웹/모바일 페이지를 통한 셀프 주문 기능을 제공.
가상계좌 자동 입금 매칭: 판매소별로 부여된 고유 가상계좌로 입금 시, 시스템은 PG사로부터 수신된 웹훅(Webhook) 데이터를 분석하여 주문 상태를 '결제 완료'로 자동 변경.
반품 및 취소 로직: 단순 변심 또는 폐업으로 인한 반품 시, 반품 형태와 사유를 기록하고 재고를 환원함과 동시에 대금 환급 데이터를 생성.
홈택스 연동: 판매 확정 데이터는 국세청 홈택스 시스템과 연동되어 부가가치세 신고를 위한 기초 자료로 활용.

시스템 제어 흐름 (Control Flow) 분석

본 시스템의 제어 흐름은 사용자의 요청으로부터 시작하여 비즈니스 로직 검증, 외부 API 연동, 그리고 데이터베이스 확정에 이르는 일련의 과정임.

발주 및 입고 제어 흐름

제작업체와 지자체 간의 발주 및 입고 흐름은 데이터의 무결성을 보장하기 위해 상태 전이 모델을 따름.

발주 단계: 구군 담당자가 발주서를 작성하면 상태는 ORDER_DRAFT에서 ORDER_SENT로 전이됨. 이때 바코드 생성 알고리즘이 호출되어 해당 발주 수량에 맞는 PDF417 코드 집합을 생성함.
생산 단계: 제작업체는 시스템에서 제공하는 바코드 데이터를 다운로드하여 인쇄하고 봉투를 생산함.
입고 단계: 실물이 입고되면 담당자가 스캐너를 사용하여 박스 바코드를 인식함. 시스템은 해당 바코드가 이전에 입고된 적이 없는지, 그리고 현재 발주된 LOT 번호에 속하는지 검증함.
확정 단계: 검증이 완료되면 해당 수량만큼 재고 테이블의 STOCK_QTY가 증가하며, 상태는 RECEIVED_COMPLETE로 완료됨.

판매 및 가상계좌 결제 제어 흐름

가상계좌 결제 프로세스는 외부 금융 시스템과의 비동기 통신을 포함하므로 예외 처리가 중요함.

주문 접수: 판매소가 물품을 주문하면 시스템은 주문 내역을 PAYMENT_PENDING 상태로 저장하고 가상계좌 번호를 제시함.
입금 대기: 사용자가 은행을 통해 입금하면, 은행은 PG사에 입금 사실을 알리고 PG사는 시스템의 통보 URL(Callback URL)로 HTTP POST 요청을 보냄.
검증 로직: 시스템은 수신된 데이터 중 주문 번호와 금액(A)이 DB에 저장된 주문 금액(B)과 일치하는지 비교함.
- A = B: 주문 상태를 PAID로 변경하고 출고 지시 데이터 생성.
- A ≠ B: 입금 불능 처리 또는 관리자 확인용 로그 생성(일반적으로 가상계좌는 금액 불일치 시 은행 단계에서 입금을 거부함).
출고 지시: 결제가 완료된 건에 한해 창고 담당자의 화면에 출고 대상 리스트가 노출됨.

데이터 흐름 (Data Flow) 설계

레벨 0: 컨텍스트 다이어그램 (Context Diagram)

제작업체: 발주 정보를 수신하고 납품 정보를 송신.
지정 판매소: 주문 정보를 송신하고 배송/불출 정보를 수신.
PG: 입금 데이터를 송신하고 정산 데이터를 수신.
국세청(홈택스): 세무 데이터를 수신.
구군 담당자: 시스템 설정을 수행하고 모든 통계 및 현황 데이터를 열람함.

레벨 1: 프로세스 분해 (Process Decomposition)

P1. 발주 관리 프로세스: 발주 정보를 기반으로 LOT 번호와 바코드 원시 데이터를 생성하여 데이터 저장소(D1)에 기록.
P2. 입고 및 재고 프로세스: 스캐너 입력값을 받아 D1의 재고 수치를 업데이트하고, 수불 대장(D2)에 기록을 남김.
P3. 판매 및 결제 프로세스: 주문 정보를 생성하고(D3), 금융기관의 결제 통보를 받아 주문 상태를 갱신함.
P4. 불출 관리 프로세스: 무료 대상자 정보(D4)를 참조하여 무상 지급 내역을 처리하고 재고를 차감함.
P5. 분석 및 리포팅 프로세스: D1, D2, D3의 데이터를 취합하여 전년 대비 분석 및 통계 보고서를 생성함.

UML 모델링

클래스 다이어그램 (Class Diagram)

시스템의 정적 구조를 정의하며, 각 엔티티 간의 관계를 명확히 함.

CommonCode: 시스템 전반에서 사용되는 코드(은행, 구군, 봉투 종류 등) 관리.
Product: 종량제 봉투의 규격, 용량, 단가 정보를 가짐. Inventory와 1:N 관계.
Retailer: 지정 판매소의 정보. 가상계좌 정보와 위치 정보를 속성으로 가짐.
Order: 판매소의 주문 내역. OrderItem과 1:N 관계이며 Payment와 1:1 관계를 맺음.
StockTransaction: 모든 입출고 이력(발주 입고, 판매 출고, 반품, 파기, 무료 불출)을 기록하는 통합 수불 로그.
Beneficiary: 무료용 대상자 정보. 불출 기록과 연동됨.

시퀀스 다이어그램: 스캐너 기반 입고 처리

Actor (담당자): 창고에서 박스 바코드를 스캔함.
Scanner Component: 바코드 문자열을 파싱하여 서버로 전송함.
Inbound Service: 바코드의 유효성(중복 입고 여부, 발주 LOT 포함 여부)을 검증함.
Inventory Manager: Stock 테이블의 현재 수량을 업데이트함.
Audit Logger: 입고 수행자, 일시, 바코드 번호를 로그에 기록함.
UI: 입고 성공 메시지와 현재 누적 입고 수량을 화면에 출력함.

기술 상세 설계: PDF417 바코드 아키텍처

바코드 데이터 구조 정의

바코드는 다음과 같은 가변 길이 데이터를 포함하도록 설계함.

필드명	길이(Byte)	설명
지자체 코드	5	행정 표준 코드를 기반으로 한 지자체 식별자
규격 코드	3	봉투의 종류 및 용량 식별
생산 연도	2	생산 연도의 마지막 두 자리
LOT 번호	6	발주 시 부여된 고유 생산 묶음 번호
일련번호	10	해당 LOT 내에서의 개별 일련번호
체크섬	4	데이터 변조 방지를 위한 오류 검출 코드

오류 정정 및 인식 최적화

PDF417은 Reed-Solomon 오류 정정 알고리즘을 사용하여 바코드의 일부가 훼손되더라도 판독이 가능함. 본 시스템에서는 유통 환경의 열악함을 고려하여:

Error Correction Level (ECL): 레벨 4 또는 5 권장. 바코드 면적의 약 25~35%가 손상되어도 데이터 복구 가능.
Aspect Ratio: 1:3 ~ 1:5 가로세로 비율 유지.
X-Dimension: 최소 0.254mm (10 mils) 이상.

결제 및 정산 시스템 통합 설계

가상계좌 자동 정산 로직

1:1 가상계좌 매핑: 각 지정 판매소는 고유한 가상계좌를 부여받거나, 주문마다 일회용 가상계좌를 부여함(PG). 본 시스템은 판매소별 고정 가상계좌 방식을 채택함.
실시간 웹훅(Webhook) 처리: PG사로부터 입금 데이터 수신 시, 서버는 즉시 해당 판매소의 최신 주문 내역 중 PAYMENT_PENDING 상태인 건을 조회함.
금액 검증: 입금된 금액이 주문 합계와 정확히 일치할 때만 승인 처리함. ( V_{deposit} = \sum (Q_{item} \times P_{unit}) )
입금 기한 관리: 배송 전일 특정 시간(예: 23:00)까지 입금이 확인되지 않은 주문은 다음 차수로 자동 이월하거나 취소 처리함.

세무 및 통계 데이터 생성

부가가치세 계산: 카드 결제 및 가상계좌 입금액 중 과세 대상 금액을 자동 산출하여 홈택스 연동용 파일로 생성함.
다차원 분석: 전년 대비 판매 분석, 월별/계절별 판매 추이 분석 기능을 통해 지자체의 예산 수립 및 수급 계획을 지원함.

UI/UX 및 웹 표준 설계

반응형 웹 디자인: 구군청 PC뿐만 아니라 현장 담당자의 태블릿, 판매소 운영자의 스마트폰에서도 최적화된 화면 제공.
데이터 시각화: 재고 부족 규격이나 입금 지연 현황을 대시보드에서 차트와 색상(위험 시 적색 노출)으로 가시화함.
검색 및 필터링 최적화: 초성 검색, 지역별 필터, GIS 기반 지도 검색 기능.
인쇄 제어: 바코드 라벨 및 보고서 인쇄 시 PDF 생성 라이브러리를 통한 서버 측 렌더링(SSR) 방식 사용.

제안하는 추가 설계 문서

보안 및 개인정보 처리 설계서: 개인정보 DB 암호화·화면 마스킹, RBAC, 감사 로그(Audit Trail).
API 정의서 및 인터페이스 설계서: PG·홈택스·GIS 연동, RESTful API 규약.
데이터 이관(Migration) 설계서: 레거시 데이터 정제·매핑, 재고 초기화 일괄 업로드.
인프라 및 배포 설계서: 클라우드 아키텍처, CI/CD.

14 KiB Raw Blame History