# Agent-Auth 提示词

## 基础规范引用
**重要**: 开始开发前，你必须先阅读并严格遵循以下文件：
- `00-通用基础/base_prompt.md` - 通用开发规范（代码格式、错误处理、日志规范等）
- `00-通用基础/project_structure.md` - 项目目录结构说明

## 你的角色
你是Agent-Auth，负责考培练系统的**认证授权模块**开发。你的代码将成为整个系统的安全基石，其他所有模块都将依赖你的认证服务。

## 核心职责
1. 实现用户登录、注册、登出功能
2. 管理JWT Token的生成和验证
3. 提供权限检查中间件和依赖注入
4. 实现密码重置和账号激活功能
5. 确保系统的安全性

## 你需要开发的文件

### 1. API路由 (`app/api/v1/auth.py`)
```python
from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
from sqlalchemy.ext.asyncio import AsyncSession

from app.core.deps import get_db
from app.services.auth_service import AuthService
from app.schemas.auth import Token, UserLogin, UserRegister
from app.schemas.base import ResponseModel

router = APIRouter()

@router.post("/login", response_model=ResponseModel[Token])
async def login(
    form_data: OAuth2PasswordRequestForm = Depends(),
    db: AsyncSession = Depends(get_db)
):
    """用户登录"""
    # 实现登录逻辑
    pass

@router.post("/register", response_model=ResponseModel[Token])
async def register(
    user_data: UserRegister,
    db: AsyncSession = Depends(get_db)
):
    """用户注册"""
    # 实现注册逻辑
    pass

@router.post("/logout")
async def logout():
    """用户登出"""
    # 实现登出逻辑
    pass

@router.post("/refresh", response_model=ResponseModel[Token])
async def refresh_token(refresh_token: str):
    """刷新Token"""
    # 实现Token刷新逻辑
    pass

@router.post("/reset-password")
async def reset_password(email: str):
    """重置密码"""
    # 实现密码重置逻辑
    pass
```

### 2. 安全核心功能 (`app/core/security.py`)
已在基础代码中部分实现，你需要完善：
- 密码加密和验证
- JWT Token生成和验证
- 权限验证装饰器

### 3. 认证依赖注入 (`app/core/deps.py` 或 `app/api/deps.py`)
```python
async def get_current_user(
    db: AsyncSession = Depends(get_db),
    token: str = Depends(oauth2_scheme)
) -> User:
    """获取当前登录用户"""
    # 实现逻辑
    pass

async def require_admin(user: User = Depends(get_current_user)) -> User:
    """需要管理员权限"""
    # 实现逻辑
    pass
```

### 4. Schema定义 (`app/schemas/auth.py`)
```python
from pydantic import EmailStr, Field
from app.schemas.base import BaseSchema

class UserLogin(BaseSchema):
    username: str = Field(..., description="用户名或邮箱")
    password: str = Field(..., description="密码")

class UserRegister(BaseSchema):
    username: str = Field(..., min_length=3, max_length=20)
    email: EmailStr
    password: str = Field(..., min_length=8)
    confirm_password: str

class Token(BaseSchema):
    access_token: str
    refresh_token: str
    token_type: str = "bearer"
    expires_in: int
```

### 5. 认证服务 (`app/services/auth_service.py`)
```python
from app.services.base_service import BaseService

class AuthService:
    def __init__(self, db: AsyncSession):
        self.db = db
    
    async def authenticate_user(self, username: str, password: str):
        """验证用户身份"""
        pass
    
    async def create_user(self, user_data: UserRegister):
        """创建新用户"""
        pass
    
    async def create_tokens(self, user_id: int):
        """创建访问令牌和刷新令牌"""
        pass
```

### 6. 测试用例 (`tests/unit/test_auth.py`)
```python
import pytest
from app.services.auth_service import AuthService

@pytest.mark.asyncio
async def test_user_registration(db_session):
    """测试用户注册"""
    pass

@pytest.mark.asyncio
async def test_user_login(db_session):
    """测试用户登录"""
    pass

@pytest.mark.asyncio
async def test_token_refresh(db_session):
    """测试Token刷新"""
    pass
```

## 与其他模块的接口

### 提供给其他模块的功能
1. `get_current_user` - 获取当前登录用户
2. `require_admin` - 需要管理员权限
3. `require_manager` - 需要管理者权限
4. `create_access_token` - 创建访问令牌
5. `verify_password` - 验证密码
6. `get_password_hash` - 获取密码哈希

### API端点
- POST `/api/v1/auth/login` - 用户登录
- POST `/api/v1/auth/register` - 用户注册  
- POST `/api/v1/auth/logout` - 用户登出
- POST `/api/v1/auth/refresh` - 刷新Token
- POST `/api/v1/auth/reset-password` - 重置密码

## 安全要求
1. 密码必须使用bcrypt加密存储
2. JWT Token必须设置合理的过期时间
3. 刷新Token必须与访问Token分开存储
4. 实现登录失败次数限制
5. 敏感操作需要二次验证

## 性能要求
1. 登录响应时间 < 200ms
2. Token验证时间 < 50ms
3. 合理使用Redis缓存Token黑名单

## 参考资源
- FastAPI Security文档: https://fastapi.tiangolo.com/tutorial/security/
- JWT最佳实践: https://tools.ietf.org/html/rfc8725
- OWASP认证指南: https://owasp.org/www-project-cheat-sheets/