123
This commit is contained in:
566
.kiro/specs/multi-user-signin/design.md
Normal file
566
.kiro/specs/multi-user-signin/design.md
Normal file
@@ -0,0 +1,566 @@
|
||||
# 设计文档：Weibo-HotSign 多用户签到系统
|
||||
|
||||
## 概述
|
||||
|
||||
本设计文档描述 Weibo-HotSign 系统的架构重构与核心功能实现方案。核心目标是：
|
||||
|
||||
1. 引入 `backend/shared/` 共享模块，统一 ORM 模型、数据库连接和加密工具，消除各服务间的代码重复
|
||||
2. 完善 `auth_service`，实现 Refresh Token 机制
|
||||
3. 从零实现 `api_service`，提供微博账号 CRUD、任务配置和签到日志查询 API
|
||||
4. 将 `signin_executor` 和 `task_scheduler` 中的 Mock 实现替换为真实数据库交互
|
||||
5. 所有 API 遵循统一响应格式
|
||||
|
||||
技术栈：Python 3.11 + FastAPI + SQLAlchemy (async) + Celery + MySQL (aiomysql) + Redis
|
||||
|
||||
## 架构
|
||||
|
||||
### 重构后的服务架构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "客户端"
|
||||
FE[Web Frontend / API Client]
|
||||
end
|
||||
|
||||
subgraph "后端服务层"
|
||||
API[API_Service :8000<br/>账号/任务/日志管理]
|
||||
AUTH[Auth_Service :8001<br/>注册/登录/Token刷新]
|
||||
SCHED[Task_Scheduler<br/>Celery Beat]
|
||||
EXEC[Signin_Executor<br/>Celery Worker]
|
||||
end
|
||||
|
||||
subgraph "共享层"
|
||||
SHARED[shared/<br/>ORM Models + DB Session<br/>+ Crypto Utils + Response Format]
|
||||
end
|
||||
|
||||
subgraph "基础设施"
|
||||
MYSQL[(MySQL)]
|
||||
REDIS[(Redis<br/>Cache + Message Queue)]
|
||||
PROXY[Proxy Pool]
|
||||
end
|
||||
|
||||
FE -->|REST API| API
|
||||
FE -->|REST API| AUTH
|
||||
API -->|导入| SHARED
|
||||
AUTH -->|导入| SHARED
|
||||
SCHED -->|导入| SHARED
|
||||
EXEC -->|导入| SHARED
|
||||
SHARED -->|aiomysql| MYSQL
|
||||
SCHED -->|发布任务| REDIS
|
||||
EXEC -->|消费任务| REDIS
|
||||
EXEC -->|获取代理| PROXY
|
||||
EXEC -->|签到请求| WEIBO[Weibo.com]
|
||||
|
||||
```
|
||||
|
||||
### 关键架构决策
|
||||
|
||||
1. **共享模块而非微服务间 RPC**：各服务通过 Python 包导入 `shared/` 模块访问数据库，而非通过 HTTP 调用其他服务查询数据。这简化了部署，减少了网络延迟，适合当前规模。
|
||||
2. **API_Service 作为唯一对外网关**：所有账号管理、任务配置、日志查询 API 集中在 `api_service` 中，`auth_service` 仅负责认证。
|
||||
3. **Celery 同时承担调度和执行**：`task_scheduler` 运行 Celery Beat（调度），`signin_executor` 运行 Celery Worker（执行），通过 Redis 消息队列解耦。
|
||||
4. **Dockerfile 多阶段构建**：保持现有的多阶段 Dockerfile 结构，新增 `shared/` 目录的 COPY 步骤。
|
||||
|
||||
### 目录结构（重构后）
|
||||
|
||||
```
|
||||
backend/
|
||||
├── shared/ # 新增：共享模块
|
||||
│ ├── __init__.py
|
||||
│ ├── models/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── base.py # SQLAlchemy Base + engine + session
|
||||
│ │ ├── user.py # User ORM model
|
||||
│ │ ├── account.py # Account ORM model
|
||||
│ │ ├── task.py # Task ORM model
|
||||
│ │ └── signin_log.py # SigninLog ORM model
|
||||
│ ├── crypto.py # AES-256-GCM 加密/解密工具
|
||||
│ ├── response.py # 统一响应格式工具
|
||||
│ └── config.py # 共享配置（DB URL, Redis URL 等）
|
||||
├── auth_service/
|
||||
│ └── app/
|
||||
│ ├── main.py # 重构：使用 shared models
|
||||
│ ├── config.py
|
||||
│ ├── schemas/
|
||||
│ │ └── user.py # 增加 RefreshToken schema
|
||||
│ ├── services/
|
||||
│ │ └── auth_service.py # 增加 refresh token 逻辑
|
||||
│ └── utils/
|
||||
│ └── security.py # 增加 refresh token 生成/验证
|
||||
├── api_service/
|
||||
│ └── app/
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py # 新增：FastAPI 应用入口
|
||||
│ ├── config.py
|
||||
│ ├── dependencies.py # JWT 认证依赖
|
||||
│ ├── schemas/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── account.py # 账号请求/响应 schema
|
||||
│ │ ├── task.py # 任务请求/响应 schema
|
||||
│ │ └── signin_log.py # 签到日志响应 schema
|
||||
│ └── routers/
|
||||
│ ├── __init__.py
|
||||
│ ├── accounts.py # 账号 CRUD 路由
|
||||
│ ├── tasks.py # 任务 CRUD 路由
|
||||
│ └── signin_logs.py # 签到日志查询路由
|
||||
├── signin_executor/
|
||||
│ └── app/
|
||||
│ ├── main.py
|
||||
│ ├── config.py
|
||||
│ ├── services/
|
||||
│ │ ├── signin_service.py # 重构：使用 shared models 查询真实数据
|
||||
│ │ └── weibo_client.py # 重构：实现真实加密/解密
|
||||
│ └── models/
|
||||
│ └── signin_models.py # 保留 Pydantic 请求/响应模型
|
||||
├── task_scheduler/
|
||||
│ └── app/
|
||||
│ ├── celery_app.py # 重构：从 DB 动态加载任务
|
||||
│ ├── config.py
|
||||
│ └── tasks/
|
||||
│ └── signin_tasks.py # 重构：使用真实 DB 查询
|
||||
├── Dockerfile # 更新：各阶段 COPY shared/
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
## 组件与接口
|
||||
|
||||
### 1. shared 模块
|
||||
|
||||
#### 1.1 数据库连接管理 (`shared/models/base.py`)
|
||||
|
||||
```python
|
||||
# 提供异步 engine 和 session factory
|
||||
# 所有服务通过 get_db() 获取 AsyncSession
|
||||
async def get_db() -> AsyncGenerator[AsyncSession, None]:
|
||||
async with AsyncSessionLocal() as session:
|
||||
try:
|
||||
yield session
|
||||
finally:
|
||||
await session.close()
|
||||
```
|
||||
|
||||
#### 1.2 加密工具 (`shared/crypto.py`)
|
||||
|
||||
```python
|
||||
def encrypt_cookie(plaintext: str, key: bytes) -> tuple[str, str]:
|
||||
"""AES-256-GCM 加密，返回 (密文base64, iv_base64)"""
|
||||
|
||||
def decrypt_cookie(ciphertext_b64: str, iv_b64: str, key: bytes) -> str:
|
||||
"""AES-256-GCM 解密，返回原始 Cookie 字符串"""
|
||||
```
|
||||
|
||||
#### 1.3 统一响应格式 (`shared/response.py`)
|
||||
|
||||
```python
|
||||
def success_response(data: Any, message: str = "Operation successful") -> dict
|
||||
def error_response(message: str, code: str, details: list = None, status_code: int = 400) -> JSONResponse
|
||||
```
|
||||
|
||||
### 2. Auth_Service 接口
|
||||
|
||||
| 方法 | 路径 | 描述 | 需求 |
|
||||
|------|------|------|------|
|
||||
| POST | `/auth/register` | 用户注册 | 1.1, 1.2, 1.8 |
|
||||
| POST | `/auth/login` | 用户登录，返回 access_token + refresh_token | 1.3, 1.4 |
|
||||
| POST | `/auth/refresh` | 刷新 Token | 1.5, 1.6 |
|
||||
| GET | `/auth/me` | 获取当前用户信息 | 1.7 |
|
||||
|
||||
### 3. API_Service 接口
|
||||
|
||||
| 方法 | 路径 | 描述 | 需求 |
|
||||
|------|------|------|------|
|
||||
| POST | `/api/v1/accounts` | 添加微博账号 | 2.1, 2.7, 2.8 |
|
||||
| GET | `/api/v1/accounts` | 获取账号列表 | 2.2, 2.8 |
|
||||
| GET | `/api/v1/accounts/{id}` | 获取账号详情 | 2.3, 2.6, 2.8 |
|
||||
| PUT | `/api/v1/accounts/{id}` | 更新账号信息 | 2.4, 2.6, 2.8 |
|
||||
| DELETE | `/api/v1/accounts/{id}` | 删除账号 | 2.5, 2.6, 2.8 |
|
||||
| POST | `/api/v1/accounts/{id}/tasks` | 创建签到任务 | 4.1, 4.2, 4.6 |
|
||||
| GET | `/api/v1/accounts/{id}/tasks` | 获取任务列表 | 4.3 |
|
||||
| PUT | `/api/v1/tasks/{id}` | 启用/禁用任务 | 4.4 |
|
||||
| DELETE | `/api/v1/tasks/{id}` | 删除任务 | 4.5 |
|
||||
| GET | `/api/v1/accounts/{id}/signin-logs` | 查询签到日志 | 8.1, 8.2, 8.3, 8.4, 8.5 |
|
||||
|
||||
### 4. Task_Scheduler 内部接口
|
||||
|
||||
Task_Scheduler 不对外暴露 HTTP 接口，通过以下方式工作：
|
||||
|
||||
- **启动时**：从 DB 加载 `is_enabled=True` 的任务，注册到 Celery Beat
|
||||
- **运行时**：根据 Cron 表达式触发 `execute_signin_task` Celery task
|
||||
- **动态更新**：通过 Redis pub/sub 接收任务变更通知，动态更新调度
|
||||
|
||||
### 5. Signin_Executor 内部流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Queue as Redis Queue
|
||||
participant Exec as Signin_Executor
|
||||
participant DB as MySQL
|
||||
participant Weibo as Weibo.com
|
||||
participant Proxy as Proxy Pool
|
||||
|
||||
Queue->>Exec: 消费签到任务 (task_id, account_id)
|
||||
Exec->>DB: 查询 Account (by account_id)
|
||||
Exec->>Exec: 解密 Cookie (AES-256-GCM)
|
||||
Exec->>Weibo: 验证 Cookie 有效性
|
||||
alt Cookie 无效
|
||||
Exec->>DB: 更新 account.status = "invalid_cookie"
|
||||
Exec->>DB: 写入失败日志
|
||||
else Cookie 有效
|
||||
Exec->>Weibo: 获取超话列表
|
||||
loop 每个未签到超话
|
||||
Exec->>Proxy: 获取代理 IP
|
||||
Exec->>Exec: 随机延迟 (1-3s)
|
||||
Exec->>Weibo: 执行签到请求
|
||||
Exec->>DB: 写入 signin_log
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## 数据模型
|
||||
|
||||
### ORM 模型定义（shared/models/）
|
||||
|
||||
#### User 模型
|
||||
|
||||
```python
|
||||
class User(Base):
|
||||
__tablename__ = "users"
|
||||
id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
|
||||
username = Column(String(50), unique=True, nullable=False, index=True)
|
||||
email = Column(String(255), unique=True, nullable=False, index=True)
|
||||
hashed_password = Column(String(255), nullable=False)
|
||||
created_at = Column(DateTime, server_default=func.now())
|
||||
is_active = Column(Boolean, default=True)
|
||||
# Relationships
|
||||
accounts = relationship("Account", back_populates="user", cascade="all, delete-orphan")
|
||||
```
|
||||
|
||||
#### Account 模型
|
||||
|
||||
```python
|
||||
class Account(Base):
|
||||
__tablename__ = "accounts"
|
||||
id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
|
||||
user_id = Column(String(36), ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
|
||||
weibo_user_id = Column(String(20), nullable=False)
|
||||
remark = Column(String(100))
|
||||
encrypted_cookies = Column(Text, nullable=False)
|
||||
iv = Column(String(32), nullable=False)
|
||||
status = Column(String(20), default="pending") # pending, active, invalid_cookie, banned
|
||||
last_checked_at = Column(DateTime, nullable=True)
|
||||
created_at = Column(DateTime, server_default=func.now())
|
||||
# Relationships
|
||||
user = relationship("User", back_populates="accounts")
|
||||
tasks = relationship("Task", back_populates="account", cascade="all, delete-orphan")
|
||||
signin_logs = relationship("SigninLog", back_populates="account")
|
||||
```
|
||||
|
||||
#### Task 模型
|
||||
|
||||
```python
|
||||
class Task(Base):
|
||||
__tablename__ = "tasks"
|
||||
id = Column(String(36), primary_key=True, default=lambda: str(uuid4()))
|
||||
account_id = Column(String(36), ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False)
|
||||
cron_expression = Column(String(50), nullable=False)
|
||||
is_enabled = Column(Boolean, default=True)
|
||||
created_at = Column(DateTime, server_default=func.now())
|
||||
# Relationships
|
||||
account = relationship("Account", back_populates="tasks")
|
||||
```
|
||||
|
||||
#### SigninLog 模型
|
||||
|
||||
```python
|
||||
class SigninLog(Base):
|
||||
__tablename__ = "signin_logs"
|
||||
id = Column(BigInteger, primary_key=True, autoincrement=True)
|
||||
account_id = Column(String(36), ForeignKey("accounts.id"), nullable=False)
|
||||
topic_title = Column(String(100))
|
||||
status = Column(String(20), nullable=False) # success, failed_already_signed, failed_network, failed_banned
|
||||
reward_info = Column(JSON, nullable=True)
|
||||
error_message = Column(Text, nullable=True)
|
||||
signed_at = Column(DateTime, server_default=func.now())
|
||||
# Relationships
|
||||
account = relationship("Account", back_populates="signin_logs")
|
||||
```
|
||||
|
||||
### Refresh Token 存储
|
||||
|
||||
Refresh Token 使用 Redis 存储，key 格式为 `refresh_token:{token_hash}`，value 为 `user_id`，TTL 为 7 天。这避免了在数据库中增加额外的表，同时利用 Redis 的自动过期机制。
|
||||
|
||||
```python
|
||||
# 存储
|
||||
await redis.setex(f"refresh_token:{token_hash}", 7 * 24 * 3600, user_id)
|
||||
|
||||
# 验证
|
||||
user_id = await redis.get(f"refresh_token:{token_hash}")
|
||||
|
||||
# 刷新时删除旧 token，生成新 token（Token Rotation）
|
||||
await redis.delete(f"refresh_token:{old_token_hash}")
|
||||
await redis.setex(f"refresh_token:{new_token_hash}", 7 * 24 * 3600, user_id)
|
||||
```
|
||||
|
||||
## 正确性属性 (Correctness Properties)
|
||||
|
||||
*属性（Property）是指在系统所有有效执行中都应成立的特征或行为——本质上是对系统应做什么的形式化陈述。属性是人类可读规格说明与机器可验证正确性保证之间的桥梁。*
|
||||
|
||||
### Property 1: Cookie 加密 Round-trip
|
||||
|
||||
*For any* 有效的 Cookie 字符串，使用 AES-256-GCM 加密后再用相同密钥和 IV 解密，应产生与原始字符串完全相同的结果。
|
||||
|
||||
**Validates: Requirements 3.1, 3.2, 3.3**
|
||||
|
||||
### Property 2: 用户注册后可登录获取信息
|
||||
|
||||
*For any* 有效的注册信息（用户名、邮箱、符合强度要求的密码），注册后使用相同邮箱和密码登录应成功返回 Token，使用该 Token 调用 `/auth/me` 应返回与注册时一致的用户名和邮箱。
|
||||
|
||||
**Validates: Requirements 1.1, 1.3, 1.7**
|
||||
|
||||
### Property 3: 用户名/邮箱唯一性约束
|
||||
|
||||
*For any* 已注册的用户，使用相同用户名或相同邮箱再次注册应返回 409 Conflict 错误。
|
||||
|
||||
**Validates: Requirements 1.2**
|
||||
|
||||
### Property 4: 无效凭证登录拒绝
|
||||
|
||||
*For any* 不存在的邮箱或错误的密码，登录请求应返回 401 Unauthorized 错误。
|
||||
|
||||
**Validates: Requirements 1.4**
|
||||
|
||||
### Property 5: Refresh Token 轮换
|
||||
|
||||
*For any* 已登录用户的有效 Refresh Token，刷新操作应返回新的 Access Token 和新的 Refresh Token，且旧的 Refresh Token 应失效（再次使用应返回 401）。
|
||||
|
||||
**Validates: Requirements 1.5, 1.6**
|
||||
|
||||
### Property 6: 弱密码拒绝
|
||||
|
||||
*For any* 不满足强度要求的密码（缺少大写字母、小写字母、数字或特殊字符，或长度不足8位），注册请求应返回 400 Bad Request。
|
||||
|
||||
**Validates: Requirements 1.8**
|
||||
|
||||
### Property 7: 账号创建与列表一致性
|
||||
|
||||
*For any* 用户和任意数量的有效微博账号数据，创建 N 个账号后查询列表应返回恰好 N 条记录，每条记录的状态应为 "pending"，且响应中不应包含解密后的 Cookie 明文。
|
||||
|
||||
**Validates: Requirements 2.1, 2.2, 2.7**
|
||||
|
||||
### Property 8: 账号详情 Round-trip
|
||||
|
||||
*For any* 已创建的微博账号，通过详情接口查询应返回与创建时一致的备注和微博用户 ID。
|
||||
|
||||
**Validates: Requirements 2.3**
|
||||
|
||||
### Property 9: 账号更新反映
|
||||
|
||||
*For any* 已创建的微博账号和任意新的备注字符串，更新备注后再次查询应返回更新后的值。
|
||||
|
||||
**Validates: Requirements 2.4**
|
||||
|
||||
### Property 10: 账号删除级联
|
||||
|
||||
*For any* 拥有关联 Task 和 SigninLog 的账号，删除该账号后，查询该账号的 Task 列表和 SigninLog 列表应返回空结果。
|
||||
|
||||
**Validates: Requirements 2.5**
|
||||
|
||||
### Property 11: 跨用户资源隔离
|
||||
|
||||
*For any* 两个不同用户 A 和 B，用户 A 尝试访问、修改或删除用户 B 的账号、任务或签到日志时，应返回 403 Forbidden。
|
||||
|
||||
**Validates: Requirements 2.6, 4.6, 8.5**
|
||||
|
||||
### Property 12: 受保护接口认证要求
|
||||
|
||||
*For any* 受保护的 API 端点（账号管理、任务管理、日志查询），不携带 JWT Token 或携带无效 Token 的请求应返回 401 Unauthorized。
|
||||
|
||||
**Validates: Requirements 2.8, 8.4, 9.4**
|
||||
|
||||
### Property 13: 有效 Cron 表达式创建任务
|
||||
|
||||
*For any* 有效的 Cron 表达式和已存在的账号，创建任务应成功，且查询该账号的任务列表应包含新创建的任务。
|
||||
|
||||
**Validates: Requirements 4.1, 4.3**
|
||||
|
||||
### Property 14: 无效 Cron 表达式拒绝
|
||||
|
||||
*For any* 无效的 Cron 表达式字符串，创建任务请求应返回 400 Bad Request。
|
||||
|
||||
**Validates: Requirements 4.2**
|
||||
|
||||
### Property 15: 任务启用/禁用切换
|
||||
|
||||
*For any* 已创建的任务，切换 `is_enabled` 状态后查询应反映新的状态值。
|
||||
|
||||
**Validates: Requirements 4.4**
|
||||
|
||||
### Property 16: 任务删除
|
||||
|
||||
*For any* 已创建的任务，删除后查询该任务应返回 404 或不在列表中出现。
|
||||
|
||||
**Validates: Requirements 4.5**
|
||||
|
||||
### Property 17: 调度器加载已启用任务
|
||||
|
||||
*For any* 数据库中的任务集合，Task_Scheduler 启动时加载的任务数量应等于 `is_enabled=True` 的任务数量。
|
||||
|
||||
**Validates: Requirements 5.1**
|
||||
|
||||
### Property 18: 分布式锁防重复调度
|
||||
|
||||
*For any* 签到任务，同一时刻并发触发两次应只产生一次实际执行。
|
||||
|
||||
**Validates: Requirements 5.5**
|
||||
|
||||
### Property 19: 签到结果持久化
|
||||
|
||||
*For any* 签到执行结果（成功或失败），`signin_logs` 表中应存在对应的记录，且记录的 `account_id`、`status` 和 `topic_title` 与执行结果一致。
|
||||
|
||||
**Validates: Requirements 6.1, 6.4**
|
||||
|
||||
### Property 20: Cookie 失效时更新账号状态
|
||||
|
||||
*For any* Cookie 已失效的账号，执行签到时应将账号状态更新为 "invalid_cookie"。
|
||||
|
||||
**Validates: Requirements 6.5, 3.4**
|
||||
|
||||
### Property 21: 随机延迟范围
|
||||
|
||||
*For any* 调用反爬虫延迟函数的结果，延迟值应在配置的 `[min, max]` 范围内。
|
||||
|
||||
**Validates: Requirements 7.1**
|
||||
|
||||
### Property 22: User-Agent 来源
|
||||
|
||||
*For any* 调用 User-Agent 选择函数的结果，返回的 UA 字符串应属于预定义列表中的某一个。
|
||||
|
||||
**Validates: Requirements 7.2**
|
||||
|
||||
### Property 23: 签到日志时间倒序
|
||||
|
||||
*For any* 包含多条签到日志的账号，查询返回的日志列表应按 `signed_at` 降序排列。
|
||||
|
||||
**Validates: Requirements 8.1**
|
||||
|
||||
### Property 24: 签到日志分页
|
||||
|
||||
*For any* 包含 N 条日志的账号和分页参数 (page, size)，返回的记录数应等于 `min(size, N - (page-1)*size)` 且总记录数应等于 N。
|
||||
|
||||
**Validates: Requirements 8.2**
|
||||
|
||||
### Property 25: 签到日志状态过滤
|
||||
|
||||
*For any* 状态过滤参数，返回的所有日志记录的 `status` 字段应与过滤参数一致。
|
||||
|
||||
**Validates: Requirements 8.3**
|
||||
|
||||
### Property 26: 统一响应格式
|
||||
|
||||
*For any* API 调用，成功响应应包含 `success=true` 和 `data` 字段；错误响应应包含 `success=false`、`data=null` 和 `error` 字段。
|
||||
|
||||
**Validates: Requirements 9.1, 9.2, 9.3**
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 错误分类与处理策略
|
||||
|
||||
| 错误类型 | HTTP 状态码 | 错误码 | 处理策略 |
|
||||
|----------|------------|--------|----------|
|
||||
| 请求参数校验失败 | 400 | VALIDATION_ERROR | 返回字段级错误详情 |
|
||||
| 未认证 | 401 | UNAUTHORIZED | 返回标准 401 响应 |
|
||||
| 权限不足 | 403 | FORBIDDEN | 返回资源不可访问提示 |
|
||||
| 资源不存在 | 404 | NOT_FOUND | 返回资源未找到提示 |
|
||||
| 资源冲突 | 409 | CONFLICT | 返回冲突字段说明 |
|
||||
| 服务器内部错误 | 500 | INTERNAL_ERROR | 记录详细日志，返回通用错误提示 |
|
||||
|
||||
### 签到执行错误处理
|
||||
|
||||
- **Cookie 解密失败**：标记账号为 `invalid_cookie`，记录错误日志，终止该账号签到
|
||||
- **Cookie 验证失败**（微博返回未登录）：同上
|
||||
- **网络超时/连接错误**：记录 `failed_network` 日志，不更改账号状态（可能是临时问题）
|
||||
- **微博返回封禁**：标记账号为 `banned`，记录日志，发送通知
|
||||
- **代理池不可用**：降级为直连，记录警告日志
|
||||
- **Celery 任务失败**：自动重试最多3次，间隔60秒，最终失败记录日志
|
||||
|
||||
### 全局异常处理
|
||||
|
||||
所有 FastAPI 服务注册统一的异常处理器：
|
||||
|
||||
```python
|
||||
@app.exception_handler(HTTPException)
|
||||
async def http_exception_handler(request, exc):
|
||||
return error_response(exc.detail, f"HTTP_{exc.status_code}", status_code=exc.status_code)
|
||||
|
||||
@app.exception_handler(RequestValidationError)
|
||||
async def validation_exception_handler(request, exc):
|
||||
details = [{"field": e["loc"][-1], "message": e["msg"]} for e in exc.errors()]
|
||||
return error_response("Validation failed", "VALIDATION_ERROR", details, 400)
|
||||
```
|
||||
|
||||
## 测试策略
|
||||
|
||||
### 测试框架选择
|
||||
|
||||
- **单元测试**：`pytest` + `pytest-asyncio`（异步测试支持）
|
||||
- **属性测试**：`hypothesis`（Python 属性测试库）
|
||||
- **HTTP 测试**：`httpx` + FastAPI `TestClient`
|
||||
- **数据库测试**：使用 SQLite in-memory 或测试专用 MySQL 实例
|
||||
|
||||
### 测试分层
|
||||
|
||||
#### 1. 单元测试
|
||||
- 加密/解密函数的边界情况
|
||||
- 密码强度验证的各种组合
|
||||
- Cron 表达式验证
|
||||
- 响应格式化函数
|
||||
- 具体的错误场景（网络超时、解密失败等）
|
||||
|
||||
#### 2. 属性测试（Property-Based Testing）
|
||||
- 使用 `hypothesis` 库，每个属性测试至少运行 100 次迭代
|
||||
- 每个测试用注释标注对应的设计文档属性编号
|
||||
- 标注格式：`# Feature: multi-user-signin, Property {N}: {property_text}`
|
||||
- 每个正确性属性对应一个独立的属性测试函数
|
||||
|
||||
#### 3. 集成测试
|
||||
- API 端点的完整请求/响应流程
|
||||
- 数据库 CRUD 操作的正确性
|
||||
- 服务间通过 Redis 消息队列的交互
|
||||
- Celery 任务的调度和执行
|
||||
|
||||
### 属性测试配置
|
||||
|
||||
```python
|
||||
from hypothesis import given, settings, strategies as st
|
||||
|
||||
@settings(max_examples=100)
|
||||
@given(cookie=st.text(min_size=1, max_size=1000))
|
||||
def test_cookie_encryption_roundtrip(cookie):
|
||||
"""Feature: multi-user-signin, Property 1: Cookie 加密 Round-trip"""
|
||||
key = generate_test_key()
|
||||
ciphertext, iv = encrypt_cookie(cookie, key)
|
||||
decrypted = decrypt_cookie(ciphertext, iv, key)
|
||||
assert decrypted == cookie
|
||||
```
|
||||
|
||||
### 测试目录结构
|
||||
|
||||
```
|
||||
backend/
|
||||
├── tests/
|
||||
│ ├── conftest.py # 共享 fixtures（DB session, test client 等）
|
||||
│ ├── unit/
|
||||
│ │ ├── test_crypto.py # 加密/解密单元测试
|
||||
│ │ ├── test_password.py # 密码验证单元测试
|
||||
│ │ └── test_cron.py # Cron 表达式验证单元测试
|
||||
│ ├── property/
|
||||
│ │ ├── test_crypto_props.py # Property 1
|
||||
│ │ ├── test_auth_props.py # Property 2-6
|
||||
│ │ ├── test_account_props.py # Property 7-12
|
||||
│ │ ├── test_task_props.py # Property 13-18
|
||||
│ │ ├── test_signin_props.py # Property 19-22
|
||||
│ │ └── test_log_props.py # Property 23-26
|
||||
│ └── integration/
|
||||
│ ├── test_auth_flow.py # 完整认证流程
|
||||
│ ├── test_account_flow.py # 账号管理流程
|
||||
│ └── test_signin_flow.py # 签到执行流程
|
||||
```
|
||||
Reference in New Issue
Block a user