JobFit Agent

JobFit Agent는 취업준비생이 목표 직무의 채용공고, 회사 인재상, 본인의 기술스택과 프로젝트 경험을 입력하면 채용공고 기준의 역량 갭, 보완 학습 항목, 추천 프로젝트, 실행 로드맵, Markdown 리포트를 생성하는 Agent 서비스입니다.

이 저장소는 두 부분으로 구성되어 있습니다.

backend/: 최종 평가 핵심입니다. Python + LangChain + LangGraph 기반 Agent Core, Tool, RAG, Memory, Middleware, FastAPI, CLI 데모를 포함합니다.
src/: Next.js + TypeScript 기반 UI입니다. 입력 Wizard, 결과 화면, Human-in-the-loop, Markdown 다운로드, Python backend 호출 옵션을 제공합니다.

서비스 소개
문제 정의
사용 시나리오
전체 아키텍처
LangGraph Workflow
Backend 구성
Frontend 구성
설치 및 실행
환경변수
FastAPI API
CLI 데모
LangChain Tool
RAG
Memory
Middleware / Guardrail
Pydantic / OutputParser
Next.js UI 사용법
개인정보 보호
검증 명령어
한계점 및 향후 개선
자주 나는 오류

서비스 소개

JobFit Agent는 채용공고와 사용자 경험 사이의 차이를 분석해 취업 준비 계획으로 바꾸는 서비스입니다.

사용자는 다음 정보를 입력합니다.

목표 직무
채용공고 원문
회사 인재상 또는 핵심가치
사용자 기술스택
사용자 프로젝트 경험
자기소개서 또는 경험 서술
준비 가능 기간
선호 프로젝트 방식
현재 수준

Agent는 다음 결과를 제공합니다.

채용공고 요구역량 요약
사용자 보유 역량 분석
부족 역량과 우선순위
공부로 보완할 항목
프로젝트로 증명할 항목
추천 프로젝트 3개
선택 기간 기준 학습 로드맵
포트폴리오 산출물 체크리스트
Markdown 최종 리포트

문제 정의

취업준비생은 채용공고를 읽어도 실제로 어떤 역량을 준비해야 하는지 판단하기 어렵습니다.

주요 문제는 다음과 같습니다.

채용공고의 담당업무, 필수사항, 우대사항을 구조화하기 어렵습니다.
본인의 프로젝트 경험이 공고 요구사항을 얼마나 증명하는지 알기 어렵습니다.
공부로 보완할 항목과 프로젝트로 증명할 항목을 구분하기 어렵습니다.
준비 기간이 짧을 때 무엇을 줄이고 무엇을 남겨야 하는지 판단하기 어렵습니다.
포트폴리오 README와 면접에서 어떤 근거를 보여줘야 하는지 명확하지 않습니다.

JobFit Agent는 이 문제를 LangGraph 기반 Agent workflow로 나누어 처리합니다.

사용 시나리오

대표 사용자는 백엔드 개발 직무를 준비하는 취업준비생입니다.

사용자가 백엔드 개발 채용공고를 입력합니다.
회사 인재상과 협업 문화 문구를 입력합니다.
본인의 FastAPI, Docker, 프로젝트 경험, 자기소개서 내용을 입력합니다.
준비 기간을 4주로 선택합니다.
Agent가 채용공고와 사용자 경험을 비교합니다.
RAG가 로컬 직무 지식 문서를 검색해 추천 근거를 보강합니다.
Agent가 부족 역량, 추천 프로젝트, 4주 로드맵을 생성합니다.
사용자는 Human-in-the-loop 패널에서 “너무 어려움”, “더 실무적으로” 같은 피드백을 입력합니다.
선택한 프로젝트 기준으로 로드맵을 다시 생성합니다.
최종 Markdown 리포트를 다운로드합니다.

멀티턴 예시:

1턴: 백엔드 개발 직무에 맞춰 분석해줘
2턴: Docker 경험은 있는데 Kubernetes는 없어
3턴: 4주 안에 가능한 프로젝트로 줄여줘

전체 아키텍처

