jongryangje/docs/기본 개발계획/06-development-plan.md

# 종량제 프로젝트 개발 계획

앞으로의 개발 순서와 단계별 목표를 정리한 문서입니다.  
기능 상세는 `01-web-features.md`, 권한·개요는 `00-project-overview.md`를 참고합니다.

---

## 0. 참조 프로젝트·환경·정책

### 0.1 참조 프로젝트: slow-auth-application

- **위치**: `PhpstormProjects/slow-auth-application` (jongryangje와 동일 상위 폴더)
- **역할**: **admin 단(메뉴관리, 회원관리)** 을 이 프로젝트 구조를 참고해 가져와 개발을 시작한다.
- **auth 구조 요약**:
  - **프레임워크**: CodeIgniter 3 (jongryangje는 CI4 + PHP 8)
  - **베이스 컨트롤러**: `SL_Controller` — 로그인 체크, `_setting_view()` 로 레이아웃(header + sidebar + page) 출력
  - **admin 경로**: `setting/` — `setting/Menu`(메뉴 관리), `setting/Member`(회원 관리)
  - **레이아웃**: `layout_main_v` — App__sidebar + App_container(header + 본문), sidebar에 권한별 메뉴
  - **모델 네이밍**: `Menu_m`, `Member_m`, `Define_m` — 테이블 `menu`, `member` 등, 컬럼 `mm_idx`, `mb_idx` 등 짧은 식별자
  - **뷰**: `setting/menu/main_v`, `setting/member/list_v`, `write_v` 등
- **jongryangje 적용**: CI4 구조로 옮기되, **기능(메뉴 CRUD, 회원 CRUD, 권한별 메뉴 노출)** 과 **화면 흐름**은 auth와 맞춘다. PHP 버전·프레임워크가 다르므로 코드를 그대로 복사하지 않고 동작을 이식한다.

### 0.2 개발 환경

- **서버**: 아직 미정. 테스트 서버는 대구사장님과 협의 후 결정 예정.
- **당분간**: 개발자 **로컬에 DB까지 설정**하여 진행. 상세 절차는 **`07-local-db-setup.md`** 참고.

### 0.3 프론트엔드·디자인

- **Stitch(Google)**: UI 디자인·시안에 활용. 기존 화면 스크린샷을 올려 “웹 전환·최신 스타일” 시안 요청 가능.
- **admin 디자인**: 현재 auth admin 그대로 사용해도 되고, 필요 시 Stitch에 admin 화면 스크린샷 올려 프론트 시안 후 적용 가능.

### 0.4 메뉴 통합 방향

- 전체 메뉴는 `04-menu-structure.md` 1차 정리 기준으로 하되, **화면 수는 줄여서** 개발한다.
- **예시**:
  - **무료용 불출**: “무료용 불출 현황” 한 화면에서 **불출 처리 / 불출 취소** 함께 처리.
  - **판매관리**: 전화 접수·지정판매소 판매·취소·반품 등을 **한 화면 또는 소수 탭/섹션**으로 묶어 처리.
- 상세 설계 시 메뉴별로 “한 화면에서 처리 가능한 것”을 묶어 세분화된 메뉴 수를 줄인다.

### 0.5 우선 진행 순서(요약)

1. **로컬 DB 설정** — MariaDB 등으로 `jongryangje_dev` DB·사용자 생성.
2. **Phase 1** — 로그인·로그아웃·세션.
3. **Phase 2** — auth의 admin(메뉴관리, 회원관리)을 CI4로 이식하여 관리자 화면·권한별 메뉴 구성.
4. 이후 Phase 3(기본정보)부터 기능 목록 순으로 진행.

---

## 1. 개발 원칙

- **의존 관계 우선**: 다른 기능이 참조하는 기반(로그인·권한·기본정보)을 먼저 구현한다.
- **웹 우선**: 웹 기능을 먼저 진행하고, 모바일앱은 웹 API·데이터가 안정된 뒤 진행한다.
- **단계별 검증**: 각 단계 완료 시 로그인·권한·메뉴와 연동해 동작을 확인한다.

