好的，这是一份为专业 Coding AI 模型或开发者编写的详细开发文档 (Development Document)。文档遵循常见的软件工程规范，旨在将一个概念转化为可实施的技术蓝图。

---

## **项目名称: Weibo-HotSign**

### **1. 项目概述 (Project Overview)**

#### 1.1. 项目简介
Weibo-HotSign 是一个分布式的、面向多用户的微博超话智能签到系统。它旨在通过自动化的方式，帮助用户定时、稳定地完成微博超话的签到任务，以获取积分和经验值。项目的核心挑战在于应对微博复杂的反爬虫机制，确保长期运行的稳定性和成功率。

#### 1.2. 核心价值主张
*   **多账户管理**: 为用户提供一个集中的平台来管理多个微博账号的签到任务。
*   **高稳定性与反爬虫**: 采用动态IP代理池、浏览器指纹模拟、智能Cookie管理及高级JS逆向（必要时）等技术，最大限度规避微博的风控策略，保障签到任务的成功率。
*   **用户友好**: 提供Web UI进行可视化管理，避免用户直接操作代码或配置文件。
*   **可观测性**: 实时日志、任务历史和状态监控，让用户清晰掌握每个账号的运作情况。
*   **通知系统**: 提供多种渠道的实时通知，让用户第一时间了解任务结果。

#### 1.3. 目标用户
*   拥有多个微博账号，希望自动化完成日常签到的普通用户。
*   希望通过技术手段研究反爬虫方案的开发者。
*   需要将此类自动化功能集成到自己系统中的第三方服务（通过API）。

---

### **2. 系统架构 (System Architecture)**

本项目采用基于微服务的架构，以实现模块间的解耦、独立部署和水平扩展。

#### 2.1. 架构图
```mermaid
graph TD
    subgraph User Interaction Layer
        A[Web Frontend (React/Vue)]
    end

    subgraph Backend Services Layer
        B[API Gateway / Main API Service (FastAPI)]
        C[Authentication Service (FastAPI)]
        D[Task Scheduler Service (Celery Beat)]
        E[Sign-in Executor Worker (Celery Worker)]
        F[Notification Hub Service (FastAPI)]
        G[Browser Automation Service (Node.js/Python)]
    end

    subgraph Core Infrastructure Layer
        H[(Message Queue: Redis/RabbitMQ)]
        I[(Cache & Session Store: Redis)]
        J[(Relational DB: PostgreSQL)]
        K[(Proxy Pool Manager)]
        L[(Browser Fingerprint Generator)]
    end

    subgraph External Systems
        M[Weibo.com]
        N[User Notification Channels (ServerChan, Email, etc.)]
        O[Payment Gateway (Future)]
    end

    A -->|HTTPS| B;
    B -->|AuthN/AuthZ| C;
    A -->|API Calls| B;
    
    D -->|Publishes Task| H;
    E -->|Consumes Task| H;
    
    E -->|Updates Status| J;
    E -->|Reads Config| J;
    E -->|Logs Result| J;
    
    E -->|Stores/Retrieves Session| I;
    D -->|Stores Schedule| J;
    
    E -->|Requests Proxy| K;
    K -->|Provides Proxy IP| E;
    
    E -->|Requests Fingerprint| L;
    L -->|Provides Fingerprint| E;
    
    E -->|Performs Action| M;
    G -->|Executes JS & Extracts Data| M;
    E -->|Delegates to| G;
    
    F -->|Sends Notification| N;
    
    B -->|Authenticated| O;

    style A fill:#D5F5E3
    style B fill:#EBDEF0
    style C fill:#EBDEF0
    style D fill:#EBDEF0
    style E fill:#EBDEF0
    style F fill:#EBDEF0
    style G fill:#EBDEF0
    style H fill:#FDF2E9
    style I fill:#FDF2E9
    style J fill:#FADBD8
    style K fill:#EAFAF1
    style L fill:#EAFAF1
    style M fill:#FDEBD0
    style N fill:#D6EAF8
    style O fill:#EBDEF0
```

