# 需求综述

实现游戏引擎存档系统（`SaveSystem`）及全局事务（`GlobalTransaction`）两个类的完整逻辑。
存档系统分为两部分：

- **存档内容**：按 slot id 保存/读取游戏当前状态（`Map<string, ISaveableContent<unknown>>`），
  使用 Dexie 将数据存入 IndexedDB。
- **全局存储**：跨存档的 key-value 存储，用于存放存档 meta data、全局设置等。
  支持事务处理，事务中的写入操作在发生错误时全部回滚。

此外，系统提供基于内存的自动存档，并支持 undo/redo 操作。
自动存档不主动写入 IndexedDB，只有显式调用 `saveAutosaveToDB` 时才将 undo
栈顶存档写入数据库。
存档操作使用 `performance` 接口监控耗时，超过配置阈值时通过 logger 发出警告。

---

# 实现思路

## 1. Dexie 数据库 Schema 设计

`SaveSystem` 构造函数接收数据库名称 `name`，在其中创建如下两张表：

| 表名     | 主键            | 说明                                                      |
| -------- | --------------- | --------------------------------------------------------- |
| `saves`  | `id`（number）  | 按 slot id 存储存档数据；`id = -1` 固定用于持久化自动存档 |
| `global` | `key`（string） | 全局 key-value 存储                                       |

- `saves` 表中每条记录结构为 `{ id: number, compression: SaveCompression, data: Map<string, unknown> }`，
  与 `ISaveRead` 对应，直接利用 IndexedDB 的结构化克隆存储，不进行 JSON 序列化。
- `global` 表中每条记录结构为 `{ key: string, value: unknown }`，
  同样直接存储，不进行 JSON 序列化。

## 2. 内部状态

`SaveSystem` 需要维护如下私有成员：

- `private undoStack: ISaveRead[]`：undo 栈，存储 `ISaveRead` 快照
- `private redoStack: ISaveRead[]`：redo 栈，存储 `ISaveRead` 快照
- `private stackSize: number`：undo/redo 栈最大容量（默认 `20`）
- `private autosaveLevel: SaveCompression`：默认 `SaveCompression.LowCompression`
- `private commonSaveLevel: SaveCompression`：默认 `SaveCompression.HighCompressoin`
- `private saveTimeTolerance: number`：默认 `100`（ms）
- `private autosaveTimeTolerance: number`：默认 `50`（ms）

## 3. ISaveRead 数据结构

栈与数据库读写均使用新接口 `ISaveRead`：

```ts
interface ISaveRead {
    readonly compression: SaveCompression;
    readonly data: Map<string, unknown>;
}
```

- `compression`：存档时使用的压缩等级，读档时传回给 `loadState`，使接收方能够正确解压。
- `data`：key 到每个可存档对象序列化数据的 Map，key 与 `ISaveableContent` 注册时的 id 对应。

内存栈和数据库均直接存储 `ISaveRead`，不需要引入辅助包装层。
存档系统本身不负责将数据写回游戏对象，调用方拿到 `ISaveRead` 后自行遍历并调用
各可存档对象的 `loadState(data, compression)` 完成状态恢复。

## 4. 各方法实现

### `config(config)`

将 config 各字段写入对应私有成员，使用传入的值覆盖默认值。

### `setAutosaveStackSize(size)`

将 `stackSize` 更新为 `size`。如果当前 undo 栈超过新的 `size`，
从栈底移除多余条目（保留最新的）；redo 栈同理。

### `autosave(state)`

1. 遍历 `state`，对每个 `(key, content)` 调用
   `content.saveState(this.autosaveLevel)` 获取序列化数据，
   汇总为 `Map<string, unknown>`，构建 `ISaveRead { compression: autosaveLevel, data }` 并压入 `undoStack`；
2. **清空 `redoStack`**（执行新的自动存档后无法再 redo）；
3. 若 `undoStack.length > stackSize`，从栈底（`[0]`）移除多余条目。

