Orbit 제품군

서버 없이 같은 브라우저에서 연결되는 예산 앱과 목표형 위시리스트.

앱

설치되는 앱은 하나이고 그 안에 화면 묶음이 둘이다.

• Orbit Budget (/) — 항목별 예산, 거래, 남은 자유비용
• Orbit Wish (/wish/) — 자유비용을 모아 위시를 이루는 목표 관리. 오르빗 허브·퀘스트 로그·우주 도감·관측소 4화면. 관측소 하위 화면은 레벨 보상·꾸미기·상점(상자 포함)·설정

기능

• 첫 실행 안내 — 이번 달 수입 → 카테고리별 월 예산 → 예비비 순서의 3단계 초기 설정, 남은 자유비용 미리보기, 설정에서 다시 보기
• 홈 — 월 전체 남은 자유비용, 오늘 총지출, 카테고리별 오늘·이번 주 잔액과 횟수 한도, 퀵 슬롯 구슬, 기간이 있는 위시의 오늘 저금 줄·금액 조정·못 모아요 기록, 이번 달 저금·저금통 누적, 전체 카테고리 카드, 오늘 내역
• 달력 — 날짜별 지출·수입·예정 거래, 날짜 선택 시 상세, 맨 아래 그 달 소비 요약(총지출·지난달 대비·최다 지출 카테고리)
• 소비 분석 — 달력 요약 카드에서 진입, 월 이동(이번 달까지). 총지출·수입·위시 저금·무지출일, 카테고리별 지출 비중·예산 대비·지난달 대비, 횟수·교통 카테고리의 기간별 한도 준수율·자유비용 환급·초과액(끝난 기간만), 고정비·변동비 비율, 큰 지출 Top 5, 자주 쓴 메모 Top 5(2회 이상). 지출은 실제 지출만(예정 제외, 위시 구매·예비비 포함)
• 예비비 지출 — 지출 입력 시 예비비에서 사용 토글(카테고리 없음), 남은 예비비 표시, 예비비 0인 달은 잠김
• 거래 내역 — 전체·예정 탭(예정은 조회 기간 무시, 가까운 날짜순), 조회 기간(기본 최근 1주일 · 1주일/1개월/전체 · 날짜 직접 지정), 날짜별 그룹, 메모·카테고리 검색, 종류·카테고리 필터, 수정·삭제
• 설정 — 카테고리 관리, 반복 거래, 예비비, 자유비용에 예정 수입 포함(기본 켬), CSV 내보내기(거래만), 전체 백업·복원(예산·위시 JSON 한 파일, 복원 시 전부 교체), 라이트/다크 테마(선택 저장, 미선택 시 기기 설정)
• 예산 계산 도구 — 월 예산을 횟수(한 번에 얼마 × 주 몇 회), 교통(편도 × 왕복), 구독 합계로 산출. 요일 지정 시 그 달 실제 요일 수 반영, 금액은 한 번 단가의 배수로 반올림, 달·반복 거래 변경 시 자동 갱신
• 반복 거래 — 월 단위(매달 며칠, 월말 날짜 보정) 또는 주 단위(매주 무슨 요일, 여러 요일 가능)로 예정 거래 자동 생성. 주 단위는 고른 요일마다 한 건씩, 구독 합계 예산에는 그 달 횟수만큼 반영
• 위시 달성 — 구매·더 기다리기·정리 3분기, 등록 후 3일 구매 잠금, 구매 시 Orbit 지출 자동 기록(자유비용 이중 차감 제외), 정리 시 다른 위시 이전 또는 자유비용 회수
• 기간 없는 위시 저금통 — 아무 때나 넣기·꺼내기(꺼낸 돈은 자유비용 회수), 목표 금액까지만 넣기, XP·연속 기록 없음, 목표 도달 시 구매·정리, 남은 예산 넘기기 대상 포함
• 위시 관리 — 궤도 슬롯과 기간 없는 위시 목록 분리, 목록 위시의 궤도 전환, 이름·목표 금액·목표 기간 수정, 삭제 시 모은 금액 자유비용 회수, 상단 로고 메뉴에서 Orbit·Wish 전환
• PWA — 홈 화면 추가로 앱처럼 실행

계산식 (packages/budget-core/src/budget.ts)

남은 자유비용 = 총수입 + 지난달 이월 − 전체 카테고리 월 예산 − 예산 밖·초과 지출 − 예비비 − 예비비 초과분 − 이번 달 위시 순저금
남은 예비비   = 예비비 − 예비비에서 쓴 지출
지난달 이월   = 그 달 수입 + 그 달이 받은 이월 − 그 달 지출 − 그 달 위시 순저금

카테고리 예산 안에서 쓴 금액은 자유비용에서 다시 차감하지 않는다. 하루 몫의 미사용액은 다음 날, 주간 몫의 미사용액은 다음 주에 자유비용으로 돌려주고 초과분은 즉시 차감한다. 예정 거래도 같은 기준으로 즉시 반영한다. 주간 몫은 월 경계에서 자르고 합계가 월 예산을 넘지 않게 배분한다.

