[3-9] 잔고 현황 할부 연동 (#112)

* feat: 잔고 현황 할부 연동 및 거래 상세 원본 링크 추가

* fix: PR 리뷰 반영 (할부 조회 실패 격리 및 SPA 라우팅)

Author: sscoderati

apps/web/src/routes/reports.tsx

@@ -7,7 +7,6 @@ import { createFileRoute, redirect } from '@tanstack/react-router'
 import {
   ArrowDown,
   ArrowUp,
-  BarChart2,
   Building2,
   Check,
   ChevronLeft,
@@ -131,6 +130,22 @@ type CashFlow = {
   total: number
 }
 
+type InstallmentProgress = {
+  processedMonths: number
+  totalMonths: number
+  progressRate: number
+}
+
+type InstallmentSummary = {
+  id: number
+  accountId: number
+  totalAmount: number
+  totalMonths: number
+  monthlyAmount: number
+  memo: string | null
+  progress: InstallmentProgress
+}
+
 type BalanceReport = {
   summary: {
     totalAssets: number
@@ -311,7 +326,15 @@ function NetAssetCard({ summary }: { summary: BalanceReport['summary'] }) {
   )
 }
 
-function AccountGroupSection({ group, type }: { group: AccountGroup; type: 'asset' | 'liability' }) {
+function AccountGroupSection({
+  group,
+  type,
+  installmentsByAccount,
+}: {
+  group: AccountGroup
+  type: 'asset' | 'liability'
+  installmentsByAccount?: Map<number, InstallmentSummary[]>
+}) {
   const [expanded, setExpanded] = useState(true)
   const isAsset = type === 'asset'
   const panelId = `group-panel-${type}-${group.major}`
@@ -331,14 +354,33 @@ function AccountGroupSection({ group, type }: { group: AccountGroup; type: 'asse
         </span>
       </button>
       <div id={panelId} hidden={!expanded} className="divide-y">
-        {group.accounts.map((account) => (
-          <div key={account.id} className="flex items-center justify-between px-4 py-2.5">
-            <span className="text-sm text-foreground">{account.name}</span>
-            <span className={cn('text-sm font-medium', isAsset ? 'text-foreground' : 'text-red-500')}>
-              {formatAmount(account.balance)}
-            </span>
-          </div>
-        ))}
+        {group.accounts.map((account) => {
+          const linkedInstallments = isAsset ? [] : (installmentsByAccount?.get(account.id) ?? [])
+
+          return (
+            <div key={account.id} className="flex items-start justify-between gap-3 px-4 py-2.5">
+              <div className="flex min-w-0 flex-col gap-1">
+                <span className="text-sm text-foreground">{account.name}</span>
+                {linkedInstallments.map((installment) => {
+                  const remainingMonths = Math.max(
+                    installment.totalMonths - installment.progress.processedMonths,
+                    0,
+                  )
+                  const installmentName = installment.memo?.trim() || `할부 #${installment.id}`
+
+                  return (
+                    <span key={installment.id} className="text-xs text-muted-foreground">
+                      {installmentName} · 잔여 {remainingMonths}개월 · 월 {formatAmount(installment.monthlyAmount)}
+                    </span>
+                  )
+                })}
+              </div>
+              <span className={cn('text-sm font-medium', isAsset ? 'text-foreground' : 'text-red-500')}>
+                {formatAmount(account.balance)}
+              </span>
+            </div>
+          )
+        })}
       </div>
     </div>
   )
@@ -389,6 +431,7 @@ function CashFlowCard({ cashFlow }: { cashFlow: CashFlow }) {
 
 function BalanceTab({ ledgerId }: { ledgerId: number }) {
   const [report, setReport] = useState<BalanceReport | null>(null)
+  const [installmentsByAccount, setInstallmentsByAccount] = useState<Map<number, InstallmentSummary[]>>(new Map())
   const [loading, setLoading] = useState(true)
   const [error, setError] = useState<string | null>(null)
 
@@ -398,15 +441,15 @@ function BalanceTab({ ledgerId }: { ledgerId: number }) {
     setError(null)
 
     apiFetch(`/api/ledgers/${ledgerId}/reports/balance`)
-      .then(async (res) => {
+      .then(async (balanceRes) => {
         let json: unknown = null
         try {
-          json = await res.json()
+          json = await balanceRes.json()
         } catch {
           // 응답 본문이 JSON이 아닌 경우 json은 null로 유지
         }
 
-        if (!res.ok) {
+        if (!balanceRes.ok) {
           let message = '잔고 데이터를 불러오지 못했습니다.'
           if (json && typeof json === 'object') {
             const anyJson = json as { error?: { message?: unknown }; message?: unknown }
@@ -423,7 +466,55 @@ function BalanceTab({ ledgerId }: { ledgerId: number }) {
           json && typeof json === 'object' && 'data' in json
             ? (json as { data: BalanceReport }).data
             : (json as BalanceReport)
-        if (!cancelled) setReport(data)
+        if (!cancelled) {
+          setReport(data)
+        }
+
+        let installmentsRes: Response | null = null
+        try {
+          installmentsRes = await apiFetch(`/api/ledgers/${ledgerId}/installments`)
+        } catch {
+          installmentsRes = null
+        }
+
+        if (!installmentsRes || !installmentsRes.ok) {
+          if (!cancelled) {
+            setInstallmentsByAccount(new Map())
+          }
+          return
+        }
+
+        let installmentsPayload: { data?: InstallmentSummary[] } | InstallmentSummary[] = []
+        try {
+          installmentsPayload = (await installmentsRes.json()) as
+            | { data?: InstallmentSummary[] }
+            | InstallmentSummary[]
+        } catch {
+          installmentsPayload = []
+        }
+        const installments = Array.isArray(installmentsPayload)
+          ? installmentsPayload
+          : (installmentsPayload.data ?? [])
+        const nextInstallmentsByAccount = new Map<number, InstallmentSummary[]>()
+
+        for (const installment of installments) {
+          const remainingMonths = Math.max(
+            installment.totalMonths - installment.progress.processedMonths,
+            0,
+          )
+          if (remainingMonths <= 0) continue
+
+          const existing = nextInstallmentsByAccount.get(installment.accountId)
+          if (existing) {
+            existing.push(installment)
+          } else {
+            nextInstallmentsByAccount.set(installment.accountId, [installment])
+          }
+        }
+
+        if (!cancelled) {
+          setInstallmentsByAccount(nextInstallmentsByAccount)
+        }
       })
       .catch((err: Error) => {
         if (!cancelled) setError(err.message)
@@ -497,7 +588,12 @@ function BalanceTab({ ledgerId }: { ledgerId: number }) {
           <h2 className="text-xs font-semibold text-muted-foreground uppercase tracking-wide mb-2 px-0.5">부채</h2>
           <div className="space-y-2">
             {report.liabilityGroups.map((group) => (
-              <AccountGroupSection key={group.major} group={group} type="liability" />
+              <AccountGroupSection
+                key={group.major}
+                group={group}
+                type="liability"
+                installmentsByAccount={installmentsByAccount}
+              />
             ))}
           </div>
         </section>

apps/web/src/routes/transactions.tsx

@@ -2,7 +2,7 @@ import { EmptyState } from '@repo/ui/components/ui/empty-state'
 import { Button } from '@repo/ui/components/ui/button'
 import { MonthPickerSheet } from '@repo/ui/components/ui/month-picker-sheet'
 import { showErrorSnackbar, showSuccessSnackbar, showUndoSnackbar } from '@repo/ui/components/ui/snackbar'
-import { createFileRoute, redirect } from '@tanstack/react-router'
+import { Link, createFileRoute, redirect } from '@tanstack/react-router'
 import {
   CalendarDays,
   ChevronLeft,
@@ -59,6 +59,19 @@ type Schedule = {
   templateAccountInId: number | null
   templateAccountOutId: number | null
 }
+type Installment = {
+  id: number
+  accountId: number
+  totalAmount: number
+  totalMonths: number
+  monthlyAmount: number
+  memo: string | null
+  progress: {
+    processedMonths: number
+    totalMonths: number
+    progressRate: number
+  }
+}
 type ResolvedSchedule = Schedule & {
   resolvedDate: string
 }
@@ -180,6 +193,7 @@ function TransactionsPage() {
   const [categories, setCategories] = useState<Category[]>([])
   const [accounts, setAccounts] = useState<Account[]>([])
   const [schedules, setSchedules] = useState<Schedule[]>([])
+  const [installments, setInstallments] = useState<Installment[]>([])
   const [recentCategories, setRecentCategories] = useState<Category[]>([])
 
   const goPrevMonth = () => {
@@ -239,6 +253,23 @@ function TransactionsPage() {
       const payload = (await schedulesRes.json()) as { data?: Schedule[] } | Schedule[]
       setSchedules(Array.isArray(payload) ? payload : (payload.data ?? []))
     }
+
+    try {
+      const installmentsRes = await apiFetch(`/api/ledgers/${ledgerId}/installments`)
+      if (!installmentsRes.ok) {
+        setInstallments([])
+        return
+      }
+
+      try {
+        const payload = (await installmentsRes.json()) as { data?: Installment[] } | Installment[]
+        setInstallments(Array.isArray(payload) ? payload : (payload.data ?? []))
+      } catch {
+        setInstallments([])
+      }
+    } catch {
+      setInstallments([])
+    }
   }, [ledgerId])
 
   const fetchTransactions = useCallback(async () => {
@@ -520,6 +551,7 @@ function TransactionsPage() {
   const monthLabel = `${selectedYear}년 ${selectedMonth}월`
   const categoryOptions = categories.filter((item) => item.type === tab)
   const accountNameById = useMemo(() => new Map(accounts.map((a) => [a.id, a.name])), [accounts])
+  const installmentById = useMemo(() => new Map(installments.map((item) => [item.id, item])), [installments])
   const categoryNameById = useMemo(
     () => new Map(categories.map((c) => [c.id, `${c.major} · ${c.minor}`])),
     [categories],
@@ -1633,6 +1665,10 @@ function TransactionsPage() {
         const categoryName = tx.categoryId
           ? (categoryNameById.get(tx.categoryId) ?? (hasCategoriesLoaded ? '(삭제됨)' : '(불러오는 중)'))
           : null
+        const linkedInstallment = tx.installmentId ? (installmentById.get(tx.installmentId) ?? null) : null
+        const remainingInstallmentMonths = linkedInstallment
+          ? Math.max(linkedInstallment.totalMonths - linkedInstallment.progress.processedMonths, 0)
+          : null
 
         return (
           <div
@@ -1723,7 +1759,22 @@ function TransactionsPage() {
 
                 {tx.installmentId ? (
                   <div className="rounded-md border border-amber-300 bg-amber-50 px-3 py-2 text-xs text-amber-900">
-                    할부 연결 거래입니다. 개별 삭제는 불가하며, 설정 &gt; 할부에서 관리할 수 있습니다.
+                    <p className="font-medium">할부 연결 거래입니다.</p>
+                    {linkedInstallment ? (
+                      <Link
+                        to="/settings"
+                        onClick={() => setDetailTransaction(null)}
+                        className="mt-1 inline-flex text-xs font-medium text-amber-950 underline underline-offset-2"
+                      >
+                        원본 할부 정보: 총액 {Number(linkedInstallment.totalAmount).toLocaleString()}원 · 잔여{' '}
+                        {remainingInstallmentMonths}개월
+                      </Link>
+                    ) : (
+                      <span className="mt-1 inline-flex text-xs">
+                        원본 할부 정보를 불러올 수 없습니다.
+                      </span>
+                    )}
+                    <p className="mt-1">개별 삭제는 불가하며, 설정 &gt; 할부에서 관리할 수 있습니다.</p>
                   </div>
                 ) : null}
               </div>

memories/task.md

@@ -480,9 +480,10 @@
 - **의존성:** 1-8, 3-7
 
 ### [3-9] 잔고 현황 할부 연동
-- **상태:** 대기
+- **상태:** 완료
 - **범위:** `apps/web`
 - **설명:** 잔고 현황 부채 목록에서 할부 연결된 계좌에 잔여 개월 + 월 상환액 표시. 거래 상세에서 할부 연결 거래에 원본 할부 정보 링크(총액, 잔여 개월).
+- **진행 메모 (2026-03-31):** `apps/web/src/routes/reports.tsx`에서 잔고 탭 조회 시 할부 API를 함께 호출해 부채 계좌별 활성 할부의 `잔여 개월 · 월 상환액`을 노출하도록 반영. `apps/web/src/routes/transactions.tsx` 거래 상세에서 할부 연결 거래에 원본 할부 정보 링크(총액, 잔여 개월)를 추가.
 - **참조:** screen-design §6-10, §6-7
 - **완료 조건:**
   - 부채 목록에 할부 잔여 개월·월 상환액 표시