# bill_app

**Repository Path**: nerokey/bill_app

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-01
- **Last Updated**: 2025-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Bill App - 智能记账应用

一个基于FastAPI和PostgreSQL的智能记账应用，支持AI对话式记账、多账本管理、分类管理等功能。

## 🚀 功能特性

- **用户认证系统**: JWT token认证，支持用户名/邮箱/手机号登录
- **智能记账**: 通过AI对话识别用户意图，自动分类和记录账单
- **多账本管理**: 支持创建多个账本，满足不同场景需求
- **分类管理**: 灵活的收支分类体系，支持多级分类
- **数据安全**: 密码加密存储，JWT token保护API接口
- **高性能**: 使用连接池和Snowflake ID生成器

## 🏗️ 技术架构

- **后端框架**: FastAPI (Python 3.11+)
- **数据库**: PostgreSQL 16
- **认证**: JWT + bcrypt
- **ID生成**: Snowflake算法
- **容器化**: Docker + Docker Compose
- **日志**: 结构化日志 + 文件轮转

## 📋 系统要求

- Python 3.11+
- PostgreSQL 16+
- Docker & Docker Compose (可选)

## 🛠️ 快速开始

### 使用Docker Compose (推荐)

1. 克隆项目
```bash
git clone <repository-url>
cd bill-app
```

2. 配置环境变量
```bash
cp env.example .env
# 编辑.env文件，修改必要的配置
```

3. 启动服务
```bash
docker-compose up -d
```

4. 访问应用
- API文档: http://localhost:8000/docs
- 健康检查: http://localhost:8000/health

### 本地开发

1. 安装依赖
```bash
pip install -r requirements.txt
```

2. 配置PostgreSQL数据库
```bash
# 创建数据库
createdb appdb
```

3. 配置环境变量
```bash
cp env.example .env
# 编辑.env文件
```

4. 启动应用
```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

## 📚 API文档

### 认证接口

- `POST /auth/register` - 用户注册
- `POST /auth/login` - 用户登录

### 用户接口

- `GET /api/v1/user/me` - 获取当前用户信息
- `POST /api/v1/user/change-password` - 修改密码

### 数据库表结构

- **users**: 用户信息表
- **bill_mates**: 账本表
- **categories**: 分类表
- **bill_items**: 账单项目表
- **chat_messages**: 对话消息表

## 🔧 配置说明

主要配置项在`.env`文件中：

```env
# 应用配置
APP_NAME=bill-app
DEBUG=false
APP_HOST=0.0.0.0
APP_PORT=8000

# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=appdb

# JWT配置
JWT_SECRET=your-secret-key
JWT_EXPIRE_MINUTES=30

# Snowflake ID配置
SNOWFLAKE_EPOCH_MS=1704067200000
SNOWFLAKE_MACHINE_ID=1
```

## 🧪 测试

```bash
# 运行测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=app --cov-report=html
```

## 📁 项目结构

```
bill-app/
├── app/
│   ├── api/           # API路由
│   │   └── v1/       # API版本1
│   ├── core/          # 核心模块
│   ├── models/        # 数据模型
│   ├── schemas/       # 数据验证
│   ├── services/      # 业务逻辑
│   └── main.py        # 应用入口
├── test/              # 测试文件
├── docker-compose.yml # Docker编排
├── Dockerfile         # Docker镜像
├── requirements.txt   # Python依赖
└── README.md         # 项目文档
```

## 🔒 安全特性

- JWT token认证
- 密码bcrypt加密
- API接口权限控制
- 中间件级别的安全验证

## 📝 开发计划

- [ ] 账单统计和分析功能
- [ ] 多用户账本共享
- [ ] 移动端API优化
- [ ] 数据导入导出
- [ ] 定时提醒功能

## 🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue
- 发送邮件
- 项目讨论区

---

**注意**: 这是一个开发中的项目，生产环境使用前请仔细测试和配置。