# 认证系统开发文档

## 概述

本文档详细介绍了基于Laravel 12和Laravel Sanctum实现的Token认证系统，适用于Web端、移动端及各种API调用场景。

## 系统架构

### 1. 整体结构

```
认证系统
├── 控制器层 (AuthController)
│   ├── 用户认证逻辑
│   ├── Token管理
│   └── 设备管理
├── 模型层 (User)
│   ├── 用户数据管理
│   ├── Sanctum Token集成
│   └── 数据验证
├── 路由层 (admin.php)
│   ├── 公开路由 (登录)
│   └── 受保护路由 (需Token)
└── 中间件层 (auth:sanctum)
    ├── Token验证
    └── 用户授权
```

### 2. 文件结构

```
app/
├── Http/Controllers/Admin/
│   └── AuthController.php          # 认证控制器
├── Models/
│   └── User.php                    # 用户模型
└── Http/Middleware/
    └── (使用Laravel内置auth:sanctum中间件)

routes/
└── admin.php                      # 后台认证路由

database/
├── migrations/
│   ├── create_users_table.php     # 用户表结构
│   └── create_personal_access_tokens_table.php  # Token表结构
└── seeders/
    └── AdminUserSeeder.php         # 测试用户数据

config/
└── sanctum.php                    # Sanctum配置文件

docs/
└── 认证系统开发文档.md            # 本文档
```

## 核心组件详细说明

### 1. AuthController 认证控制器

**位置**: `app/Http/Controllers/Admin/AuthController.php`

**职责**:
- 处理用户登录认证
- 生成和管理API Token
- 处理用户登出
- 提供用户信息查询
- 管理多设备登录

**主要方法**:

#### login() - 用户登录
- **功能**: 验证用户凭据，生成Token
- **输入**: username, password, device_name(可选)
- **输出**: 用户信息 + Token
- **验证**: 用户名密码、用户状态检查

#### logout() - 登出当前设备
- **功能**: 删除当前设备的Token
- **输入**: 当前请求的Token
- **输出**: 成功确认消息

#### logoutAll() - 登出所有设备
- **功能**: 删除用户所有设备的Token
- **输入**: 当前请求的Token
- **输出**: 成功确认消息

#### me() - 获取用户信息
- **功能**: 返回当前登录用户信息
- **输入**: Token认证
- **输出**: 用户详细信息 + Token状态

#### refresh() - 刷新Token
- **功能**: 生成新Token，删除旧Token
- **输入**: 当前Token + device_name
- **输出**: 新Token信息

#### devices() - 获取设备列表
- **功能**: 查看用户所有登录设备
- **输入**: Token认证
- **输出**: 设备列表 + Token信息

#### deleteDevice() - 删除指定设备
- **功能**: 根据Token ID删除指定设备
- **输入**: token_id参数
- **输出**: 删除确认消息

### 2. User 用户模型

**位置**: `app/Models/User.php`

**特性**:
- 继承Laravel Authenticatable
- 集成HasApiTokens trait (Sanctum)
- 自定义时间戳字段映射
- 用户状态验证

**重要配置**:
```php
// 自定义时间戳字段
const CREATED_AT = 'create_time';
const UPDATED_AT = 'update_time';

// 可批量赋值字段
protected $fillable = [
    'username', 'nickname', 'email', 'mobile', 
    'password', 'dept_id', 'avatar', 'status'
];

// 隐藏敏感字段
protected $hidden = ['password'];
```

### 3. 路由配置

**位置**: `routes/admin.php`

**结构**:
```php
// 公开路由 (无需认证)
Route::prefix('auth')->group(function () {
    Route::post('/login', [AuthController::class, 'login']);
});

// 受保护路由 (需要Token认证)
Route::middleware('auth:sanctum')->group(function () {
    // 认证相关
    Route::prefix('auth')->group(function () {
        Route::post('/logout', [AuthController::class, 'logout']);
        Route::post('/logout-all', [AuthController::class, 'logoutAll']);
        Route::get('/me', [AuthController::class, 'me']);
        Route::post('/refresh', [AuthController::class, 'refresh']);
        Route::get('/devices', [AuthController::class, 'devices']);
        Route::delete('/devices', [AuthController::class, 'deleteDevice']);
    });
    
    // 业务功能
    Route::get('/dashboard', function () { /* 仪表盘逻辑 */ });
});
```

## 业务流程

### 1. 用户登录流程

