998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
138 lines
3.7 KiB
Markdown
138 lines
3.7 KiB
Markdown
# 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. 敏感操作记录审计日志
|