# 修复计划 — halo-dark-mode-plugin（2026-08-08）

> 依据：`docs/review-2026-08-08.md`
> 状态：待用户审批
> 审批通过后按 P2 → P3 顺序执行

## 一、修复总览

| ID | 优先级 | 问题 | 修复方式 | 主要涉及文件 |
| --- | --- | --- | --- | --- |
| P2-1 | P2 | 深色用户刷新 console 会浅色闪烁 | 同步设置 `color-scheme`，在 `enable()` 前减少闪烁 | `ui/src/composables/useDarkMode.ts`、`ui/src/darkreader-engine.ts` |
| P2-2 | P2 | 本地项目文档仍描述旧的手工 CSS / Monaco 架构 | 同步 AGENTS.md、CLAUDE.md、scripts/README.md 到纯 Dark Reader 现状 | `AGENTS.md`、`CLAUDE.md`、`scripts/README.md` |
| P2-3 | P2 | `scripts/` 与 `workplace/` 脚本双份 | 删除重复脚本；专用分析脚本保留在 `workplace/` 或迁移，待确认 | `workplace/login_wait.py`、`workplace/scan_dark.py` 等 |
| P2-4 | P2 | 前端无单元测试 | 为 `useDarkMode` 补测试，覆盖 light/dark/auto、持久化与非法回退 | `ui/src/composables/__tests__/useDarkMode.spec.ts` |
| P2-5 | P2 | 多标签页主题不同步 | 监听 `storage` 事件同步主题 | `ui/src/composables/useDarkMode.ts` |
| P2-6 | P2 | 切换器/设置选项不可键盘操作 | 改为原生 `button` + ARIA，或原生 radio 语义 | `ui/src/components/ThemeToggle.vue`、`ui/src/views/SettingsView.vue` |
| P3-1 | P3 | 后端使用 `System.out.println` | 使用 Lombok `@Slf4j` 输出日志 | `src/main/java/run/halo/darkmode/DarkModePlugin.java` |
| P3-2 | P3 | vendored package.json 保留完整 devDependencies | 裁剪为最小字段，只保留构建所需元数据 | `third-party/darkreader/package.json` |
| P3-3 | P3 | 无 Dark Reader 升级/完整性机制 | 增加 `SHA256SUMS` 并写入 README 校验说明 | `third-party/darkreader/SHA256SUMS`、`README.md`、`.gitignore` |
| P3-4 | P3 | `data-halo-theme` 属性为历史遗留 | 保留属性，但在代码注释中说明兼容性遗留 | `ui/src/composables/useDarkMode.ts`、`ui/src/styles/variables.css` |
| P3-6 | P3 | `plugin.yaml` 的 `spec.enabled: true` | 建议改为 `false`，安装后由用户启用 | `src/main/resources/plugin.yaml` |

## 二、详细修复说明

### P2-1 FOUC 闪烁

- 在 `useDarkMode.ts` 的 `applyHtmlAttribute()` 中同步设置：
  `document.documentElement.style.colorScheme = isDark ? 'dark' : 'light'`
- `darkreader-engine.ts` 保持现有 `enable()/disable()` 逻辑。
- `color-scheme` 只能缓解浏览器控件/滚动条闪烁，无法完全消除 DR 异步注入间隙；
  该限制会写进注释和 README。

### P2-2 本地项目文档

- `AGENTS.md` / `CLAUDE.md`：
  - 删除 `overrides/`、`halo-core.css`、Monaco 同步、FOUC 同步脚本等旧描述
  - 统一为“纯 Dark Reader 策略”
- `scripts/README.md`：
  - 把“Monaco 日志查看器主题同步”改为检查 `data-darkreader-mode`
  - 补充 `verify-toggle.py` 的新三向断言说明

### P2-3 脚本收口