```mermaid
graph TD
    A[客户端发送登录请求] --> B[AuthController::login]
    B --> C[验证请求参数]
    C --> D{参数是否有效?}
    D -->|否| E[返回参数错误]
    D -->|是| F[验证用户凭据]
    F --> G{用户名密码是否正确?}
    G -->|否| H[返回认证失败]
    G -->|是| I[检查用户状态]
    I --> J{用户是否可用?}
    J -->|否| K[返回用户状态错误]
    J -->|是| L[生成API Token]
    L --> M[返回用户信息和Token]
```

### 2. API请求流程

```mermaid
graph TD
    A[客户端发送API请求] --> B[携带Bearer Token]
    B --> C[auth:sanctum中间件验证]
    C --> D{Token是否有效?}
    D -->|否| E[返回401未授权]
    D -->|是| F[获取Token对应用户]
    F --> G{用户是否存在且可用?}
    G -->|否| H[返回403禁止访问]
    G -->|是| I[执行控制器方法]
    I --> J[返回业务数据]
```

### 3. Token管理流程

```mermaid
graph TD
    A[Token生成] --> B[存储到personal_access_tokens表]
    B --> C[设置设备名称和权限]
    C --> D[Token使用验证]
    D --> E{Token是否过期?}
    E -->|是| F[自动清理]
    E -->|否| G[继续使用]
    G --> H[用户主动登出]
    H --> I[删除指定Token]
    I --> J[Token失效]
```

## 数据库设计

### 1. system_users 表 (用户表)

```sql
CREATE TABLE `system_users` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `username` varchar(50) NOT NULL COMMENT '用户名',
  `nickname` varchar(50) DEFAULT NULL COMMENT '昵称',
  `email` varchar(100) DEFAULT NULL COMMENT '邮箱',
  `mobile` varchar(20) DEFAULT NULL COMMENT '手机号',
  `password` varchar(255) NOT NULL COMMENT '密码',
  `avatar` varchar(500) DEFAULT NULL COMMENT '头像',
  `dept_id` int DEFAULT NULL COMMENT '部门ID',
  `status` tinyint DEFAULT '1' COMMENT '状态 1:正常 0:禁用',
  `deleted` tinyint DEFAULT '0' COMMENT '删除 1:已删除 0:正常',
  `create_time` timestamp NULL DEFAULT CURRENT_TIMESTAMP,
  `update_time` timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `username` (`username`)
) COMMENT='系统用户表';
```

### 2. personal_access_tokens 表 (Token表)

```sql
CREATE TABLE `personal_access_tokens` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `tokenable_type` varchar(255) NOT NULL,
  `tokenable_id` bigint unsigned NOT NULL,
  `name` varchar(255) NOT NULL,
  `token` varchar(64) NOT NULL,
  `abilities` text,
  `last_used_at` timestamp NULL DEFAULT NULL,
  `expires_at` timestamp NULL DEFAULT NULL,
  `created_at` timestamp NULL DEFAULT NULL,
  `updated_at` timestamp NULL DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `personal_access_tokens_token_unique` (`token`),
  KEY `personal_access_tokens_tokenable_type_tokenable_id_index` (`tokenable_type`,`tokenable_id`)
) COMMENT='API访问令牌表';
```

## 使用方法

### 1. 客户端集成示例

#### JavaScript/Web端
```javascript
class AuthService {
    constructor() {
        this.token = localStorage.getItem('auth_token');
        this.baseURL = '/admin';
    }

    // 登录
    async login(username, password, deviceName = 'Web Browser') {
        const response = await fetch(`${this.baseURL}/auth/login`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            },
            body: JSON.stringify({
                username,
                password,
                device_name: deviceName
            })
        });

        const data = await response.json();
        if (data.success) {
            this.token = data.data.token.access_token;
            localStorage.setItem('auth_token', this.token);
            return data.data;
        }
        throw new Error(data.message);
    }

    // 发送认证请求
    async apiRequest(url, options = {}) {
        const headers = {
            'Authorization': `Bearer ${this.token}`,
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            ...options.headers
        };

        return fetch(url, { ...options, headers });
    }

    // 获取用户信息
    async getUser() {
        const response = await this.apiRequest(`${this.baseURL}/auth/me`);
        return response.json();
    }

    // 登出
    async logout() {
        await this.apiRequest(`${this.baseURL}/auth/logout`, {
            method: 'POST'
        });
        this.token = null;
        localStorage.removeItem('auth_token');
    }
}
```