---

## 2. 코딩 컨벤션·네이밍

- **auth와의 일관성**: 프로젝트 구조·화면 흐름·역할은 slow-auth-application과 맞추되, **CI4·PHP 8 문법**에 맞게 작성한다. (네임스페이스, PSR-4, CI4 Controller/Model 규칙.)
- **변수명·클래스명**: **너무 길지 않게** 한다. auth처럼 `mm_idx`, `mb_idx`, `get_item`, `insert_item` 같은 짧은 이름을 선호한다.
- **컨트롤러/모델**: CI4 규칙에 따라 `PascalCase`(예: `Menu`, `Member`, `MenuModel`, `MemberModel`). 내부 변수·메서드는 `camelCase` 또는 auth 스타일 짧은 식별자(`midx`, `list`, `write`) 혼용 가능.
- **DB 컬럼**: auth와 유사하게 `mm_idx`, `mb_id`, `mb_name` 등 약어 사용 시 일관성 유지. 새 테이블도 과도하게 긴 컬럼명은 지양.

---

## 3. 단계별 개발 계획

### Phase 1: 공통·인증 (PWB-010000)

**목표**: 로그인·세션·최소 보안과 로깅 기반을 갖춘다.

| 순서 | 작업 | 참조 ID | 비고 |
|------|------|---------|------|
| 1-1 | 로그인 | PWB-010301-001 | 아이디/비밀번호, 세션. 2차인증·5회 실패 lock은 2단계에서 |
| 1-2 | 로그아웃 | — | 세션 파기 |
| 1-3 | 작업 이력/로깅 | PWB-010101-001 | DB CRUD 로깅(최소: 로그인 이력) |
| 1-4 | 개인정보 비식별화 | PWB-010201-001 | 이름·휴대전화 마스킹 규칙 적용 |

**산출물**: 로그인/로그아웃 동작, 사용자·권한 테이블 설계(Phase 2와 연계).

---

### Phase 2: 관리자·메뉴 (PWB-020000)

**목표**: **slow-auth-application의 admin 단(메뉴관리, 회원관리)을 CI4로 이식**하여, 권한별 사용자와 메뉴 접근 제어를 구현한다.

| 순서 | 작업 | 참조 ID | 비고 |
|------|------|---------|------|
| 2-1 | 메뉴 관리 | PWB-020401-001 | auth `setting/Menu` 참고. 메뉴 등록/수정/삭제/순서, `04-menu-structure.md` 반영 |
| 2-2 | 메뉴별 권한 설정 | PWB-020401-001 | 메뉴별 접근 가능 권한(레벨·그룹) 매핑, sidebar 권한별 노출 |
| 2-3 | 사용자 권한 관리 | PWB-020101-001 | super admin·지자체·지정판매소·일반 등 권한(레벨/그룹) CRUD |
| 2-4 | 사용자 관리 | PWB-020201-001 | auth `setting/Member` 참고. 사용자 등록/수정/삭제(삭제 상태 5년 유지) |
| 2-5 | 로그인 이력 조회 | PWB-020301-001 | 기간 지정 조회 |
| 2-6 | 권한 승인 루틴 | PWB-020301-001 | 브라우저 사용자 등록 시 권한 승인 |

**산출물**: auth와 유사한 admin 레이아웃(header + sidebar + 본문), 메뉴·회원 CRUD, 권한별 메뉴 노출.

---

### Phase 3: 기본정보 관리 (PWB-030000)

**목표**: 발주·입고·불출·판매에서 공통으로 쓰는 마스터 데이터를 구축한다.

