docs/devlog/2026-06-07.md

# 개발일지: 2026-06-07

## 오늘의 목표

자격증 문제풀이 웹 프로젝트를 GitHub 포트폴리오처럼 기록할 수 있도록 README와 docs 문서를 정리한다.

단순히 기능 목록만 적는 것이 아니라, 왜 이 구조를 선택했는지와 현재 개발 중인 상태를 초보자도 이해할 수 있게 설명하는 것이 목표였다.

## 오늘 정리한 문서

- `README.md`
- `docs/01_overview.md`
- `docs/02_architecture.md`
- `docs/03_data_pipeline.md`
- `docs/04_database.md`
- `docs/05_deployment.md`
- `docs/06_decision_log.md`
- `docs/07_troubleshooting.md`
- `docs/devlog/2026-06-07.md`

## 현재 프로젝트 이해

이 프로젝트는 자격증 시험 문제 PDF를 업로드하고, 문제를 구조화한 뒤 웹에서 풀 수 있게 만드는 앱이다.

현재 구조는 Streamlit 웹 앱을 중심으로 구성되어 있다. 문제와 풀이 기록은 PostgreSQL에 저장하고, 유사 문제 검색을 위해 Chroma를 사용한다. PDF 처리처럼 오래 걸리는 작업은 Airflow로 관리하는 방향이다.

## 오늘 확인한 실제 코드 구조

확인한 주요 파일:

- `streamlit_app.py`
- `cert_study_app/models.py`
- `cert_study_app/graphs/pdf_ingestion_graph.py`
- `cert_study_app/services`
- `dags/cert_study_pdf_ingestion_dag.py`
- `docker-compose.yml`

실제 앱에는 문제 풀이, PDF 업로드, 오답/복습, 개념 정리, 처리 현황, 시험 현황, AI 색인 흐름이 있었다.

데이터 모델에는 문제, 풀이 기록, 개념 노트, PDF 처리 작업, 문서 색인 작업이 정의되어 있었다.

## 오늘 문서화한 핵심 내용

### 1. 프로젝트 목적

PDF 문제를 사람이 직접 정리하는 부담을 줄이고, 문제 풀이와 복습까지 이어지는 학습 웹을 만드는 것이 목적이다.

### 2. 전체 아키텍처

Streamlit, PostgreSQL, Chroma, Airflow, Docker Compose가 어떤 역할을 하는지 정리했다.

`docs/02_architecture.md`에는 Mermaid 다이어그램도 추가했다.

### 3. 데이터 파이프라인

PDF 업로드부터 문제 저장까지의 흐름을 단계별로 정리했다.

주요 흐름:

1. PDF 업로드
2. `IngestionJob` 생성
3. Airflow DAG 실행
4. PDF 파싱
5. 파싱 품질 검증
6. Quality Gate
7. PostgreSQL 저장
8. Chroma 색인

### 4. PostgreSQL과 Chroma의 역할 분리

PostgreSQL은 원본 문제와 풀이 기록을 정확하게 저장하는 기준 저장소로 설명했다.

Chroma는 유사 문제 검색을 위한 보조 색인으로 설명했다.

### 5. 기술 선택 이유

의사결정 기록 문서에 다음 내용을 ADR 형태로 정리했다.

- Streamlit 선택 이유
- PostgreSQL 선택 이유
- Chroma 선택 이유
- Airflow 선택 이유
- Docker Compose 선택 이유
- Oracle Cloud Ubuntu 배포 계획
- 품질 게이트를 두는 이유

## 현재 개발 중인 부분

이 프로젝트는 아직 완성된 운영 서비스가 아니다. 개인 프로젝트로 기능과 구조를 계속 다듬는 중이다.

현재 중요하게 보고 있는 개선점:

- PDF 파싱 정확도 개선
- 문제 청킹 품질 검증
- 품질 리포트 UI 개선
- 북마크 기능
- 시험별 진도율과 정답률
- 중복 문제 감지
- Oracle Cloud Ubuntu 배포
- 테스트 자동화

