PROJECT DOCUMENTATION

2. 요구사항 정의서

사전상담·후속 과제 반영 · 일부 보완 예정기준일 2026-09-19담당 장민석 · PM/아키텍트

창업 금융 네비게이터의 기능·품질 요구사항을 구현 상태와 검증 근거로 정리합니다.

9월 19일 밤 작업 로그 기준
주 동선을 계약 전 창업자금 사전상담으로 전환했습니다(DEC-017). 아래의 구현은 원본 작업 로그에 구현·로컬 검증이 기록됐다는 뜻입니다. 첫 배포의 운영 페르소나 10건은 검증했습니다. 실제 창업 판단에 대한 유효성은 아직 검증하지 않았습니다.

개발 개요

계약을 검토하는 예비 창업자가 한 문장 질문(지역·업종·예산)으로 시작해 자리를 고르고, 자금계획의 최초안과 현재안을 비교한 뒤 선택안을 상담자료로 준비합니다. iM뱅크 공식 안내로 이동할 수 있지만 자료가 은행에 전송되지는 않습니다. 대상 지역은 대구 8개 구·군(군위군 제외) 144개 행정동, 업종은 인허가 7업종입니다. 기존 사업자 운영 개선은 이번 범위에서 제외합니다.

상태 표기	뜻
구현	9/18 작업 로그에 구현·로컬 테스트 통과가 기록됨
부분 구현	동작하지만 요구사항의 일부가 빠져 있음
예정(P0)	접수 전 보완 우선 항목. 아직 구현하지 않음. 기존 코드 프리즈는 해제됨(DEC-018)
제외	이번 접수 범위에서 뺀 항목

REQ-001 · 세무·매출 AI 도우미

항목	내용
상태	제외 — 로드맵으로 이동
사유	개별 가게의 실매출·정산 자료를 확보할 수 없습니다. 카드 소비 데이터는 DIP 빅데이터활용센터에 있지만 이용·반출 조건을 확인하지 못했습니다(OPEN-004).
남긴 것	처음 검토한 주제로 기록만 유지합니다. 관련 기능·API·테스트는 없습니다.

REQ-002 · 창업 자금 점검과 금융상품 연결

처음 검토한 “청년창업 매칭”을 자금 계산과 금융상품 연결로 구체화했습니다.

항목	내용
사용자 요구	계약 전에 월세·투자비를 바꿔 필요한 매출과 자금을 비교하고, 선택한 계획으로 은행 상담을 준비하고 싶다.
입력	보증금·권리금·인테리어·설비, 월세·인건비·보험, 원가율·수수료율, 자기자본·희망 대출·대출금리, 예상 월매출(사용자 가정)
출력	초기 투자비·6개월 운영준비금·총 준비자금·자기자본 외 조달 필요액·희망대출 반영 후 남는 부족액·손익분기 매출·시나리오·금리 스트레스. 최초안·현재안 비교, 선택안 상담자료, iM뱅크 우선 후보·차선 후보
필수 조건	금액과 비교표는 코드가 계산하고 AI는 설명·질문만 쓴다. 잘못된 입력은 422. 은행 연결 근거(direct → linked → unverified)를 우선 정렬하고 같은 등급 안에서 보증 → 은행 → 정책자금 순으로 표시한다. 지역 한정 상품은 사용자 자치구로 필터링한다.
구현 상태	구현 — 사전상담 T1~T7, 미입력 구분, 계산안 비교·선택, 지역 한정 매칭, 상담 세션·계획·노트·문서 기록과 세션 갱신. 완성된 상담자료만 Markdown으로 내보내고 브라우저 인쇄로 PDF 저장 가능. 대출금리 기본값은 한국은행 최신 중소기업 대출금리(조회 전·실패 시 4.5%)
해석 제한	예상 매출·6개월 운영준비금·시나리오 배수(0.6·1.0·1.6)는 가정입니다. 금리 미공개는 “은행별 상이”로 표시합니다. 재무 입력이 없으면 재무 계산과 상품 매칭을 건너뜁니다. 폼에서 확인하지 않은 금액은 미입력으로 기록해 0원이 맞는지 확인 질문을 남깁니다. 상담 후보는 대출 승인·자격 확정을 뜻하지 않습니다.
후속 확인	재단 4건 취급은행 문의, 북구 청년창업 특례보증의 2026년 재공고 확인. 계산 가정·미입력 표시는 구현 완료
연결 테스트	TC-001, TC-002, TC-004

REQ-003 · 상권 진단과 AI 리포트

처음 검토한 “골목상권 AI 컨설팅”을 행정동 단위 진단과 근거가 달린 리포트로 구체화했습니다.

