123

.kiro/specs/multi-user-signin/tasks.md

@@ -0,0 +1,185 @@
+# 实现计划：Weibo-HotSign 多用户签到系统
+
+## 概述
+
+按照自底向上的顺序实现：先构建共享基础层，再逐步实现各微服务。每个阶段包含核心实现和对应的测试任务。
+
+## Tasks
+
+- [x] 1. 创建共享模块 (shared/)
+  - [x] 1.1 创建 `backend/shared/` 包结构和共享配置
+    - 创建 `shared/__init__.py`、`shared/config.py`
+    - 配置项包括 DATABASE_URL、REDIS_URL、JWT_SECRET_KEY、COOKIE_ENCRYPTION_KEY
+    - 使用 pydantic-settings 从环境变量加载
+    - _Requirements: 10.1, 10.2_
+  - [x] 1.2 创建共享 ORM 模型和数据库连接管理
+    - 创建 `shared/models/base.py`：AsyncEngine、AsyncSessionLocal、Base、get_db()
+    - 创建 `shared/models/user.py`：User 模型（含 accounts relationship）
+    - 创建 `shared/models/account.py`：Account 模型（含 tasks、signin_logs relationship）
+    - 创建 `shared/models/task.py`：Task 模型
+    - 创建 `shared/models/signin_log.py`：SigninLog 模型
+    - 所有模型与 `init-db.sql` 中的表结构对齐
+    - _Requirements: 10.1, 10.2, 10.3_
+  - [x] 1.3 实现 Cookie 加密/解密工具 (`shared/crypto.py`)
+    - 使用 pycryptodome 实现 AES-256-GCM 加密/解密
+    - `encrypt_cookie(plaintext, key) -> (ciphertext_b64, iv_b64)`
+    - `decrypt_cookie(ciphertext_b64, iv_b64, key) -> plaintext`
+    - 密钥从环境变量 COOKIE_ENCRYPTION_KEY 派生（使用 SHA-256 哈希为32字节）
+    - _Requirements: 3.1, 3.2, 10.4_
+  - [ ]* 1.4 编写 Cookie 加密 Round-trip 属性测试
+    - **Property 1: Cookie 加密 Round-trip**
+    - 使用 hypothesis 生成随机字符串，验证 encrypt 后 decrypt 还原
+    - **Validates: Requirements 3.1, 3.2, 3.3**
+  - [x] 1.5 实现统一响应格式工具 (`shared/response.py`)
+    - `success_response(data, message)` 返回标准成功格式
+    - `error_response(message, code, details, status_code)` 返回标准错误格式
+    - _Requirements: 9.1, 9.2_
+
+- [x] 2. 重构 Auth_Service（Token 刷新机制）
+  - [x] 2.1 重构 Auth_Service 使用 shared 模块
+    - 修改 `auth_service/app/main.py` 导入 shared models 和 get_db
+    - 删除 `auth_service/app/models/database.py` 中的重复 User 模型定义
+    - 更新 `auth_service/app/services/auth_service.py` 使用 shared User 模型
+    - _Requirements: 10.3_
+  - [x] 2.2 实现 Refresh Token 机制
+    - 在 `auth_service/app/utils/security.py` 中添加 `create_refresh_token()` 和 `verify_refresh_token()`
+    - Refresh Token 使用 Redis 存储（key: `refresh_token:{hash}`, value: `user_id`, TTL: 7天）
+    - 登录接口返回 access_token + refresh_token
+    - 实现 `/auth/refresh` 端点：验证旧 token → 删除旧 token → 生成新 token 对（Token Rotation）
+    - 更新 `auth_service/app/schemas/user.py` 添加 RefreshToken 相关 schema
+    - _Requirements: 1.3, 1.5, 1.6_
+  - [x] 2.3 为 Auth_Service 所有响应应用统一格式
+    - 注册、登录、刷新、获取用户信息接口使用 `shared/response.py` 格式化响应
+    - 注册全局异常处理器（HTTPException、RequestValidationError）
+    - _Requirements: 9.1, 9.2, 9.3, 9.4_
+  - [ ]* 2.4 编写认证流程属性测试
+    - **Property 2: 用户注册后可登录获取信息**
+    - **Property 3: 用户名/邮箱唯一性约束**
+    - **Property 4: 无效凭证登录拒绝**
+    - **Property 5: Refresh Token 轮换**
+    - **Property 6: 弱密码拒绝**
+    - **Validates: Requirements 1.1-1.8**
+
+- [x] 3. Checkpoint - 确保共享模块和认证服务测试通过
+  - 运行所有测试，确认 shared 模块和 auth_service 工作正常
+  - 如有问题请向用户确认
+
+- [x] 4. 实现 API_Service（账号管理）
+  - [x] 4.1 创建 API_Service 基础结构
+    - 创建 `api_service/app/__init__.py`、`main.py`、`config.py`、`dependencies.py`
+    - `main.py`：FastAPI 应用，注册 CORS、全局异常处理器、路由
+    - `dependencies.py`：JWT 认证依赖（`get_current_user`），复用 shared 的 JWT 验证逻辑
+    - _Requirements: 2.8, 9.1, 9.2, 9.3, 9.4_
+  - [x] 4.2 实现微博账号 CRUD 路由
+    - 创建 `api_service/app/schemas/account.py`：AccountCreate、AccountUpdate、AccountResponse
+    - 创建 `api_service/app/routers/accounts.py`：
+      - `POST /api/v1/accounts`：加密 Cookie 后存储，状态初始化为 "pending"
+      - `GET /api/v1/accounts`：返回当前用户的账号列表（不含 Cookie 明文）
+      - `GET /api/v1/accounts/{id}`：返回账号详情
+      - `PUT /api/v1/accounts/{id}`：更新备注或 Cookie（更新 Cookie 时重新加密）
+      - `DELETE /api/v1/accounts/{id}`：删除账号（级联删除 tasks 和 logs）
+    - 所有接口验证资源归属（user_id 匹配）
+    - _Requirements: 2.1-2.8_
+  - [ ]* 4.3 编写账号管理属性测试
+    - **Property 7: 账号创建与列表一致性**
+    - **Property 8: 账号详情 Round-trip**
+    - **Property 9: 账号更新反映**
+    - **Property 10: 账号删除级联**
+    - **Property 11: 跨用户资源隔离**
+    - **Property 12: 受保护接口认证要求**
+    - **Validates: Requirements 2.1-2.8, 4.6, 8.5, 8.4, 9.4**
+
+- [-] 5. 实现 API_Service（任务配置）
+  - [x] 5.1 实现签到任务 CRUD 路由
+    - 创建 `api_service/app/schemas/task.py`：TaskCreate、TaskUpdate、TaskResponse
+    - 创建 `api_service/app/routers/tasks.py`：
+      - `POST /api/v1/accounts/{id}/tasks`：验证 Cron 表达式有效性，创建任务
+      - `GET /api/v1/accounts/{id}/tasks`：获取账号的任务列表
+      - `PUT /api/v1/tasks/{id}`：更新任务（启用/禁用）
+      - `DELETE /api/v1/tasks/{id}`：删除任务
+    - 使用 `croniter` 库验证 Cron 表达式
+    - 任务创建/更新/删除时通过 Redis pub/sub 通知 Task_Scheduler
+    - _Requirements: 4.1-4.6_
+  - [ ]* 5.2 编写任务配置属性测试
+    - **Property 13: 有效 Cron 表达式创建任务**
+    - **Property 14: 无效 Cron 表达式拒绝**
+    - **Property 15: 任务启用/禁用切换**
+    - **Property 16: 任务删除**
+    - **Validates: Requirements 4.1-4.6**
+
+- [x] 6. 实现 API_Service（签到日志查询）
+  - [x] 6.1 实现签到日志查询路由
+    - 创建 `api_service/app/schemas/signin_log.py`：SigninLogResponse、PaginatedResponse
+    - 创建 `api_service/app/routers/signin_logs.py`：
+      - `GET /api/v1/accounts/{id}/signin-logs`：支持分页（page, size）和状态过滤（status）
+      - 返回按 `signed_at` 降序排列的日志
+      - 返回总记录数用于前端分页
+    - 验证账号归属权限
+    - _Requirements: 8.1-8.5_
+  - [ ]* 6.2 编写签到日志查询属性测试
+    - **Property 23: 签到日志时间倒序**
+    - **Property 24: 签到日志分页**
+    - **Property 25: 签到日志状态过滤**
+    - **Validates: Requirements 8.1-8.3**
+
+- [ ] 7. Checkpoint - 确保 API_Service 所有测试通过
+  - 运行所有测试，确认账号管理、任务配置、日志查询功能正常
+  - 如有问题请向用户确认
+
+- [ ] 8. 重构 Task_Scheduler（真实数据库交互）
+  - [ ] 8.1 重构 Task_Scheduler 使用 shared 模块
+    - 修改 `task_scheduler/app/celery_app.py` 导入 shared models
+    - 实现 `load_scheduled_tasks()`：从 DB 查询 `is_enabled=True` 的 Task，动态注册到 Celery Beat
+    - 实现 Redis pub/sub 监听：接收任务变更通知，动态更新调度
+    - 替换 `signin_tasks.py` 中的 mock 账号列表为真实 DB 查询
+    - _Requirements: 5.1, 5.2, 5.3_
+  - [ ] 8.2 实现分布式锁和重试机制
+    - 使用 Redis SETNX 实现分布式锁，防止同一任务重复调度
+    - 配置 Celery 任务重试：`max_retries=3`、`default_retry_delay=60`
+    - _Requirements: 5.4, 5.5_
+  - [ ]* 8.3 编写调度器属性测试
+    - **Property 17: 调度器加载已启用任务**
+    - **Property 18: 分布式锁防重复调度**
+    - **Validates: Requirements 5.1, 5.5**
+
+- [ ] 9. 重构 Signin_Executor（真实数据库交互）
+  - [ ] 9.1 重构 Signin_Executor 使用 shared 模块
+    - 修改 `signin_service.py` 中的 `_get_account_info()` 从 DB 查询真实 Account 数据
+    - 修改 `weibo_client.py` 中的 `_decrypt_cookies()` 使用 `shared/crypto.py`
+    - 实现签到结果写入 `signin_logs` 表（替代 mock）
+    - 实现 Cookie 失效时更新 `account.status = "invalid_cookie"`
+    - _Requirements: 6.1, 6.2, 6.4, 6.5_
+  - [ ] 9.2 实现反爬虫防护模块
+    - 实现随机延迟函数：返回 `[min, max]` 范围内的随机值
+    - 实现 User-Agent 轮换：从预定义列表中随机选择
+    - 实现代理池集成：调用 proxy pool 服务获取代理，不可用时降级为直连
+    - _Requirements: 7.1, 7.2, 7.3, 7.4_
+  - [ ]* 9.3 编写签到执行属性测试
+    - **Property 19: 签到结果持久化**
+    - **Property 20: Cookie 失效时更新账号状态**
+    - **Property 21: 随机延迟范围**
+    - **Property 22: User-Agent 来源**
+    - **Validates: Requirements 6.1, 6.4, 6.5, 7.1, 7.2**
+
+- [ ] 10. 更新 Dockerfile 和集成配置
+  - [ ] 10.1 更新 `backend/Dockerfile`
+    - 在每个构建阶段添加 `COPY shared/ ./shared/`
+    - 确保 shared 模块在所有服务容器中可用
+    - _Requirements: 10.1, 10.3_
+  - [ ] 10.2 更新 `backend/requirements.txt`
+    - 添加 `croniter`（Cron 表达式解析）
+    - 添加 `hypothesis`（属性测试）
+    - 添加 `pytest`、`pytest-asyncio`（测试框架）
+    - 确认 `pycryptodome`、`redis`、`celery` 等已存在
+
+- [ ] 11. 最终 Checkpoint - 全量测试
+  - 运行所有单元测试和属性测试
+  - 验证各服务可独立启动
+  - 如有问题请向用户确认
+
+## 备注
+
+- 标记 `*` 的任务为可选测试任务，可跳过以加快 MVP 进度
+- 每个任务引用了具体的需求编号以确保可追溯性
+- 属性测试使用 `hypothesis` 库，每个测试至少运行 100 次迭代
+- Checkpoint 任务用于阶段性验证，确保增量开发的正确性