※ 이 설계 문서는 사후에 정리한 산출물이 아니라, Claude Code와 대화하며 프로젝트 설계를 진행한 원문 그대로입니다.
이 문서는 [가계부_아키텍처_설계.md]의 목차 번호를 기준으로 기능 코드(F-코드)를 부여합니다. WBS 문서의 모든 TASK는 이 코드를 참조합니다.
코드 형식: F-{아키텍처 장 번호}-{일련번호} (예: F-1-1-1 = 아키텍처 1-1장 관련 1번째 기능)
1. IA (정보구조) — 전체 메뉴 트리
가계부 앱
├── 0. 인증 (F-3-x)
│ ├── 회원가입
│ ├── 로그인 (이메일/소셜)
│ └── 계정 설정
│
├── 1. 대시보드 (F-5-x)
│ ├── 개요 (이번달 총지출, 예산 소진율)
│ ├── 항목별 통계 (②카테고리)
│ ├── 지출분류별 통계 (①현금/카드, 카드(카드사명)별)
│ ├── 지출처 Top N (③)
│ ├── 상세항목 Top10 (④⑤)
│ └── 단가 분석 (⑥수량/단위 기반)
│
├── 2. 지출 입력/관리 (F-1-1-x)
│ ├── 지출 입력 (신규/수정)
│ │ ├── 지출분류 선택
│ │ ├── 지출항목 선택
│ │ ├── 지출처 선택/등록
│ │ └── 상세내용 추가(선택, 품목+수량/단위+금액)
│ ├── 지출 내역 리스트/검색/필터
│ └── 지출 내역 캘린더 조회 (월별, 날짜별 "+" 빠른 입력) — F-1-1-14
│
├── 3. 마스터 데이터 관리 (F-1-1-x, 설정 메뉴 하위)
│ ├── 지출분류 관리 (현금 표시, 계좌/카드 등록, 카드사명 설정)
│ ├── 지출항목 관리 (카테고리 CRUD)
│ ├── 지출처 관리 (Vendor CRUD)
│ ├── 상세항목(품목) 관리 (Item 마스터, 별칭/병합)
│ └── 단위 관리 (Unit 마스터)
│
├── 4. 예산 관리 (F-4-1)
│ └── 카테고리별 예산 설정/소진율 확인
│
├── 5. 관리비 명세서 (F-1-2-x) — 2단계, 2026-07-11 메인앱 내장 기능으로 재정의(서브앱 방식 폐기)
│ ├── 명세서 업로드 (사진/PDF → OCR 추출 → 등록)
│ ├── 항목 선정 (최초 업로드·양식 변경 감지 시 진입)
│ ├── 명세서 통계 (총액·항목별 추이 등)
│ └── 명세서 이력 확인 (월별 원본 항목 내역, 2026-07-19 추가 — F-1-2-6)
│
└── 6. 관리자 전용 (F-1-1-13) — 운영자
└── 동의어 사전(SYNONYM_DICTIONARY) 관리
1-1. 실제 네비게이션 메뉴 구성 (구현 완료 기준)
위 1장 "전체 메뉴 트리"는 최종 완성 시점의 계획도다. 여기 표는 지금 화면에 실제로 노출되는 사이드바 메뉴만 담는다 — 아직 안 만든 화면으로 가는 링크를 넣어서 죽은 링크를 만들지 않기 위함. 코드 상 원본은 apps/main/web/app/(app)/nav-items.ts이며, 새 화면(F-코드)이 완료될 때마다 이 표와 nav-items.ts 둘 다 같이 갱신할 것.
| 메뉴 라벨 |
경로 |
상위 메뉴 |
대응 F-코드 |
| 홈 |
/ |
- |
F-5-1 (요약 카드) + F-1-8-2(월별추이) + F-1-8-3(카테고리별) + F-3-1-1(지출분류별, 현금/카드 대분류+카드사명별) + F-3-1-2(지출처 Top 10) + F-3-1-3(상세항목 Top 10 + 지출처별 드릴다운) + F-3-1-4(품목×단위 평균단가 추이) |
| 지출 입력 |
/expenses/create |
- |
F-1-1-4 |
| 지출 내역 |
/expenses |
- |
F-1-1-11 |
| 예산 관리 |
/budgets |
- |
F-4-1 |
| 관리비 명세서 |
/utility-bills/upload |
- |
F-1-2-1 (2차 개발 TASK ID는 F-2-1-1~F-2-1-3 — WBS 2차 §4 표기법 참고) |
| 명세서 업로드 |
/utility-bills/upload |
관리비 명세서 |
F-1-2-1 |
| 명세서 통계 |
/utility-bills/stats |
관리비 명세서 |
F-1-2-3 (총액 불일치 알림 아이콘은 F-1-2-5) |
| 명세서 이력 |
/utility-bills/history |
관리비 명세서 |
F-1-2-6 (2차 개발 TASK ID는 F-2-4-4) |
| 설정 |
/settings |
- |
F-3-4 |
| 지출분류 관리 |
/settings/payment-methods |
설정 |
F-1-1-1 |
| 지출항목 관리 |
/settings/categories |
설정 |
F-1-1-2 |
| 지출처 관리 |
/settings/vendors |
설정 |
F-1-1-3 |
| 품목 관리 |
/settings/items |
설정 |
F-1-1-8 (F-1-6-1, 목록 조회만) |
| 동의어 사전 관리 |
/admin/synonyms |
- |
F-1-1-13 (운영자 전용 — ADMIN_EMAILS 화이트리스트에 없으면 사이드바 비노출 + 직접 접근 시 /로 리다이렉트) |
레이아웃 구조: 상단바(로고 + 알림 아이콘 자리 — 알림 기능 자체는 미구현) + 좌측 사이드바(위 메뉴) + 우측 콘텐츠 영역. 모바일에서는 사이드바가 드로어(하단이 아닌 좌측 슬라이드 오버레이)로 전환된다.
2. 기능 명세 (F-코드별 상세)
F-3 — 인증 (아키텍처 3장)
| 코드 |
기능명 |
설명 |
입력 |
출력/결과 |
| F-3-1 |
회원가입 |
이메일/비밀번호 또는 소셜 계정으로 가입 |
이메일, 비밀번호 (or OAuth) |
Supabase Auth 사용자 생성 |
| F-3-2 |
로그인 |
가입된 계정으로 로그인 |
이메일/비밀번호 |
JWT 세션 발급 |
| F-3-3 |
로그아웃/세션관리 |
세션 종료, Refresh Token 회전 |
- |
세션 무효화 |
| F-3-4 |
계정 설정 |
이름/이메일 변경, 비밀번호 변경 |
변경값 |
사용자 정보 갱신 |
F-1-1 — 지출 입력 및 마스터 데이터 관리 (아키텍처 1-1장 ①~⑥)
| 코드 |
기능명 |
참조 |
설명 |
| F-1-1-1 |
지출분류 관리 |
1-1① |
현금(지갑, 가입 시 자동생성·고정) 표시/이름수정, 계좌(통장) 등록(UI 문구는 "자동이체" 대신 "계좌"), 카드 등록(카드사명/카드종류, 2026-07-03 정정 — 별도 카드사 필드 폐기), 수정/비활성화 |
| F-1-1-2 |
지출항목 관리 |
1-1② |
시스템 기본 지출항목(회원가입 시 자동생성) 표시/활성-비활성화 + 사용자 지출항목 CRUD (단일 항목, 계층 없음) |
| F-1-1-3 |
지출처 관리 |
1-1③ |
Vendor CRUD (2026-07-03 정정 — 기본 카테고리 추천 설정 폐기: 한 지출처에서 여러 카테고리 지출이 섞일 수 있어 고정 매칭하지 않음) |
| F-1-1-4 |
지출 입력(상세 미사용) |
1-1③ |
지출분류+지출항목+지출처+금액 직접입력 |
| F-1-1-5 |
지출 입력(상세 사용) |
1-1③④ |
지출처 하위에 상세항목(품목) 여러 건 추가, 금액 자동합산 |
| F-1-1-6 |
상세항목 자동완성/신규생성 |
1-1⑤ |
입력 중 기존 Item 검색 → 선택 or 신규 생성 |
| F-1-1-7 |
상세항목 유사 후보 제안 |
1-1⑤ |
유사 항목/동의어 사전 기반 "같은 품목인가요?" 제안 팝업 |
| F-1-1-8 |
상세항목 마스터 관리(품목 관리 화면) |
1-1⑤ |
내 품목 목록 조회, 별칭 추가, 수동 병합(merge) |
| F-1-1-9 |
수량/단위 입력 |
1-1⑥ |
자유 텍스트 입력 → 구조화 시도(숫자+단위 분리) → 실패시 원본 보존 |
| F-1-1-10 |
단위 자동완성/신규생성 |
1-1⑥ |
기존 Unit 검색 → 선택 or 신규 단위 등록 제안 |
| F-1-1-11 |
지출 내역 리스트/검색/필터 |
1-1, 4 |
기간/지출분류/지출항목/지출처 필터, 검색 |
| F-1-1-12 |
지출 수정/삭제 |
1-1, 4 |
기존 트랜잭션 수정(상세 포함)/삭제 |
| F-1-1-14 |
지출 내역 캘린더 조회 + 빠른 입력 |
1-1, 4 |
(2026-07-04 백로그 B-7 채택) 월별 캘린더 그리드에 일자별 지출 카드 나열, /expenses 화면에서 목록↔캘린더 토글로 진입. 날짜 셀의 "+"로 레이어 팝업을 열어 그 날짜를 기본값으로 바로 지출 입력, 저장 즉시 캘린더에 반영. 캘린더의 기존 지출 카드를 클릭해도 페이지 이동 없이 동일한 레이어 팝업으로 수정/삭제(F-1-1-12와 동일 기능을 팝업으로 재사용) 가능 |
F-4 — 예산 (아키텍처 4장 BUDGET/BUDGET_TOTAL 엔티티)
| 코드 |
기능명 |
설명 |
| F-4-1 |
예산 설정 |
전체(월) 예산을 먼저 등록 → 그 안에서 카테고리별 월 한도 설정(2026-07-03 정정 — 카테고리별 예산 합계가 전체 예산을 초과하면 저장 자체를 막음) |
| F-4-2 |
예산 소진율 표시 |
/budgets 화면에 인라인 게이지로 표시(전체 예산 + 카테고리별 각각, 2026-07-03 구현 — 이번 달 실제 지출을 예산과 비교, MV 없이 단순 직접 쿼리). 대시보드 요약 카드(F-5-1)에서의 표시는 3-8 대시보드 TASK에서 별도 진행 |
F-5 — 대시보드/통계 (아키텍처 5장)
| 코드 |
기능명 |
참조 |
설명 |
| F-5-1 |
대시보드 개요 |
5 |
이번달 총지출, 전월 대비, 예산 소진율 요약 카드 |
| F-5-2 |
월별 추이 차트 |
5 |
최근 N개월 지출 추이 |
| F-5-3 |
항목별(②) 통계 |
5 |
카테고리 도넛/트리맵 |
| F-5-4 |
지출분류별(①) 통계 |
5 |
현금 vs 카드, 카드(카드사명)별 집계 |
| F-5-5 |
지출처별(③) Top N |
5 |
자주/많이 쓴 지출처 순위 |
| F-5-6 |
상세항목(④⑤) Top10 |
5 |
품목별 지출 Top10, 드릴다운(어느 지출처에서) |
| F-5-7 |
단가 분석(⑥) |
5 |
item_id+unit_id 기준 평균단가 추이, "1+1" 등 비구조화 데이터 제외 |
F-1-2 — 관리비 명세서 (2026-07-11 재정의 — 서브앱/Webhook 방식 폐기, 메인앱 내장 기능으로 전환)
이 번호대는 원래 "서브앱 연동"(계정연결·항목매핑·Webhook 수신) 용도로 부여됐으나, 2차 설계 과정에서 관리비를 별도 서브앱이 아닌 메인앱 내장 기능으로 개발하기로 결정(콘텐츠상 독립 실행 가치가 낮고 개발 범위가 크게 줄어듦)하면서 미구현 상태 그대로 이 기능으로 재정의합니다. 상세 데이터 구조는 docs/2차/관리비명세서_데이터구조설계.md 참고. 아키텍처 참조 장은 해당 문서 반영 후 가계부_아키텍처_설계.md에 소단원 추가 예정(현재 미반영, TBD).
| 코드 |
기능명 |
설명 |
단계 |
| F-1-2-1 |
명세서 업로드 |
관리비 고지서 사진/PDF 업로드 → OCR 추출 → 최초업로드/재업로드(형식동일)/형식변경 자동 분기 → 등록. 동일 월 기존 등록(수동/업로드) 존재 시 차단 또는 재업로드 확인 팝업 처리 |
2단계 |
| F-1-2-2 |
항목 선정 |
최초 업로드·형식변경 감지 시에만 진입(별도 페이지, 팝업 아님). 추출된 항목 중 통계로 추적할 항목 선택(최소 1개 필수), 신규 항목 추가/기존 항목 비활성화 처리 |
2단계 |
| F-1-2-3 |
명세서 통계 |
총액추이(입력방식 무관 전체), 항목별추이(업로드된 달만, 값 없음은 "-" 표시), 비지정 항목 리스트(+지정 항목 승격), 총액불일치 알림 아이콘 등. 콘텐츠 상세 우선순위는 화면설계 시 확정(TBD) |
2단계 |
| F-1-2-4 |
지출입력 수동등록 연계 |
기존 지출 입력 화면(F-1-1-4)에서 카테고리="관리비/공과금" 선택 시 그대로 수동 금액 입력(화면 변경 없음, 기존 기능 재사용) |
2단계 |
| F-1-2-5 |
총액 불일치 알림 |
지정 항목 합계와 트랜잭션 총액이 다를 경우 지출 수정 화면(F-1-1-12)과 명세서 통계 화면 양쪽에 알림 표시 |
2단계 |
| F-1-2-6 |
명세서 이력 확인 |
월별 등록 이력을 원본 항목별 내역(TRANSACTION.raw_payload, 구획별 소계 포함)으로 확인. 웹/태블릿은 이전/현재/다음 3개월 동시 비교, 모바일은 1개월 + 화살표 이동. 수동 등록(source='MANUAL') 달은 총액만, 등록 자체가 없는 달은 안내 문구 표시(둘 다 화살표는 계속 활성). 화살표는 전체 등록 기간 양끝(최초 등록월 이전 / 오늘이 속한 달 이후)에서만 비활성화(2026-07-19 PM 요청, WBS 2차 TASK ID는 F-2-4-4) |
2단계 |
F-1-1-13 — 동의어 사전 관리 (아키텍처 1-1⑤, 운영자 전용)
| 코드 |
기능명 |
설명 |
| F-1-1-13 |
동의어 사전 관리 |
SYNONYM_DICTIONARY 그룹/단어 CRUD (운영자 어드민 화면) |
3. 기능 ↔ 아키텍처 ↔ 데이터 매핑 요약
| 기능 코드 |
아키텍처 참조 장 |
핵심 테이블 |
| F-3-x |
3 |
Supabase Auth (auth.users) |
| F-1-1-1 |
1-1①, 4 |
PAYMENT_METHOD |
| F-1-1-2 |
1-1②, 4 |
CATEGORY |
| F-1-1-3 |
1-1③, 4 |
VENDOR |
| F-1-1-4~5 |
1-1③④, 4 |
TRANSACTION, TRANSACTION_DETAIL |
| F-1-1-6~8 |
1-1⑤, 4 |
ITEM, SYNONYM_DICTIONARY(참고용) |
| F-1-1-9~10 |
1-1⑥, 4 |
UNIT |
| F-4-x |
4 |
BUDGET |
| F-5-x |
5 |
tx_stats, item_stats, item_unit_stats (MV) |
| F-1-2-x |
TBD(아키텍처 문서 미반영, docs/2차/관리비명세서_데이터구조설계.md 참고) |
UTILITY_BILL_ITEM, UTILITY_BILL_RECORD, UTILITY_BILL_ITEM_VALUE, TRANSACTION(연계) |
| F-1-1-13 |
1-1⑤ |
SYNONYM_DICTIONARY |
이 매핑표가 WBS 문서에서 "이 TASK가 설계서 어느 부분을 구현하는지"를 추적하는 기준이 됩니다.