# 종량제 (Jongryangje) - Claude Code 프로젝트 가이드

## 프로젝트 개요

지자체 종량제 쓰레기봉투 물류/유통 관리 웹 애플리케이션

## 기술 스택

- **Framework**: CodeIgniter 4.7+ (PHP 8.2+, strict types)
- **Database**: MySQL/MariaDB (MySQLi 드라이버)
- **의존성 관리**: Composer 2.x
- **테스트**: PHPUnit 10.x
- **세션**: 파일 기반 (`writable/session/`)

## 프로젝트 구조

```
app/
├── Config/          # Routes, Database, Roles, Filters, Session 등
├── Controllers/     # Home, Auth, Admin/* (8개 관리자 컨트롤러)
├── Models/          # MemberModel, LocalGovernmentModel, DesignatedShopModel 등
├── 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`, `LEVEL_LOCAL_ADMIN`, `LEVEL_SHOP`, `LEVEL_CITIZEN`)

## 멀티테넌시

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

## 코딩 컨벤션

### PHP

- `declare(strict_types=1)` 모든 PHP 파일 상단
- CodeIgniter 4 네이밍 규칙 준수 (PascalCase 클래스, camelCase 메서드)
- DB 컬럼: snake_case with prefix (`mb_`, `lg_`, `ds_`, `mm_`, `mt_`, `mar_`)
- 모델에서 `$allowedFields` 명시, `$useTimestamps` 활용

### 보안

- PII(이메일, 전화번호)는 `pii_encryption_helper`로 암호화 (`ENC:` prefix)
- 비밀번호: `password_hash()` + `password_verify()` (bcrypt)
- 입력 유효성: CodeIgniter Validation 사용
- `.env` 파일 절대 커밋 금지

### View

- Admin 레이아웃: `admin/layout/main` 기반
- 메뉴: DB 기반 동적 메뉴 (`admin_helper.php`의 `buildMenuTree()`)

## 개발 서버 실행

```bash
php spark serve --port=8045
```

## 테스트 실행

```bash
vendor/bin/phpunit
```

## DB 초기화 순서

1. `writable/database/init_jongryangje_dev.sql` - 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` - 코드 마스터

## 주요 라우트

- 공개: `/`, `/login`, `/register`
- 인증: `/dashboard`, `/bag/*`
- 관리자 (`adminAuth` 필터): `/admin/*`

라우트 정의: `app/Config/Routes.php`

## 주의사항

- 관리자 컨트롤러는 `App\Controllers\Admin` 네임스페이스
- `AdminAuthFilter`가 로그인 + 레벨 3/4 + 지자체 선택 여부 검증
- SQL 마이그레이션 미사용 — `writable/database/` SQL 스크립트 직접 실행
- encryption.key 필요 (64자리 hex) — PII 암호화용