Fix API compatibility and add user/role/permission and asset import/export
This commit is contained in:
284
backend/README.md
Normal file
284
backend/README.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# 资产管理系统 - 后端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
|
||||
Reference in New Issue
Block a user