# grape_bookkeeping_python

**Repository Path**: fu-hehuang/grape_bookkeeping_python

## Basic Information

- **Project Name**: grape_bookkeeping_python
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# bookkeeping_python

`bookkeeping_python` 是将原有 `bookkeeping` Spring Boot 项目重构为 Python 版本的记账应用后端，采用 FastAPI 框架实现。

## 项目概述

这是一个完整的记账应用后端服务，提供账本管理、账户管理、账单记录、收支统计、会员系统等核心功能。支持用户名密码登录、手机验证码登录、PC 端扫码登录等多种认证方式，并预留了 AI 智能记账助手接口。

## 技术栈

| 分类 | 技术选型 | 说明 |
|------|---------|------|
| Web 框架 | FastAPI | 高性能异步 API 框架，自动生成 OpenAPI 文档 |
| ORM | SQLAlchemy 2.0 | 支持 SQLite/MySQL 等多种数据库 |
| 数据验证 | Pydantic | 请求参数校验，类型提示 |
| 缓存 | Redis / 内存 | 会话存储，支持降级到内存缓存 |
| 认证 | Token + bcrypt | UUID Token 认证，bcrypt 密码加密 |
| 部署 | Uvicorn | ASGI 服务器，支持热重载 |

## 目录结构

```
bookkeeping_python/
├─ app/
│  ├─ api/              # API 路由层
│  │  ├─ deps.py         # 依赖注入（获取当前用户、权限验证）
│  │  ├─ open.py         # 开放接口（登录、验证码、扫码登录）
│  │  ├─ system.py       # 系统管理（用户、角色、菜单、字典）
│  │  ├─ account.py      # 账务管理（账本、账户、分类、账单）
│  │  └─ member.py        # 会员管理
│  │
│  ├─ core/              # 核心模块
│  │  ├─ config.py       # 配置管理，从环境变量读取
│  │  ├─ constants.py    # 业务常量定义
│  │  ├─ database.py     # 数据库连接配置
│  │  ├─ exceptions.py   # 自定义异常和全局处理器
│  │  ├─ redis_client.py # Redis 缓存封装（支持内存降级）
│  │  ├─ response.py     # 统一 API 响应格式
│  │  └─ security.py      # 安全工具（Token、密码哈希）
│  │
│  ├─ models/            # 数据模型层
│  │  ├─ base.py         # 模型基类（ID生成、审计字段、软删除）
│  │  ├─ system.py       # 系统模型（用户、角色、权限、菜单）
│  │  ├─ account.py      # 账务模型（账本、账户、分类、账单）
│  │  └─ member.py        # 会员模型
│  │
│  ├─ schemas/           # Pydantic 数据模型
│  │  ├─ common.py       # 通用模型（分页参数/结果）
│  │  ├─ auth.py         # 认证相关（登录请求、会话用户）
│  │  ├─ system.py       # 系统相关（用户、角色更新等）
│  │  ├─ account.py      # 账务相关（账本、账单等）
│  │  └─ member.py        # 会员相关
│  │
│  ├─ services/          # 业务逻辑层
│  │  ├─ base.py         # CRUD 基础服务
│  │  ├─ auth.py         # 认证服务（登录、登出、Token管理）
│  │  ├─ system.py       # 系统服务（用户、角色、菜单管理）
│  │  ├─ account.py      # 账务服务（账本、账单、统计）
│  │  └─ member.py        # 会员服务
│  │
│  ├─ tasks/             # 定时任务预留目录
│  │
│  ├─ utils/            # 工具函数
│  │  ├─ bill.py         # 账单时间字段填充
│  │  ├─ pagination.py   # 分页查询工具
│  │  └─ serializers.py   # 数据序列化（模型转字典）
│  │
│  └─ main.py           # FastAPI 应用创建和配置
│
├─ main.py               # 应用入口文件
├─ pyproject.toml        # 项目依赖定义
├─ requirements.txt      # Python 依赖
├─ .env.example          # 环境变量示例
└─ test_main.http        # 接口测试脚本
```

## 模块说明

### API 层 (api/)

API 层负责定义 HTTP 接口路由，使用 FastAPI 的路径装饰器注册接口。

