우리집 가계부 (fos-accountbook)
가족이 함께 수입과 지출을 기록하고, 월 예산을 관리하는 가계부 웹앱이다.
직접 쓰려고 만들었고 홈서버에서 운영한다.
주요 기능
| 기능 | 내용 |
|---|
| 로그인 | Google, Naver 소셜 로그인 |
| 가족 | 가족 생성, 초대 링크 발급과 수락, 기본 가족 선택 |
| 달력 홈 | 날짜 칸마다 구성원별 지출을 보여 주고, 날짜를 골라 바로 등록·수정·삭제 |
| 거래 내역 | 지출과 수입의 등록·수정·삭제, 카테고리와 기간 필터 |
| 반복 지출 | 매월 정한 날에 지출을 자동으로 만든다 |
| 카테고리 | 가족별 카테고리, 색상과 아이콘, 예산 제외 설정 |
| 예산 | 월 예산과 진행률, 50·80·100% 도달 알림 |
| 할부 | 할부를 기록하고 회차와 남은 금액을 본다. 예산에는 넣지 않는다 |
| 분석 | 월별 지출 추이, 카테고리별 비중과 전월 대비 변동 |
| 알림 센터 | 예산 알림과 반복 지출 생성 알림, 읽음 처리 |
| 외부 연동 토큰 | AI 에이전트 같은 외부 도구가 가계부 API 를 부를 수 있게 사용자별 토큰을 발급하고 폐기한다 |
구성
flowchart LR
U[브라우저] --> F[frontend<br/>Next.js 16]
F -- Server Action / ky --> B[backend<br/>Spring Boot 4]
A[외부 에이전트] -- fab_ 토큰 --> B
B --> D[(MySQL 8.4)]
| 디렉터리 | 내용 | 기술 |
|---|
frontend/ | 웹 화면과 Server Action | Next.js 16, React 19, TypeScript, Tailwind CSS v4, shadcn/ui, NextAuth v5 |
backend/ | REST API (/api/v1) | Java 21, Spring Boot 4, Spring Data JPA, QueryDSL, Flyway, MySQL 8.4 |
docs/ | 저장소 전체 결정 (ADR-M) | |
로컬 실행
도구 버전은 .tool-versions 가 정한다(Node 24, pnpm 10, Java 21).
# 1. MySQL (호스트 포트 13306)
docker compose -f backend/docker/compose.yml up -d
# 2. 백엔드 (http://localhost:8080)
cd backend && ./gradlew bootRun --args='--spring.profiles.active=local'
# 3. 프론트엔드 (http://localhost:3000)
cd frontend && pnpm install && pnpm dev
gradle-wrapper.jar 는 추적하지 않는다. 없으면 CLAUDE.md 의 명령으로 만든다.- 프론트엔드 환경 변수는
frontend/README.md 에 있다.
- 프론트엔드와 백엔드의
AUTH_SECRET 은 같은 값이어야 한다. 소셜 로그인 결과를 이 값으로 서명해 백엔드에 넘긴다.
검증
커밋 전에 바뀐 쪽의 검증을 로컬에서 통과시킨다.
cd frontend && pnpm lint && pnpm test
cd backend && ./gradlew qualityCheck test
CI와 배포
| 워크플로 | 하는 일 |
|---|
frontend-ci.yml, backend-ci.yml | PR 과 main push 마다 타입 검사, lint, 테스트 |
docs-ci.yml | 문서가 바뀐 PR 에서 ADR 링크 검사 |
claude-code-review.yml | PR 자동 코드 리뷰. 재실행은 /review 댓글 |
frontend-image.yml, backend-image.yml | main 에 머지되면 이미지를 ghcr.io/jon890/fos-accountbook-{frontend,backend} 로 올린다 |
홈서버는 올라간 이미지를 받아 실행한다.
DB 스키마는 백엔드가 시작할 때 Flyway 가 적용한다.
기여 규칙
- main 에 직접 push 할 수 없다. 작업 브랜치와 PR 로 바꾼다.
- PR 제목과 커밋 메시지는
type(scope): 설명 형식이고, 커밋은 한국어로 쓴다.
- 브랜치 이름, 계획서 작성 흐름, 문서 원칙은 CLAUDE.md 가 정한다.
문서
