InboundVerify/docs/superpowers/plans/2026-07-24-ingest-hook.md

# 下载后自动入库钩子 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 把 PostgreSQL 入库动作挂到 `runtime.dispatch_task` 下载成功分支，使每次下载成功后自动、尽力而为、kind 级地把刚下载的数据 UPSERT 进 PG。

**Architecture:** 新增 `store.ingest_task(site, kind)`（kind 级路由，复用现有 `_ingest_*`）+ `runtime._persist_to_db(site, kind)`（同步内联钩子，懒导入 store，绝不外抛）+ `state_store.ingest_state` 表（结果可查，经 `/status` 暴露）+ 配置开关/超时。详见 spec `docs/superpowers/specs/2026-07-24-ingest-hook-design.md`。

**Tech Stack:** Python 3.10+、psycopg(v3)、sqlite3、Playwright(不动)、FastAPI(仅 `/status` 加字段)、pyyaml。包以可编辑模式安装（`pip install -e .`），命令走 `.venv/Scripts/python.exe -m inbound_verify...`。

## Global Constraints

- **Python 一律走项目虚拟环境**：`.venv/Scripts/python.exe`（全局 CLAUDE.md 协议）。命令默认在 `InboundVerify/` 根目录执行。
- **无 pytest 测试套件**（本仓库约定，覆盖 writing-plans 默认的 TDD-pytest 步骤）：每个任务的验证用 `py_compile` + `black` + 导入冒烟 + 功能/手动校验，不写 pytest。
- **改完任何 .py 必须跑 Black**：`.venv/Scripts/python.exe -m black inbound_verify`。
- **不自动提交/推送**（本仓库约定，覆盖 writing-plans 默认的"每任务即提交"）：每个任务的 Commit 步骤**仅在用户明确说"提交"/"commit"时执行**；否则完成任务后停在待提交态，告知用户。
- **commit message 一律英文**（全局 CLAUDE.md）。
- **不改下载流程/比对逻辑**；4 站 `-未到数据.xlsx` 不入库（既有设计）；不上连接池/后台线程/补入重试。
- 导入约束：`runtime` 已 import `compare`，`store` 也 import `compare`；钩子里对 `store` **懒导入**以回避成环。

---

## File Structure

| 文件 | 责任 | 本计划改动 |
|---|---|---|
| `inbound_verify/store.py` | PG 持久化（建库/建表/入库 CLI） | 改 `_load_pg_config`/`_connect`；加 `ingest_enabled()`、`ingest_task()`；CLI 加 `ingest-one` |
| `inbound_verify/state_store.py` | SQLite 状态持久化 | `init_db` 加 `ingest_state` 表；加 `set_ingest_state()`、`get_all_ingest_state()` |
| `inbound_verify/runtime.py` | 两种模式共享核心（含 dispatch_task） | 加 `_persist_to_db()`；在 `dispatch_task` 成功分支调用 |
| `inbound_verify/cli/server.py` | FastAPI 服务模式 | `/status` 返回加 `ingest` 字段 |
| `config.example.yaml` | 配置模板（提交） | `postgres` 段加 `auto_ingest`/`connect_timeout_seconds`；修过期 `db_store.py`→`store.py` 注释 |
| `config.yaml` | 真实配置（gitignored） | 同上两键 + 修注释 |
| `README.md` | 用户文档 | DB CLI 命令列表加 `ingest-one` |

任务依赖：Task 2 依赖 Task 1；Task 4 依赖 Task 1+2+3；Task 5 依赖 Task 3。Task 3 独立。建议顺序 1→2→3→4→5。

---

### Task 1: store.py 配置键 + 连接超时层

**Files:**
- Modify: `inbound_verify/store.py:48-78`（`_load_pg_config`、`_connect`）
- Modify: `config.example.yaml:72-89`、`config.yaml`（postgres 段）

**Interfaces:**
- Consumes: 无（配置层根基）
- Produces: `_load_pg_config()` 返回新增 `auto_ingest: bool`、`connect_timeout_seconds: int`；`_connect(dbname)` 连接带 `connect_timeout` 且会话级 `statement_timeout=30s`；新函数 `ingest_enabled() -> bool`。后续任务依赖 `ingest_enabled()` 与超时连接。

