# `docs/DEBTS.json` 审读（2026-09-26）

审读对象：`docs/DEBTS.json`（25 条、余额 27）。
方法：读文件 + 读**它的三个消费方**（Go 判据 / electron RESULT 行 / `debt-visibility`），
再用仓库现状**反查每条的 `due`/`where` 是否仍与事实一致**。凡是我能实测的都实测了。

结论先说：**结构是好的，两条被机器钉住的条目也是准的**；
但**「已结算」这件事没有任何判据在管** —— 于是「结算了却看起来没结算」就成了一种静默状态，
而且我实测**已经发生过一次**，且它把一个**真·未验的欠账**藏进了不可见的桶里。

---

## 一、总体健康度（这些是好的，先说清楚）

| 项 | 实测 | 判断 |
|---|---|---|
| JSON 合法、`debts` 25 条 | ✓ | 好 |
| 每条 `id/count/due/where` 齐全 | ✓ 0 条缺失 | 好 |
| `static-criteria` 登记 vs `STATIC_ONLY.length` | 5 vs **5** | 好（`commit-hygiene` 钉住） |
| `mails-status-derived` 登记 vs 实测 | 1 vs 1 | 好（`TestDebtLedgerMatchesMeasurement` 钉住） |
| 头部"两端都读同一个文件" | 属实 | 好 |
| 余额打印来自权威源（无手写副本） | 属实 | 好（`TestDebtSummaryReadsAuthoritativeLedger` 钉住） |

★ 特别值得一提：`debt_registry_test.go` 里那段"**该断言的是形状，不是点名**"（删掉硬编码三笔清单）
和 `run-all.mjs` 里"子集关系必须打进字符串本身" —— 这两条**是这份文件里最有价值的资产**：
它们挡的正是"余额看起来对、其实没人判"这一族。下面的问题**不是**它们失职，
而是**它们覆盖的相位之外还有一片空地**。

---

## 二、★ 主要问题：**「已结算」无判据 ⇒ 结算后的条目会"看起来没结算"**

### 2.1 机制

```
余额打印只收 count>0（debtSummary / run-all.mjs 的 reduce，两处一致）
⇒ 一旦把某条 count 置 0，它就从**默认可见的余额**里消失
⇒ 而 due / where 是**自由文本**，没有任何判据校验它们与 note 里"已结算"是否一致
   （实测: 读 `note` 的判据 **0 处** —— `run-all.mjs` 里那个 `.note` 属于变异体 `DIAG` 表，
    与 DEBTS 条目无关；due/where 则只被断言"非空"）
⇒ 结果: 「已结算」只写在 note 深处，而 due/where 可以永远停在结算前 —— 全绿
```

### 2.2 我实测到的**真实案例**（不是假想）

`harmony-maildetail-missing-three`：

```
count = 0                        ← 不计入余额 ⇒ 默认路径上看不见
due   = 「鸿蒙详情页对齐 WebUI 时（三块功能，服务端都已支持）」   ← 读起来是**未完成**
where = 「MailDetailPage.ets（对照 MailView.tsx）」              ← 读起来是**缺口**
note 末段 = 「2026-09-19 结算：三块**都做完了**」                ← 事实是**已完成**
```

我反查了代码，`note` 是对的、`due`/`where` 是**过期**的：

```
client/harmony/.../MailDetailPage.ets  里三块都在: Forward ×19 / rename ×22 / Budget ×17（max_rounds ×5）
```

⇒ ★ 这条**已还清**，但它**三条字段全都停在结算前**，且因 `count=0` 而不可见。
下一个人来审计，看到的是"鸿蒙详情页缺三块功能"这个**已经不存在的欠账**。

### 2.3 ★★ 而它顺带藏起了一个**真的**未验项

同一条的 note 末尾有一句**实质未验**：

> ★ 未验：预算条的**点击**在设备上没走通 —— 模拟器顶部 155px 是系统手势区，
> 而折叠头部恰在其中（坐标式点击会被系统抢走）。数据链路已实测，观感没验。

我实测：这句话**只存在于这个 `count=0` 的 note 里**，
`MailDetailPage.ets` 里搜不到（grep `155px`/`系统手势区` = 0）。
而本仓对"设备未验"的**既有惯例是单独立条、`count=1`**：

```
harmony-morph-unverified-middleframes          count=1
harmony-account-errors-banner-unverified       count=1
harmony-permission-history-render-unverified   count=1
```

⇒ ★ 于是这里出现了**双重的不可见**：
① 它被写在一个 `count=0` 的条目的 note 里（不进余额）；
② 它**没有**按同一族的惯例**单独立条**。
⇒ 按本文件自己的判据（"**欠账不显形，就等于没有**"），这条**等于不存在**。

### 2.4 为什么现有判据抓不到（这不是它们写错了）

