feat(ledger): 예산 설정·CSV 가져오기·영수증 첨부 + 모듈 서브 네비 인프라

[Ledger 기능]
- 카테고리별 예산 한도 (002_budget.sql, budget_limit 필드, 차트 뷰 예산 바)
- CSV 가져오기 (csv-import.ts: RFC4180 파서, EUC-KR 감지, 은행·카드사 포맷 자동 감지,
  중복 판정, 2단계 모달 — 미리보기 → 열 매핑 → 가져오기)
- 영수증 첨부 (003_receipt.sql, receipt_path 필드, 상세 패널 업로드·보기·삭제)
- 카테고리 인라인 편집 시 예산 입력 필드 추가
- routes: POST/GET/DELETE /entries/:id/receipt, POST /import/preview·commit

[모듈 서브 네비 인프라]
- moduleConfig.ts: 모듈별 서브 라우트 정의 레지스트리
- main.tsx: 해시 서브라우트 파싱 (ledger/xxx → base=ledger, sub=xxx)
- AppShell: 활성 모듈 아래 서브 항목 들여쓰기 렌더 (접힘 시 숨김)
- shell.css: .shell-subnav-* 스타일

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: SOIV

apps/web/src/components/AppShell.tsx

@@ -2,13 +2,18 @@ import { type ReactNode, useState, useEffect } from "react";
 import "../styles/shell.css";
 
 import { apiFetch } from "../lib/apiFetch";
