docs: 添加爬虫模块化设计（Spider 基类 + Pipeline 策略模式）

docs/superpowers/specs/2026-05-09-fastapi-docker-migration-design.md

@@ -42,12 +42,14 @@ gx-gp-notify/
 │   │   └── schemas.py           # Pydantic 请求/响应模型
 │   ├── crawler/
 │   │   ├── __init__.py
-│   │   ├── spider.py            # 爬虫核心
+│   │   ├── base.py              # Spider 抽象基类 + Pipeline 配置
-│   │   ├── dahuagov_spider.py   # 大化县专用爬虫
+│   │   ├── gxgp_spider.py       # 广西政府采购网爬虫 (API 模式)
+│   │   ├── dahuagov_spider.py   # 大化县政府网爬虫 (HTML 模式)
 │   │   └── parsers.py           # 数据解析器
 │   ├── services/
 │   │   ├── __init__.py
-│   │   ├── crawl_service.py     # 爬取业务流程
+│   │   ├── crawl_service.py     # 爬取编排器 (注册/调用所有 Spider)
+│   │   ├── pipeline.py          # 统一后处理管道 (存储→筛选→推送)
 │   │   ├── filter_service.py    # 筛选逻辑
 │   │   └── notification_service.py  # 通知服务
 │   ├── wechat/
@@ -78,7 +80,142 @@ gx-gp-notify/
 
 ---
 
-## 3. API 端点设计
+## 3. 爬虫模块化设计
+
+### 3.1 设计动机
+
+系统爬取两个不同来源的公告：广西政府采购网（API 模式，13 种公告类型）和大化县政府网（HTML 解析，单一来源）。两个爬虫的后处理流程不同：
+
+| 对比 | 广西政府采购网 | 大化县政府网 |
+|------|---------------|-------------|
+| 爬取方式 | POST JSON API | GET HTML + BeautifulSoup |
+| 反爬机制 | 敏感词检查 | 无 |
+| 分页 | 多页轮询 | 单页 |
+| 筛选策略 | 关键词 + 日期 + 去重 | 不过滤 |
+| 推送策略 | 只推送关键词匹配的 | 全部推送 |
+| 已发送标记 | is_new 标记 | is_new → mark_sent |
+
+为避免两个爬虫各自维护一套存储/筛选/推送逻辑，采用 **Spider 接口 + Pipeline 策略模式** 分离关注点。
+
+### 3.2 架构
+
+```
+┌─────────────────────────────────────────────────┐
+│              CrawlOrchestrator                   │
+│    (注册所有 Spider，统一调度爬取)                 │
+└─────────────────────┬───────────────────────────┘
+                      │
+        ┌─────────────┼─────────────┐
+        │             │             │
+┌───────▼──────┐ ┌────▼──────┐ ┌────▼──────────┐
+│ GXGPSpider   │ │ Dahuagov  │ │ (FutureSpider) │
+│ (API 模式)    │ │ Spider    │ │                │
+│ 13 sources   │ │ (HTML模式) │ │                │
+└───────┬──────┘ └────┬──────┘ └────┬───────────┘
+        │             │             │
+        └─────────────┼─────────────┘
+                      │  List[Announcement]
+                      │
+┌─────────────────────▼───────────────────────────┐
+│              PostCrawlPipeline                   │
+│                                                  │
+│  每个 Spider 声明 PipelineConfig:                 │
+│   - filter_enabled: 是否启用关键词筛选            │
+│   - keywords: 筛选关键词列表                      │
+│   - dedup_enabled: 是否去重                      │
+│   - notify_mode: "filtered" | "all"             │
+│   - mark_sent: 推送后是否标记已发送               │
+│                                                  │
+│  统一处理流程:                                    │
+│  存储 → 去重 → 筛选(可选) → 推送(可选) → 标记(可选) │
+└──────────────────────────────────────────────────┘
+```
+
+### 3.3 Spider 基类
+
+```python
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import List
+
+@dataclass
+class PipelineConfig:
+    """Spider 后处理策略配置"""
+    filter_enabled: bool = True
+    keywords: List[str] = None
+    dedup_enabled: bool = True
+    notify_mode: str = "filtered"  # "filtered" | "all"
+    mark_sent: bool = False
+
+
+class BaseSpider(ABC):
+    """爬虫基类 — 只负责爬取+解析，不管后续如何处理"""
+
+    name: str                            # spider 名称
+    source_code: str                     # 来源代码
+    source_name: str                     # 来源名称
+
+    @abstractmethod
+    async def crawl(self) -> CrawlResult:
+        """执行爬取，返回包含 Announcement 列表的 CrawlResult"""
+        ...
+
+    def get_pipeline_config(self) -> PipelineConfig:
+        """返回后处理策略（子类可覆盖）"""
+        return PipelineConfig()
+```
+
+### 3.4 两个 Spider 的 PipelineConfig
+
+```python
+# GXGPSpider — 关键词筛选模式
+PipelineConfig(
+    filter_enabled=True,
+    keywords=["大化"],          # 从配置读取
+    dedup_enabled=True,
+    notify_mode="filtered",     # 只推送匹配关键词的
+    mark_sent=False,            # 用 is_new 标记，不单独 mark_sent
+)
+
+# DahuagovSpider — 全量推送模式
+PipelineConfig(
+    filter_enabled=False,
+    keywords=[],
+    dedup_enabled=True,
+    notify_mode="all",          # 全部推送
+    mark_sent=True,             # 推送后标记已发送
+)
+```
+
+### 3.5 统一后处理管道
+
+```python
+class PostCrawlPipeline:
+    """统一后处理管道 — 所有 Spider 共用"""
+
+    async def process(self, announcements: List[Announcement],
+                     config: PipelineConfig) -> PipelineResult:
+        # 1. 统一存入 announcements 表 (按 source_code 区分)
+        # 2. 去重 (基于 content_hash)
+        # 3. 根据 config.filter_enabled 决定是否筛选
+        # 4. 根据 config.notify_mode 决定推送策略
+        #    - "all": 推送全部新公告
+        #    - "filtered": 只推送匹配关键词的
+        # 5. 根据 config.mark_sent 标记已发送
+        # 6. 生成 Markdown (可选)
+        ...
+```
+
+### 3.6 优势
+
+- **新增爬虫源**只需实现 `BaseSpider.crawl()` + 声明 `PipelineConfig`，推送/存储逻辑零改动
+- **推送逻辑单一入口**，修改一处对所有源生效
+- 每个 Spider 文件只关注"怎么爬"和"怎么解析"，不再包含存储/筛选/推送代码
+- `dahuagov_announcements` 独立表可合并到统一的 `announcements` 表，用 `source_code='dahuagov'` 区分
+
+---
+
+## 4. API 端点设计
 
 ### 3.1 公告查询
 