#### 2.2. 组件职责描述
*   **Web Frontend**: 负责所有用户交互，包括登录注册、账号管理、任务配置、日志查看等。
*   **API Gateway / Main API Service**: 作为系统的唯一入口，负责请求路由、API组合、限流和初步的请求验证。
*   **Authentication Service**: 独立的认证授权服务，使用JWT或OAuth2.0标准，为所有服务提供统一的身份验证和权限校验。
*   **Task Scheduler Service**: 基于Celery Beat，负责解析用户配置的Cron表达式，并将签到任务发布到消息队列中。
*   **Sign-in Executor Worker**: 核心工作节点，消费消息队列中的任务，执行具体的登录、签到逻辑。此服务可水平扩展以应对高并发。
*   **Notification Hub Service**: 统一处理所有通知请求，并根据用户偏好分发至不同的渠道（Server酱、邮件等）。
*   **Browser Automation Service**: 独立的、无状态的浏览器服务。当遇到复杂的JS加密时，Executor Worker将通过API调用此服务来获取签名后的参数。此服务可使用Playwright或Puppeteer构建，并可独立集群部署。
*   **Message Queue (Redis/RabbitMQ)**: 实现异步和解耦的核心组件。Scheduler生产任务，Executor消费任务。
*   **Cache & Session Store (Redis)**: 存储短期数据，如用户会话、分布式锁、API速率限制计数器、以及所有微博账号的有效Cookies。
*   **Relational DB (PostgreSQL)**: 存储结构化核心业务数据，如用户信息、账号元数据、任务配置、签到历史记录。
*   **Proxy Pool Manager**: (可以是独立进程或一个服务) 负责维护一个高质量的代理IP池，提供健康检查、分配和回收机制。
*   **Browser Fingerprint Generator**: (可以是独立进程或一个库) 负责生成高仿真的浏览器指纹，供Executor Worker在发起请求时使用。

---

### **3. 核心技术选型 (Technology Stack)**

| 层级 | 技术组件 | 推荐技术 | 备选技术 | 目的 |
| :--- | :--- | :--- | :--- | :--- |
| **前端** | 框架 | React (Vite) | Vue 3 (Nuxt) | 构建动态、响应式的用户界面 |
| | 状态管理 | Redux Toolkit / Zustand | Pinia | 管理复杂的应用状态 |
| | UI库 | Ant Design / Material-UI | Element Plus | 快速搭建美观的界面 |
| **后端** | Web框架 | Python FastAPI | Node.js Express/NestJS | 高性能、易开发、自动生成API文档 |
| | ASGI服务器 | Uvicorn | Hypercorn | 运行FastAPI应用 |
| | 异步任务 | Celery | RQ (Redis Queue) | 分布式任务队列，处理后台任务 |
| | 消息代理 | Redis | RabbitMQ | Celery的消息中间件 |
| | ORM | SQLAlchemy (async) | Tortoise-ORM | 与PostgreSQL交互 |
| | 数据库 | PostgreSQL | MySQL | 存储核心业务数据，保证事务性和数据完整性 |
| | 缓存 | Redis | Memcached | 高速缓存、会话存储 |
| **基础设施**| 容器化 | Docker | Podman | 环境标准化、简化部署 |
| | 编排 | Docker Compose | Kubernetes (K8s) | 本地开发和生产环境部署 |
| | 反向代理 | Nginx | Traefik/Caddy | SSL终结、负载均衡、静态文件服务 |
| **浏览器自动化**| 库/工具 | Playwright (Python/Node) | Selenium | 模拟浏览器行为、对抗JS加密 |
| **运维** | CI/CD | GitHub Actions | GitLab CI/Jenkins | 自动化测试与部署 |
| | 监控 | Prometheus + Grafana | Zabbix | 系统指标监控 |
| | 日志 | ELK Stack (Elasticsearch, Logstash, Kibana) | Loki + Grafana | 集中式日志收集与分析 |

---

### **4. 模块详细设计 (Detailed Module Design)**

#### 4.1. 认证与授权模块 (`auth_service`)
*   **API端点**:
    *   `POST /auth/register`: 用户注册。
    *   `POST /auth/login`: 用户登录，返回JWT。
    *   `POST /auth/refresh`: 刷新JWT。
    *   `GET /auth/me`: 获取当前用户信息。
*   **数据库模型 (`users`)**: `id`, `username`, `email`, `hashed_password`, `created_at`, `is_active`。
*   **关键逻辑**: 使用 `bcrypt` 或 `argon2` 哈希密码。JWT包含 `user_id` 和权限声明。所有受保护的API都需通过中间件校验JWT的有效性。

