jongryangje/docs/기본 개발계획/테이블/04-마스터_데이터_선행_정리.md

## 04. 마스터 데이터 선행 정리

이 문서는 **종량제 시스템 전역에서 공통으로 사용하는 기준 값(코드·마스터 데이터)** 중,  
**서비스 오픈 전/개발 초기에 미리 DB에 적재해 두는 것이 좋은 항목**을 정리한다.

목표:

- 행정구역·코드·상태값·역할 등을 사전에 정의하여 **설계 변경을 최소화**한다.
- 화면 구현 시 **드롭다운(콤보박스)·검색 조건·통계 축**으로 재사용한다.

---

## 1. 행정구역·지자체 관련 마스터

### 1-1. 시/도, 구/군, 동 코드

- **구분**
  - 시/도: 행정구역 상위 단위 (서울특별시, 부산광역시, ○○도 등)
  - 구/군: 시/도 하위 행정구역 (○○구, ○○군)
  - 동: 구/군 하위 동/읍/면
- **출처**
  - `종량제_개발목록_20260127(기본코드 종류).csv` 의 **코드 A, B, C, D** 및 하위 데이터
- **권장 구조(예시)**
  - `local_government`:
    - `lg_idx`: PK
    - `lg_name`: 지자체 명칭 (예: 대구광역시 북구청)
    - `lg_code`: 행정 코드(구/군 코드) – 기본코드 B/C 기반
  - `district` (또는 `gu`):
    - `dt_idx`: PK
    - `dt_lg_idx`: FK → `local_government.lg_idx`
    - `dt_code`: 구/군 코드 (기본코드 C)
    - `dt_name`: 구/군 명칭
  - `dong`:
    - `dg_idx`: PK
    - `dg_dt_idx`: FK → `district.dt_idx`
    - `dg_code`: 동 코드 (기본코드 D)
    - `dg_name`: 동/읍/면 명칭

> 운영 방침: **행정구역은 문자열이 아니라 코드·PK로 정규화**해서 관리한다.

### 1-2. 지자체별 기본 설정

- 예시 항목
  - 사용 봉투 종류(일반/공공/음식물/재사용 등)
  - 사용 단위(리터/장/팩), VAT 포함 여부
  - 지자체별 회수업체/제작업체 기본 설정
- 구현 방식
  - `local_government_config` 테이블 등으로 별도 관리하거나,
  - 코드 테이블(`code_detail`)과 조합해서 지자체별 설정값을 유지.

---

## 2. 기본 코드 체계 (code_kind / code_detail)

### 2-1. CSV 기반 코드 종류

다음 코드는 **CSV 기준으로 이미 정의되어 있으므로, 초기에 모두 `code_kind`/`code_detail`로 적재**하는 것을 권장한다.

- **봉투·판매 관련**
  - 코드 E: 봉투구분 (일반/공공/무료/공동주택/음식물/재사용 등)
  - 코드 F: 봉투재질 (고밀도, PP마대, 스티커, 용기 등)
  - 코드 G: 용량별 (2L, 3L, 5L, 10L, 20L, 50L, 100L 등)
  - 코드 H: 무상지급 구분 (시설보호대상자, 생보자, 사회복지시설 등)
  - 코드 I: 판매형태 (무상지급, 일반판매, 관내판매, 교환판매 등)
  - 코드 J: 반품형태 (일반반품, 관내반품 등)
  - 코드 K: 반품사유 (봉투훼손, 지정판매소 폐업, 스티커 미사용 등)
- **수불·재고 관련**
  - 코드 M: 수불구분
    - 실사입고, 신청입고, 무료입고, 발주입고, 반품입고(정상/불용), 이동입고
    - 실사출고, 신청불출, 무료불출, 일반판매, 공공출고, 반품출고(정상/불용), 이동출고, 파기처리, 시찰 등
- **조직·권한 관련**
  - 코드 S: 소속 (청소과, 청소행정과, 자원순환과, 도시미화과, 영업부, 관리부, 기술부 등)
  - 코드 T: 직위 (7급, 8급, 9급, 기능, 계장, 과장, 사장, 상무 등)
  - 코드 P: 작업권한 (향후 역할·권한 체계와 연동 가능)
- **예산·금융 관련**
  - 코드 Q: 예산과목 (관·항·목 수준 코드)
  - 코드 R: 은행목록 (국민은행, 수협, 우리은행, 부산은행, 새마을금고 등)

### 2-2. code_kind / code_detail 설계 원칙

- `code_kind`:
  - 코드 종류를 정의 (예: `E`, `F`, `G` …)
  - 설명 필드에 한글 설명(봉투구분, 봉투재질 등) 저장
- `code_detail`:
  - `ck_id` 또는 `ck_code` FK → `code_kind`
  - `cd_code`: 세부코드 값 (예: 10, 11, 12 …)
  - `cd_name`: 코드명 (예: 일반용 10L, 음식물 2L, 폐기물 스티커 1,000원 등)
  - 필요 시 `cd_sort`, `cd_state`, `cd_memo` 등 추가

> 화면에서는 **code_detail 기반으로 selectbox·radio·checkbox**를 구성하며,  
> 비즈니스 로직에서는 **하드코딩 대신 코드값 비교**를 사용한다.