flowchart LR
    user[사용자] --> ui[Next.js UI]
    user --> cli[Python CLI Demo]
    user --> docs[FastAPI /docs]

    ui --> proxy[Next.js API Proxy<br/>/api/python-agent/jobfit/jobs]
    proxy --> jobs[FastAPI Background Job API]
    jobs --> api[LangGraph Agent 실행]
    cli --> state_graph[LangGraph StateGraph]
    docs --> api

    api --> guard[Middleware / Guardrail]
    guard --> state_graph

    state_graph --> tools[LangChain Tools]
    state_graph --> rag[RAG<br/>Markdown docs + Chroma]
    state_graph --> memory[Memory<br/>session_id + MemorySaver]

    tools --> response[AgentResponse / FinalReport]
    rag --> response
    memory --> response

    response --> dashboard[ResultDashboard]
    response --> markdown[Markdown Report]

실행 경로는 크게 3개입니다.

FastAPI 단독 실행: POST /agent/jobfit
Cloudflare Tunnel 경유 실행: POST /agent/jobfit/jobs 후 상태 조회
CLI 실행: python cli_demo.py --sample --once
Next.js UI 실행: Wizard에서 Python LangGraph Agent 사용 옵션 선택

LangGraph Workflow

Workflow 구현 위치:

backend/app/graph_workflow.py
backend/app/graph_nodes.py
backend/app/graph_state.py
backend/docs/workflow.mmd
backend/docs/workflow.md
docs/workflow.mmd
docs/WORKFLOW_DIAGRAM.md
docs/workflow.png

이미지 다이어그램:

Mermaid 다이어그램:

flowchart TD
    START([START]) --> input_validation[input_validation_node]

    input_validation --> validation_route{route_after_validation}
    validation_route -- "입력 부족" --> clarification[clarification_node]
    validation_route -- "입력 충분" --> job_posting[job_posting_analysis_node]

    job_posting --> user_profile[user_profile_analysis_node]
    user_profile --> rag[rag_retrieval_node]
    rag --> gap[gap_analysis_node]

    gap --> gap_route{route_after_gap_analysis}
    gap_route -- "추가 정보 필요" --> clarification
    gap_route -- "추천 가능" --> tool_selection[tool_selection_node]

    tool_selection --> project[project_recommendation_node]
    project --> roadmap[roadmap_generation_node]
    roadmap --> final_report[final_report_node]

    clarification --> END([END])
    final_report --> END

Workflow Node

Node	역할
`input_validation_node`	입력 길이, 필수값, 개인정보 마스킹, 추가 입력 필요 여부를 검사합니다.
`job_posting_analysis_node`	채용공고와 회사 인재상에서 담당업무, 필수역량, 우대역량, 기술 키워드를 추출합니다.
`user_profile_analysis_node`	사용자 기술스택, 프로젝트 경험, 자기소개서에서 확인된 역량과 근거가 약한 역량을 나눕니다.
`rag_retrieval_node`	목표 직무와 부족 역량 기준으로 로컬 RAG 문서를 검색합니다.
`gap_analysis_node`	공고 요구역량과 사용자 보유역량을 비교합니다.
`tool_selection_node`	다음 실행 단계와 사용 Tool을 결정합니다.
`project_recommendation_node`	부족 역량을 증명할 프로젝트 3개를 추천합니다.
`roadmap_generation_node`	준비 기간 기준 학습 및 프로젝트 로드맵을 생성합니다.
`final_report_node`	최종 구조화 응답과 Markdown 리포트 기반 데이터를 생성합니다.
`clarification_node`	입력이 부족하면 추가 입력 요청 메시지를 생성하고 종료합니다.

Conditional Edge

backend/app/graph_workflow.py에는 조건부 분기가 2개 있습니다.

함수	분기	설명
`route_after_validation`	`clarification` / `analyze`	필수 입력이 부족하면 추가 질문으로 종료하고, 충분하면 공고 분석으로 진행합니다.
`route_after_gap_analysis`	`clarification` / `recommend`	갭 분석 후 핵심 정보가 부족하면 추가 질문으로 종료하고, 충분하면 프로젝트 추천으로 진행합니다.

Mermaid 문자열은 API로도 확인할 수 있습니다.

curl http://127.0.0.1:8001/agent/workflow-mermaid

Backend 구성

backend/README_BACKEND.md의 핵심 내용을 메인 README에도 포함했습니다. 평가자는 이 섹션과 backend/ 코드를 보면 Python 제출 요구사항을 확인할 수 있습니다.