@@ -127,11 +264,11 @@ gx-gp-notify/
 
 ---
 
-## 4. 数据模型
+## 5. 数据模型
 
-### 4.1 公告表 (announcements)
+### 5.1 公告表 (announcements)
 
-合并现有的 `announcements`、`auto_announcements`、`manual_announcements` 三张表为一张，通过 `crawl_mode` 字段区分自动/手动。
+合并现有的 `announcements`、`auto_announcements`、`manual_announcements`、`dahuagov_announcements` 四张表为一张，通过 `source_code` 字段区分来源，通过 `PipelineConfig` 控制每个来源的推送策略。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
@@ -140,41 +277,30 @@ gx-gp-notify/
 | publish_date | DateTime | 发布时间 |
 | purchase_name | String(200) | 发布单位 |
 | content_url | Text | 内容链接 |
-| source_code | String(50) | 来源代码 |
+| source_code | String(50) | 来源代码（ZcyAnnouncement1 / dahuagov 等） |
 | source_name | String(100) | 来源名称 |
 | announcement_type | String(50) | 公告类型枚举值 |
-| content_hash | String(64) | SHA256 内容哈希，UNIQUE |
+| content_hash | String(64) | SHA256 内容哈希，UNIQUE INDEX |
 | crawl_mode | String(20) | "auto" / "manual" |
 | is_new | Boolean | 是否新公告 |
-| is_today | Boolean | 是否今日公告 |
+| is_sent | Boolean | 是否已推送 |
+| keyword_matched | Boolean | 是否匹配关键词 |
 | created_at | DateTime | 创建时间 |
 | updated_at | DateTime | 更新时间 |
 
-### 4.2 大化县公告表 (dahuagov_announcements)
+### 5.2 设计决策
 
-保留独立表，因为推送逻辑不同（全部推送，不筛选关键词）。
+- **四表合一**：不再为不同来源或抓取模式创建独立表。`source_code` 区分来源（`ZcyAnnouncement1` ~ `dahuagov`），`crawl_mode` 区分自动/手动
+- **is_sent 字段**：替代原来大化县的 `is_new → mark_sent` 模式，同时为广西采购网的公告提供统一的已推送标记
+- **keyword_matched 字段**：在筛选阶段标记，持久化到数据库方便后续查询
 
-| 字段 | 类型 | 说明 |
+### 5.3 变更说明
-|------|------|------|
-| id | Integer | 主键 |
-| title | String(500) | 公告标题 |
-| publish_date | DateTime | 发布时间 |
-| purchase_name | String(200) | 发布单位 |
-| content_url | Text | 内容链接 |
-| source_code | String(50) | 默认 "dahuagov" |
-| source_name | String(100) | 默认 "大化县政府网采购公告" |
-| content_hash | String(64) | SHA256 内容哈希，UNIQUE |
-| is_new | Boolean | 是否新公告（未推送） |
-| created_at | DateTime | 创建时间 |
-| updated_at | DateTime | 更新时间 |
-
-### 4.3 变更说明
 
 - `content_hash` 从 MD5 (32位) 改为 SHA256 (64位)
 - 去掉 `announcement_sources` 表，来源信息从环境变量配置动态读取
 - 去掉 `crawl_results` 表，爬取结果通过日志记录
-- 去掉多余的索引表（keyword_matched / date_filtered 字段），筛选在应用层处理
 - 使用 Alembic 管理数据库迁移
+- 旧数据迁移：通过 Alembic migration 脚本将现有四张表的数据合并到新表
 
 ---
 
@@ -387,4 +513,4 @@ __pycache__/
 | 数据库迁移丢失数据 | Alembic 自动生成迁移脚本，先在测试环境验证 |
 | 异步爬虫被目标站限流 | 保留现有延迟/重试机制，httpx 支持同样的超时配置 |
 | 企业微信回调兼容性 | 回调路径不变，加解密逻辑完全复用现有代码 |
-| Docker 网络访问 10.10.10.14 | 确认 Docker 宿主机可访问该 IP，必要时用 `host.docker.internal` |
+| Docker 网络访问 10.10.10.14 | 确认 Docker 宿主机可访问该 IP，必要时用 `host.docker.internal` |