| 순서 | 작업 | 참조 ID | 비고 |
|------|------|---------|------|
| 3-1 | 기본코드 종류 | PWB-030101-001 | `03-basic-codes.md` 코드 종류(A~Y) 등록/수정/삭제 |
| 3-2 | 기본코드 세부코드 | PWB-030101-001 | 종류별 하위 세부 코드 CRUD |
| 3-3 | 단가 관리 | PWB-030201-001 | 지자체별·봉투 종류별 단가, 적용일·변경 이력 |
| 3-4 | 단가 조회 | PWB-030301-001 | 기간별 단가 조회/인쇄 |
| 3-5 | 포장 단위 관리 | PWB-030401-001 | 박스당 팩·팩당 낱장·유효기간·적용일·이력 |
| 3-6 | 포장 단위 조회 | PWB-030401-001 | 기간별 조회/인쇄 |
| 3-7 | 판매 대행소 관리 | PWB-030501-001 | 대행소 CRUD, 지자체 연결, 조회/인쇄 |
| 3-8 | 담당자 관리 | PWB-030601-001, 002 | 소속·담당자명·전화, 구/군/대행소/제작업체 구분 |
| 3-9 | 업체 관리 | PWB-030701-001 | 협회·제작업체·회수업체 등록/조회/인쇄 |
| 3-10 | 무료용 대상자 관리 | PWB-030801-001 | 읍면동/무료대상자/기타, 종료일·상태 |
| 3-11 | 지정판매소 관리·조회·현황 | PWB-030901-001 | 리스트·상세·CRUD·지도·엑셀·인쇄·바코드·신규/취소 현황 |
| 3-12 | PASSWORD 변경 | PWB-031001-001 | 로그인 사용자 비밀번호 변경 |

**산출물**: 기본코드·단가·포장단위·대행소·지정판매소 등 기본정보 화면 및 API.

---

### Phase 4: 발주·입고 관리 (PWB-040000)

**목표**: 발주부터 입고까지 흐름을 구현하고, LOT·바코드 정책을 확정한다.

| 순서 | 작업 | 참조 ID | 비고 |
|------|------|---------|------|
| 4-1 | 발주 등록 | PWB-040101-001 | 발주 이력·폼·단가표, UUID·SHA-256·LOT·블록 저장 |
| 4-2 | LOT·바코드 생성 | PWB-040101-001 | AES-256·RSA, PDF417 박스/팩/낱장 |
| 4-3 | 발주 변경 | PWB-040201-001 | 버전+1 insert, SHA-256, 수정 전/후 해시 |
| 4-4 | 발주 삭제 | PWB-040301-001 | 상태 삭제로 변경 |
| 4-5 | 발주 현황 | PWB-040401-001 | 기간·제작업체·품명·입고처 조회, 엑셀·인쇄 |
| 4-6 | 발주 입고(스캐너) | PWB-040501-001 | 바코드 스캐너 연동(serialport), 스캔 입고 |
| 4-7 | 일괄 입고 | PWB-040501-001 | 일괄 입고 처리 |
| 4-8 | 입고 현황 | PWB-040501-001 | 입고 현황 조회 |

**산출물**: 발주 CRUD, 입고 처리, 입고된 봉투 기준 재고 반영. (실사는 Phase 6에서.)

---

### Phase 5: 불출 관리 (PWB-050000)

**목표**: 무료용 불출·취소를 구현하고, 재고와 연동한다.

| 순서 | 작업 | 참조 ID | 비고 |
|------|------|---------|------|
| 5-1 | 무료용 불출 현황 조회 | PWB-050101-001 | 기간별 무료용 봉투별 불출 현황 |
| 5-2 | 무료용 불출 처리 | PWB-050201-001 | 년도·분기·불출일·불출처·봉투코드·저장, 재고 감산·판매 처리 |
| 5-3 | 무료용 불출 취소 | PWB-050301-001 | 취소 수량 저장·재고 합산·판매 취소 또는 재입고(T.B.D) |

**산출물**: 불출 처리/취소 화면, 재고·판매 데이터와 연동. (`05-meeting-notes.md` 참고.)

---

### Phase 6: 재고·실사 관리 (PWB-060000, PWB-070000)

**목표**: 재고 조회와 실사 선별로 재고 정확도를 확보한다.

