# 관리자단 기능 개발 설계서

> 웹 기능목록 CSV(관리자단 PWB-020000) 기준 · Auth 프로젝트와 동일한 방식으로 구현

**참조 CSV**: `docs/종량제 관련 자료/종량제 개발목록/종량제_개발목록_20260127(웹 기능목록) (1).csv`  
**참조 구현**: `app/Controllers/Auth.php`, `app/Views/auth/`, `app/Models/MemberModel.php`, `app/Config/Routes.php`

---

## 1. Auth 프로젝트 구조 (참조 패턴)

### 1.1 디렉터리/파일 구조

```
app/
├── Controllers/
│   └── Auth.php              # showLoginForm, login, logout, showRegisterForm, register
├── Models/
│   ├── MemberModel.php        # 회원 CRUD, findByLoginId
│   └── MemberLogModel.php     # 로그인 이력
├── Views/
│   └── auth/
│       ├── login.php          # 로그인 폼
│       └── register.php       # 회원가입 폼
└── Config/
    └── Routes.php             # login, logout, register 라우트
```

### 1.2 네이밍 규칙

| 구분 | 규칙 | 예시 |
|------|------|------|
| 컨트롤러 | PascalCase, 단수/역할명 | `Auth`, `Home` |
| 메서드 | camelCase, 동사+명사 | `showLoginForm`, `login` |
| 뷰 폴더 | 컨트롤러명 소문자 | `auth/`, `home/` |
| 뷰 파일 | 소문자+언더스코어 | `login.php`, `register.php` |
| 라우트 URI | 소문자, 케밥 또는 경로 | `login`, `logout`, `register` |
| 모델 | PascalCase + Model | `MemberModel`, `MemberLogModel` |

### 1.3 라우트 패턴 (Auth 기준)

```php
// GET  = 폼 표시 (showXxxForm 또는 index)
// POST = 처리 (login, register)
$routes->get('login', 'Auth::showLoginForm');
$routes->post('login', 'Auth::login');
$routes->get('logout', 'Auth::logout');
$routes->get('register', 'Auth::showRegisterForm');
$routes->post('register', 'Auth::register');
```

### 1.4 컨트롤러 메서드 패턴

- **폼 표시**: `showXxxForm()` → `return view('auth/xxx');`
- **처리**: `xxx()` → 유효성 검사 → Model 호출 → `redirect()->to(...)->with(...)`
- **유효성**: `$this->validate($rules, $messages)` 사용
- **에러 시**: `redirect()->back()->withInput()->with('errors', ...)`

### 1.5 뷰 공통 사항

- `base_url()`, `csrf_field()`, `esc()`, `old()` 사용
- 플래시: `session()->getFlashdata('success')`, `getFlashdata('error')`, `getFlashdata('errors')`

---

## 2. 관리자단 기능 목록 (CSV 매핑)

| No | SFR 2레벨 | SFR 3레벨 | 기능 ID | 기능명 | 비고 |
|----|-----------|-----------|---------|--------|------|
| 4 | PWB-020100 | PWB-020101 | PWB-020101-001 | 사용자 권한 관리 | 권한 등록/수정/삭제, 역할별 설명 |
| 5 | PWB-020200 | PWB-020201 | PWB-020201-001 | 사용자 관리 | 사용자 등록/수정/삭제(삭제상태 5년 유지) |
| 6 | PWB-020300 | PWB-020301 | PWB-020301-001 | 사용자 로그인 이력 확인 | 기간 지정 조회 |
| 7 | PWB-020300 | PWB-020301 | PWB-020301-001 | 사용자 권한 승인 | 브라우저 회원가입 시 권한 승인 루틴 |
| 8 | PWB-020400 | PWB-020401 | PWB-020401-001 | 메뉴 관리 | 메뉴 등록/수정/삭제, "전체 메뉴" 시트 참고 |
| 9 | PWB-020400 | PWB-020401 | PWB-020401-001 | 메뉴 별 권한 설정 | 메뉴별 사용자 접근 권한 설정 |

---

## 3. 관리자단 구현 설계 (Auth 방식 적용)

### 3.1 URL/라우트 구조

관리자 전용 prefix `admin` 사용, 인증 필터 적용 대상.

