# 资产管理系统 - 后端API

基于 FastAPI + SQLAlchemy + PostgreSQL 的企业级资产管理系统后端API

## 技术栈

- **框架**: FastAPI 0.104+
- **ORM**: SQLAlchemy 2.0+ (异步模式)
- **数据库**: PostgreSQL 14+
- **缓存**: Redis
- **认证**: JWT (python-jose)
- **密码加密**: bcrypt
- **数据验证**: Pydantic v2
- **数据库迁移**: Alembic
- **测试**: pytest
- **ASGI服务器**: Uvicorn

## 项目结构

```
asset_management_backend/
├── app/
│   ├── api/                    # API路由
│   │   └── v1/
│   │       ├── auth.py        # 认证相关API
│   │       └── __init__.py
│   ├── core/                   # 核心模块
│   │   ├── config.py          # 配置管理
│   │   ├── security.py        # 安全相关
│   │   ├── deps.py            # 依赖注入
│   │   ├── exceptions.py      # 自定义异常
│   │   └── response.py        # 统一响应
│   ├── crud/                   # 数据库CRUD操作
│   │   ├── user.py            # 用户CRUD
│   │   └── ...
│   ├── db/                     # 数据库相关
│   │   ├── base.py            # 模型基类
│   │   └── session.py         # 会话管理
│   ├── models/                 # SQLAlchemy模型
│   │   ├── user.py            # 用户模型
│   │   └── ...
│   ├── schemas/                # Pydantic Schema
│   │   ├── user.py            # 用户Schema
│   │   └── ...
│   ├── services/               # 业务逻辑层
│   │   ├── auth_service.py    # 认证服务
│   │   └── ...
│   └── utils/                  # 工具函数
│       └── ...
├── alembic/                    # 数据库迁移
│   └── versions/
├── tests/                      # 测试
├── logs/                       # 日志文件
├── uploads/                    # 上传文件
├── .env.example               # 环境变量示例
├── requirements.txt           # 依赖包
├── run.py                     # 开发服务器启动脚本
└── README.md                  # 项目说明
```

## 快速开始

### 1. 环境准备

确保已安装：
- Python 3.10+
- PostgreSQL 14+
- Redis

### 2. 安装依赖

```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖包
pip install -r requirements.txt
```

### 3. 配置环境变量

```bash
# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，配置数据库等信息
```

### 4. 初始化数据库

```bash
# 创建数据库
createdb asset_management

# 运行数据库迁移
alembic upgrade head

# 或在开发环境直接初始化（会自动创建表）
# 修改 app/main.py 中的 lifespan 函数，取消注释 init_db()
```

### 5. 启动服务

```bash
# 开发模式（支持热重载）
python run.py

# 或使用 uvicorn
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 6. 访问API文档

启动成功后，访问以下地址：

- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json

## API端点

### 认证模块

- `POST /api/v1/auth/login` - 用户登录
- `POST /api/v1/auth/refresh` - 刷新令牌
- `POST /api/v1/auth/logout` - 用户登出
- `PUT /api/v1/auth/change-password` - 修改密码
- `GET /api/v1/auth/captcha` - 获取验证码

### 用户管理

- `GET /api/v1/users` - 用户列表
- `POST /api/v1/users` - 创建用户
- `GET /api/v1/users/{user_id}` - 获取用户详情
- `PUT /api/v1/users/{user_id}` - 更新用户
- `DELETE /api/v1/users/{user_id}` - 删除用户
- `POST /api/v1/users/{user_id}/reset-password` - 重置密码
- `GET /api/v1/users/me` - 获取当前用户信息

### 角色权限

- `GET /api/v1/roles` - 角色列表
- `POST /api/v1/roles` - 创建角色
- `GET /api/v1/roles/{role_id}` - 获取角色详情
- `PUT /api/v1/roles/{role_id}` - 更新角色
- `DELETE /api/v1/roles/{role_id}` - 删除角色
- `GET /api/v1/permissions/tree` - 权限树列表

更多API请查看Swagger文档。

## 开发规范

请参考 `development_standards_guide.md` 文件。

### 代码风格

- 遵循 PEP 8 规范
- 使用 Black 进行代码格式化
- 使用 isort 管理导入
- 使用 flake8 进行代码检查
- 使用 mypy 进行类型检查

### 提交规范

遵循 Conventional Commits 规范：

```
feat: 新功能
fix: Bug修复
docs: 文档更新
style: 代码格式
refactor: 重构
perf: 性能优化
test: 测试
chore: 构建/工具
```

示例：
```bash
git commit -m "feat(auth): 实现用户登录功能"
git commit -m "fix(asset): 修复资产状态转换问题"
```

## 测试

```bash
# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/api/test_auth.py

# 生成覆盖率报告
pytest --cov=app --cov-report=html

# 查看覆盖率报告
open htmlcov/index.html
```

## 数据库迁移

```bash
# 创建新的迁移
alembic revision --autogenerate -m "描述信息"

# 执行迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1

# 查看迁移历史
alembic history

# 查看当前版本
alembic current
```

## 生产部署

### 使用 Docker

```bash
# 构建镜像
docker build -t asset-management-backend .

# 运行容器
docker run -d \
  --name asset-backend \
  -p 8000:8000 \
  --env-file .env \
  asset-management-backend
```

### 使用 Gunicorn + Uvicorn

```bash
pip install gunicorn

gunicorn app.main:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --access-logfile - \
  --error-logfile -
```

## 常见问题

### 数据库连接失败

检查 `DATABASE_URL` 是否正确配置，确保PostgreSQL服务正在运行。

### Redis连接失败

检查 `REDIS_URL` 是否正确配置，确保Redis服务正在运行。

### Token验证失败

确保 `SECRET_KEY` 配置正确，并检查Token是否过期。

## 贡献指南

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 许可证

本项目采用 MIT 许可证。

## 联系方式

- 项目负责人: 老王
- 创建时间: 2025-01-24
- 版本: v1.0.0