backend/
  main.py                         FastAPI 엔트리포인트
  cli_demo.py                     터미널 실행용 CLI 데모
  requirements.txt                Python 의존성
  .env.example                    backend 환경변수 예시
  README_BACKEND.md               backend 빠른 안내

  app/
    api.py                        FastAPI route
    config.py                     pydantic-settings 기반 환경변수 로딩
    graph_state.py                LangGraph state TypedDict
    graph_nodes.py                LangGraph node 함수
    graph_workflow.py             StateGraph 구성, conditional edge, MemorySaver
    memory.py                     session_id 기반 인메모리 저장소
    middleware.py                 입력 검증, 마스킹, 로깅, 안전한 에러
    schemas.py                    Pydantic 요청/응답 모델, OutputParser

  tools/
    job_posting_tools.py          analyze_job_posting_tool
    project_tools.py              search_jobfit_rag_tool, recommend_project_tool
    report_tools.py               generate_markdown_report_tool

  rag/
    loader.py                     Markdown 문서 로딩 및 chunk 분할
    retriever.py                  Chroma vector store, embedding, 검색
    documents/
      backend_skills.md
      embedded_skills.md
      interview_evaluation_criteria.md
      it_infra_skills.md
      portfolio_checklist.md
      project_templates.md
      sw_it_role_competency_map.md

  docs/
    workflow.mmd                  Mermaid workflow 원본
    workflow.md                   Workflow 설명 문서

Backend 핵심 파일

파일	역할
`backend/main.py`	FastAPI 앱 생성, middleware 설치, router 등록
`backend/app/api.py`	`/health`, `/agent/jobfit`, `/agent/workflow-mermaid` 엔드포인트
`backend/app/graph_workflow.py`	LangGraph `StateGraph`, conditional edge, MemorySaver 구성
`backend/app/graph_nodes.py`	Agent workflow node 함수
`backend/app/schemas.py`	Pydantic 모델과 `PydanticOutputParser`
`backend/app/middleware.py`	guardrail, 개인정보 마스킹, 안전한 에러 응답
`backend/app/memory.py`	`session_id` 기반 인메모리 세션 저장
`backend/tools/`	LangChain `StructuredTool` 구현
`backend/rag/`	로컬 Markdown 문서 기반 RAG
`backend/cli_demo.py`	FastAPI 없이 실행 가능한 CLI 데모

Frontend 구성

src/
  app/
    layout.tsx
    page.tsx
    globals.css
    api/
      analyze/gap/route.ts
      analyze/job-posting/route.ts
      analyze/user-profile/route.ts
      recommend/projects/route.ts
      recommend/roadmap/route.ts
      report/final/route.ts
      python-agent/jobfit/route.ts
      python-agent/jobfit/jobs/route.ts
      python-agent/jobfit/jobs/[jobId]/route.ts

  components/jobfit/
    InputWizard.tsx
    ResultDashboard.tsx
    HumanReviewPanel.tsx
    DemoDataButton.tsx
    MarkdownExportButton.tsx
    StatusNotice.tsx
    steps/
    results/

  lib/
    ai/
    demo/
    errors/
    privacy/
    prompts/
    report/
    schemas/
    types/

Frontend 핵심 파일

파일	역할
`src/components/jobfit/InputWizard.tsx`	입력 Wizard, 분석 실행, Python Agent 호출, 결과 상태 관리
`src/app/api/python-agent/jobfit/jobs/route.ts`	분석 작업을 시작하는 Cloudflare 대응 proxy
`src/app/api/python-agent/jobfit/jobs/[jobId]/route.ts`	분석 완료 여부와 결과를 조회하는 proxy
`src/components/jobfit/ResultDashboard.tsx`	최종 분석 결과 표시
`src/components/jobfit/HumanReviewPanel.tsx`	준비 기간, 수준, 프로젝트 선호, 피드백 기반 로드맵 재생성
`src/components/jobfit/MarkdownExportButton.tsx`	Markdown 미리보기, 복사, 다운로드
`src/lib/schemas/jobfit.ts`	Zod 입력/출력 schema
`src/lib/report/markdown.ts`	Markdown 리포트 생성

설치 및 실행

Windows PowerShell 기준입니다.

1. Python 가상환경 생성

cd C:\Ucode\11_AIboot_FINAL
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r backend\requirements.txt

PowerShell 실행 정책 때문에 Activate.ps1이 막히면 현재 터미널에서만 허용합니다.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
.\.venv\Scripts\Activate.ps1

