종량제 — 쓰레기봉투 물류시스템 (jongryangje)

종량제 개발목록 (엑셀 다운로드) — 로컬 복제 후에는 assets/종량제_개발목록_20260127.xlsx

지자체·지정판매소 등을 대상으로 하는 종량제 쓰레기봉투 물류·업무 웹 애플리케이션입니다. 백엔드는 CodeIgniter 4 기반입니다.

저장소: wixon-associates/jongryangje | 구현 화면 스크린샷 | Notion 진행상황 |

---

기술 스택

항목	기술
Framework	CodeIgniter 4.7+
Language	PHP 8.2+ (strict types)
Database	MySQL / MariaDB (MySQLi)
의존성 관리	Composer 2.x
테스트	PHPUnit 10.x
세션	파일 기반 (writable/session/)

---

요구 사항

• PHP 8.2 이상 (composer.json 기준)
• Composer 2.x
• MySQL / MariaDB (프로젝트는 MySQLi 드라이버 사용)
• 권장 PHP 확장: intl, mbstring, MySQL 사용 시 mysqlnd

---

빠른 시작 (로컬)

1) 저장소 복제

git clone https://github.com/wixon-associates/jongryangje.git
cd jongryangje

2) 의존성 설치

composer install

3) 환경 설정

루트에 있는 샘플 파일을 복사해 .env를 만듭니다.

cp env .env

.env에서 최소한 다음을 설정합니다.

항목	설명
app.baseURL	예: http://localhost:8080/ (끝에 /)
database.default.*	DB 호스트·DB명·사용자·비밀번호
encryption.key	개인정보(이메일·연락처) 암호화용. 64자리 hex (예: php -r "echo bin2hex(random_bytes(32));")

.env는 Git에 올리지 마세요. 비밀번호·키가 들어갑니다.

4) 데이터베이스 준비

아래 순서대로 SQL 스크립트를 실행합니다.

순서	파일	용도
1	writable/database/init_jongryangje_dev.sql	DB·DB 사용자 생성
2	writable/database/login_tables.sql	회원·로그인·지자체·지정판매소 기본 테이블
3	writable/database/member_approval_request_add.sql	회원가입 역할 승인 요청 테이블
4	writable/database/menu_tables.sql	메뉴 시스템 (메뉴 타입 + 메뉴 항목 + 시드)
5	writable/database/local_government_init_daegu.sql	대구 시범 지자체 데이터
6	writable/database/code_master_init_daegu.sql	기본코드 마스터 초기화

5) 개발 서버 실행

php spark serve --port=8045

6) 테스트

vendor/bin/phpunit

---

프로젝트 구조

app/
├── Config/          # Routes, Database, Roles, Filters, Session 등
├── Controllers/     # Home, Auth, Admin/* (8개 관리자 컨트롤러)
├── Models/          # 7개 모델 (Member, LocalGovernment, DesignatedShop 등)
├── Views/           # admin/, auth/, bag/, home/ 템플릿
├── Filters/         # AdminAuthFilter (관리자 접근 제어)
├── Helpers/         # admin_helper, pii_encryption_helper
└── Database/        # Migrations, Seeds
public/              # 웹 루트
writable/database/   # SQL 초기화 스크립트
tests/               # unit/, database/, session/
assets/              # 기획 문서 (엑셀)

---

역할 체계 (RBAC)

Level	역할	설명
4	Super Admin	전체 시스템 관리, 작업 지자체 선택 필수
3	지자체관리자	소속 지자체 범위 내 관리
2	지정판매소	봉투 판매/재고 관리
1	일반 사용자	기본 조회 (시민)

• 역할 상수: Config\Roles — LEVEL_SUPER_ADMIN(4), LEVEL_LOCAL_ADMIN(3), LEVEL_SHOP(2), LEVEL_CITIZEN(1)
• AdminAuthFilter가 로그인 + 레벨 3/4 + 지자체 선택 여부 검증

멀티테넌시

• local_government.lg_idx 가 테넌트 루트
• 관리자 필터에서 session('admin_lg_idx') 기반 테넌트 분리
• Super Admin은 /admin/select-local-government에서 작업 지자체 선택

---

주요 URL

