# 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`。