# Storage Package 设计文档

## 背景

DeerFlow 当前有多类持久化职责分散在 app、gateway、runtime 和旧 persistence 模块中。这会带来几个问题：

- routers 和 runtime services 容易依赖具体 persistence 实现，而不是稳定契约。
- user/auth、run metadata、thread metadata、feedback、run events、checkpointer setup 的初始化路径不统一。
- memory、SQLite、PostgreSQL 相关路径中存在部分重复逻辑。
- app 层代码和 storage 层代码耦合，导致增量迁移困难。
- 增加或验证新的 SQL backend 时，需要改动 app/runtime，而不是只改 storage package。

引入 storage package 的目标，是把应用数据持久化抽象成 package 级能力，并提供明确契约、清晰边界和 SQL backend 兼容性。

## 目标

- 新增独立的 `packages/storage`，负责 durable application data。
- 通过统一 persistence 构造流程支持 SQLite、PostgreSQL、MySQL。
- 保持 LangGraph checkpointer 与同一个数据库 backend 兼容。
- 将 repository contracts 作为 package 对外唯一数据访问边界。
- app 层通过 `app.infra.storage` 适配 storage，而不是直接依赖 storage DB 实现类。
- 支持 app/gateway 后续小步迁移，避免一次性大重构。

## 非目标

- 第一阶段不删除旧 persistence。
- 不让 routers 直接依赖 storage package models。
- 不让 app routers 管理 SQLAlchemy sessions。
- cron persistence 不属于 storage package 基础迁移范围。
- memory backend 不属于 durable storage package。若 app runtime 仍需要 memory 兼容，应放在 `packages/storage` 之外。

## Storage 设计理念

### Package 自己负责 Durable Storage

`packages/storage` 负责应用数据的 durable persistence，包括：

- storage 持久化配置
- SQLAlchemy models
- repository contracts 和 DTOs
- SQL repository 实现
- persistence factory functions
- 面向现有 config 的兼容初始化入口

该 package 不应该 import `app.gateway`、routers、auth providers 或 runtime 中的 gateway 对象。

### SQL Backend 兼容

该 package 支持三种 SQL backend：

- SQLite：本地或单节点部署
- PostgreSQL：生产多节点部署
- MySQL：使用 MySQL 作为标准数据库的部署

backend 差异在 storage package 内部处理：

- SQLAlchemy async engine URL 构造
- LangGraph checkpointer 连接串兼容
- SQLite/PostgreSQL/MySQL 的 JSON metadata filter
- 不同 SQL 方言在 locking、aggregation、JSON 类型语义上的差异

### 统一 Persistence Bundle

Storage 初始化返回 `AppPersistence` bundle：

```python
@dataclass(slots=True)
class AppPersistence:
    checkpointer: Checkpointer
    engine: AsyncEngine
    session_factory: async_sessionmaker[AsyncSession]
    setup: Callable[[], Awaitable[None]]
    aclose: Callable[[], Awaitable[None]]
```

app runtime 只需要初始化一次 persistence，调用 `setup()`，然后注入：

- `checkpointer`
- `session_factory`
- repository adapters

这样 checkpointer 和应用数据可以对齐到同一个 backend，同时 routers 不需要理解数据库配置。

## Package 结构

```text
backend/packages/storage/
  store/
    config/
      storage_config.py
      app_config.py
    persistence/
      factory.py
      types.py
      base_model.py
      json_compat.py
      drivers/
        sqlite.py
        postgres.py
        mysql.py
    repositories/
      contracts/
        user.py
        run.py
        thread_meta.py
        feedback.py
        run_event.py
      models/
        user.py
        run.py
        thread_meta.py
        feedback.py
        run_event.py
      db/
        user.py
        run.py
        thread_meta.py
        feedback.py
        run_event.py
      factory.py
```

## Persistence 构造

storage 的主要入口：

```python
from store.persistence import create_persistence_from_storage_config

persistence = await create_persistence_from_storage_config(storage_config)
await persistence.setup()
```

为了兼容现有 app database config，也提供：

```python
from store.persistence import create_persistence_from_database_config

persistence = await create_persistence_from_database_config(config.database)
await persistence.setup()
```

