# Goalskill (Python + 기본정보기술자 버전)

Claude가 이 프로젝트에서 일할 때 알아야 할 핵심 규칙.

---

## 0. 가장 중요한 구분

**이 레포 = JP/KR 버전, Python + 기본정보기술자(Engineer Information Processing) 자격증 학습**

- `NDA` / `SG` / `Singapore` 버전은 **별개 레포**. 여기 코드와 섞지 말 것.
- 관련 키워드가 대화에 등장하면 "별개 레포 아닌가?"를 먼저 확인할 것.
- 커리큘럼/퀴즈 콘텐츠를 제안할 때는 항상 **Python + 기본정보기술자** 전제.
- GitHub 원격: `https://github.com/smarttov/E-GOALSkill.git`

---

## 1. 학습 흐름 (확정)

```
① 온보딩(인사+이름)
    ↓
② 목표 탐색
    ↓
  ★ 테스트 패널 (MBTI / SPI / Python)   ← ②와 ③ 사이의 진단 단계 · 전부 선택적
    ↓
③ 학습계획 조사
    ↓
④ 커리큘럼 생성 (SUMMARY)
    ↓
⑤ 일일 학습 루틴
```

| 단계 | Frontend Theme | Backend Router |
|---|---|---|
| ① 온보딩 | `front/js/modules/themes/onboarding_theme.js` | `back/app/routers/onboarding_router.py` |
| ② 목표 탐색 | `front/js/modules/themes/findgoal_theme.js` | `back/app/routers/findgoal_router.py` |
| ★ 테스트: MBTI | `front/js/modules/themes/mbti_theme.js` | `back/app/routers/mbti_router.py` |
| ★ 테스트: SPI | `front/js/modules/themes/spi_theme.js` | `back/app/routers/spi_router.py` |
| ★ 테스트: Python | `front/js/modules/themes/python_theme.js` | `back/app/routers/python_router.py` |
| ★ 테스트 허브(선택 UI) | `front/js/modules/themes/selection_hub_theme.js` | — |
| ③ 학습계획 조사 | `front/js/modules/themes/studyplan_theme.js` | `back/app/routers/studyplan_router.py` |
| ④ 커리큘럼 생성 (SUMMARY) | `front/js/modules/themes/summary_theme.js` | `back/app/routers/summary_router.py` |
| ⑤ 일일 학습 루틴 | `front/js/modules/themes/curriculum_theme.js` + `journal_theme.js` | `back/app/routers/curriculum_router.py` + `general_router.py` |

**주의**: 위 순서와 파일 매핑은 팀이 확정한 것. 임의로 순서를 바꾸거나 단계를 추가/삭제하지 말 것. 구조 변경이 필요하면 먼저 질문.

### 테스트 패널 규칙 (중요)

- **완전히 선택적**. 사용자는 패널에 들어가서:
  - 하나도 안 하고 나가도 됨
  - 1개만 해도 됨
  - 2개만 해도 됨
  - 3개 다 해도 됨
- 즉 **아무것도 강제하지 않음**. "테스트를 완료해야 다음 단계로" 같은 게이트를 추가하지 말 것.
- 완료된 테스트 결과만 `A_DB.user_profile_summary` 에 저장되어 ③/④에 반영됨.

### IT → Python 테마 마이그레이션 (진행 중)

- 공식 방향: **`it_theme.js` → `python_theme.js` 로 교체 중**.
- 현재 코드 상태 (교체 미완):
  - `python_theme.js` 파일은 존재하지만 `chat.js` / `selection_hub_theme.js` 어디서도 아직 import되지 않음
  - `front/js/modules/chat.js:703-706` 와 `selection_hub_theme.js:215-218` 는 여전히 `ITTheme` 을 동적 import
  - `back/app/routers/it_router.py` 도 `main.py` 에 등록되어 활성 상태
- **Claude는 `it_theme.js` / `it_router.py` 를 마음대로 삭제하지 말 것**. 교체 배선이 끝나기 전에는 런타임이 깨짐.
- 교체 작업을 맡으면: ① `python_theme`/`python_router` 배선 추가 → ② 동작 확인 → ③ `it_*` 제거 순서로.

### 일일 학습 루틴(⑤) 내부 구조

- **A' 파트**: 컨디션 체크 (Gemini 멀티턴)
  - 같은 날 연속 학습 시 A' 생략 처리 있음 (커밋 `e78476b` 참고)
- **B 파트**: 일지(日誌)
- **C 파트**: 영상 → PPT → 퀴즈 → 저널 인터뷰(4단계)

---

## 2. 기술 스택

- **Backend**: FastAPI 0.115 · SQLAlchemy 2.0 · MySQL 8 (aiomysql)
- **Frontend**: Vanilla JS (번들러 없음) · Nginx 정적 서빙
- **AI**: Google Gemini 주력 (`google-genai` 1.56.0). OpenAI는 fallback/레거시.
- **배포**: Docker Compose (web:80, api:5450, db:3307)

---

## 3. 아키텍처 규칙

### Frontend: Theme 기반 컨트롤러

- 모든 테마는 `front/js/modules/themes/` 에 위치.
- 테마 클래스 필수 메서드: `start(chatCtrl)`, `onUserMessage(chatCtrl, text)`.
- 내부 상태는 `this.phase` 로 관리 (예: onboarding은 `greeting → name → reason → ...`).
- 완료 시 `ChatController`에 다음 테마 전이 요청.
- `localStorage` 의 `curriculumState` 로 새로고침 resume — 깨뜨리지 말 것.
- 새 테마 추가 시 **ChatController의 테마 레지스트리에 반드시 등록**.

### Backend: Router → Model → Service 3계층

