BakNRet

58 Commits 1 Branch 0 Tags

2 Commits

Include renames

Author	SHA1	Message	Date
Shuery	7149ea691e	fix(backup,restore): 显式指定的清单不存在时报失败，不再静默成功传 -BackupListPath 指向一个不存在的文件时，原实现把它当成"首次运行"处理：备份端会在那个位置凭空建一份模板，恢复端则"从备份内容生成清单"，然后两者都 exit 0。后果在计划任务里最明显：任务计划程序读到的是"上次运行结果 = 成功"，而实际上一个条目都没处理。这与本仓库已经修过的"27 条被静默跳过、退出码仍是 0"是同一类缺陷 —— 退出码是自动化唯一能读到的信号，它必须对得上"到底干了什么"。现在按 $PSBoundParameters.ContainsKey('BackupListPath') 把两条语义分开： * 显式指定了清单却不存在 -> 报 ERROR 并 exit 1。路径写错、或相对路径按了别的工作目录解析（计划任务的工作目录通常是 C:\Windows\System32），都是调用方的错误，不能伪装成"已经帮你建好模板了"。 * 没指定（首次运行引导）-> 保持原行为：备份端建模板、恢复端从 manifest 生成清单，仍然 exit 0。这是"开箱即用"，不是失败。顺带补 2 处运算符前的空格（Backup.ps1 / Restore.ps1 的 PSUseConsistentWhitespace）。测试： * 2 条成对回归用例（显式缺失报失败 / 首次运行仍建模板）。必须成对 —— 只测一条的话， "把所有缺失都改成 exit 1"这种错误实现也能骗过测试。 * 7 条断言覆盖归档原子替换与路径解析基准。其中 3 条用 AST 判定，因为文本匹配会被函数自己的注释绊倒（注释里正当地提到了 $PSScriptRoot，解释为什么不许用）。验收：test.ps1 9/9 全绿（5.1 与 7）；Pester 183 -> 192，0 失败；静态分析 80 条、 0 Error（与改造前持平）。	2026-10-02 01:16:25 +08:00
Shuery	4e3c0461c0	refactor: 入口改名（Backup/Restore -> Backup-Data/Restore-Data）+ 只留一轮的垫片 git mv 保留历史。旧名字留薄垫片：入口脚本是外部接口（README 二十多处引用、使用者的肌肉记忆、注册脚本里的路径），内部实现改名断了会当场报错，外部接口改名断了是静默没用 —— 后者对备份工具尤其不能接受（ADR-0012）。垫片踩到四个坑，全部由门禁报出（E2E 与 Pester 集成用例本来就是通过子进程调这两个入口的，于是它们原封不动成了垫片的验收）：① `& script.ps1` 里子脚本的 exit 不会把退出码传到父脚本的 $LASTEXITCODE —— 会把失败变成成功，而计划任务靠退出码判断成败；② 调用方传 -Verbose 时垫片里的 Import-Module 会多打一行加载信息，顶掉测试的输出断言；③ 不重定向时子进程的输出到不了调用方（父进程的 stdout 常常是管道，而 .NET 起的进程默认只继承控制台）—— 改成显式重定向 + 异步读转发（同步先读 stdout 再读 stderr 会在管道写满时死锁）；④ `[CmdletBinding()]` 会把 -Verbose 当通用参数绑走，它不会落进 $Rest，于是没被转发给子进程 —— 而测试正是靠 -Verbose 拿那条 VERBOSE 级日志的。现在显式把 -Verbose / -Debug 加进转发参数。参数引号化用模块自己的 ConvertTo-BakNRetNativeArgumentString（5.1 上 ProcessStartInfo.ArgumentList 不存在）。tools\Register-BackupTask.ps1 已同步改指 Backup-Data.ps1（4 处）。门禁新增一条机械检查：源码里不得出现"左边空的赋值" —— 它是"用双引号拼代码导致 $变量被插值成空"那个坑的指纹（合法语法、Parse 层抓不到、只有跑到才炸，同一块代码里出现过五次）。垫片全部用单引号 here-string 生成，零插值。验收：test.ps1 9/9 全绿（5.1 与 7）；真实清单只读冒烟 4/4。	2026-09-27 19:51:24 +08:00