```
· debt_registry_test.go  : 只断言 due/where **非空** + 两笔存在 + 与**实测**一致
                           ⇒ "结算后字段该更新"不在这三条里
· commit-hygiene         : 只钉 static-criteria（那笔有权威实测源）
· debt-visibility        : 形状是"**判据目录里**声明未覆盖/未验 ⇒ 必须登记"
                           ★ 它**确实**读了 DEBTS.json，但只取 `d.where` 做"这一笔是否被引用"的比对，
                             **从不读 `d.note`**（实测: 该文件里 `\.note` 命中 0）
                           ⇒ 扫描面 = 判据目录的文件 + 条目的 `where`
                           ⇒ 而这里那句"未验"写在 **`note` 里**，两处都不在 ⇒ **不在它的扫描面**
⇒ 三者的盲区**恰好交汇**在这条上 ⇒ 全绿
```

### 2.5 建议（判据形状，不是改数字）

```
① 结算语义判据（Go 侧，最便宜）:
   若 note 里出现"结算/已还清/都做完了"等词 ⇒ 断言 due 也带已清标记（或断言该条被移出 debts[]）
   反向: 若 due 带已清标记 ⇒ 断言 note 里确有结算条目（防止"标了却没说清是什么")
② note 里的"未验/未覆盖"必须**另有登记**:
   把 debt-visibility 的 MARKERS 扫描面从"判据目录"**扩到 docs/DEBTS.json 的 note**
   （否则 note 就成了新的"注释里写边界"——正是该判据 §16 要挡的那件事）
③ 惯例二选一并写进头部:
   "结算即移除"（头部现在这么写）与"置 count=0 留档"（实际做法，5 条）**两套并存**
   ⇒ 我倾向**保留留档**（有考古价值），但**头部那句话要改**，否则它本身在误导
```

---

## 三、次要问题

### 3.1 `kind` 无判据，且 `run-all.mjs` 拿它当**分类**用

```
16 条 'scope' / 6 条 'env' / 3 条是**整句话**（被当成分类值）:
  deploy-space-prefix-fs              kind = 「判据铺得不满（不是新列）」
  pi-bridge-adopt-cwd-mismatch        kind = 「沙箱 rw 与 worker 实际 cwd 的第三个来源未对齐（同类已修两处，剩接管路径）」
  deploy-interrupt-trap-other-scripts kind = 「只在 redeploy-gateway.sh 做了，另两个部署脚本没做」
```

消费侧 `run-all.mjs:1960` 做的是 `filter(d => d.kind === 'env')` ⇒ 那 3 条**静默落进 other 桶**。
Go 侧 struct **根本不读 `kind`**，所以没有编译期或运行期反馈。
⇒ 不是错误（余额没算丢），但**"分类"这个字段目前是装饰性的**：
读的人会以为 `kind` 是枚举，实际是自由文本。
建议：要么把 `kind` 收成枚举并登记那 3 条，要么承认它是"备注"并**改名**（`kind_note`），
否则下一个写条目的人会照着这 3 条继续写句子。

### 3.2 无"路径腐烂"检查

`where` 里的仓库路径没有任何判据验证仍存在。
我扫了全部 `where`+`due`，**实测只有 1 处疑似**（`platform-mirror-…` 的 `server/main.go`），
复核后**是散文里的裸文件名、不是路径声明**（真路径 `server/cmd/server/main.go`）—— 所以当前没坏。
但这是**运气**：`where` 指的文件被改名/移动时，没有任何东西会红。
建议：`where` 里形如 `client/…|server/…|deploy/…|plugins/…|docs/…` 的 token 断言 `os.Stat` 通过。

### 3.3 `count=0` 条目的"到期前提"措辞不一致

5 条已清条目的 `due` 都带「已…」，但 `harmony-maildetail-missing-three` 不带（见 §2.2）。
这正是 §2.5① 那条判据要抓的形状 —— 单列出来是为了说明**它不是孤例的猜测，是可复现的类别**。

---

## 四、我**没有**发现问题的部分（避免下一个人重复审）

- 两处"同一个事实两份实现"的坑（`var debts` 手写 map、`debtSummary` 不读权威源）**已经修好且判据在位** ——
  且 `debt_registry_test.go` 里那个"锚点会自匹配"的教训（`var " + "debts"`）写得很清楚，值得保留。
- 余额数值本身：25 条 / 余额 27 / env 桶 6 / other 21 —— 我逐条加过，**算术无误**。
- `note` 可选：9 条没有 `note` 字段（都在头部或 `due` 里交代了），**不是缺失**。
- `harmony-permission-history`(0) 与 `...-render-unverified`(1) 看似重复，实为两条不同对象
  （前者=数据源只读 pending，后者=渲染段未验）—— **不是重复登记**。

---

## 五、一句话

**这份文件最擅长的、也已经做到的是"销账"（条目还清 → count 归零）；它最弱的是"销账之后"** ——
`count=0` 让条目离开默认可见的余额，而 `due`/`where` 与 `note` 的一致性、
以及 `note` 里新写下的边界，都**没有判据**。
`harmony-maildetail-missing-three` 同时踩中两处：它**已还清**（却读起来像没还），
并且把一个**真的未验项**（预算条点击）藏进了不可见的 note —— 按本文件自己的话，
**那一条等于没有**。