116 lines
3.2 KiB
Markdown
116 lines
3.2 KiB
Markdown
# Accounting App Backend
|
||
|
||
这是 Accounting App 的后端服务，基于 Go (Gin 框架) 开发。它提供 RESTful API，支持账户管理、交易记录、汇率同步、AI 记账等功能。
|
||
|
||
## 🛠️ 技术栈
|
||
|
||
* **语言**: Go 1.24+
|
||
* **Web 框架**: [Gin](https://github.com/gin-gonic/gin)
|
||
* **ORM**: [GORM](https://gorm.io/)
|
||
* **数据库**: MySQL 8.0+
|
||
* **缓存**: Redis 7.0+ (用于汇率缓存)
|
||
* **配置**: [godotenv](https://github.com/joho/godotenv)
|
||
* **PDF 生成**: [gofpdf](https://github.com/jung-kurt/gofpdf)
|
||
* **Excel 处理**: [excelize](https://github.com/xuri/excelize)
|
||
|
||
## 📂 目录结构
|
||
|
||
```
|
||
backend/
|
||
├── cmd/ # 应用程序入口
|
||
│ ├── server/ # 主 API 服务入口
|
||
│ └── migrate/ # 数据库迁移工具
|
||
├── internal/ # 内部业务逻辑 (不对外暴露)
|
||
│ ├── cache/ # 缓存相关代码 (Redis)
|
||
│ ├── config/ # 配置加载
|
||
│ ├── database/ # 数据库连接与初始化
|
||
│ ├── handler/ # HTTP 路由处理函数 (Controller)
|
||
│ ├── middleware/ # Gin 中间件
|
||
│ ├── models/ # 数据模型 (GORM struct)
|
||
│ ├── repository/ # 数据访问层 (DAO)
|
||
│ ├── router/ # 路由定义
|
||
│ └── service/ # 业务逻辑服务层
|
||
├── pkg/ # 通用包 (可被外部导入)
|
||
│ ├── api/ # API 响应结构定义
|
||
│ └── utils/ # 工具函数
|
||
└── database/
|
||
└── sql/ # SQL 脚本 (结构与初始数据)
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置要求
|
||
|
||
* Go 1.24+
|
||
* MySQL 8.0+
|
||
* Redis 7.0+ (可选，推荐启用以获得更好的汇率性能)
|
||
|
||
### 1. 配置环境变量
|
||
|
||
复制 `.env.example` 为 `.env` 并填写配置：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
关键配置项：
|
||
|
||
```ini
|
||
# 数据库配置
|
||
DB_HOST=localhost
|
||
DB_PORT=3306
|
||
DB_USER=root
|
||
DB_PASSWORD=your_password
|
||
DB_NAME=accounting_db
|
||
|
||
# Redis 配置 (可选)
|
||
REDIS_HOST=localhost
|
||
REDIS_PORT=6379
|
||
REDIS_PASSWORD=
|
||
|
||
# 外部 API (汇率)
|
||
YUN_API_URL=https://api.example.com
|
||
YUN_API_KEY=your_api_key
|
||
```
|
||
|
||
### 2. 数据库迁移
|
||
|
||
初始化数据库表结构：
|
||
|
||
```bash
|
||
go run cmd/migrate/main.go
|
||
```
|
||
|
||
### 3. 运行服务
|
||
|
||
启动后端服务器：
|
||
|
||
```bash
|
||
go run cmd/server/main.go
|
||
```
|
||
|
||
服务默认运行在 `http://localhost:8080`。
|
||
|
||
## ✨ 主要功能
|
||
|
||
* **账户管理**: 支持多币种账户、信用卡和普通账户。
|
||
* **交易记录**: 记录收入、支出和转账，支持批量导入。
|
||
* **多币种支持**: 实时汇率同步 (支持缓存策略)，支持多种国际货币。
|
||
* **AI 智能记账**: 基于 LLM 的自然语言记账功能 (语音/文本 -> 交易记录)。
|
||
* **统计报表**: 生成 Excel/PDF 格式的财务报表，支持按类别、时间统计。
|
||
* **自动分类**: 基于规则和历史数据的智能分类建议。
|
||
|
||
## 🧪 测试
|
||
|
||
运行所有单元测试：
|
||
|
||
```bash
|
||
go test ./...
|
||
```
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
* 确保 `internal/config` 中的配置结构与 `.env` 文件一致。
|
||
* 生产环境部署建议使用 `go build` 编译为二进制文件运行。
|
||
* Redis 连接失败时，汇率服务会自动降级为直接请求 API 模式。
|