🗺️ Project Knowledge Index

Bundle OKF 0.1 · 25 conceitos · jinhoOps/IndividualSavingsFlowUI

Open source Repository Open in the app JSON README (API)

About

# 🗺️ Project Knowledge Index

IndividualSavingsFlowUI (ISF) 프로젝트의 모든 지식은 이 지도를 통해 연결됩니다. v1.1 현대화 이후의 구조를 반영합니다.

## 🏛️ 핵심 참조 (The Constitution)
*현대적 개발 인프라와 운영의 근간이 되는 문서들입니다.*
- [Operating_Principles](./core/operating_principles.md): 프로젝트 운영 원칙 및 현대적 DX 지침.
- [Architecture_Reference](./core/architecture_reference.md): Vite, TS, Tailwind v4 기반 아키텍처 명세.
- [Data_Model_Reference](./core/data_model_reference.md): v2 스토리지 스키마, Branded Types, 데이터 무결성 규칙.
- [Financial_Taxation_Reference](./core/financial_taxation_reference.md): 금융소득종합과세 정책 및 UI 경고 기준 (Safety Margin).
- [Version_Management_Principles](./core/version_management_principles.md): 자동화된 버전 관리 및 배포(Actions) 프로토콜.
- [UI_Standards_Reference](./core/ui_standards_reference.md): 디자인 시스템(Glassmorphism), 피드백 및 시각화 표준.
- [Knowledge_Harness](./core/knowledge_harness.md): 지식 하네스(LLM Wiki) 및 Codegraph 연계 운영 체계.

