 Shuery
|
60f2ae3e0f
|
docs: TUI 与入口重组的设计记录（4 条 ADR + 验收锚点）
grilling 三轮把设计树走完了，这里把它落成文件，避免决策只活在对话里。
ADR-0010 零依赖自研 TUI：三个候选库全部实测排除 —— ConsoleGuiTools 的 PSGallery 元数据声明最低 7.2（5.1 装不上）；Spectre.Console 0.49.1 能在 5.1 加载但要塞 4 个第三方 DLL 且不支持鼠标；Terminal.Gui 1.15.0 能反射接线到真的渲染出窗口，但 Application.Shutdown() 在两端都抛 NRE。同时记下两条实测坑：无控制台时 $Host.UI.SupportsVirtualTerminal 会撒谎返回 True（第一道闸门必须是 [Console]::IsOutputRedirected），以及 5.1 的 RawUI.LengthInBufferCells 对中文返回 2、对边框字符返回 6（都不能用来排版）。
ADR-0011 进度回调这个例外：它是注入点不是状态，无头路径为 $null 时行为与今天完全一致。
ADR-0012 入口改名与垫片：这次留垫片而 Common.psm1 直接删，是因为前者是外部接口（断了是静默没用）后者是内部实现（断了当场报错）。并纠正了自己的一个伪前提 —— 本机实测没有注册任何 BakNRet 计划任务。
ADR-0013 TUI 写配置：外科式改写 + 校验通过才原子替换。硬事实是 SoftwareCatalog.psd1 根本不能被 Import-PowerShellDataFile 读入（动态表达式），任何"解析成对象再序列化"的方案都会毁掉表达式与注释。
.scratch/tui/spec.md 是这次改造的验收锚点：9 条已定决策 + 三轮的判据 + 风险表。
验收：Parse 两版仍绿。
|
2026-09-27 15:27:01 +08:00 |
|
|
Shuery
|
2446c7c5c7
|
docs: 把"前缀补全只搜一层、且不提供深度开关"写成决策记录
深度递归不是"补上一个没实现的功能"，而是引入一个具体的错。写成 ADR-0009 连同实测数据：26 条真实 Path 里 19 条直接命中、3 条补全救不了（软件没装）、1 条（%UserProfile%\fnm）在 5 层内会命中 AppData\Local\fnm_multishells 这个临时目录 —— 静默备份错的东西还报成功。
同时在 Find-BakNRetChildDirectoryByName 的注释里指回 ADR，免得下一个人把它当"漏了的功能"补回去。
顺带修掉 README 里一句与实现不符的话：原先写"前缀补全命中多个候选（同名目录分散在多处）"，而只搜一层时多个候选只可能来自同一个父目录（既有 X 又有 X_后缀）。
全仓复查：MaxDepth / CatalogMaxDepth / 最大深度 / 向下找几层 除 ADR-0009 的历史叙述外 0 处。
验收：test.ps1 9/9 全绿（7 与 5.1）。
|
2026-09-27 11:34:34 +08:00 |
|
|
Shuery
|
3a3a57a6a1
|
docs: 决策记录 8 条、变更日志、README 的验收与口令两节
0007 与 0008 是本次改造新产生的决策（原计划 6 条）。它们同样满足「后人会问为什么」：把运行锁改成互斥体、或给库里 27 个函数补上 SupportsShouldProcess，都是看起来更规范的错法。
CHANGELOG.md：把 README 里那 33 行「相对旧版修了什么」整节搬过去，并补上本次改造的记录（11 条修复 + 6 条结构与规范，每条修复都写明现象与现状）。README 那一节换成指针。
README 新增两节：「验收与静态分析」（六个层次、Run-RealSmoke 为什么独立存在、以及那 6 条格式规则默认 Disabled 这个容易漏掉的事实）；「口令放在哪里」（默认留空不是遗漏，附迁移与验证命令）。
.markdownlint.json 照 PowerShell 主仓库的实践（default true、行长 240），只把 MD024 从关闭改成「仅同级不重复」，因为变更日志需要重复标题。顺带按 .editorconfig 把 .md 的 BOM 去掉。
|
2026-09-27 10:01:54 +08:00 |
|