> IndexedDB 支持结构化克隆，Map、Set、TypedArray 等均可直接存储，无需 JSON 序列化。

### `undoAutosave(current)`

1. 若 `undoStack` 为空，返回 `null`；
2. 将 `current` 序列化为 `ISaveRead { compression: autosaveLevel, data: Map }`，
   压入 `redoStack`；检查 `redoStack.length > stackSize`，超长时从栈底移除多余条目；
3. 弹出 `undoStack` 栈顶（`pop()`），返回弹出的 `ISaveRead`；
4. 调用方拿到返回的 `ISaveRead` 后，自行遍历并对各游戏对象调用 `loadState` 完成恢复。

### `redoAutosave(current)`

与 `undoAutosave` 逻辑对称：将 `current` 序列化压入 `undoStack`，
弹出 `redoStack` 栈顶并返回，调用方自行恢复状态。

### `getUndoStack()` / `getRedoStack()`

使用 `slice()` 返回栈数组的浅拷贝快照，防止外部意外修改栈结构。

### `saveAutosaveToDB()`

1. 若 `undoStack` 为空，直接返回（无需写入）；
2. 记录 `t0 = performance.now()`；
3. 取 `undoStack` 栈顶（`ISaveRead`），将其连同 `id = -1` 一起写入 `saves` 表；
4. 记录 `t1 = performance.now()`；若 `t1 - t0 > autosaveTimeTolerance`，
   调用 `logger.warn(115, (t1 - t0).toFixed(0), this.autosaveTimeTolerance.toString())`。

### `save(id, state)`

1. 记录 `t0 = performance.now()`；
2. 遍历 `state`，对每个 `(key, content)` 调用
   `content.saveState(this.commonSaveLevel)` 汇总为 `Map<string, unknown>`，
   构建 `{ id, compression: commonSaveLevel, data }` 写入 `saves` 表；
3. 将 `id` 写入全局存储 `'lastSlot'` 键（用于 `getLastSlot()`）；
4. 记录 `t1 = performance.now()`；若 `t1 - t0 > saveTimeTolerance`，
   调用 `logger.warn(114, (t1 - t0).toFixed(0), this.saveTimeTolerance.toString())`。

### `load(id)`

1. 从 Dexie `saves` 表查询 `id`；
2. 若不存在返回 `null`；
3. 将读取到的记录中的 `compression` 和 `data` 字段组装成 `ISaveRead` 返回。
   调用方自行遍历 `data` 并对各游戏对象调用 `loadState` 完成恢复。

> `load(-1)` 可用于读取持久化的自动存档。

### `deleteSave(id)`

直接从 Dexie `saves` 表删除对应记录。

### `getLastSlot()`

从全局存储读取 `'lastSlot'` 键对应的值并返回；若不存在则返回 `0`。

### `getGlobal<T>(key)` / `setGlobal(key, value)`

- `getGlobal`：从 Dexie `global` 表读取 `key` 对应的 `value` 字段并返回，类型断言为 `T`；
- `setGlobal`：将 `{ key, value }` 直接写入 Dexie `global` 表，无需 JSON 序列化。

### `startGlobalTransaction<R>(handle)`

使用 `Dexie.transaction('rw', this.db.table('global'), ...)` 包裹 `handle` 调用，
传入 `GlobalTransaction` 实例，出错时自动回滚。

### `GlobalTransaction.get<T>(key)` / `GlobalTransaction.set(key, value)`

在事务上下文中直接读写 `table`（即全局 `global` 表的引用），无需 JSON 序列化。

## 5. logger.json 新增 warn 代码

当前最大 warn 代码为 `113`，新增如下两条（写入 `packages/common/src/logger.json`
的 `warn` 对象，置于 `113` 之后）：

| 代码  | 消息                                                                                                  |
| ----- | ----------------------------------------------------------------------------------------------------- |
| `114` | `Save operation took $1ms, exceeding the tolerance of $2ms. Consider reducing compression level.`     |
| `115` | `Autosave operation took $1ms, exceeding the tolerance of $2ms. Consider reducing compression level.` |

