zcglxt/DEVELOPMENT.md

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

## 项目进度追踪

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