파일명: README.md
최종 수정일: 2026-05-12
문서 해시: SHA256:TBD 문서 역할: 프로젝트 최상위 안내 문서 / 관문 문서
문서 우선순위: 0
연관 문서: CHANGE_CONTROL.md, PRD.md, SYSTEM_ARCHITECTURE.md, DIRECTORY_SPEC.md, PROJECT_SUMMARY.md, SUMMARY.md, RAG_PIPELINE.md, Indexing_Architecture.txt
참조 규칙: 작업 시작 전 본 문서와CHANGE_CONTROL.md를 먼저 읽고, 이후 관련 상세 문서를 확인한다.
청년 위험군 단계와 관심 직무/도메인을 바탕으로, 관련 자격증을 추천하고 단계형 로드맵을 제안하는 시스템이다.
추후 시험 일정, 접수 일정, 지원 링크까지 연결할 수 있는 확장 구조를 목표로 하지만, 현재 단계에서는 추천 구조와 지식 파이프라인을 먼저 안정화하는 것을 우선한다.
[1단계] 위험군 진단
12문항 설문(관계망·활동·노동경제·정신건강·자기관리) → 1~5단계 위험군 판정
Safety Override: 자해·자살 관련 항목 "일주일 이상" 응답 시 최소 4단계 조정
↓
[2단계] 관심 분야 선택
허용된 taxonomy 안에서 관심 도메인(필수) + 희망 직무(선택) 선택
↓
[3단계] 성장 로드맵 확인
위험군 × 도메인 기반 단계형 로드맵 + 자격증별 AI 맞춤 분석
↓
[4단계] 자격증 상세 확인
자격증 클릭 → 자격 활용 현황·추천 근거·연결 경로·관련 동영상 확인
각 단계의 선택 상태는 세션에 저장되어, 네비게이션으로 이탈 후 복귀해도 컨텍스트가 유지된다.
로드맵 이후 단계는 이전 진단 없이 직접 진입할 수 없도록 파이프라인 guard가 적용되어 있다.
이 프로젝트는 아래 4개 축을 연결한다.
-
위험군 단계
- 청년 사용자의 현재 상태를 설문(12문항)으로 진단하여 1단계 ~ 5단계 구조로 관리한다.
-
구조적 추천
- 자격증을 단독 객체가 아니라 직무, 도메인, 로드맵 단계와 연결된 후보로 추천한다.
-
문서 기반 설명 근거
- PDF / HTML 기반 공식 문서에서 추천 결과를 설명할 근거를 검색한다.
-
추후 일정 확장
- 후속 스프린트에서 시험 일정, 접수 일정, 지원 링크를 연결한다.
- 진단 방식: 12문항 설문(관계망 4·활동 2·노동경제 2·정신건강 3·자기관리 1)으로 판정
- 1단계: 취업 안정권
- 5단계: 취업을 하고 싶어도 하기 어려운 가장 높은 위험군
- 2~4단계: 단계형 위험군 체계로 관리하며, 세부 의미는 후속 문서에서 확정
- Safety Override: 정신건강 항목(자살·자해)에 "일주일 이상" 이상 응답 시 최소 4단계로 조정
related_domains는 도메인 taxonomy의 세부 라벨만 사용related_jobs는 희망 직무 taxonomy의 세부 직무만 사용- 자유 텍스트 라벨 생성은 허용하지 않는다
- PDF / HTML: 설명형 지식 소스, Parse 및 indexing 대상
- CSV: 구조화 데이터 소스, structured no-parse canonicalization 대상
- API: 일정/링크 최신성 소스, 현재는 reserved 상태
- 위험군 진단 (12문항 설문 + Safety Override)
- 관심 도메인·직무 선택 (taxonomy 기반, 43개 도메인 / 142개 직무)
- 위험군 × 도메인 기반 단계형 로드맵 (5단계 경로, 전체 추천 + ✦ AI 맞춤 추천 탭)
- 자격증 상세 evidence 패널 (자격 활용 현황·자격증 소개·시험 정보·연결 경로·AI 추천 이유)
- 자격증 검색·등급 필터·자격증 목록 페이지
- 관련 YouTube 강의 영상 검색·캐싱
- 자격증 DAG (선수·후속 자격증 경로 다이어그램)
- 파이프라인 상태 sessionStorage 저장 + Roadmap 단계 강제 guard
- 공인민간자격 정보집(140종) + 국가자격 정보집(138종) 로컬 카탈로그 매핑
- Supabase pgvector RAG evidence 검색
- 청년지원제도 외부 링크 메가 메뉴
- 시험 일정·접수 일정 실연동 API
- 지원 링크 실연동
- reranker / sparse BM25 상시 사용
- parent-child chunk 고도화
- 상담형 대화 에이전트
제품 목표와 범위의 상세 정의는 PRD.md를 따른다.
| 단계 | 페이지 | 역할 |
|---|---|---|
| 1 | RiskAssessment | 12문항 설문 → 위험군 단계(1~5) 판정, 결과 레이더 차트 |
| 2 | InterestSelection | 관심 도메인(필수) + 희망 직무(선택) — taxonomy 기준 |
| 3 | Roadmap | 위험군 × 도메인 단계형 로드맵, 전체/AI 탭, 인라인 evidence 드로어 |
| 4 | Recommendation | 자격증 목록·검색·필터, evidence 패널, DAG, 관련 동영상 |
- HTML Direct Path
- Primary PDF Parser
- Table Assist / OCR / Fallback
- Chunk Builder
- Metadata Tagging
- Embedding / Retrieval
- Dataset Type Registry
- Schema Mapping
- Canonicalization
- Entity Builder
- Relation Builder
- Candidate Row Builder
이 두 흐름은 이후 canonical merge, retrieval, recommendation 계층에서 연결된다.
전체 구조의 상세 정의는 SYSTEM_ARCHITECTURE.md와 RAG_PIPELINE.md를 따른다.
이 프로젝트는 루트 md 문서를 기준선으로 운영한다.
| 문서명 | 역할 |
|---|---|
README.md |
프로젝트 입구 문서 |
SUMMARY.md |
구현된 기능·데이터·API·스택 핵심 요약 (빠른 파악용) |
PROJECT_SUMMARY.md |
저장소 한눈에 보기 — 목적·두 레인·스택·청킹 개요·긴 기법 문서 보관 위치 |
CHANGE_CONTROL.md |
문서 수정 규칙, 메타데이터 갱신 원칙, 작업 절차 |
DIRECTORY_SPEC.md |
디렉토리 구조와 파일/폴더 책임 |
ROOT_DOC_GUIDE.md |
루트 문서 탐색·읽기 순서 안내 |
HASH_INCREMENTAL_BUILD_GUIDE.md |
해시 키·증분 재처리 원칙 |
Indexing_Architecture.txt |
인덱싱/지식 파이프라인 참고 구조 문서 |
PRD.md |
문제 정의, 타깃 사용자, 제품 범위 |
SYSTEM_ARCHITECTURE.md |
시스템 계층, 책임, 데이터 흐름 |
FEATURE_SPEC.md |
기능별 입력/출력/예외처리 |
DATA_SCHEMA.md |
엔티티, 관계, candidate row, 메타데이터 구조 |
CSV_CANONICALIZATION_TEAM_GUIDE.md |
CSV 레인 담당자(영민·유빈)용 수집·매핑·canonical 지침 |
API_SPEC.md |
API 계약, request/response, 오류 형식 |
PROMPT_DESIGN.md |
프롬프트 역할, 입력 슬롯, 출력 계약 |
RAG_PIPELINE.md |
Parse / Chunk / Embedding / Retrieval 파이프라인 |
EVALUATION_GUIDELINE.md |
평가 기준, baseline, 비교 원칙 |
EVALUATION.md |
평가 결과 |
EXPERIMENT_GUIDE.md |
실험 세팅과 재현 방법 |
ERROR_ANALYSIS.md |
실패 사례와 개선 방향 |
DEV_LOG.md |
진행 로그와 변경 이력 |
Cursor IDE용 작업 규칙은 .cursor/rules/에 둔다. (루트에 동일 본문 md를 두지 않는 것을 권장한다.)
심화 참고(인덱싱·질의): 이 저장소의 파이프라인 계약은 RAG_PIPELINE.md가 우선한다. 인덱싱(Parse→Chunk→Embed·Store)과 evidence 검색 질의·Pre-retrieval을 실무 수준으로 정리한 외부 장문 기준서가 있다면 로컬에서만 참고하고, 설계 반영 시에는 루트 문서와 PRD.md·reserved 규칙을 따른다. 팀 공유가 필요 없는 자료는 docs/references/_private/에 두며 해당 경로는 Git에서 제외한다.
작업 시작 시 아래 순서로 문서를 확인한다.
README.mdCHANGE_CONTROL.mdPRD.mdSYSTEM_ARCHITECTURE.md- 작업에 직접 관련된 상세 문서
- 기능 수정 →
FEATURE_SPEC.md - 데이터 구조 수정 →
DATA_SCHEMA.md - API 수정 →
API_SPEC.md - 프롬프트 수정 →
PROMPT_DESIGN.md - RAG 파이프라인 수정 →
RAG_PIPELINE.md - 디렉토리 수정 →
DIRECTORY_SPEC.md
- 기능 수정 →
프로젝트의 최종 루트 디렉토리는 아래를 기준으로 한다.
project-root/
├─ .gitignore
├─ README.md
├─ PROJECT_SUMMARY.md
├─ CHANGE_CONTROL.md
├─ DIRECTORY_SPEC.md
├─ ROOT_DOC_GUIDE.md
├─ HASH_INCREMENTAL_BUILD_GUIDE.md
├─ Indexing_Architecture.txt
├─ PRD.md
├─ SYSTEM_ARCHITECTURE.md
├─ FEATURE_SPEC.md
├─ API_SPEC.md
├─ PROMPT_DESIGN.md
├─ DATA_SCHEMA.md
├─ CSV_CANONICALIZATION_TEAM_GUIDE.md
├─ RAG_PIPELINE.md
├─ EVALUATION_GUIDELINE.md
├─ EVALUATION.md
├─ EXPERIMENT_GUIDE.md
├─ ERROR_ANALYSIS.md
├─ DEV_LOG.md
│
├─ docs/
├─ data/
├─ frontend/
├─ backend/
├─ scripts/
├─ experiments/
├─ infra/
└─ shared/
세부 폴더 설명은 DIRECTORY_SPEC.md를 따른다.
이 프로젝트는 루트 문서 리팩토링을 거친 뒤 구현하는 방식으로 진행한다.
- 기능, 정책, 구조가 바뀌면 먼저 관련 루트 문서를 수정한다.
- 문서를 수정할 때는 상단 메타데이터의
최종 수정일도 함께 갱신한다. - 해결된 문제는 PRD에 그대로 방치하지 않는다.
- 문서 간 충돌이 생기면
CHANGE_CONTROL.md의 우선순위를 따른다. - 구조 변경 전에는
DIRECTORY_SPEC.md, 시스템 변경 전에는SYSTEM_ARCHITECTURE.md를 먼저 수정한다.
자세한 운영 규칙은 CHANGE_CONTROL.md를 따른다.
이 프로젝트는 아래 두 축을 먼저 안정화하는 것을 목표로 한다.
- CSV canonicalization 기반 추천 구조 정비
- PDF / HTML 기반 설명 근거 검색 구조 정비
즉, 현재 단계의 핵심은
완성형 일정 연동 서비스가 아니라
위험군 맞춤 추천 + 로드맵 제안 + 설명 근거 결합이 가능한 기준 구조를 만드는 것이다.
| 영역 | 선택 |
|---|---|
| 프론트 | React 19 + Vite 6 (frontend/) |
| API | FastAPI (backend/) |
| RAG 런타임 | Supabase pgvector + 로컬 카탈로그 JSON 직접 매핑 |
| 벡터 DB | Supabase pgvector (match_certificates RPC) |
| 임베딩 | OpenAI text-embedding-3-small |
| LLM | OpenAI GPT (로드맵 AI 분석, 자격증 추천 이유) |
| YouTube | YouTube Data API v3 (관련 강의 영상 검색·캐시) |
| 배포 | 프론트 Vite dev / API Render.com (https://vulnerable-groups-rag.onrender.com) |
API 프록시 타겟은 frontend/.env.local의 VITE_API_PROXY_TARGET으로 제어한다.
미설정 시 Render.com 배포 서버로 자동 연결된다.