# SQLite EventManager 重构规范

## 概述

将 EventManager 从内存存储迁移到 SQLite，实现事件持久化、分页加载和更好的查询性能。

## 决策摘要

| 项目 | 决定 |
|------|------|
| 写入策略 | 实时写入（每个事件立即写入 SQLite） |
| 前端加载 | 分页加载，向上滚动加载更旧事件 |
| 每页数量 | 100 条 |
| 数据库位置 | 每个存档一个，格式 `{save_name}_events.db` |
| 索引策略 | SQLite 原生索引 |
| 数据清理 | 用户控制（提供"清理历史"按钮） |
| 旧数据迁移 | 自动迁移（加载时从 JSON 迁移到 SQLite） |
| 实时推送 | 保持现有 WebSocket 方式 |
| 错误处理 | 静默失败，记录日志但不影响游戏运行 |
| API 分页 | Cursor 分页（复合 cursor: month_stamp + rowid） |
| Pair 查询 | 在事件筛选器中增加"筛选两人"选项 |
| 多存档 | 支持，使用时间戳命名（如 `save_20260105_1423`） |
| 优先级 | **高** |

---

## 数据库设计

### 表结构

```sql
-- 事件主表
CREATE TABLE events (
    id TEXT PRIMARY KEY,              -- UUID
    month_stamp INTEGER NOT NULL,     -- 月份时间戳
    content TEXT NOT NULL,            -- 事件内容
    is_major BOOLEAN DEFAULT FALSE,   -- 是否为大事（长期记忆）
    is_story BOOLEAN DEFAULT FALSE,   -- 是否为故事事件
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 事件-角色关联表
CREATE TABLE event_avatars (
    event_id TEXT NOT NULL,
    avatar_id TEXT NOT NULL,
    PRIMARY KEY (event_id, avatar_id),
    FOREIGN KEY (event_id) REFERENCES events(id) ON DELETE CASCADE
);

-- 索引
CREATE INDEX idx_events_month_stamp ON events(month_stamp DESC);
CREATE INDEX idx_events_is_major ON events(is_major);
CREATE INDEX idx_event_avatars_avatar_id ON event_avatars(avatar_id);
CREATE INDEX idx_event_avatars_event_id ON event_avatars(event_id);
```

### 复合 Cursor 格式

```
{month_stamp}_{rowid}
```

使用 SQLite rowid 而非 UUID，保证同一 month_stamp 内的确定性排序（UUID 排序不稳定）。

示例: `1764_12345`

---

## API 设计

### GET /api/events

获取事件列表（分页）。

**Query Parameters:**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| avatar_id | string | 否 | 按单个角色筛选 |
| avatar_id_1 | string | 否 | Pair 查询：角色 1 |
| avatar_id_2 | string | 否 | Pair 查询：角色 2（需同时提供 avatar_id_1） |
| cursor | string | 否 | 分页 cursor，获取该位置之前的事件 |
| limit | int | 否 | 每页数量，默认 100 |

**Response:**

```json
{
  "events": [
    {
      "id": "uuid",
      "text": "147年5月: 张三开始修炼",
      "content": "张三开始修炼",
      "year": 147,
      "month": 5,
      "month_stamp": 1764,
      "related_avatar_ids": ["avatar_id_1"],
      "is_major": false,
      "is_story": false
    }
  ],
  "next_cursor": "1764_12345",  // null 表示没有更多
  "has_more": true
}
```

### DELETE /api/events/cleanup

清理历史事件（用户触发）。

**Query Parameters:**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keep_major | bool | 否 | 是否保留大事，默认 true |
| before_month_stamp | int | 否 | 删除此时间之前的事件 |

---

## 后端实现

### 新增文件

```
src/classes/event_storage.py     # SQLite 存储层
```

### 修改文件

```
src/classes/event_manager.py     # 重构为使用 SQLite
src/server/main.py               # 新增分页 API
src/sim/save/save_game.py        # 关联数据库文件
src/sim/load/load_game.py        # 加载时连接数据库
```

### EventStorage 类

