012-kaopeilian/docs/规划/后端开发拆分策略/子agent/01-Agent-Auth/context.md

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) - 需要你创建

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天）

数据库表结构

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)
);

环境变量

# .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. 敏感操作记录审计日志