sb-front/docs/FRONTEND.md

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

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

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

## 브랜딩
- 서비스명 **돈돼지 가계부** (구 Slim Budget)
- 로고: 돈돼지(투명 배경) — 헤더/사이드바 로고·파비콘·앱 런처 아이콘. 브랜드 그린 `#00bc7e`

## 플랫폼별 동작
- **웹(PC·모바일)**: 안내 페이지([WebOnlyNotice.vue](../src/components/WebOnlyNotice.vue))만 노출(앱 다운로드 유도). 실제 이용은 앱에서. `npm run dev` 는 예외로 전체 앱 표시
- **안드로이드**: Capacitor WebView 패키징 → [ANDROID.md](ANDROID.md)
- **Windows**: Electron 이 라이브 사이트(app.sblog.kr)를 직접 로드 → 프론트 변경이 재설치 없이 반영
- 기능 플래그 [src/config/features.js](../src/config/features.js): `ID_LOGIN_ENABLED`(아이디 로그인)·`BILLING_ENABLED`(인앱결제)·`ADS_ENABLED`(광고)·`CARD_NOTIF_ENABLED`(카드알림) — 첫 출시 기준 전부 `false`

## 디렉터리 구조
```
src/
├── api/               # 백엔드 연동 (axios)
│   ├── http.js        # 공통 인스턴스 (Authorization 주입, 401 처리)
│   ├── authApi.js     # 로그인/회원가입/세션
│   ├── boardApi.js    # 게시판
│   ├── adminApi.js    # 관리자(태그 카테고리)
│   └── accountApi.js  # 가계부 전체
│   ├── billingApi.js  # 인앱결제/구독
├── stores/            # Pinia (auth, ui, user)
├── config/features.js # 기능 플래그(아이디로그인·결제·광고·카드알림)
├── router/index.js    # 라우트 + 인증 가드
├── components/
│   ├── layout/        # AppHeader / AppSidebar / AppFooter / AppBottomNav
│   ├── ui/            # IconBtn / AppModal(전체화면 슬라이드업) / AppDialog / CategoryPicker
│   ├── editor/        # MarkdownEditor / MarkdownViewer
│   ├── LoginModal.vue / SignupModal.vue / AppLockScreen.vue(PIN) / AdBanner.vue / WebOnlyNotice.vue
├── views/
│   ├── HomeView.vue   # 홈 대시보드(요약·일별 캘린더)
│   ├── board/         # 게시판 (목록/상세/작성)
│   ├── account/       # 가계부 (아래 참조)
│   └── admin/         # 회원/태그 관리(관리자)
└── assets/            # base.css(data-theme 다크모드) 등 전역 스타일
```

## 인증
- 로그인 시 발급된 **Bearer 토큰**을 `localStorage`에 저장, `http.js` 요청 인터셉터가 `Authorization` 헤더에 주입
- **구글 로그인**(웹/PC=Google Identity Services, 앱=네이티브 플러그인) — 현재 소셜 로그인 전용(`ID_LOGIN_ENABLED=false` 로 아이디/비번 폼·회원가입 UI 숨김)
- 401 응답 시 토큰 정리 후 `auth:unauthorized` 이벤트 → 로그인 모달 표시
- 라우트 `meta.requiresAuth` / `requiresAdmin` 가드

## 레이아웃 / 반응형 / 테마
- 그리드 레이아웃 — 사이드바가 좌측 상단(헤더 행)까지, 헤더는 현재 화면 타이틀 표시. 본문 폭 `--page-max`(760px)로 통일
- **하단 고정 내비**([AppBottomNav.vue](../src/components/layout/AppBottomNav.vue)): 뒤로·앞으로·홈·새로고침·설정 (안드로이드 소프트키 위 안전영역)
- **모바일(≤768px)**: 사이드바가 **오프캔버스 드로어**(햄버거 토글 + 백드롭, 라우트 이동 시 자동 닫힘)
- **입력 모달**: 전체화면 슬라이드업([AppModal.vue](../src/components/ui/AppModal.vue), 바깥 닫힘 방지). 셀렉트 대신 **뱃지/칩** 선택, 분류는 공통 [CategoryPicker.vue](../src/components/ui/CategoryPicker.vue)(대/소분류 아코디언)
- **테마**: 시스템 / 라이트 / 다크 (설정 화면, `data-theme` 기반)
- 모든 액션 버튼은 **아이콘화**(`IconBtn`), `title`로 접근성·툴팁 제공

