README

README.md

@@ -0,0 +1,115 @@
+# 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 模式。