#### 4.2. 账号与任务管理模块 (`api_service`)
*   **API端点 (示例)**:
    *   `POST /accounts`: 添加一个微博账号，需提交从前端获取的微博Cookie或通过二维码登录流程绑定的凭证。
    *   `GET /accounts`: 获取当前用户的所有微博账号列表及其状态。
    *   `PUT /accounts/{account_id}`: 更新账号信息（如备注、启用/禁用状态）。
    *   `DELETE /accounts/{account_id}`: 删除一个账号。
    *   `POST /tasks`: 为指定账号创建一个签到任务，接收Cron表达式和配置参数。
*   **数据库模型**:
    *   `accounts`: `id`, `user_id` (FK), `weibo_user_id`, `remark`, `encrypted_cookies`, `status` ('active', 'invalid_cookie', 'banned'), `last_check_time`.
    *   `tasks`: `id`, `account_id` (FK), `cron_expression`, `is_enabled`, `created_at`.
*   **关键逻辑**: 对用户输入的Cookie进行强加密（如AES-256-GCM）后存储。状态`status`由一个独立的后台校验服务定期更新。

#### 4.3. 任务调度模块 (`task_scheduler`)
*   **技术**: Celery Beat + Redis。
*   **配置**: 在启动时，从数据库`tasks`表中加载所有`is_enabled=True`的任务，并将其注册到Celery Beat的调度器中。
*   **工作流程**:
    1.  Beat根据Cron表达式触发任务。
    2.  任务内容是向消息队列（Redis）发送一条消息，消息体包含`task_id`和`account_id`。
    3.  Worker监听到消息后，调用`Sign-in Executor`的逻辑。

#### 4.4. 签到执行模块 (`signin_executor`)
*   **技术**: Celery Worker。
*   **工作流程**:
    1.  **接收任务**: 从消息队列获取任务。
    2.  **前置检查**: 查询Redis或DB，检查账号`status`是否为`active`。若否，则记录日志并终止。
    3.  **获取资源**: 从`Proxy Pool Manager`获取一个健康代理；从`Fingerprint Generator`获取一个指纹；从Redis解密并获取该账号的`cookies`。
    4.  **执行签到**:
        *   调用`login_and_verify`模块检查Cookie有效性。
        *   调用`get_super_topics`获取签到列表。
        *   遍历列表，对每个超话调用`sign_topic`。
        *   **反爬策略**: 在请求间引入随机延迟；为每个请求构造独特的Headers（含UA、指纹等）；使用代理IP。
        *   **JS逆向**: 如果API请求签名失败，向`Browser Automation Service`发起RPC调用，获取签名参数后再重试。
    5.  **结果上报**: 将签到结果（成功、失败、原因、获得积分）写入数据库的`signin_logs`表。
    6.  **清理**: 归还代理IP，更新Redis中的会话状态。

#### 4.5. 浏览器自动化模块 (`browser_automation_service`)
*   **API端点 (gRPC or REST)**:
    *   `POST /api/v1/get_signature`: 接收目标URL和必要的上下文，返回一个已签名的请求载荷或Headers。
*   **实现**: 使用Playwright启动一个无头浏览器池。收到请求后，从池中分配一个浏览器上下文，导航至相关页面，注入JS钩子或直接监听网络请求，提取所需数据后关闭上下文并返回结果。

---

### **5. 数据库设计 (Database Schema)**

#### 5.1. `users` Table
| Column | Type | Constraints | Description |
| :--- | :--- | :--- | :--- |
| `id` | UUID | PK | Primary Key |
| `username` | VARCHAR(50) | UNIQUE, NOT NULL | Unique username |
| `email` | VARCHAR(255) | UNIQUE, NOT NULL | User's email address |
| `hashed_password` | VARCHAR(255) | NOT NULL | Hashed password |
| `created_at` | TIMESTAMPTZ | DEFAULT NOW() | Account creation time |
| `is_active` | BOOLEAN | DEFAULT TRUE | Whether the user account is active |

