# 记账后端服务器

**Repository Path**: liao1230/accounting-backend-server

## Basic Information

- **Project Name**: 记账后端服务器
- **Description**: No description available
- **Primary Language**: Java
- **License**: AFL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 墨迹记账后端服务器

轻量级记账 API 服务，集成 Ollama 本地大模型，为「墨迹记账」App 提供完整的数据管理与 AI 能力。

[![FastAPI](https://img.shields.io/badge/FastAPI-0.141+-green.svg)](https://fastapi.tiangolo.com)
[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 功能概览

| 模块 | 功能 |
|------|------|
| 🔐 认证 | 手机号注册/登录、JWT Token、密码修改、忘记密码 |
| 📒 账单 | CRUD、云端同步、搜索、标签关联 |
| 📊 统计 | 月度汇总、分类统计、异常检测、AI 消费分析 |
| 💰 预算 | 分类预算、超支预警、进度追踪 |
| 🎯 目标 | 储蓄目标创建与管理 |
| 🔄 循环 | 月度/周度自动记账 |
| 🔔 提醒 | 定时提醒设置 |
| 🤖 AI | 本地 LLM（Ollama）消费分析、智能分类推荐 |
| 👤 管理后台 | 用户管理、账单管理、数据统计、系统备份 |
| 🏷️ 标签 | 自定义标签系统 |

---

## 技术栈

- **后端框架**: FastAPI + Uvicorn
- **数据库**: SQLite（WAL 模式，高并发优化）
- **认证**: JWT（7 天有效期）+ bcrypt 密码哈希
- **AI 引擎**: Ollama（qwen2.5:3b / qwen2.5:7b）
- **前端**: 原生 HTML/CSS/JS + Tailwind CSS

---

## 快速开始

### 环境要求

- Python 3.10+
- Ollama（可选，AI 功能需要）

### 安装

```bash
pip install -r requirements.txt
```

### 配置

复制环境变量模板并修改：

```bash
cp .env.example .env
# 编辑 .env，至少修改 JWT_SECRET_KEY 和 ADMIN_PASSWORD
```

### 启动服务

```bash
python run.py
```

或直接在终端运行：

```bash
python server.py
```

### 访问地址

| 地址 | 说明 |
|------|------|
| http://localhost:8000/docs | Swagger API 文档 |
| http://localhost:8000/health | 健康检查 |
| http://localhost:8000/admin.html | 管理后台（需前端文件） |

---

## 测试账号

| 角色 | 手机号 | 密码 |
|------|--------|------|
| 管理员 | 13800000001 | admin123 |

> ⚠️ 生产环境请务必修改默认管理员密码！

---

## 运行测试

```bash
python run_test.py
```

预期结果：`20 通过, 0 失败`

---

## API 接口速览

完整接口清单（93 个端点）见 [CHANGELOG.md](CHANGELOG.md)。

### 认证
```
POST /api/auth/register          # 用户注册
POST /api/auth/login             # 用户登录
GET  /api/auth/me                # 获取当前用户
POST /api/auth/refresh           # Token 刷新
PUT  /api/auth/password          # 修改密码
POST /api/auth/forgot-password/send    # 发送验证码
POST /api/auth/forgot-password/reset # 重置密码
```

### 账单
```
GET    /api/bills                 # 账单列表
POST   /api/bills                 # 创建账单
PUT    /api/bills/{cloud_id}      # 更新账单
DELETE /api/bills/{cloud_id}      # 删除账单
POST   /api/bills/sync/upload     # 同步上传
POST   /api/bills/sync/download   # 同步下载
GET    /api/bills/search          # 高级搜索
GET    /api/bills/export/csv      # CSV 导出
```

### 统计 & AI
```
GET  /api/stats/summary          # 月度汇总
GET  /api/stats/categories       # 分类统计
GET  /api/anomalies              # 异常检测
GET  /api/recommendations        # 智能推荐
POST /api/ai/analysis            # AI 消费分析
POST /api/bills/smart-category   # AI 智能分类
```

### 管理（需 admin 角色）
```
GET  /api/admin/bills             # 账单列表（分页）
GET  /api/admin/users             # 用户列表（分页）
POST /api/admin/backup            # 数据库备份
GET  /api/admin/stats/overview    # 统计概览
```

---

## 项目结构

```
D:/Bookkeeping_servers/
├── server.py          # 主程序（约 3000 行）
├── run.py             # 安全启动器（加载 .env）
├── run_test.py        # API 测试脚本
├── backup.py          # 数据库备份脚本
├── health_check.py    # 健康检查脚本
├── requirements.txt   # Python 依赖
├── pyproject.toml     # 项目元数据
├── .env               # 环境变量（不要提交到 Git）
├── .env.example       # 环境变量模板
├── .gitignore         # Git 忽略规则
├── bookkeeping.db     # SQLite 数据库
├── README.md          # 本文件
├── SECURITY.md        # 安全说明
├── CHANGELOG.md       # 版本历史 + 完整 API 清单 + 数据库表结构
└── LICENSE            # MIT 许可证
```

---

## 安全特性

- ✅ bcrypt 密码哈希（自动盐值）
- ✅ JWT Token 认证（7 天有效期 + 刷新机制）
- ✅ 全参数化 SQL 查询（防注入）
- ✅ XSS 防护（HTML/脚本清理）
- ✅ 登录频率限制（5 次/5 分钟）
- ✅ 注册频率限制（3 次/分钟）
- ✅ 安全响应头（X-Frame-Options 等）

详见 [SECURITY.md](SECURITY.md)

---

## 维护指南

### 数据库备份
```bash
python backup.py
# 或调用 API
curl -X POST http://localhost:8000/api/admin/backup \
  -H "Authorization: Bearer <token>"
```

### 查看日志
```bash
tail -f server.log
grep ERROR server.log
```

### 端口排查
```bash
netstat -ano | findstr :8000
taskkill //F //IM python.exe
```

---

## 许可证

MIT License — 详见 [LICENSE](LICENSE)