# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

个人记账 Web 应用（"记账助手"），前后端分离架构。用于日常收支记录、分类管理、统计分析和余额追踪。

## 技术栈

- **前端 (client/)**: Vue 3 + Composition API + Vite 5, Element Plus (中文 locale), Pinia 状态管理, Vue Router 4, ECharts 图表, Axios HTTP 客户端
- **后端 (server/)**: Express 4 (Node.js), sql.js (内存 SQLite，文件持久化到 `server/data/accounting.db`)
- **无 TypeScript，无 ESLint，无测试框架**

## 常用命令

```bash
# 安装所有依赖（首次）
npm run install:all

# 同时启动前后端开发服务器
npm run dev

# 仅启动后端 (端口 3000)
npm run dev:server

# 仅启动前端 (端口 5173，API 代理到 3000)
npm run dev:client

# 前端构建
cd client && npm run build
```

## 架构

```
记账/
  package.json          # 根 monorepo 脚本 (concurrently)
  client/               # Vue 3 前端
    src/
      api/index.js      # Axios 封装，全部 API 在此定义
      router/index.js   # 三个路由: / (总览), /input (记账), /statistics (统计)
      stores/            # Pinia stores
        records.js       # 记录 CRUD + 分类列表
        statistics.js    # 统计数据 + 余额
      views/             # 页面组件 (Dashboard, DailyInput, Statistics)
      components/        # UI 组件 (Navbar, RecordForm, RecordTable, BalanceCard, SummaryCards, TrendChart, CategoryPieChart)
      styles/global.css  # 全局样式（卡片、颜色变量、等宽数字）
    vite.config.js       # 开发代理 /api -> :3000, 手动 chunk 分包
  server/               # Express 后端
    index.js            # 服务入口，挂载路由和静态文件
    db.js               # sql.js 初始化、表结构定义、DbWrapper 封装
    routes/
      records.js        # CRUD /api/records (按日期/月份查询，分页)
      categories.js     # CRUD /api/categories (删除时检查关联记录)
      statistics.js     # /api/statistics/daily|weekly|monthly|yearly|balance|trend
      balance.js        # /api/balance GET/PUT (初始余额设置)
    data/               # SQLite 数据库文件存放目录 (gitignore)
```

## 数据模型

三张表，定义在 `server/db.js`:

- **categories**: id, name (UNIQUE), type ('income'|'expense'), icon, sort_order -- 预置 15 个分类
- **records**: id, date (TEXT, YYYY-MM-DD), type, category_id (FK), amount, note, created_at, updated_at -- 按 date 和 type 有索引
- **balance_settings**: id=1 单行, initial_balance -- 用于计算当前余额

余额计算公式: `current_balance = initial_balance + SUM(income) - SUM(expense)`

## 关键设计模式

- **sql.js 同步封装**: `DbWrapper` 类将 sql.js 的 prepare/step/getAsObject 模式封装为 `all()/get()/run()` 方法，每次写操作后自动 `saveDb()` 持久化到文件
- **API 响应拦截**: `client/src/api/index.js` 的 response interceptor 直接返回 `response.data`，所以 store 层拿到的就是数据本身
- **Vite 代理**: 开发时前端 `/api` 请求代理到后端 3000 端口；生产环境后端直接 serve `client/dist` 静态文件
- **手动 chunk 分包**: vite.config.js 中将 element-plus、echarts、vue 相关库分别打包

## 编码规范

- Vue 组件使用 `<script setup>` 语法
- 全局 CSS class 约定: `.card` (卡片容器), `.mono-number` (等宽数字), `.text-income` / `.text-expense` / `.text-balance` (语义颜色), `.page-section` (页面间距), `.gradient-card` (渐变背景)
- 后端路由均为 CommonJS (`require`/`module.exports`)
- 日期格式统一 `YYYY-MM-DD`，月份 `YYYY-MM`
- 金额字段为 `REAL` 类型，前端显示时 `.toFixed(2)`