- 明确 `scripts/` 为正式工具目录。
- 计划删除的重复文件（需审批）：
  - `workplace/login_wait.py`（重复 `scripts/login-wait.py`）
  - `workplace/scan_dark.py`（重复 `scripts/scan-dark.py`）
- `workplace/fetch_bundle.py`、`probe_conflict.py`、`aggregate.py` 属于专用分析工具，
  默认保留在 `workplace/`；如需一并迁移到 `scripts/`，请在审批时注明。

### P2-4 单元测试

新增 `ui/src/composables/__tests__/useDarkMode.spec.ts`，覆盖：

1. 默认 `auto` + 系统深色 → `isDark = true`
2. `auto` 下点击切换 → 变成显式深色/浅色
3. `dark ↔ light` 往返切换
4. `setTheme()` 持久化到 localStorage
5. localStorage 非法值回退到 `auto`
6. `storage` 事件跨标签页同步

同时移除 `pnpm test:unit` 的 `--passWithNoTests`，防止测试静默通过。

### P2-5 多标签页同步

- `useDarkMode.ts` 增加：
  `window.addEventListener('storage', handler)`
- 仅当 `newValue` 是合法 `light/dark/auto` 时更新 `theme`。

### P2-6 可访问性

- `ThemeToggle.vue`：
  - `div` 改为 `<button type="button">`
  - 增加 `:aria-pressed="isDark"`
  - 保留现有样式并补按钮 reset
- `SettingsView.vue`：
  - 选项容器加 `role="radiogroup"`
  - 每个选项改为 `<button type="button" role="radio" :aria-checked="...">`
  - 键盘 Tab / Enter / Space 原生可用

### P3-1 后端日志

- `DarkModePlugin.java` 增加 `@Slf4j`
- `System.out.println` 改为 `log.info(...)`
- 保留 start/stop 语义不变

### P3-2 vendored package.json

- 裁剪为：
  `name / version / description / main / module / types / license`
- 删除 scripts、devDependencies、optionalDependencies 等构建无关字段
- 更新后执行 `pnpm install` 同步 lockfile

### P3-3 完整性校验

- 新增 `third-party/darkreader/SHA256SUMS`，记录：
  `darkreader.js`、`darkreader.mjs`、`package.json`、`index.d.ts`、`LICENSE`
- `.gitignore` 白名单增加 `SHA256SUMS`
- README 增加“升级 Dark Reader 后校验 SHA256SUMS”说明

### P3-4 历史遗留属性

- 保留 `data-halo-theme`（verify-toggle.py 仍使用）
- 在 `useDarkMode.ts` 与 `variables.css` 增加注释：
  该属性当前无 CSS 消费方，仅为兼容性遗留标记

### P3-6 plugin.yaml

- 建议将 `spec.enabled` 改为 `false`
- 理由：官方 manifest 文档建议生产环境由用户安装后手动启用

## 三、暂缓项（本计划不做）

- P3-5 i18n：目标用户为中文，暂不引入国际化
- Dark Reader 完整源码保留在本地但不入库：维持现状
- 不新增界面截图：README 已可用，后续上架前再补

## 四、回归验证

```bash
cd ui
pnpm install
pnpm type-check
pnpm lint
pnpm test:unit
pnpm build

cd ..
./gradlew test
./gradlew build
```

运行时验证：

```bash
D:\settings\settings\uv\my_uv_env\Scripts\python.exe scripts\verify-toggle.py
```

验收标准：

- 单测至少覆盖 P2-4 中列出的 6 个场景且全部通过
- `pnpm test:unit` 不再 `--passWithNoTests`
- 深色刷新时 `color-scheme` 已同步
- 键盘可操作侧边栏按钮与设置选项
- `SHA256SUMS` 可校验，README 有说明
- 后端日志不再输出到 stdout

## 五、版本与提交

- 修复内容涉及运行时代码，后续打 JAR 时按项目约定递增版本（1.0.4 → 1.0.5）
- 本次审批通过后，先提交代码修复，再按需打包