| 순서 | 작업 | 참조 ID | 비고 |
|------|------|---------|------|
| 6-1 | 재고 조회 | PWB-060101-001 | 기준일·구/군·대행소별 봉투·스티커 재고, 엑셀·인쇄(결재란) |
| 6-2 | 실사 선별 | PWB-070101-001 | 봉투·스티커 선택, 전산 선별 실행 confirm |
| 6-3 | 실사 선별 조회 | PWB-070101-001 | 기간·품목·박스/팩, 리스트·박스/낱장 정보 |

**산출물**: 재고 현황 화면, 실사 선별·조회. (`04-menu-structure.md` 재고/실사 메뉴 반영.)

---

### Phase 7: 주문·판매 관리 (PWB-080000)

**목표**: 전화 접수와 지정판매소 판매·반품·취소를 구현한다.

| 순서 | 작업 | 참조 ID | 비고 |
|------|------|---------|------|
| 7-1 | 주문 접수 관리 메인 | PWB-080101-001 | 전화 주문 접수 내역, 배달일자·인쇄(집계·영수증·list) |
| 7-2 | 전화 주문 접수 | PWB-080101-001 | 판매소 검색(SLOW 자동완성), 접수번호·가상계좌·주문접수표·저장 |
| 7-3 | 전화 접수 수정/취소 | PWB-080101-001 | 접수량 변경·주문 수정·주문 취소(STATUS) |
| 7-4 | 지정 판매소 판매 | PWB-080101-001 | 판매소 검색·봉투코드·바코드 스캔·판매 저장 |
| 7-5 | 지정 판매소 판매 취소 | PWB-080201-001 | 판매일·취소 선택·품목/봉투코드별 취소 |
| 7-6 | 지정 판매소 반품 | PWB-080301-001 | 판매소·봉투코드 스캔·반품 저장 |
| 7-7 | 지정 판매소 반품 취소 | PWB-080301-001 | 반품 일자 조회·취소 선택·반품 취소 저장 |

**산출물**: 전화 접수·판매·반품·취소 화면. 가상계좌 실시간 조회는 별도 검토(`05-meeting-notes.md`).

---

### Phase 8: 판매 현황 (PWB-090000)

**목표**: 판매·반품 데이터 기반 대장·일계표·기간별·년도별 조회를 제공한다.

| 순서 | 작업 | 참조 ID | 비고 |
|------|------|---------|------|
| 8-1 | 지정 판매소 판매 대장 | PWB-090101-001 | 기간·일자별/기간별·엑셀·인쇄(결재란) |
| 8-2 | 일계표 | PWB-090201-001 | 특정일 일계·누계(월간) |
| 8-3 | 기간별 판매현황 | PWB-090301-001 | 일자별/기간별 판매·반품·합계 |
| 8-4 | 년 판매 현황 | PWB-090401-001 | 년도·품목별·월/분기 |
| 8-5 | 지정 판매소 별 판매 현황 | PWB-090501-001 | 수량/금액·1~12월 컬럼 |
| 8-6 | 홈택스 처리 | PWB-090601-001 | 세금계산서 일괄발급 엑셀 양식 |

**산출물**: 판매 대장·일계표·기간별/년도별/판매소별 현황, 홈택스용 엑셀.

---

### Phase 9: 봉투 수불 관리 (PWB-100000)

**목표**: 수불 이력·현황·반품/파기·LOT 수불 조회를 구현한다.

| 순서 | 작업 | 참조 ID | 비고 |
|------|------|---------|------|
| 9-1 | 기타 입출고 | PWB-100101-001 | 수불 년월·봉투코드·구분·상세(요구사항 확인) |
| 9-2 | 봉투 수불 현황 | PWB-100201-001 | 기간·품목·대행소·일자별/기간별·전일재고·입고/출고·잔량 |
| 9-3 | 반품/파기 현황 | PWB-100301-001 | 기간·입출고 구분·조회/엑셀/인쇄 |
| 9-4 | 봉투 수급 계획 | PWB-100401-001 | 기능 범위 추가 확인 |
| 9-5 | LOT 수불 조회 | PWB-100501-001 | 바코드/봉투번호 입력·일자·입고출처·구분 |