#### 5.2. `accounts` Table
| Column | Type | Constraints | Description |
| :--- | :--- | :--- | :--- |
| `id` | UUID | PK | Primary Key |
| `user_id` | UUID | FK (`users.id`), ON DELETE CASCADE | Owner of the account |
| `weibo_user_id` | VARCHAR(20) | NOT NULL | UID on Weibo platform |
| `remark` | VARCHAR(100) | | User-defined note for the account |
| `encrypted_cookies` | TEXT | NOT NULL | AES-256 encrypted cookie string |
| `iv` | VARCHAR(32) | NOT NULL | Initialization vector for AES-GCM |
| `status` | VARCHAR(20) | DEFAULT 'pending' | 'active', 'invalid_cookie', 'banned' |
| `last_checked_at` | TIMESTAMPTZ | | Last time the cookie was verified |
| `created_at` | TIMESTAMPTZ | DEFAULT NOW() | When the account was added |

#### 5.3. `tasks` Table
| Column | Type | Constraints | Description |
| :--- | :--- | :--- | :--- |
| `id` | UUID | PK | Primary Key |
| `account_id` | UUID | FK (`accounts.id`), ON DELETE CASCADE | Associated account |
| `cron_expression` | VARCHAR(50) | NOT NULL | Cron expression for scheduling |
| `is_enabled` | BOOLEAN | DEFAULT TRUE | Enable or disable the task |
| `created_at` | TIMESTAMPTZ | DEFAULT NOW() | Task creation time |

#### 5.4. `signin_logs` Table
| Column | Type | Constraints | Description |
| :--- | :--- | :--- | :--- |
| `id` | BIGSERIAL | PK | Primary Key |
| `account_id` | UUID | FK (`accounts.id`) | Associated account |
| `topic_title` | VARCHAR(100) | | Title of the signed super topic |
| `status` | VARCHAR(20) | NOT NULL | 'success', 'failed_already_signed', 'failed_network', 'failed_banned' |
| `reward_info` | JSONB | | Details about rewards, e.g., `{"exp": 2, "credit": 1}` |
| `error_message` | TEXT | | Error details if status is 'failed' |
| `signed_at` | TIMESTAMPTZ | DEFAULT NOW() | Timestamp of the sign-in attempt |

---

### **6. API 设计规范 (API Design Specification)**

*   **协议**: 全站使用 HTTPS。
*   **数据格式**: 请求和响应体均使用 `application/json`。
*   **认证方式**: Bearer Token (JWT)。需要在请求头的 `Authorization` 字段中携带：`Authorization: Bearer <your_jwt_token>`。
*   **版本控制**: URL路径中包含版本号，例如 `/api/v1/auth/login`。
*   **通用响应结构**:
    ```json
    {
      "success": true,
      "data": { ... }, // 成功时返回的数据
      "message": "Operation successful.", // 可选的提示信息
      "error": null // 失败时返回的错误对象
    }
    ```
    *   失败时 (HTTP状态码 >= 400):
    ```json
    {
      "success": false,
      "data": null,
      "message": "Validation failed.",
      "error": {
        "code": "VALIDATION_ERROR",
        "details": [
          {"field": "email", "message": "Invalid email format."}
        ]
      }
    }
    ```
*   **状态码**: 严格遵守 RESTful 规范。200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 500 (Internal Server Error)。

---

### **7. 部署与运维 (Deployment & Operations)**

*   **开发环境**: 使用 `docker-compose.yml` 定义所有服务（API, DB, Redis, Frontend Dev Server），实现一键启动。
*   **生产环境**: 使用 `Kubernetes` 进行编排。编写 `Deployment.yaml`, `Service.yaml`, `Ingress.yaml` 等清单文件。
*   **CI/CD Pipeline (GitHub Actions Example)**:
    1.  **On Push to `main`**: Trigger workflow.
    2.  **Lint & Test**: Run code linters (Black, Flake8) and unit/integration tests.
    3.  **Build**: Build Docker images for all services and push them to a container registry (e.g., Docker Hub, AWS ECR).
    4.  **Deploy**: Use `kubectl` or ArgoCD to apply the new Kubernetes manifests to the production cluster.
*   **监控与告警**:
    *   **Metrics**: Expose metrics via `prometheus_client` in Python services. Monitor queue length, task success/failure rates, API latency.
    *   **Alerts**: Configure Alertmanager to trigger alerts on Slack/PagerDuty for critical issues (e.g., high task failure rate > 10%, worker node down).
    *   **Logging**: Configure all services to output structured logs (JSON). Use Filebeat or Fluentd to ship logs to Elasticsearch. Use Kibana for visualization and querying.

这份文档为专业的 Coding AI 或开发团队提供了从宏观架构到微观实现的全面指导。开发过程应遵循此文档，并可根据实际情况进行迭代和优化。