- [ ] **Step 1: 改 `_load_pg_config` 加两键**

`inbound_verify/store.py` 的 `_load_pg_config` 返回 dict，在 `schema` 之后追加两键：

```python
    return {
        "host": pg.get("host", "127.0.0.1"),
        "port": int(pg.get("port", 5432)),
        "user": pg.get("user", "postgres"),
        "password": pg.get("password", ""),
        "dbname": pg.get("dbname", "CQHXDB"),
        "schema": pg.get("schema", "inbound_verify"),
        "auto_ingest": bool(pg.get("auto_ingest", True)),
        "connect_timeout_seconds": int(pg.get("connect_timeout_seconds", 5)),
    }
```

- [ ] **Step 2: 改 `_connect` 加 connect_timeout + statement_timeout**

把 `_connect` 替换为（用 `options` 一次性设 search_path + statement_timeout，等价于 spec 的 SET 但不引入额外事务）：

```python
def _connect(dbname):
    """用关键字参数连接（避开 conninfo 对密码特殊字符的解析）。
    options 设 search_path 到专用 schema + 会话级 statement_timeout=30s
    （cpolar 隧道上防失控查询；connect_timeout 守连接阶段）。"""
    c = _load_pg_config()
    return psycopg.connect(
        host=c["host"],
        port=c["port"],
        dbname=dbname,
        user=c["user"],
        password=c["password"],
        options=f"-c search_path={c['schema']} -c statement_timeout=30s",
        connect_timeout=c["connect_timeout_seconds"],
    )
```

- [ ] **Step 3: 加 `ingest_enabled()` 薄封装**

在 `_connect` 之后、`# 建库 / 建表` 分节注释之前插入：

```python
def ingest_enabled():
    """是否启用下载后自动入库（config.yaml postgres.auto_ingest，默认 True）。
    供 runtime 钩子判定开关，避免它伸手进 _load_pg_config。"""
    return _load_pg_config()["auto_ingest"]
```

- [ ] **Step 4: 更新 store.py 模块 docstring 的命令列表**

把文件顶部 docstring 的命令行小节，在 `ingest` 行后补一行 `ingest-one`（Task 2 会实现该命令，docstring 先行）：

```
  python -m inbound_verify.store ingest [site]   入库全站或单站（幂等 UPSERT）
  python -m inbound_verify.store ingest-one <site> <kind>  仅入库指定站/类（钩子同款路由）
  python -m inbound_verify.store all             createdb → init → 全站 ingest 一条龙
```

- [ ] **Step 5: config.example.yaml 加两键 + 修过期注释**

`config.example.yaml` 的 postgres 段：把 `# PostgreSQL 数据持久化（到货核销数据入库，详见 db_store.py）` 改为 `... 详见 store.py）`；命令注释里的 `python db_store.py ...` 改为 `python -m inbound_verify.store ...`；在 `schema: inbound_verify` 之后追加：

```yaml
  schema: inbound_verify
  # 下载成功后自动入库（钩子，见 runtime._persist_to_db）；false=跳过（无 PG/cpolar 的开发机）。
  auto_ingest: true
  # PG 连接超时（秒）；cpolar 抖动时快速失败，不拖垮下载 worker。
  connect_timeout_seconds: 5
```

- [ ] **Step 6: config.yaml 同步（gitignored 本地文件）**

对 `config.yaml` 做同样两键追加，并把注释里的 `db_store.py` 改为 `store.py`。保留其真实凭据不动。

- [ ] **Step 7: 编译 + Black**

```
.venv/Scripts/python.exe -m py_compile inbound_verify/store.py
.venv/Scripts/python.exe -m black inbound_verify/store.py
```
Expected: py_compile 无输出；black 报 `reformatted` 或 `left unchanged`。

- [ ] **Step 8: 回归既有 CLI 不破**

```
.venv/Scripts/python.exe -c "from inbound_verify import store; c=store._load_pg_config(); assert c['auto_ingest'] is True and c['connect_timeout_seconds']==5; assert store.ingest_enabled() is True; print('config ok')"
```
Expected: `config ok`。

- [ ] **Step 9: Commit（gated）**

仅当用户说"提交"时执行：