```python
class EventStorage:
    """SQLite 事件存储层。"""

    def __init__(self, db_path: Path):
        """初始化数据库连接，创建表（如不存在）。"""

    def add_event(self, event: Event) -> bool:
        """
        写入单个事件。
        失败时记录日志并返回 False，不抛异常。
        """

    def get_events(
        self,
        avatar_id: str | None = None,
        avatar_id_pair: tuple[str, str] | None = None,
        cursor: str | None = None,
        limit: int = 100,
    ) -> tuple[list[Event], str | None]:
        """
        分页查询事件。
        返回 (events, next_cursor)。
        """

    def get_events_by_avatar(self, avatar_id: str, limit: int = 50) -> list[Event]:
        """后端用：获取角色相关事件（供 LLM prompt 使用）。"""

    def get_events_between(self, id1: str, id2: str, limit: int = 50) -> list[Event]:
        """后端用：获取两角色之间的事件。"""

    def cleanup(self, keep_major: bool = True, before: int | None = None) -> int:
        """清理事件，返回删除数量。"""

    def close(self):
        """关闭数据库连接。"""
```

### EventManager 重构

```python
class EventManager:
    """重构后的 EventManager，使用 SQLite 存储。"""

    def __init__(self, storage: EventStorage):
        self._storage = storage
        # 移除所有内存索引（_events, _by_avatar, _by_pair 等）

    def add_event(self, event: Event) -> None:
        """实时写入 SQLite。"""
        self._storage.add_event(event)

    # 其他查询方法委托给 storage
```

---

## 前端实现

### 修改文件

```
web/src/stores/world.ts                    # 事件状态管理
web/src/components/panels/EventPanel.vue   # 分页 UI
web/src/api/game.ts                        # 新增 API
```

### 事件状态管理

```typescript
// world.ts
interface EventState {
  events: GameEvent[];
  cursor: string | null;
  hasMore: boolean;
  isLoading: boolean;
}

// 新增 actions
async function loadMoreEvents(): Promise<void>;
async function resetEvents(avatarId?: string, avatarId2?: string): Promise<void>;
```

### EventPanel 改动

1. **向上滚动加载**：监听滚动事件，当接近顶部时触发 `loadMoreEvents()`
2. **筛选器扩展**：增加"筛选两人"选项
3. **加载指示器**：显示加载状态
4. **切换筛选重置**：切换角色时调用 `resetEvents()` 重新加载

### 筛选器 UI

```
[所有人 ▼] [+ 添加第二人]

// 选择第二人后变为：
[张三 ▼] [李四 ▼] [×]
```

---

## 存档系统整合

### 文件结构

```
assets/saves/
├── save_20260105_1423.json          # 游戏状态
├── save_20260105_1423_events.db     # 事件数据库
├── save_20260105_1500.json
└── save_20260105_1500_events.db
```

### 保存流程

1. 保存 JSON 存档（现有逻辑）
2. 确保数据库文件存在（实时写入已处理）
3. 可选：执行 `VACUUM` 优化数据库大小

### 加载流程

1. 读取 JSON 存档
2. 连接对应的 `_events.db` 文件
3. 如果数据库不存在，创建空数据库

### 新建游戏

1. 生成时间戳名称：`save_YYYYMMDD_HHMM`
2. 创建空数据库文件
3. 初始化游戏状态

---

## 错误处理

### SQLite 写入失败

```python
def add_event(self, event: Event) -> bool:
    try:
        # 写入逻辑
        return True
    except Exception as e:
        logger.error(f"Failed to write event: {e}")
        return False  # 不抛异常，游戏继续运行
```

### 数据库文件丢失

加载存档时，如果 `_events.db` 不存在：
- 记录警告日志
- 创建新的空数据库
- 游戏正常运行（但没有历史事件）

---

## TODO（未来扩展）

```python
# TODO(xzhseh): 事件搜索功能
# - 支持按关键词搜索事件内容
# - 可能需要 SQLite FTS5 扩展

# TODO(xzhseh): 事件分类/标签系统
# - 添加 event_type 字段（combat/cultivation/social/death 等）
# - 支持按类型筛选
```

---

## 实现顺序

1. **Phase 1: 后端核心** ✅
   - [x] 创建 `EventStorage` 类
   - [x] 重构 `EventManager`
   - [x] 修复 `event_id` → `id` bug
   - [x] 实现分页 API

2. **Phase 2: 存档整合** ✅
   - [x] 修改保存/加载逻辑
   - [x] 支持多存档槽位
   - [x] 时间戳命名

3. **Phase 3: 前端** ✅
   - [x] 分页加载 UI
   - [x] 向上滚动加载
   - [x] 双人筛选器

4. **Phase 4: 清理**
   - [x] 用户清理历史 API（`/api/events/cleanup`）
   - [ ] 清理历史 UI 按钮
   - [x] 移除旧的内存索引代码（EventManager 已重构）