| 文件 | 功能 | 说明 |
|------|------|------|
| `deps.py` | 依赖注入 | `get_current_auth_context` 获取当前用户，`require_admin` 权限验证 |
| `open.py` | 开放接口 | 登录、验证码、扫码登录，无需认证即可访问 |
| `system.py` | 系统管理 | 用户、角色、权限、菜单、字典、通知、反馈管理 |
| `account.py` | 账务管理 | 账本、账户、分类、账单、自动记账、AI助手 |
| `member.py` | 会员管理 | 会员开通、等级定价、充值记录 |

### Core 层 (core/)

核心模块提供基础设施支持。

| 文件 | 功能 | 说明 |
|------|------|------|
| `config.py` | 配置管理 | 统一配置，支持 .env 文件加载 |
| `constants.py` | 业务常量 | 删除标记、用户状态、分类类型等 |
| `database.py` | 数据库 | SQLAlchemy 连接配置，会话管理 |
| `exceptions.py` | 异常处理 | 自定义异常，全局异常处理器 |
| `redis_client.py` | 缓存 | Redis 封装，支持内存降级 |
| `response.py` | 响应格式 | 统一 JSON 响应结构 |
| `security.py` | 安全工具 | Token生成、密码哈希、认证头解析 |

### Models 层 (models/)

数据模型定义数据库表结构。

| 模型 | 说明 |
|------|------|
| `SysUser` | 系统用户 |
| `SysRole` | 角色 |
| `SysPermission` | 权限点 |
| `SysMenu` | 菜单 |
| `SysDict/SysDictItem` | 字典 |
| `AccountBook` | 账本 |
| `Account` | 账户 |
| `Category` | 分类 |
| `Bill` | 账单 |
| `AutoAccountingConfig` | 自动记账配置 |
| `Member` | 会员 |
| `MemberGradePrice` | 会员等级定价 |

### Services 层 (services/)

业务逻辑层，处理核心业务规则。

| 服务 | 功能 |
|------|------|
| `AuthService` | 登录、登出、Token管理、二维码登录 |
| `UserService` | 用户CRUD、首页统计、记账指标 |
| `AccountBookService` | 账本管理（创建、删除、级联删除） |
| `AccountService` | 账户管理、余额同步 |
| `CategoryService` | 分类管理、预算统计 |
| `BillService` | 账单CRUD、每日分组、月份统计、年度报告 |
| `AutoAccountingConfigService` | 自动记账配置和执行 |
| `AiService` | AI 意图识别、记账创建、统计查询 |

## 环境准备

### 1. Python 环境

推荐使用 Python 3.11 或 3.12。

```bash
# 创建虚拟环境（可选）
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate  # Windows
```

### 2. 安装依赖

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

### 3. 配置环境变量

复制 `.env.example` 为 `.env`，根据需要修改配置：

```env
# 应用配置
APP_NAME=bookkeeping_python
APP_ENV=dev
APP_DEBUG=true
APP_PORT=20000

# 数据库配置（支持 SQLite 和 MySQL）
# 开发模式使用 SQLite，无需安装数据库
DATABASE_URL=sqlite:///./bookkeeping_python.db

# 生产模式使用 MySQL
# DATABASE_URL=mysql+pymysql://user:password@localhost:3306/bookkeeping

# Redis 配置（开发模式可使用内存缓存）
REDIS_URL=memory://
# REDIS_URL=redis://localhost:6379/0

# 会话配置
SESSION_TTL_SECONDS=2629800

# 上传配置
UPLOAD_DIR=./uploads
DEFAULT_AVATAR=

# CORS 配置
CORS_ORIGINS=*

# 默认管理员账号
DEFAULT_ADMIN_USERNAME=admin
DEFAULT_ADMIN_PHONE=15666666661
DEFAULT_ADMIN_PASSWORD=admin123456

# AI 功能（可选）
AI_ENABLED=false
AI_API_KEY=
AI_BASE_URL=
AI_MODEL=

# 自动记账
ENABLE_SCHEDULER=true
```

### 4. 启动服务

```bash
# 开发模式（热重载）
uvicorn main:app --reload --host 0.0.0.0 --port 20000

# 生产模式
uvicorn main:app --host 0.0.0.0 --port 20000 --workers 4
```