```bash
git add inbound_verify/store.py config.example.yaml
git commit -m "feat(store): add auto_ingest config + pg connect/statement timeouts"
```
（`config.yaml` 已 gitignore，不入提交。）

---

### Task 2: store.ingest_task + ingest-one CLI

**Files:**
- Modify: `inbound_verify/store.py`（加 `ingest_task`；`main()` 加 `ingest-one` 分支）

**Interfaces:**
- Consumes: Task 1 的 `_connect`(超时)、`_load_pg_config`、既有 `_ingest_expected/_ingest_actual/_ingest_undelivered_baishi`、`_read_business_dates`、`ALL_SITES`、`_site_cfg`。
- Produces: `ingest_task(site: str, kind: str) -> int`（返回入库总条数；`__compare__`/不支持组合返回 0）。

- [ ] **Step 1: 加 `ingest_task`**

在 `ingest(site)` 函数之后、`# 命令行` 分节之前插入：

```python
def ingest_task(site, kind):
    """按 (site, kind) 入库本次刚下载的文件（幂等 UPSERT），返回总条数。
    与 ingest(site) 的区别：只入本次刷新的那一类，避免重读写另一类文件（同步钩子里减少阻塞）。
    kind 路由：
      expected/actual        各入其列；
      undelivered 百世        入未到；
      undelivered 4 站        _site_undelivered_handler 内部连带下了 expected+actual，故入两者；
      __compare__ / 其它组合  返回 0。
    """
    if site == "__compare__":
        return 0
    dates = _read_business_dates()
    total = 0
    with _connect(_load_pg_config()["dbname"]) as conn:
        with conn.cursor() as cur:
            if kind == "expected":
                total += _ingest_expected(cur, site, dates.get(site))
            elif kind == "actual":
                total += _ingest_actual(cur, site)
            elif kind == "undelivered":
                if site == "百世":
                    total += _ingest_undelivered_baishi(cur)
                else:  # 顺心/中通/韵达/安能
                    total += _ingest_expected(cur, site, dates.get(site))
                    total += _ingest_actual(cur, site)
            # 其它组合（如 百世/expected，正常不经钩子触发）：防御性返回 0
        conn.commit()
    return total
```

- [ ] **Step 2: `main()` 加 `ingest-one` 分支**

在 `main()` 的 `elif cmd == "all":` 分支之后、`else:` 之前插入：

```python
    elif cmd == "ingest-one":
        kind = sys.argv[3] if len(sys.argv) > 3 else None
        if not site or kind not in ("expected", "actual", "undelivered"):
            print("用法: python -m inbound_verify.store ingest-one <site> <expected|actual|undelivered>")
            sys.exit(1)
        total = ingest_task(site, kind)
        print(f">> [ingest-one] {site}/{kind} 入库 {total} 条")
```

- [ ] **Step 3: 编译 + Black**

```
.venv/Scripts/python.exe -m py_compile inbound_verify/store.py
.venv/Scripts/python.exe -m black inbound_verify/store.py
```
Expected: 无编译错误。

- [ ] **Step 4: 路由正确性（手动，需 PG 已 createdb+init 且 downloads/ 有数据）**

逐条验证 kind 级只入对应文件：

```
.venv/Scripts/python.exe -m inbound_verify.store ingest-one 韵达 expected
```
Expected: stdout 只出现 `[应到] 韵达：N 条运单`，**不**出现 `[实到] 韵达` 行；结尾 `[ingest-one] 韵达/expected 入库 N 条`。

```
.venv/Scripts/python.exe -m inbound_verify.store ingest-one 顺心 undelivered
```
Expected: stdout 同时出现 `[应到] 顺心` 与 `[实到] 顺心`（undelivered→两者）。

```
.venv/Scripts/python.exe -m inbound_verify.store ingest-one 百世 undelivered
```
Expected: stdout 出现 `[未到] 百世`。

> 若某站 downloads/ 无文件：`_ingest_*` 打印 `[跳过] ... 文件不存在`，ingest_task 返回 0，属正常（非错误）。

- [ ] **Step 5: 无 PG 时的降级（手动，可选）**