가상환경 활성화 없이 직접 실행할 수도 있습니다.

C:\Ucode\11_AIboot_FINAL\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt

2. 환경설정 파일 생성

루트 .env.example을 복사해서 .env를 만듭니다. 프론트 포트, 백엔드 포트, Python Agent API 요청 위치를 여기서 관리합니다.

Copy-Item .env.example .env

기본값:

FRONTEND_PORT=3001
BACKEND_HOST=127.0.0.1
BACKEND_PORT=8001
AGENT_BACKEND_URL=http://127.0.0.1:8001

AGENT_BACKEND_URL을 비워두면 Next.js proxy가 http://BACKEND_HOST:BACKEND_PORT로 요청합니다.

3. Python backend 실행

터미널 1:

cd C:\Ucode\11_AIboot_FINAL
.\.venv\Scripts\Activate.ps1
.\scripts\dev.ps1 backend

정상 확인:

curl http://127.0.0.1:8001/health

FastAPI 문서:

http://127.0.0.1:8001/docs

4. Next.js UI 실행

터미널 2:

cd C:\Ucode\11_AIboot_FINAL
npm install
.\scripts\dev.ps1 frontend

브라우저:

http://127.0.0.1:3001

backend와 frontend는 각각 다른 터미널에서 계속 실행해야 합니다.

환경변수

루트 `.env.example`

OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.5
MOCK_AI=false

FRONTEND_PORT=3001
BACKEND_HOST=127.0.0.1
BACKEND_PORT=8001
AGENT_BACKEND_URL=http://127.0.0.1:8001

JOBFIT_BACKEND_MOCK=false
JOBFIT_BACKEND_LOG_LEVEL=INFO

backend `.env.example`

OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.5
EMBEDDING_MODEL=text-embedding-3-small
APP_ENV=development
BACKEND_HOST=127.0.0.1
BACKEND_PORT=8001
JOBFIT_BACKEND_MOCK=false

환경변수 설명

이름	사용 위치	설명
`OPENAI_API_KEY`	Next.js server route, Python backend	OpenAI API Key입니다. 코드에 하드코딩하지 않습니다.
`OPENAI_MODEL`	Next.js / Python backend	사용할 모델명입니다. 기본 예시는 `gpt-5.5`입니다.
`EMBEDDING_MODEL`	Python RAG	OpenAI embedding 모델명입니다.
`MOCK_AI`	Next.js API route	`true`이면 Next.js 자체 Mock AI 경로가 동작합니다.
`JOBFIT_BACKEND_MOCK`	Python backend	`true`이면 외부 OpenAI API 대신 로컬 fallback을 사용합니다. 제출/실제 분석은 `false` 권장입니다.
`FRONTEND_PORT`	`scripts/dev.ps1 frontend`	Next.js UI 실행 포트입니다.
`BACKEND_HOST`	`scripts/dev.ps1 backend`, Next.js proxy	Python backend host입니다.
`BACKEND_PORT`	`scripts/dev.ps1 backend`, Next.js proxy	Python backend port입니다.
`AGENT_BACKEND_URL`	Next.js proxy	외부 backend 주소를 직접 지정할 때 사용합니다. 비우면 `BACKEND_HOST`와 `BACKEND_PORT`를 조합합니다.
`APP_ENV`	Python backend	실행 환경명입니다.

FastAPI API

구현 위치: backend/app/api.py

Method	Path	응답	설명
`GET`	`/health`	`HealthResponse`	서버 상태, 환경명, 모델명을 반환합니다.
`POST`	`/agent/jobfit`	`AgentResponse` 또는 `ErrorResponse`	LangGraph Agent를 실행합니다.
`POST`	`/agent/jobfit/jobs`	작업 ID	장시간 분석을 백그라운드에서 시작합니다.
`GET`	`/agent/jobfit/jobs/{job_id}`	작업 상태 또는 결과	`running`, `done`, `failed` 상태를 조회합니다.
`GET`	`/agent/workflow-mermaid`	`text/plain`	LangGraph workflow Mermaid 문자열을 반환합니다.

Next.js UI는 Cloudflare Tunnel의 장시간 HTTP 요청 제한을 피하기 위해 작업 시작 후 3초 간격으로 결과를 조회하며 최대 5분 동안 기다립니다. /agent/jobfit은 FastAPI /docs와 로컬 단독 테스트용으로 유지합니다.