#### 移动端示例 (React Native)
```javascript
import AsyncStorage from '@react-native-async-storage/async-storage';

class MobileAuthService {
    constructor() {
        this.token = null;
        this.baseURL = 'https://your-api.com/admin';
        this.loadToken();
    }

    async loadToken() {
        this.token = await AsyncStorage.getItem('auth_token');
    }

    async login(username, password) {
        const deviceInfo = {
            device_name: `${Platform.OS} ${DeviceInfo.getSystemVersion()}`
        };

        const response = await fetch(`${this.baseURL}/auth/login`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            },
            body: JSON.stringify({
                username,
                password,
                ...deviceInfo
            })
        });

        const data = await response.json();
        if (data.success) {
            this.token = data.data.token.access_token;
            await AsyncStorage.setItem('auth_token', this.token);
            return data.data;
        }
        throw new Error(data.message);
    }
}
```

### 2. 服务端扩展示例

#### 添加新的认证路由
```php
// routes/admin.php
Route::middleware('auth:sanctum')->group(function () {
    // 用户管理
    Route::prefix('users')->group(function () {
        Route::get('/', [UserController::class, 'index']);
        Route::post('/', [UserController::class, 'store']);
        Route::put('/{id}', [UserController::class, 'update']);
        Route::delete('/{id}', [UserController::class, 'destroy']);
    });
});
```

#### 创建新的业务控制器
```php
<?php

namespace App\Http\Controllers\Admin;

use App\Http\Controllers\BaseController;
use Illuminate\Http\Request;

class UserController extends BaseController
{
    public function index(Request $request)
    {
        // 获取当前认证用户
        $currentUser = $request->user();
        
        // 业务逻辑
        $users = User::paginate(10);
        
        return $this->success($users, '获取用户列表成功');
    }
}
```

## 配置说明

### 1. Sanctum配置

**文件**: `config/sanctum.php`

**重要配置项**:
```php
// Token过期时间 (分钟)
'expiration' => null, // null表示永不过期

// 中间件配置
'middleware' => [
    'verify_csrf_token' => App\Http\Middleware\VerifyCsrfToken::class,
    'encrypt_cookies' => App\Http\Middleware\EncryptCookies::class,
],

// 前缀配置
'prefix' => 'sanctum',

// 数据库连接
'connection' => env('SANCTUM_CONNECTION'),
```

### 2. 环境变量配置

**.env 文件**:
```env
# 应用配置
APP_NAME="Study API V2"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

# 数据库配置
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=study_api_v2
DB_USERNAME=root
DB_PASSWORD=

# Sanctum配置
SANCTUM_STATEFUL_DOMAINS=localhost,127.0.0.1
SANCTUM_EXPIRATION=null
```

## 安全考虑

### 1. Token安全

**存储安全**:
- ✅ 客户端使用安全存储 (Web: localStorage, 移动端: Keychain/Keystore)
- ✅ 避免在URL参数中传递Token
- ✅ 使用HTTPS传输
- ⚠️ 定期轮换Token (refresh机制)

**传输安全**:
- ✅ 始终使用 `Authorization: Bearer {token}` 头
- ✅ 不在Cookie中存储Token (避免CSRF)
- ✅ 设置合适的CORS策略

### 2. 用户验证

**登录安全**:
- ✅ 密码哈希存储 (bcrypt)
- ✅ 用户状态检查 (status, deleted字段)
- ✅ 失败次数限制 (可扩展)
- ⚠️ 双因素认证 (可扩展)

**会话管理**:
- ✅ 多设备登录管理
- ✅ 设备标识和追踪
- ✅ 远程登出功能
- ✅ Token使用时间记录

### 3. API安全

**访问控制**:
- ✅ 基于Token的认证
- ✅ 路由级别的权限控制
- ✅ 用户状态实时验证
- ⚠️ 角色权限系统 (可扩展)

**数据保护**:
- ✅ 敏感数据过滤 (密码等)
- ✅ 统一错误响应格式
- ✅ 请求参数验证
- ✅ SQL注入防护 (Eloquent ORM)

## 错误处理

### 1. 常见错误码

| 错误码 | 说明 | 处理方式 |
|--------|------|----------|
| 401 | 未授权访问 | 重新登录 |
| 403 | 禁止访问 | 检查用户状态 |
| 422 | 参数验证失败 | 修正请求参数 |
| 500 | 服务器内部错误 | 联系技术支持 |