## 🚀 진행 중인 개발 (Active Development)
- [Phase 2 Context](file:///D:/jhkSandBox/CODE/IndividualSavingsFlowUI/.planning/phases/02-core

Details

Kind

OKF bundles

Topic

AI, RAG & memory

Publisher

jinhoops

Origin

okf_github

Category

dados

Version

0.1

Forks

1

Last push

2026-09-10T03:49:55Z

Repository state

ativo

Language

TypeScript

License

MIT

Added

2026-09-09 12:03:57

Updated

2026-09-09 12:03:57

Origin id

jinhoOps/IndividualSavingsFlowUI:.gemini/knowledge/wiki/index.md

README

# IndividualSavings Flow UIUX

개인 재무 흐름을 입력하고 장기 투자 전략과 실행 계획으로 연결하는 정적 웹 앱입니다. 2026-09-08 최신 main 기능과 Supabase workspace v4를 통합하고 원격 main push·Pages 배포를 완료했습니다. 2026-09-10 지출 도우미·workspace v5도 운영 DB에 적용하고 Pages 배포와 실제 계정 저장을 검증했습니다. 공개 사이트의 실제 임시 이메일 로그인·계정 저장·두 브라우저 동기화를 검증했습니다. Google provider 설정은 아직 미완료입니다. [최신 배포 기록](docs/superpowers/evidence/2026-09-10-expense-assistant-production-rollout.md)과 [계정 저장 운영 안내](docs/supabase-account-setup.md)를 따릅니다.

현재 지원 제품은 Main, Simulation, Portfolio와 Account Map입니다. 네 앱은 shared workspace를 사용합니다.

- **Main**: 월 실수령액, 지출, 저축, 투자와 남는 돈을 한눈에 보여주고 whole-workspace 백업을 관리하는 현재 제품 기준선입니다.
- **Simulation**: Main의 월 저축·투자를 기준으로 장기 복리 성장과 전부 저축 기준선을 비교합니다.
- **Portfolio**: 최신 Main 투자금을 첫 설정 흐름에서 전체 기준으로 배분하고, 이후 안정 비중 중심 결과와 집중 편집 화면을 제공합니다.
- **Account Map**: Main의 다섯 월 금액을 읽어 목적 배정과 계좌 간 월 계획 흐름을 만들고 노드 지도로 관리합니다.

배포 페이지: https://jinhoops.github.io/IndividualSavingsFlowUI/

## 제품 컨셉

ISF는 단순히 수입과 지출을 기록하는 도구가 아닙니다. 지금 들어오는 돈이 생활비, 저축과 투자로 어떻게 나뉘는지 이해하고, 현재 선택을 장기 계획과 실제 실행으로 연결해 가기 위한 개인 재무 플래닝 도구입니다.

현재는 월간 현금흐름을 정리하는 Main, N년 후 기대 자산을 비교하는 Simulation, 최신 Main 투자금을 전체 기준으로 배분하는 Portfolio, 계획을 실제 금융 위치에 연결하는 Account Map을 제공합니다. 네 앱은 하나의 versioned workspace를 사용합니다.

여기서 보여주는 미래 값은 확정된 예측이나 수익 보장이 아닙니다. 사용자가 입력한 현재 상황과 가정을 바탕으로 여러 선택지를 비교하고 더 나은 질문을 만들기 위한 계획용 시나리오입니다.

## 프로젝트 목표

ISF의 네 앱은 다음 질문에 답합니다.

- 내 월 수입은 어디로 흘러가는가?
- 생활비, 저축과 투자 비중은 현재 계획에 맞는가?
- **Simulation**: 정한 월 저축·투자가 장기 복리로 얼마나 커지는가?
- **Portfolio**: 선택한 전략을 어떤 투자 대상으로 배분할 것인가?
- **Account Map**: 금융 위치와 계좌 간 월 계획 흐름을 어떻게 관리할 것인가?

사용자가 입력한 데이터를 브라우저 안에서 계산하고 시각화하며, 로그인한 Supabase 계정의 workspace를 저장합니다. Google과 임시 이메일·비밀번호 로그인은 같은 사용자 ID와 저장 계약을 사용합니다. 별도 앱 서버나 은행 연동은 없습니다.

## 현재 제품

### Main

Main은 월 실수령액, 지출, 저축, 투자와 남는 돈을 한눈에 보여줍니다.

처음에는 월 실수령액, 주거 고정비, 평균 생활비, 저축, 투자를 빠르게 입력합니다. 각 단계에서 현재 계획과 남는 돈을 바로 확인하고, 마지막 확인 화면에서 지출, 저축, 투자, 남는 돈의 비율을 살펴본 뒤 계획을 적용합니다. 적용 후에는 대시보드에서 같은 수치를 확인하고 수정할 수 있습니다.

Main에서 다루는 주요 내용:

- 월간 현금흐름 요약
- 2분 빠른 설정과 중간 이탈 후 재개
- 지출, 저축, 투자, 남는 돈의 금액과 비율
- 월 실수령액과 월간 계획 수치 편집
- 지출 금액을 눌러 고정비·변동비 13개 항목을 계산하고, 기억한 답변의 합계로 주거비·생활비 대체
- 남는 돈 금액을 눌러 저축·투자에 전부 또는 일부를 나누고, 반영 전후와 남겨둘 돈 확인
- 모든 현재 앱 slice와 공유 위치를 한 번에 다루는 whole-workspace JSON 백업

### Simulation

Main에 적용된 계획이 있으면 `Simulation으로 이어가기`가 URL로만 이동합니다. 최초에는 시작 자산, 시작 자산이 2억 원 이상일 때의 조건부 목표 금액, 예상 연 수익률을 한 가지씩 설정하고, 이후에는 결과로 바로 진입합니다. Simulation은 진입할 때마다 계정 workspace의 최신 Main slice를 읽되 Main 원본은 변경하지 않습니다.

기간은 현재를 뜻하는 0년부터 30년까지 조정합니다. 결과는 한국식 정수 금액, 전체 폭 성장 그래프와 전부 저축 비교를 제공하며 pointer·touch·keyboard로 연도별 상세를 확인할 수 있습니다.

런처는 Main, Simulation, Portfolio와 Account Map을 한 줄 아이콘으로 표시합니다. 현재 앱은 선택선으로 구분합니다. 아이콘의 한글·영문 명칭은 hover, keyboard focus, 모바일 길게 누르기 또는 `?` 도움말로 확인할 수 있습니다.

## Portfolio와 Account Map

### Portfolio

최신 Main 투자금을 workspace에서 읽어 최대 10개 자유 이름 투자 대상과 현금에 배분합니다. 최초에는 시작·배분·검토의 안내 흐름을 거치고 이후에는 결과로 바로 진입합니다. 각 대상은 성장·안정 분류와 자동 추천·사용자 지정 출처를 소유합니다. 결과에서는 원화 금액을 기본으로 숨긴 채 안정 비중과 가장 큰 배분 대상을 요약한 뒤 이름·비율·비례 막대 목록을 보여줍니다. 관리 메뉴에서 전체 금액 표시와 비율순·입력순 정렬을 바꿀 수 있습니다. `배분 수정`은 모바일·태블릿에서 하단 sheet, 데스크톱에서 우측 panel로 열립니다. 현재 UI는 `전체 기준` 적용 계획과 초안만 편집하며 Main을 수정하지 않습니다.

선택한 투자 방향을 종목·자산별 적립 금액과 비중으로 구체화합니다.

### Account Map

Account Map은 Main의 다섯 월 금액을 읽기 전용 기준으로 사용합니다. 최초 설정에서 수입·주거·생활비·저축·투자를 계좌·보관처에 배정하고, 계좌 간 고정 이체와 `남은 금액 전부` 규칙을 확인합니다. 완료 지도는 전체 월 계획 흐름을 기본으로 보이고, 계좌를 한 번 선택하면 상·하류·목적과 명시적 흐름 편집 action을 보여줍니다. 이는 실제 잔액·거래 또는 실행 이체가 아닙니다. Main 금액 수정은 지도를 유지한 Main 소유 overlay에서만 저장하며, 저장 뒤에는 사용자가 `현재 Main 기준으로 확인`을 명시해야 stale notice가 해제됩니다. Account Map command는 `workspace.locations`와 `workspace.accountMap`만 갱신하고 Main·Simulation·Portfolio에는 write-back하지 않습니다. 상세 계약은 [Account Map Planned Account Flow Design](docs/superpowers/specs/2026-09-04-account-map-planned-account-flow-design.md)에 정의되어 있습니다.

## 공유 인프라

현재 네 앱은 다음 기반을 공유합니다.

- 네 목적지 앱 런처와 현재 위치 표시
- 계정당 하나의 Supabase JSONB workspace(schema v5)와 앱별 typed slice adapter
- RLS 계정 격리, 서버 revision 검사와 mutation receipt를 사용한 동시 저장·중복 재시도 보호
- Main·Simulation·Portfolio·공유 금융 위치와 Account Map 상태를 포함하는 whole-workspace 백업
- 모든 slice와 참조를 먼저 검증한 뒤 한 번에 교체하는 atomic restore
- URL 기반 앱 탐색과 workspace Main slice를 읽는 앱별 read-only adapter
- Vite PWA가 소유하는 PWA 매니페스트와 배포 서비스워커
- 공통 디자인 토큰과 버튼·패널 스타일

금융 데이터 원본은 로그인한 계정의 서버 workspace입니다. 브라우저에는 계정별 마지막 snapshot과 미전송 입력을 복구용으로 보관합니다. 오프라인 재방문은 읽기 전용이며, 열린 화면은 focus·online 복귀 또는 visible 상태의 30초 조회로 최신화합니다. 다른 기기가 먼저 저장했으면 입력을 유지하고 명시적으로 재적용합니다. Portfolio의 금액 표시·정렬 같은 보기 설정은 금융 workspace와 별개의 브라우저 설정입니다.

현재 코드는 [지출 도우미 설계](docs/superpowers/specs/2026-09-10-main-expense-assistant-design.md)의 workspace v5를 사용합니다. 기존 [v4 통합](docs/superpowers/specs/2026-09-08-supabase-workspace-v4-integration-design.md) 위에 Main 항목별 답변을 추가하고 모든 RPC에 protocol 5를 요구합니다. 계정 캐시는 `isf-account-workspace-v3`이며 구 v2/v1 캐시의 미전송 요청은 자동 재전송하지 않고 복구 원문으로 보관합니다.

브라우저 현재 키는 `isf-workspace-v5`이며 명시적 가져오기 후보입니다. 없을 때만 v4 → v3 → 유효한 retired v1/v2 원본 `isf-workspace-v1` 순으로 읽기 전용 변환합니다. invalid 최신 원본에서는 과거 버전으로 fallback하지 않고 원본·foreign record를 변경하거나 삭제하지 않습니다. 정상 export는 서버 확정 데이터의 backup format 4/workspace v5이며 format 3/2/1은 역사적 parser와 converter를 거칩니다. 미전송 입력은 별도의 복구 파일로 제공합니다.

## 제품 원칙

- **요약 먼저**: 기본 화면은 입력 폼보다 현재 상태와 다음 행동을 먼저 보여줍니다.
- **작고 명확한 입력 계약**: Main은 다섯 월간 금액과 지출 계산용 보조 답변을 소유합니다.
- **명시적 저장**: 큰 편집은 적용 전까지 draft로 유지합니다.
- **계정별 원본**: 서버 저장 확정 후 성공을 표시하고, 로컬 원본과 미전송 입력은 구분해 보존합니다.
- **한국어 금액 UX**: 사용자는 만 원·억 원 단위로 읽고 내부 계산과 저장은 원 단위를 유지합니다.
- **시각화 중심**: 현재 Main의 월 자금 구성과 향후 앱별 시각화는 숫자의 관계를 설명해야 합니다.
- **명시적 연결**: 앱 이동은 URL만 사용하고 Simulation·Portfolio·Account Map이 같은 workspace의 최신 Main slice를 읽습니다. Account Map의 Main 수정 요청은 Main 소유 overlay가 처리합니다.
- **책임 분리**: 각 앱은 자신의 draft/applied 상태만 쓰고 다른 제품 slice에는 암묵적으로 write-back하지 않습니다.

## Legacy Migration Status

아직 이관하지 않은 기능이나 데이터 호환성 지식이 남아 있는 레거시 코드는 임시로 보존합니다.

레거시는 지원되는 사용자 경로나 신규 기능의 기반이 아닙니다. 각 기능을 목록화하고 현재 제품에 필요한지 판정한 뒤, 필요한 기능은 현재 책임 경계로 이관하고 불필요한 기능은 폐기 근거를 기록합니다. 사용자 동작과 구버전 저장 데이터의 호환성을 검증하고 모든 runtime·route·selector·storage·test 참조를 제거한 후 레거시 구현을 삭제합니다.

Phase 4에서 구 Main runtime, storage bridge, shared browser layer와 구 서비스워커를 삭제했습니다. `shared/brand/mainBrandGeometry.js`만 이전 shared browser tree에서 남은 파일이며 현재 Main brand icon이 사용합니다. 구 저장 키 문자열은 read-only migration/rollback 경계, 음성 참조 검사와 fixture에만 남습니다. Task 8의 최종 전체 검증은 통과했고, 정확한 명령·참조 감사·반응형 QA 결과는 [Phase 4 disposition](docs/superpowers/evidence/2026-09-02-phase4-legacy-test-disposition.md)에 기록되어 있습니다.

후속 정리에서는 미사용 글로벌 CSS, 예전 시세 생성·문서 변환 스크립트와 검사 출력물을 제거했습니다. 삭제 근거와 현재 저장 호환성 보존 범위는 [잔여 자산 정리 기록](docs/superpowers/plans/2026-09-08-entry-focus-and-legacy-residue.md)에 정리합니다.

## 실행하기

필요 조건:

- Node.js 22 이상 권장
- npm

설치:

```bash
npm install
```

개발 서버:

`.env.example`을 참고해 `.env.local`에 Supabase URL과 공개 publishable key를 설정합니다. DB 비밀번호·service-role/secret key는 넣지 않습니다. 임시 이메일·비밀번호 로그인은 관리자가 사전 준비한 계정으로 사용하며, 회원가입이나 계정 자동 생성은 제공하지 않습니다. 임시 계정 준비와 Google provider·callback 등록은 [운영 안내](docs/supabase-account-setup.md)를 따릅니다. 로그인 비밀번호는 화면에서 입력하고 소스·환경변수·정적 빌드에 넣지 않습니다. 연결 설정이 없으면 제품 대신 설정 오류를 표시하며 production build도 실패합니다.

```bash
npm run dev
```

타입 체크:

```bash
npm run check
```

전체 E2E 테스트:

```bash
npm run test:e2e -- --reporter=list
```

빌드:

```bash
npm run build
```

## 개발 구조

이 저장소는 Vite 기반 정적 멀티페이지 앱입니다. 현재 Main, Simulation, Portfolio와 Account Map은 React·TypeScript·Tailwind CSS로 구성됩니다.

큰 책임 경계:

- **입력과 정규화**: 사용자 입력과 current workspace/backup payload의 exact validation
- **draft와 상태**: 편집 중 상태, dirty 판정, 적용과 취소
- **현재 계산**: Main 월간 현금흐름, 잔액과 적자
- **현재 시각화**: Main 요약 카드와 월 자금 구성
- **저장과 공유**: 단일 revisioned workspace, 앱 slice adapter, 공유 금융 위치와 whole-workspace JSON
- **앱 연결**: URL로 이동하는 Main → Simulation → Portfolio → Account Map 상세 화면
- **공통 UI**: 앱 런처, Main 데이터 허브, 피드백, 테마와 PWA

## 검증 기준

최소 정적 검증:

```bash
npm run check
```

사용자 흐름을 변경했다면 관련 Playwright 테스트를 실행합니다.

```bash
npm run test:e2e -- --reporter=list
```

Main의 빠른 설정이나 대시보드를 수정했다면 focused 회귀를 먼저 확인할 수 있습니다.

```bash
npx playwright test tests/main-react.spec.ts
```

Account Map 사용자 흐름, Main overlay와 v3/v2 호환성 회귀는 다음 명령으로 실행합니다.

```bash
npx playwright test tests/account-map.spec.ts --reporter=list
```

계정 흐름은 `npx playwright test --project=cloud`, 기존 로컬 데이터 호환성과 제품 회귀는 테스트 전용 entry의 `--project=chromium`으로 검증합니다. 인증 우회는 production entry에 없습니다. DB 권한·트랜잭션 검증은 Docker 실행 후 `node scripts/test-workspace-db.mjs`로 수행하며 운영 DB에는 접속하지 않습니다.

Node 25 이상에서 실험적 Web Storage가 jsdom과 충돌하면 단위 테스트에 `NODE_OPTIONS=--no-experimental-webstorage`를 지정합니다.

## 현재 로드맵

Phase A shared workspace foundation과 Main, Simulation, aggregate-first Portfolio, planned account-flow Account Map은 현재 기준선입니다. 다음 단계는 이 기준선을 보존하며 별도 계획으로 진행합니다.

- **계정 저장 구현**: 정적 배포를 유지하는 [Google 로그인·Supabase 계정별 workspace 저장](docs/superpowers/specs/2026-09-07-supabase-account-workspace-design.md)과 2026-09-08 승인된 임시 이메일·비밀번호 로그인. 실제 임시 계정 준비·운영 DB migration·Google 실제 왕복·Pages 배포는 [운영 안내](docs/supabase-account-setup.md)의 별도 rollout 항목입니다.
- **Phase B 완료**: 계좌 우선 설정, 계좌·보관처 registry, 노드 지도와 가역적 관리가 있는 Account Map
- **Phase C**: 현재 Main metric 영역을 대체하는 Main·Simulation·Portfolio·Account Map 연결 결과 카드
- **Phase 4 완료**: 분류된 legacy runtime·compatibility path·test 삭제, v1/v2 migration evidence와 [repository-wide 최종 검증](docs/superpowers/evidence/2026-09-02-phase4-legacy-test-disposition.md)을 기록함
- **별도 후속**: 금융 workspace·backup과 분리된 hidden trophy room
- 한국어 은행·카드 알림 텍스트 기반 지출 capture
- 두 사람의 Main 데이터를 이용한 가구 병합 미리보기
- 과거 snapshot 대비 현재 지출 비교
- 가구 소득·부채·DSR·LTV 기반 부동산 구매력 계획
- 필요한 레거시 기능의 현재 모듈 이관과 검증 후 제거

## 제품 문서

- [Product PRD](docs/ways-of-work/plan/isf-rebuild/connected-financial-planning-workspace/prd.md)
- [Agent Guide](AGENTS.md)
- [Design Contract](DESIGN.md)
- [Product Direction and Documentation Spec](docs/superpowers/specs/2026-07-29-product-direction-and-documentation-design.md)
- [Journey Snapshot Retirement Spec](docs/superpowers/specs/2026-08-03-journey-snapshot-retirement-design.md)
- [Connected Account Map Workspace Design](docs/superpowers/specs/2026-08-06-connected-account-map-workspace-design.md)
- [Account Map Planned Account Flow Design](docs/superpowers/specs/2026-09-04-account-map-planned-account-flow-design.md)
- [Shared Workspace Foundation Plan](docs/superpowers/plans/2026-08-06-shared-workspace-foundation.md)
- [Account Flow Decision History](docs/adr/0002-account-flow-belongs-to-portfolio-boundary.md)

## 데이터와 주의사항

ISF는 금융기관 연동, 실시간 시세 연동, 법적 금융 자문을 제공하지 않습니다. 모든 결과는 사용자가 입력한 가정에 기반한 계획용 추정입니다.

대출, 세금, 투자와 부동산 의사결정에는 실제 금융기관 조건과 전문가 검토가 필요합니다.

## 라이선스

ISC

More

• More okf bundles on AI, RAG & memory
• Everything published by jinhoops
• Browse the whole catalog