 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 |
|
|
Shuery
|
187d2759fd
|
style: 按微软规范落地静态分析，并全仓机械重排
三件事：
1) tools\Install-TestDependencies.ps1 现在也把 PSScriptAnalyzer 装进仓库内的 .tools\modules
（不动机器上的全局模块，与 Pester 同一策略）。
2) PSScriptAnalyzerSettings.psd1：这是必要的，不是装饰 —— 那 6 条格式规则
（括号、缩进、空格、对齐、大小写）默认全是 Disabled，所以不带 -Settings 的
`Invoke-ScriptAnalyzer -Severity Warning,Error` 会**静默漏掉全部排版问题**。本文件用 Rules
把它们打开（而不是用 IncludeRules 换一套），于是默认规则与格式规则同时生效。
三条有意的排除都写明了理由：PSAvoidUsingWriteHost（彩色控制台输出是这份工具的刻意设计）、
PSUseShouldProcessForStateChangingFunctions（WhatIf 的边界在入口脚本，给库里 27 个改状态的
函数都加上反而会"静默跳过"，备份看着成功却什么都没做）、PSAvoidUsingPlainTextForPassword
（7z 只接受命令行口令，这是 7z 的限制，README 里写明了取舍）。
3) tools\Invoke-Analyzer.ps1：独立门禁（不塞进 Pester 用例 —— 套件跑一次二十多秒，
混进去会让"测试红了"这句话失去分辨力），路径过滤与验收门槛的 Encode/Parse 两层一致。
全仓重排结果：706 条告警 -> 67 条。修掉的 639 条全部是格式（闭括号 168、空格 80、
对齐 68、缩进 60、行长 229）。重排后 9/9 验收全绿、100 个文件两版解析零错、
276 个断言原样通过 —— 机械重排没有改变任何可观察行为。
如实说明两件事：
* 行长上限设成 160，**不是**官方默认的 120。120 在本仓库意味着 270 处改动（主要是
中文注释与测试夹具里的一行式目录），160 意味着 41 处。160 仍是"宽但可读"，而理由是写在
配置文件里的：这不是悄悄放宽，想收紧到 120 时那份清单就在分析器输出里。
* 剩余 67 条里，41 条是上面那批行长，其余 26 条是分析器找出的真问题（未使用参数 6、
空 catch 6、MD5 指纹 1、覆盖内置命令 1、switch 默认值 1 等）。其中
Find-ChildDirectoryByName 的 MaxDepth 参数从未被使用 —— 也就是配置里的
CatalogMaxDepth = 5 是假的，前缀补全实际只查 1 层。这条要改行为、且影响真实名录的解析
结果，留给你拍板，不在本提交里动手。
|
2026-09-27 09:46:08 +08:00 |
|
|
Shuery
|
2d26f78d15
|
fix: 源文件改存 UTF-8 with BOM，让 Windows PowerShell 5.1 真正可用
改造前：全仓 6/6 个源文件在 5.1 上解析失败（README 却承诺支持 5.1）。原因是文件是无 BOM 的
UTF-8，而 5.1 没有 BOM 就按 ANSI 代码页解码源码，中文变乱码、全角问号吃掉引号，整块语法塌掉。
现在 28/28 个文件在 5.1 与 7 上都解析零错误，E2E 36 项在 5.1 上全绿。
顺带修掉一个被 5.1 掩盖的缺陷：带 [CmdletBinding()] 的脚本在 5.1 上，param() 默认值里
拿不到 $PSScriptRoot（实测为空串，7 上正常）。于是 Backup.ps1 / Restore.ps1 在 5.1 上不传
路径参数就报错退出 —— 而计划任务恰恰不传。E2E 之所以看不见，是因为它总是显式传路径。
8 处默认值全部移到 param() 之后的解析段，沿用本仓库对 -BackupDir 一直在用的写法。
新增三条可重放的约定，让编码不再是一次性动作：
.gitattributes 接管行尾（本机 core.autocrlf=true，会把工作区改成 CRLF 制造伪 diff）
.editorconfig 用 charset = utf-8-bom 锁住 BOM
tools\Set-SourceEncoding.ps1 是规范化脚本，tools\Invoke-* 之外的任何改动之后都能重放
test.ps1 是唯一验收入口：Encode + Parse + Unit + Smoke + E2E，在 7 与 5.1 上各跑一遍
test.ps1 的 Encode 层直接检查"必须有 BOM"这条规则。加它的原因很实际：实测本仓库用的
编辑工具在保存时会悄悄去掉 BOM，而丢了 BOM 的文件只在 5.1 上出错、在 7 上完全正常，
没有这条检查就会一直漏过去。
已知未修（下一步处理）：5.1 上 Unit 有 6 项、Smoke 有 1 项失败，全部源于测试夹具写
临时文件时没指定编码（5.1 的 Set-Content 默认 ANSI），与产品代码无关。
|
2026-09-26 22:05:42 +08:00 |
|
|
Shuery
|
dbc0c00554
|
重构为可核对、可恢复的备份工具（P0-P3）
修复（P0）
- 退出码：改用 .NET Process 继承控制台启动外部命令。Start-Process -PassThru 的
ExitCode 在 PowerShell 7.7.0-preview.4 上恒为 $null，会把成功的压缩判成失败，
并让 "exit 2 -> 删档重试" 的自愈分支永远不可达。
- BackupList.txt 解析：先按第一个 :: 切开再处理引号，修正整行被引号包住时
排除表被吞进路径的问题（该条目此前被静默跳过，其 2.8 GB 归档成了孤儿）。
- 排除分隔符同时接受 , 与 ;：此前解析器只认 ; 而清单里写的是 ,，
等于所有排除规则都没生效。
- 7z 排除参数不再嵌引号，含空格的模式自动转成 ?：旧写法 -x!"路径" 会让引号
成为模式的一部分，导致排除对所有条目都失效。
加固（P1）
- 先写临时归档 -> 7z t 校验 -> 原子替换，中断不再污染正式归档。
- 放弃 7z 的更新模式 u：固实压缩下收益极小，却让排除规则改动与已删文件
永远进不了归档。
- 新增 Backups/manifest.json 与 logs/*.log，跳过/失败有据可查。
- 结尾按失败数 exit；恢复支持 -WhatIf / -DryRun / -VerifyOnly / -Only。
- 恢复优先用 manifest 定位归档，并精确比较 BaseName（不再用 -Filter 通配）。
- 修正 tar 分支用 $LASTEXITCODE 判断成功与否的缺陷。
- 有警告（文件被占用）时拒绝用不完整的归档覆盖完整归档，需显式 -AcceptWarnings。
策略与安全（P2）
- Edge 条目加排除规则：解压后 4.22 GB 中 3.79 GB 是可再生的缓存/遥测/扩展本体，
保留书签、密码、偏好、历史与站点数据。
- 可选 7z 加密（@encrypt 标记或全局开关），取不到口令时明确失败，绝不写明文。
- 磁盘空间守卫：放不下就跳过该条目，低于阈值告警。
工程化（P3）
- 新增 BackupConfig.psd1、README.md、.gitignore。
- tests/Run-Tests.ps1（32 项）与 tests/Run-E2E.ps1（16 项端到端验收）。
- tools/Register-BackupTask.ps1 注册每日计划任务。
- 归档命名算法保持不变，已有归档不会失联。
|
2026-09-21 20:10:18 +08:00 |
|