### 2. 错误响应格式

```json
{
    "success": false,
    "message": "具体错误信息",
    "code": 422,
    "data": null,
    "errors": {
        "username": ["用户名不能为空"],
        "password": ["密码长度至少6位"]
    }
}
```

### 3. 客户端错误处理示例

```javascript
async function handleApiCall() {
    try {
        const response = await authService.apiRequest('/admin/auth/me');
        const data = await response.json();
        
        if (!response.ok) {
            switch (response.status) {
                case 401:
                    // Token过期或无效，重新登录
                    authService.logout();
                    window.location.href = '/login';
                    break;
                case 403:
                    // 用户被禁用
                    alert('账户已被禁用，请联系管理员');
                    break;
                case 422:
                    // 参数错误
                    console.error('参数错误:', data.errors);
                    break;
                default:
                    console.error('API错误:', data.message);
            }
            return;
        }
        
        // 处理成功响应
        console.log('用户信息:', data.data);
    } catch (error) {
        console.error('网络错误:', error);
    }
}
```

## 性能优化

### 1. 数据库优化

**索引优化**:
- ✅ username字段唯一索引
- ✅ personal_access_tokens表Token字段索引
- ✅ 用户状态字段索引

**查询优化**:
- ✅ 避免N+1查询问题
- ✅ 使用Eloquent关联查询
- ✅ 合理使用缓存

### 2. Token管理优化

**清理策略**:
- ✅ 定期清理过期Token
- ✅ 限制单用户Token数量
- ✅ 异步处理Token操作

**缓存策略**:
- ⚠️ Redis缓存用户信息 (可扩展)
- ⚠️ Token黑名单缓存 (可扩展)

## 监控和日志

### 1. 日志记录

**登录日志**:
```php
// 在AuthController中添加
Log::info('User login attempt', [
    'username' => $request->username,
    'ip' => $request->ip(),
    'user_agent' => $request->userAgent(),
    'timestamp' => now()
]);
```

**API访问日志**:
```php
// 可以创建中间件记录API访问
Log::info('API access', [
    'user_id' => Auth::id(),
    'endpoint' => $request->path(),
    'method' => $request->method(),
    'ip' => $request->ip()
]);
```

### 2. 监控指标

**关键指标**:
- 登录成功/失败率
- Token使用频率
- API响应时间
- 并发用户数

## 注意事项

### 1. 开发注意事项

**代码规范**:
- ✅ 遵循PSR-4自动加载规范
- ✅ 使用Laravel最佳实践
- ✅ 保持代码注释完整
- ✅ 单一职责原则

**测试要求**:
- ⚠️ 编写单元测试
- ⚠️ 集成测试覆盖
- ⚠️ API文档同步更新

### 2. 部署注意事项

**环境配置**:
- ✅ 生产环境关闭DEBUG
- ✅ 配置正确的APP_URL
- ✅ 设置强密码和密钥
- ✅ 配置HTTPS

**安全配置**:
- ✅ 限制文件权限
- ✅ 配置防火墙规则
- ✅ 定期更新依赖包
- ✅ 监控异常访问

### 3. 维护注意事项

**定期维护**:
- 清理过期Token
- 检查用户状态
- 更新安全补丁
- 备份重要数据

**扩展考虑**:
- 角色权限系统
- 多租户支持
- 接口版本控制
- 限流和熔断

## 技术支持

### 1. 常见问题

**Q: Token过期时间如何设置？**
A: 在 `config/sanctum.php` 中设置 `expiration` 字段，单位为分钟。设置为 `null` 表示永不过期。

**Q: 如何实现Token自动刷新？**
A: 客户端可以调用 `/admin/auth/refresh` 接口获取新Token，同时删除旧Token。

**Q: 如何限制用户同时登录设备数？**
A: 在登录时可以检查用户现有Token数量，超过限制时删除最旧的Token。

### 2. 扩展资源

**相关文档**:
- [Laravel Sanctum官方文档](https://laravel.com/docs/11.x/sanctum)
- [Laravel认证文档](https://laravel.com/docs/11.x/authentication)
- [API资源文档](https://laravel.com/docs/11.x/eloquent-resources)

**工具推荐**:
- Postman/Insomnia (API测试)
- Laravel Telescope (调试工具)
- Laravel Horizon (队列监控)

---

**文档版本**: v1.0  
**最后更新**: 2024年12月  
**作者**: 开发团队  
**审核**: 技术负责人