가족 자산 관리

Claude Design에서 제작한 시안의 레이아웃과 테마를 그대로 구현하고, 기존 asset_dashboard_claude-code 앱의 실데이터(KV 자산, 시세·배당 API, 인증)를 연결한 버전입니다.

페이지 구성

사이드바는 일곱 개 메뉴이며, 메뉴 안의 세부 화면은 제목 줄 오른쪽 링크로 전환합니다.

1. 홈

가족 투자자산 합계 + 일일손익·평가손익·연 배당·리스크 배지, 자산 배분 도넛(클릭 시 소속 종목 펼침), 섹터 집중도 바, 평가손익 기여도, 수익률·손실률 TOP 5, 그리고 검색 가능한 보유 종목 표 + 선택 종목 요약(배당 정보 포함).

2. 자산 관리

• 보유 목록 — 투자자산 CRUD + 적립식 매수 규칙 등록 (모든 화면의 원본)
• ETF 탐색 — 보유 ETF의 구성종목, 기준일·완전성 점검, 소유주별 직접/간접 노출 분해, 날짜별 구성 변화
• 구성원 비교 — 구성원 카드 클릭 필터 + 보유 자산 표 + 소유주별 자산군 구성
• 비중 분석 — Plotly 선버스트로 비중 드릴다운

3. 투자 분석

• 성과 — 소유주별 포트폴리오 vs S&P 500 · KOSPI 정규화 차트와 기간별 초과수익·MDD 표. 현재 보유 비중을 기간 시작일부터 소급 적용한 백캐스트이며 화면에 그렇게 표기됩니다. 같은 화면 아래의 투자자산 추이 카드는 소급 가정 없이 매일 기록된 실제 평가액을 그립니다(부동산·부채 제외, 수익률 아님)
• 리스크 — 점수 링 + 규칙 카드 8종(집중도·가상화폐·섹터·변동성·현금·환노출·분산·레버리지) + 보조 진단 8종(ETF 중복 노출률, ETF 간 중복도, 실효 종목 수, 환율 충격, 국가·섹터 집중도, 배당원 의존도, 손실 회복 필요 수익률) + 종목 집중도 ETF 룩스루

4. 배당

세전/세후 전환, 연간·월평균·YoC·배당성장률·집중도 카드, 입력된 일반계좌 배당 기준 금융소득 부분 근접도, 월별 배당 캘린더, 종목별 배당 표(배당세 칼럼), 향후 90일 예상 일정.

5. 투자 계획

• 목표 — 재무 목표 진행률(자산군·순자산 연동), 남은 기간 기준 월 적립 필요액(수익률 0% 가정). 현금 안전판 목표 개월수도 여기서 바꿉니다
• 리밸런싱 — 목표 비중 대비 편차 → 필요 조정액 → 월 적립식 보정안, 계좌 배치 진단(실제 배당 세율 기준 절세 여력)
• 적립식 매수 — 규칙 상태, 다음 매수일·예상 처리 시점(시장 휴일·증권사별 주문 시각 반영), 월 환산 배분
• 투자 시뮬레이터 — 두 개 탭. 과거 성과 백테스트(단일 종목, 수정주가 기준 적립식 시뮬레이션)와 추가 투자 배분(새로 넣을 돈을 목표 비중에 맞춰 나누는 메모리 전용 시나리오)

6. 현금 흐름

월별 수입·지출 가계부(일회성·자동이체), 수입/지출 구성과 순현금흐름 추이 차트, 고정비 관리. 여기서 고정비로 분류한 항목이 현금 안전판의 기준이 됩니다.

7. 세금·증여

• 실현손익·세금 — 월별 실현손익 기록·차트, 해외주식 250만원 기본공제 → 지방세 포함 22%, 계좌별(일반·연금저축·ISA) 구분, 연말 절세 여력과 손실 상계 후보
• 가족 증여 — 자녀 정기증여(법정 할인율을 월납으로 근사한 유기정기금 PV)와 부부 증여 계획, 최근 10년 실제 내역 대비 공제 잔여 검토