临时把 `config.yaml` 的 `host` 改成不可达地址，重跑 Step 4 任一命令：应在 `connect_timeout_seconds`（默认 5s）内报 psycopg 连接错误并退出（非 hang）。验证后改回真实 host。

- [ ] **Step 6: Commit（gated）**

```bash
git add inbound_verify/store.py
git commit -m "feat(store): add kind-level ingest_task + ingest-one CLI subcommand"
```

---

### Task 3: state_store ingest_state 表 + 读写函数

**Files:**
- Modify: `inbound_verify/state_store.py:32-113`（`init_db` 加表）、`:219-247`（加两函数）

**Interfaces:**
- Consumes: 无（独立叶子，仅依赖 paths + sqlite3 + datetime）。
- Produces: `set_ingest_state(site, kind, ok, count=0, error=None) -> None`；`get_all_ingest_state() -> dict`（形状 `{site: {kind: {ok, ingested_at, count, error}}}`）。Task 4 与 Task 5 依赖这两个。

- [ ] **Step 1: `init_db` 加 `ingest_state` 表**

在 `init_db` 内、`site_settings` 表 CREATE 之后（`conn.commit()` 之前）插入：

```python
        conn.execute("""
            CREATE TABLE IF NOT EXISTS ingest_state (
                site        TEXT,
                kind        TEXT,
                ok          INTEGER,
                ingested_at TEXT,
                count       INTEGER,
                error       TEXT,
                PRIMARY KEY (site, kind)
            )
            """)
```

- [ ] **Step 2: 加 `set_ingest_state` 与 `get_all_ingest_state`**

在 `get_all_status()` 函数之后插入：

```python
def set_ingest_state(site, kind, ok, count=0, error=None):
    """记录一次入库结果（UPSERT）。ok: bool；count: 入库条数；error: 失败原因或 None。"""
    with sqlite3.connect(STATE_DB_PATH) as conn:
        conn.execute(
            "INSERT INTO ingest_state (site, kind, ok, ingested_at, count, error) "
            "VALUES (?, ?, ?, ?, ?, ?) "
            "ON CONFLICT(site, kind) DO UPDATE SET "
            "ok=excluded.ok, ingested_at=excluded.ingested_at, "
            "count=excluded.count, error=excluded.error",
            (site, kind, 1 if ok else 0, _now(), int(count or 0), error or ""),
        )
        conn.commit()


def get_all_ingest_state():
    """返回 {site: {kind: {ok, ingested_at, count, error}}}；库不存在返回 {}。"""
    if not os.path.exists(STATE_DB_PATH):
        return {}
    with sqlite3.connect(STATE_DB_PATH) as conn:
        rows = conn.execute(
            "SELECT site, kind, ok, ingested_at, count, error FROM ingest_state"
        ).fetchall()
    out = {}
    for site, kind, ok, ingested_at, count, error in rows:
        out.setdefault(site, {})[kind] = {
            "ok": bool(ok),
            "ingested_at": ingested_at or "",
            "count": int(count or 0),
            "error": error or "",
        }
    return out
```

- [ ] **Step 3: 编译 + Black**

```
.venv/Scripts/python.exe -m py_compile inbound_verify/state_store.py
.venv/Scripts/python.exe -m black inbound_verify/state_store.py
```
Expected: 无错误。

- [ ] **Step 4: set/get 往返冒烟**

```
.venv/Scripts/python.exe -c "from inbound_verify import state_store as s; s.init_db(); s.set_ingest_state('韵达','expected',True,count=42); s.set_ingest_state('韵达','expected',False,error='boom'); d=s.get_all_ingest_state(); r=d['韵达']['expected']; assert r['ok'] is False and r['count']==42 and r['error']=='boom' and r['ingested_at']; print('ingest_state ok')"
```
Expected: `ingest_state ok`（验证 UPSERT 覆盖：第二次写把 ok 改 False，count 保留 42，error 写入）。

- [ ] **Step 5: Commit（gated）**

```bash
git add inbound_verify/state_store.py
git commit -m "feat(state_store): add ingest_state table + set/get helpers"
```

---

### Task 4: runtime._persist_to_db 钩子 + 挂到 dispatch_task

