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 两版仍绿。
This commit is contained in:
Shuery committed
1 parent
187549e2af
commit
60f2ae3e0f
25 files changed
+1708
No files matched your search
@@ -0,0 +1,34 @@
|
||||
# TUI 用零依赖自研，不引入任何 TUI 库
|
||||
|
||||
三个候选库**全部实测排除**（不是偏好，是硬障碍）：
|
||||
|
||||
- **`Microsoft.PowerShell.ConsoleGuiTools`（`Out-ConsoleGridView`）**：PSGallery 元数据声明
|
||||
`PowerShellVersion = 7.2`，**5.1 装不上**。
|
||||
- **`Spectre.Console` 0.49.1（netstandard2.0）**：能在 5.1 上加载并渲染，但必须往仓库塞
|
||||
**4 个第三方 DLL**（`System.Memory` / `System.Runtime.CompilerServices.Unsafe` /
|
||||
`System.Buffers` / `System.Numerics.Vectors`）——直接违反 README 的"运行备份/恢复不需要任何
|
||||
模块"承诺。而且它**不支持鼠标**。（最新稳定版 0.57.2 还要多两个依赖，所以连版本都得钉在 0.49.1。）
|
||||
- **`Terminal.Gui` 1.15.0（net472）**：反射接线后 `Window` + `Label` + `Button` 在 5.1 与 7 上
|
||||
**真的渲染出来了**，但 `Application.Init()` 在这个版本没有无参重载，`NetMainLoop` 是 `internal`，
|
||||
且 **`Application.Shutdown()` 在两端都抛 `NullReferenceException`** —— 不能用于生产。
|
||||
|
||||
所以自研，只用四样东西：`$Host.UI.RawUI.ReadKey('NoEcho,IncludeKeyDown')`、
|
||||
`[Console]::SetCursorPosition`、`Write-Host -ForegroundColor`、自算的 `Get-CellWidth`。
|
||||
零依赖承诺因此保住；代价是**不支持鼠标、不做复杂控件**。
|
||||
|
||||
## 两条必须记住、都实测过的坑
|
||||
|
||||
**一、无控制台时 `$Host.UI.SupportsVirtualTerminal` 会撒谎。** 它返回 `True`，而同一时刻
|
||||
`GetConsoleMode` 已经因句柄无效而失败；`[Console]::SetCursorPosition` / `WindowWidth` /
|
||||
`KeyAvailable` 全部抛异常；`$Host.UI.RawUI.WindowSize` 不抛错但**静默返回假的 `160x40`**。所以：
|
||||
|
||||
- 唯一可靠的第一道闸门是 **`[Console]::IsOutputRedirected`**，不是那个属性；
|
||||
- **TUI 的异常绝不改退出码** —— 退出码只属于 `$failed` 语义（计划任务靠它判断成败）。
|
||||
|
||||
**二、中文列宽必须自己算。** `.Length` 是 UTF-16 code unit（中文 1 个 char、2 列）；而 5.1 的
|
||||
`$Host.UI.RawUI.LengthInBufferCells('中文')` 返回 **2**（把中文当单列）、对边框字符返回 **6**（把
|
||||
制表符当宽字符）——**5.1 上绝对不能拿它排版**，7 上它是对的，所以这个坑只在一边出现、更危险。
|
||||
自建的 East-Asian-Wide 表必须覆盖全角拉丁、半角片假名（后者是 1 列）、emoji（代理对）。
|
||||
|
||||
另注：VT 在本机**默认已启用**（新 conhost 与 Windows Terminal 的 `STDOUT mode` 都是 `0x7`），
|
||||
所以彩色与光标定位不需要 `SetConsoleMode`；但代码里保留"无 VT 时退化"的分支以防老环境。
|
||||
@@ -0,0 +1,15 @@
|
||||
# 进度用"注入的钩子"，这是对"模块不持有运行状态"的一次有意例外
|
||||
|
||||
TUI 需要知道"正在处理哪个条目、处在哪个阶段"，而目前唯一的通道是日志文本。解析日志行是脆的
|
||||
——这个仓库已经因为"从文本里反推结构"吃过一次亏（方向标记贴在名字上时解析不出来，27/28 个条目
|
||||
被静默跳过）。
|
||||
|
||||
所以核心在几个确定的点上调用一个**可注入的进度回调**（建暂存 / 压缩 / 校验 / 安全描述符）；
|
||||
无头路径下它是 `$null`，行为与今天**完全一致**。
|
||||
|
||||
**为什么这不是"又把全局可变状态请回来"**：它是一个注入点，不是一份状态——除了运行期被调用之外
|
||||
不被读、不被写、不跨条目累积，也不参与任何判断。ADR-0007（运行锁用文件句柄而非模块级变量）的
|
||||
同一条原则仍然成立：**状态属于调用方，模块只提供能力**。
|
||||
|
||||
代价：这些回调点会成为核心里的"缝"。以后新增或改动回调点时，要同时想清楚它对**两个前端**
|
||||
（TUI 与无头）分别意味着什么——尤其是"跳过"这种既不是成功也不是失败的状态，两个前端都得有说法。
|
||||
@@ -0,0 +1,30 @@
|
||||
# 入口改名：新名字 + 只留一轮的薄垫片
|
||||
|
||||
入口从一个（按方向各一个脚本）变成四个：
|
||||
|
||||
| 名字 | 角色 |
|
||||
| --- | --- |
|
||||
| `Manage-Backup.ps1` | **主入口**：TUI；同一个文件的无头模式（`-Action Backup -Quiet`）供计划任务调用 |
|
||||
| `Backup-Data.ps1` | 备份动作（无头） |
|
||||
| `Restore-Data.ps1` | 恢复动作（无头） |
|
||||
| `Edit-Config.ps1` | 配置管理（TUI 三个界面） |
|
||||
|
||||
旧的 `Backup.ps1` / `Restore.ps1` 留**薄垫片**（转发 + 打印一句改名提示），**只留一轮**，下一轮删。
|
||||
|
||||
## 为什么这次留垫片，而 ADR-0001 里 `Common.psm1` 是直接删
|
||||
|
||||
因为两者的性质不同：`Common.psm1` 是**内部实现**（只有仓库内引用，全仓 grep 就能改完），而入口
|
||||
脚本是**外部接口**——README 里 25 处、使用者的肌肉记忆、以及 `tools/Register-BackupTask.ps1` 里
|
||||
硬编码的 `-File <仓库>\Backup.ps1`。内部实现断了当场报错，外部接口断了是**静默没用**。
|
||||
|
||||
## 一处实测纠正
|
||||
|
||||
写这条决策时我原以为"有个正在跑的计划任务依赖旧路径"。实测：**本机没有注册任何 BakNRet 计划
|
||||
任务**（枚举 200 个任务，按任务名与 Action 两个维度过滤，0 条命中）。所以那个风险**现在不存在**，
|
||||
垫片的理由只剩"使用者的肌肉记忆 + 文档引用"。改名时必须**同步改 `Register-BackupTask.ps1`**，
|
||||
否则将来注册出来的任务会指向一个垫片。
|
||||
|
||||
## 命名上的一处偏离
|
||||
|
||||
用户最初提的是 `Handle-Config`。`Handle` **不在** PowerShell 官方 approved verbs 里，而本仓库的
|
||||
静态分析门禁里 `PSUseApprovedVerbs` 是恒开的（当前 0 告警），所以改用 **`Edit-Config`**。
|
||||
@@ -0,0 +1,32 @@
|
||||
# TUI 写配置：外科式改写，校验通过才原子替换
|
||||
|
||||
三个配置文件都含**无法往返**的内容：
|
||||
|
||||
- `SoftwareCatalog.psd1` 里有 `$(if ($env:SCOOP_GLOBAL) { ... } else { ... })\persist` 这类动态
|
||||
表达式、`$(scoop prefix translucenttb)\settings.json`，以及**跨行字符串拼接**的 `Exclude`。
|
||||
`Import-PowerShellDataFile` **实测读不了这个文件**（报 "cannot generate a PowerShell object
|
||||
for a ScriptBlock evaluating dynamic expressions"）。
|
||||
- `BackupList.txt` 与 `BackupConfig.psd1` 里的注释**本身就是文档**（记录每个开关的取舍）。
|
||||
|
||||
所以任何"解析成对象 → 改 → 重新序列化"的方案都会把它们毁掉。做法：
|
||||
|
||||
1. **只改写被编辑的那一行/那一块**，其余逐字节保持；
|
||||
2. 写临时文件 → 用模块自己的读取器解析 + 语义校验（清单逐行 `ConvertFrom-BackupListLine`、
|
||||
配置的类型与取值、名录的展开与 `Test-Path`）；
|
||||
3. **只有全过才调用已有的 `Write-BaknretAtomicText` 替换**；不过就**拒绝保存**并把原文错误打出来。
|
||||
|
||||
这条让 TUI 编辑器从"方便"升级为"**比手改更安全**"——手改没有校验，而它有。
|
||||
|
||||
## 可编辑面按"能不能安全往返"来定
|
||||
|
||||
| 文件 | 模型 | 可编辑 |
|
||||
| --- | --- | --- |
|
||||
| `BackupList.txt` | 行编辑器（复用已有 token 解析器） | 方向 / 目标 / 覆盖 / 排除 / 追加 / 加密 / 键值 / 说明 |
|
||||
| `BackupConfig.psd1` | 扁平表单 | 目录、阈值、开关及其合法取值 |
|
||||
| `SoftwareCatalog.psd1` | 树 + 只读字段 | **只有 `Encrypt` 与 `Description`**；`Path`/`Exclude`/`Include` 显示为只读并提示用文本编辑器 |
|
||||
|
||||
## 两条配套约定
|
||||
|
||||
- 每次保存前把原文件按时间戳复制到 `logs/config-backups/`（已 gitignore，不污染仓库）。
|
||||
- 每个编辑器带一条**往返断言**：解析 → 改一个字段 → 写回 → 重新解析，**除目标字段外逐字段相等，
|
||||
且注释行数不变**。没有这条断言，TUI 编辑器就是"看起来能保存"的典型。
|
||||
Reference in new issue
Block a user