데이터 상태는 사이드바 푸터의 상태 줄에서 엽니다 — 항목별 출처·최근 확인 시각·상태를 한곳에서 보여주고, 카드마다 해당 소스만 다시 조회할 수 있습니다. 상태는 정상 / 확인 필요 / 확인 전 세 가지이며, 아직 조회하지 않은 것은 오류가 아니므로 푸터 점은 실패가 있을 때만 붉어집니다. 최근 확인 시각은 기기 간에 공유되므로 다른 접속에서 확인한 기록에는 표시가 붙습니다.

디자인 시스템

• 3테마: 라이트(기본) / 다크 / 네이비 — 사이드바 세그먼트로 전환, 선택 저장
• 표시 통화: 자산 합계·손익은 KRW, 종목 평단가·현재가는 원래 거래 통화로 표시
• 3D 자산 배분: PC에서는 선택한 조각이 올라오는 입체 도넛, 모바일·WebGL 미지원 환경에서는 SVG 도넛. 두 차트 모두 같은 비중과 범례를 사용하며, 동작 줄이기 설정을 존중합니다.
• 모바일 보유 목록: 긴 종목명·평가금액·수익률을 함께 표시하고, 항목을 누르면 수량·단가·평가손익을 펼칩니다.
• 타이포그래피: Manrope(디스플레이) · IBM Plex Mono(숫자) · Noto Sans KR(본문)
• 우하단 시세 위젯: JPY100/KRW · 금 1g(KRW), 전일 종가 기준
• 용어 툴팁: YoC·과세표준·유기정기금 등 점선 밑줄 용어에 마우스오버 설명

실행

Vercel 호스팅 SPA입니다 — 빌드 단계 없음.

npm install                      # 서버리스 함수(Node) + 테스트 의존성
pip install -r requirements.txt  # api/dashboard.py 의존성 (yfinance, pykrx, pandas)
vercel dev                       # http://localhost:3000
npm test                         # 문법·타입·회귀 테스트 (CI와 동일)
npm run check:tax-rules          # 규칙 구조·출처 계약·사람 검토기한 확인
npm run check:tax-rules:remote   # 공식 법령·국세청 페이지까지 실제 확인

세금·증여 규칙 최신성

tax-rules.js가 계산값, 적용 연도, 버전, 공식 출처, 계산 가정과 제외 항목의 단일 기준입니다. 배당 관리·양도소득세·가족 증여 화면에서 접이식 근거 패널을 열어 현재 적용값과 사람 검토일을 확인할 수 있습니다. 실현손익 기록에는 당시의 ruleSetId도 함께 저장합니다.

.github/workflows/tax-rule-watch.yml이 매일 공식 법령·국세청 출처의 핵심 문구와 검토기한을 확인합니다. 변경 의심·접속 실패·검토기한 초과가 생기면 하나의 GitHub Issue를 열거나 갱신하고 워크플로를 실패시킵니다. 정상으로 돌아오면 이슈를 닫습니다. 법률 숫자는 자동으로 바꾸지 않습니다. 공식 본문을 사람이 대조한 뒤 값·가정·제외 항목·검토일을 같은 변경으로 갱신해야 합니다.

“최신”은 공식 출처 일일 감시와 최대 31일 사람 재검토를 뜻합니다. 화면은 검토기한이 지나면 공식 근거 재검토 필요로 바뀌며, 계산은 신고나 세무 자문을 대신하지 않습니다. 변경 이력과 갱신 절차는 docs/tax-rule-changelog.md에 기록합니다.

Vercel 환경변수

변수	용도
KV_REST_API_URL	Upstash Redis(KV) REST URL — 자산/가계부 등 영구 저장
KV_REST_API_TOKEN	Upstash REST 토큰
DASHBOARD_PASSWORD	로그인 비밀번호
SESSION_SECRET	HttpOnly 로그인 세션 서명 키 — 충분히 긴 무작위 값 사용
INTERNAL_API_TOKEN	Node 서버리스 함수가 Python 내부 API를 호출할 때만 쓰는 별도 무작위 토큰
INTERNAL_API_ORIGIN	(선택) 내부 API 호출용 고정 HTTPS origin. 미설정 시 Vercel 배포 URL 사용