+import type { ModuleSubRoute } from "../moduleConfig";
 
 // 코어 라우트 + 설치된 모듈 이름도 RouteKey에 포함 (가계부: "ledger" 등)
 export type CoreRouteKey = "login" | "forgot-password" | "home" | "marketplace" | "admin" | "change-password";
 export type RouteKey = CoreRouteKey | string;
 
 interface AppShellProps {
   route: RouteKey;
+  /** 현재 모듈 내 서브 라우트 ("" = 기본, "import" 등) */
+  subRoute?: string;
+  /** 모듈명 → 서브 라우트 목록 매핑 */
+  moduleSubNav?: Record<string, ModuleSubRoute[]>;
   isAdmin: boolean;
   currentUser: { email: string } | null;
   notice: string;
@@ -42,6 +47,8 @@ function handleNavKeyDown(e: React.KeyboardEvent<HTMLUListElement>) {
 
 export function AppShell({
   route,
+  subRoute = "",
+  moduleSubNav = {},
   isAdmin,
   currentUser,
   notice,
@@ -161,20 +168,50 @@ export function AppShell({
           <p className="shell-nav-label" aria-hidden="true">Modules</p>
           <ul className="shell-nav-list" aria-label="설치된 모듈" onKeyDown={handleNavKeyDown}>
             {sidebarModules.length > 0 ? (
-              sidebarModules.map((mod) => (
-                <li key={mod.name}>
-                  <button
-                    type="button"
-                    className="shell-nav-item"
-                    data-label={mod.displayName || mod.name}
-                    aria-current={route === mod.name ? "page" : undefined}
-                    onClick={() => { window.location.hash = mod.name; closeMobileMenu(); }}
-                  >
-                    <span className="shell-nav-icon" aria-hidden="true">📦</span>
-                    <span className="shell-nav-text">{mod.displayName || mod.name}</span>
-                  </button>
-                </li>
-              ))
+              sidebarModules.map((mod) => {
+                const isActive = route === mod.name;
+                const subItems = moduleSubNav[mod.name];
+                return (
+                  <li key={mod.name}>
+                    {/* 모듈 루트 버튼 */}
+                    <button
+                      type="button"
+                      className="shell-nav-item"
+                      data-label={mod.displayName || mod.name}
+                      aria-current={isActive && !subRoute ? "page" : undefined}
+                      onClick={() => { window.location.hash = mod.name; closeMobileMenu(); }}
+                    >
+                      <span className="shell-nav-icon" aria-hidden="true">📦</span>
+                      <span className="shell-nav-text">{mod.displayName || mod.name}</span>
+                    </button>
+
+                    {/* 서브 네비게이션 — 해당 모듈이 활성화됐을 때만 표시 */}
+                    {isActive && subItems && subItems.length > 0 && (
+                      <ul className="shell-subnav-list" aria-label={`${mod.displayName} 하위 메뉴`}>
+                        {subItems.map((sub) => {
+                          const hash = sub.key ? `${mod.name}/${sub.key}` : mod.name;
+                          const isSubActive = subRoute === sub.key;
+                          return (
+                            <li key={sub.key}>
+                              <button
+                                type="button"
+                                className="shell-subnav-item"
+                                aria-current={isSubActive ? "page" : undefined}
+                                onClick={() => { window.location.hash = hash; closeMobileMenu(); }}
+                              >
+                                {sub.icon && (
+                                  <span className="shell-subnav-icon" aria-hidden="true">{sub.icon}</span>
+                                )}
+                                <span className="shell-subnav-text">{sub.label}</span>
+                              </button>
+                            </li>
+                          );
+                        })}
+                      </ul>
+                    )}
+                  </li>
+                );
+              })
             ) : (
               <li className="shell-nav-empty">모듈 없음</li>
             )}

apps/web/src/main.tsx

@@ -19,6 +19,7 @@ import { ChangePasswordView } from "./views/ChangePasswordView";
 import { ForgotPasswordView } from "./views/ForgotPasswordView";
 import { SetupWizardView } from "./views/SetupWizardView";
 import { LedgerView } from "../../../modules/ledger/frontend/LedgerView";
+import { MODULE_SUB_NAV } from "./moduleConfig";
 
 // ─── Helpers ──────────────────────────────────────────────────
 
@@ -27,14 +28,23 @@ const CORE_ROUTES = ["login", "forgot-password", "home", "marketplace", "admin",
 // 모듈 라우트 — module.json name 기준 (서버 레지스트리와 일치)
 const MODULE_ROUTES: string[] = ["ledger"];
 
+/** 해시에서 베이스 라우트만 추출 ("ledger/import" → "ledger") */
 function getRouteFromHash(rawHash: string): RouteKey {
   const hash = rawHash.replace("#", "");
-  if (hash === "settings") return "home";
-  if ((CORE_ROUTES as readonly string[]).includes(hash)) return hash as RouteKey;
-  if (MODULE_ROUTES.includes(hash)) return hash as RouteKey;
+  const base = hash.split("/")[0] ?? hash;
+  if (base === "settings") return "home";
+  if ((CORE_ROUTES as readonly string[]).includes(base)) return base as RouteKey;
+  if (MODULE_ROUTES.includes(base)) return base as RouteKey;
   return "login";
 }
 
+/** 해시에서 서브 라우트만 추출 ("ledger/import" → "import", "ledger" → "") */
+function getSubRouteFromHash(rawHash: string): string {
+  const hash = rawHash.replace("#", "");
+  const parts = hash.split("/");
+  return parts.length > 1 ? parts.slice(1).join("/") : "";
+}
+
 // ─── Theme ────────────────────────────────────────────────────
 type ThemeSetting = "light" | "dark" | "system";
 
@@ -158,11 +168,14 @@ function App() {
   const [isPinModalOpen, setIsPinModalOpen] = useState(false);
   const [notice, setNotice] = useState("");
   const [route, setRoute] = useState<RouteKey>(() => getRouteFromHash(window.location.hash));
+  const [subRoute, setSubRoute] = useState<string>(() => getSubRouteFromHash(window.location.hash));
 
   useEffect(() => {
     const handleHashChange = () => {
       const next = getRouteFromHash(window.location.hash);
+      const nextSub = getSubRouteFromHash(window.location.hash);
       setRoute(next);
+      setSubRoute(nextSub);
       // 비인증 상태에서 app route로 hash 변경 시 redirect 대상 갱신
       const appRoutes: RouteKey[] = ["home", "marketplace", "admin"];
       if (sessionStorage.getItem(SS.auth) !== "true" && (appRoutes as string[]).includes(next)) {
@@ -463,6 +476,8 @@ function App() {
       )}
       <AppShell
         route={effectiveRoute}
+        subRoute={subRoute}
+        moduleSubNav={MODULE_SUB_NAV}
         isAdmin={isAdmin}
         currentUser={currentUser}
         notice={notice}
@@ -487,7 +502,7 @@ function App() {
           />
         )}
         {/* ── 모듈 뷰 ────────────────────────────────────── */}
-        {effectiveRoute === "ledger" && <LedgerView />}
+        {effectiveRoute === "ledger" && <LedgerView subRoute={subRoute} />}
         {isSettingsOpen && (
           <SettingsView
             theme={theme}

apps/web/src/moduleConfig.ts

@@ -0,0 +1,18 @@
+/**
+ * 모듈별 사이드바 서브 네비게이션 정의
+ *
+ * key: "" → 모듈 기본 뷰 (#ledger)
+ * key: "xxx" → 서브 뷰 (#ledger/xxx)
+ *
+ * 새 모듈을 추가할 때 여기에 항목을 등록한다.
+ */
+
+export interface ModuleSubRoute {
+  key: string;
+  label: string;
+  icon?: string;
+}
+
+export const MODULE_SUB_NAV: Record<string, ModuleSubRoute[]> = {
+  // 서브 네비 항목은 추후 계획 후 등록
+};

apps/web/src/styles/shell.css

@@ -137,6 +137,83 @@
   opacity: 0.45;
 }
 
+/* ── 서브 네비게이션 ──────────────────────────────────────────── */
+
+.shell-subnav-list {
+  list-style: none;
+  margin: 2px 0 4px 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+
+.shell-subnav-item {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  /* 모듈 버튼보다 들여쓰기 + 작은 높이 */
+  padding: 5px 8px 5px 28px;
+  border: none;
+  border-radius: 5px;
+  background: transparent;
+  color: var(--text-faint);
+  font-size: 12px;
+  font-weight: 500;
+  font-family: inherit;
+  text-align: left;
+  cursor: pointer;
+  transition: background 100ms ease, color 100ms ease;
+  position: relative;
+}
+
+/* 왼쪽 연결선 */
+.shell-subnav-item::before {
+  content: "";
+  position: absolute;
+  left: 17px;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 6px;
+  height: 1px;
+  background: var(--border-subtle);
+}
+
+.shell-subnav-item:hover {
+  background: var(--bg-hover);
+  color: var(--text-muted);
+}
+
+.shell-subnav-item[aria-current="page"] {
+  background: var(--accent-subtle);
+  color: var(--accent-hover);
+  font-weight: 600;
+}
+
+.shell-subnav-item[aria-current="page"]::before {
+  background: var(--accent-hover);
+}
+
+.shell-subnav-icon {
+  font-size: 11px;
+  width: 13px;
+  text-align: center;
+  flex-shrink: 0;
+  opacity: 0.7;
+}
+
+.shell-subnav-text {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* 사이드바 접힘 상태: 서브 네비 숨김 */
+.shell[data-sidebar-collapsed] .shell-subnav-list {
+  display: none;
+}
+
 /* Empty state for module list */
 .shell-nav-empty {
   padding: 5px 8px;

docs/v2_FINANCIAL-LEDGER/roadmap/01-development-plan.md

@@ -1,11 +1,12 @@
 # 단계별 개발 계획
 
-> 📌 **프로젝트 상태:** 2026-04-16 기준 **Phase 1.95 진행 중** (1.95.3 Setup UI 구현 완료, 1.95.4 대기).
+> 📌 **프로젝트 상태:** 2026-04-19 기준 **Phase 2.1 Ledger 기능 완료 (테스트 제외)**.
 > - Phase 1.5 전 항목 완료 (Core UI Shell / 로그인 / 홈 / 설정 / 관리자).
 > - Phase 1.9 완료 (API 서버 + DB + 인증 백엔드 + 공유 링크).
-> - Phase 1.95.1 모드 전환 시스템 완료 (`installed.lock` / `fieldstack.config.json` 기반).
-> - Phase 1.95.2 Setup 백엔드 API 완료 (Docker/systemd/native 런타임 감지·프로비저닝, SSE 스트리밍, IP 배너 출력).
-> - Phase 1.95.3 Setup UI 완료 (4단계 설치 마법사 — Welcome / Config / Progress / Complete).
+> - Phase 1.95 전 항목 완료 (모드 전환·Setup 백엔드 API·Setup UI·초기화 UI).
+> - Phase 2 사전 작업 완료 (ModuleRegistry·모듈 관리 API·Admin UI 연동·유저별 모듈 활성화).
+> - Phase 2.1 Ledger 백엔드 완료 (CRUD·통계·CSV export/import·카테고리·결제수단·예산·영수증 첨부 API).
+> - Phase 2.1 Ledger 프론트엔드 완료 (목록·폼·요약 카드·카테고리·결제수단 관리·상세 패널·SVG 차트·예산 현황·CSV import 2단계 모달·영수증 첨부). 미완료: 테스트.
 
 ## 개요
 
@@ -532,11 +533,11 @@ Chrome 확장 프로그램의 "새로고침" 방식과 동일하게:
 
 **Frontend:**
 - [x] 목록 페이지 (DataTable, 월 네비게이션, 필터 탭)
-- [ ] 상세 페이지
+- [x] 상세 패널 (우측 슬라이드 드로어 — 금액·카테고리·메모·태그·등록일·수정·삭제 액션)
 - [x] 생성/수정 폼 (모달)
 - [x] 통계 대시보드 (월별 수입·지출·잔액 카드)
 - [x] 카테고리·결제수단 관리 UI (탭 모달 — 추가/삭제)
-- [ ] 차트 시각화 (recharts)
+- [x] 차트 시각화 (SVG 도넛 차트 — 수입·지출 비교 바 + 카테고리별 도넛, 라이브러리 불필요)
 - [ ] 테스트
 
 **기능:**
@@ -545,9 +546,9 @@ Chrome 확장 프로그램의 "새로고침" 방식과 동일하게:
 - [x] 결제 수단 관리 (CRUD API + 관리 UI)
 - [x] 월별/연도별 통계
 - [x] CSV 내보내기 (`GET /api/ledger/entries/export`, BOM 포함 UTF-8, 프론트 다운로드 버튼 포함)
-- [ ] 카테고리별 예산 설정 (`ledger_categories.budget_limit` 컬럼 추가 — `002_budget.sql`)
-- [ ] CSV 가져오기 (은행·카드사 CSV 포맷 자동 감지·매핑·중복 검증 — `docs/modules/91-ledger-csv-import.md` 설계 완료)
-- [ ] 영수증 첨부 (선택)
+- [x] 카테고리별 예산 설정 (`ledger_categories.budget_limit` 컬럼 — `002_budget.sql`, 관리 UI·차트 뷰 예산 바)
+- [x] CSV 가져오기 (은행·카드사 포맷 자동 감지·열 매핑·중복 감지·2단계 모달 — `csv-import.ts`)
+- [x] 영수증 첨부 (`ledger_entries.receipt_path` — `003_receipt.sql`, 상세 패널 업로드/삭제)
 - [ ] 사업자 관련 (세무 메타데이터 — `docs/modules/04-tax-management.md` 초안 완료, 세무사 검증 후 착수)
 
 #### 2.2 Subscription Module (구독 관리)