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를 추가했다.

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 추가