# 设置中的存档导入与导出

2026-10-17 用户已确认布局和交互；实现已进入 `0.37.1-rc.2` 集成分支，待验收后发布。当前待办统一见 [ROADMAP](../ROADMAP.md)。

## 入口与样式

DSH 和桌面版都在「设置」中新增「存档」，放在「扩展」之后、「小猪大小」之前。保持面板宽 292px，复用现有 `dp-set`、`dp-actions` 和药丸按钮，不增加主菜单 App。

```text
设置

更新                         [更新]
扩展                         [扩展]

存档
备份进度，或把小猪带到另一台设备
[ 导出存档 ]       [ 导入存档 ]

小猪大小
……现有设置……
```

两个入口使用现有次要按钮；只有导入确认页的「备份并导入」使用主按钮。正常页面仅有一句说明，文件范围和替换提示放到导入确认页。

## 导出

1. 点击「导出存档」，按钮显示「导出中…」，暂时禁止重复操作。
2. 宿主结清在途写入和工作事件事务，生成同一时点的完整备份。
3. 桌面端弹系统保存框；网页端使用保存文件选择器，不支持时走浏览器下载。
4. 默认文件名为 `piggy-save-YYYYMMDD-HHmm.zip`。成功后由小猪短暂提示「存档已导出」；取消不报错，写入失败恢复按钮并说明原因。

默认导出一份完整包，不让用户先选择复杂的备份范围：

| 包含 | 说明 |
|---|---|
| 养成存档 | 猪、金币、物品、奖励、图鉴、日记、设置中跟随猪的偏好、农场和矿洞等扩展进度 |
| 自定义皮肤 | 已安装皮肤的描述和图片，避免换设备后只剩记录 |
| 已安装官方扩展 | 对应版本的扩展包，支持离线恢复；恢复时仍走现有官方校验 |
| 已提交工作收据 | 与该快照配套的去重记录，避免恢复后同一工作事件重复奖励 |

不带日志、代理凭据、接入令牌、绝对路径、运行锁、未完成事务、下载缓存、窗口位置或本机缩放。内置素材使用目标版本自带内容。

## 导入

点击「导入存档」打开文件选择框，支持本功能导出的 ZIP，并兼容已有 `state.json`。选文件后只校验、预览，此时不改当前存档。

```text
导入存档

小猪：团团 · Lv.12
备份时间：2026-10-17 20:30
游戏版本：0.37.1-rc.2
内容：养成进度、2 个扩展、1 个自定义皮肤

将替换当前这只猪。
当前存档会先自动备份，导入后两边不会自动同步。

[ 取消 ]             [ 备份并导入 ]
```

以上名字和等级仅为示例；确认页展示文件中的真实摘要。旧 JSON 无备份时间时显示「未记录」，不拿文件修改时间冒充备份时间。若它缺少扩展文件或自定义皮肤，明确列出缺项，不称为完整备份。

确认后的流程：

1. 暂停新的游戏动作和工作事件写入，等待现有操作结束。
2. 自动备份当前完整存档；备份失败则停止，当前猪继续可用。
3. 在临时区域完成校验、旧档迁移与资源检查，再通过可恢复的导入事务切换；不能边解压边覆盖正在使用的文件。
4. 成功后切换运行时并刷新两个窗口或网页面板，显示「存档已导入」。桌面端若需要重开，确认前明确提示，不静默退出。
5. 失败时恢复原存档和运行时；断电或异常退出时，下次启动先恢复导入事务。自动备份保留，不能把失败文件当空白新猪启动。

导入就是整档替换，不累加金币、物品或奖励，不在此处实现 #14 的两猪取优合并。DSH 与桌面之间可手动导出、导入；导入后仍各自独立。

## 数据与兼容边界

- 两种运行形态共用一套运行时导入/导出服务，不让设置页直接读取或覆盖 `state.json`。现有桌面托盘「从 DSH 导入猪」只复制 JSON，不能当作完整备份实现直接复用。
- 备份说明记录格式版本、游戏版本、存档版本和文件清单；校验和用于完整性，扩展可信性继续使用现有官方识别规则。
- 旧存档先迁移到临时区域；高于当前支持版本时拒绝导入并提示升级，原存档不动。
- 无法验证的扩展保留其进度，不加载其代码，并在预览中说明需重新安装；自定义皮肤继续沿用现有图片校验。
- 保存工作收据前结清事务；导入时恢复与导入猪匹配的收据，不继续套用目标设备旧猪的事务或收据。接入令牌在目标设备重新生成。
- 解包只接收规定文件，限制文件数和解压体积，拒绝越界路径、符号链接和无关文件。主机路径和凭据不进入备份。
- 没有猪时仍可导入；导出入口显示不可用并提示「接到小猪后即可备份」。

## 实现后的验收要求

1. Windows、Linux 桌面和 DSH 网页走真实按钮完成导出、导入、取消；macOS 未实机验证时如实标注。
2. 备份包含自定义皮肤、农场/矿洞进度；在另一份全新目录恢复后核对金币、物品、奖励和进度，重启后仍一致。
3. 覆盖旧 JSON、缺失资源、旧档迁移、新版存档拒绝、损坏包、无写入权限和取消选择。
4. 连续点击、两个窗口同时发起操作、工作事件正在写入时，不生成混合时点快照，不重复发奖励。
5. 验证自动备份失败不替换，导入中断和恢复失败不丢原档，成功及失败后的运行锁都正确。
6. 窄面板、键盘焦点、Tab/Shift+Tab、Esc 和窗口缩放沿用已有行为；不引入新的宽大透明点击区域。

实现已接入运行时代码与自动化测试；集成分支主机全量 1231/1231 通过，本轮不迁移真实存档、不创建新版本或发布。

## 候选实现约束

- 一份存档独占一个目录；自定义 statePath 支持任意文件名，但不能叫 skins、extensions 或 backups（会与同目录的资源/备份目录重名；Windows 和 macOS 默认不区分大小写），否则导入和导出都会拒绝，避免把状态文件本身当成目录替换。
- ZIP 压缩体积与总展开体积均不超过 32 MiB，最多 512 项，单文件最多 8 MiB；导入预览十分钟内有效，重新选文件会撤销上一份预览。
- 导入预览最多返回 50 条具体提示，超出部分合并为「另有 N 条提示」；自定义皮肤记录最多 128 个，导出和导入都会拒绝超限存档。
- 自动备份位于存档同目录的 backups；导入是整档替换，不能用于同时同步两只猪。
- 提交标记发布后即完成导入；仅事务临时目录清理失败会延迟到下次启动清理，不再误报导入失败。若回滚本身受磁盘错误阻断，停止游戏写入并保留事务证据，修复磁盘后重启恢复。