기존 배포와 같은 Upstash 인스턴스를 연결하면 기존 자산 데이터가 그대로 표시됩니다. 과거 AUTH_TOKEN bearer는 더 이상 허용하지 않습니다. 무중단 업그레이드를 위해 SESSION_SECRET이 없는 기존 배포에서는 AUTH_TOKEN을 서버 내부 세션 서명 키로만 임시 사용합니다. 로그인 복구 후 SESSION_SECRET과 INTERNAL_API_TOKEN을 서로 다른 값으로 발급하고 AUTH_TOKEN을 제거해 주세요.

구조

• index.html — 모든 뷰가 <div id="view-*">로 선언된 단일 페이지
• tax-rules.js — 대한민국 세금·증여 규칙 버전, 공식 출처, 계산 가정·제외 항목
• script.js — 데이터 엔진 + 기존 기능 뷰 (~7,600줄, 모듈 시스템 없음)
• finance.js — 목표·리밸런싱·투자자산 추이·데이터 상태. script.js의 저장 엔진과 cobalt.js의 표시 헬퍼를 재사용
• navigation.js — 일곱 개 메뉴(APP_NAV)와 세부 링크, 옛 링크 해석, 메뉴 간 소유주 범위 유지
• backtest.js / simulator.js / etf-explorer.js — 백테스트·추가 투자 배분·ETF 탐색. 모두 Cobalt 가 렌더할 때까지 함수만 정의합니다
• workspace-ui.css / etf-explorer.css — style.css 뒤에 로드되어 통합 워크스페이스와 ETF 탐색 레이아웃을 덮어씁니다
• cobalt.js — 메인 페이지 렌더러 + 라우터. switchView/changeOwner/saveAssetsToKV/fetchDivData 등을 감싸 재렌더와 데이터 신선도 기록을 통합
• allocation-3d.js — 자산 배분 차트의 선택적 WebGL 렌더러. vendor/의 Three.js 0.180.0 모듈과 MIT 라이선스를 함께 배포하며, 화면에 필요할 때만 불러옵니다.
• style.css — 디자인 토큰(:root=라이트, [data-theme="dark"], [data-theme="navy"]) + 시안 토큰 별칭(--tx, --panel, --accSoft 등)
• api/ — Vercel 서버리스 함수 (가격/배당/환율/검색/KV 프록시/인증)
• .github/workflows/ — 자동 배치. 품질 검사(push·PR), ETF 구성종목 수집(미국 장 마감 뒤 평일 KST 07:30, 리포에 커밋), 순자산 스냅샷 기록(매일 KST 16:40, KV에 직접 기록), 세금·증여 공식 근거 점검(매일, 알림만)
• docs/invariants.md — 건드리면 안 되는 것. 실제로 사고가 났던 자리와 그 증상, npm test 로는 확인되지 않는 영역(워크플로·모바일 레이아웃·CDN 실패·터치)을 정리했습니다. 수정 작업을 맡기기 전에 이 문서를 먼저 읽게 하세요
• scripts/tests/ — 회귀 테스트. npm test 가 전체 게이트(문법 검사 → tsc --noEmit → Node 테스트 → Python 테스트)를 돌리고, GitHub Actions(품질 검사)가 push·PR 마다 같은 명령을 실행합니다. 개별 실행은 node scripts/tests/<file>.mjs

스크립트 로드 순서는 tax-rules.js → script.js → finance.js → navigation.js → backtest.js → simulator.js → etf-explorer.js → cobalt.js 로 고정입니다. cobalt.js가 CB_VIEWS에서 다른 파일의 렌더 함수를 참조하고 전역 함수들을 감싸기 때문에 데이터·페이지 스크립트 중 마지막에 와야 합니다. 선택적 allocation-3d.js는 그 뒤에 로드합니다. 스타일시트는 style.css → workspace-ui.css → etf-explorer.css 순입니다.

자세한 개발 규칙은 CLAUDE.md(기계가 읽는 판본)와 docs/invariants.md(사람이 읽는 판본)를 참고하세요.