Author

SHA1

Message

Date

Shuery

7149ea691e

fix(backup,restore): 显式指定的清单不存在时报失败，不再静默成功

传 -BackupListPath 指向一个不存在的文件时，原实现把它当成"首次运行"处理：备份端会在
那个位置凭空建一份模板，恢复端则"从备份内容生成清单"，然后两者都 exit 0。

后果在计划任务里最明显：任务计划程序读到的是"上次运行结果 = 成功"，而实际上一个条目
都没处理。这与本仓库已经修过的"27 条被静默跳过、退出码仍是 0"是同一类缺陷 —— 退出码
是自动化唯一能读到的信号，它必须对得上"到底干了什么"。

现在按 $PSBoundParameters.ContainsKey('BackupListPath') 把两条语义分开：

  * 显式指定了清单却不存在 -> 报 ERROR 并 exit 1。路径写错、或相对路径按了别的工作
    目录解析（计划任务的工作目录通常是 C:\Windows\System32），都是调用方的错误，
    不能伪装成"已经帮你建好模板了"。
  * 没指定（首次运行引导）-> 保持原行为：备份端建模板、恢复端从 manifest 生成清单，
    仍然 exit 0。这是"开箱即用"，不是失败。

顺带补 2 处运算符前的空格（Backup.ps1 / Restore.ps1 的 PSUseConsistentWhitespace）。

测试：
  * 2 条成对回归用例（显式缺失报失败 / 首次运行仍建模板）。必须成对 —— 只测一条的话，
    "把所有缺失都改成 exit 1"这种错误实现也能骗过测试。
  * 7 条断言覆盖归档原子替换与路径解析基准。其中 3 条用 AST 判定，因为文本匹配会被
    函数自己的注释绊倒（注释里正当地提到了 $PSScriptRoot，解释为什么不许用）。

验收：test.ps1 9/9 全绿（5.1 与 7）；Pester 183 -> 192，0 失败；静态分析 80 条、
0 Error（与改造前持平）。

2026-10-02 01:16:25 +08:00

Shuery

4e3c0461c0

refactor: 入口改名（Backup/Restore -> Backup-Data/Restore-Data）+ 只留一轮的垫片

git mv 保留历史。旧名字留薄垫片：入口脚本是**外部接口**（README 二十多处引用、使用者的肌肉记忆、注册脚本里的路径），内部实现改名断了会当场报错，外部接口改名断了是静默没用 —— 后者对备份工具尤其不能接受（ADR-0012）。

垫片踩到四个坑，全部由门禁报出（E2E 与 Pester 集成用例本来就是通过子进程调这两个入口的，于是它们原封不动成了垫片的验收）：① `& script.ps1` 里子脚本的 exit 不会把退出码传到父脚本的 $LASTEXITCODE —— 会把失败变成成功，而计划任务靠退出码判断成败；② 调用方传 -Verbose 时垫片里的 Import-Module 会多打一行加载信息，顶掉测试的输出断言；③ 不重定向时子进程的输出到不了调用方（父进程的 stdout 常常是管道，而 .NET 起的进程默认只继承控制台）—— 改成显式重定向 + 异步读转发（同步先读 stdout 再读 stderr 会在管道写满时死锁）；④ **`[CmdletBinding()]` 会把 -Verbose 当通用参数绑走，它不会落进 $Rest，于是没被转发给子进程** —— 而测试正是靠 -Verbose 拿那条 VERBOSE 级日志的。现在显式把 -Verbose / -Debug 加进转发参数。

参数引号化用模块自己的 ConvertTo-BakNRetNativeArgumentString（5.1 上 ProcessStartInfo.ArgumentList 不存在）。tools\Register-BackupTask.ps1 已同步改指 Backup-Data.ps1（4 处）。

门禁新增一条机械检查：**源码里不得出现"左边空的赋值"** —— 它是"用双引号拼代码导致 $变量 被插值成空"那个坑的指纹（合法语法、Parse 层抓不到、只有跑到才炸，同一块代码里出现过五次）。垫片全部用单引号 here-string 生成，零插值。

验收：test.ps1 9/9 全绿（5.1 与 7）；真实清单只读冒烟 4/4。

2026-09-27 19:51:24 +08:00