PROJECT DOCUMENTATION

5.1. 최종 검수

배포 갱신·접수 완료 · 최종 배포본 재검수 기록 필요기준일 2026-09-20담당 장민석 · PM/아키텍트

설치·실행 재현, 배포 환경 동작, 예외 처리와 유지보수 절차를 확인합니다.

검수 기준

접수 전 검수 대상은 두 가지입니다. ① 로컬 개발 환경에서 핵심 시나리오 재현은 9월 18일에 확인했습니다. ② 배포 주소(localhostdaegu.cloud)의 흐름 검증은 9월 19일 페르소나 10건 모두 상담자료까지 도달했습니다. 후속 수정 18건은 로컬에서 다시 10/10 통과했습니다. 9월 20일 팀 확인 기준 최신 변경 배포 갱신과 접수는 완료했습니다. 최종 배포본의 추가 검수 결과는 별도 기록이 필요합니다. 별도 고객 환경으로의 구축·이전은 현재 작업 목록에 없습니다.

검수 항목	통과 조건	현재 판정
자동 테스트	백엔드·프론트엔드 테스트 결과와 실행 시점 확인	원본 로그 기준 pytest 603 passed · 1 skipped, Vitest 226/46 files(9/19 밤)
핵심 시나리오	질문 → 지도 → 최초 계산·재계산·계획 선택 → 상담자료 → 공식 안내	로컬 통과 — 확장된 깔때기·AI 리포트 E2E PASS(9/18)
배포 환경	배포 주소에서 전체 흐름과 AI 리포트 실시간 전송	첫 배포 검증 통과(9/19) — 페르소나 10/10·SSE 순차 수신
데이터 해석	지표의 분모·기간·건수, 위험도 표현이 확인 가능한 사실만 말함	연도 전달·분모 설명·30일 규칙·상대 순위·추정 라벨 반영 완료. 스냅샷 2~4주 관측 후 재평가

개발 환경 — HW / SW

항목	내용	현재 상태
HW	로컬 개발 머신, 모델 평가 GPU는 NVIDIA RTX 5060 Ti 16 GB	qwen + gemma4 동시 상주 11.58 GiB 실측(9/18). 기본 서비스 경로는 Gemini 유지
SW	Python 3.14 · FastAPI, Next.js 16 · React 19, PostgreSQL 17 + pgvector, Redis 7 · Neo4j 5(미사용), Docker Compose	로컬 검증
AI	기본 Gemini API, 로컬 대체 qwen3-embedding:4b@2560·gemma4:12b	양쪽 모델 평가 완료. 2560 halfvec 변경·Gemini 재색인·provider 설정화 완료(9/19). 자동 폴백 없음
네트워크	백엔드 8300, 프론트엔드 3300. 데이터 스토어는 `127.0.0.1`에만 공개(5437·6381·7476·7689)	9/19 Vercel + Cloudflare Tunnel 첫 배포
검수 버전	9/19 밤 작업 로그 기준	최종 제출 커밋·배포 버전은 별도 기록 필요. 코드 프리즈 해제(DEC-018)

개발 내용 Flow와 동작 과정

시작 → 설정 확인 → 입력 → 데이터 처리 → AI 추론 → 결과 확인 → 로그 확인 → 종료의 실제 경로입니다. 상세 동작은 상세 설계와 같습니다.

