后端: 销掉一份漂移的欠账副本 + 钉住 user_appearance.user_id 的语义陷阱

## 一、`user_appearance.user_id` 存的是**用户名**（不是 UUID）—— 陷阱显式化

审计时实测到的差异：

| 表 | `user_id` 存的是 |
|---|---|
| `user_keys` | **UUID**（`809967c5-…`） |
| `user_sessions` | **UUID** |
| `user_appearance` | **用户名**（`jianf`）← 与兄弟表不同 |

**功能上自洽**（本包读写都用 username，handler 一律传 `user.Username`），
所以**不是活跃 bug**。但它是个**不报错的陷阱**：按兄弟表的习惯写

    LEFT JOIN user_appearance a ON u.user_id = a.user_id

会**静默匹配到 0 行**。我自己审计时就先踩了一次 —— 查出来全是空，
差点当成"这些账号从没设置过外观"（实际 jianf 有记录）。

**没有改列名**：表里有生产数据（壁纸本体在 blob 里、由 `image_sha256` 引用），
改列要迁移 + 回滚预案，收益只是"名字更好看"。选择**把语义钉住**：
文件头写清（**指名兄弟表**当锚、说清**失败长什么样**）+ 新判据
`appearance_semantics_test.go` 双向校验（repo 层不得混入 UUID 语义、
handler 层不得出现 `user.UserID`）。

★ 判据从源码读而不是运行时测：这里要钉的是**约定**，
而约定的存在形式就是注释与命名 —— 行为测试证明不了"下一个人不会踩"。

## 二、销掉一份**已经漂移**的欠账副本

`debt_registry_test.go` 里有一份**手写副本** `debts` map（给 `debtSummary()`
打印用），而**没有任何判据校验它与权威 `docs/DEBTS.json` 一致**。
实测漂移得很厉害：

- 副本 3 条 vs 权威 **17 条**；
- 里面还留着 **`gesture-semantics`** —— 那一笔已于 2026-09-19 还清并销账；
- `static-criteria` 的余额还是旧值 **7**（权威已是 5）。

后果很具体：**`TestMain` 打印的余额是错的**，而余额的全部意义就是"能看全"。

处理：**删掉副本**，让 `debtSummary()` 直接读权威 JSON（同一个事实不留两份），
并加判据 `TestDebtSummaryReadsAuthoritativeLedger` 双向钉住：
① 不许再引入手写副本；② 打出来的数字必须与 JSON 一致，
且**每一笔余额>0 的都要出现在打印里**（漏掉的欠账等于不存在）。

同时修了 `TestDebtLedgerMatchesMeasurement` 里一条**硬编码欠账清单**的断言
（它点名要求 `gesture-semantics` 必须存在 —— 还清了反而红）。
改成断言**形状**（跨端净值 + 本包可实测的那笔必须同处登记），不点名具体笔数。
★ 教训：硬编码欠账清单不可维护，漏改的后果是"还清了反而红"。

## 三、写这三条判据时连踩两次**自匹配**

`strings.Contains(src, "var debts = map[string]debt{")` —— 那串字**本身**
出现在断言的 `t.Fatal` 消息里（以及我留的说明注释里）⇒ 恒红。
（`run-all.mjs` 的自检锚点也栽过一次，那里改用 `lastIndexOf`。）
修法：锚点**拼出来**（`"var " + "debts" + " = map..."`）+ 注释措辞避开那个声明。

## 四、验证

`go test ./...` → **13 个包全过**。
新增：`appearance_semantics_test.go`（4 条断言）、
`TestDebtSummaryReadsAuthoritativeLedger`（2 条）。

server/internal/repo/appearance.go

@@ -15,8 +15,42 @@ import (
 // 而且**多账号共用一份**（键是全局常量）—— 同一台机器换账号背景不跟着走。
 // 语义是**账号级**（跟账号走，不跟设备走）。
 
+/*
+ * ⚠️⚠️ **本文件的 userID 参数收的是「用户名」，不是 UUID。**
+ *
+ * `user_appearance.user_id` 这一列存的是 `users.username`（如 `jianf`），
+ * 而**兄弟表的同名列存的是 UUID**（`user_keys` / `user_sessions` 实测都是
+ * `809967c5-…` 这种）。两处实测（2026-09-19）：
+ *
+ *     user_keys.user_id        = 809967c5-fb1e-4759-9ff7-75e312fb4d02
+ *     user_sessions.user_id    = 809967c5-fb1e-4759-9ff7-75e312fb4d02
+ *     user_appearance.user_id  = jianf                    ← 与兄弟表不同
+ *
+ * **功能上是自洽的**（本文件读写都用 username，handler 也一律传
+ * `user.Username`），所以这不是一个活跃的 bug。但它是**一个不报错的陷阱**：
+ * 任何人按兄弟表的习惯去 JOIN —— 例如
+ *
+ *     SELECT u.username, a.bg_kind FROM users u
+ *       LEFT JOIN user_appearance a ON u.user_id = a.user_id
+ *
+ * —— 会**静默匹配到 0 行**（UUID 永不等于用户名），而且没有任何错误。
+ * 我自己在审计时就先踩了一次（用 `users.user_id = user_appearance.user_id`
+ * 查出来全是空，差点当成"记录不存在"）。
+ *
+ * 为什么不改列名/加迁移：表里有**生产数据**（壁纸本体存在 blob 里、
+ * 由 `image_sha256` 引用），改列要迁移 + 回滚预案，而收益只是"名字更好看"。
+ * ⇒ 选择**把语义钉在这里**：参数名保持 `userID`（与 SQL 列名一致），
+ *   但在函数注释里写明它收的是用户名，并由判据
+ *   （`server/internal/repo/appearance_semantics_test.go`）钉住"这一列存的是用户名"。
+ *
+ * 哪天真要统一：那是一次**独立的数据迁移**（UPDATE 把 username 换成 UUID），
+ * 不该顺手做。
+ */
+
 // GetAppearance 读某个用户的外观。没有记录时返回**默认值 + false**（不是错误）：
 // 「从没设置过」是正常状态，调用方不该为此处理 404。
+//
+// `userID` 传的是**用户名**（见文件头那段警告）。
 func GetAppearance(ctx context.Context, userID string) (models.Appearance, bool, error) {
 	a := models.DefaultAppearance()
 	var updated sql.NullString