## 오늘의 결정

문서는 과장된 완성형 서비스 소개가 아니라, 현재 개발 중인 개인 프로젝트라는 점을 분명히 드러내는 방향으로 작성했다.

또한 README는 짧게 전체를 소개하고, 자세한 내용은 `docs/` 문서로 연결하는 구조로 정리했다.

## 다음 작업 후보

- `.env.example` 점검
- GitHub 업로드 전 불필요한 런타임 파일 제외 확인
- Oracle Cloud 배포 절차 실제 검증
- PDF 파싱 품질 리포트 화면 개선
- 북마크 기능 설계 및 구현
- README에 스크린샷 추가

## 추가 진행 내용

GitHub와 Hugging Face Space 배포 자동화를 정리했다. Hugging Face에는 로컬 DB나 PDF 원본을 직접 올리지 않고, 배포용 seed와 필요한 정적 이미지만 올리는 방식으로 구성했다.

배포용 seed는 `scripts/export_hf_seed.py`로 생성한다. 기준 문제 데이터는 `data/Json/questions.json`을 사용하고, 공통 지문과 공통 지문 원문 이미지는 `data/parsed_json/reparsed_multipage_images_20260601_205501.json`에서 보강한다.

현재 배포용 seed에는 321문항이 들어 있다. 공통 지문이 있는 문항은 `parent_stem`과 `parent_image_paths`를 함께 가진다.

문제풀이 UI에서는 Yes/No 진술형 문제를 일반 객관식이 아니라 진술별 `예 / 아니오` 매트릭스로 표시하도록 개선했다. `1-A / 1-B / 2-A / 2-B`처럼 항목별 선택이 필요한 문제는 항목별 select로 표시한다.

일자별 Git 변경 확인을 쉽게 하기 위해 `scripts/git_daily_changes.sh`를 추가했다.

```bash
scripts/git_daily_changes.sh 2026-06-07
```

## 문제 유형/모바일 UI 개선

문제 유형이 여러 형태로 들어오면서 화면 표시와 채점 기준이 어긋날 수 있는 문제가 있었다. 예를 들어 `Hotspot (True/False)`, `True/False (In-Context)`, `Hotspot (Drag and Drop)`처럼 원문에서 온 유형명이 내부 로직과 정확히 맞지 않으면 Yes/No 문제가 객관식처럼 보이거나, 순서가 중요한 답안이 일반 복수 선택처럼 비교될 수 있었다.

이를 줄이기 위해 다음 구조를 추가했다.

- `answer_normalizer.py`: Yes/No, 객관식, 복수 선택, 순서형 답안을 비교 가능한 형태로 정규화
- `question_type_metadata_service.py`: 다양한 문제 유형명을 내부 표준 유형으로 변환
- `tests/test_answer_normalizer.py`: 정답 정규화 테스트
- `tests/test_question_type_metadata_service.py`: 문제 유형 alias 테스트

모바일 화면은 문제풀이를 첫 번째 동선으로 두고, 업로드/처리 현황/AI 색인은 관리 영역으로 묶었다. 답안 선택 UI는 터치하기 쉽도록 버튼과 radio 영역의 높이와 간격을 조정했다.

## 배포/품질 보완

추가로 배포 전에 놓치기 쉬운 부분을 정리했다.

- seed 갱신 시 사람이 검수한 문제를 기본적으로 덮어쓰지 않도록 보호
- seed export 결과를 `questions_seed.report.json`으로 저장
- `scripts/check_quality.py`로 문법 검사와 핵심 테스트를 한 번에 실행
- GitHub Actions `quality-check.yml` 추가
- `.env.example` 추가
- Docker Compose에서 비밀번호와 모델 설정을 환경 변수로 분리
- `CHANGELOG.md` 추가