# API 集成检查清单

## ✅ 已完成的集成工作

### 1. 路由集成 (app/api/v1/router.py)

已添加以下路由到 API Router：

```python
# 新增导入
from app.api.v1.endpoints import (
    ...
    user_management,  # 用户管理
    audit,            # 审计日志
)

# 新增路由
api_router.include_router(user_management.router, prefix="/users", tags=["User Management"])
api_router.include_router(audit.router, prefix="/audit", tags=["Audit Logs"])
```

**路由端点**：
- `/api/v1/auth/` - 认证相关（register, login, me, refresh）
- `/api/v1/users/` - 用户管理（CRUD操作，仅管理员）
- `/api/v1/audit/` - 审计日志查询（仅管理员）

### 2. 主应用配置 (app/main.py)

#### 2.1 导入更新
```python
from app.core.config import settings
from app.infra.audit.middleware import AuditMiddleware
```

#### 2.2 数据库初始化
```python
# 在 lifespan 中存储数据库实例到 app.state
app.state.db = pgdb
```

#### 2.3 FastAPI 配置
```python
app = FastAPI(
    lifespan=lifespan,
    title=settings.PROJECT_NAME,
    description="TJWater Server - 供水管网智能管理系统",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc",
)
```

#### 2.4 审计中间件（可选）
```python
# 取消注释以启用审计日志
# app.add_middleware(AuditMiddleware)
```

### 3. 依赖项更新 (app/auth/dependencies.py)

更新 `get_db()` 函数从 Request 对象获取数据库：

```python
async def get_db(request: Request) -> Database:
    """从 app.state 获取数据库实例"""
    if not hasattr(request.app.state, "db"):
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail="Database not initialized"
        )
    return request.app.state.db
```

### 4. 审计日志更新

- `app/api/v1/endpoints/audit.py` - 使用正确的数据库依赖
- `app/core/audit.py` - 接受可选的 db 参数

---

## 📋 部署前检查清单

### 环境配置
- [ ] 复制 `.env.example` 为 `.env`
- [ ] 配置 `SECRET_KEY`（JWT密钥）
- [ ] 配置 `ENCRYPTION_KEY`（数据加密密钥）
- [ ] 配置数据库连接信息

### 数据库迁移
- [ ] 执行用户表迁移：`psql -U postgres -d tjwater -f migrations/001_create_users_table.sql`
- [ ] 执行审计日志表迁移：`psql -U postgres -d tjwater -f migrations/002_create_audit_logs_table.sql`
- [ ] 验证表已创建：`\dt` 在 psql 中

### 依赖检查
- [ ] 确认已安装：`cryptography`
- [ ] 确认已安装：`python-jose[cryptography]`
- [ ] 确认已安装：`passlib[bcrypt]`
- [ ] 确认已安装：`email-validator`（用于 Pydantic email 验证）

### 代码验证
- [ ] 检查所有文件导入正常
- [ ] 运行加密功能测试：`python tests/test_encryption.py`
- [ ] 启动服务器：`uvicorn app.main:app --reload`
- [ ] 访问 API 文档：http://localhost:8000/docs

### API 测试
- [ ] 测试登录：POST `/api/v1/auth/login`
- [ ] 测试获取当前用户：GET `/api/v1/auth/me`
- [ ] 测试用户列表（需管理员）：GET `/api/v1/users/`
- [ ] 测试审计日志（需管理员）：GET `/api/v1/audit/logs`

---

## 🔧 快速测试命令

### 1. 生成密钥
```bash
# JWT 密钥
openssl rand -hex 32

# 加密密钥
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

### 2. 执行迁移
```bash
cd /home/zhifu/TJWaterServer/TJWaterServerBinary
psql -U postgres -d tjwater -f migrations/001_create_users_table.sql
psql -U postgres -d tjwater -f migrations/002_create_audit_logs_table.sql
```

### 3. 测试加密
```bash
python tests/test_encryption.py
```

### 4. 启动服务器
```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 5. 测试登录 API
```bash
# 使用默认管理员账号
curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123"

# 或使用迁移的账号
curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=tjwater&password=tjwater@123"
```

### 6. 测试受保护接口
```bash
# 保存 Token
TOKEN="<从登录响应中获取的 access_token>"

# 获取当前用户信息
curl -X GET "http://localhost:8000/api/v1/auth/me" \
  -H "Authorization: Bearer $TOKEN"

# 获取用户列表（需管理员权限）
curl -X GET "http://localhost:8000/api/v1/users/" \
  -H "Authorization: Bearer $TOKEN"

# 查询审计日志（需管理员权限）
curl -X GET "http://localhost:8000/api/v1/audit/logs" \
  -H "Authorization: Bearer $TOKEN"
```

