MailUI4Agents/docs/DEBTS.json

{
  "_": [
    "欠账的**单一登记**（pi 2026-09-14 裁定 §3）：三笔类型不同、但必须能一眼看全。",
    "为什么要一个文件：三笔原先各自表达（RESULT static=5 / t.Skip / 登记在文档里的到期前提），",
    "没有一处能看全 —— 而『欠账不显形，就等于没有』；分散在多处的登记，审计时只会被找到一处就当全部。",
    "两端都读这个文件：Go 侧判据断言自己的条目与**实测**一致（不许留一份手写的数字），",
    "electron 套件把它打进 RESULT 行（那是常态可见的位置）。",
    "已结算（2026-09-14）：calendar-today-recompute —— P6 第 1 步（日历页 pages/CalendarPage.ets）落地，today 走 `@Prop @Watch('onVisibleChanged') visible` 在 pane 变可见时重算（另有 aboutToAppear 覆盖重新挂载），判据 test/harmony-calendar.test.mjs 的「★ today 在 pane **变可见时**重算」。结算即从此清单移除，余额里不再计这一笔。",
    "已结算（2026-09-19）：gesture-semantics —— P6 第 3 步（左右滑动翻页）落地：鸿蒙侧 `CalendarPage.ets` 加了 `PanGesture`、判定逻辑在纯逻辑层 `model/Calendar.ts` 的 `judgeSwipe`。按该条自己的口径（「鸿蒙侧出现滑动手势代码时**立即建**」）同步建了语义契约判据 `test/cross-client-gesture.test.mjs`（8 条）—— 按 (b) 口径钉**语义**不钉数值：左滑=下一段/右滑=上一段/纵向优先/快滑窗口/手势与按钮共用同一翻页函数/无边界回弹/有意差异被记录/方向写反必红。另在 `harmony-logic.test.mjs` 加了行为判据（跑 `judgeSwipe` 的四道门）。结算即从此清单移除，余额里不再计这一笔。",
    "2026-09-19 新增 wide-breakpoint-divergence：两端断点不同且含义不同（审计发现，此前无记录）。它不是\"已确认的缺陷\"，而是**未决的口径** —— 登记它是为了让「两者不同」这个事实本身可见，而不是让它藏在两处代码里。",
    "2026-09-19 新增 mail-list-attachment-count：邮件列表的附件数两端都拿不到（WebUI 那段是死代码）。鸿蒙侧只补了有真数据的「抄送 N」。",
    "2026-09-19 新增 harmony-maildetail-missing-three：邮件详情页缺三块功能（改名建议 / 转发 / 预算编辑），服务端都已支持。"
  ],
  "debts": [
    {
      "id": "static-criteria",
      "count": 5,
      "due": "本工作区能装、能点设备（探针三值转 true 时自动变红）",
      "where": "client/electron/test/run-all.mjs 的 STATIC_ONLY（2026-09-19 起 harmony-admin 那条已升级为设备判据、移出名单 ⇒ 6 → 5：test/harmony-appearance.test.mjs、test/harmony-logic.test.mjs、test/cross-client-theme.test.mjs、test/appearance-defaults.test.mjs、test/harmony-imageprep.test.mjs）",
      "kind": "scope",
      "note": "2026-09-19：`harmony-admin` 的条目**已升级**（管理页真的能打开、列表真的渲染出用户行）并移出 STATIC_ONLY ⇒ 本笔 6 → 5。剩下的五次升级按\"每条缺什么设备侧验证\"逐条来，不为了把数字消成 0 而凑 —— 凑出来的设备判据只是把\"没验\"换成\"假装验了\"。\n\n2026-09-19 再更新：`cross-client-theme` **升级了一半** —— 新增一条设备判据（读悬浮球像素：品牌色真的画成 `#2563EB`；且球上图标与底色 WCAG 对比度 ≥3:1），并顺手钉了一条静态防线（`Theme.surface` 不得当代的前景色）。**它仍留在 STATIC_ONLY 名单里**，因为 `.ets` 那半只有悬浮球这一处上了设备 —— 其余令牌仍是静态对齐。「一半」要写出来，不能让名单看起来像没动过。"
    },
    {
      "id": "mails-status-derived",
      "count": 1,
      "due": "详情/线程改为按读者派生（readStateFor）之后 —— 那时 mail_status_derived_test.go 从 Skip 转实跑",
      "where": "server/internal/repo/mail_status_derived_test.go",
      "kind": "scope"
    },
    {
      "id": "observability-output",
      "count": 1,
      "due": "页面层（MainPage.ets）接上「读 presetSubstitutedFrom 并打一行日志」时；那一步同时补判据『读侧恰好出现 1 次且在日志调用里』",
      "where": "尚无判据 —— 这正是欠账的一部分（P6 第 1、2 步动 MainPage.ets 时一起做）；形态判据在位：test/harmony-appearance.test.mjs（bgBlur 消费侧计数）",
      "kind": "scope"
    },
    {
      "id": "unknown-preset-approval",
      "count": 1,
      "due": "有人对上表那格**追认或驳回**「未知 id 显示 aurora 而不是空白」这个方向时（我作为实现者不能自己追认自己）",
      "where": "client/electron/test/CRITERIA.md §10 的『未知的预设 id』行（现为『无人类批准』）",
      "kind": "env"
    },
    {
      "id": "overlay-follows-app-theme",
      "count": 1,
      "due": "上设备后**翻转一次 colorMode**（应用深色 / 系统浅色），断言**解析出的遮罩值跟着「应用」主题变、而不是跟「系统」**；真机若证伪，正确修法是「遮罩从应用主题派生」，不是回到双常量",
      "where": "client/harmony/entry/src/main/ets/common/Theme.ets:58-79 的注释（机制依据：AppearanceStore.applyTheme → app.setColorMode）——**注释不是判据，所以进余额**",
      "kind": "env"
    },
    {
      "id": "nav-dark-route-b-unguarded",
      "count": 0,
      "due": "已完成 2026-09-23（见 note）",
      "where": "client/electron/test/background.test.mjs —— **已堵**：见 note。（原文：`.dark .nav-rail{}` 选择器作用域与组件 `dark:` 变体，变异确认过都会逃掉）",
      "kind": "scope",
      "note": "**已堵（2026-09-23）**。这三条逃逸路（A 选择器作用域 / B Tailwind `dark:bg-*` 变体 / C 元素级 `backdrop-blur-*`）此前各自无判据，变异确认过全逃得掉。到期条件（深色主题落地）在 2026-09-17 就成立了 —— 但那次只修了令牌这条路，欠债逾期至此。\n\n堵法（欠债原文点名的**文件窄豁免**，不是一刀切）：`background.test.mjs` 新增三条 check，**只扫 `className` 里出现 `nav-rail`／`nav-item` 的那些类串** —— 问的不是「这个文件有没有 dark: 背景」，而是「挂在导航元素上的那个类串里有没有」（与逃逸路的形状同构；同文件别的元素写什么都不影响，避免 `bg-chrome-600` 那个先例的误红）。\nA 条另起一条：CSS 里不许出现 `.dark .nav-rail`／`.dark .nav-item` 这类选择器。\n三条都做了变异验证（逐条注入 ⇒ 各红一条；恢复 ⇒ 47/47 全绿）。"
    },
    {
      "id": "nav-blur-route-c-unguarded",
      "count": 0,
      "due": "已完成 2026-09-23（见 note）",
      "where": "client/electron/test/background.test.mjs —— **已堵**：见 note。（原文：元素级 `backdrop-blur-lg` 不在那条选择器下，变异确认过逃得掉）",
      "kind": "scope",
      "note": "**已堵（2026-09-23）**。这三条逃逸路（A 选择器作用域 / B Tailwind `dark:bg-*` 变体 / C 元素级 `backdrop-blur-*`）此前各自无判据，变异确认过全逃得掉。到期条件（深色主题落地）在 2026-09-17 就成立了 —— 但那次只修了令牌这条路，欠债逾期至此。\n\n堵法（欠债原文点名的**文件窄豁免**，不是一刀切）：`background.test.mjs` 新增三条 check，**只扫 `className` 里出现 `nav-rail`／`nav-item` 的那些类串** —— 问的不是「这个文件有没有 dark: 背景」，而是「挂在导航元素上的那个类串里有没有」（与逃逸路的形状同构；同文件别的元素写什么都不影响，避免 `bg-chrome-600` 那个先例的误红）。\nA 条另起一条：CSS 里不许出现 `.dark .nav-rail`／`.dark .nav-item` 这类选择器。\n三条都做了变异验证（逐条注入 ⇒ 各红一条；恢复 ⇒ 47/47 全绿）。"
    },
    {
      "id": "boundary-vocabulary-incomplete",
      "count": 1,
      "due": "**由外部读者报告时**（自查机制对这一类结构性失明 —— 发现词表外说法的机制，正是看不见它的那个机制）。收到报告后：扩词表 + 登记该处 + 保留\"上一次是谁发现的\"。**没有内部触发器，这是这条递归的不动点**：无论词表多长、判据多严，总有一类盲区只能靠\"外面有人读了一遍\"",
      "where": "client/electron/test/debt-visibility.test.mjs（词表键控的盲区：**已知未覆盖**——词表是采样、不是完备）",
      "kind": "env"
    },
    {
      "id": "redeploy-script-unguarded-steps",
      "count": 1,
      "kind": "scope",
      "due": "**下一次改 `deploy/` 下任一脚本时**必须一并堵（`redeploy-gateway.sh` 正在被另一条会话改 ⇒ 本条目就是给它接手时的入口）。堵法：给每个副作用步骤加 `|| { bad …; exit 2; }`，或在脚本上开 `set -e`；两者都要与既有的 2=环境 / 1=检查 约定对齐。",
      "where": "`deploy/redeploy-gateway.sh:84` 的 `run \"cp -r '$REPO/client/electron/dist/.' ...\"` —— 脚本只有 `set -uo pipefail`（**无 `-e`**），`run()` 内部 `eval` 的失败既不中断也不被调用点接收 ⇒ 前端产物没拷进去也继续往下走。同类已在 `deploy/redeploy-plugin.sh` 修掉（2026-09-14）：那次的实测形状是 `mkdir`/`cp` 被拒后仍打出 `[ OK ] 已拷入 node_modules`，再打出 `[FAIL] staging 里没有入口` —— **一段输出里两个矛盾信号，且 OK 在前**。该文件现已在 `mkdir`/`cp`/`node_modules` 三处判失败并 exit 2。"
    },
    {
      "id": "deploy-space-prefix-fs",
      "count": 1,
      "kind": "判据铺得不满（不是新列）",
      "due": "下一次因空间问题失败时；或有人愿意补一行 df 时",
      "where": "deploy/lib/env-defaults.sh ②b 只判了 $TMPDIR，没判 $PREFIX 所在的文件系统"
    },
    {
      "id": "pi-bridge-adopt-cwd-mismatch",
      "count": 1,
      "kind": "沙箱 rw 与 worker 实际 cwd 的第三个来源未对齐（同类已修两处，剩接管路径）",
      "due": "下一次动 pi 桥的会话装载 / `session-scan.mjs` 时；或有人愿意把「这一轮用哪个 cwd」完全收成父进程一处决定时",
      "where": "`plugins/pi-mail-bridge/src/worker.mjs` 的**接管会话**分支：worker 用会话文件 header 里的 `info.cwd`（`resolveWorkspaceCwd(info.cwd || data.to_workspace, …)`），而父进程（`src/pool.mjs` → `src/turn-cwd.mjs`）只能从 `state` 里拿 `{sessionFile, cwd}`，**读不到 header** ⇒ 接管的首回合 rw 仍可能不含 worker 真正要写的目录。父进程要拿 header 得用 `src/session-scan.mjs`，但 `readHeader` 未导出、整表 `scan()` 在父进程里代价大（worker 里实测 1431ms / 堆瞬时 240MB，见 worker.mjs 里那段注释）。★ 这类错位的**特征是没有提示**：EACCES 落在「界内」，读日志的人会以为沙箱装错了（不像 `ask` 还有一次问）。修法方向：把「这次用哪个 cwd」收成父进程一处决定（它已有 `state.sessionFile`，header 也可读），worker 只消费、不再自己推导 —— 即 `src/turn-cwd.mjs` 头注释里写的「三来源变一来源」。"
    },
    {
      "id": "deploy-interrupt-trap-other-scripts",
      "count": 1,
      "kind": "只在 redeploy-gateway.sh 做了，另两个部署脚本没做",
      "due": "下一次动 redeploy-plugin.sh / install.sh 时",
      "where": "只有 redeploy-gateway.sh 有 INT/TERM/HUP trap；install.sh 与 redeploy-plugin.sh 在写系统目录期间被打断同样会留半成品（它们没有\"服务停着\"那种后果，所以优先级低）"
    },
    {
      "id": "harmony-p4c-boundary-decls",
      "count": 4,
      "due": "本工作区能装、能点设备 —— 那时这几条静态判据里被替代掉的那些断言换成真机断言，声明随之减少",
      "where": "client/electron/test/harmony-admin.test.mjs、client/electron/test/harmony-imageprep.test.mjs",
      "kind": "scope",
      "note": "2026-09-19 更新（设备可用了，开始逐条升级）：① `harmony-admin` 的那条**已升级为设备判据**（管理页真的能打开、列表真的渲染出用户行）⇒ 从本组减 1。② `harmony-imageprep` **只做了一半**，如实记着：新加的设备判据用真实素材（用户真上传的那张壁纸 1402×1122 / 152570 字节，从 GET /me/appearance/image 取回）验了「设备上读到的尺寸/体积与压缩决策的输入对得上」；**未做**「应用真的用 image.createImagePacker() 压一次、产出字节落在预期区间」——那需要一个**用户选图**入口（DocumentViewPicker，要人操作系统选择器），自动化里没有稳定路径。编一个绕过选择器直接调 packJpeg 的测试专用入口，会是只有测试在用的代码 —— 那种代码不会被真实场景触到，验它等于验一个不存在的东西。⇒ 剩 4 条里这一条要等一个**真人操作**的验证窗口（或平台提供可注入的选择器）。"
    },
    {
      "id": "deviceprobe-fixture-timing",
      "count": 1,
      "due": "把两份 fixture 变成**当场采集**（跑 hdc dump 取现场）而不是人工存文件时，这条就到期",
      "where": "client/electron/test/harmony-deviceprobe.test.mjs（两处提到「未验」的断言 + fixtures/aa-dump-l-*.txt）",
      "kind": "scope"
    },
    {
      "id": "wide-breakpoint-divergence",
      "count": 1,
      "due": "决定是否统一：鸿蒙 768vp vs WebUI 1024px（**不是 bug，是未决的口径**）",
      "where": "client/harmony/entry/src/main/ets/pages/MainPage.ets（isWide 的 onAreaChange，>=768） 与 client/electron/src/hooks/useIsNarrow.ts（NARROW_QUERY = max-width: 1023px）",
      "kind": "scope",
      "note": "两端断点不同，且**含义也不同**，所以数值不同本身不算错：WebUI 的 1024 是「三栏（60 导航 + 320 列表 + >=520 详情 ≈ 900px，再加余量）放不下就退化单栏」，鸿蒙的 768 是「要不要显示侧栏」（鸿蒙没有并排的列表+详情三栏，它的内容区是一个窗格，所以 768 就够）。但**用户可见的后果**是：在 768–1023 宽（常见竖屏平板、窄窗口）下，WebUI 是单栏 + 底部导航，鸿蒙是侧栏 + 内容 —— 两台设备上同一宽度长得不一样。2026-09-19 由审计发现（此前**没有任何地方记录**这件事，连「两者不同」这个事实本身都没写下来，所以下一个人只会当成漏改）。待定：① 统一到 1024（鸿蒙跟 WebUI）；② 统一到 768（WebUI 跟鸿蒙，但要重新论证三栏是否真能在 768 放下）；③ 承认它们是两件事、把语义差异写进文档（那就该给两端各自的名字，而不是都叫 wide）。"
    },
    {
      "id": "mail-list-attachment-count",
      "count": 0,
      "due": "已修（2026-09-20）：字段确实返回，两端都可接",
      "where": "server/internal/handler(邮件列表的响应构造) —— 客户端侧见 client/harmony/entry/src/main/ets/pages/MainPage.ets 的 MailItem",
      "kind": "scope",
      "note": "★★ 2026-09-20 **更正**：当初这条的结论是**错的**，根因是它把一个`omitempty` 造成的**字段缺失**当成了「服务端不返回这个字段」。\n\n原文（留档，别再犯）：实测 `GET /me/mail/inbox` 的回包字段列表里「既没有 `attachments` 也没有 `has_attachments`」⇒ `MailList.tsx:261` 的 `mail.attachments?.length ?? 0` 恒为 0、那个 📎 在 WebUI 上从不出现（死代码）。\n\n事实：服务端 `GetInbox`（`mail.go:586`）**明确调了 `fillAttachments`**，并写了理由：「Agent 靠收件箱列表得知有哪些附件可下载，否则它不知道该调 attachment_id」。而 `Mail.Attachments` 的 json tag 带 **`omitempty`** —— **没有附件的邮件根本不输出这个 key**。\n我当初是**只看了一封没附件的邮件**就下了全称结论。\n\n2026-09-20 实测（`limit=200`，96 封）：带 `attachments` 的 **2 封**，都是真有附件的那两封。⇒ **WebUI 那个 📎 不是死代码**，鸿蒙当初「有意不抄」的前提不成立。\n\n★ 教训：`omitempty` 字段的**缺失**不等于「服务端不返回」。判「某字段有没有」必须拿**确实有值的那条**去验，而不是拿一条恰好为空的数据。这与同一天那个真崩溃（`session_workspace` 的 `omitempty` → 客户端 `undefined` → 白屏）是**同一个坑的两面**。"
    },
    {
      "id": "harmony-maildetail-missing-three",
      "count": 0,
      "due": "鸿蒙详情页对齐 WebUI 时（三块功能，服务端都已支持）",
      "where": "client/harmony/entry/src/main/ets/pages/MailDetailPage.ets （对照 client/electron/src/components/MailView.tsx）",
      "kind": "scope",
      "note": "2026-09-19 审计发现：邮件详情页缺**三块 WebUI 有的功能**，而且**服务端三块都已支持**（不是做不了）：① `RenameProposalBar`（MailView.tsx:324）—— Agent 建议改会话别名，人确认/驳回。服务端 `server/internal/handler/rename_proposal.go` 已在解析 `propose_alias` 标记并把提议从正文剥掉。**这条对寻址稳定性很重要**（WebUI 那里的注释：「Agent 干到一半自己改掉，人上一秒记住的地址下一秒就失效」）。② `ForwardBar`（MailView.tsx:378）—— 转发。服务端 `forward.go` 完整（含 `forwardSubject` 的 Fwd: 叠加处理）。③ `BudgetEditor`（MailView.tsx:235）—— 会话往返预算编辑（`max_rounds`，服务端 `forward.go:304` 有此字段）。三条都不是顺手能补的量级（各含交互 + 接口 + 状态），所以先登记，不在审计那一批里硬塞 —— 硬塞的结果是每条都半成品。\n\n2026-09-19 结算：三块**都做完了** ——\n① 转发（commit cc7ff25，`ForwardMailRequest` + 弹层；修了两个真 bug：两个动作球几乎完全重叠、弹层没高度导致键盘一弹按钮被顶出屏幕）；\n② 会话改名建议（commit c26e857 接口 + fe4342a UI，端到端实测：服务端识别 rename_proposed → 建议条出现 → 点接受 → 库里别名真的改了）；\n③ 往返预算（commit 4e84369，GET/PUT 契约用 curl 逐条实测）。\n★ 未验：预算条的**点击**在设备上没走通 —— 模拟器顶部 155px 是系统手势区，而折叠头部恰在其中（坐标式点击会被系统抢走）。数据链路已实测，观感没验。"
    },
    {
      "id": "harmony-dead-pages",
      "count": 2,
      "due": "下次清理鸿蒙页面时（要先确认不是将来要用的留存实现）",
      "where": "client/harmony/entry/src/main/ets/pages/InboxPage.ets（238 行）、pages/SessionsPage.ets（170 行）",
      "kind": "scope",
      "note": "2026-09-20 盘点发现的**不可达页面**（两页共 408 行）：\n· `InboxPage.ets` —— 不在 `resources/base/profile/main_pages.json` 的页面表里，全仓**没有任何** `pushUrl('pages/InboxPage')`。\n· `SessionsPage.ets` —— 注册在页面表里，但**唯一的引用**是 `InboxPage.ets:171` 的 `pushUrl('pages/SessionsPage')`，而 InboxPage 本身不可达 ⇒ 一起不可达。\n\n★ 为什么没顺手删：`docs/HARMONY-ALIGN-PLAN.md:214` 把 `InboxPage.ets` 当作变异测试的靶子（往它塞一个色值来验证判据能判红），说明它在某个时点是有用的。删掉会永久丢代码，而它是否只是「早期实现的留存」我判断不了 —— **这是人的决定**。\n\n★ 它现在还带来实际成本：`cross-client-logic` 与 `harmony-arkts` 的**形状判据**会扫到它（并按「死代码」给它豁免）—— 每加一条形状判据都要为「这文件还活着」多写一次例外。要么删、要么在文件头明确写「这是留存参考、不参与构建」，两条路都比现在清楚。"
    },
    {
      "id": "harmony-permission-history",
      "count": 0,
      "due": "**已完成 2026-09-21**（本轮「授权栏与 WebUI 对齐」）",
      "where": "client/harmony/entry/src/main/ets/pages/MainPage.ets 的 PermissionTab（现在只读 /permission/pending）",
      "kind": "scope",
      "note": "**已修（2026-09-21）**。原文：鸿蒙只调 `/permission/pending`（SQL `WHERE pr.result IS NULL`）⇒ 已决策的历史完全看不到。\n\n修法与**为什么不照抄 WebUI 的 inbox 分组**：\n· WebUI 从 inbox 分组（`groupPermissions`），但它的 `PermissionRow` 只渲染\n  `subject`/`created_at`/`permission_result`/`permission_expires_at`（逐字段 grep 过）；\n· 而**待决**那一段我们要显示 `question`/`options`/`context`/`kind` —— 那四个字段在\n  `permission_requests` **表**里，inbox 回包（`models.Mail`）**没有**（模型逐条核过）。\n⇒ 待决继续走专用端点（信息更全、能直接决策），**历史**走 inbox 补上。\n  代价：每账号多一次请求。这是有意的取舍。\n\n落地：`model/MailGrouping.ts` 加 `groupPermissions` + `PermissionGroup` + `isPendingPermission`；\n`PermissionTab.load` 取 inbox 里 `mail_type=permission_request && permission_result!=空` 的，\n分组后渲染「历史 n 条」。`cross-client-logic.test.mjs` 的 `gaps` 已按提示清空。"
    },
    {
      "id": "harmony-morph-unverified-middleframes",
      "count": 1,
      "due": "有更快的取帧手段时（snapshot_display 往返 1.5-3s ⇒ 只能验 >=3s 的动画），或用户在真机上看过并反馈",
      "where": "client/harmony/entry/src/main/ets/common/Motion.ets 的 Motion.morph；调用点 MailDetailPage / MainPage",
      "kind": "env",
      "note": "2026-09-21 加了两处**共享元素转场**（geometryTransition：回复球<->回复条、写信 FAB<->写信页），结构与接线都有判据钉住（animation-audit.test.mjs 6 条，三条变异逐个验过会红），但**动画本体在设备上没能看到**。\n\n原因：snapshot_display 一次往返 1.5-3s，uitest screenCap 约 3s，而这条动画 220ms ⇒ 探针比被测对象慢一个数量级。实测连拍 4 张，y=1600 的白区跨度全是 (30,1007)（每张都已是终态）。\n\n★ 这里的教训本仓已记过一次（「探针对被测变化不敏感时，量的是噪声」——那次我连测七八轮「没有中间帧」并编出三个错误理论，最后被位移探针推翻）。这次不再重复：**如实标未验**，不声称已看到。\n\n要验它需要：能按帧取图的手段（screenrecord 在本环境不可用），或真机上手看。"
    },
    {
      "id": "harmony-account-errors-banner-unverified",
      "count": 1,
      "due": "有一个会取失败的账号可构造时（例如故意把某账号的 server 指向不可达地址）",
      "where": "client/harmony/entry/src/main/ets/pages/MainPage.ets 的 accountErrors 横幅",
      "kind": "env",
      "note": "2026-09-21 接上了聚合失败横幅（WebUI MailList.tsx:85-96 的 account-errors）。修的是一处**安全网断线**：MailStore 一直在收集 snap.accountErrors（两处 load 都写），而界面从来没读过 ⇒ 某个账号拉不到邮件时列表**静默少一整份**，界面看起来完全正常，用户会得出错误结论（「没人给我发信」）。\n\n**只验了「不出现」那一半**：本机所有账号都取得到 ⇒ 横幅正确地不显示。「真的会显示成那样」没能实测 —— 需要一个取失败的账号，本机构造不出。\n\n为什么仍值得登记：这条横幅的**全部价值就在它出现的那一次**。「逻辑对齐 + 编译通过」与「真的渲染出来」是两件事，本仓为此反复吃过亏。"
    },
    {
      "id": "harmony-permission-history-render-unverified",
      "count": 1,
      "due": "**有一个「未归档会话」里的已决策权限请求时**（光 `UPDATE mails SET permission_result` 不够 —— 见 note 里的实测）",
      "where": "client/harmony/entry/src/main/ets/pages/MainPage.ets 的 permGroups 渲染段",
      "kind": "env",
      "note": "2026-09-21 闭合 harmony-permission-history 时新增的「历史 n 条」渲染。\n\n分组逻辑（`groupPermissions`）是纯函数、有跨端逐例判据；渲染那一层没验。\n\n★★ 2026-09-23 **实测订正复现路径**（原文写的是「`UPDATE mails SET permission_result` 之后即可复现」—— **那样做复现不出来**）。\n\n本机实测：库里**确实有 137 条已决策**的权限请求（`to_name=jianf` 107 条），但 `GET /me/mail/inbox?status=all` 返回的权限请求是 **0 条**。根因不在权限，在**会话归档**：\n  · `repo.ListInboxScoped` 硬编码 `AND s.status <> 'archived'`（该过滤在整个 repo 出现 8 处，是「归档会话不进任何列表」的**全局约定**）；\n  · 而那 107 条所在会话**全部是 archived** ⇒ 被整条过滤掉；\n  · 实测「未归档会话 + 已决策权限请求」的组合数 = **0**。\n\n  ⇒ 鸿蒙的「历史 n 条」在**当前这台库上恒为空**，不是渲染坏了，是数据够不到。\n     两端一致（WebUI `PermissionList.tsx:66` 也是 `fetchInbox('all')`，同一端点同一过滤）⇒ 这不是鸿蒙的遗漏，**是两端共同的行为**，服务端的过滤是有意的。\n\n要真验，需构造：**未归档**会话 + 该会话里一条已决策的权限请求（例如 `UPDATE sessions SET status='active' WHERE session_id=<那条>`，或让 agent 在活跃会话里发一条再决策）。\n\n★ 另一处（同一次实测发现，已修）：渲染注释曾承诺「会话别名 + **决策** + **时间**」，而代码只渲染「别名 + 历史 n 条」—— 属本仓反复在消的「声明比实现宽」。已把注释改成与 WebUI 折叠态一致的**真实形态**（WebUI 也是每组一行 `历史 {n}`，逐条的决策/时间要展开才看得到，而鸿蒙没有展开层）。"
    },
    {
      "id": "permission-expires-at-unused",
      "count": 1,
      "due": "决定是否要把「可能已失效」做进**两端**（需要两端都补类型 + 渲染）；或确认这个告警对产品不重要、把服务端那个字段也去掉",
      "where": "服务端 `models.go:254`（`PermissionRequest.ExpiresAt`）/ `repo.go:1617`（`pr.ExpiresAt = models.PermissionDeadline(...)`）；客户端类型两处都缺：`client/electron/src/types/index.ts` 的 `PermissionRequest`、`client/harmony/entry/src/main/ets/model/Models.ets` 的 `PermissionRequest`",
      "kind": "scope",
      "note": "★★ 2026-09-23 发现自己：**服务端返回一个两端客户端都不读的字段**。\n\n`GET /permission/pending` 的回包里 `expires_at` 一定存在（`ExpiresAt time.Time` 且**不带** `omitempty`），服务端在 `ListPendingPermissionsFor` 里用 `models.PermissionDeadline(pr.CreatedAt)` 算出它。而**两端的 `PermissionRequest` 类型都没有声明这个字段** ⇒ 反序列化静默丢掉。\n\n── 这次的教训与 `mail-list-attachment-count` 那次**方向相反、形状相同** ──\n那一次我把「`omitempty` 字段在一封没附件的邮件里缺失」当成了「服务端不返回这个字段」；这一次是**真的两端都没读**，而我一开始又差点写成「鸿蒙落后于 WebUI」——实际是**共同缺口**（WebUI 也没读）。两次都说明：**「两端不一致」与「两端都没做」必须先分清**，否则会去\"对齐\"一个根本不存在的东西。\n\n── 已经做掉的那一半 ──\n鸿蒙侧 2026-09-23 补上了 `expires_at` 并把它接进**待决卡片**的失效告警（`PermissionTab.ets` 的 `isStale`）。所以这条债现在**只剩 WebUI 那一半**：WebUI 的 `PermissionList.tsx:248` 读的是 `mail.permission_expires_at`（**别的字段**，那是 `Mail` 模型上由 `AttachPermissionDeadline` 算出来的，只在 inbox 路径上有），而它自己那份 `PermissionRequest` 同样没有 `expires_at`。\n\n★ 要闭合需先决定：**这个告警归哪条路径**？· 走 inbox（`permission_expires_at`）—— 但 inbox **只给未决策的**（`AttachPermissionDeadline` 的 return），  且 inbox 的 SQL **根本没选** `permission_expires_at`（实测 0 处），  它是在 repo 层算出来贴上去的 ⇒ 要确认它真的出现在回包里；\n· 走 `/permission/pending`（`expires_at`）—— 字段现成、语义清楚，但 WebUI 那边要改类型 + 读它。\n  我倾向后者（数据来源本来就对着\"待决\"这件事）。"
    }
  ]
}