# 独立配置存储与迁移

此功能属于 0.4.0，尚未在实际 profile 中执行迁移。包版本 0.4.0（未发布）。

## 数据位置

完整的外观、文案、规则、分组、选择和触发配置保存到宿主文件：

`<profile-dir>/dsh-status-flair/settings.json`

路径只来自宿主可信的 profileContext.dir，不接受浏览器传入路径。不同 profile 使用不同文件；不是浏览器 localStorage，也不与其他插件共用预设文件。

主配置仅需轻量的 `storage: file` 标记。旧 `flair` 仅用于兼容读取，不再通过 volatile 表单写入，旧页面不能重新写回已经清理的大块数据。

## 操作流程

1. 打开插件页，只读取数据，不创建目录或文件，不自动清理旧主配置。
2. 建议先点“备份成文件”，把当前配置和迁移前原件存成 JSON，另放一处留底。
3. 无未保存草稿时，可点“迁移并清理旧配置”，再点“确认迁移”。
4. 迁移先将已保存配置与原始旧配置备份写入独立文件，读取校验成功后，才通过 DSH 配置编辑器清理本插件旧块并写入标记。
5. 编辑后的普通“保存修改”也写入独立文件，并在落盘后补上主配置标记，但不会删除旧 flair。已有旧块时，随后可点“完成迁移 / 清理旧配置”，它只删除主配置里的残留，不覆盖独立文件。

未保存草稿不能直接迁移；可先保存，或放弃后迁移。清理只处理当前可编辑 profile 的本插件字段，不删除整个插件条目，不改其他插件。若继承层仍提供旧字段、配置已改变、文件校验失败或编辑器拒绝写入，旧数据保留并显示待清理提示。重试清理不会用旧配置覆盖已经保存的独立文件。

## 备份与恢复

独立文件保留首次迁移时的原始 rawFlair、当时有效的 effectiveFlair、来源指纹和时间。后续保存不替换这份原始备份。导出文档同时包含当前配置和迁移备份；其中可能有自定义文案及图标，不宜公开分享。

迁移前请用“备份成文件”自己留底；插件不会替用户另存一份可恢复的副本。独立文件里只保留一份迁移时的原始记录，用于清理前校验，不提供读取按钮。

内部文件和导出备份的格式不同，不能直接用导出 JSON 覆盖内部文件。降级到旧版前，应备份整份独立文件，并从导出备份中恢复旧版所需的 flair 字段；实际 profile 修改需另外确认。损坏文件只报错且禁止保存，不自动重置为默认值；应保留损坏现场，再从完整文件备份恢复或安排明确的恢复操作。

备份位于独立文件内，不能替代异地副本。整份文件被删除时，内置备份也会丢失。成功写入 file 标记后，缺失文件会报错而不是静默恢复旧配置；同一运行实例见过独立文件后也会拒绝这种回退。若标记写入失败，应先完成迁移，不应删除文件或把待完成状态视为全部迁移成功。

## 并发、失败与同步

- 每个 profile 的同一宿主内，保存按队列执行，校验草稿捕获的 revision。另一页面先保存后，旧草稿会收到冲突提示并保留，不自动升级版本重试。
- 保存期间继续编辑，不会被先前保存的确认响应清掉；下一次保存使用已确认版本作为基线。
- 完整数据写入同目录临时文件，先同步文件，再原子重命名；成功后才确认保存。操作标识用于识别响应丢失后的已提交操作，避免盲目重写。
- 数据轮询约每 5 秒一次，窗口重新聚焦时重读。这与规则的最短切换间隔 3000ms 是两套独立机制；没有伪造原生 settings 通知。
- 损坏 JSON、未知文件格式、权限错误及已标记但缺失的文件，不会被当作首次使用而写回默认值。
- 只保证单宿主内的跨浏览器并发保护。外部文件修改仅能在保存前尽力检测，不具备跨进程原子 CAS；不要在保存期间手工改文件，也不要让多个宿主进程同时写同一 profile。
- 写入接口通过 DSH connection 的认证、owner-only Fetch 路由提供；不使用无认证的公开 webServer 写接口。

## 验证范围

离线测试使用临时 profile，覆盖首次保存标记、原始备份、损坏与缺失文件、保存冲突、原子写失败、迁移重试、清理前锁内校验和 HMR 自关闭。客户端测试覆盖只读打开、跨页更新、丢失确认、过期响应、二次确认、恢复草稿及保存期间继续编辑。

这些测试不代表实际 profile 已经迁移。首次真实迁移仍需在页面核对数据、备份位置和确认提示。