193 lines
14 KiB
Markdown
193 lines
14 KiB
Markdown
|
# 종량제봉투 웹 플랫폼 개발 (노션 정리)
|
||
|
|
|
||
|
|
> 출처: 차장님 노션 정리. 업무 요구사항 정의, 기능 분석, 제어/데이터 흐름, 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 번호**는 낱장 단위까지 추적할 수 있는 인덱스 역할을 수행하며, 이는 추후 불법 유통 방지를 위한 추적 시스템의 기반이 됨.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 재고 및 실사 관리 요구사항
|
||
|
|
|
||
|
|
재고 관리는 시스템상의 장부 재고와 창고의 실물 재고를 일치시키는 과정임.
|
||
|
|
|
||
|
|
1. **실시간 재고 가시화**: 규격별, 창고별, 상태별(가용, 불출 대기, 파기 예정) 재고를 실시간으로 집계함.
|
||
|
|
2. **다단계 실사 프로세스**: 실사 대상을 선별하고, 박스 → 팩 → 낱장 순으로 상세 수량을 입력하여 오차를 분석함.
|
||
|
|
3. **수급 계획 수립**: 과거 판매 데이터를 기반으로 적정 재고 보유 일수를 설정하고, 부족분 발생 시 자동으로 발주 필요 수량을 제안함.
|
||
|
|
4. **LOT 수불 추적**: 특정 낱장 봉투 번호가 유출되거나 발견되었을 때, 해당 번호가 포함된 박스와 팩의 입출고 이력을 역추적(Tracking)함.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 판매 및 결제 시스템 요구사항
|
||
|
|
|
||
|
|
판매 관리는 지정 판매소의 주문을 처리하고 대금을 정산함.
|
||
|
|
|
||
|
|
- **주문 채널의 다각화**: 전화 접수뿐만 아니라 판매소 전용 웹/모바일 페이지를 통한 셀프 주문 기능을 제공.
|
||
|
|
- **가상계좌 자동 입금 매칭**: 판매소별로 부여된 고유 가상계좌로 입금 시, 시스템은 PG사로부터 수신된 **웹훅(Webhook)** 데이터를 분석하여 주문 상태를 '결제 완료'로 자동 변경.
|
||
|
|
- **반품 및 취소 로직**: 단순 변심 또는 폐업으로 인한 반품 시, 반품 형태와 사유를 기록하고 재고를 환원함과 동시에 대금 환급 데이터를 생성.
|
||
|
|
- **홈택스 연동**: 판매 확정 데이터는 국세청 홈택스 시스템과 연동되어 부가가치세 신고를 위한 기초 자료로 활용.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 시스템 제어 흐름 (Control Flow) 분석
|
||
|
|
|
||
|
|
본 시스템의 제어 흐름은 사용자의 요청으로부터 시작하여 비즈니스 로직 검증, 외부 API 연동, 그리고 데이터베이스 확정에 이르는 일련의 과정임.
|
||
|
|
|
||
|
|
### 발주 및 입고 제어 흐름
|
||
|
|
|
||
|
|
제작업체와 지자체 간의 발주 및 입고 흐름은 데이터의 무결성을 보장하기 위해 **상태 전이 모델**을 따름.
|
||
|
|
|
||
|
|
1. **발주 단계**: 구군 담당자가 발주서를 작성하면 상태는 `ORDER_DRAFT`에서 `ORDER_SENT`로 전이됨. 이때 바코드 생성 알고리즘이 호출되어 해당 발주 수량에 맞는 PDF417 코드 집합을 생성함.
|
||
|
|
2. **생산 단계**: 제작업체는 시스템에서 제공하는 바코드 데이터를 다운로드하여 인쇄하고 봉투를 생산함.
|
||
|
|
3. **입고 단계**: 실물이 입고되면 담당자가 스캐너를 사용하여 박스 바코드를 인식함. 시스템은 해당 바코드가 이전에 입고된 적이 없는지, 그리고 현재 발주된 LOT 번호에 속하는지 검증함.
|
||
|
|
4. **확정 단계**: 검증이 완료되면 해당 수량만큼 재고 테이블의 `STOCK_QTY`가 증가하며, 상태는 `RECEIVED_COMPLETE`로 완료됨.
|
||
|
|
|
||
|
|
### 판매 및 가상계좌 결제 제어 흐름
|
||
|
|
|
||
|
|
가상계좌 결제 프로세스는 외부 금융 시스템과의 비동기 통신을 포함하므로 예외 처리가 중요함.
|
||
|
|
|
||
|
|
1. **주문 접수**: 판매소가 물품을 주문하면 시스템은 주문 내역을 `PAYMENT_PENDING` 상태로 저장하고 가상계좌 번호를 제시함.
|
||
|
|
2. **입금 대기**: 사용자가 은행을 통해 입금하면, 은행은 PG사에 입금 사실을 알리고 PG사는 시스템의 통보 URL(Callback URL)로 HTTP POST 요청을 보냄.
|
||
|
|
3. **검증 로직**: 시스템은 수신된 데이터 중 주문 번호와 금액(A)이 DB에 저장된 주문 금액(B)과 일치하는지 비교함.
|
||
|
|
- **A = B**: 주문 상태를 `PAID`로 변경하고 출고 지시 데이터 생성.
|
||
|
|
- **A ≠ B**: 입금 불능 처리 또는 관리자 확인용 로그 생성(일반적으로 가상계좌는 금액 불일치 시 은행 단계에서 입금을 거부함).
|
||
|
|
4. **출고 지시**: 결제가 완료된 건에 한해 창고 담당자의 화면에 출고 대상 리스트가 노출됨.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 데이터 흐름 (Data Flow) 설계
|
||
|
|
|
||
|
|
### 레벨 0: 컨텍스트 다이어그램 (Context Diagram)
|
||
|
|
|
||
|
|
- **제작업체**: 발주 정보를 수신하고 납품 정보를 송신.
|
||
|
|
- **지정 판매소**: 주문 정보를 송신하고 배송/불출 정보를 수신.
|
||
|
|
- **PG**: 입금 데이터를 송신하고 정산 데이터를 수신.
|
||
|
|
- **국세청(홈택스)**: 세무 데이터를 수신.
|
||
|
|
- **구군 담당자**: 시스템 설정을 수행하고 모든 통계 및 현황 데이터를 열람함.
|
||
|
|
|
||
|
|
### 레벨 1: 프로세스 분해 (Process Decomposition)
|
||
|
|
|
||
|
|
1. **P1. 발주 관리 프로세스**: 발주 정보를 기반으로 LOT 번호와 바코드 원시 데이터를 생성하여 데이터 저장소(D1)에 기록.
|
||
|
|
2. **P2. 입고 및 재고 프로세스**: 스캐너 입력값을 받아 D1의 재고 수치를 업데이트하고, 수불 대장(D2)에 기록을 남김.
|
||
|
|
3. **P3. 판매 및 결제 프로세스**: 주문 정보를 생성하고(D3), 금융기관의 결제 통보를 받아 주문 상태를 갱신함.
|
||
|
|
4. **P4. 불출 관리 프로세스**: 무료 대상자 정보(D4)를 참조하여 무상 지급 내역을 처리하고 재고를 차감함.
|
||
|
|
5. **P5. 분석 및 리포팅 프로세스**: D1, D2, D3의 데이터를 취합하여 전년 대비 분석 및 통계 보고서를 생성함.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## UML 모델링
|
||
|
|
|
||
|
|
### 클래스 다이어그램 (Class Diagram)
|
||
|
|
|
||
|
|
시스템의 정적 구조를 정의하며, 각 엔티티 간의 관계를 명확히 함.
|
||
|
|
|
||
|
|
- **CommonCode**: 시스템 전반에서 사용되는 코드(은행, 구군, 봉투 종류 등) 관리.
|
||
|
|
- **Product**: 종량제 봉투의 규격, 용량, 단가 정보를 가짐. Inventory와 1:N 관계.
|
||
|
|
- **Retailer**: 지정 판매소의 정보. 가상계좌 정보와 위치 정보를 속성으로 가짐.
|
||
|
|
- **Order**: 판매소의 주문 내역. OrderItem과 1:N 관계이며 Payment와 1:1 관계를 맺음.
|
||
|
|
- **StockTransaction**: 모든 입출고 이력(발주 입고, 판매 출고, 반품, 파기, 무료 불출)을 기록하는 통합 수불 로그.
|
||
|
|
- **Beneficiary**: 무료용 대상자 정보. 불출 기록과 연동됨.
|
||
|
|
|
||
|
|
### 시퀀스 다이어그램: 스캐너 기반 입고 처리
|
||
|
|
|
||
|
|
1. **Actor (담당자)**: 창고에서 박스 바코드를 스캔함.
|
||
|
|
2. **Scanner Component**: 바코드 문자열을 파싱하여 서버로 전송함.
|
||
|
|
3. **Inbound Service**: 바코드의 유효성(중복 입고 여부, 발주 LOT 포함 여부)을 검증함.
|
||
|
|
4. **Inventory Manager**: Stock 테이블의 현재 수량을 업데이트함.
|
||
|
|
5. **Audit Logger**: 입고 수행자, 일시, 바코드 번호를 로그에 기록함.
|
||
|
|
6. **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:1 가상계좌 매핑**: 각 지정 판매소는 고유한 가상계좌를 부여받거나, 주문마다 일회용 가상계좌를 부여함(PG). 본 시스템은 **판매소별 고정 가상계좌** 방식을 채택함.
|
||
|
|
2. **실시간 웹훅(Webhook) 처리**: PG사로부터 입금 데이터 수신 시, 서버는 즉시 해당 판매소의 최신 주문 내역 중 `PAYMENT_PENDING` 상태인 건을 조회함.
|
||
|
|
3. **금액 검증**: 입금된 금액이 주문 합계와 정확히 일치할 때만 승인 처리함. \( V_{deposit} = \sum (Q_{item} \times P_{unit}) \)
|
||
|
|
4. **입금 기한 관리**: 배송 전일 특정 시간(예: 23:00)까지 입금이 확인되지 않은 주문은 다음 차수로 자동 이월하거나 취소 처리함.
|
||
|
|
|
||
|
|
### 세무 및 통계 데이터 생성
|
||
|
|
|
||
|
|
- **부가가치세 계산**: 카드 결제 및 가상계좌 입금액 중 과세 대상 금액을 자동 산출하여 홈택스 연동용 파일로 생성함.
|
||
|
|
- **다차원 분석**: 전년 대비 판매 분석, 월별/계절별 판매 추이 분석 기능을 통해 지자체의 예산 수립 및 수급 계획을 지원함.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## UI/UX 및 웹 표준 설계
|
||
|
|
|
||
|
|
1. **반응형 웹 디자인**: 구군청 PC뿐만 아니라 현장 담당자의 태블릿, 판매소 운영자의 스마트폰에서도 최적화된 화면 제공.
|
||
|
|
2. **데이터 시각화**: 재고 부족 규격이나 입금 지연 현황을 대시보드에서 차트와 색상(위험 시 적색 노출)으로 가시화함.
|
||
|
|
3. **검색 및 필터링 최적화**: 초성 검색, 지역별 필터, GIS 기반 지도 검색 기능.
|
||
|
|
4. **인쇄 제어**: 바코드 라벨 및 보고서 인쇄 시 **PDF 생성 라이브러리를 통한 서버 측 렌더링(SSR)** 방식 사용.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 제안하는 추가 설계 문서
|
||
|
|
|
||
|
|
1. **보안 및 개인정보 처리 설계서**: 개인정보 DB 암호화·화면 마스킹, RBAC, 감사 로그(Audit Trail).
|
||
|
|
2. **API 정의서 및 인터페이스 설계서**: PG·홈택스·GIS 연동, RESTful API 규약.
|
||
|
|
3. **데이터 이관(Migration) 설계서**: 레거시 데이터 정제·매핑, 재고 초기화 일괄 업로드.
|
||
|
|
4. **인프라 및 배포 설계서**: 클라우드 아키텍처, CI/CD.
|