预期 app startup 流程：

```python
persistence = await create_persistence_from_database_config(config.database)
await persistence.setup()

app.state.persistence = persistence
app.state.checkpointer = persistence.checkpointer
app.state.session_factory = persistence.session_factory
```

预期 app shutdown 流程：

```python
await app.state.persistence.aclose()
```

## Repository 契约设计

Repository contracts 是 storage package 对外公开的数据访问边界。它们位于 `store.repositories.contracts`，并通过 `store.repositories` re-export。

主要契约包括：

- `UserRepositoryProtocol`
- `RunRepositoryProtocol`
- `ThreadMetaRepositoryProtocol`
- `FeedbackRepositoryProtocol`
- `RunEventRepositoryProtocol`

每组契约包含：

- 输入 DTO，例如 `UserCreate`、`RunCreate`、`ThreadMetaCreate`
- 输出 DTO，例如 `User`、`Run`、`ThreadMeta`
- repository protocol methods
- 必要的领域异常，例如 `InvalidMetadataFilterError`

Repository 通过 session 构造：

```python
from store.repositories import build_run_repository

async with persistence.session_factory() as session:
    repo = build_run_repository(session)
    run = await repo.get_run(run_id)
```

这样可以让 transaction ownership 保持明确。storage package 不通过全局 singleton 隐式隐藏 commit 或 session 生命周期。

## App/Infra 调用契约

app 层不应该直接调用 `store.repositories.db.*`。预期的 app 边界是 `app.infra.storage`。

`app.infra.storage` 负责：

- 从 FastAPI runtime 初始化中接收 `session_factory`
- 为 app-facing repository methods 管理 session 生命周期
- 在必要时将 storage DTOs 转成 app/gateway DTOs
- 迁移期间保留现有 app-facing 名称
- 依赖 storage repository protocols，而不是具体 DB classes

预期 adapter 模式：

```python
class StorageRunRepository(RunRepositoryProtocol):
    def __init__(self, session_factory):
        self._session_factory = session_factory

    async def get_run(self, run_id: str):
        async with self._session_factory() as session:
            repo = build_run_repository(session)
            return await repo.get_run(run_id)
```

为了兼容 gateway，app state 可以暂时保持现有名字，只替换内部实现：

```python
app.state.run_store = StorageRunStore(run_repository)
app.state.feedback_repo = StorageFeedbackStore(feedback_repository)
app.state.thread_store = StorageThreadMetaStore(thread_meta_repository)
app.state.run_event_store = StorageRunEventStore(run_event_repository)
app.state.checkpointer = persistence.checkpointer
app.state.session_factory = persistence.session_factory
```

app-facing objects 可以在迁移期间保留旧方法名，但内部数据访问必须经过 storage contracts。

## 边界规则

### 允许调用的范围

storage package 调用方可以使用：

```python
from store.persistence import create_persistence_from_database_config
from store.persistence import create_persistence_from_storage_config
from store.repositories import build_run_repository
from store.repositories import build_user_repository
from store.repositories import build_thread_meta_repository
from store.repositories import build_feedback_repository
from store.repositories import build_run_event_repository
from store.repositories import RunRepositoryProtocol
from store.repositories import UserRepositoryProtocol
```

app 层应该使用：

```python
from app.infra.storage import StorageRunRepository
from app.infra.storage import StorageUserDataRepository
from app.infra.storage import StorageThreadMetaRepository
from app.infra.storage import StorageFeedbackRepository
from app.infra.storage import StorageRunEventRepository
```

### 禁止调用的范围

app/gateway/router/auth 代码不应该 import：

```python
from store.repositories.db import DbRunRepository
from store.repositories.models import Run
from store.persistence.base_model import MappedBase
```

routers 禁止：

- 创建 SQLAlchemy engines
- 直接创建 SQLAlchemy sessions
- 直接调用 storage DB repository classes
- 直接 commit/rollback storage transactions，除非这是 infra adapter 明确管理的范围
- 依赖 storage SQLAlchemy model classes

storage package 禁止 import：

```python
import app.gateway
import app.infra
import deerflow.runtime
```

依赖方向必须是：