**산출물**: 수불 현황·반품/파기·LOT 수불 조회.

---

### Phase 10: 봉투 스캔 현황 (PWB-110000)

**목표**: 앱 스캔 이력을 웹에서 조회할 수 있게 한다.

| 순서 | 작업 | 참조 ID | 비고 |
|------|------|---------|------|
| 10-1 | 봉투 스캔 횟수/위치 조회 | PWB-110101-001 | 낱장별 앱 스캔 횟수·경위도·지도 표시(옵션) |

**산출물**: 스캔 횟수/위치 조회 화면(지도는 옵션).

---

### Phase 11: 모바일앱 (선택·별도 일정)

**목표**: 웹 API·데이터가 안정된 뒤, `02-mobile-features.md` 15건을 앱에서 구현한다.

- 공통: 로그인·로깅·비식별화  
- 발주 입고, 불출·불출 취소  
- 지정판매소 판매·취소·반품·반품 취소  
- LOT 수불 조회, 주문 내역·주문·수정/취소, 봉투 정품 인증  

웹과 동일한 권한·기본정보·발주·입고·판매 데이터를 사용한다.

---

## 4. 요약 타임라인(개념)

| Phase | 영역 | 의존 |
|-------|------|------|
| 1 | 공통·인증 | — |
| 2 | 관리자·메뉴 | Phase 1 |
| 3 | 기본정보 | Phase 2 |
| 4 | 발주·입고 | Phase 3 |
| 5 | 불출 | Phase 4 |
| 6 | 재고·실사 | Phase 4, 5 |
| 7 | 주문·판매 | Phase 3, 4, 5 |
| 8 | 판매 현황 | Phase 7 |
| 9 | 봉투 수불 | Phase 4, 5, 7 |
| 10 | 봉투 스캔 | Phase 4, 앱 스캔 기능 |
| 11 | 모바일앱 | Phase 1~7 안정화 후 |

---

## 5. 문서 갱신

- 단계 완료 시 이 문서에 **완료일·담당·비고**를 추가해 두면 진행 상황 파악에 유리합니다.
- 요구사항 변경은 `01-web-features.md`, `05-meeting-notes.md`에 반영하고, 필요 시 이 개발 계획도 함께 수정합니다.

---

## 6. 상위 설계 문서(Notion)와의 매핑

최근 Notion 설계 문서(“종량제봉투 웹 플랫폼 개발”) 기준으로, 상위 아키텍처·WBS 는 다음과 같이 이 계획의 Phase들과 대응됩니다.

- **기본 정보 관리 체계 (Master Data, F-MD-01~06)**  
  → 이 문서의 **Phase 3 기본정보 관리**와 매핑. 공통 코드, 단가, 포장 단위, 대행소·업체·담당자·지정판매소 관리가 포함됩니다.
- **발주 및 입고 프로세스 (F-PO-01~04)**  
  → **Phase 4 발주·입고 관리**와 매핑. 발주 등록/변경, LOT-No·PDF417 바코드 생성, 스캐너 기반 입고, 일괄 입고·입고 현황을 포함합니다.
- **재고 및 실사 관리 요구사항**  
  → **Phase 6 재고·실사 관리**, **Phase 9 봉투 수불 관리**와 매핑. 실시간 재고, 다단계 실사, 수급 계획, LOT 수불 추적 기능을 여기서 구현합니다.
- **판매 및 결제 시스템 (고정 가상계좌, Webhook, 홈택스 연동)**  
  → **Phase 7 주문·판매 관리**(주문/판매/반품/취소)와 **Phase 8 판매 현황**(리포트·홈택스용 엑셀)에서 1차 구현하고, PG/Webhook·홈택스 API 연동은 **웹 1차 안정화 이후 단계적 고도화 항목**으로 둡니다.