---

## 📚 API 端点总览

### 认证接口 (`/api/v1/auth`)

| 方法 | 端点 | 描述 | 权限 |
|------|------|------|------|
| POST | `/register` | 用户注册 | 公开 |
| POST | `/login` | OAuth2 登录 | 公开 |
| POST | `/login/simple` | 简化登录（兼容旧版） | 公开 |
| GET | `/me` | 获取当前用户信息 | 认证用户 |
| POST | `/refresh` | 刷新 Token | 认证用户 |

### 用户管理 (`/api/v1/users`)

| 方法 | 端点 | 描述 | 权限 |
|------|------|------|------|
| GET | `/` | 获取用户列表 | 管理员 |
| GET | `/{id}` | 获取用户详情 | 所有者/管理员 |
| PUT | `/{id}` | 更新用户信息 | 所有者/管理员 |
| DELETE | `/{id}` | 删除用户 | 管理员 |
| POST | `/{id}/activate` | 激活用户 | 管理员 |
| POST | `/{id}/deactivate` | 停用用户 | 管理员 |

### 审计日志 (`/api/v1/audit`)

| 方法 | 端点 | 描述 | 权限 |
|------|------|------|------|
| GET | `/logs` | 查询审计日志 | 管理员 |
| GET | `/logs/count` | 获取日志总数 | 管理员 |
| GET | `/logs/my` | 查看我的操作记录 | 认证用户 |

---

## ⚠️ 注意事项

### 1. 审计中间件
审计中间件默认是**禁用**的。如需启用，在 `app/main.py` 中取消注释：

```python
app.add_middleware(AuditMiddleware)
```

**注意**：启用后会自动记录所有 POST/PUT/DELETE 请求，可能增加数据库负载。

### 2. 向后兼容
保留了原有的简化登录接口 `/auth/login/simple`，可以直接使用查询参数：

```bash
POST /api/v1/auth/login/simple?username=admin&password=admin123
```

### 3. 数据库连接
确保数据库实例在应用启动时正确初始化并存储到 `app.state.db`。

### 4. 权限控制示例
为现有接口添加权限控制：

```python
from app.auth.permissions import require_role, get_current_admin
from app.domain.models.role import UserRole

# 需要管理员权限
@router.delete("/resource/{id}")
async def delete_resource(
    id: int,
    current_user = Depends(get_current_admin)
):
    ...

# 需要操作员以上权限
@router.post("/resource")
async def create_resource(
    data: dict,
    current_user = Depends(require_role(UserRole.OPERATOR))
):
    ...
```

---

## 🚀 完整启动流程

```bash
# 1. 进入项目目录
cd /home/zhifu/TJWaterServer/TJWaterServerBinary

# 2. 配置环境变量（如果还没有）
cp .env.example .env
# 编辑 .env 填写必要的配置

# 3. 执行数据库迁移（如果还没有）
psql -U postgres -d tjwater < migrations/001_create_users_table.sql
psql -U postgres -d tjwater < migrations/002_create_audit_logs_table.sql

# 4. 测试加密功能
python tests/test_encryption.py

# 5. 启动服务器
uvicorn app.main:app --reload

# 6. 访问 API 文档
# 浏览器打开: http://localhost:8000/docs
```

---

## 📞 故障排查

### 问题 1: 导入错误
```
ModuleNotFoundError: No module named 'jose'
```
**解决**: 安装依赖 `pip install python-jose[cryptography]`

### 问题 2: 数据库未初始化
```
503 Service Unavailable: Database not initialized
```
**解决**: 检查 `main.py` 中的 lifespan 函数是否正确设置 `app.state.db`

### 问题 3: Token 验证失败
```
401 Unauthorized: Could not validate credentials
```
**解决**: 
1. 检查 SECRET_KEY 是否配置正确
2. 确认 Token 格式：`Authorization: Bearer {token}`
3. 检查 Token 是否过期

### 问题 4: 表不存在
```
relation "users" does not exist
```
**解决**: 执行数据库迁移脚本

---

## 📖 相关文档

- **使用指南**: `SECURITY_README.md`
- **部署指南**: `DEPLOYMENT.md`
- **实施总结**: `SECURITY_IMPLEMENTATION_SUMMARY.md`
- **自动设置**: `setup_security.sh`

---

**最后更新**: 2026-02-02
**状态**: ✅ API 已完全集成