Shuery
42f02d0eca
16 个没有前缀的公共函数补上 BakNRet（Write-Log → Write-BakNRetLog、Resolve-BackupEntry → Resolve-BakNRetBackupEntry、Find-ChildDirectoryByName → Find-BakNRetChildDirectoryByName 等）， 另外把全仓的 Baknret 统一成 BakNRet（47 个文件、940 处、65 个定义文件重命名）。 这不是审美问题：静态分析直接拓出一条实据 —— Write-Log 与本机某个已装模块导出的命令 **重名**（PSAvoidOverwritingBuiltInCmdlets），而重名的后果是导入两个模块时有一方的命令被 静默遮蔽。补前缀正是这条规则的解法，改名后它归零。 为什么敢做这个规模：PowerShell 的函数名解析大小写不敏感，所以 Baknret → BakNRet 在功能 上是零风险；真正要验证的是 16 个补前缀的调用点，而 276 个断言几乎覆盖了每个函数。另外 "名字与文件名一致"这条不变式有断言盯着（加载器点源的文件集合 vs 磁盘）。 踩到并记下的坑：Windows 文件系统大小写不敏感，所以**只改大小写**的重命名会被 Move-Item 当成同一个文件而静默跳过 —— 同一批里同时改了名字的那 16 个文件却成功了，于是"看起来能跑"。 最后用"先移到临时名、再移到目标名"的两步走解决，判断与替换全部改用显式大小写敏感的形式 （-creplace / -cmatch）。 顺带把名录指纹缓存从 MD5 换成 SHA256（PSAvoidUsingBrokenHashAlgorithms）：它只是缓存键， 没有兼容负担。 验收：test.ps1 9/9 全绿（7 与 5.1）、100 个文件两版解析零错、276 个断言全过、 构建工具仍能合回单文件（3300 行）。
74 lines
3.1 KiB
Markdown
74 lines
3.1 KiB
Markdown
# BakNRet
|
||
|
||
一个 Windows 备份 / 恢复工具：把机器上指定的软件与目录收进归档，并能把它们放回原位。本文件是本项目的术语表——「要处理什么」「东西放在哪」这些概念在本仓库里只有一个叫法，写作与命名都照这里的词来。
|
||
|
||
## 语言
|
||
|
||
### 输入
|
||
|
||
**清单**：
|
||
备份与恢复共用的唯一声明：本次要处理哪些东西。一行一个条目。
|
||
_Avoid_: 列表、任务列表、backup list、配置
|
||
|
||
**条目**：
|
||
清单里的一行所代表的一次处理单元——一个软件名，或一个手写路径。
|
||
_Avoid_: 项、记录、任务、job
|
||
|
||
**方向**：
|
||
条目在本次运行里参不参与：仅备份、仅恢复、还是两者都做。
|
||
_Avoid_: 模式、标志、flag
|
||
|
||
**软件名录**：
|
||
「软件名 → Slot 组」的映射表。清单里写软件名时，靠它换成宿主机上的真实路径。
|
||
_Avoid_: 软件目录、路径表、catalog 配置
|
||
|
||
**Slot**：
|
||
名录里给一个软件定义的一个具名位置，决定这块内容在归档内的那一层目录名。一个软件可以有多个 Slot。
|
||
_Avoid_: 层、分组、子目录、条目
|
||
|
||
**覆盖**：
|
||
清单行里对名录默认值（路径 / 排除 / 追加 / 加密）的一次性改写。覆盖是**替换**，不是叠加。
|
||
_Avoid_: 补丁、自定义、patch
|
||
|
||
**排除模式**：
|
||
匹配**归档内相对路径**的通配表达式，用来把可再生内容挡在归档之外。`!` 打头表示任意层级匹配。
|
||
_Avoid_: 过滤规则、正则、ignore
|
||
|
||
**前缀补全**：
|
||
名录里的路径带版本后缀时的匹配规则（写的 `legendary` 对实际的 `legendary_2.0.4`）。只认 `<名>_*` 与 `<名>-*`；补全出多个候选时必须报错，不许任选一个。
|
||
_Avoid_: 模糊匹配、自动补全、glob
|
||
|
||
### 归档布局
|
||
|
||
**归档**：
|
||
一份按 Slot / 归档项布局写出的 7z 文件。软件名条目的归档名就是软件名。
|
||
_Avoid_: 包、压缩包、备份文件、zip
|
||
|
||
**归档项**：
|
||
归档内的一个顶层条目——一个 Slot 或一个追加项，各自对应宿主机上的一个路径。恢复时每一项只解出自己那棵子树。
|
||
_Avoid_: 目录项、子项、包内条目、root
|
||
|
||
**旧布局**：
|
||
重构前的归档形态：归档内顶层直接是源目录名，没有 Slot 这一层。恢复端必须仍然认得它。
|
||
_Avoid_: 老格式、v1、legacy 格式
|
||
|
||
### 产物与审计
|
||
|
||
**manifest**：
|
||
归档旁边的登记簿 `manifest.json`：每份归档的来源、状态与历史。恢复端优先靠它定位归档。
|
||
_Avoid_: 索引、记录文件、数据库
|
||
|
||
**安全描述符旁挂**：
|
||
与归档同名、放在归档旁边的安全描述符文件（属主 / 属组 / DACL）。归档格式装不下它，所以它必须跟着归档一起搬。
|
||
_Avoid_: acl 文件、附加文件、附件
|
||
|
||
**孤儿归档**：
|
||
磁盘上存在、但没有任何清单条目指向的归档。它恢复不到，所以别当垃圾删。
|
||
_Avoid_: 无用归档、残留、垃圾文件
|
||
|
||
### 名字
|
||
|
||
**BakNRet**：
|
||
本工具的名称，任何场合（文档、文件名、标识符）都一律写作 `BakNRet`。
|
||
_Avoid_: BakNRet、baknret、BakRet、BaknRet 备份工具
|