Shuery
d72fe63c02
README 里 24 处过期入口名（13 处 Backup.ps1、11 处 Restore.ps1）全部更新为新名字 —— 这正是 ADR-0012 里垫片存在的理由：内部实现改名断了会当场报错，而 README 里的入口名过期是**静默没用**，所以垫片留一轮等文档跟上。现在文档跟上了，删垫片的时机也就到了。 README 新增「交互界面（TUI）」一节：怎么进三个编辑器、每个编辑器能改什么（以及为什么有些字段刻意不列 —— 值跨行或本身是集合时"改一行"没有明确含义）、-Quiet 与 -InputScript 的用途、以及"只有真终端才画界面，否则明确报错并给退出码 2"。入口表从"两个入口"扩成四个（主入口 / 动作 / 配置 / 垫片）。 CHANGELOG 增加「新增：交互界面与入口重组」一节，含三项编辑器共用的外科式改写保证与那条往返断言；并写明旧命令照旧可用。 CONTEXT.md 增加「模块与入口」一节：BakNRet/ 四层的分工与规矩（清单是显式白名单、加载器是唯一点源顺序声明处、Public 一个函数一个文件、Private 放内部实现与 State），以及四个入口脚本的职责与"编排尚未下沉"这个已知的下一步。 验收：test.ps1 9/9 全绿（5.1 与 7）。
4.4 KiB
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 备份工具
模块与入口
BakNRet/ 是 PowerShell 模块：既能被 Import-Module 直接用，也是四个入口脚本背后的实现层。
| 位置 | 是什么 | 规矩 |
|---|---|---|
BakNRet/BakNRet.psd1 |
模块清单 | FunctionsToExport 是显式白名单：没列进去的不会出现在外面 |
BakNRet/BakNRet.psm1 |
加载器 | 唯一声明点源顺序的地方（Public 再 Private）；别处不许自己点源模块内部文件 |
BakNRet/Public/ |
对外函数 | 一个函数一个文件、文件名 = 函数名；公共函数只放这里 |
BakNRet/Private/ |
内部实现 | 4 个映射/读取辅助函数 + State.ps1（模块状态：编码、日志句柄、运行锁） |
根目录的四个入口脚本 —— Manage-Backup.ps1（主入口，TUI + -Action）、Backup-Data.ps1、
Restore-Data.ps1、Edit-Config.ps1 —— 负责"解析参数 → 干活 → exit 退出码"。
编排逻辑目前仍在 Backup-Data.ps1 / Restore-Data.ps1 里（Invoke-BackupItem 等），把它们下沉进模块是
已被记录、尚未实施的下一步：做完之后一份编排就能同时服务 TUI 与无头两条路，TUI 也不必再起子进程
（见 docs/adr/0012）。层与层的分工见 docs/adr/0001。