```
admin/                          # 관리자 대시보드 (선택)
admin/users                     # 사용자 관리 목록 (GET)
admin/users/create              # 사용자 등록 폼 (GET)
admin/users/store               # 사용자 등록 처리 (POST)
admin/users/(:num)/edit         # 사용자 수정 폼 (GET)
admin/users/(:num)/update       # 사용자 수정 처리 (POST)
admin/users/(:num)/delete       # 사용자 삭제(상태변경) (POST)

admin/roles                     # 사용자 권한 관리 (목록/등록/수정/삭제)
admin/roles/create
admin/roles/store
admin/roles/(:num)/edit
admin/roles/(:num)/update
admin/roles/(:num)/delete

admin/access                    # 사용자 접근 관리 (하위: 로그인이력, 권한승인)
admin/access/login-history      # 로그인 이력 조회 (GET, 기간 조건)
admin/access/approvals          # 권한 승인 대기 목록 (GET)
admin/access/approvals/(:num)   # 권한 승인/반려 처리 (POST)

admin/menus                     # 메뉴 관리 (목록/등록/수정/삭제)
admin/menus/create
admin/menus/store
admin/menus/(:num)/edit
admin/menus/(:num)/update
admin/menus/(:num)/delete
admin/menus/permissions         # 메뉴별 권한 설정
```

### 3.2 컨트롤러 구성 (Auth와 동일 패턴)

| 컨트롤러 | 파일 | 역할 | 주요 메서드 |
|----------|------|------|-------------|
| Admin\Dashboard | `Controllers/Admin/Dashboard.php` | 관리자 첫 화면 | `index()` |
| Admin\User | `Controllers/Admin/User.php` | 사용자 관리 | `index()`, `create()`, `store()`, `edit($id)`, `update($id)`, `delete($id)` |
| Admin\Role | `Controllers/Admin/Role.php` | 사용자 권한 관리 | `index()`, `create()`, `store()`, `edit($id)`, `update($id)`, `delete($id)` |
| Admin\Access | `Controllers/Admin/Access.php` | 접근 관리 | `loginHistory()`, `approvals()`, `approve($id)`, `reject($id)` |
| Admin\Menu | `Controllers/Admin/Menu.php` | 메뉴 관리 | `index()`, `create()`, `store()`, `edit($id)`, `update($id)`, `delete($id)`, `permissions()` |

- **목록/폼**: GET → `view('admin/xxx/yyy')`
- **저장/수정/삭제**: POST → `validate` → Model → `redirect()->to(...)->with(...)`
- **에러**: `redirect()->back()->withInput()->with('errors', ...)` (Auth와 동일)

### 3.3 모델 구성

| 모델 | 파일 | 테이블 | 비고 |
|------|------|--------|------|
| MemberModel | (기존) | member | 사용자 관리에서 재사용 |
| MemberLogModel | (기존) | member_log | 로그인 이력에서 재사용 |
| RoleModel | `Models/RoleModel.php` | role (신규) | 권한/역할 마스터 |
| MenuModel | `Models/MenuModel.php` | menu (신규) | 메뉴 마스터 |
| MenuPermissionModel | `Models/MenuPermissionModel.php` | menu_permission (신규) | 메뉴별 권한 |

- `member.mb_level`은 `Roles` 설정과 연동 유지.
- 권한 테이블(role)이 있으면 `member.mb_level`과 매핑 또는 확장.

### 3.4 뷰 디렉터리 구조

```
app/Views/
└── admin/
    ├── layout.php              # 관리자 공통 레이아웃 (선택)
    ├── dashboard/
    │   └── index.php
    ├── user/
    │   ├── index.php           # 목록
    │   ├── create.php          # 등록 폼
    │   └── edit.php            # 수정 폼
    ├── role/
    │   ├── index.php
    │   ├── create.php
    │   └── edit.php
    ├── access/
    │   ├── login_history.php   # 로그인 이력 조회
    │   └── approvals.php       # 권한 승인 목록/처리
    └── menu/
        ├── index.php
        ├── create.php
        ├── edit.php
        └── permissions.php    # 메뉴별 권한 설정
```

- 공통: `base_url()`, `csrf_field()`, `esc()`, `old()`, 플래시 메시지 (Auth와 동일).

### 3.5 인증/권한

