accountbook/SPEC.md

# 记账网站 - 技术规范

## 1. 项目概述

- **项目名称**: 简易记账本
- **项目类型**: Web 应用
- **核心功能**: 用户注册登录、记录收支、查看账目明细和统计
- **目标用户**: 个人用户，需要简单易用的记账工具

## 2. 技术栈

- **后端**: Node.js + Express
- **数据库**: SQLite (轻量级，无需额外安装)
- **前端**: Next.js 14 (React)
- **认证**: JWT Token

## 2.1 端口配置

| 服务 | 端口 | 启动命令 |
|------|------|----------|
| 前端 (Next.js) | 3500 | `cd frontend && npm run dev` |
| 后端 (Express API) | 3501 | `node server.js` |

> **注意**: 前端通过 Next.js 开发服务器的 API 代理访问后端，代理配置在 `frontend/next.config.js` 中

## 3. UI/UX 规范

### 3.1 布局结构

- **移动端优先设计**
- 顶部导航栏 (固定)
- 主要内容区域 (可滚动)
- 底部操作栏 (新增按钮)

### 3.2 视觉设计

**色彩方案**
- 主色: `#2563eb` (蓝色)
- 背景: `#f8fafc` (浅灰白)
- 卡片背景: `#ffffff`
- 文字主色: `#1e293b`
- 文字次色: `#64748b`
- 收入: `#10b981` (绿色)
- 支出: `#ef4444` (红色)
- 边框: `#e2e8f0`

**字体**
- 主字体: `"PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif`
- 数字字体: `"SF Mono", Monaco, monospace`

**间距系统**
- 基础单位: 4px
- 小间距: 8px
- 中间距: 16px
- 大间距: 24px

**圆角**
- 卡片: 12px
- 按钮: 8px
- 输入框: 8px

### 3.3 页面结构

**登录/注册页面**
- Logo + 标题
- 用户名输入框
- 密码输入框
- 登录/注册按钮
- 切换登录/注册链接

**主页面**
- 顶部: 月份选择 + 退出登录
- 概要卡片: 本月收入/支出/结余
- 账目列表: 按日期分组显示
- 底部: 新增按钮 (固定)

**新增账目弹窗**
- 类型切换 (收入/支出)
- 金额输入
- 分类选择
- 日期选择
- 备注输入
- 保存按钮

### 3.4 组件

**账目卡片**
- 左侧: 分类图标 + 描述
- 右侧: 金额 (收入绿色/支出红色)
- 点击可编辑/删除

**分类图标**
- 餐饮: 🍜
- 交通: 🚗
- 购物: 🛒
- 工资: 💰
- 其他: 📝

**动画效果**
- 页面切换: 淡入淡出 200ms
- 弹窗: 缩放进入 200ms
- 列表项: 滑入 150ms

## 4. 功能规范

### 4.1 用户系统

**注册**
- 用户名 (3-20字符，字母数字)
- 密码 (6-20字符)
- 用户名唯一性检查

**登录**
- 用户名 + 密码
- 返回 JWT Token
- Token 有效期 7 天

### 4.2 账目管理

**新增账目**
- 类型: 收入/支出
- 金额: 正数
- 分类: 预设分类
- 日期: 默认为今天
- 备注: 可选

**编辑账目**
- 可修改所有字段
- 删除账目

**查看账目**
- 按月份筛选
- 按类型筛选 (收入/支出/全部)
- 按日期倒序排列

### 4.3 数据统计

**月度统计**
- 本月总收入
- 本月总支出
- 本月结余

## 5. API 规范

### 认证接口
- `POST /api/auth/register` - 注册
- `POST /api/auth/login` - 登录

### 账目接口
- `GET /api/records` - 获取账目列表 (支持 month 参数)
- `POST /api/records` - 新增账目
- `PUT /api/records/:id` - 更新账目
- `DELETE /api/records/:id` - 删除账目
- `GET /api/stats` - 获取月度统计

## 6. 数据库设计

### users 表
```sql
CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  username TEXT UNIQUE NOT NULL,
  password TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

### records 表
```sql
CREATE TABLE records (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  user_id INTEGER NOT NULL,
  type TEXT NOT NULL CHECK(type IN ('income', 'expense')),
  amount REAL NOT NULL,
  category TEXT NOT NULL,
  date DATE NOT NULL,
  note TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id)
);
```

## 7. 验收标准

1. ✅ 用户可以注册新账号
2. ✅ 用户可以登录系统
3. ✅ 登录后可查看月度账目统计
4. ✅ 可以新增收入/支出记录
5. ✅ 可以编辑和删除记录
6. ✅ 移动端界面正常显示和操作
7. ✅ 通过 http://localhost:3500 访问前端

## 8. 快速启动

```bash
# 启动后端 (端口 3501)
cd /opt/accountbook
node server.js

# 启动前端 (端口 3500)
cd /opt/accountbook/frontend
npm run dev
```

访问 http://你的IP:3500

## 9. 项目结构

### 后端目录结构
```
server/
├── index.js              # 入口文件
├── config/
│   └── database.js       # 数据库配置
├── middleware/
│   ├── auth.js           # 认证中间件
│   └── errorHandler.js   # 错误处理
├── routes/
│   ├── auth.js           # 认证路由
│   ├── records.js        # 账目路由
│   ├── stats.js          # 统计路由
│   ├── recurring.js      # 周期性账单
│   ├── categories.js     # 分类路由
│   ├── export.js         # 导入导出
│   └── search.js         # 搜索路由
├── utils/
│   └── validators.js     # 验证函数
└── db/
    ├── migrations/       # 数据库迁移
    └── migrate.js        # 迁移脚本
```

### 前端优化
- 使用 SWR 进行数据获取和缓存
- 乐观更新支持
- 错误边界组件
- 统一加载状态

### 新增功能
- 数据库迁移系统 (`npm run migrate`)
- 结构化日志
- 统一错误处理
- API 请求验证
- 数据库索引优化