## 接口文档

启动服务后访问：

- Swagger UI: http://127.0.0.1:20000/doc.html
- OpenAPI JSON: http://127.0.0.1:20000/openapi.json

## 快速开始（SQLite 模式）

如果只想快速体验接口，可以用 SQLite 模式，无需安装 MySQL 和 Redis：

1. 设置环境变量：

```bash
export DATABASE_URL=sqlite:///./bookkeeping_python.db
export REDIS_URL=memory://
export AUTO_CREATE_TABLES=true
```

2. 启动服务：

```bash
uvicorn main:app --reload --port 20000
```

3. 访问接口文档开始测试。

## 接口列表

### 开放接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/opens/test` | GET | 服务健康检查 |
| `/opens/captcha` | GET | 获取图形验证码 |
| `/opens/login` | POST | 用户名密码登录 |
| `/opens/loginForPc` | POST | PC端登录 |
| `/opens/loginByCode` | POST | 手机验证码登录 |
| `/opens/sendCode` | POST | 发送短信验证码 |
| `/opens/qrLogins/create` | GET | 创建扫码登录二维码 |
| `/opens/qrLogins/status` | GET | 查询扫码登录状态 |

### 账务接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/accountBooks` | GET/POST | 账本列表/创建 |
| `/accountBooks/{id}` | PUT/DELETE | 更新/删除账本 |
| `/accounts` | GET/POST | 账户列表/创建 |
| `/accounts/statistic` | GET | 账户资产统计 |
| `/categories` | GET/POST | 分类列表/创建 |
| `/categories/statisticBudget` | GET | 分类预算统计 |
| `/bills` | GET/POST | 账单列表/创建 |
| `/bills/getDailyList` | POST | 按日分组账单 |
| `/bills/getCurrentMonthStatistical` | GET | 当月收支统计 |
| `/bills/statisticMonthChart` | GET | 月份趋势图表 |
| `/bills/statisticByYearMonth` | POST | 按年月分类统计 |
| `/bills/annualReport` | GET | 年度收支报告 |
| `/autoAccountingConfigs` | GET/POST | 自动记账配置 |
| `/ai/chat` | POST | AI 聊天记账 |

### 系统接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/users` | GET/POST | 用户列表/创建 |
| `/users/logout` | POST | 退出登录 |
| `/users/updateAvatar` | POST | 更新头像 |
| `/users/getIndexData` | GET | 首页统计数据 |
| `/roles` | GET/POST | 角色管理 |
| `/permissions` | GET/POST | 权限管理 |
| `/menus` | GET/POST | 菜单管理 |
| `/menus/getMenuByUserId` | GET | 获取用户菜单 |
| `/dicts` | GET/POST | 字典管理 |
| `/notifications` | GET | 通知列表 |
| `/notifications/markAsRead` | POST | 标记已读 |
| `/feedbacks` | GET/POST | 反馈管理 |

## 与原 Java 项目对应关系

| Java 模块 | Python 文件 |
|----------|------------|
| `com.grape.opens` | `app/api/open.py` |
| `com.grape.account` | `app/api/account.py` |
| `com.grape.system` | `app/api/system.py` |
| `com.grape.member` | `app/api/member.py` |

数据库模型参考：
- `bookkeeping/src/main/resources/db/migration/tables.sql`
- `bookkeeping/file/grape_bookkeeping.sql`

## 后续计划

- [ ] WebSocket 实时通信
- [ ] 完整数据库迁移脚本与种子数据
- [ ] 生产级权限细粒度拦截
- [ ] 完整的 AI 提示词工程
- [ ] 监控模块迁移
- [ ] 单元测试和集成测试

## 注意事项

1. **代码注释**：所有 Python 代码都添加了详细的中文注释，解释了每个函数和类的用途、实现逻辑。

2. **软删除机制**：系统使用软删除（`del_flag` 字段），删除操作不会物理删除数据。

3. **数据隔离**：用户只能访问自己的数据，服务层会自动添加 `user_id` 筛选条件。

4. **AI 功能**：AI 模块目前支持本地启发式解析，可选接入 OpenAI 兼容 API。

5. **生产部署**：生产环境建议使用 MySQL + Redis，并配置反向代理（Nginx）。