**Files:**
- Modify: `inbound_verify/runtime.py`（加 `_persist_to_db`，位置在 `_record_business_date` 之后、`dispatch_task` 之前；改 `dispatch_task` 成功分支 `:552-557`）

**Interfaces:**
- Consumes: Task 1 `store.ingest_enabled()`、Task 2 `store.ingest_task(site, kind)`、Task 3 `state_store.set_ingest_state(...)`；既有 `state_store`（runtime 已 import）。
- Produces: `_persist_to_db(site, kind)` 被 `dispatch_task` 在下载成功后调用；下载任务的成功判定**不变**。

- [ ] **Step 1: 加 `_persist_to_db`**

在 `_record_business_date` 函数之后（`def dispatch_task` 之前）插入：

```python
def _persist_to_db(site, kind):
    """下载成功后把本次数据入库 PostgreSQL（尽力而为，绝不外抛，不影响任务判定）。
    - __compare__ 无源数据，跳过。
    - auto_ingest=false 时跳过（无 PG/cpolar 的开发机）。
    - 懒导入 store 以回避 import 顺序（store↔compare 与 runtime↔compare 共存）。
    - 结果写 state_store.ingest_state，供 /api/status 反映入库健康。
    所有写库/写状态都包 try/except：失败仅告警，绝不改变 dispatch_task 的 SUCCESS 判定。"""
    if site == "__compare__":
        return
    try:
        from inbound_verify import store  # 懒导入：冷路径（每下载一次），回避成环
    except Exception as e:
        print(f">> [warn] 入库模块不可用: {e}")
        return
    if not store.ingest_enabled():
        print(">> [入库] 已关闭 (auto_ingest=false)，跳过")
        return
    try:
        count = store.ingest_task(site, kind)
        state_store.set_ingest_state(site, kind, ok=True, count=count)
        print(f">> [入库] {site}/{kind} 成功，{count} 条")
    except Exception as e:
        print(f">> [warn] 入库失败 {site}/{kind}: {e}")
        try:
            state_store.set_ingest_state(site, kind, ok=False, error=str(e))
        except Exception as e2:
            print(f">> [warn] 写入库状态也失败: {e2}")
```

- [ ] **Step 2: 挂到 `dispatch_task` 成功分支**

把 `dispatch_task` 内的成功分支：

```python
        _record_business_date(site, kind)
        return (state_store.TASK_SUCCESS, None)
```

改为：

```python
        _record_business_date(site, kind)
        _persist_to_db(site, kind)
        return (state_store.TASK_SUCCESS, None)
```

（`_persist_to_db` 绝不外抛，故不会被外层 `except Exception` 误判为任务失败。）

- [ ] **Step 3: 编译 + Black + 导入冒烟**

```
.venv/Scripts/python.exe -m py_compile inbound_verify/runtime.py
.venv/Scripts/python.exe -m black inbound_verify/runtime.py
.venv/Scripts/python.exe -c "from inbound_verify.runtime import dispatch_task, _persist_to_db; print('runtime import ok')"
```
Expected: `runtime import ok`。

- [ ] **Step 4: 端到端（手动，需站点已登录）**

任选一种模式触发一次真实下载并观察钩子：

- 服务模式：`POST /tasks` `{"site":"韵达","kind":"expected"}`（或经 dashboard 触发），下载完成后看 worker stdout：
  - 成功：`>> [入库] 韵达/expected 成功，N 条`。
  - 失败（如 PG 未 init）：`>> [warn] 入库失败 ...`，且任务本身仍 `success`（`GET /tasks/{id}` 验证）。
- 交互模式：菜单 `[6]` 韵达应到，完成后看同样的 `[入库]` 行。

并查 `state/state.db`：
```
.venv/Scripts/python.exe -c "from inbound_verify import state_store as s; print(s.get_all_ingest_state())"
```
Expected: 含 `韵达`/`expected` 的记录，`ok` 与 stdout 一致。

- [ ] **Step 5: 关开关降级（手动）**

把 `config.yaml` 的 `auto_ingest` 改 `false`，再触发一次下载：stdout 应出现 `>> [入库] 已关闭 (auto_ingest=false)，跳过`，且不连 PG；任务仍 SUCCESS。验证后改回 `true`。

- [ ] **Step 6: Commit（gated）**

