8. 상세 설계서

ERD — 데이터 모델에서 테이블 관계·컬럼·변경 근거를 확인합니다. 구현의 측정 기록은 검증 결과와 구현 근거로 연결합니다.

구현 기준: 2026-10-01, feat/warning-copy · 750b4e5 (BE v0.63.0 / FE v0.52.1). 운영 배포 완료를 뜻하지 않습니다. 검증 결과와 원문 근거.

개발개요

백엔드의 판정(verdict)·설명(agent)·검색(rag)·자금 계산(finance)을 분리하고 Next.js 기능별 화면으로 연결했습니다. 9/28 당시 “판정 구현 중”이던 설명과 현재 상태를 혼동하지 않도록 9/28 상세 설계 기록을 보존했습니다.

Data Flow (아키텍처링)

원천 자료 → 지역·업종 집계 → 규칙 판정 배치 → 판정 API → 지도 카드, 그리고 판정·검색·지원 후보 → 사실 선수집 → LLM 설명 → 리포트가 두 주요 경로입니다. 자금 계획은 같은 동·업종 맥락을 받되 별도 결정론 엔진을 사용합니다. 시스템 아키텍처

목적과 기능

모듈	현재 책임	근거 코드
master·store·commerce·neighborhood	원천 기준·점포 이력·분기 실적·동네 맥락	`backend/apps/`의 각 BC
verdict	판정·배치·대안·백테스트	`verdict/domain/services`·API 라우터
rag	청크·임베딩·코사인 검색·뉴스 사건 접기	`rag_repository.py`, `rag_interactor.py`
agent	13키 사실 수집·6절 리포트·스트리밍·저장	`report_facts.py`, `section_stream.py`
funding·finance	후보 공고·지원 안내·비용 계산·상담 질문	`support_guide.py`, `engine.py`
admin·ops	계정·접근 제어·운영 관측	각 ORM·라우터

데이터베이스 설계 (ERD)

현재 브랜치에서 ORM 테이블 이름 47개를 정적으로 확인했습니다. 9/23 실DB 36테이블 기록과 측정 방식이 다릅니다. 추가 테이블·관계·판정 행의 상세는 ERD에 있습니다. 이번 작업은 DB 마이그레이션 적용 상태를 재측정하지 않았습니다.

요구사항 별 상세설계

요구사항 #1 — 창업 경고·근거·대안

신호: 순유출·생존 절벽·조기 폐업·포화는 등급에 참여하고 상권 축소는 참고만 표시합니다.
상대평가: 같은 업종의 평가 가능한 값에서 strict 백분위를 계산합니다. 75 이상 on, 90 이상 strong. 점포·코호트·폐업 표본 10, 포화의 상주인구 1,000 가드를 사용합니다.
등급 순서: 평가 가능한 판정 신호 2개 미만이면 보류 → strong 2개 이상 비추천 → 켜진 신호 1개 이상 조건부 → 경고 없음.
저장: 동 코드·업종 복합키로 등급·신호 JSON·산출일·원천(basis)을 보관합니다. 카드가 한 묶음으로 읽는 신호 JSON은 명시적 역정규화입니다.
대안: clear·orange 후보 중 기준보다 (등급 순위, strong, on)이 낮은 것만 축별 최대 3개. 다른 동 후보는 같은 최신 동네 유형으로 제한합니다.
화면: region·industry·budget을 URL에 전달합니다. 요약·판정은 독립 조회하고 제외·404·빈 대안을 별도로 처리합니다.

요구사항 #2 — 사실 선수집과 설명 리포트

ReportFactsCollector는 6개 스레드로 자료를 독립적으로 조회합니다. 결과 13키는 region·verdict·alternatives·profile·hour_gap·commerce_change·metrics_history·population·shocks·analogs·news·funding_candidates·budget입니다. 항목 오류는 자료 없음으로 표현하고 동일 사실을 화면과 LLM에 전달합니다.

남은 도구는 뉴스 검색·공고 검색·재무 시뮬레이션·월세/매입 비교 4종입니다. 월세/매입 비교 도구가 남아 있는 것과 /plan의 주 사용자 흐름은 다릅니다. 리포트는 판정·이유·유사 사례·조건·대안·지원사업 6개 절이며 섹션 마커가 토큰 경계에서 갈라져도 분할기가 이어 붙입니다.

요구사항 #3 — 지원 정보·자금 계획

GET /funding/support가 대출·보증, 자치구 전용, 창업·경영 묶음을 반환합니다. 구 이름과 업종의 낱말 규칙으로 무관한 공고를 줄이며 자격을 확정하지 않습니다.

finance/domain/services/engine.py에서 초기 비용과 6개월 동안의 고정비 준비액을 합산합니다. 자기자본 외 조달 필요액과 희망대출 반영 후 부족액을 구분합니다. 손익분기 매출은 고정비 ÷ (1−원가율−수수료율), 매출 시나리오는 기준의 0.6·1.0·1.6배 가정입니다. 이는 매출 예측 모델이 아닙니다.

핵심 설계 선택과 트러블슈팅

문제	선택과 이유	검증 근거	남은 한계
자료 부족을 안전으로 읽을 위험	보류 규칙을 가장 먼저 검사	`rules.py`·`thresholds.py`와 경계 테스트	소규모 업종 보류가 많고 가드 통과가 신뢰구간을 보장하지 않음
상권 축소 신호가 차이를 못 가름	등급 합산에서 제외하고 참고로 유지	9/29 백테스트 신호별 전체 lift 0.96배	단일 시점·업종 구성의 영향
LLM의 반복 조회·수치 조립 오류	사실 선수집, 유사 사례 고정 문장, 토큰 스트리밍	BE v0.45.0·v0.58.0~v0.59.0 기록과 현행 코드	자유 설명은 계속 검토 필요
자치구 유사 사례 값이 크게 흔들림	1,000곳 가드 실험 후 서울 전체 계산으로 되돌림	BE v0.63.0: 무사건 분기의 한식 강세·약세 비율, 구 58~89%·서울 34%	서울 전체도 인과 식별 불가
자금 계획 재방문 시 옛 결과만 남음	sessionStorage 복원 제거, 화면 상태만 유지	FE v0.51.0·`plan-page.tsx`	장기 초안 저장 기능 없음
키워드가 다른 업종·구를 가리킴	구 이름 낱말 경계·업소 지칭 표현으로 후보 규칙 정정	BE v0.60.0·v0.62.0 실측 기록	규칙만으로 신청 자격 판단 불가

표의 실험 수치는 저장된 과거 기록이며 이번 문서 작업에서 재실행한 수치가 아닙니다. 검증 결과와 원문 근거

ERD — 데이터 모델