---

# 涉及文件

## 需要引用的文件

- `dexie`：Dexie / Table 类型，用于创建和操作 IndexedDB 数据库
- `@motajs/common`：`logger`，用于输出存档耗时超限警告
- `@user/data-base`：`ISaveableContent`、`SaveCompression`，存档接口与压缩枚举
- `./types`：`ISaveRead`、`IGlobalTrasaction`、`ISaveSystem`、`ISaveSystemConfig`

## 需要修改的文件

### `packages/common/src/logger.json`

- [x] 在 `warn` 对象中新增代码 `114`：普通存档耗时超限警告
- [x] 在 `warn` 对象中新增代码 `115`：自动存档耗时超限警告

### `packages-user/data-state/src/save/system.ts`

- [x] 新增 `private undoStack: ISaveRead[]` 成员：存储 undo 历史快照
- [x] 新增 `private redoStack: ISaveRead[]` 成员：存储 redo 历史快照
- [x] 新增 `private stackSize: number` 成员：undo/redo 栈容量上限，默认 `20`
- [x] 新增 `private autosaveLevel: SaveCompression` 成员：
      默认 `SaveCompression.LowCompression`
- [x] 新增 `private commonSaveLevel: SaveCompression` 成员：
      默认 `SaveCompression.HighCompressoin`
- [x] 新增 `private saveTimeTolerance: number` 成员：普通存档耗时阈值，默认 `100`
- [x] 新增 `private autosaveTimeTolerance: number` 成员：自动存档耗时阈值，默认 `50`
- [x] 编写构造函数：初始化 Dexie 实例，定义 `saves`（主键 `id`）和
      `global`（主键 `key`）两张表的 schema
- [x] 编写 `config` 方法：将配置项写入私有成员
- [x] 编写 `setAutosaveStackSize` 方法：更新 stackSize，修剪超长的 undo/redo 栈
- [x] 编写 `autosave` 方法：遍历 state 序列化为 `ISaveRead` 压入 undoStack，
      清空 redoStack，超长时修剪栈底
- [x] 编写 `undoAutosave` 方法：将 current 序列化为 `ISaveRead` 压入 redoStack，
      弹出 undoStack 栈顶返回 `ISaveRead`（或 null）
- [x] 编写 `redoAutosave` 方法：与 undoAutosave 对称
- [x] 编写 `getUndoStack` / `getRedoStack` 方法：使用 `slice()` 返回栈的浅拷贝快照
- [x] 编写 `saveAutosaveToDB` 方法：取 undoStack 栈顶以 `id = -1` 写入 `saves` 表，
      performance 监控，超限时调用 `logger.warn(115, ...)`
- [x] 编写 `save` 方法：遍历 state 序列化为 `ISaveRead` 写入 `saves` 表，
      更新 `lastSlot`，performance 监控，超限时调用 `logger.warn(114, ...)`
- [x] 编写 `load` 方法：从 Dexie `saves` 表读取记录组装为 `ISaveRead` 返回
      （不存在返回 null）；`load(-1)` 可读取持久化的自动存档
- [x] 编写 `deleteSave` 方法：从 Dexie `saves` 表删除指定记录
- [x] 编写 `getLastSlot` 方法：从全局存储读取 `'lastSlot'`，不存在时返回 `0`
- [x] 编写 `getGlobal` / `setGlobal` 方法：直接读写 Dexie `global` 表，不进行 JSON 序列化
- [x] 编写 `startGlobalTransaction` 方法：
      使用 Dexie 事务包裹 handle，传入 GlobalTransaction 实例

### `packages-user/data-state/src/save/system.ts`（GlobalTransaction 部分）

- [x] 编写 `GlobalTransaction.get` 方法：在事务上下文中直接读取 table 中 key 对应的 value
- [x] 编写 `GlobalTransaction.set` 方法：在事务上下文中直接写入 key-value，不进行 JSON 序列化