데이터 스토어와 백엔드·프론트엔드를 실행하고 백엔드 상태 확인(/health).
첫 화면에 한 문장 입력 → 지역·업종·예산 인식.
지도에서 행정동 지표·위험도 확인(기본 2025년).
비용·자금 입력 → 최초안 계산 → 조건 수정·현재안 계산 → 자금 구성 비교·계획 선택.
상담자료 생성 → 계획·비교·계산표·정책자금·질문·상권 확인 → Markdown 다운로드·브라우저 인쇄/PDF 저장·공식 안내 확인. 지역 분석(review)도 별도 검증.
수집 로그(logs/*.log)와 서버 로그에서 오류·키 흔적이 없는지 확인.

설치·소스 이전 매뉴얼

서비스 저장소 인수인계 문서에 적힌, 실제로 실행해 확인한 명령입니다.

docker compose up -d db redis neo4j                       # 데이터 스토어
cd backend && .venv/bin/python -m pytest tests/ -q        # 테스트 전용 DB 자동 생성
cd backend && .venv/bin/uvicorn main:app --port 8300      # 백엔드
cd frontend && npm run dev                                # 프론트엔드 :3300
cd frontend && npx vitest run                             # 프론트엔드 테스트
node frontend/tests/funnel.cjs                            # 깔때기 E2E(headless)

소스 저장소를 받고 main의 검수 버전 확인
Python 가상환경·Node 의존성 설치
루트 .env 또는 backend/.env에 외부 API 키 입력(값은 커밋하지 않음)
데이터 스토어 실행, 마이그레이션·마스터 시드 적용
수집기 실행으로 공공데이터 적재(인허가 전량 약 18분), 검색 색인 생성
서비스 실행과 /health 확인
핵심 시나리오 재현(E2E 스크립트)
crontab 등록, 로그 확인·재시작

알려진 재현 제한: 새로 받은 저장소에서는 일부 테스트가 저장소에 없는 원본 데이터 파일을 요구해 그대로 통과하지 않습니다. 새 환경에서 처음부터 설치해 재현하는 절차는 아직 검증하지 않았습니다.

이 Jekyll 문서 사이트의 실행 방법은 저장소 README에 따로 정리했습니다.

로컬 → 배포 환경 이전

배포 구조는 Vercel(프론트엔드)·로컬 GPU 머신 + Cloudflare Tunnel(백엔드)·로컬 Docker(DB)로 정했습니다. 장민석이 구조를 맡고 김충식이 백엔드, 류준이 프론트엔드를 배포합니다. 9월 19일 Cloudflare 네임서버 이전과 첫 배포를 마쳤습니다. 운영 주소에서 페르소나 10건을 확인했으며 9월 20일 팀 확인 기준 최신 변경 배포 갱신과 접수도 완료했습니다. 서비스 저장소에 배포 런북과 가이드를 작성했습니다.

확인 항목	기록할 내용	상태
배포 대상	프론트엔드 Vercel, 백엔드 로컬 머신의 Tunnel, DB 로컬 Docker	첫 배포 완료(9/19) · 배포 갱신 완료(9/20 팀 확인)
환경 대응	Gemini 키, `CORS_ALLOW_ORIGINS`, 워커 1개, `NEXT_PUBLIC_API_BASE`, SSE 버퍼링 해제	운영 CORS 두 오리진 허용·타 오리진 400 확인. 추가 수집기 키의 운영 검증 결과는 별도 기록 필요
데이터 보관	로컬 DB 유지, 백업·복원 및 운영 수집 절차 확인	최종 운영 검수 전
연결 확인	도메인·TLS, 프록시 뒤 SSE 스트림, 외부 API	첫 배포 스모크 통과(9/19)
재검증	같은 입력으로 깔때기·AI 리포트 재실행	운영 페르소나 10/10·개선 후 로컬 10/10. 최종 배포본 재검수는 남음
복구	배포 실패 시 되돌리는 절차	미정

사용자 설정·예외 처리

사용자가 조정하는 값	범위·기본값	반영 시점
지도 기준 연도	2019~2026, 기본 2025. 2026은 “(집계 중)”	분석 요청에서 지표·위험도까지 전달, 캐시 프록시 누락 수정·검증
재무 입력 13항목	금액 0 이상, 비율 0 이상 1 미만, 원가율 + 수수료율 < 1. 대출금리 기본값은 최신 중소기업 대출금리(실패 시 4.5%)	시뮬레이션 실행 시
AI 추가 질문	500자 이하	분석 시작 시
상담 계산안	최초안·현재안·선택안·변경 이유, 미입력 확인 목록	계산·선택 시 화면 초안 갱신, 자료 생성 시 서버 스냅샷 기록

검수한 예외 동작(잘못된 입력 422, 없는 분석 요청 404, AI 실패 시 대체 문구)은 TC-004에 정리했습니다.

유지보수와 검수 결과

이 페이지의 통과 표시는 원본 서비스 작업 로그의 결과입니다. 최신 수치는 9/19 밤 603/226을 사용하고 개별 검증의 환경·시점은 구분합니다(실행 결과 기준).

현재 판정: 로컬·첫 배포 검증 통과 · 배포 갱신·접수 완료(9/20 팀 확인) · 최종 배포본 재검수 기록 필요. 테스트 번호별 상세 결과는 시나리오 테스트에 있습니다.