# 归档布局、命名与迁移

> 本文从 [README.md](../README.md) 拆出，单独成篇是为了让它能被单独引用与单独评审。

### 包内长什么样

| 条目类型 | 归档内部 |
| --- | --- |
| 软件名 + Slot 目录 | `<Slot>\<该 Path 的内容>` |
| 软件名 + Slot 文件 | 一个名为 `<Slot>` 的文件（没有扩展名，恢复时还原成 Path 里的原名） |
| 手写路径（目录） | `<路径末级名>\...`（与历史归档一致） |
| 手写路径（文件） | 一个名为 `<路径末级名>` 的文件 |
| `:+` / `Include` 追加项 | 你写的那个 `<归档内相对路径>`（目录就是目录，文件就是那个文件） |

7z 没有"入库时改名"的能力，所以打包前会建一个**暂存目录**：目录项用 junction、
文件项用硬链接（不可用时退回复制）按归档内的名字挂进去，打完立刻拆掉。
建不出连接点时会**明确报错**，不会悄悄换成另一种布局——布局一变恢复就对不上了。

### 归档名

| 条目类型 | 归档名 |
| --- | --- |
| 软件名 | `<软件名>.7z` |
| 字面路径 | `<末级名>_from_<上级路径用 + 连接>.7z`（`:` 归一化成 `_`） |
| 软件名 + `@pathname` | 同字面路径 |

> `::` / `@ Path=` 只改**从哪儿读**，不改归档名：软件名条目仍然叫 `<软件名>.7z`。
> 想换归档名就用 `@pathname`，或者干脆把条目写成绝对路径。

### 从旧版迁移（重要）

1. **包内布局变了。** 重构前生成的归档，包内顶层是源目录名；现在软件名条目多了一层 Slot。
   `Restore.ps1` 会识别这种情况（归档里没有该 Slot 时打印告警并按旧布局解），
   所以**旧归档仍然恢复得出来**；但要让包内结构统一，跑一次 `.\Backup.ps1 -Force` 重打即可
   （`-Force` 会忽略"源未更新"判断）。
2. **手写路径条目的归档名可能变了。** 清单里把原来的软件名改成绝对路径之后，
   归档名会从 `<软件名>` 变成 `<末级名>_from_<...>`。用重命名工具对齐（**默认试运行**、
   逐份大小校验、重建 manifest，只改名不搬数据）：

   ```powershell
   .\tools\Rename-Archives.ps1            # 先看计划
   .\tools\Rename-Archives.ps1 -Apply     # 确认后执行
   ```

   它会先用当前规则算出目标名，再从"路径命名算法 / 名录里的软件名 / manifest 里记录过的归档名"
   里找磁盘上真实存在的旧文件。
3. **名录里的 `Encrypt` 现在生效。** 如果某个 Slot 写了 `Encrypt = $true`（或清单里写了
   `:encrypt`），但运行时取不到口令，该条目会**明确失败**，绝不会退化成明文归档。
   先准备好 `$env:BAKNRET_PASSWORD` 或用 `-KeyFile` 指定密码文件再跑。
4. **孤儿归档审计**会在每次备份后点名"磁盘上有、但清单里没有任何条目指向"的归档
   （旧名字没迁移、条目被删掉或改名都会这样）。确认新归档校验通过之后再删旧文件。