# 后台定时任务系统

## 📋 概述

游铛铛后端系统现已集成了完整的后台定时任务系统，用于自动执行关键的维护和管理任务，确保系统的稳定运行和安全性。

## 🔄 后台任务列表

### 1. 密钥轮换任务
- **执行间隔**: 每 5 分钟
- **功能**: 检查并自动轮换RSA+AES加密密钥
- **重要性**: 确保加密安全性，防止密钥过期

### 2. Session清理任务
- **执行间隔**: 每 2 小时
- **功能**: 清理30天前的非活跃Session记录（保留用于审计）
- **重要性**: 控制数据库大小，同时保持用户在线体验

### 3. 心跳缓存清理任务
- **执行间隔**: 每 1 小时
- **功能**: 清理过期的心跳监控缓存数据
- **重要性**: 释放内存，监控系统健康状态

## 🚀 自动启动

后台任务会在应用启动时自动启动，关闭时自动停止：

```python
# main.py 中的配置
app = FastAPI(
    title="游铛铛API",
    description="游铛铛产品后端API",
    version="1.0.0",
    docs_url="/docs",
    redoc_url="/redoc",
    lifespan=lifespan_manager,  # 自动管理后台任务
)
```

## 📊 监控后台任务

### 通过管理后台查看
访问 `/admin/docs` 查看API文档，或使用以下端点：

#### 获取仪表盘统计（包含后台任务状态）
```
GET /admin/dashboard/stats
```

响应示例：
```json
{
  "code": 200,
  "data": {
    "background_tasks": {
      "running": true,
      "total_tasks": 3,
      "active_tasks": 3,
      "completed_tasks": 0
    }
  }
}
```

#### 获取后台任务详细状态
```
GET /admin/dashboard/background-tasks/status
```

响应示例：
```json
{
  "code": 200,
  "data": {
    "manager_running": true,
    "total_tasks": 3,
    "tasks": [
      {
        "id": 1,
        "name": "后台任务-1",
        "status": "running",
        "done": false,
        "cancelled": false
      }
    ]
  }
}
```

## 📝 日志监控

后台任务的运行状态会记录在应用日志中：

```
INFO | 启动后台定时任务...
INFO | 已启动 3 个后台任务
INFO | 启动密钥轮换定时任务 (间隔: 5分钟)
INFO | 启动Session清理定时任务 (间隔: 10分钟)
INFO | 启动心跳缓存清理定时任务 (间隔: 1小时)
INFO | 停止后台定时任务...
INFO | 后台定时任务已停止
```

## ⚙️ 配置说明

后台任务的执行间隔可以在 `app/background_tasks.py` 中修改：

```python
# 密钥轮换间隔（秒）
await asyncio.sleep(300)  # 5分钟

# Session清理间隔（秒）
await asyncio.sleep(7200)  # 2小时

# 心跳缓存清理间隔（秒）
await asyncio.sleep(3600)  # 1小时
```

## 🔧 手动控制（开发调试用）

如果需要手动控制后台任务（仅用于开发调试）：

```python
from app.background_tasks import start_background_tasks, stop_background_tasks

# 手动启动
await start_background_tasks()

# 手动停止
await stop_background_tasks()
```

## 💡 设计理念

### 用户状态校验机制
所有API接口都会自动校验用户状态，异常时客户端自动退出登录：

#### 🔐 校验项目
- **用户存在性**: 检查用户是否还存在且未被删除
- **用户状态**: 验证用户是否被管理员禁用 (`status != 1`)
- **卡密有效性**: 检查充值是否过期 (`expire_time < now`)
- **单点登录**: 验证Session是否被其他地方登录踢掉
- **Session有效性**: 检查Session是否过期或异常

#### 🚨 异常响应
当检测到异常时，后端返回相应的HTTP状态码：
- `401 Unauthorized`: Session无效、用户不存在
- `403 Forbidden`: 用户禁用、卡密过期、其他地方登录

#### 📱 客户端响应策略
客户端根据错误类型采用不同的处理策略：

