# Agent-Auth 上下文信息

## 重要规划文档
在开始开发前，请确保你已经理解以下关键文档：
- `../../协作机制设计.md` - 特别是全局上下文(GlobalContext)和服务间调用机制
- `../../模块分工指南.md` - 了解Auth模块的职责边界（第2.1节）
- `../../开发规范文档.md` - 编码标准和API设计规范
- `../../统一基础代码.md` - 可复用的代码模板

## 项目位置

- 项目根目录: `/Users/nongjun/Desktop/Ai公司/本地开发与测试/kaopeilian-backend/`
- 你的工作目录: `app/api/v1/auth.py`, `app/core/security.py`, `app/services/auth_service.py`

## 重要依赖文件

### 1. 基础模型 (`app/models/base.py`)

已提供BaseModel, SoftDeleteMixin, AuditMixin等基类

### 2. 用户模型 (`app/models/user.py`) - 需要你创建

```python
from sqlalchemy import Column, String, Boolean, Enum
from app.models.base import BaseModel, AuditMixin

class User(BaseModel, AuditMixin):
    __tablename__ = "users"
  
    username = Column(String(50), unique=True, nullable=False, index=True)
    email = Column(String(100), unique=True, nullable=False, index=True)
    password_hash = Column(String(200), nullable=False)
    is_active = Column(Boolean, default=True)
    is_superuser = Column(Boolean, default=False)
    role = Column(String(20), default="trainee")  # trainee, manager, admin
```

### 3. 基础Schema (`app/schemas/base.py`)

已提供BaseSchema, ResponseModel, ErrorResponse等基类

### 4. 异常处理 (`app/core/exceptions.py`)

已定义所有标准异常类

### 5. 日志系统 (`app/core/logger.py`)

已配置结构化日志

### 6. 配置管理 (`app/config/settings.py`)

关键配置项：

- SECRET_KEY - JWT密钥
- ALGORITHM - JWT算法（默认HS256）
- ACCESS_TOKEN_EXPIRE_MINUTES - 访问Token过期时间（默认30分钟）
- REFRESH_TOKEN_EXPIRE_DAYS - 刷新Token过期时间（默认7天）

## 数据库表结构

```sql
CREATE TABLE users (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    password_hash VARCHAR(200) NOT NULL,
    is_active BOOLEAN DEFAULT TRUE,
    is_superuser BOOLEAN DEFAULT FALSE,
    role VARCHAR(20) DEFAULT 'trainee',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    created_by BIGINT,
    updated_by BIGINT,
    INDEX idx_username (username),
    INDEX idx_email (email)
);
```

## 环境变量

```bash
# .env 文件中的认证相关配置
SECRET_KEY="your-secret-key-here-must-be-at-least-32-chars"
ALGORITHM="HS256"
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
```

## 测试账号

用于开发测试的默认账号：

- 超级管理员: superadmin / Superadmin123!
- 系统管理员: admin / Admin123!
- 测试学员: testuser / TestPass123!

## 错误码约定

- 1001: 用户名或密码错误
- 1002: 账号已被禁用
- 1003: Token无效或已过期
- 1004: 权限不足
- 1005: 用户名已存在
- 1006: 邮箱已存在

## 关键流程

### 登录流程

1. 接收用户名和密码
2. 验证用户身份
3. 检查账号状态
4. 生成访问Token和刷新Token
5. 返回Token信息

### 注册流程

1. 验证输入数据
2. 检查用户名和邮箱唯一性
3. 加密密码
4. 创建用户记录
5. 自动登录并返回Token

### Token刷新流程

1. 验证刷新Token
2. 检查Token是否在黑名单
3. 生成新的访问Token
4. 可选：轮换刷新Token

## 安全最佳实践

1. 使用bcrypt加密密码，cost factor设为12
2. JWT Token使用RS256算法（生产环境）
3. 实现Token黑名单机制（使用Redis）
4. 登录失败5次锁定账号15分钟
5. 敏感操作记录审计日志