155 lines
4.5 KiB
Markdown
155 lines
4.5 KiB
Markdown
# 09 存档与后端
|
||
|
||
本文档定义新项目的存档模型与后端接口。目标：稳定、可迁移、可扩展、可观测。即使是单机为主，也建议提供云端存档能力以支持跨设备与版本兼容。
|
||
|
||
## 9.1 存档设计目标
|
||
|
||
- 数据完整：可恢复到任意一个确定状态
|
||
- 可迁移：版本升级可做增量迁移
|
||
- 可校验：避免异常/作弊数据导致崩档
|
||
- 可压缩：存档体积可控，读写快速
|
||
|
||
## 9.2 存档分层与结构
|
||
|
||
存档建议由三部分组成：
|
||
|
||
- `meta`：版本、时间戳、校验、内容包版本
|
||
- `player`：玩家状态与资产
|
||
- `world`：世界状态（时间、地点资源、灾害、标记）
|
||
|
||
```json
|
||
{
|
||
"meta": {
|
||
"saveVersion": 3,
|
||
"contentVersion": {"base": "1.0.0", "packs": {"event_pack_01": "1.0.0"}},
|
||
"createdAt": 1730000000000,
|
||
"updatedAt": 1730001234000,
|
||
"checksum": "sha256:..."
|
||
},
|
||
"player": {
|
||
"name": "Player",
|
||
"placeId": "home",
|
||
"stats": {"life": 80, "hunger": 40, "thirst": 60, "energy": 30, "san": 50, "radiation": 10},
|
||
"attributes": {"str": 4, "agi": 5, "int": 6, "per": 5, "luck": 3},
|
||
"inventory": [{"itemId": "water_purified", "count": 2, "durability": null}],
|
||
"equipment": {"weapon": "knife_01", "body": "jacket_01"},
|
||
"buffs": [{"buffId": "infection_1", "startedAt": 1730000500000, "stacks": 1}],
|
||
"quests": {"active": ["q_main_01"], "completed": ["q_tutorial_01"]}
|
||
},
|
||
"world": {
|
||
"time": {"baseTime": 0, "minutesFromStart": 1234},
|
||
"flags": {"met_trader": true},
|
||
"places": {
|
||
"ruins_store": {
|
||
"heat": 3,
|
||
"resourceStock": {"water_dirty": 0, "scrap_metal": 2},
|
||
"lastRefreshAt": 1730001200000
|
||
}
|
||
},
|
||
"disaster": {"activeId": "sandstorm", "endsAt": 1730003000000}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 9.3 存档写入策略
|
||
|
||
- 自动存档触发点（建议）：
|
||
- 回到基地
|
||
- 完成任务步骤
|
||
- 战斗结束
|
||
- 灾害开始/结束
|
||
- 重要事件选择后
|
||
- 快速保存：
|
||
- UI 提供手动保存按钮
|
||
- 保存期间不阻塞主线程（使用异步/worker）
|
||
- 防止坏档：
|
||
- 写入采用“双缓冲”：先写临时，再替换正式
|
||
- 写入失败保留上一份
|
||
|
||
## 9.4 存档校验与迁移
|
||
|
||
### 9.4.1 校验（客户端与服务端）
|
||
|
||
- Schema 校验：字段类型、必填字段、范围
|
||
- 引用校验：itemId/placeId/questId 必须存在于内容库
|
||
- 数值校验：状态上下限、背包容量、堆叠上限
|
||
|
||
### 9.4.2 迁移（SaveVersion）
|
||
|
||
- 每次内容/结构变化提升 `saveVersion`
|
||
- 迁移必须是纯函数：`migrate(save_vN) -> save_vN+1`
|
||
- 迁移记录：
|
||
- 变更点
|
||
- 默认值策略
|
||
- 兼容策略（删字段/改名/拆分）
|
||
|
||
## 9.5 后端能力范围（建议）
|
||
|
||
后端建议至少提供：
|
||
|
||
- 账号与鉴权（匿名账号也可）
|
||
- 云端存档 CRUD
|
||
- 内容包版本与更新清单（可选）
|
||
- 运行日志/错误上报（可选）
|
||
|
||
## 9.6 API 约定（REST 示例）
|
||
|
||
### 9.6.1 鉴权
|
||
|
||
- 登录（匿名/设备绑定）：
|
||
- `POST /api/v1/auth/anonymous`
|
||
- 返回 `accessToken/refreshToken`
|
||
- 请求头：
|
||
- `Authorization: Bearer <accessToken>`
|
||
|
||
### 9.6.2 存档接口
|
||
|
||
- 列表：
|
||
- `GET /api/v1/saves`
|
||
- 读取：
|
||
- `GET /api/v1/saves/{slotId}`
|
||
- 写入（覆盖）：
|
||
- `PUT /api/v1/saves/{slotId}`
|
||
- Body：完整存档 JSON
|
||
- 服务端校验通过后写入
|
||
- 删除：
|
||
- `DELETE /api/v1/saves/{slotId}`
|
||
|
||
### 9.6.3 并发与冲突
|
||
|
||
使用乐观锁：
|
||
|
||
- 存档 meta 带 `etag` 或 `rev`
|
||
- 更新时带 `If-Match: <etag>`
|
||
- 冲突返回 409，客户端提示“本地与云端不一致”
|
||
|
||
## 9.7 速率限制与滥用防护
|
||
|
||
- 写入频率限制：例如每分钟最多 10 次
|
||
- 存档大小限制：例如 1MB
|
||
- 结构化错误码，避免泄漏服务端信息
|
||
|
||
## 9.8 旧版 PHP 存档参考（当前仓库）
|
||
|
||
当前仓库包含简单的 PHP+MySQL 存档端点：
|
||
|
||
- [save.php](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/save.php)：按 `key/data/overwrite` 写入 `record(key,data)`，并校验 `data` 是 JSON
|
||
- [load.php](file:///Users/virtheart/Documents/CloneProjects/TinyWaste/load.php)：按 `key` 读取
|
||
|
||
新项目不建议继续沿用 SAE 环境变量模式与弱协议，建议升级为标准鉴权、版本控制与迁移机制。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant API as Save API
|
||
participant DB as Database
|
||
C->>API: PUT /saves/{slotId} (save, If-Match)
|
||
API->>API: 校验Schema/引用/数值
|
||
API->>DB: 写入(事务)
|
||
DB-->>API: ok
|
||
API-->>C: 200 (new etag)
|
||
```
|
||
|
||
对应源文件：[save-flow.mmd](./diagrams/save-flow.mmd)
|
||
|