## 게시판 (`/board`)
- **커뮤니티 / 짠테크 수다방 / 재테크 팁** 3개 게시판(카테고리)
- 목록(페이징·태그 필터·검색[제목/본문/댓글]·공지 최상단), 상세, 작성/수정(마크다운·이미지 업로드)
- 댓글, 추천(vote), 태그, **공지**(관리자), 관리자 **열람 제한/해제**, 신고

## 가계부 (`/account`)
사용자별 데이터 격리(본인 데이터만). 주요 화면(사이드바 하위 메뉴):

| 경로 | 화면 | 설명 |
|------|------|------|
| `/account` | 대시보드 | 예산 대비 지출 도넛, **분류별 파이차트**(대분류 집계), 수입대비지출(월말 예상·지난달 대비), 월별 총액, **순자산 추이**(주간) 라인차트, 일별 캘린더 |
| `/account/entries` | 가계부 내역 | 월별 내역 CRUD, **검색·필터**(키워드/구분/분류/계좌/태그), 날짜 그룹 접기/펴기, **외화 입력**(환율 자동환산), 내역→고정지출 바로 등록 |
| `/account/recurrings` | 고정 지출 | 일/주/월/년 반복 규칙, 진입 시 자동 반영(중복 없이·'확인 필요'로 생성) |
| `/account/wallets` | 계좌 관리 | 은행/**현금**/카드/대출/**투자** 계좌, 잔액·순자산, 상환/납부(원금·이자·연회비 분리), 월별 이용내역 |
| `/account/categories` | 분류 관리 | 수입/지출 분류 CRUD(**대/소분류 2단계**), 칩 그리드 관리, 순서변경, 기존 내역에서 가져오기 |
| `/account/budget` | 예산 설정 | **월별 예산**(전월/다음달 복사), 고정(일수 기준 자동 환산)/비고정, 예산 대비 진행률 |
| `/account/tags` | 태그 관리 | 사용자별 가계부 태그 |

### 잔액·순자산 모델 (표시)
- 자산(+) / 부채(−) 부호 모델. 현금은 은행과 동일하게 자산 합산. 지갑 잔액 = 개시잔액 + 수입 − 지출 − 이체출금 + 이체입금
- 순자산 = 총자산 − 총부채 (투자계좌는 평가금액 반영)

### 투자 계좌 (계좌 관리 > 투자 탭)
- 투자계좌를 펼치면 [InvestPortfolio.vue](../src/views/account/InvestPortfolio.vue) 패널
- **단순형 UI**: **투자금(투입원금) + 현재 평가액**만 입력 → 손익·수익률 자동 계산(퇴직연금·연금 등 포함). 계좌 펼침 시 투자금/평가액/손익(%) 요약 카드
- 입금은 가계부 **이체**(은행→투자)로, 평가액은 순자산·추이에 반영
- ℹ️ 백엔드는 종목 단위(매수·매도·시세 자동조회) API 를 유지하나 현재 UI 에는 노출하지 않음. 원화 기준

## 설정 화면
- 하단 내비 → 설정: 계정정보(이름·이메일·비밀번호 변경) · 테마(시스템/라이트/다크) · 앱 잠금(PIN, 1시간 유예) · 앱 버전 · App Data 삭제 · (PC)창 크기 프리셋

## 개발/빌드
```bash
npm install
npm run dev        # 개발 서버(전체 앱 표시)
npm run build      # dist/ 정적 빌드(웹 배포)
npm run cap:sync   # 앱 빌드 + 안드로이드 동기화
npm run electron:build  # Windows 설치파일
npm test           # Vitest
```
- API 베이스 URL: `VITE_API_BASE_URL` (기본 `/api`)
- 상세: [../README.md](../README.md) · 앱 [ANDROID.md](ANDROID.md) · 배포 [../deploy/README.md](../deploy/README.md)