# 기술 구현 보고서: PHP 8 및 CodeIgniter 4 기반 종량제 봉투 관리 시스템 (노션 정리)

> 출처: 차장님 노션. 블록체인 기반 종량제 봉투 관리 시스템 특허 문서를 참조한 중앙 집중형 폐쇄적 블록체인 구축 방안.

---

## 1. 서론 (Introduction)

### 1.1 배경 및 목적

- 종량제 봉투는 위조가 용이하여 불법 제작·유통이 빈번함. 기존 바코드/일련번호는 복제 용이·이력 추적 불가.
- **핵심 요구사항**: **단일 중앙 서버** 환경에서 **폐쇄적 블록체인(Private Blockchain)** 네트워크 구축. 분산 합의 대신, 중앙 관리 기관이 신뢰의 주체가 되되 **해시 연결성**을 차용하여 **불변 원장(Immutable Ledger)** 패턴 적용.

### 1.2 개발 환경 및 기술 스택

- **언어**: PHP 8.2 이상 (Strong Typing, JIT, Readonly 프로퍼티)
- **프레임워크**: CodeIgniter 4.4 (경량, MVC, 내장 보안)
- **데이터베이스**: MySQL 8.0 (JSON, 대용량 트랜잭션)
- **인증**: JWT (JSON Web Tokens) 기반 Stateless 인증
- **암호화**: SHA-256 (블록 연결성 보장)

### 1.3 사용자 등급 및 역할 정의

1. **Super Admin**: 시스템 전체 설정, 지역별 관리자 생성, 블록체인 무결성 감사, 강제 포크 해결.
2. **Regional Admin**: 특정 시/군/구 내 봉투 생산 지시, 판매자 관리, 불법 유통 모니터링.
3. **Regional Seller**: 봉투 판매처. 입고 확인 및 소비자 판매 등록.
4. **Consumer**: 봉투 구매자. QR 스캔으로 소유권 등록 및 배출 이력 관리.

---

## 2. 시스템 아키텍처 및 데이터베이스 설계

### 2.1 중앙 집중형 블록체인 구조

- **SQL-Ledger** 방식: RDBMS 내에 블록 자료 구조 이식. 각 블록은 `previous_hash`를 포함하여 변조 시 이후 해시가 깨지도록 함.

### 2.2 데이터베이스 스키마 (MySQL)

#### 2.2.1 블록체인 원장 테이블 (`blockchain_ledger`)

| **필드명** | **타입** | **설명** |
| --- | --- | --- |
| `index` | BIGINT (PK) | 블록 순서(Height). 자동 증가. |
| `timestamp` | DATETIME | 블록 생성 시간. |
| `transaction_type` | ENUM | 'GENESIS', 'PRODUCTION', 'DISTRIBUTION', 'SALE', 'DISCHARGE', 'REPORT'. |
| `data_payload` | JSON | 트랜잭션 상세 데이터(봉투 ID, 사용자 ID, 위치 등). |
| `previous_hash` | CHAR(64) | 이전 블록의 SHA-256 해시값. |
| `hash` | CHAR(64) | 현재 블록의 SHA-256 해시값. |
| `nonce` | INT | (선택) 0 고정 가능. |

**권한**: `INSERT`, `SELECT`만 허용. `UPDATE`, `DELETE` 차단.

#### 2.2.2 종량제 봉투 상태 테이블 (`waste_bags`)

| **필드명** | **타입** | **설명** |
| --- | --- | --- |
| `bag_id` | CHAR(64) (PK) | 봉투 고유 식별자(생산공장+날짜+일련번호의 해시). |
| `qr_code_raw` | VARCHAR(255) | QR 코드 원본 문자열. |
| `factory_id` | INT | 생산 공장 ID. |
| `production_date` | DATE | 생산 일자. |
| `serial_number` | VARCHAR(50) | 일련 번호. |
| `owner_id` | INT | 현재 소유자 ID. |
| `status` | ENUM | 'CREATED', 'DISTRIBUTED', 'SOLD', 'USED', 'REPORTED'. |
| `last_block_index` | BIGINT | 해당 상태를 변경시킨 마지막 블록 인덱스. |

#### 2.2.3 사용자 테이블 (`users`)

| **필드명** | **타입** | **설명** |
| --- | --- | --- |
| `id` | INT (PK) | 사용자 고유 ID. |
| `username` | VARCHAR(100) | 로그인 ID. |
| `password` | VARCHAR(255) | Password Hash (Argon2id 권장). |
| `role` | ENUM | 'SUPER_ADMIN', 'REGIONAL_ADMIN', 'SELLER', 'CONSUMER'. |
| `region_code` | VARCHAR(20) | 관할 구역 코드. |

---

## 3. CodeIgniter 4 프로젝트 설정

- Composer로 CI4 프로젝트 생성, `firebase/php-jwt` 설치.
- `.env`: DB 연결, `encryption.key`, `JWT_SECRET` 설정.
- 블록체인 코어: `App\Libraries\Blockchain` 네임스페이스 하위에 `Block.php`, `Chain.php` 등.

---

## 4. 핵심 블록체인 로직 요약

- **Block 클래스**: `index`, `timestamp`, `data`, `previousHash`로 `calculateHash()` (SHA-256) 수행. PHP 8 readonly 등으로 불변성 강제 가능.
- **Chain 클래스**: `getLatestBlock()`, `createGenesisBlock()`, `addBlock(type, data)`, `isValidChain()`. DB의 `blockchain_ledger`와 연동하여 블록 추가·검증.

---

## 5. API 및 인증

- **RoleAuthFilter**: JWT Bearer 검증, RBAC(라우트별 허용 역할과 토큰 내 역할 비교).
- **WasteBagController (API)**: `produce()`(봉투 생산·PRODUCTION 블록), `sell()`(소유권 이전·SALE 블록), `registerOwnership()`(소비자 소유권 등록/확인), `reportIllegalDump()`(불법배출 신고·REPORT 블록).

---

## 6. 웹 대시보드 (관리자)

- **Admin/BlockchainController**: `isValidChain()` 호출, 원장 최근 N건 조회.
- **View (blockchain_dashboard.php)**: 무결성 결과(정상/변조 경고), 블록 목록 테이블(Index, Time, Type, Data Payload, Previous Hash, Current Hash).

---

## 7. 보안 및 성능

- **DB 계정**: `blockchain_ledger`에 대해 `INSERT`, `SELECT`만 부여. `UPDATE`, `DELETE` 박탈.
- **동시성**: 블록 생성 시 `SERIALIZABLE` 또는 테이블 락으로 중복 인덱스 방지.
- **위조 방지**: 이미 `SOLD`인 봉투의 QR로 다른 위치에서 SALE 시도 시 복제 QR로 간주·경고.

---

## 8. 결론

PHP 8·CodeIgniter 4로 중앙 집중형 환경에서도 **해시 연결 구조**를 통해 데이터 투명성·무결성을 보장하는 폐쇄적 블록체인을 설계함. 관리자 조작 방지 및 감사(Audit) 기능을 제공함.

---

**참고**: 원본 노션에는 Block/Chain/WasteBagController/RoleAuthFilter/BlockchainController/View에 대한 실제 PHP 코드가 포함되어 있음. 상세 구현은 프로젝트 코드베이스 또는 특허 문서·CI4 가이드를 참조함.