```text
app/gateway -> app.infra.storage -> packages/storage contracts/factories -> packages/storage db implementations
```

禁止反向依赖。

## Checkpointer 兼容

storage persistence bundle 会同时初始化 LangGraph checkpointer 和应用数据持久化。

backend 说明：

- SQLite 使用 `langgraph-checkpoint-sqlite`。
- PostgreSQL 使用 `langgraph-checkpoint-postgres`，需要字符串形式的 `postgresql://...` 连接串。
- MySQL 使用 `langgraph-checkpoint-mysql`，需要字符串形式的 MySQL 连接串。

SQLAlchemy 可以使用 `postgresql+asyncpg://...` 或 `mysql+aiomysql://...` 这类 async driver URL，但 LangGraph checkpointer 构造函数需要普通字符串连接串。这个转换应该封装在 storage driver implementation 内部。

## JSON Metadata Filtering

Thread metadata search 通过 `store.persistence.json_compat` 支持跨方言 JSON filtering。

支持的 filter value 类型：

- `None`
- `bool`
- `int`
- `float`
- `str`

拒绝：

- unsafe keys
- nested JSON path expressions
- dict/list values
- 超出 signed 64-bit 范围的整数

这样可以避免 SQL/JSON path injection，避免 compiled-cache 类型漂移，并保留类型语义，例如 `True != 1`，显式 JSON `null` 不等于 missing key。

## 分步实现方案

### 第 1 步：新增 Storage Package 基础

- 新增 `backend/packages/storage`。
- 增加 storage config models。
- 增加 `AppPersistence`。
- 增加 SQLite/PostgreSQL/MySQL persistence drivers。
- 增加 repository contracts、models、DB implementations 和 factory helpers。
- 接入 package dependency。
- 排除 cron persistence。

### 第 2 步：补齐 Storage Backend 兼容性

- 验证 SQLite setup 和 repository 行为。
- 使用本地 E2E 验证 PostgreSQL 和 MySQL。
- 修复 checkpointer 连接串兼容。
- 修复 PostgreSQL locking 和 aggregation 差异。
- 增加跨方言 JSON metadata filtering。

### 第 3 步：新增 App Infra Adapters

- 新增 `backend/app/infra/storage`。
- 实现 app-facing repositories，由它们管理 session 生命周期。
- 保持 storage contracts 作为唯一数据访问边界。
- 为现有 app/gateway method shape 增加兼容 adapters。
- 避免 `packages/storage` import app/gateway。

### 第 4 步：切换 FastAPI Runtime 注入

- 在 FastAPI startup/lifespan 中初始化 storage persistence。
- 将 `persistence`、`checkpointer`、`session_factory` 注入 `app.state`。
- 暂时保留现有对外 state 名称：
  - `run_store`
  - `feedback_repo`
  - `thread_store`
  - `run_event_store`
  - `checkpointer`
  - `session_factory`
- 先切 user/auth provider 构造，再逐步迁移 run/thread/feedback/run_event。

### 第 5 步：Router 和 Auth 兼容

- 确保 routers 消费 app-facing adapters，而不是 storage DB classes。
- 确保 auth providers 依赖 user repository contracts。
- 保持 router response shapes 不变。
- 增加 auth/admin/router regression tests。

### 第 6 步：清理旧 Persistence

- app/gateway 迁移完成后，再比较旧 persistence usage。
- 所有 call sites 迁移完成后，再删除未使用的旧 repository implementations。
- 只在必要时保留短期 compatibility shims。
- 从 storage-owned durable persistence 中移除 memory backend 路径。

## 测试策略

单测应覆盖：

- config parsing
- persistence setup
- table creation
- repository CRUD/query behavior
- typed JSON metadata filtering
- dialect SQL compilation
- cron exclusion

E2E 应覆盖：

- SQLite persistence setup
- PostgreSQL temporary database setup
- MySQL temporary database setup
- 所有支持 SQL backend 下的 repository contract 行为
- JSON/Unicode round trip
- rollback behavior
- persistence close/cleanup

如果 CI 暂时没有 PostgreSQL/MySQL services，E2E 可以先作为 local-only 验证保留。