- **데이터 흐름·제어 흐름·UML/ERD**  
  → 이 문서의 각 Phase에서 구현해야 할 **비즈니스 플로우와 테이블 설계에 대한 상위 가이드**로 삼고, 실제 마이그레이션/엔티티 설계는 Phase 착수 시점에 Notion 내용을 참고해 구체화합니다.
- **블록체인/불변 원장 구조(SQL-Ledger)**  
  → 종량제 v1(웹 1차)에서는 **일반 RDBMS 기반 수불·이력 관리**를 우선 완성하고, 이후 “블록체인/Immutable Ledger 기반 이력 보강”을 **별도 고도화 Phase**로 추가하는 것을 전제로 합니다.

즉, Notion 문서는 “전체 시스템 설계·데이터/제어 흐름·블록체인·고정 가상계좌 등 상위 아키텍처”를 제시하고 있고,  
이 문서(`06-development-plan.md`)는 그 중 **웹 애플리케이션 기능 개발 순서와 범위(Phase 1~11)** 에 초점을 맞춘 실행 계획으로 사용합니다.

---

## 7. 추가 비즈니스/운영 요구사항 (25.11.24 미팅 요약)

- **가격·수익 구조**
  - 봉투 1장당 바코드 비용은 **약 7원**, 이 중 **0.5원(약 7%)을 영업 파트너(Wixon 등)와 분배**하는 모델을 전제로 함.
  - 개발비 5천만 원은 “설계도까지 사 오는 것”이 아니라, **서진이 프로그램 소유권을 가지되, 윅슨이 영업 시 일정 수익을 공유하는 투자 개념**으로 이해함.
- **프로그램 소유권**
  - 개발비를 서진이 부담하는 만큼 **프로그램 소유권은 서진**이 갖고,  
  - 윅슨이 서울/경기에서 영업하는 것은 **막지 않는 방향(라이선스 제공)** 으로 합의.
  - 별도 2안으로는 **프로그램 소유권까지 전부 이전(매입)** 하는 조건도 논의됨.
- **서버·배포 방식**
  - 지자체 정보통신과를 거치지 않고 **지자체 내부 서버에 설치하는 응용프로그램 방식**을 우선 고려 (현재도 원격 접속으로 운영 중).
  - 동시에, 경쟁사(예: IT플러스)가 **외부 서버 방식**을 쓰는 점을 감안해,  
    **지자체 내 서버 설치형 + 외부 서버/클라우드형을 모두 지원하는 유연한 구조**가 영업 전략상 유리하다는 의견.
- **블록체인·특허**
  - 순수 기술 관점에서는 **주기적 백업 + 암호화** 만으로도 충분하나,  
  - **특허(블록체인 기반 종량제 봉투 관리)와 연계해 입찰 없이 수의계약·영업 차별화**를 하기 위해,  
    설계 상 **블록체인/불변 원장 아키텍처를 반영**해야 함.
  - v1 웹 개발에서는 RDBMS 기반으로 구현하되, 데이터 구조와 로그(수불 이력 등)는 **나중에 블록체인/Immutable Ledger로 확장 가능하도록 설계**하는 것을 목표로 함.
- **운영·테스트**
  - “검수 및 관공서 설치 테스트” 기간은 **약 1개월**을 기준으로, 실제 환경에서 잘 돌아가는지 모니터링.
  - 오래된 레거시 메뉴가 많아, 웹 전환 시 **기능 통합·정리로 메뉴 수를 줄이는 것**도 중요한 목표.
- **기타 운영 요구**
  - PC가 안 되는 경우 **PDA에서 먼저 입고/불출 처리 후 나중에 PC와 동기화**해야 하는 케이스가 있으므로,  
    온라인/오프라인 혼합 시나리오를 고려한 **동기화 로직**이 필요함.
  - 각 기능별 **로그(감사 이력) 기록**은 필수이며, 이는 향후 블록체인/불변 원장 도입 시에도 핵심 데이터가 됨.