feat(ledger): CSV 내보내기 및 카테고리·결제수단 관리 UI 추가

- GET /api/ledger/entries/export — BOM 포함 UTF-8 CSV 내보내기 (Excel 호환)
- 카테고리·결제수단 관리 모달 추가 (탭 전환, 추가/삭제)
- LedgerView 헤더에 CSV 내보내기 버튼 및 관리 버튼 추가
- loadMeta useCallback으로 분리하여 관리 모달과 공유
- vite.config.ts: @fieldstack/* 패키지를 dist 대신 src 직접 참조로 변경
  (Vite export* 체인 캐싱 문제 해결, tsc 빌드 없이 즉시 반영)
- ledger.css: --fs-* 변수명을 실제 global.css 기준(--border, --text 등)으로 전면 교체
- CLAUDE.md: CSS 변수명 규칙 명시

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

Author: SOIV

CLAUDE.md

@@ -80,10 +80,29 @@ TypeScript 계약(`ControlDescriptor`, `CONTROL_DESCRIPTORS`)만 선언되어 
 
 ### 스타일
 
-- CSS 커스텀 프로퍼티 기반 다크 모드 디자인 토큰 (`apps/web/src/styles/`).
-- Primary `#3B82F6`, success `#10B981`, warning `#F59E0B`, danger `#EF4444`.
+- CSS 커스텀 프로퍼티 기반 다크 모드 디자인 토큰 (`apps/web/src/styles/global.css`).
 - 현재 Tailwind 미적용 (계획 중). 현재는 각 View별 CSS 파일 직접 작성.
 
+**CSS 변수명 — 반드시 `global.css` 기준을 사용할 것. `--fs-*` 접두사는 존재하지 않음.**
+
+| 용도 | 변수명 |
+|------|--------|
+| 배경 (기본) | `--bg` |
+| 배경 (카드/서피스) | `--bg-surface` |
+| 배경 (보조/elevated) | `--bg-elevated` |
+| 배경 (호버) | `--bg-hover` |
+| 테두리 | `--border` |
+| 테두리 (subtle) | `--border-subtle` |
+| 텍스트 (기본) | `--text` |
+| 텍스트 (보조) | `--text-muted` |
+| 텍스트 (희미) | `--text-faint` |
+| 강조색 | `--primary` / `--accent` |
+| 성공 | `--ok` |
+| 경고 | `--warn` |
+| 오류/위험 | `--err` |
+
+> ⚠️ `--fs-border`, `--fs-text-primary`, `--fs-bg-secondary` 등 `--fs-` 접두사 변수는 정의되어 있지 않아 항상 빈 값으로 처리됨. 절대 사용 금지.
+
 ---
 
 ## Code Conventions

apps/web/vite.config.ts

@@ -10,14 +10,17 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // alias로 각 export 경로를 명시한다.
 // 주의: 서브패스(controls/styles)를 베이스(controls)보다 먼저 선언해야
 //       prefix 매칭 순서가 올바르게 동작한다.
-const WEB_NODE_MODULES = path.resolve(__dirname, "node_modules");
+// 모노레포 내부 패키지는 dist 대신 src를 직접 참조한다.
+// Vite는 TypeScript를 네이티브로 처리하므로 빌드 단계가 불필요하고,
+// 소스 변경이 즉시 HMR에 반영되며 dist 캐싱 문제가 발생하지 않는다.
+const PACKAGES = path.resolve(__dirname, "../../packages");
 
 export default defineConfig({
   resolve: {
     alias: {
-      "@fieldstack/controls/styles": path.join(WEB_NODE_MODULES, "@fieldstack/controls/src/styles/index.css"),
-      "@fieldstack/controls": path.join(WEB_NODE_MODULES, "@fieldstack/controls/dist/index.js"),
-      "@fieldstack/core/browser": path.join(WEB_NODE_MODULES, "@fieldstack/core/dist/browser.js"),
+      "@fieldstack/controls/styles": path.join(PACKAGES, "controls/src/styles/index.css"),
+      "@fieldstack/controls": path.join(PACKAGES, "controls/src/index.ts"),
+      "@fieldstack/core/browser": path.join(PACKAGES, "core/src/browser.ts"),
     },
   },
   server: {

modules/ledger/backend/routes.ts

@@ -7,6 +7,7 @@ import {
   CreateEntrySchema,
   CreatePaymentMethodSchema,
   EntryListQuerySchema,
+  ExportQuerySchema,
   SummaryQuerySchema,
   UpdateEntrySchema,
   validateBody,
@@ -163,6 +164,31 @@ export function createLedgerRouter(
     }
   });
 
+  /** GET /api/ledger/entries/export?year=2026&month=4&type=expense */
+  router.get('/entries/export', auth, validateQuery(ExportQuerySchema), async (req, res) => {
+    try {
+      type Q = {
+        year?: number;
+        month?: number;
+        type?: 'income' | 'expense';
+        categoryId?: string;
+      };
+      const query = (req as Request & { validatedQuery: Q }).validatedQuery;
+      const csv = await service.exportEntriesCsv(req.auth!.userId, query);
+
+      const now = new Date();
+      const dateStr = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}`;
+      const filename = `ledger-${dateStr}.csv`;
+
+      res.setHeader('Content-Type', 'text/csv; charset=utf-8');
+      res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
+      // UTF-8 BOM — Excel에서 한글 깨짐 방지
+      res.send('\uFEFF' + csv);
+    } catch (err) {
+      res.status(500).json({ success: false, error: (err as Error).message });
+    }
+  });
+
   /** GET /api/ledger/entries/:id */
   router.get('/entries/:id', auth, async (req, res) => {
     try {

modules/ledger/backend/service.ts

@@ -349,6 +349,88 @@ export class LedgerService {
     return rows.length > 0;
   }
 
+  async exportEntriesCsv(
+    userId: string,
+    opts: {
+      year?: number;
+      month?: number;
+      type?: 'income' | 'expense';
+      categoryId?: string;
+    },
+  ): Promise<string> {
+    const conditions: string[] = ['e.user_id = $1'];
+    const params: unknown[] = [userId];
+    let idx = 2;
+
+    if (opts.year !== undefined && opts.month !== undefined) {
+      const from = `${opts.year}-${String(opts.month).padStart(2, '0')}-01`;
+      const toYear = opts.month === 12 ? opts.year + 1 : opts.year;
+      const toMonth = opts.month === 12 ? 1 : opts.month + 1;
+      const to = `${toYear}-${String(toMonth).padStart(2, '0')}-01`;
+      conditions.push(`e.date >= $${idx} AND e.date < $${idx + 1}`);
+      params.push(from, to);
+      idx += 2;
+    } else if (opts.year !== undefined) {
+      const from = `${opts.year}-01-01`;
+      const to = `${opts.year + 1}-01-01`;
+      conditions.push(`e.date >= $${idx} AND e.date < $${idx + 1}`);
+      params.push(from, to);
+      idx += 2;
+    }
+
+    if (opts.type) {
+      conditions.push(`e.type = $${idx}`);
+      params.push(opts.type);
+      idx++;
+    }
+
+    if (opts.categoryId) {
+      conditions.push(`e.category_id = $${idx}`);
+      params.push(opts.categoryId);
+    }
+
+    const where = conditions.join(' AND ');
+    const rows = await this.db.query<EntryRow>(
+      `SELECT
+         e.*,
+         c.name  AS category_name,
+         pm.name AS payment_method_name
+       FROM ledger_entries e
+       LEFT JOIN ledger_categories      c  ON c.id  = e.category_id
+       LEFT JOIN ledger_payment_methods pm ON pm.id = e.payment_method_id
+       WHERE ${where}
+       ORDER BY e.date DESC, e.created_at DESC`,
+      params,
+    );
+
+    const entries = rows.map(rowToEntry);
+
+    // CSV 헤더
+    const header = ['날짜', '유형', '금액', '카테고리', '내용', '결제수단', '메모', '태그'].join(',');
+
+    const escapeCell = (val: string | null | undefined): string => {
+      if (val == null) return '';
+      // 쉼표·큰따옴표·줄바꿈이 있으면 큰따옴표로 감싸기
+      if (/[",\n\r]/.test(val)) return `"${val.replace(/"/g, '""')}"`;
+      return val;
+    };
+
+    const lines = entries.map((e) =>
+      [
+        escapeCell(e.date),
+        escapeCell(e.type === 'income' ? '수입' : '지출'),
+        String(e.amount),
+        escapeCell(e.categoryName),
+        escapeCell(e.description),
+        escapeCell(e.paymentMethodName),
+        escapeCell(e.notes),
+        escapeCell(e.tags.join('|')),
+      ].join(','),
+    );
+
+    return [header, ...lines].join('\r\n');
+  }
+
   // ── 통계 ──────────────────────────────────────────────────────
 
   async getSummary(userId: string, year: number, month: number): Promise<LedgerSummary> {

modules/ledger/backend/validation.ts

@@ -48,6 +48,13 @@ export const SummaryQuerySchema = z.object({
   month: z.coerce.number().int().min(1).max(12),
 });
 
+export const ExportQuerySchema = z.object({
+  year: z.coerce.number().int().min(2000).max(2100).optional(),
+  month: z.coerce.number().int().min(1).max(12).optional(),
+  type: z.enum(['income', 'expense']).optional(),
+  categoryId: z.string().uuid().optional(),
+});
+
 // ── 미들웨어 헬퍼 ─────────────────────────────────────────────
 
 export function validateBody<T>(schema: z.ZodSchema<T>) {