```bash
git add inbound_verify/runtime.py
git commit -m "feat(runtime): auto-ingest hook after successful download"
```

---

### Task 5: /status 暴露 ingest 态 + README

**Files:**
- Modify: `inbound_verify/cli/server.py:189-196`（`get_status`）
- Modify: `README.md`（DB CLI 命令列表）

**Interfaces:**
- Consumes: Task 3 `state_store.get_all_ingest_state()`。
- Produces: `GET /status` 返回体新增 `ingest` 字段。

- [ ] **Step 1: `/status` 加 `ingest` 字段**

把 `get_status` 的返回 dict：

```python
    return {
        "worker_ready": worker_state["ready"],
        "worker_error": worker_state["error"],
        "sites": state_store.get_all_status(),
    }
```

改为：

```python
    return {
        "worker_ready": worker_state["ready"],
        "worker_error": worker_state["error"],
        "sites": state_store.get_all_status(),
        "ingest": state_store.get_all_ingest_state(),
    }
```

并把 docstring 顺手补一句（可选）：`"""各站登录态 + 数据态 + 入库态（前端状态盘用），另含 worker 就绪状态。"""`

- [ ] **Step 2: README DB CLI 命令列表加 `ingest-one`**

`README.md` 第五章"运行"下、DB CLI 注释行（`# 或：inbound-verify-db createdb|init|ingest|all` 附近）补一行说明自动入库 + 新命令：

```
# DB CLI：建库 / 初始化 / 灌数据 / 全流程 / 单站单类
.venv/Scripts/python.exe -m inbound_verify.store createdb   # 或 init | ingest | ingest-one <site> <kind> | all
# 注：下载成功后会自动入库（postgres.auto_ingest，默认开）；ingest-one 用于手动重灌指定站/类。
```

- [ ] **Step 3: 编译 + Black**

```
.venv/Scripts/python.exe -m py_compile inbound_verify/cli/server.py
.venv/Scripts/python.exe -m black inbound_verify/cli/server.py
```
Expected: 无错误。

- [ ] **Step 4: `/status` 含 ingest 字段（手动，服务模式已启动）**

```
curl -s http://127.0.0.1:8000/status | python -m json.tool
```
（或浏览器 `http://127.0.0.1:8000/docs` 试 `/status`。）Expected: 返回体含 `"ingest": {...}` 键（无入库记录时为 `{}`，Task 4 跑过后会有值）。经 dashboard 的 `GET /api/status`（代理）同样可见。

- [ ] **Step 5: 全量回归冒烟**

```
.venv/Scripts/python.exe -m py_compile inbound_verify
.venv/Scripts/python.exe -m black inbound_verify
.venv/Scripts/python.exe -c "import inbound_verify.store, inbound_verify.state_store, inbound_verify.runtime, inbound_verify.cli.server; print('all imports ok')"
```
Expected: `all imports ok`，black 无 diff。

- [ ] **Step 6: Commit（gated）**

```bash
git add inbound_verify/cli/server.py README.md
git commit -m "feat(server): expose ingest state in /status; doc auto-ingest in README"
```

---

## Self-Review 结论

- **Spec 覆盖**：spec §4.1 → Task 1+2；§4.2 → Task 4；§4.3 → Task 3；§4.4 → Task 5；§4.5 配置 → Task 1（config 两文件）；§7 测试手段 → 各任务手动步（ingest-one 路由、端到端、降级、回归）。无遗漏。
- **占位符**：无 TBD/TODO；每步含完整代码与确切命令。
- **类型/命名一致**：`ingest_task(site, kind)`、`ingest_enabled()`、`set_ingest_state(site, kind, ok, count=0, error=None)`、`get_all_ingest_state()`、`_persist_to_db(site, kind)` 在各任务间签名一致；`/status` 字段名 `ingest` 与 `get_all_ingest_state` 返回一致。
- **已标注偏离**：(a) 无 pytest → 用 py_compile/black/冒烟/手动代替（Global Constraints）；(b) 不自动提交 → Commit 步骤 gated（Global Constraints + 每任务注明）；(c) `_connect` 用 `options` 设 statement_timeout 取代 spec 的 `SET`（等价、无额外事务，Task 1 Step 2 注释说明）。