예비비에서 쓴 지출은 예비비 안에서는 자유비용에 영향 없음. 예비비를 넘긴 금액만 자유비용에서 차감.

달이 끝나면 안 쓴 돈 전부가 다음 달 자유비용으로 이월한다 — 자유비용 잔액 · 안 쓴 카테고리 예산 · 안 쓴 예비비. 초과 지출한 달은 마이너스로 이월한다. 이월액은 달이 바뀔 때 한 번 계산해 저장하며, 다음 달 이월은 지난달 한 달치만 읽어 만든다. 시작은 앱을 처음 연 달이고 그 이전 기록은 이월에 넣지 않는다. 지난달 거래를 뒤늦게 넣거나 고치면 반영되지만, 그보다 이전 달을 고치면 반영되지 않는다. 위시에 모아 둔 돈은 아직 묶인 돈이라 이월에서 제외한다. 화면에 이월 줄은 따로 없고 남은 자유비용 숫자에 들어간다.

총수입에는 예정 수입도 들어간다. 설정에서 끄면 실제로 들어온 수입만 센다 (예정 지출은 설정과 무관하게 늘 차감).

위시 구매 지출은 저금 단계에서 이미 자유비용이 줄었으므로 자유비용 계산에서 제외한다. 거래 내역과 선택한 카테고리 통계에는 그대로 남는다.

실행

npm install
npm run dev          # 두 앱을 같은 origin에서 실행
npm run dev:orbit    # Orbit만 실행
npm run dev:wish     # Wish만 실행
npm run build        # Orbit, Wish 타입 검사 + 빌드
npm run verify       # 계산 로직 검산

통합 개발 서버 경로: http://localhost:5173/apps/orbit/, http://localhost:5173/apps/wish/

프로덕션 결과물: dist/(Orbit, 도메인 루트) + dist/wish/(Wish)

빌드 순서 주의 — Wish가 먼저 dist/wish를 채우고, 그 다음 Orbit이 dist를 채우면서 wish/**까지 서비스 워커 프리캐시에 담는다. npm run build가 그 순서(clean → wish → orbit)다. 순서를 바꾸거나 하나만 돌리면 오프라인 캐시가 어긋난다.

배포

Vercel 프로젝트 하나. 설정은 vercel.json에 고정되어 있어 대시보드 값과 무관하다.

항목	값
Build Command	npm run build
Output Directory	dist
Root Directory	저장소 루트
예산	/
위시	/wish/

왜 PWA가 하나인가

iOS는 홈 화면 앱마다 저장소 컨테이너를 나눈다. 같은 도메인이어도 아이콘을 두 개 만들면 위시가 예산 데이터를 읽지 못한다(기기에서 확인함). 브라우저 탭에서는 공유되지만 홈 화면 앱끼리는 아니다.

그래서 manifest와 서비스 워커는 apps/orbit 하나뿐이고 위시 결과물까지 그 워커가 캐시한다. 홈 화면 아이콘 하나 안에서 두 화면을 오간다.

• manifest id: '/'를 바꾸지 말 것. 바꾸면 이미 설치된 앱이 다른 앱으로 인식되어 업데이트되지 않고 아이콘이 하나 더 생긴다
• apps/wish의 서비스 워커는 자폭 전용이다. 이전 배포에서 /wish/ 스코프에 설치된 워커를 해지시킨다. 기기가 한 번씩 열어 정리되면 그 플러그인은 빼도 된다
• 아이콘 두 개가 필요해지면 도메인을 나누고 서버를 둬야 한다. 그때 위시의 manifest를 되살리고 apps/wish/src/lib/budget.ts의 어댑터만 서버 조회로 바꾸면 된다

주의사항

• 데이터는 브라우저 IndexedDB에만 저장. 기기 간 동기화 없음 (PC와 폰 별개)
• 두 앱 연동은 동일한 프로토콜·도메인·포트에서만 가능. iOS 홈 화면 앱은 앱마다 저장소가 나뉠 수 있어 실제 기기 확인 필요
• Orbit의 배포 경로(/)·start_url·manifest id를 바꾸면 이미 설치된 홈 화면 앱이 다른 앱으로 인식된다
• 브라우저 데이터 삭제 시 함께 소실
• iOS 사파리는 7일 미방문 시 저장소 삭제. 홈 화면 추가하면 제외
• 백업은 설정 → 전체 백업(JSON). 주기적 백업 권장. CSV는 거래 내역만이라 복원 불가
• 복원은 지금 데이터를 전부 지우고 교체. 새 버전 앱에서 받은 백업은 옛 앱에서 복원 불가
• 금액 계산은 정수, 나눗셈은 내림 처리
• 예산 이력 저장 없음. 지난 달 분석에서 계산식 예산은 그 달 기준 재계산, 직접 입력 예산은 현재 값 기준

범위 밖

계좌 연동, 클라우드 동기화·로그인, 차트 라이브러리(분석 막대는 CSS만), 다중 통화