docs: add project docs and test updates
This commit is contained in:
taekyoungc
121
docs/종량제 관련 자료/종량제 개발목록/노션_정리_04-블록체인_기술구현보고서.md
Normal file
121
docs/종량제 관련 자료/종량제 개발목록/노션_정리_04-블록체인_기술구현보고서.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# 기술 구현 보고서: 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 가이드를 참조함.
|
||||
Reference in New Issue
Block a user