경로	설명	인증
/	홈 (비로그인 시 환영 화면)	공개
/login, /logout	로그인·로그아웃	공개
/register	회원가입 (역할 승인 플로우 연동)	공개
/dashboard	로그인 후 메인 대시보드	인증
/dashboard/classic-mock 등	UI 시안용 라우트	인증
/bag/*	봉투 관련 페이지 (목업)	인증
/admin	관리자 대시보드	관리자 (Lv.3+)
/admin/users	회원 관리 (CRUD)	관리자
/admin/access/login-history	로그인 이력 조회	관리자
/admin/access/approvals	회원가입 역할 승인 대기 처리	관리자
/admin/roles	역할 목록 조회	관리자
/admin/menus	메뉴 관리 (트리 구조 CRUD)	관리자
/admin/local-governments	지자체 관리	관리자
/admin/designated-shops	지정판매소 관리 (CRUD)	관리자
/admin/select-local-government	작업 지자체 선택	Super Admin

정확한 라우트는 app/Config/Routes.php를 확인하세요.

---

DB 테이블

테이블	용도
member	회원 (mb_id, mb_level, mb_state, PII 암호화)
member_log	로그인/로그아웃 감사 로그 (IP, User-Agent)
member_approval_request	회원가입 승인 요청 (pending/approved/rejected)
local_government	지자체 (테넌트 루트)
designated_shop	지정판매소 (지자체별 관리)
menu_type	메뉴 유형 (admin, site)
menu	메뉴 항목 (트리 구조, 역할별 노출)

---

기본코드 체계

개발목록 엑셀의 "기본코드 종류" 시트 기준, A~Y 총 25종의 코드 체계:

코드	코드명	코드	코드명
A	도/특별시/광역시 구분	N	동판종류
B	특별시/광역시/시/군코드	O	봉투명
C	구코드	P	작업권한
D	동코드	Q	예산과목
E	봉투구분 (일반/공공/무료/공동주택/재사용/음식물)	R	은행목록
F	봉투재질 (고밀도/PP마대/스티커/용기)	S	소속
G	용량별 (2L120L, 1000원10000원)	T	직위
H	무상지급 대상	U	배달
I	판매형태 (무상/일반/관내/교환)	V	구역
J	반품형태	W	봉투명(약어)
K	반품사유	X	봉투구분(대분)
L	지정판매소 변경사유	Y	분기
M	수불구분

---

개발 현황

웹 기능목록 (63개 항목)

기획 문서(assets/종량제_개발목록_20260127.xlsx)의 "웹 기능목록" 시트 기준으로 정리합니다.

구현 완료

No	카테고리	기능	상태	비고
1	공통	로깅 (로그인/로그아웃 이력)	완료	member_log 테이블, IP/UA 기록
2	공통	개인정보 비식별화	완료	pii_encryption_helper (ENC: prefix, AES 암호화)
3	공통	로그인	부분	로그인/세션/역할별 리다이렉트 완료. 2차 인증 미구현, 5회 실패 lock 미구현
4	관리자단	사용자 권한 관리	완료	4단계 RBAC, Config 기반
5	관리자단	사용자 관리	완료	Full CRUD + soft delete + PII 암복호화
6	관리자단	사용자 로그인 이력 확인	완료	기간 지정 조회 구현
7	관리자단	사용자 권한 승인	완료	승인/거절 + 사유 입력 + 트랜잭션 처리
8	관리자단	메뉴 관리	완료	트리 구조 CRUD, 지자체별 메뉴 복사
9	관리자단	메뉴 별 권한 설정	완료	mm_level 필드로 역할별 노출 제어
25	기본정보관리	지정판매소 관리 (리스트/상세)	완료	지자체별 필터링, 판매소 정보 표시
26	기본정보관리	지정판매소 등록/수정/삭제	완료	Full CRUD, 판매소번호 자동생성
29	기본정보관리	PASSWORD 변경	미구현

미구현 — 기본정보관리 (SFR-PWB-003)

No	기능	설명
10-11	기본코드 관리	코드 종류 및 하위 세부코드 CRUD
12-13	단가 관리	지자체별 봉투 종류별 단가 CRUD, 이력 관리, 기간별 조회
14-15	포장 단위 관리	박스당 팩/팩당 낱장 수량 CRUD, 기간별 조회
16-18	판매 대행소 관리	대행소 CRUD, 지자체 연결, 조회
19-20	담당자 관리	지자체별 담당자 CRUD (소속: 구/군/대행소/제작업체)
21-22	업체 관리	협회/제작업체/회수업체 CRUD, 조회/인쇄
23-24	무료용 대상자 관리	읍면동/무료대상자/기타 구분별 CRUD
27	지정판매소 지도	지정판매소 지도상 위치 확인
28	지정판매소 조회	다조건 조회, 엑셀 저장, 인쇄, 바코드 출력
29	지정판매소 현황	연도별 신규등록/취소 현황 조회
29	PASSWORD 변경	현재 로그인 사용자 비밀번호 변경

미구현 — 발주 입고 관리 (SFR-PWB-004)

No	기능	설명
30	발주 등록	발주 form (UUID v4 + SHA-256 해싱 + 블록 저장), LOT 번호 생성
31	LOT번호 및 바코드 생성	AES-256 + RSA 암호화 seed → PDF417 바코드 생성
32	발주 변경	동일 UUID 버전 관리, 해시 체인
33	발주 삭제	상태 변경 방식 삭제
34	발주 현황	기간/제작업체/품명/입고처 조건 조회, 리포트
35	발주 입고 (스캐너)	바코드 스캐너 연동 (Electron + serialport)
36	발주 입고 (스캐너)	제작업체별 미입고 발주 조회, 스캔 입고 처리
37	일괄 입고	LOT 단위 전체 입고 처리
38	입고 현황	기간/업체/품명/구분별 조회, 리포트

미구현 — 불출 관리 (SFR-PWB-005)

No	기능	설명
39	무료용 불출 현황	기간별 봉투 종류별 불출 현황 조회
40	무료용 불출 처리	불출 기록, 바코드 스캔, 재고 감산, 판매 처리
41	무료용 불출 취소	불출 리스트/품목/코드 3분할 화면, 취소 후 재고 복원

미구현 — 재고/실사 관리 (SFR-PWB-006~007)

No	기능	설명
42	재고 조회	기준일자 봉투/스티커 종류별 재고량, 결재란 인쇄
43	실사 선별	바코드 있는 봉투 대상 실사 실시
44	실사 선별 조회	전체→박스→팩→낱장 drill-down 조회

미구현 — 주문/판매 관리 (SFR-PWB-008)

No	기능	설명
45	주문 접수 관리 메인	접수 리스트, 상세, 전화 주문 접수 3분할 화면
46	전화 주문 접수	판매소 자동완성 검색, 가상계좌 안내, 포장단위 자동 계산
47	전화 접수 수정/취소	접수량 수정, 상태 변경 방식 취소
48	지정판매소 판매	바코드 스캔 판매 처리, 중복 스캔 방지
49	지정판매소 판매 취소	품목별/봉투코드별 선택 취소
50	지정판매소 반품	바코드 스캔 반품 처리
51	지정판매소 반품 취소	반품 취소 → 판매 상태 복원

미구현 — 판매 현황 (SFR-PWB-009)

No	기능	설명
52	판매 대장	일자별/기간별 집계, 수수료/총액, 결재란 인쇄
53	일계표	일계 + 월간 누계 (판매수량/금액/수수료/징수액)
54	기간별 판매현황	일자별/기간별 판매+반품+계, 봉투계/스티커계 소계
55	년 판매 현황	월별/분기별 품목별 판매
56	지정판매소별 판매현황	읍면동별, 수량/금액 집계, 1~12월 컬럼
57	홈택스 처리	세금계산서 일괄발급 엑셀 양식 생성

미구현 — 봉투 수불 관리 (SFR-PWB-010)

No	기능	설명
58	기타 입출고	상세 기능 확인 필요
59	봉투 수불 현황	전일재고/입고/출고/잔량, 일자별/기간별
60	반품/파기 현황	기간별 입출고 구분 조회
61	봉투 수급 계획	기능 확인 필요 (추가 발주 예정일 산출 방식 불명확)
62	LOT 수불 조회	바코드 스캔으로 개별 봉투 수불 이력 조회

미구현 — 봉투 스캔 (SFR-PWB-011)

No	기능	설명
63	봉투 스캔 현황	앱 바코드 스캔 횟수 확인, 경위도 위치 지도 표시

모바일앱 기능목록 (15개 항목) — 전체 미구현

No	카테고리	기능
1-3	공통	로깅, 개인정보 비식별화, 로그인 (2차인증)
4	발주 입고	PDF417 스캐너 연동 입고 처리
5-6	불출 관리	무료용/공공용 불출 처리/취소
7-8	판매 관리	지정판매소 판매/판매취소
9-10	판매 관리	지정판매소 반품/반품취소
11	봉투 수불	LOT 수불 조회
12-14	봉투 주문	주문 내역/주문/주문 수정·취소
15	정품 인증	PDF417 스캐너 봉투 정품 인증

전체 메뉴 구조

개발목록 엑셀의 "전체 메뉴" 시트 기준, 10개 대메뉴:

기본정보관리 ─ 기본코드, 단가, 포장단위, 대행소, 담당자, 업체, 무료대상자, 지정판매소, 환경설정
발주 입고 관리 ─ 발주 등록/변경, LOT, 발주현황, 입고(스캐너/일괄), 입고현황
불출 관리 ─ 무료 불출 현황/처리/취소
재고 관리 ─ 재고현황, 실사(선별/등록/조회/오류/취소)
판매 관리 ─ 전화접수, 판매소 판매/반품/취소
판매 현황 ─ 판매대장, 일계표, 기간별/년/판매소별 현황, 홈택스
봉투 수불 관리 ─ 기타 입출고, 수불현황, 반품/파기, 수급계획, LOT 수불
통계 분석 관리 ─ 전년대비, 월별/계절별 추이 분석

---

개발 진행 요약

구분	항목 수	완료	부분완료	미구현
공통	3	2	1	0
관리자단	6	6	0	0
기본정보관리	20	2	0	18
발주 입고 관리	9	0	0	9
불출 관리	3	0	0	3
재고/실사 관리	3	0	0	3
주문/판매 관리	7	0	0	7
판매 현황	6	0	0	6
봉투 수불 관리	5	0	0	5
봉투 스캔	1	0	0	1
웹 합계	63	10	1	52
모바일앱	15	0	0	15
전체 합계	78	10	1	67

현재 진척율: 약 13% (웹 기준 약 16%)

---

향후 개발 로드맵

Phase 2 — 기본정보관리 완성

• 기본코드 종류/세부코드 관리 (CRUD)
• 지자체별 봉투 단가 관리 + 이력 관리
• 포장 단위 관리 (박스/팩/낱장 체계)
• 판매 대행소 관리 + 지자체 연결
• 담당자 관리, 업체 관리 (협회/제작업체/회수업체)
• 무료용 대상자 관리
• 지정판매소 다조건 조회 + 엑셀 저장 + 인쇄 + 바코드 출력
• 지정판매소 현황 (신규/취소) + 지도 표시
• 지자체 수정/삭제 기능
• PASSWORD 변경 기능
• 로그인 5회 실패 lock 처리

Phase 3 — 발주·입고·재고 핵심

• 발주 등록 (UUID v4 + SHA-256 해싱 + 블록)
• LOT 번호 생성 + PDF417 바코드 (AES-256 + RSA)
• 발주 변경/삭제 (버전 관리)
• 발주 현황 리포트
• 발주 입고 처리 (바코드 스캐너 / 일괄 입고)
• 재고 조회 + 결재란 인쇄
• 실사 선별 / 등록 / 조회

Phase 4 — 주문·판매·불출

• 전화 주문 접수 + 자동완성 검색
• 주문 수정/취소
• 지정판매소 판매 처리 (바코드 스캔)
• 판매 취소, 반품, 반품 취소
• 무료용 불출 현황/처리/취소

Phase 5 — 현황·리포트·수불

• 판매 대장 (일자별/기간별)
• 일계표, 기간별 판매현황, 년 판매 현황
• 지정판매소별 판매현황 (수량/금액)
• 홈택스 세금계산서 엑셀 생성
• 봉투 수불 현황 (전일재고/입고/출고/잔량)
• 반품/파기 현황, LOT 수불 조회

Phase 6 — 모바일앱

• 앱 공통 (로그인, 2차인증, PII)
• 발주 입고 (PDF417 카메라 스캔)
• 불출 관리 (카메라 스캔)
• 판매/반품 처리 (카메라 스캔)
• 봉투 주문/주문 수정·취소
• 봉투 정품 인증

공통 기술 과제

• 2차 인증 적용
• 페이지네이션 구현
• 엑셀 저장/인쇄 공통 컴포넌트
• 바코드 스캐너 연동 (Electron + serialport)
• 카카오 주소 검색 API 연동
• CRUD 로깅 (전체 데이터 변경 이력)
• 대시보드 실 데이터 연동