flowchart LR
    USER["学生 / 实验操作者"] --> UI["React + Vite 控制台"]
    UI -->|"REST /api/crawl"| API["Flask Blueprint"]
    UI -.->|"join room / 订阅任务"| WS["实时日志 / 状态流"]
    WS -.->|"crawl_log / tech_log"| UI
    API --> APP["CrawlerService"]
    APP --> DOMAIN["领域层<br/>Entity / Value Objects / Domain Services"]
    APP --> REPO["Repository"]
    APP --> BUS["EventBus"]
    DOMAIN --> HTTP["Requests / HybridHttpClient"]
    DOMAIN --> PARSER["HTML / robots / PDF 解析"]
    REPO --> DB[("MySQL")]
    BUS --> WS

flowchart TB
    UI["前端控制台"] --> VIEW["view<br/>crawler_view.py"]
    VIEW --> SERVICE["services<br/>crawler_service.py"]
    SERVICE --> DOMAIN["domain<br/>task / config / result / events"]
    SERVICE --> SHARED["shared<br/>event_bus / websocket handlers / db_manager"]
    DOMAIN --> INFRA["infrastructure<br/>http / parser / playwright / queue / repository"]
    INFRA --> DB[("SQLAlchemy + MySQL")]
    SHARED --> SOCKET["Socket.IO 推送"]

sequenceDiagram
    actor U as 用户
    participant UI as React 控制台
    participant API as Flask API
    participant S as CrawlerService
    participant Q as CrawlTask / UrlQueue
    participant D as Domain Services
    participant I as Infra Adapters
    participant R as Repository
    participant E as EventBus / WebSocket

    U->>UI: 填写抓取配置
    UI->>API: POST /api/crawl/create
    API->>S: create_crawl_task(config)
    S->>R: save_task(PENDING)
    API-->>UI: task_id

    U->>UI: 启动任务
    UI->>API: POST /api/crawl/start/:id
    API->>S: start_crawl_task(id)
    S->>Q: initialize queue

    loop 每个待抓取 URL
        S->>Q: dequeue()
        S->>I: HTTP 获取页面 / PDF
        I-->>S: response
        S->>D: 提取元数据 / 发现链接 / 识别 PDF
        D-->>S: crawl result + new links
        S->>R: save_result / save_task
        S->>E: publish domain events
        E-->>UI: crawl_log / tech_log
        UI->>API: GET /api/crawl/status/:id
        API-->>UI: 任务状态与结果统计
    end

    S->>R: save_task(COMPLETED / STOPPED)
    S->>E: publish lifecycle event
    E-->>UI: 最终状态

flowchart TD
    START["任务启动"] --> STRATEGY{"抓取策略"}
    STRATEGY -->|"BFS"| BFS["按层推进队列"]
    STRATEGY -->|"DFS"| DFS["按深度推进队列"]
    STRATEGY -->|"BIG_SITE_FIRST"| PRIORITY["优先域名加权"]

    BFS --> FETCH["取出下一个 URL"]
    DFS --> FETCH
    PRIORITY --> FETCH

    FETCH --> TYPE{"资源类型"}
    TYPE -->|"HTML"| HYBRID["HybridHttpClient"]
    TYPE -->|"PDF"| PDF["PdfDomainService"]

    HYBRID --> DYNAMIC{"内容过短 / 疑似 SPA ?"}
    DYNAMIC -->|"否"| PARSER["HtmlParserImpl"]
    DYNAMIC -->|"是"| PLAY["PlaywrightClient"]
    PLAY --> PARSER

    PARSER --> META["提取标题 / 作者 / 摘要 / 关键词"]
    PARSER --> LINKS["发现可抓取链接 / PDF 链接"]
    PDF --> PDFRESULT["提取 PDF 元数据与正文"]

    META --> RESULT["统一映射为 CrawlResult"]
    LINKS --> RESULT
    PDFRESULT --> RESULT

    RESULT --> STORE["Repository 持久化"]
    STORE --> EVENT["EventBus + WebSocket"]
    EVENT --> CONSOLE["前端日志 / 状态 / 结果面板"]

flowchart LR
    ROOT["CrawlFlow"] --> FE["frontend/"]
    ROOT --> BE["backend/"]
    ROOT --> DOCS["docs/"]
    ROOT --> TESTS["tests/"]
    ROOT --> CI[".github/workflows/ci.yml"]

    FE --> FE1["src/features/crawler_main"]
    BE --> BE1["src/crawl/view"]
    BE --> BE2["src/crawl/services"]
    BE --> BE3["src/crawl/domain"]
    BE --> BE4["src/crawl/infrastructure"]
    BE --> BE5["src/shared"]
    DOCS --> D1["dev/advanced_features_design.md"]
    DOCS --> D2["development/commands.md"]
    DOCS --> D3["ai/v2_feature_update.md"]
    TESTS --> T1["integration/test_realtime_logging_backend.py"]