항목	내용
사용자 요구	이 동네·업종의 개폐업 흐름을 보고, 근거와 함께 해석을 받고 싶다.
입력	한 문장 질문(구·동·랜드마크 15곳·업종·예산 추출), 지도에서 고른 행정동·업종·연도, 선택 질문(500자 이하)과 재무 입력
출력	지도·요약·위험도·업종별 순위와 참고 자료. review는 종합 진단·상권·충격·정책자금(재무 입력 시 계산표), handoff는 계획·비교·계산표·정책자금·확인 질문·상권
필수 조건	점수·지표표·상품 목록은 코드가 바로 내보내고 AI는 해석 문단만 쓴다. AI 호출이 실패해도 섹션은 대체 문구로 채운다. 사용자 질문이나 검색 문서 안의 지시는 따르지 않는다.
구현 상태	구현 — 의도 해석, 지도·지표·위험도 API, 목적별 리포트(SSE). 선택 연도를 리포트의 지표·위험도까지 전달하며 캐시 프록시 누락도 수정. 기본 연도는 마지막 완결 연도(2025), 2026년은 “(집계 중)” 표시
해석 제한	지표는 인허가 개업·폐업 일자로 재구성한 연도별 집계로, 현재 영업 중인 점포 수나 매출이 아닙니다. 화면의 “점포 증감률”은 매출 성장이 아니라 (개업 − 폐업) ÷ 전년 말 점포 수입니다. 위험도는 폐업률·점포 수·성장률의 지역 간 상대 순위를 섞은 값이며 창업 실패 확률이 아닙니다. 30일 이내 종료는 집계에서 제외했습니다(9/19). 학원·부동산·어린이집은 소실 추정이며, 편의점은 담배소매인 대용 지표입니다. “충격 분석”은 관련 뉴스 검색이며 정량 영향 계산이 아닙니다. 다른 구·군 전용 문서 제외는 반영됐고 기간 필터는 없습니다.
보완 완료(9/19)	① 연도 전달, ② 수행 작업 중심 AI 진행 안내, ③ 자금 점검·가정 표시, ④ 분모 설명·30일 규칙·상대 순위·추정 라벨 반영. 11업종 지표 연결 완료
연결 테스트	TC-001, TC-003, TC-004

공통 기술·품질 요구사항

번호	요구사항	판정 방법	현재 상태
NFR-001	결과의 출처·기준일을 확인할 수 있다.	결과와 출처 연결 확인	부분 구현 — AI 리포트 하단에 참고 자료(공고·뉴스)를 표시. 금융상품과 충격 이벤트는 데이터에 출처·확인일을 기록. 지표 분모 설명·선택 연도·위험도 상대 순위·추정 라벨 반영 완료
NFR-002	잘못된 입력·데이터 부족·외부 실패를 설명한다.	예외 시나리오 실행	부분 구현 — 입력 오류 422와 공통 오류 형식, AI 섹션 대체 문구, 없는 분석 요청 404. 데이터 없음 안내·확인된 사실 배지 제거 반영. 전체 지역·기간 조합 검증은 남음
NFR-003	처리량과 응답시간을 구간별로 측정할 수 있다.	요청 시작·종료·실패 기록	부분 측정 — 초기 AI 리포트 전체 10.4~13.4초, 모델 평가에서 임베딩 지연·처리량과 LLM 첫 조각·총 시간 p50·로컬 토큰 속도 측정. 서비스 부하·p95는 미측정
NFR-004	동일 데이터와 설정으로 검증을 재현할 수 있다.	버전·설정·데이터 기록	부분 구현 — 테스트 전용 DB를 자동 생성·마이그레이션·시드. 일부 테스트가 저장소에 없는 원본 데이터 파일을 요구해 새로 받은 저장소에서는 재현 불가
NFR-005	필요한 데이터만 처리하고 자격증명을 코드와 분리한다.	입력·저장 항목 및 설정 검토	구현·키 교체 완료 — 키는 환경변수 파일로 분리(커밋 제외). 외부 API 키 하나가 서버 로그에 남은 사고 후 오류 메시지의 키 제거를 모든 해당 연동에 적용·테스트. 9/19 밤 해당 키 재발급·교체 후 단건 200·수집기 정상 종료 확인

추적표

요구사항	구현 모듈(서비스 저장소)	상세 설계	검증
REQ-001	없음(제외)	—	—
REQ-002	백엔드 finance·matching·product·consultation·shock(금리) / 프론트 simulator	자금 계산·매칭	TC-001 · TC-002 · TC-005
REQ-003	백엔드 intent·master·store·metric·analysis·rag·news·funding / 프론트 intent-gate·map-explorer·agent-report	상권 진단·AI 리포트	TC-001 · TC-003
NFR-001~005	공통 처리	설정·예외 설계	공통 예외