# 政务网站信息采集系统 (GovCrawler)

## What This Is

一个**多站点、定时、低调**地采集政务公开信息的系统。按站点与栏目配置化抓取政府门户网站的政务动态、政策法规、最新文件等公开内容，结构化保存到服务器目录与数据库，供下游已有 RAG 系统作为知识库数据源使用。目标用户是内部构建政务领域 RAG 知识库的工程团队。

## Core Value

**在不惊扰目标政务网站的前提下，稳定、增量、可追溯地把 20–30 个政务门户网站的公开内容持续落到本地存储，并让下游 RAG 系统简单地拉到增量。**

一句话：**抓得到 + 抓得稳 + 抓得轻**。

## Requirements

### Validated

(None yet — ship to validate)

### Active

- [ ] 支持 20–30 个政府门户网站的多栏目配置化采集（YAML 定义站点/栏目/选择器）
- [ ] 采集字段：标题、发布时间、发布主体、正文、附件（原件）、原文 URL、所属栏目、抓取时间
- [ ] 分层抓取策略：Tier 1 官方接口 → Tier 2 httpx → Tier 3 Playwright stealth → Tier 4 DrissionPage，自动降级
- [ ] Cookie 池（Valkey）实现：浏览器过挑战后的 Cookie 共享复用，减少浏览器启动
- [ ] 增量抓取：URL 归一化去重 + 正文 SimHash 去重；列表页遇已采文章即停
- [ ] 解析器：XPath/CSS 主选 + GNE 兜底，站点改版时可热更新选择器
- [ ] 附件原件落盘（不做 OCR、不抽文本、不解压），按 站点/栏目/年/月 分层
- [ ] 原始 HTML 归档 + 正文纯文本分别落盘，供后续重新解析或 RAG 直接消费
- [ ] 元数据入 PostgreSQL，含 `exported_to_rag_at` 字段便于下游拉增量
- [ ] 对外暴露 REST API：`GET /api/articles?since=...`、详情、附件下载、ack
- [ ] APScheduler 定时调度，允许 T+1 滞后；每栏目每天 1 次，01:00–05:00 错峰
- [ ] 对目标站点"无感"：单站并发 1，间隔 ≥5s + 20% 抖动，UA 带身份，遵守 robots.txt
- [ ] 失败处理：412/403 连续 3 次放弃本轮，次日重试；非硬冲
- [ ] 最小监控：成功率、耗时、412/403 率、栏目 24h 无新文章告警（飞书/企微）
- [ ] 管理后台（可选）：站点/栏目 CRUD + XPath 在线编辑 + 运行监控 + 失败重放

### Out of Scope

- **向量化 / 切片 / Embedding** — 已有 RAG 系统负责，本系统只负责落地
- **附件内容解析 / OCR / PDF 抽文本 / ZIP 解压** — 由下游系统处理
- **登录态抓取 / 付费内容** — 只采公开信息
- **验证码破解 / 真滑块** — 触发真滑块即跳过，不采用打码平台
- **实时抓取** — 允许 T+1 滞后，核心是"无感"而非"最新"
- **分布式 / K8s / 代理 IP 池** — 20–30 站规模单机足够，避免过度工程化
- **在线全文检索 / 问答** — RAG 系统职责
- **AGPL/SSPL/BSL 许可证组件**（如 Redis 7.4+、MinIO、Grafana、Loki、Elasticsearch） — 商用合规约束

## Context

- **规模**：20–30 个政府门户网站，总栏目数 150–300，日均新增 200–500 篇，日均请求 ~800 次/天，峰值并发 2–3。
- **反爬现状**：实测 `www.gdqy.gov.cn` 部署知道创宇 ctct 盾（HTTP 412 + 滑块挑战页），httpx + 真实 UA 拿不到内容；**真实 Chrome 内核（Playwright）可自动过 JS 挑战**，未触发真滑块。推测同集团政务站多数走相同方案，单一 Playwright stealth 策略可覆盖绝大部分。
- **下游 RAG**：已存在独立 RAG 系统，消费方式偏好**直接查 DB + 读共享目录**（最简），T+1 完全够用。
- **先导设计**：本项目有一份完整设计文档 `政务网站采集系统-设计文档.md`（v2.1），包含架构、数据模型、分阶段路线、合规红线、许可证清单，已作为本 PROJECT.md 的基础。
- **合规背景**：政务公开信息本身依法公开，但对方部署专业 WAF，需严格频控与低调访问以避免被封/被投诉。

## Constraints

- **Tech stack**: Python 3.11+ — 生态最全，反爬 + 解析 + 调度全套成熟。
- **License**: 所有依赖必须 MIT / BSD / Apache-2.0 / PostgreSQL License / PSF — 商用合规，**禁用 AGPL/SSPL/BSL/Elastic License**。
- **Deployment**: 单机 Docker Compose — 20–30 站规模永久够用，月成本 200–400 元。
- **Timing**: 允许 T+1 滞后 — 发布当天抓不到没关系，第二天补上即可。
- **Concurrency**: 单站并发 1，请求间隔 ≥5s，夜间（01:00–05:00）错峰。严禁高频轮询。
- **Storage**: 本地文件系统 `/data/govcrawler/` 为主；不引入 MinIO（AGPL）。
- **External deps avoided**: 不做向量化、OCR、附件解析 — 交由下游系统。
- **Etiquette**: UA 标明身份与联系邮箱；遵守 robots.txt；只采公开信息路径。

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| 选用 Valkey 替代 Redis | Redis 7.4+ 转 SSPL 非开源，Valkey 是 Linux 基金会 BSD-3 分支，协议兼容客户端零改动 | — Pending |
| 不引入 MinIO，仅用本地文件系统 | MinIO AGPL v3 有传染性；20–30 站规模本地 `/data` 完全够 | — Pending |
| 附件只保存原件，不做任何解析 | 下游系统负责；避免把 OCR/抽文本的复杂性塞进采集链路 | — Pending |
| 分层 Fetcher：httpx → Playwright stealth → DrissionPage | 实测 gdqy.gov.cn 需要浏览器过 ctct 盾；分层避免浏览器高成本成为瓶颈 | — Pending |
| Cookie 池（Valkey，TTL 4h） | 浏览器过挑战一次后 Cookie 可复用，同域后续请求走 httpx，降本关键 | — Pending |
| T+1 滞后 + 01:00–05:00 错峰跑批 | "对目标站点无感"是硬约束；实时性无业务价值 | — Pending |
| 监控面板避开 Grafana/Loki（AGPL） | 改用 VictoriaMetrics Perses / OpenObserve 或自建 HTML 小面板 | — Pending |
| 不做向量化，交下游 RAG | 已有 RAG 系统；避免重复投资与职责不清 | — Pending |
| Python + FastAPI + PostgreSQL + APScheduler | 单机够用的最简栈；生态成熟、许可证干净 | — Pending |

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition** (via `/gsd-transition`):
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone** (via `/gsd-complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---
*Last updated: 2026-04-22 after initialization（基于 政务网站采集系统-设计文档.md v2.1）*