# 화장품 제조 AI 품질예측 솔루션

원료 계근 데이터 기반으로 제조 완료 **전** 품질(pH·경도·비중·함량·점도·적합여부)을
예측하고, 기준 이탈을 사전 경고하며, 데이터 기반 제조 의사결정을 지원하는 시스템.

## 요구사항 매핑

| 요구사항 | 구현 |
|---|---|
| ❶ 계근 데이터 기반 품질 예측 체계 | `cq_weighing` 계근 연계 → `features.py` 피처화 → 예측 → `cq_prediction` 저장 |
| ❷ 물성 품질 예측 AI 모델 | XGBoost 회귀(물성) + 분류(적합/부적합), 데이터 부족 시 RandomForest 자동 전환 |
| ❸ 품질 이상 사전 경고 | `predictor._evaluate_warnings` 기준 이탈/경계 판정 + SHAP 영향 원료 분석 → `cq_warning`,`cq_impact` |
| ❹ 데이터 기반 의사결정 지원 | SHAP 영향도, What-if 시뮬레이션(`/simulate`), 배합비교·이력조회 |

## 아키텍처

```
[PHP 대시보드]  ──HTTP/JSON──▶  [Python Flask 예측 API]
   index.php                       app.py
   action.php  ◀──예측결과/경고──   predictor.py / trainer.py / features.py
       │                                   │
       └────────── MySQL (cosmetics_qpred) ─┘
```

## 설치

### 1. 데이터베이스
```bash
mysql -u root -p -e "CREATE DATABASE cosmetics_qpred DEFAULT CHARSET utf8mb4;"
mysql -u root -p cosmetics_qpred < sql/schema.sql
mysql -u root -p cosmetics_qpred < sql/seed.sql      # 마스터/기준 샘플
```

### 2. Python 예측 엔진
```bash
cd api
pip install -r requirements.txt
# 환경변수로 DB 접속정보 설정 (또는 config.py 기본값 사용)
export CQ_DB_HOST=127.0.0.1 CQ_DB_USER=root CQ_DB_PASS=비밀번호 CQ_DB_NAME=cosmetics_qpred

python gen_demo_data.py    # (선택) 데모용 220배치 합성 데이터 생성
python trainer.py          # 모델 학습 → model/quality_model.pkl
python app.py              # 예측 API 기동 (포트 5005)
```
운영 시: `gunicorn -w 2 -b 0.0.0.0:5005 app:app`

### 3. PHP 프론트엔드
`php/` 폴더를 웹서버(Apache/Nginx + PHP-FPM) 도큐먼트 루트에 배치.
`php/config/db.php` 의 `DB_*`, `PRED_API` 값을 환경에 맞게 수정.
필요 확장: `mysqli`, `curl`.

## API 명세 (Python, 포트 5005)

| 메서드 | 경로 | 설명 |
|---|---|---|
| GET | `/health` | 상태 확인 |
| POST | `/train` | 품질검사 데이터로 모델 재학습 |
| POST | `/predict` `{batch_no}` | 예측 + 경고 + 영향도 (DB 저장) |
| POST | `/simulate` `{batch_no,material_code,delta_pct}` | What-if 시뮬레이션 |
| GET | `/model_info` | 현재 모델 정보 |

## 운영 워크플로

1. 계근 시스템이 `cq_weighing` 에 배치 원료 투입 실적 적재 (편차율 포함)
2. 교반 전 `/predict` 호출 → 물성·적합여부 예측, 기준 이탈 시 경고 발생
3. 작업자가 대시보드에서 경고 확인 → 영향 원료/보정 방향 파악
4. What-if 로 원료 조정 효과 검토 후 보정
5. 교반·검사 완료 후 실측값을 `cq_quality` 에 입력 → 누적 데이터로 주기적 재학습

## 모델 신뢰도 안내
- 최소 10배치부터 학습 가능하나, **200배치 이상** 누적 시 신뢰도 확보 권장
- 80배치 미만은 RandomForest, 이상은 XGBoost 자동 적용
- 검증 결과(합성 220배치): pH MAE≈0.06, 경도 MAE≈0.42, 분류 F1≈0.75