- **Router** (`back/app/routers/`): FastAPI 엔드포인트, 요청 파싱, 오케스트레이션
- **Model** (`back/app/models/`): DB 접근, 데이터 변환
- **Service** (`back/app/services/`): 상태 없는 비즈니스 로직 (AI 프롬프트, 스코어링, 분류기)
- **Schema** (`back/app/schemas/`): Pydantic 요청/응답 검증

**크로스레이어 직접 호출 금지** (예: Router가 Model 건너뛰고 DB 직접 접근 X).

### 전역 규약

- 모든 API 호출에 `session_id` (UUID) 포함 — 프론트→라우터→모델→DB 전 계층 관통.
- 메시지는 `back/app/services/goalskill_classifier.py` 의 48-class 분류기를 거쳐 `chat_log_DB` 에 저장.

---

## 4. 데이터베이스 분리 규칙

| DB | 용도 |
|---|---|
| `A_DB` | **사용자 프로필 · `user_profile_summary`** (최종 목표·테스트 결과 저장소) |
| `B_DB` | **데일리 체크** (컨디션/일지/당일 학습 상태) |
| `C_DB` | **커리큘럼 관련** (`master_items`, 레슨 매핑 등) |
| `Q_DB` | 문제은행 (퀴즈 문항) |
| `Theory_DB` | 이론 콘텐츠 |
| `chat_log_DB` | 대화 로그 (48-class 분류기 결과 포함) |
| `Goalskill_DB` | 전역 · 보조 |

**목적 외 교차 쓰기 금지**. 스키마 변경 시 영향받는 Router·Model 전부 확인 후 진행.

- `final_goal` · 테스트 결과(MBTI/SPI/IT) → `A_DB.user_profile_summary`
- 일일 컨디션 체크·일지 → `B_DB`
- 레슨·커리큘럼 진도 → `C_DB`

---

## 5. Gemini / AI 프롬프트 규칙

- **Gemini가 주력**. 새 기능은 Gemini로 구현. OpenAI는 기존 코드만 유지.
- 시스템 프롬프트가 라우터에 **하드코딩** 되어 있음 (예: `findgoal_router.py` 800+줄).
  - 수정 시 **confidence 스코어링 JSON 스키마** 가 깨지지 않는지 확인.
  - `findgoal` 은 `confidence >= 0.95` 에서 목표 확정 — 이 임계값 로직은 건드리기 전 질문.
- Gemini 클라이언트는 `back/app/core/config.py` 의 `get_gemini_model()` 싱글턴으로만 접근.

---

## 6. 절대 커밋·수정 금지 파일

`.gitignore` 로 보호 중이지만 Claude가 실수로 건드리지 않도록 명시:

- `back/.env` — API 키 (Gemini, OpenAI, Weather)
- `.env` (루트)
- `back/credentials.json`, `back/token.pickle` — Google OAuth
- `docker-compose.yml` — 환경별 차이로 인해 gitignore됨
- `back/uploads/`, `back/img/`, `back/img_q/`, `back/img_explanation/`, `back/studyplan_files/` — 생성물
- `db_data/` — MySQL 볼륨
- `back/nohup.out`

---

## 7. 개발 워크플로

### 브랜치

- `main` — 프로덕션
- `development` — 통합 브랜치
- `dev-shin` — Shin Eun Chong (UI/UX)
- `dev-noh` — 백엔드 로직
- `dev-yu` — 기능 브랜치
- 흐름: `dev-*` → `development` → `main` (PR 기반)

### 자주 쓰는 명령

```bash
# 전체 스택 기동
docker-compose up -d

# 백엔드 로그
docker-compose logs -f api

# DB 접속 (컨테이너 외부에서)
mysql -h 127.0.0.1 -P 3307 -u root -p

# 백엔드 API 헬스체크
curl http://localhost:5450/
```

---

## 8. 새 기능 추가 시 체크리스트

### 새 Theme 추가

1. `front/js/modules/themes/<name>_theme.js` 작성 (`start`, `onUserMessage`, `this.phase`)
2. `ChatController` 레지스트리에 등록
3. 이전 테마에서 전이 트리거 추가
4. 필요하면 `localStorage` 키 사용 — 기존 `curriculumState` 와 충돌 없는지 확인
5. 5단계 흐름(본 문서 §1)을 깨지 않는지 검증

### 새 Router 추가

1. `back/app/routers/<name>_router.py` — FastAPI APIRouter
2. `back/app/models/<name>_module.py` — DB 접근
3. 필요하면 `back/app/services/<name>_service.py` — 비즈니스 로직
4. `back/app/schemas/` 에 Pydantic 모델
5. `back/main.py` 에 라우터 등록
6. `session_id` 파라미터 필수 포함

---

## 9. 테스트 / CI 현황

- **테스트 없음** — 기여 시 가능하면 `back/tests/` 에 pytest + `fastapi.testclient` 추가.
- **CI 없음** — GitHub Actions 도입 대기 중.
- Gemini 호출은 **mock** 처리 (실제 API 비용·flakiness 방지).

---

## 10. 언어·주석 규약

- UI 언어는 **일본어**. 사용자 대화 전반의 자연어는 일본어 기준.
- 코드 주석은 혼재 상태 (한국어·일본어·영어). 새 주석은 **한국어 또는 영어** 권장.
- `CLAUDE.md`, 커밋 메시지, PR 설명은 **한국어**.

---

## 11. 모르겠으면 먼저 질문할 것

- 5단계 흐름 순서·단계 변경
- Gemini confidence 임계값 (0.95) 변경
- DB 스키마 변경
- 테마 레지스트리 구조 변경
- `NDA` / `SG` 관련 코드 통합 요청