139 lines
9.7 KiB
Markdown
139 lines
9.7 KiB
Markdown
# 需求文档：Weibo-HotSign 多用户签到系统
|
||
|
||
## 简介
|
||
|
||
Weibo-HotSign 是一个分布式微博超话自动签到系统，采用微服务架构（FastAPI + Celery + MySQL + Redis）。本需求文档覆盖系统的五大核心模块：用户认证（含 Token 刷新）、微博账号管理、定时签到任务配置、签到执行引擎、以及整体架构重构。目标是将当前分散的、含大量 Mock 实现的代码库重构为一个真正可运行的、模块间紧密集成的生产级系统。
|
||
|
||
## 术语表
|
||
|
||
- **System**: 指 Weibo-HotSign 后端系统整体
|
||
- **Auth_Service**: 用户认证与授权服务（`backend/auth_service`）
|
||
- **API_Service**: API 网关与账号/任务管理服务（`backend/api_service`）
|
||
- **Task_Scheduler**: 基于 Celery Beat 的定时任务调度服务（`backend/task_scheduler`）
|
||
- **Signin_Executor**: 签到执行 Worker 服务（`backend/signin_executor`）
|
||
- **User**: 使用本系统的注册用户
|
||
- **Weibo_Account**: 用户绑定到系统中的微博账号，以 Cookie 形式存储凭证
|
||
- **Task**: 用户为某个 Weibo_Account 配置的定时签到任务
|
||
- **Cookie**: 微博网站的登录凭证，用于模拟已登录状态
|
||
- **Cron_Expression**: 标准 Cron 表达式，用于定义任务调度时间
|
||
- **Signin_Log**: 每次签到执行的结果记录
|
||
- **JWT**: JSON Web Token，用于用户身份认证
|
||
- **Refresh_Token**: 用于在 Access Token 过期后获取新 Token 的长期凭证
|
||
- **AES-256-GCM**: 对称加密算法，用于加密存储 Cookie
|
||
|
||
## 需求
|
||
|
||
### 需求 1：用户认证与 Token 管理
|
||
|
||
**用户故事：** 作为用户，我希望能够注册、登录并安全地维持会话，以便长期使用系统而无需频繁重新登录。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 用户提交有效的注册信息（用户名、邮箱、密码），THE Auth_Service SHALL 创建用户账户并返回用户信息
|
||
2. WHEN 用户提交的用户名或邮箱已存在，THE Auth_Service SHALL 返回 409 Conflict 错误并指明冲突字段
|
||
3. WHEN 用户提交有效的邮箱和密码进行登录，THE Auth_Service SHALL 返回包含 Access Token 和 Refresh Token 的认证响应
|
||
4. WHEN 用户提交无效的邮箱或密码进行登录，THE Auth_Service SHALL 返回 401 Unauthorized 错误
|
||
5. WHEN 用户携带有效的 Refresh Token 请求刷新，THE Auth_Service SHALL 返回新的 Access Token 和新的 Refresh Token
|
||
6. WHEN 用户携带过期或无效的 Refresh Token 请求刷新，THE Auth_Service SHALL 返回 401 Unauthorized 错误
|
||
7. WHEN 用户携带有效的 Access Token 请求 `/auth/me`，THE Auth_Service SHALL 返回当前用户的完整信息
|
||
8. IF 用户密码不满足强度要求（至少8位，含大小写字母、数字和特殊字符），THEN THE Auth_Service SHALL 返回 400 Bad Request 并说明密码强度不足
|
||
|
||
### 需求 2：微博账号管理
|
||
|
||
**用户故事：** 作为用户，我希望能够添加、查看、更新和删除我的微博账号，以便集中管理多个微博账号的签到。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 用户提交微博 Cookie 和备注信息，THE API_Service SHALL 使用 AES-256-GCM 加密 Cookie 后存储，并返回新创建的账号信息
|
||
2. WHEN 用户请求获取账号列表，THE API_Service SHALL 返回该用户拥有的所有 Weibo_Account（不包含解密后的 Cookie）
|
||
3. WHEN 用户请求获取单个账号详情，THE API_Service SHALL 返回该账号的状态、备注和最近签到信息
|
||
4. WHEN 用户请求更新账号的备注或 Cookie，THE API_Service SHALL 更新对应字段并返回更新后的账号信息
|
||
5. WHEN 用户请求删除一个账号，THE API_Service SHALL 级联删除该账号关联的所有 Task 和 Signin_Log，并返回成功响应
|
||
6. IF 用户尝试操作不属于自己的账号，THEN THE API_Service SHALL 返回 403 Forbidden 错误
|
||
7. WHEN 账号被创建时，THE API_Service SHALL 将账号状态初始化为 "pending"
|
||
8. THE API_Service SHALL 对所有账号管理接口要求有效的 JWT Access Token 认证
|
||
|
||
### 需求 3：Cookie 加密与验证
|
||
|
||
**用户故事：** 作为用户，我希望我的微博 Cookie 被安全存储，并且系统能自动检测 Cookie 是否失效，以便我及时更新。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 存储 Cookie 时，THE API_Service SHALL 使用 AES-256-GCM 算法加密，并将密文和 IV 分别存储到 `encrypted_cookies` 和 `iv` 字段
|
||
2. WHEN 读取 Cookie 用于签到时，THE Signin_Executor SHALL 使用对应的 IV 解密 Cookie 并还原为原始字符串
|
||
3. FOR ALL 有效的 Cookie 字符串，加密后再解密 SHALL 产生与原始字符串完全相同的结果（Round-trip 属性）
|
||
4. IF 解密过程中发生错误（密钥不匹配、数据损坏），THEN THE System SHALL 将账号状态标记为 "invalid_cookie" 并记录错误日志
|
||
|
||
### 需求 4：定时签到任务配置
|
||
|
||
**用户故事：** 作为用户，我希望能够为每个微博账号配置独立的签到时间计划，以便灵活控制签到频率和时间。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 用户为某个账号创建签到任务并提供有效的 Cron_Expression，THE API_Service SHALL 创建任务记录并将任务注册到 Task_Scheduler
|
||
2. WHEN 用户提交无效的 Cron_Expression，THE API_Service SHALL 返回 400 Bad Request 并说明表达式格式错误
|
||
3. WHEN 用户请求获取某个账号的任务列表，THE API_Service SHALL 返回该账号关联的所有 Task 及其启用状态
|
||
4. WHEN 用户启用或禁用一个任务，THE API_Service SHALL 更新数据库中的 `is_enabled` 字段，并同步更新 Task_Scheduler 中的调度状态
|
||
5. WHEN 用户删除一个任务，THE API_Service SHALL 从数据库删除任务记录，并从 Task_Scheduler 中移除对应的调度
|
||
6. IF 用户尝试为不属于自己的账号创建任务，THEN THE API_Service SHALL 返回 403 Forbidden 错误
|
||
|
||
### 需求 5：任务调度引擎
|
||
|
||
**用户故事：** 作为系统，我需要根据用户配置的 Cron 表达式准时触发签到任务，以确保签到按时执行。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Task_Scheduler 启动时，THE Task_Scheduler SHALL 从数据库加载所有 `is_enabled=True` 的任务并注册到 Celery Beat 调度器
|
||
2. WHEN Celery Beat 根据 Cron_Expression 触发一个任务，THE Task_Scheduler SHALL 向消息队列发送包含 `task_id` 和 `account_id` 的签到消息
|
||
3. WHEN 新任务被创建或现有任务被更新，THE Task_Scheduler SHALL 动态更新 Celery Beat 的调度配置而无需重启服务
|
||
4. IF 任务执行失败，THEN THE Task_Scheduler SHALL 按照配置的重试策略（最多3次，间隔60秒）进行重试
|
||
5. WHILE Task_Scheduler 运行中，THE Task_Scheduler SHALL 使用 Redis 分布式锁确保同一任务不会被重复调度
|
||
|
||
### 需求 6：签到执行引擎
|
||
|
||
**用户故事：** 作为系统，我需要真正执行微博超话签到操作，并将结果持久化到数据库，以替代当前的 Mock 实现。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Signin_Executor 从消息队列接收到签到任务，THE Signin_Executor SHALL 从数据库查询对应的 Weibo_Account 信息（替代 Mock 数据）
|
||
2. WHEN 执行签到前，THE Signin_Executor SHALL 解密 Cookie 并验证其有效性
|
||
3. WHEN Cookie 有效时，THE Signin_Executor SHALL 获取该账号关注的超话列表并逐一执行签到
|
||
4. WHEN 单个超话签到完成后，THE Signin_Executor SHALL 将结果（成功/失败/已签到、奖励信息、错误信息）写入 `signin_logs` 表
|
||
5. IF Cookie 已失效，THEN THE Signin_Executor SHALL 将账号状态更新为 "invalid_cookie" 并终止该账号的签到流程
|
||
6. IF 签到过程中遇到网络错误，THEN THE Signin_Executor SHALL 记录错误日志并将该超话的签到状态标记为 "failed_network"
|
||
|
||
### 需求 7：反爬虫防护
|
||
|
||
**用户故事：** 作为系统，我需要在执行签到时采取反爬虫措施，以降低被微博风控系统检测和封禁的风险。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 执行签到请求时，THE Signin_Executor SHALL 在每次请求之间插入随机延迟（1-3秒可配置）
|
||
2. WHEN 构造 HTTP 请求时，THE Signin_Executor SHALL 从预定义的 User-Agent 列表中随机选择一个
|
||
3. WHEN 代理池服务可用时，THE Signin_Executor SHALL 为每次签到请求分配一个代理 IP
|
||
4. IF 代理池服务不可用，THEN THE Signin_Executor SHALL 使用直连方式继续执行签到并记录警告日志
|
||
|
||
### 需求 8：签到日志与查询
|
||
|
||
**用户故事：** 作为用户，我希望能够查看每个微博账号的签到历史记录，以便了解签到执行情况。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 用户请求查看某个账号的签到日志，THE API_Service SHALL 返回按时间倒序排列的 Signin_Log 列表
|
||
2. WHEN 用户请求签到日志时提供分页参数，THE API_Service SHALL 返回对应页码的日志数据和总记录数
|
||
3. WHEN 用户请求签到日志时提供状态过滤参数，THE API_Service SHALL 仅返回匹配该状态的日志记录
|
||
4. THE API_Service SHALL 对签到日志查询接口要求有效的 JWT Access Token 认证
|
||
5. IF 用户尝试查看不属于自己账号的签到日志，THEN THE API_Service SHALL 返回 403 Forbidden 错误
|
||
|
||
### 需求 9：统一 API 响应格式与错误处理
|
||
|
||
**用户故事：** 作为 API 消费者，我希望所有接口返回统一格式的响应，以便前端能够一致地处理成功和错误情况。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE API_Service SHALL 对所有成功响应返回 `{"success": true, "data": ..., "message": ...}` 格式
|
||
2. THE API_Service SHALL 对所有错误响应返回 `{"success": false, "data": null, "message": ..., "error": {"code": ..., "details": [...]}}` 格式
|
||
3. WHEN 请求参数校验失败，THE API_Service SHALL 返回 400 状态码，并在 `error.details` 中列出每个字段的具体错误
|
||
4. WHEN 未认证用户访问受保护接口，THE API_Service SHALL 返回 401 状态码和标准错误响应
|
||
|