阶段1：服务化骨架（FastAPI + Playwright worker + 任务队列）

- 新增 runtime.py：抽离共享核心 launch_and_prepare / dispatch_task / run_heartbeat /
  probe_* / launch_anneng / RuntimeContext，常量 SITES_CONFIG 等；main_router 复用
- 新增 server.py：FastAPI（主线程）+ Playwright worker（独立线程）+ 任务队列；
  API：POST/GET /tasks、GET /status、GET /data/{file}（防路径穿越）
- state_store：加 task_history 表 + create/update/get/list 接口
- 5 站点 with_retry 改为返回 True/False，供 dispatch_task 判成败
- main_router：重写为复用 runtime 的交互模式（行为不变）
- requirements：加 fastapi、uvicorn
- CLAUDE.md：补充运行模式与共享核心架构说明

线程模型：主线程 FastAPI 不碰 Playwright，worker 线程独占 page，经 Queue + SQLite 通信。

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -7,6 +7,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 自动登录 5 家物流承运商工作台，下载"应到 / 实到"货物数据，离线比对出**应到未到**
 异常运单并汇总成 Excel。4 个网页站点 + 1 个 Electron 应用（安能）。
 
+**两种运行模式**（阶段1 起）：
+- **交互模式** `main_router.py`：人工调试 / 操作，交互菜单（登录、触发下载、[12] 状态盘）。
+- **服务模式** `server.py`：常驻 + FastAPI，客户端经 HTTP 触发任务、查状态、下载数据（API 文档 `/docs`）。
+- 两者共享 `runtime.py`（启动 / 就绪 / 任务派发 / 心跳）与 `state_store.py`（SQLite 状态持久化）。
+
 ## 常用命令
 
 所有 Python 一律在项目虚拟环境 `.venv` 中运行（Windows 下可直接用
@@ -20,6 +25,9 @@ playwright install chromium
 # 运行主程序（交互式菜单，详见 main_router 的 run_multi_site_daemon）
 .venv/Scripts/python.exe main_router.py
 
+# 服务模式（常驻 + FastAPI，客户端经 HTTP 触发；默认 :8000，API 文档见 /docs）
+.venv/Scripts/python.exe server.py
+
 # 单站点联调：在 config.yaml 设 debug.enabled=true + debug.target_site=顺心|百世|中通|韵达|安能
 #   网页站：只挂载该站；安能：只启动 Electron 应用。
 
@@ -38,6 +46,14 @@ playwright install chromium
 
 ## 架构（big picture）
 
+### 运行模式与共享核心（阶段0/1 重构）
+- **`runtime.py`**：两种模式共享的核心——`launch_and_prepare`（启动 Playwright + 各站就绪 + 弹窗 + 心跳初值，阻塞至就绪）、`dispatch_task(ctx, {site,kind})`（派发任务，掉登录直接判 failed）、`run_heartbeat`、`probe_site_login/probe_data_file`、`RuntimeContext.stop()`。常量 `SITES_CONFIG/READY_SELECTORS/APP_SITES/HEARTBEAT_INTERVAL/DATA_FILENAMES` 在此。
+- **`state_store.py`**：SQLite 状态持久化（`state/state.db`）。`site_status`（登录态 + 数据态 + 时间戳，心跳刷新）、`task_history`（任务记录）。重启不丢。
+- **`main_router.py`**：交互模式，菜单循环（input 后台线程 + `_await_command` + `dispatch_task` + 心跳）。
+- **`server.py`**：服务模式。**FastAPI（主线程）+ Playwright worker（独立线程）**——主线程处理 HTTP（绝不碰 Playwright），worker 独占 page 操作，经 `task_queue` + `state_store` 通信。API：`POST/GET /tasks`、`GET /status`、`GET /data/{file}`。
+- **关键线程约束**：Playwright sync 对象绑定创建它的线程；`launch_and_prepare`（含 `sync_playwright().start()`）必须在持有 Playwright 的线程调用（交互=主线程，服务=worker 线程）。FastAPI 路由绝不访问 page。
+- 站点模块 `site_*.py` 的 `with_retry` 返回 `True/False`（成功 / 放弃），供 `dispatch_task` 判成败。
+
 ### 两套驱动模态 —— 这是理解全局的关键
 - **网页 4 站**（顺心/百世/中通/韵达）：`main_router` 用 Playwright 开 chromium，
   每站一个 `page`，流程函数签名为 `xxx_download_impl(page)`。**例外：顺心是双账号**