85 lines
3.7 KiB
Markdown
85 lines
3.7 KiB
Markdown
|
# 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)`
|