zcglxt/backend/DEVELOPMENT.md

资产管理系统后端开发文档

项目进度追踪

Phase 1: 基础框架 ✅ (已完成)

• 项目结构搭建
• 统一响应封装 (app/core/response.py)
• 异常处理中间件 (app/core/exceptions.py)
• JWT认证服务 (app/core/security.py)
• 数据库连接和Session管理 (app/db/session.py)
• 依赖注入系统 (app/core/deps.py)

Phase 2: 认证与用户管理 🚧 (进行中)

• 认证模块API (app/api/v1/auth.py)
• 用户管理模型 (app/models/user.py)
• 用户管理Schema (app/schemas/user.py)
• 用户CRUD操作 (app/crud/user.py)
• 认证服务 (app/services/auth_service.py)
• 用户管理API
• 角色权限API
• RBAC权限控制中间件

Phase 3-7: 待开发

• Phase 3: 基础数据管理
• Phase 4: 资产管理核心
• Phase 5: 资产分配
• Phase 6: 维修与统计
• Phase 7: 系统管理

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

cp .env.example .env
# 编辑 .env 文件

3. 初始化数据库

# 方式1: 使用 Alembic (推荐)
alembic upgrade head

# 方式2: 开发环境自动初始化
# 已在 app/main.py 的 lifespan 中实现

4. 启动服务

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/ 中创建路由

示例：

# 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})

数据库迁移

# 创建迁移
alembic revision --autogenerate -m "描述"

# 执行迁移
alembic upgrade head

# 回滚
alembic downgrade -1

运行测试

# 所有测试
pytest

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

# 带覆盖率
pytest --cov=app --cov-report=html

API规范

统一响应格式

成功响应：

{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": 1706092800
}

错误响应：

{
  "code": 400,
  "message": "参数验证失败",
  "errors": [
    {"field": "username", "message": "用户名不能为空"}
  ],
  "timestamp": 1706092800
}

认证方式

使用JWT Token认证：

Authorization: Bearer {access_token}

代码规范

命名规范

• 类名：大驼峰 (PascalCase) - UserService
• 函数名：小写+下划线 (snake_case) - get_user_by_id
• 变量名：小写+下划线 - user_id
• 常量：大写+下划线 (UPPER_CASE) - MAX_RETRY_COUNT

Docstring规范

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