청사진 (CheongSaJin)
청년 정책금융 AI PB 웹서비스 MVP.
내가 가진 돈 + 활용할 수 있는 정책을 합쳐 목표가 실제로 가능한지 계산하고 실행까지 연결합니다.
회원가입/로그인 → 목표 자연어 입력 → STEP1 정책 판정(중복 선택)
→ STEP2 필요 자금 계산 → STEP3 시뮬레이션·최종 확정 → STEP4 소비 진단(상시) → STEP5 실행 로드맵
상시 탭: 소비 습관 진단 · 신용 빌드업 (비금융 신용 가점 · 알뜰폰 매칭 · XP/등급)
목표가 있으면 다음 접속 시 곧바로 대시보드로 진입합니다.
지금 바로 실행하기 (계정·키 없이 전 기능 동작)
python dev-server.py
→ http://127.0.0.1:8777
데모 계정 (심사위원용, 회원가입 없이 즉시 로그인)
엔진 회귀 테스트: http://127.0.0.1:8777/test.html — 두 페르소나 전 구간을 검증합니다.
구조
public/ 정적 프론트 (빌드 없음, ES 모듈)
index.html 랜딩 · 목표 자연어 입력
auth.html 로그인 / 회원가입(정책 판정 정보 수집)
app.html STEP 1~5 + 대시보드 (해시 라우팅)
test.html 엔진 회귀 테스트
js/
rules.js ★ 정책 자격 판정 (4단계) + 중복 수혜 조합 판정
calc.js ★ 금융 계산 (필요 자기자본·부족액·시뮬레이션·달성률)
fintox.js ★ 소비 위험 점수 + 문자 파서 + Smart Prescription
credit.js ★ 비금융 신용 가점 + 알뜰폰 매칭 + XP/등급
goalparse.js 자연어 목표 파서 (규칙 기반, AI는 보정만)
store.js 인증·저장 어댑터 (supabase | localStorage 자동 전환)
app.js 화면 컨트롤러
ycapi.js 온통청년 API 정책 → 판정 엔진용 변환
ics.js 신청일 캘린더 알림(.ics) 생성
regions.js 법정시군구코드
data/
policies.json ★ 정형 정책 DB 16종 (금융 파라미터 포함)
dummy_tx.txt 팀 제공 카드 이용내역 96건
mvno.json 알뜰폰 데이터 구간별 요금 범위 (검증 전)
api/ Vercel 서버리스 (키 은닉 전용)
config.js 공개 설정 전달 (anon key 등)
policies.js 온통청년 청년정책 API 프록시 + 응답 정규화
ai.js Claude 프록시 (목표 파싱 · 결과 설명)
db/schema.sql Supabase 테이블 + RLS + 가입 트리거
docs/API코드정보.xlsx 온통청년 공식 코드정의서
설계 원칙 (설계서 Trust Architecture 준수)
- 판정과 계산은 코드가, 설명만 LLM이.
rules.js / calc.js가 결론을 내고 api/ai.js는 그 JSON을 문장으로 풀어 쓰기만 합니다. 시스템 프롬프트에 금액 생성·승인 단정·감정 추정 금지가 박혀 있습니다.
- "승인/확정/100%" 표현 금지. 모든 금액에 "상품상 최대한도 기준 1차 자격검토 결과" 고지가 붙습니다.
- 모든 판정에 근거·출처·기준일 노출. STEP 1에서 행을 펼치면 조건별 통과/미통과와 계산식이 보입니다.
- 판별 불가는 판별 불가라고 표시. 결제대행사 이름만 남은 건은 추측하지 않고 사용자에게 분류를 요청합니다.
배포 (Vercel)
- 이 폴더를 GitHub 저장소로 push
- Vercel → Add New Project → 저장소 import → Framework Preset: Other
(
vercel.json이 outputDirectory: public을 지정하므로 추가 설정 불필요)
- Settings → Environment Variables 에
.env.example 항목 입력
- Deploy
로컬에 Node.js가 없어도 GitHub 연동 방식이면 배포됩니다.
vercel CLI로 배포하려면 Node 20+ 설치가 필요합니다.
환경변수 (전부 선택 — 없으면 자동으로 대체 동작)
| 변수 | 없을 때 동작 |
|---|
SUPABASE_URL / SUPABASE_ANON_KEY | localStorage 모드로 동작 (계정·데이터는 브라우저에만 저장) |
YOUTH_API_KEY | 정형 정책 DB 17종만 사용 (‘정책 모아보기’의 지역 정책 확장이 비활성) |
ANTHROPIC_API_KEY | 규칙 기반 파서·설명만 사용 |
ANTHROPIC_WORKSPACE_ID | identity-linked 키를 쓸 때만 필요 (없으면 anthropic-workspace-id is required 오류) |
즉 키가 하나도 없어도 전 기능이 동작하고, 키를 넣는 순간 해당 기능만 실제 연동으로 승격됩니다.
Supabase 설정
- 프로젝트 생성 → SQL Editor에
db/schema.sql 붙여넣고 실행
- Authentication → Providers → Email 활성화 (데모라면 "Confirm email" 끄기 권장)
- Project Settings → API 에서 URL과 anon key를 Vercel 환경변수에 입력
온통청년 API 키
youthcenter.go.kr 회원가입 → 마이페이지 > OPEN API → 신청 → 담당자 심사 후 승인.
실제 응답으로 검증 완료 (2026-09-03, 총 2,750건 조회 확인)
{ "resultCode": 200, "resultMessage": "성공적으로 데이터를 가지고 왔습니다.",
"result": { "pagging": { "totCount": 2750, ... }, "youthPolicyList": [ ... ] } }
실제 데이터에서 확인된 특이사항을 api/policies.js 에 반영했습니다.
| 특이사항 | 처리 |
|---|
빈 필드가 빈 문자열이 아니라 공백 8칸(' ') | trim 후 빈 값이면 null |
aplyYmd 가 "20260818 ~ 20260903" 한 덩어리 문자열 | ~ 로 쪼개 start/end 로 분리 |
날짜가 하이픈 없는 YYYYMMDD | YYYY-MM-DD 로 변환 |
lclsfNm/mclsfNm 이 콤마 다중값 | 배열로 파싱 |
earnMaxAmt: 0 = 소득 무관 | income_max: null 로 정규화 |
| 분류명이 코드정의서와 다름 | 코드표의 교육/복지문화/참여권리 → 실제는 교육･직업훈련/금융･복지･문화/참여･기반. 실제 응답 기준으로 맞춤 |
| 신청 URL이 52%가 비어 있음 | CTA 렌더링 시 방어 처리 |
정규화 로직을 실제 응답 200건에 돌려 이상 0건을 확인했습니다.
화면 연결 — 정책 모아보기 탭에서 거주지 기준으로 조회합니다 (마포구+서울 = 482건).
계산에 쓰는 정형 DB 17종과 달리 금액은 만들지 않고 자격 판정만 합니다. API에 금융 파라미터가 없기 때문입니다.
운영기관이 특정 지자체여도 지역코드를 전국(250여 개)으로 등록한 정책이 많아, 그대로 나열하면
마포구 사용자에게 의성군 정책이 뜹니다. 그래서 지역 범위를 우리 지역 전용 / N개 지역 / 전국으로
구분해 배지로 표시하고, 같은 판정 안에서는 지역 전용 정책을 위로 정렬합니다.
두 목록 모두 10개씩 페이지네이션됩니다.
정책 DB
public/data/policies.json 17종. 온통청년 API가 연령·소득·지역 요건은 주지만 대출한도·보증금 비율·금리를 주지 않아서 목표 자금 계산에 필요한 금융 파라미터는 정형 DB로 직접 관리합니다.
전세자금(택1) 청년 버팀목 / 서울 임차보증금 / 중기청(확인 필요) / 카뱅(민간)
주택구입(택1) 신혼 디딤돌 / 신생아 특례 / 보금자리론
자산형성 청년미래적금 / 청년도약계좌(종료) / 청년내일저축계좌 / 내일채움공제(종료) / ISA
현금지원 청년월세 특별지원 / 서울 청년수당
생활비 절감 K-패스 / 기후동행카드 / 지역사랑상품권
중복 수혜 규칙 — exclusive_groups로 관리합니다.
one : 같은 그룹에서 1건만 실행 가능 (전세대출끼리, 구입대출끼리)review : 동시 수혜 가능 여부 확인 필요 (청년도약계좌 ↔ 내일저축계좌)- 그룹 없음 : 성격이 다르므로 합산 (대출 + 지원금 + 적금)
수치 검증 결과 (2026-09-03 기준)
17종 중 12종 원문 대조 완료. 검증 과정에서 판정을 뒤집는 오류 5건을 발견해 정정했습니다.
| 정책 | 잘못돼 있던 것 | 정정 |
|---|
| 청년도약계좌 | 상시 모집으로 표기 | 2025.12 신규 가입 종료 → 종료 판정 + 후속 상품 청년미래적금 신규 추가 |
| 청년내일채움공제 | 상시 모집으로 표기 | 신규 가입 중단(사실상 폐지) → 종료 판정 |
| 청년월세 지원 | 월 20만 × 12개월 = 240만 | 최대 24개월 = 480만, 2026년부터 한시→상시사업 전환 |
| 신혼부부 디딤돌 | 한도 4억 | 3.2억으로 축소 |
| 신생아 특례 | 한도 5억 / 소득 1.3억 | 한도 4억(2025.6.27 이후 계약분) / 부부합산 2억(1인 1.3억 초과 불가) |
그 외 정정: 버팀목 금리 2.0~3.1% → 1.8~2.7% · 서울 임차보증금 소득기준 4,000만 → 5,000만(2026.6.5 상향) · 보금자리론 소득 1억 → 일반 7,000만/신혼 8,500만(결혼상태별 상한을 엔진이 지원하도록 확장) · K-패스 청년 환급률 30% → 45% · 기후동행카드 청년 연령 만34 → 만39
미검증으로 남긴 5종 — 화면에 "검증 전" 배지가 그대로 뜹니다.
| 정책 | 이유 |
|---|
| 중소기업 취업청년 전월세대출 | "2024.12 일몰 종료"로 적어뒀으나 근거를 확인하지 못해 철회. 2026년 연장 안내는 확인됨 → '신규 접수 확인 필요'(조건부)로 변경 |
| 카카오뱅크 전월세 | 민간 상품이라 금리·한도 수시 변동 |
| 청년내일저축계좌 | 2026년 모집 공고 원문 미확인 |
| ISA | 서민형/일반형 비과세 한도 구분 미확인 |
| 지역사랑상품권 | 지자체별 할인율·구매한도가 달라 단일값 검증 불가 |
알뜰폰 요금표(mvno.json)는 모요 시세와 대조해 구간을 조정했습니다(7GB급 16,300~18,500원 등).
금리·한도는 공시 시점에 따라 수시로 바뀝니다. 발표 당일 아침에 verified: true 항목도 한 번 더 훑어보시길 권합니다.
FinTox 점수 규칙
팀이 제공한 실제 카드내역 96건을 분석해서 배점을 정했습니다.
| 규칙 | 배점 | 근거 |
|---|
| 단건 이상치 | 35 | 개인 중앙값(14,695원)의 4.5배 = 상위 10% 커트라인 66,000원과 일치 |
| 목표 저축 잠식 | 25 | 결제액 ÷ 월 저축목표 |
| 반복 결제 | 20 | 30일 내 동일 가맹점 횟수 (쏘카 9회·피플카 4회 등 실제 패턴) |
| 야간 결제 | 10 | 22~06시. 낮게 잡은 이유: 야간 금액 비중 41%는 122만 원짜리 1건이 만든 착시였고, 그 건을 빼면 12.5%로 떨어짐 |
| 예산 소진율 | 10 | 이번 달 누적 지출 ÷ 가용 예산 |
하지 않는 것
- 카테고리별 감점 없음 — 더미 데이터 지출 2위가 교육/자격(52만 원)이었습니다. 카테고리로 벌점을 주면 자기계발이 '낭비'로 찍힙니다.
- 감정·심리 확률 추정 없음.
- 업종 추측 없음 — 96건 중 결제대행사 이름만 남은 건이 다수라 "업종 미상"으로 표시하고 사용자 분류를 받습니다.
Smart Prescription이 실제 데이터에서 잡아낸 것: 대중교통 정기권(기후동행 56,770원)을 쓰면서 카셰어링에 214,088원을 추가 지출 → 교통비 이중지출 경고.
STEP 3 시뮬레이터 — 슬라이더 2개와 D-Day 연동
목표 금액 슬라이더와 월 저축액 슬라이더가 있고, 둘 중 무엇을 움직여도 도달 시점·정책 판정·달성 가능성이 즉시 다시 계산됩니다.
| 구분 | 설명 |
|---|
| 목표 D-Day | 시작일 + 목표 기간. 저축액과 무관하게 고정 |
| 예상 D-Day | 시작일 + 실제 필요 개월수. 저축 속도에 따라 실시간으로 움직임 |
설계서 8p 시연 포인트가 그대로 재현됩니다 — 월 58.3만 원 D-761 → 70만 원 D-608.
목표 금액을 바꾸면 정책 판정 자체가 달라집니다. 주택가격·보증금 상한 조건에 걸리기 때문이며, 바뀐 정책은 "판정이 바뀌었습니다" 카드에 이전 → 이후로 표시됩니다.
이지은 (금융자산 1.99억, 월 200만 저축)
7억 → 🔴 현재 계획으로는 어려움 + 보금자리론이 주택가격 상한 초과로 '대상 아님'으로 전환
6억 → 🔴 현재 계획으로는 어려움 · 예상 D-639 (목표 D-365 대비 274일 지연)
5억 → 🟢 달성 가능권 · 지금 실행 가능 (추가 저축 불필요)
목표 금액 슬라이더는 탐색용이라 저장되지 않습니다. 확정하려면 "이 금액으로 목표 변경"을 눌러야 하며, 그 전까지는 상단에 탐색 중 배너가 뜹니다.
AI가 실제로 쓰이는 지점
원칙: 판정·계산은 코드가, 해석·설명만 AI가. 금액을 AI가 만들어내지 않습니다.
| 위치 | 태스크 | AI가 하는 일 | AI가 없으면 |
|---|
| 랜딩 목표 입력 | parse_goal | 규칙 파서가 못 찾은 값만 보정 (기존 값은 덮어쓰지 않음) | 규칙 파서 결과 그대로 사용 |
| STEP 1 판정 상세 | explain_verdict | "AI에게 이 판정 설명 듣기" 버튼 — 요청할 때만 호출 | 버튼 자리에 안내 문구 |
| STEP 2 청사진 | explain_blueprint | 계산 결과를 받아 "그래서 뭘 해야 하는지" 설명 | 규칙 기반 결론 문장만 |
| STEP 4 소비 진단 | explain_fintox | 점수와 근거를 받아 목표 영향 해석 | 규칙 기반 처방만 |
정직성 장치 — 헤더에 AI 연결됨 / AI 미연결 상태가 항상 표시됩니다. 키가 없으면 신뢰 배지의 AI ADVICE가 자동으로 꺼지고 규칙 기반으로 바뀝니다. AI가 만든 문장에만 AI ADVICE 배지와 모델명이 붙어 출처가 구분됩니다. AI 호출이 실패해도 규칙 기반 결과는 그대로 남습니다.
AI 배선 검증 방법 (키 없이)
python dev-server.py --mock-ai
/api/config와 /api/ai를 가짜로 응답해 4개 지점이 모두 붙었는지 확인할 수 있습니다. 응답에 [MOCK]이 붙어 실제 AI와 구분됩니다.
실행 지원 3종 (STEP 4 · 5)
1. 신청일 알림 (.ics) — 웹은 푸시가 어려우므로 사용자 캘린더에 일정을 넣어 기기가 대신 알리게 합니다.
확정 정책의 접수 시작·마감일, 자격 재검증 시점, 서류 준비 시점(D-30), 목표 D-Day를 한 파일로 묶어 내려받습니다.
각 일정에 VALARM 미리 알림(3~14일 전)이 들어가고, RFC 5545 규격(CRLF·75옥텟 줄접기)을 지켜 구글·애플·아웃룩에서 모두 열립니다.
내려받으면 준비도의 '정책 신청일 알림 설정' 항목이 자동 완료됩니다.
2. 제출서류 체크리스트 — 확정 정책별 필요 서류를 체크리스트로 관리합니다 (버팀목 7건, 보금자리론 6건 등 16종).
전부 체크하면 준비도의 '필요서류 체크' 항목이 자동 완료되어 실행 준비도가 함께 올라갑니다.
서류 목록은 일반적으로 요구되는 항목이라 "실제 제출 목록은 기관 공고로 확인" 안내가 항상 붙습니다.
3. FinTox 넛지 저축 (설계서 10p "3,400원 10% 셀프저축") — 소비를 막는 대신 쓴 금액의 일부를 즉시 목표 저축으로 옮기게 합니다.
위험도에 따라 비율이 달라지고(양호 5% / 관찰 10% / 주의 15%), 한 번에 5만 원을 넘지 않도록 상한을 둡니다.
누적 넛지 저축은 목표 도달일을 며칠 앞당기는지로 환산해 보여줍니다 — 소비 억제가 아니라 목표 속도로 연결하는 것이 핵심입니다.
신용 빌드업 (초안 5p "신용 빌드업 탭")
#credit 탭. STEP과 무관하게 상시 이용합니다.
1. 비금융 신용 가점 Agent — 등록된 결제내역에서 통신비·보험료·공과금·4대보험 자동납부를 찾아, KCB/NICE 비금융정보 반영 신청에 쓸 정형 스크립트를 만듭니다. 더미 데이터에서 실제로 LGU+ 통신요금(35,470원)과 삼성화재 보험료(7,690원)가 잡힙니다.
2. 청년 알뜰폰 매칭 — 현재 통신비와 데이터 구간별 알뜰폰 가격대를 비교합니다. 35,470원 → 표준 구간 기준 연 209,640원 절감, 이는 월 저축목표의 3%입니다.
3. XP / 등급 — 설계서 11p Financial Execution Quest 항목 그대로 퀘스트당 +20XP, 총 180XP. 씨앗 → 새싹 → 성장 → 실행 4단계.
⚠️ 안전장치: 신용점수가 몇 점 오른다고 단정하지 않습니다(평가사 기준 상이). 특정 통신사 요금제를 확정 가격으로 제시하지 않고 구간 범위로만 보여줍니다. 등급은 "실행 준비도"이며 신용점수·승인확률과 무관하다고 화면에 명시합니다.
남은 작업
