fix: 按审查报告修复 P2/P3 问题并升级 1.0.5

2026-08-08 18:15:11 +08:00
parent b6403b7536
commit d95d17234e
20 changed files with 457 additions and 439 deletions
@@ -0,0 +1,81 @@
+# 代码审查交接单 — halo-dark-mode-plugin（2026-08-08）
+
+> 由审查窗口产出，供开发窗口执行。结论：**可合入，无 P1 阻断问题**。
+> 审查基线：`HEAD = 363f30d`（工作区干净，已与 origin/main 同步）。
+> 审查范围：Dark Reader 迁移相关 4 个提交（202ab53 / 0bb552b / 88a071f / 363f30d）。
+
+## 一、开发窗口无需重复验证（审查窗口已实测）
+
+- `vite build` 通过：main.js 109.96KB（gzip 37.79KB）、style.css 3.76KB，Dark Reader 已打入 bundle，`enable/disable` 具名导出解析正常
+- `vue-tsc --build` 通过（exit 0）
+- `pnpm-lock.yaml` 与 `file:../third-party/darkreader` 依赖一致（含 malevic 0.20.2）
+- 构建产物 style.css 已无 `[data-halo-theme=dark]` 规则（属性属历史遗留）
+- DR 产物头 `v4.9.129` 与 README 一致
+
+## 二、待办清单（建议按 P2 → P3 顺序执行）
+
+### P2-1 FOUC：深色用户刷新 console 会浅色闪烁
+- 位置：`ui/src/darkreader-engine.ts`（watch immediate 块，33-46 行）
+- 原因：bundle 在 console 渲染后才执行，DR `enable()` 是异步分析+注入，无同步兜底
+- 建议：`enable()` 前同步设 `document.documentElement.style.colorScheme = 'dark'`；或作为已知限制写进文档
+
+### P2-2 本地项目文档滞后（与"纯 DR 策略"不符）
+- `AGENTS.md` / `CLAUDE.md`：仍描述 `halo-core.css`、`overrides/`、Monaco 同步、FOUC 同步脚本——这些已不存在（`ui/src/styles/` 只剩 `index.css` + `variables.css`）
+- `scripts/README.md` 45-52 行：仍写"Monaco 日志查看器主题同步"，实际已改为检查 `data-darkreader-mode`
+- 建议：同步到纯 DR 现状
+
+### P2-3 验证工具双份、命名不一致
+- `scripts/`：login-wait.py、scan-dark.py、verify-toggle.py
+- `workplace/`：login_wait.py、scan_dark.py、fetch_bundle.py、probe_conflict.py、aggregate.py
+- 建议：统一收口到 `scripts/`，旧文件删除需用户书面确认
+
+### P2-4 前端零单元测试
+- `pnpm test:unit` 为 `vitest --passWithNoTests`，恒绿
+- 建议：为 `ui/src/composables/useDarkMode.ts` 补 3-4 个用例，覆盖 `toggle()` 的 light/dark/auto 三种迁移与持久化回退
+
+### P2-5 多标签页主题不同步
+- 位置：`ui/src/composables/useDarkMode.ts`
+- 建议：监听 `storage` 事件同步主题
+
+### P2-6 可访问性
+- `ui/src/components/ThemeToggle.vue` 10-15 行：div+@click，无 role/tabindex/键盘/aria-pressed
+- `ui/src/views/SettingsView.vue` 36-41 行：选项 div+@click，同上
+- 建议：补键盘与 ARIA（或改原生 radio 语义）
+
+### P3-1 后端日志
+- 位置：`src/main/java/run/halo/darkmode/DarkModePlugin.java` 24、29 行 `System.out.println`
+- 建议：build.gradle 已有 Lombok，改 `@Slf4j` + `log.info`
+
+### P3-2 vendored package.json 保留完整 devDependencies
+- 位置：`third-party/darkreader/package.json`
+- 建议：裁剪为 name/version/main/module/types/license 最小字段（`file:` 依赖不会安装 devDeps，但保持干净）
+
+### P3-3 无 DR 升级/完整性机制
+- 建议：README 或脚本记录 DR 产物 SHA-256，固定版本
+
+### P3-4 data-halo-theme 属性 + variables.css 已成历史遗留
+- 构建产物已无 `[data-halo-theme=dark]` 规则，属性无 CSS 消费方
+- 建议：保留可以，但注释说明是兼容性遗留
+
+### P3-5 文案硬编码中文，无 i18n
+- 低优先级（目标用户中文），可暂缓
+
+### P3-6 plugin.yaml `spec.enabled: true`
+- 确认是否有意（Halo 通常安装后由用户启用）
+
+## 三、完成后回归验证清单
+
+```bash
+cd ui
+pnpm build          # 构建通过
+pnpm type-check     # 类型检查通过
+pnpm lint           # 通过
+# 真实环境验证（AGENTS.md 规定流程）
+python scripts\verify-toggle.py   # 三向断言全 PASS（属性/存储/Dark Reader 翻转）
+```
+
+## 四、无需改动的亮点（避免开发窗口误改）
+
+- third-party/darkreader 只跟踪 5 个构建必需文件 + gitignore 白名单，LICENSE/版权头保留，合规 ✅
+- style.css 从 ~500KB 降到 3.76KB，纯 DR 策略成立 ✅
+- verify-toggle.py 的 darkreader 断言与策略一致 ✅