Fix API compatibility and add user/role/permission and asset import/export

backend/DEVELOPMENT.md

@@ -0,0 +1,213 @@
+# 资产管理系统后端开发文档
+
+## 项目进度追踪
+
+### 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