214 lines
3.9 KiB
Markdown
214 lines
3.9 KiB
Markdown
# 资产管理系统后端开发文档
|
||
|
||
## 项目进度追踪
|
||
|
||
### Phase 1: 基础框架 ✅ (已完成)
|
||
- [x] 项目结构搭建
|
||
- [x] 统一响应封装 (app/core/response.py)
|
||
- [x] 异常处理中间件 (app/core/exceptions.py)
|
||
- [x] JWT认证服务 (app/core/security.py)
|
||
- [x] 数据库连接和Session管理 (app/db/session.py)
|
||
- [x] 依赖注入系统 (app/core/deps.py)
|
||
|
||
### Phase 2: 认证与用户管理 🚧 (进行中)
|
||
- [x] 认证模块API (app/api/v1/auth.py)
|
||
- [x] 用户管理模型 (app/models/user.py)
|
||
- [x] 用户管理Schema (app/schemas/user.py)
|
||
- [x] 用户CRUD操作 (app/crud/user.py)
|
||
- [x] 认证服务 (app/services/auth_service.py)
|
||
- [ ] 用户管理API
|
||
- [ ] 角色权限API
|
||
- [ ] RBAC权限控制中间件
|
||
|
||
### Phase 3-7: 待开发
|
||
- Phase 3: 基础数据管理
|
||
- Phase 4: 资产管理核心
|
||
- Phase 5: 资产分配
|
||
- Phase 6: 维修与统计
|
||
- Phase 7: 系统管理
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 文件
|
||
```
|
||
|
||
### 3. 初始化数据库
|
||
|
||
```bash
|
||
# 方式1: 使用 Alembic (推荐)
|
||
alembic upgrade head
|
||
|
||
# 方式2: 开发环境自动初始化
|
||
# 已在 app/main.py 的 lifespan 中实现
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
```bash
|
||
python run.py
|
||
```
|
||
|
||
### 5. 访问API文档
|
||
|
||
http://localhost:8000/docs
|
||
|
||
## 开发指南
|
||
|
||
### 添加新的API端点
|
||
|
||
1. 在 `app/models/` 中定义数据模型
|
||
2. 在 `app/schemas/` 中定义Pydantic Schema
|
||
3. 在 `app/crud/` 中实现CRUD操作
|
||
4. 在 `app/services/` 中实现业务逻辑
|
||
5. 在 `app/api/v1/` 中创建路由
|
||
|
||
示例：
|
||
|
||
```python
|
||
# app/api/v1/assets.py
|
||
from fastapi import APIRouter, Depends
|
||
from app.core.deps import get_db, get_current_user
|
||
from app.schemas.asset import AssetCreate, AssetResponse
|
||
from app.services.asset_service import asset_service
|
||
|
||
router = APIRouter()
|
||
|
||
@router.get("/")
|
||
async def get_assets(
|
||
skip: int = 0,
|
||
limit: int = 20,
|
||
db: AsyncSession = Depends(get_db),
|
||
current_user = Depends(get_current_user)
|
||
):
|
||
"""获取资产列表"""
|
||
items, total = await asset_service.get_assets(db, skip, limit)
|
||
return success_response(data={"items": items, "total": total})
|
||
```
|
||
|
||
### 数据库迁移
|
||
|
||
```bash
|
||
# 创建迁移
|
||
alembic revision --autogenerate -m "描述"
|
||
|
||
# 执行迁移
|
||
alembic upgrade head
|
||
|
||
# 回滚
|
||
alembic downgrade -1
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 所有测试
|
||
pytest
|
||
|
||
# 特定测试文件
|
||
pytest tests/api/test_auth.py
|
||
|
||
# 带覆盖率
|
||
pytest --cov=app --cov-report=html
|
||
```
|
||
|
||
## API规范
|
||
|
||
### 统一响应格式
|
||
|
||
成功响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {},
|
||
"timestamp": 1706092800
|
||
}
|
||
```
|
||
|
||
错误响应：
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "参数验证失败",
|
||
"errors": [
|
||
{"field": "username", "message": "用户名不能为空"}
|
||
],
|
||
"timestamp": 1706092800
|
||
}
|
||
```
|
||
|
||
### 认证方式
|
||
|
||
使用JWT Token认证：
|
||
|
||
```http
|
||
Authorization: Bearer {access_token}
|
||
```
|
||
|
||
## 代码规范
|
||
|
||
### 命名规范
|
||
|
||
- 类名：大驼峰 (PascalCase) - `UserService`
|
||
- 函数名：小写+下划线 (snake_case) - `get_user_by_id`
|
||
- 变量名：小写+下划线 - `user_id`
|
||
- 常量：大写+下划线 (UPPER_CASE) - `MAX_RETRY_COUNT`
|
||
|
||
### Docstring规范
|
||
|
||
```python
|
||
async def get_user(db: AsyncSession, user_id: int) -> Optional[User]:
|
||
"""
|
||
根据ID获取用户
|
||
|
||
Args:
|
||
db: 数据库会话
|
||
user_id: 用户ID
|
||
|
||
Returns:
|
||
User: 用户对象或None
|
||
|
||
Raises:
|
||
NotFoundException: 用户不存在
|
||
"""
|
||
pass
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 数据库连接失败
|
||
|
||
检查 `DATABASE_URL` 配置是否正确
|
||
|
||
### Token过期
|
||
|
||
Access Token有效期15分钟，Refresh Token有效期7天
|
||
|
||
### 异步函数报错
|
||
|
||
确保所有数据库操作都使用 `await` 关键字
|
||
|
||
## 下一步计划
|
||
|
||
1. 完成用户管理API
|
||
2. 实现角色权限管理
|
||
3. 开发设备类型管理
|
||
4. 开发机构网点管理
|
||
5. 开发资产管理核心功能
|
||
|
||
## 联系方式
|
||
|
||
- 开发组: 后端API开发组
|
||
- 负责人: 老王
|
||
- 创建时间: 2025-01-24
|