- **관리자 구분**: `mb_level`이 `Roles::LEVEL_SUPER_ADMIN` 또는 `LEVEL_LOCAL_ADMIN`인 경우만 `admin/*` 접근 허용.
- **필터**: `app/Config/Filters.php`에 `adminAuth` 등 필터 등록 후, `admin/*` before에 적용.
- **필터 내부**: `session()->get('logged_in')` 및 `session()->get('mb_level')` 확인 후 미인증/비관리자면 `redirect()->to('login')` 또는 전용 에러 페이지.

---

## 4. Routes.php 등록 예시

```php
// 관리자단 (admin prefix, 인증 필터 적용)
$routes->group('admin', ['filter' => 'adminAuth'], static function ($routes) {
    $routes->get('/', 'Admin\Dashboard::index');
    $routes->get('users', 'Admin\User::index');
    $routes->get('users/create', 'Admin\User::create');
    $routes->post('users/store', 'Admin\User::store');
    $routes->get('users/(:num)/edit', 'Admin\User::edit/$1');
    $routes->post('users/(:num)/update', 'Admin\User::update/$1');
    $routes->post('users/(:num)/delete', 'Admin\User::delete/$1');

    $routes->get('roles', 'Admin\Role::index');
    $routes->get('roles/create', 'Admin\Role::create');
    $routes->post('roles/store', 'Admin\Role::store');
    $routes->get('roles/(:num)/edit', 'Admin\Role::edit/$1');
    $routes->post('roles/(:num)/update', 'Admin\Role::update/$1');
    $routes->post('roles/(:num)/delete', 'Admin\Role::delete/$1');

    $routes->get('access/login-history', 'Admin\Access::loginHistory');
    $routes->get('access/approvals', 'Admin\Access::approvals');
    $routes->post('access/approvals/(:num)', 'Admin\Access::approve/$1');

    $routes->get('menus', 'Admin\Menu::index');
    $routes->get('menus/create', 'Admin\Menu::create');
    $routes->post('menus/store', 'Admin\Menu::store');
    $routes->get('menus/(:num)/edit', 'Admin\Menu::edit/$1');
    $routes->post('menus/(:num)/update', 'Admin\Menu::update/$1');
    $routes->post('menus/(:num)/delete', 'Admin\Menu::delete/$1');
    $routes->get('menus/permissions', 'Admin\Menu::permissions');
    $routes->post('menus/permissions', 'Admin\Menu::savePermissions');
});
```

- `adminAuth`는 별도 필터 클래스에서 로그인 + 관리자 레벨 체크.

---

## 5. 구현 순서 제안

1. **관리자 필터**  
   - `Filters.php`에 `adminAuth` 등록, 필터 클래스에서 `logged_in` + `mb_level` 검사.
2. **사용자 관리 (PWB-020201)**  
   - `Admin\User` 컨트롤러, `admin/user` 뷰, 기존 `MemberModel` 활용.  
   - 삭제는 상태값 변경, 5년 유지 정책은 정책/스케줄로 처리.
3. **사용자 권한 관리 (PWB-020101)**  
   - `Role` 테이블/모델 정비, `Admin\Role` 컨트롤러·뷰.  
   - `member.mb_level`과 역할 매핑 유지.
4. **사용자 접근 관리 (PWB-020301)**  
   - 로그인 이력: `Admin\Access::loginHistory`, 기간 조건, `MemberLogModel` 조회.  
   - 권한 승인: 대기 목록용 테이블/플로우 정한 뒤 `approvals`, `approve`/`reject` 구현.
5. **메뉴 관리 (PWB-020401)**  
   - `menu`, `menu_permission` 테이블, `MenuModel`, `MenuPermissionModel`.  
   - `Admin\Menu` CRUD + `permissions`/`savePermissions`.

---

## 6. 정리

- **웹 기능목록 CSV**의 관리자단(No 4~9)을 **Auth와 같은 방식**으로 구현한다.
- **컨트롤러**: GET은 폼/목록, POST는 처리; 유효성 검사 후 Model 호출, 실패 시 `redirect()->back()->withInput()->with('errors', ...)`.
- **뷰**: `auth`와 동일하게 `base_url()`, `csrf_field()`, `esc()`, `old()`, 플래시 메시지 사용.
- **라우트**: `admin` 그룹 + 필터로 인증/권한 통제.
- **모델**: 기존 Member/MemberLog 활용하고, 권한·메뉴·메뉴권한은 신규 테이블/모델로 추가.

이 설계에 따라 단위 기능별로 Controller → Model → View → Route 순으로 구현하면 Auth와 일관된 관리자단을 만들 수 있다.