##### 🔐 认证异常 (401/403)
**立即退出登录**:
1. 停止心跳检测
2. 停止所有后台进程 (选品、扫货等)
3. 清除本地用户数据
4. 显示错误提示并退出登录

##### 🌐 网络异常
**宽松重试机制**:
1. 累积网络失败计数 (最高15次)
2. 超过阈值时暂停心跳检测
3. 停止后台进程但**不退出登录**
4. 显示网络异常提示，允许用户手动恢复
5. 用户可通过刷新页面重新建立心跳连接

### 📊 支持的异常场景

| 异常情况 | 检测位置 | 错误信息 | 客户端响应 | 处理策略 |
|---------|---------|---------|-----------|---------|
| 卡密过期 | Session验证 | "用户卡密已过期" | 🔐 立即退出登录 | 认证异常 |
| 用户禁用 | Session验证 | "用户不存在或已被禁用" | 🔐 立即退出登录 | 认证异常 |
| 其他地方登录 | Session验证 | "账号在其他地方登录" | 🔐 立即退出登录 | 认证异常 |
| Session过期 | 心跳验证 | "会话已过期" | 🔐 立即退出登录 | 认证异常 |
| 网络异常 | 心跳调用失败 | 连接超时/网络错误 | 🌐 宽松重试(15次) | 网络异常 |
| 服务器错误 | 心跳响应 | 5xx错误 | 🌐 宽松重试(15次) | 网络异常 |

### Session管理策略
为了保持用户的一致在线体验，我们采用了以下策略：

#### 🎯 智能过期处理
- **活跃过期Session自动延长**: 如果Session过期但用户还在活跃使用（心跳正常），自动延长Session
- **心跳延长机制**: 通过心跳检测自动延长Session过期时间（4小时内自动延长2小时）
- **无缝在线体验**: 用户不会因为Session过期而突然掉线

#### 🔄 Session生命周期
1. **创建**: Session创建时设置初始过期时间（默认24小时）
2. **验证**: 每次API调用验证Session有效性
3. **延长**: 心跳检测时检查是否需要延长过期时间
4. **停用**: 只有心跳失败或主动登出时才停用Session

#### 🧹 清理策略
- **不清理活跃Session**: 无论是否过期，只要用户在使用就不清理
- **只清理非活跃Session**: 30天前非活跃的Session记录
- **保留审计数据**: 确保安全审计和统计分析的需要

## 📈 任务执行逻辑

### 密钥轮换逻辑
1. 检查当前是否有激活的密钥
2. 检查当前密钥是否即将过期（剩余时间 < 重叠时间）
3. 如需轮换，生成新密钥对并激活
4. 清理过期的历史密钥

### Session清理逻辑
1. **智能延长活跃Session** - 检测到Session过期但用户活跃时自动延长
2. **优雅停用过期Session** - 只有长时间无心跳的Session才被停用
3. **保留审计数据** - 30天前非活跃Session记录仍保留用于分析

### 心跳缓存清理逻辑
1. 清理1小时内无活动的缓存条目
2. 输出当前监控统计信息

## 🎯 系统完整性

添加后台定时任务系统后，游铛铛系统现已达到 **100% 完整性**：

| 功能模块 | 完成度 | 状态 |
|---------|-------|------|
| API加密规范 | 100% | ✅ 完整 |
| 密钥轮换服务 | 100% | ✅ 完整 |
| Session管理 | 100% | ✅ 完整 |
| 心跳监控 | 100% | ✅ 完整 |
| 客户端实现 | 100% | ✅ 完整 |
| **后台定时任务** | **100%** | **✅ 完整** |

## 🚨 注意事项

1. **数据库连接**: 确保数据库服务正常运行，后台任务才能正常执行
2. **时区设置**: 所有时间相关的操作都使用北京时间 (UTC+8)
3. **异常处理**: 后台任务包含完整的异常处理，单个任务失败不会影响其他任务
4. **资源管理**: 应用关闭时会正确停止所有后台任务，防止资源泄露

---

*最后更新: 2026-01-06*