docs: add project docs and test updates

docs/기본 개발계획/25-메뉴_추가수정_개발_계획.md

@@ -0,0 +1,230 @@
+## 메뉴 추가·수정 개발 계획
+
+### 1. 목적 및 범위
+
+- **목적**
+  - 관리자 화면과 일반 사이트 화면의 상단 메뉴를 **지자체별·역할별로 DB에서 동적으로 관리**할 수 있도록 확장한다.
+  - 1차 메뉴뿐 아니라 **2차/3차 하위 메뉴까지 등록·수정·삭제·순서 변경** 가능하게 하고, 상단 `<nav>`에 **드롭다운 구조**로 반영한다.
+- **범위**
+  - 테이블: `menu_type`, `menu`
+  - 모델: `MenuModel`, `MenuTypeModel`
+  - 컨트롤러: `App\Controllers\Admin\Menu`
+  - 뷰: `app/Views/admin/layout.php`, `app/Views/admin/menu/index.php`
+  - 헬퍼: `app/Helpers/admin_helper.php`
+
+---
+
+### 2. 데이터 구조 및 기본 정책
+
+#### 2.1 메뉴 종류 (`menu_type`)
+
+- 컬럼
+  - `mt_idx` : PK
+  - `mt_code` : 코드 (`admin`, `site` 등)
+  - `mt_name` : 표시명
+  - `mt_sort` : 정렬 우선순위
+- 기본 데이터
+  - `admin` : 관리자 상단 메뉴
+  - `site`  : 일반 사이트 상단 메뉴
+
+#### 2.2 메뉴 항목 (`menu`)
+
+- 컬럼
+  - `mm_idx`   : PK
+  - `mt_idx`   : 메뉴 종류 FK (`menu_type.mt_idx`)
+  - `lg_idx`   : 지자체 FK (지자체별 메뉴 분리)
+  - `mm_name`  : 메뉴명 (1차/2차/3차 공통)
+  - `mm_link`  : 링크 경로 (예: `admin`, `admin/users`, `site/inventory/list`)
+  - `mm_pidx`  : 부모 메뉴 PK (`0` = 최상위 1차 메뉴)
+  - `mm_dep`   : 깊이 (`0`=1차, `1`=2차, `2`=3차 …)
+  - `mm_num`   : 형제 내 정렬 순서
+  - `mm_cnode` : 자식 개수
+  - `mm_level` : 노출 허용 `mb_level` 쉼표 구분 (빈값=전체, super admin은 무시하고 항상 전체)
+  - `mm_is_view` : `Y`=노출, `N`=숨김
+- 인덱스
+  - `idx_mt_lg (mt_idx, lg_idx)` : 메뉴 종류·지자체별 조회용
+  - `idx_mm_pidx (mm_pidx)` : 하위 메뉴 존재 여부 확인용
+  - `idx_mm_dep_num (mm_dep, mm_num)` : 트리 정렬용
+
+#### 2.3 기본 메뉴 정책
+
+- **관리자 상단 메뉴 (`mt_code='admin'`)**
+  - 각 지자체별로 다음과 같은 1차 메뉴가 기본 등록되어야 한다.
+    - 대시보드 (`admin`)
+    - 회원 관리 (`admin/users`)
+    - 로그인 이력 (`admin/access/login-history`)
+    - 승인 대기 (`admin/access/approvals`)
+    - 역할 (`admin/roles`)
+    - 메뉴 (`admin/menus`)
+    - 지자체 전환 (`admin/select-local-government`, super admin 전용)
+    - 지자체 (`admin/local-governments`, super admin 전용)
+    - 지정판매소 (`admin/designated-shops`)
+  - 각 1차 메뉴 아래에 2차/3차 하위 메뉴를 둘 수 있으며, 상단 `<nav>`에서 드롭다운으로 노출한다.
+
+- **일반 사이트 상단 메뉴 (`mt_code='site'`)**
+  - 각 지자체별로 다음과 같은 1차 메뉴 세트를 기본 등록한다.
+    - 기본정보관리
+    - 발주 입고 관리
+    - 불출 관리
+    - 재고 관리
+    - 판매 관리
+    - 판매 현황
+    - 봉투 수불 관리
+    - 통계 분석 관리
+    - 창
+    - 도움말
+  - 각 1차 메뉴 아래의 2차/3차 메뉴 구성은 **CSV의 “1차 메뉴정리” 파일**을 기준으로 초기 등록한다.
+
+- **역할·권한 정책**
+  - `mm_level` 빈값: 모든 역할 노출 (일반 사용자, 지정판매소, 지자체관리자, super admin).
+  - `mm_level`에 숫자(1,2,3) 지정: 해당 `mb_level` 사용자에게만 노출.
+  - super admin(4): DB `mm_level` 값과 관계없이 해당 지자체의 모든 메뉴를 볼 수 있도록 모델에서 처리.
+
+---
+
+### 3. 기능 요구사항 (관리자 메뉴 관리)
+
+#### 3.1 공통 동작
+
+- **지자체 선택 필수**
+  - `admin_effective_lg_idx()`를 사용해 현재 작업 지자체를 결정한다.
+  - 값이 `null`이면 지자체 선택 화면(`/admin/select-local-government`)으로 리다이렉트하고,  
+    “메뉴를 관리하려면 먼저 지자체를 선택하세요.” 메시지를 표출한다.
+
+- **메뉴 종류 선택**
+  - `menu_type` 목록에서 `mt_code`(admin/site 등)를 선택하여 관리 대상 메뉴 종류를 바꾼다.
+  - 선택된 `mt_idx` + 현재 `lg_idx` 기준으로 메뉴 목록과 등록/수정 폼을 동작시킨다.
+
+#### 3.2 목록 영역 (트리 + 들여쓰기)
+
+- 선택한 `mt_idx`, 현재 `lg_idx` 기준으로 **트리 구조를 평면 리스트로 렌더링**한다.
+  - `mm_dep` 값에 따라 좌측 padding을 주어 1차/2차/3차 메뉴를 시각적으로 구분한다.
+  - 각 행에 다음 정보를 표시한다.
+    - 메뉴명 (`mm_name`)
+    - 링크 (`mm_link`)
+    - 노출 대상 (`mm_level` → 역할 이름으로 변환, 빈값이면 “전체”)
+    - 노출 여부 (`mm_is_view` Y/N)
+  - 삭제 버튼
+    - 현재 지자체(`lg_idx`) 소속인지 검증 후 삭제 허용.
+    - 하위 메뉴가 있으면 삭제 불가.
+
+- **하위 메뉴 등록 버튼**
+  - 각 행 우측에 “하위 메뉴 추가” 버튼을 배치한다.
+  - 클릭 시:
+    - 우측 폼의 hidden 값에 `mm_pidx=해당 행 mm_idx`, `mm_dep=해당 행 mm_dep+1`을 세팅한다.
+    - 폼 타이틀을 “하위 메뉴 등록”으로 변경(표시용).
+  - 이렇게 등록된 메뉴는 동일한 컨트롤러(`/admin/menus/store`)를 통해 2차/3차 메뉴로 저장된다.
+
+- **순서 변경**
+  - 현재 구현과 동일하게 리스트 순서를 조정한 뒤, “순서 적용” 버튼으로 `mm_idx[]` 순서를 서버로 보낸다.
+  - 서버에서는 현재 지자체(`lg_idx`) 기준으로만 `mm_num`을 재부여하여 순서를 저장한다.
+
+#### 3.3 등록/수정 폼
+
+- hidden 필드
+  - `mt_idx` : 현재 선택된 메뉴 종류
+  - `mm_pidx` : 부모 메뉴 PK (기본값 `0`, “하위 메뉴 추가” 시 부모 ID로 변경)
+  - `mm_dep` : 깊이 (기본값 `0`, “하위 메뉴 추가” 시 `부모+1`)
+  - `mm_idx_edit` : 수정 대상 PK (수정 모드일 때만 값 설정)
+
+- 입력 필드
+  - `mm_name` : 필수, 메뉴명
+  - `mm_link` : 링크 경로 (1차/하위 메뉴 모두 동일 규칙)
+  - `mm_level` : 체크박스(전체 + 각 역할), super admin은 별도로 저장하지 않는다.
+  - `mm_is_view` : 체크박스, 기본값 `Y` (노출)
+
+- 동작 모드
+  - **등록 모드**
+    - `mm_idx_edit` 비어 있음.
+    - `mm_pidx=0`, `mm_dep=0`이면 1차 메뉴 등록.
+    - `하위 메뉴 추가`로 진입한 경우, `mm_pidx/mm_dep`에 부모 정보가 채워진 상태로 등록.
+  - **수정 모드**
+    - “수정” 버튼 클릭 시 해당 행의 정보를 폼에 로딩한다.
+    - `mm_pidx`, `mm_dep`는 변경하지 않고, `mm_name/mm_link/mm_level/mm_is_view`만 수정.
+
+---
+
+### 4. 네비게이션 드롭다운 설계
+
+#### 4.1 공통 트리 헬퍼/서비스
+
+- 함수 예시: `get_menu_tree(string $typeCode, int $lgIdx, int $mbLevel): array`
+  - `menu_type.mt_code`로 `mt_idx` 조회.
+  - `MenuModel::getVisibleByLevel(mt_idx, mbLevel, lgIdx)`로 현재 지자체/역할 기준 메뉴 목록 조회.
+  - 조회 결과(평면 배열)를 `mm_idx/mm_pidx` 기준으로 트리 구조로 변환:
+    - 1차 메뉴: `mm_pidx=0`
+    - children: `mm_pidx=부모 mm_idx`
+    - 각 노드에 `children` 배열을 추가.
+
+#### 4.2 관리자 레이아웃(nav)
+
+- 파일: `app/Views/admin/layout.php`
+- 변경 내용
+  - 기존 `get_admin_nav_items()`는 1차 메뉴 리스트만 반환하는 형태에서,  
+    **트리 형태를 반환하는 헬퍼**를 사용하도록 변경한다.
+  - 상단 `<nav>`에서:
+    - 1차 메뉴(트리 루트)를 루프 돌며 `<a>`를 렌더링.
+    - 자식 메뉴가 있는 경우:
+      - 1차 메뉴를 `<div class="relative group">`로 감싼 후,
+      - `group-hover:block` 형태의 `<div>` 안에 children 메뉴들을 `<a>` 리스트로 렌더링.
+  - 각 `<a>`의 `href`는 `base_url(mm_link)`로 풀 페이지 전환을 사용한다.
+
+#### 4.3 일반 사이트 레이아웃(nav)
+
+- (향후) 사이트용 레이아웃 파일에서:
+  - `get_menu_tree('site', 현재 lg_idx, 현재 사용자 레벨)` 을 호출.
+  - 관리자와 동일한 드롭다운 패턴으로 1차/하위 메뉴를 렌더링.
+  - 링크 클릭 시 역시 풀 페이지 전환을 사용한다.
+
+---
+
+### 5. 지자체·권한 정책 정리
+
+- **지자체별 메뉴 분리**
+  - 모든 메뉴 조회·등록·수정·삭제·순서 변경은 `mt_idx + lg_idx`를 조건으로 수행한다.
+  - 북구청에서 만든 메뉴(`lg_idx=북구청`)는 다른 구청(`lg_idx`가 다른 값)에서는 보이지 않고, 관리도 불가하다.
+
+- **역할별 노출**
+  - `mm_level`이 빈값인 메뉴는 **모든 역할**에 노출된다.
+  - `mm_level`에 1,2,3이 포함된 경우, 해당 `mb_level`만 노출한다.
+  - super admin(4)은 `mm_level`과 관계없이, 현재 지자체의 모든 `mm_is_view='Y'` 메뉴를 노출한다.
+
+---
+
+### 6. CSV 기반 초기 데이터 등록 계획
+
+1. **CSV 구조 확인**
+   - “1차 메뉴정리” 파일의 컬럼 구조를 확정한다.
+   - 최소 필요 컬럼 예시:
+     - 메뉴 종류(admin/site)
+     - 1차 메뉴명 / 1차 메뉴 링크
+     - 2차 메뉴명 / 2차 메뉴 링크 (선택)
+     - 3차 메뉴명 / 3차 메뉴 링크 (선택)
+     - 노출 대상 역할, 사용 여부 등
+2. **초기 시드/Import 스크립트 작성**
+   - CSV 한 행당 `menu` 테이블 1개 또는 다수 행으로 변환.
+   - 1차 메뉴는 `mm_pidx=0, mm_dep=0` 으로 insert.
+   - 2차/3차 메뉴는 상위 메뉴의 `mm_idx`를 `mm_pidx`로 참조하여 insert.
+   - 초기에는 특정 지자체(예: 대구 전체 or 테스트용 하나의 지자체) 기준으로만 시드하고,  
+     필요 시 “메뉴 복사” 기능으로 다른 지자체로 복제하는 방식을 고려.
+3. **개발/테스트 DB에 적용 및 검증**
+   - 관리자 `/admin/menus`에서 트리 구조와 드롭다운 노출 상태를 확인한다.
+   - 역할별 노출, 지자체별 분리가 기대대로 동작하는지 검증한다.
+4. **운영 반영 절차 문서화**
+   - 운영 DB 초기 세팅 시, CSV → SQL/스크립트 실행 순서를 별도 문서에 정리한다.
+
+---
+
+### 7. 구현 순서 제안
+
+1. `menu` 테이블에 `lg_idx` 컬럼 및 인덱스 추가, 시드 SQL 정리 (완료 기준 재확인).
+2. `MenuModel`에 `lg_idx`를 반영한 조회/정렬 메서드 정리 (`getAllByType`, `getVisibleByLevel`, `getNextNum`, `setOrder` 등).
+3. `Admin\Menu` 컨트롤러에서 지자체 필수 체크 및 지자체 소속 검증 로직 보완.
+4. `admin/menu/index` 뷰에서:
+   - 하위 메뉴 등록 버튼 추가
+   - `mm_pidx/mm_dep` 값을 활용한 2차/3차 메뉴 등록/표시 기능 구현.
+5. 트리 헬퍼(`get_menu_tree` 류) 구현 및 `admin_helper`에 연동.
+6. `admin/layout` 상단 네비게이션을 DB 트리 기반 드롭다운으로 교체.
+7. CSV 기반 초기 데이터 스크립트 작성 및 개발 환경에서 시범 적용.
+8. 통합 테스트 후 운영 반영 계획 수립.
+