---

## 3. 상품·포장·단가 관련 기본값

### 3-1. 품목 타입(pr_type)

- 예시 값
  - 일반, 음식물, 재사용, 스티커, 용기 등
- 사용처
  - `product.pr_type` 값으로 사용
  - 보고서/통계·단가 정책 분기 등에 활용
- 구현
  - 코드 테이블(`code_kind` / `code_detail`)로 관리하거나,
  - 소수의 고정값일 경우 ENUM 역할을 하는 코드로 고정.

### 3-2. 포장 단위 기본 룰

- 개념
  - 1박스 = N팩
  - 1팩 = M장
  - 1장 = 1EA
- 사용처
  - `packaging_unit` 테이블의 기본 데이터
  - 입고·출고·재고 실사에서 수량 변환(박스↔팩↔장) 시 사용
- 구현
  - 지자체별/봉투별로 **포장단위 기본값을 설정하는 레코드**를 선행 입력.

### 3-3. 단가 정책 유형

- 항목
  - 발주단가, 도매가, 소비자가, 유효기간
- 사용처
  - `product_price` 테이블에서 지자체·봉투별 단가 관리
- 선행 정의
  - 어떤 단가가 필수인지(소비자가 필수, 도매가는 옵션 등) 정책을 정리하고 문서화.

---

## 4. 권한·메뉴·업무 상태 마스터

### 4-1. 역할/권한 마스터

- 현재 역할
  - SUPER_ADMIN, LOCAL_ADMIN, SHOP, CITIZEN (및 향후 추가 가능 역할)
- 사용처
  - `member.mb_level` 및 RBAC 구현
- 선행 정리
  - 역할별:
    - 접근 가능한 메뉴
    - 관리 대상 지자체 범위 (전체/단일 지자체/미제한)
    - 수행 가능한 업무(등록/수정/삭제/승인 등)를 표로 정의.

### 4-2. 메뉴·기능 코드

- 출처
  - 웹·모바일 기능목록 CSV의 **PWB-XXXXXX-YYY** 형식 코드
- 사용처
  - 메뉴 트리 구성, 권한 제어, 변경 이력 로깅
- 권장 구조
  - `menu` 또는 `feature` 테이블:
    - 기능코드, 명칭, 상위메뉴, URL/라우트, 정렬순서, 사용 여부 등

### 4-3. 업무 상태값

- 예시
  - 발주 상태: 정상, 취소, 삭제 등
  - 입고 상태: 정상입고, 반품입고(정상/불용), 파기 등
  - 가상계좌 상태: 입금대기, 입금완료, 취소
- 구현
  - 가능한 한 **코드 테이블로 공통 관리**하고,
  - 테이블별 상태 컬럼(`*_state`, `*_status`)는 코드값을 참조.

---

## 5. 결제·가상계좌·바코드 정책

### 5-1. 가상계좌·정산 관련 기본값

- 예시 항목
  - 사용 은행 목록 (은행 코드, 은행명)
  - 지자체별 계약 은행/계좌 구분 방식
  - 입금 마감시간, 입금 허용 요일 등 정책성 값
- 구현
  - 은행 목록은 코드 R 기반으로 `code_detail`에 저장.
  - 지자체별 VA 정책은 별도 설정 테이블 또는 `local_government_config`에 저장.

### 5-2. 바코드·LOT 번호 정책

- 정의할 항목
  - LOT 번호 자리수, 구성 요소(지자체 코드, 발주일자, 시퀀스 등)
  - 박스/팩/낱장 바코드 규칙 (prefix, 길이, 체크섬 여부 등)
- 구현
  - 단순 문자열 규칙으로 하드코딩하지 않고,
  - 바코드 정책 테이블 또는 설정값으로 정의해 두고,
  - 바코드 생성·검증 로직은 이 설정을 참조.

---

## 6. 우선 순위 정리

**1단계(필수, 즉시 적재 추천)**  

- 행정구역·지자체 코드:
  - 시/도, 구/군, 동 코드 (local_government, district, dong)
- 기본코드:
  - 봉투구분(E), 봉투재질(F), 용량(G), 무상지급(H), 판매형태(I), 수불구분(M)
- 조직·은행:
  - 소속(S), 직위(T), 은행목록(R)

**2단계(초기 개발기·시범 운영 전 정리 추천)**  

- 반품형태(J), 반품사유(K), 작업권한(P), 예산과목(Q)
- 상품 타입(pr_type), 포장 단위 기본값, 단가 정책 유형
- 역할별 권한 정의, 메뉴/기능 코드 마스터

**3단계(실 서비스 준비 단계)**  

- 지자체별 기본 설정(운영 정책, 단가 정책, 사용 봉투 종류)
- 가상계좌 정책, 바코드·LOT 정책 세부 정의

> 이 문서는 “어떤 값을 코드·마스터로 선행 정의해야 하는지”를 개략적으로 정리한 것이며,  
> 실제 DDL 및 컬럼명은 `00-테이블_목록_및_ERD.md`, `01-마스터_테이블_DDL.md`, `02-물류_판매_테이블_DDL.md`의 규칙을 따른다.