`/agent/jobfit` 요청 필드

backend/app/schemas.py의 JobFitRequest 기준입니다.

필드	타입	필수	설명
`session_id`	`str	None`	선택
`user_message`	`str`	필수	사용자의 자연어 요청입니다.
`job_posting`	`str	None`	권장
`company_values`	`str	None`	선택
`user_skills`	`list[str]	None`	선택
`user_projects`	`str	None`	권장
`self_intro`	`str	None`	선택
`target_role`	`str	None`	권장
`preparation_weeks`	`int	None`	선택
`preferred_project_type`	`str	None`	선택

PowerShell 요청 예시

$body = @{
  session_id = "demo-session"
  user_message = "백엔드 개발 직무에 맞춰 역량 갭과 4주 로드맵을 추천해줘"
  target_role = "백엔드 개발"
  job_posting = "담당업무: FastAPI 기반 API 개발, 데이터 모델링, 운영 로그 분석, 역할 분담 문서화. 필수요건: Python, SQL, Docker, 테스트 경험. 우대사항: Redis, CI/CD, 배포 자동화, 모니터링 경험."
  company_values = "협업, 문제해결, 문서화, 지속적인 학습"
  user_skills = @("Python", "FastAPI", "Docker")
  user_projects = "FastAPI API 서버를 만들고 README와 실행 방법을 작성했습니다. Docker로 로컬 실행 환경을 구성했고 pytest로 주요 API를 검증했습니다."
  self_intro = "프로젝트에서 문제를 로그로 분석하고 테스트를 추가해 재발을 줄인 경험이 있습니다."
  preparation_weeks = 4
  preferred_project_type = "개인"
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Method POST `
  -Uri http://127.0.0.1:8001/agent/jobfit `
  -ContentType "application/json" `
  -Body $body

CLI 데모

구현 위치: backend/cli_demo.py

샘플 1회 실행

cd C:\Ucode\11_AIboot_FINAL
.\.venv\Scripts\Activate.ps1
cd backend
python cli_demo.py --sample --once

샘플 실행 후 멀티턴 입력

python cli_demo.py --sample

직접 입력 모드

python cli_demo.py

종료하려면 exit를 입력합니다.

LangChain Tool

구현 위치: backend/tools/

Tool	파일	구현 방식	역할
`analyze_job_posting_tool`	`job_posting_tools.py`	`StructuredTool.from_function`	채용공고와 회사 인재상에서 담당업무, 필수역량, 우대역량, 인재상 키워드, 기술 키워드를 추출합니다.
`search_jobfit_rag_tool`	`project_tools.py`	`StructuredTool.from_function`	로컬 Markdown RAG 문서를 검색합니다.
`recommend_project_tool`	`project_tools.py`	`StructuredTool.from_function`	부족 역량, 목표 직무, 준비 기간, 사용자 수준, RAG 근거를 바탕으로 프로젝트 3개를 추천합니다.
`generate_markdown_report_tool`	`report_tools.py`	`StructuredTool.from_function`	최종 분석 결과를 Markdown 보고서 문자열로 변환합니다.

RAG

구현 위치:

backend/rag/loader.py
backend/rag/retriever.py
backend/rag/documents/*.md

검색 대상 문서

문서	용도
`backend_skills.md`	백엔드 직무 역량, 필수 기술, 프로젝트 기준
`embedded_skills.md`	임베디드 소프트웨어 직무 기준
`it_infra_skills.md`	IT 인프라 직무 기준
`project_templates.md`	프로젝트 설계 템플릿
`portfolio_checklist.md`	포트폴리오 산출물 체크리스트
`interview_evaluation_criteria.md`	면접 평가 기준
`sw_it_role_competency_map.md`	SW/IT 17개 직무별 필수 역량과 추천 CS 지식

동작 방식

loader.py가 backend/rag/documents/*.md 파일을 로딩합니다.
Markdown 제목과 섹션을 기준으로 chunk를 만듭니다.
retriever.py가 Chroma EphemeralClient collection을 구성합니다.
OPENAI_API_KEY가 있으면 OpenAIEmbeddings를 사용합니다.
API Key가 없거나 embedding 호출이 실패하면 HashEmbeddingProvider가 fallback으로 동작합니다.
검색 결과는 문서명과 제목 출처를 포함합니다.
검색 결과는 rag_context에 저장되어 갭 분석과 프로젝트 추천에 사용됩니다.

Memory

구현 위치:

backend/app/memory.py
backend/app/graph_workflow.py

현재 Memory는 인메모리 방식입니다.

session_id 또는 thread_id 기준으로 대화 상태를 분리합니다.
LangGraph MemorySaver를 checkpointer로 사용할 수 있게 구성했습니다.
InMemorySessionStore가 최근 대화 이력과 마지막 GraphState를 저장합니다.
후속 질문에서 이전 채용공고, 사용자 경험, 분석 결과를 이어받습니다.
서버 재시작 후에는 저장된 이력이 사라집니다.

예시:

1턴: 백엔드 개발 직무에 맞춰 분석해줘
2턴: Docker 경험은 있는데 Kubernetes는 없어
3턴: 4주 안에 가능한 프로젝트로 줄여줘

Middleware / Guardrail

구현 위치: backend/app/middleware.py

기능	설명
입력 길이 제한	너무 긴 입력을 제한합니다.
필수 입력 검증	`user_message`, `job_posting`, `target_role`, 사용자 경험 부족 여부를 판단합니다.
짧은 입력 감지	채용공고나 사용자 경험이 너무 짧으면 추가 입력 요청 플래그를 만듭니다.
개인정보 마스킹	이메일, 전화번호, 주민등록번호 형태를 정규식 기반으로 마스킹합니다.
안전한 로그	채용공고, 자기소개서, 프로젝트 원문은 로그에서 `[REDACTED]` 처리합니다.
안전한 에러	stack trace, API Key, 내부 오류 정보를 사용자에게 노출하지 않습니다.
FastAPI middleware	요청 path, status, elapsed time, env를 로그로 남깁니다.

Pydantic / OutputParser

구현 위치: backend/app/schemas.py

주요 Pydantic 모델

모델	역할
`JobFitRequest`	Agent 입력 요청
`JobPostingAnalysis`	채용공고 분석 결과
`UserProfileAnalysis`	사용자 역량 분석 결과
`GapAnalysis`	역량 갭 분석 결과
`ProjectRecommendation`	추천 프로젝트
`RoadmapItem`	주차별 로드맵 항목
`Roadmap`	전체 로드맵
`FinalReport`	최종 구조화 리포트
`AgentResponse`	정상 API 응답
`ErrorResponse`	안전한 에러 응답

OutputParser

get_result_parser()가 LangChain PydanticOutputParser를 제공합니다.

return PydanticOutputParser(pydantic_object=AgentStructuredResult)

FastAPI 응답은 response_model=AgentResponse | ErrorResponse로 구조화되어 있습니다.

Next.js UI 사용법

.\scripts\dev.ps1 frontend로 UI를 실행합니다.
브라우저에서 http://127.0.0.1:3001에 접속합니다.
샘플 데이터 버튼으로 IT 인프라, 임베디드, 백엔드 예시를 채울 수 있습니다.
입력 Wizard의 마지막 단계까지 이동합니다.
기본값인 Python LangGraph Agent 사용 상태에서 분석을 실행합니다.
기존 Next.js OpenAI/Mock 경로를 비교하려면 해당 옵션을 해제합니다.
분석 결과가 ResultDashboard에 표시됩니다.
Python LangGraph 원문 JSON 결과는 접기/펼치기 패널로 확인할 수 있습니다.
Human-in-the-loop 패널에서 준비 기간, 현재 수준, 프로젝트 선호, 피드백을 수정할 수 있습니다.
Markdown 리포트를 미리 보고 복사하거나 .md 파일로 다운로드할 수 있습니다.

Python backend 연결 방식

구현 위치: src/app/api/python-agent/jobfit/jobs/route.ts, src/app/api/python-agent/jobfit/jobs/[jobId]/route.ts

Next.js route handler는 .env 설정을 기준으로 Python backend의 백그라운드 작업 API를 호출합니다.

AGENT_BACKEND_URL 값이 있으면 그 주소를 사용합니다.
비어 있으면 http://BACKEND_HOST:BACKEND_PORT/agent/jobfit로 요청합니다.

localhost 대신 127.0.0.1을 기본값으로 둔 이유는 Windows 환경에서 Node fetch가 IPv6 ::1로 붙어 uvicorn 연결에 실패하는 경우를 줄이기 위해서입니다.

Ubuntu 서버 및 Cloudflare Tunnel

서버 내부 포트는 frontend 3001, backend 8001 기준입니다. 외부에는 Cloudflare Tunnel로 frontend만 공개해도 됩니다. Next.js 서버가 같은 서버의 FastAPI를 127.0.0.1:8001로 호출하기 때문입니다.

git clone https://github.com/OPCIO0568/Jobfit.git
cd Jobfit
python3 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
npm ci
cp .env.example .env

.env에서 최소 다음 값을 설정합니다.

OPENAI_API_KEY=실제_키
OPENAI_MODEL=gpt-5.5
EMBEDDING_MODEL=text-embedding-3-small
APP_ENV=production
JOBFIT_BACKEND_MOCK=false
BACKEND_HOST=127.0.0.1
BACKEND_PORT=8001
FRONTEND_PORT=3001
AGENT_BACKEND_URL=http://127.0.0.1:8001

실행:

# 터미널 1
cd ~/Jobfit/backend
source ../.venv/bin/activate
python -m uvicorn main:app --host 127.0.0.1 --port 8001

# 터미널 2
cd ~/Jobfit
npm run build
npm run start -- -p 3001

Cloudflare Tunnel의 origin은 http://127.0.0.1:3001로 연결합니다. backend를 별도 도메인으로 공개할 필요는 없습니다. 백그라운드 작업은 현재 프로세스 메모리에만 저장되므로 backend를 여러 worker로 실행하지 말고 단일 worker로 실행해야 합니다.

개인정보 보호

API Key는 .env에서만 읽습니다.
OpenAI API Key를 클라이언트에 전달하지 않습니다.
자기소개서, 프로젝트 경험 원문은 DB에 저장하지 않습니다.
backend Memory는 인메모리 방식이며 서버 재시작 시 사라집니다.
이메일, 전화번호, 주민등록번호 형태는 정규식 기반으로 마스킹합니다.
민감한 입력 원문은 로그에 남기지 않습니다.
내부 stack trace와 API Key는 사용자 응답에 포함하지 않습니다.
AI 결과는 취업 성공을 보장하지 않는 참고 자료로 표시합니다.

검증 명령어

Python backend

cd C:\Ucode\11_AIboot_FINAL
.\.venv\Scripts\Activate.ps1
python -m compileall backend
cd backend
python cli_demo.py --sample --once

FastAPI 실행 후:

curl http://127.0.0.1:8001/health
curl http://127.0.0.1:8001/agent/workflow-mermaid

Next.js

cd C:\Ucode\11_AIboot_FINAL
npm run lint
npm run build
npm test

한계점 및 향후 개선

현재 한계점

실제 채용공고 크롤링은 없습니다.
이력서 PDF 자동 파싱은 없습니다.
GitHub 저장소 자동 분석은 없습니다.
RAG 문서는 데모용 일반화 문서입니다.
Chroma vector store는 메모리 기반입니다.
Memory는 서버 재시작 후 유지되지 않습니다.
Python backend의 일부 분석은 API Key가 없을 때 규칙 기반 fallback으로 동작합니다.
AI 분석은 참고용이며 취업 성공이나 합격을 보장하지 않습니다.

향후 개선 방향

Chroma persistent store 또는 FAISS index 저장
DB 기반 사용자 세션 저장
LangSmith tracing
채용공고 URL 수집 Tool
GitHub 프로젝트 분석 Tool
PDF 이력서 파싱 Tool
Human-in-the-loop feedback을 LangGraph node로 확장
실제 LLM 기반 tool selection 강화
RAG 문서 추가와 검색 품질 평가

자주 나는 오류

`Invalid value for '--port'`

명령어가 한 줄에 붙어서 실행된 경우입니다.

잘못된 예:

python -m uvicorn main:app --reload --port 8001c:\Ucode\11_AIboot_FINAL\.venv\Scripts\activate

올바른 예:

python -m uvicorn main:app --reload --port 8001

Next.js에서 Python Agent 502

Python backend가 실행 중인지 확인합니다.

curl http://127.0.0.1:8001/health

backend가 정상인데도 실패하면 Next.js dev 서버를 재시작합니다.

`Activate.ps1` 실행 정책 오류

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
.\.venv\Scripts\Activate.ps1

터미널은 몇 개가 필요한가?

backend와 frontend를 같이 보여주려면 터미널 2개가 필요합니다.