weibo_signin/.kiro/specs/multi-user-signin/requirements.md

需求文档：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 状态码和标准错误响应