# 돈돼지 가계부 — 프론트엔드 (sb_pt)

Vue 3 + Vite 기반의 가계부·자산·게시판 앱 프론트엔드. 웹 / 안드로이드(Capacitor) / Windows 데스크톱(Electron) 3개 플랫폼을 하나의 코드베이스로 빌드합니다.

- 서비스명 **돈돼지 가계부** (구 Slim Budget)
- 운영: [app.sblog.kr](https://app.sblog.kr) · 안내/정책 페이지 [www.sblog.kr](https://www.sblog.kr)

## 기술 스택
- **Vue 3** (`<script setup>` Composition API) + **Vite**
- **Pinia** (상태관리), **Vue Router** (라우팅 + 인증 가드)
- **Axios** (공통 인스턴스 + 토큰/401 인터셉터)
- **Toast UI Editor** + Prism.js (게시판 마크다운 작성/뷰어)
- **Capacitor** (안드로이드 하이브리드 앱), **Electron** (Windows 데스크톱)
- **Vitest** + `@vue/test-utils` (테스트)

## 빠른 시작
```sh
npm install
npm run dev        # 개발 서버 (전체 앱 표시 — 웹 접근 제한 예외)
```
- Node: `^20.19.0 || >=22.12.0`
- API 베이스 URL: `VITE_API_BASE_URL` (기본 `/api`, Nginx 가 백엔드 8080 으로 프록시)

## 주요 스크립트
| 명령 | 설명 |
|---|---|
| `npm run dev` | 개발 서버 (HMR) |
| `npm run build` | `dist/` 정적 빌드 (웹 배포용) |
| `npm run build:app` | Capacitor 모드 빌드 (`--mode capacitor`, 앱 전용 env) |
| `npm run cap:sync` | 앱 빌드 + `cap sync` (안드로이드 동기화) |
| `npm run cap:android` | Android Studio 열기 |
| `npm run electron:dev` | Electron 데스크톱 실행 |
| `npm run electron:build` | Windows 설치파일(`DonDwaeji-Setup.exe`) 빌드 |
| `npm test` | Vitest 실행 |
| `npm run lint` | oxlint + eslint (`--fix`) |

## 플랫폼별 동작
- **웹(PC·모바일)**: 안내 페이지만 노출(앱 다운로드 유도). 실제 이용은 앱에서. (`npm run dev` 는 예외로 전체 앱 표시)
- **안드로이드**: Capacitor WebView 패키징. 빌드 전 `.env.capacitor` 의 백엔드 절대 URL 설정 필수 → [docs/ANDROID.md](docs/ANDROID.md)
- **Windows**: Electron 이 라이브 사이트(app.sblog.kr)를 직접 로드 → 프론트 변경이 재설치 없이 반영

## 인증
- 로그인 시 발급된 **Bearer 토큰**을 `localStorage` 에 저장, `http.js` 인터셉터가 `Authorization` 헤더에 주입
- **구글 로그인**(웹/PC=GIS, 앱=네이티브 플러그인) — 현재 소셜 로그인 전용(아이디/비번 폼은 `features.js` 플래그로 숨김)
- 401 응답 시 토큰 정리 후 로그인 모달, 라우트 `meta.requiresAuth` / `requiresAdmin` 가드

## 주요 기능
- **가계부** — 수입·지출·이체 기록, 검색·필터, 날짜 그룹 접기/펴기, 외화 입력(환율 자동환산)
- **AI 보조** — 자연어 한 줄 입력("어제 스타벅스 5천원"), 영수증 사진 구조화, 분류·계좌 자동 추천, 통계 화면 재무 코멘트·절약 가이드 (Claude Haiku, 집계만 전송·저장은 사용자 확인 후)
- **계좌·자산** — 은행·현금·카드·대출·투자 계좌, 순자산 자동 집계
- **고정 지출** — 반복 규칙 자동 생성 + '확인' 확정 흐름
- **통계** — '이번 달 현황'(예산·수입 대비 통합), 분류별 분석, 순자산 추이, 월말 예상 지출(일회성 큰 지출 제외 결정적 계산), 지난달 대비
- **예산** — 월별 카테고리 예산, 예산 대비 진행률
- **활동 포인트** — 가계부·게시판 활동 적립, 한 달 개근(모든 날 기록) 랜덤 보너스
- **게시판** — 커뮤니티/짠테크/재테크 3개 게시판, 댓글·태그·이미지 업로드·공지
- **테마** — 시스템/라이트/다크 모드

## 문서
| 문서 | 내용 |
|---|---|
| [docs/FRONTEND.md](docs/FRONTEND.md) | 아키텍처·디렉터리 구조·화면 명세 |
| [docs/release-2026-06-06.md](docs/release-2026-06-06.md) | 누적 변경 이력 (릴리스 노트) |
| [docs/ANDROID.md](docs/ANDROID.md) | 안드로이드(Capacitor) 빌드·배포 |
| [docs/plan-membership-tiers.md](docs/plan-membership-tiers.md) | 무료/유료 티어 설계 (미구현) |
| [deploy/README.md](deploy/README.md) | 프론트 배포(Nginx + Gitea Actions) |
| [brand/LAUNCH-PROGRESS.md](brand/LAUNCH-PROGRESS.md) | Play 스토어 출시 진행 상황·로드맵 |

## 배포
- `main` 푸시 → Gitea Actions 가 CI(빌드·테스트) + Deploy(Nginx 업로드·reload) 실행
- **테스트 게이트**: CI·배포 워크플로 모두 테스트 실패 시 배포 중단
- 상세: [deploy/README.md](deploy/README.md)
