Skip to content

feat: 完成 NEXT_PHASE 阶段 1-5 产品化改造(数据库 v8) - #9

Merged
AllureCurtain merged 8 commits into
mainfrom
codex/next-phase-productization
Aug 26, 2026
Merged

feat: 完成 NEXT_PHASE 阶段 1-5 产品化改造(数据库 v8)#9
AllureCurtain merged 8 commits into
mainfrom
codex/next-phase-productization

Conversation

@AllureCurtain

Copy link
Copy Markdown
Owner

概述

docs/NEXT_PHASE_IMPLEMENTATION.md 实现阶段 1 到阶段 5 的全部内容。阶段 1-3 为此前提交,本次补齐阶段 4(设置页收口与设计 Token 清理)和阶段 5(发布候选门禁与升级文档)。

数据库 schema 从 v7 升级到 v8

分阶段内容

阶段 提交 内容
1 a586c14 主题 Token、SQLite 配置、窗口状态表与 DIP 恢复、失焦配置拆分
2 0685ad3 快捷键新表与旧配置迁移、事务化注册与回滚、录入抑制、冲突状态
3 9e8ec4a 图片原始格式读取、BLOB 表与表示关系、canonical PNG 与缩略图、按需媒体 IPC
4 657288e 六个设置面板拆分、容量与诊断、保存/取消语义、移除旧调色板 Token、i18n 与文档同步
5 87061aa 迁移/回滚/E2E/视觉/性能门禁执行、E2E 稳定性修复、docs/UPGRADE_V8.md

门禁结果

pnpm verify 全绿:

门禁 结果
pnpm lint 通过
pnpm check:contrast 通过,8 组主题组合 464 对颜色满足 WCAG 4.5:1 / 3:1
pnpm check:i18n 通过,163 个设置键 en-US / zh-CN 双语齐全
pnpm check:tokens 通过,组件中无调色板名与颜色字面量
pnpm test -- --run 通过,24 文件 201 用例
pnpm build 通过
cargo fmt -- --check 通过
cargo clippy -- -D warnings 通过
cargo test 通过,209 用例
cargo test -- --ignored(性能) 通过,10 万条文档查询 794µs(阈值 1s)、启动索引校验 2.20s(阈值 10s)
pnpm e2e(Windows) 通过,6 用例 31s

迁移与回滚门禁由 src-tauri/src/database/connection.rs 用例覆盖:v7 升级、窗口尺寸成对规则、旧图片迁移、注入失败后回滚到 pre-v8 备份、损坏库保留、高版本拒绝。

值得注意的行为变更

  • 窗口默认尺寸 560 x 760680 x 720。仅当旧值正好等于旧默认值时迁移;用户改过任一维度则整体保留。
  • 快捷键:升级保留原有快速粘贴启用态,全新安装默认关闭。
  • 失焦行为拆分为 hide_on_focus_losshide_after_paste 两个独立键。
  • 移除图片 5 MiB 拦截;改为容量预算策略(-1 / 512 MiB / 2 GiB / 5 GiB,按最旧未收藏项淘汰)。
  • pnpm verifypnpm release:verify 均新增三道静态门禁。

E2E 稳定性修复

Win32 剪贴板是全局独占资源,OpenClipboard 被其他进程持有时 Set-Clipboard / Clipboard::SetImage 会立即抛 ExternalException 而非阻塞,导致门禁偶发失败(首轮 5 通过 1 失败)。已为剪贴板读写辅助函数加入有界重试(最多 5 次、递增退避),仅匹配与显示语言无关的 ExternalException 类型名,非争用错误仍快速失败;发送按键与资源管理器辅助函数不重试以避免重复触发。

已知限制

安装包实机验证(托盘、开机自启、窗口恢复、剪贴板格式)未执行。 当前环境无法完成打包实机验收,已在 docs/UPGRADE_V8.md §10 以「状态:未执行」记录并保留未勾选清单,未按通过计入。合并前建议补做。

测试计划

  • pnpm verify 全链路
  • pnpm e2e Windows 端到端
  • cargo test -- --ignored 性能门禁
  • 迁移失败回滚与损坏库保留用例
  • 安装包实机验证托盘 / 开机自启 / 窗口恢复 / 剪贴板格式
  • v7 真实用户库升级抽样验证

按 docs/NEXT_PHASE_IMPLEMENTATION.md §16 Phase 4 收口设置页与设计系统。

设置页
- 六个面板拆分为 panels/(General/Appearance/Shortcuts/Behavior/Data/About),
  导航顺序按 §5.1 固化在 settingsNav.ts。
- 数据面板补齐容量用量与诊断信息展示。
- 保存/取消语义与未保存变更拦截(UnsavedChangesDialog),错误态可见。
- 快捷键录入抽出 shortcutCapture.ts 与 ShortcutRow,冲突与保留组合状态显式呈现。

设计 Token
- 移除旧蓝紫色 Token 与硬编码内容类型颜色,统一走语义 Token。
- 新增三道静态门禁并接入 pnpm verify:
  - check-contrast.mjs:8 组主题组合 464 对颜色校验 WCAG 4.5:1 / 3:1;
  - check-i18n.mjs:163 个设置键在 en-US / zh-CN 双语存在;
  - check-tokens.mjs:禁止组件中出现调色板名与颜色字面量。

文档与文案
- 更新中英文 i18n,清理过时快捷键文案。
- 同步 docs/API.md 图片表示与按需媒体接口、docs/DATABASE.md v8 schema。

门禁:pnpm verify 全绿(前端 24 文件 201 用例、Rust 209 用例、fmt/clippy 无警告)。
按 docs/NEXT_PHASE_IMPLEMENTATION.md §16 Phase 5、§18 六项交付物和 §19 措辞约束收尾。

门禁执行
- 迁移与回滚门禁:connection.rs 现有用例覆盖 v7 升级、尺寸成对规则、
  旧图片迁移、注入失败后回滚到 pre-v8 备份、损坏库保留、高版本拒绝。
- 性能门禁:cargo test -- --ignored,10 万条文档查询 794µs(阈值 1s)、
  启动索引校验 2.20s(阈值 10s)。
- Windows E2E 门禁:6 用例 31s 全通过。
- 视觉门禁:contrast / i18n / tokens 三道静态检查。

E2E 稳定性修复
- Win32 剪贴板是全局独占资源,OpenClipboard 被其他进程持有时 Set-Clipboard /
  Clipboard::SetImage 会立即抛 ExternalException 而非阻塞,导致门禁偶发失败。
- 为剪贴板读写辅助函数加入有界重试(最多 5 次、递增退避),仅匹配与显示语言
  无关的 ExternalException 类型名,非争用错误仍然快速失败。
- 发送按键与资源管理器辅助函数不重试,避免重复触发。

发布脚本
- scripts/verify-release.ps1 补齐此前缺失的 check:contrast / check:i18n /
  check:tokens 三道门禁,与 pnpm verify 对齐。

文档
- 新增 docs/UPGRADE_V8.md:升级前备份提示、自动备份与回滚路径、迁移日志原文、
  新增配置键与默认值变更、窗口 DIP 恢复、图片三种表示与容量策略、
  快捷键冲突与 Win 键边界、门禁执行记录、回滚步骤、已知限制。
- CHANGELOG.md 填充 Unreleased;docs/INDEX.md 与 RELEASE_CHECKLIST.md 同步。

已知限制:安装包实机验证(托盘、开机自启、窗口恢复、剪贴板格式)在当前环境
无法执行,已在 docs/UPGRADE_V8.md §10 明确记录为「未执行」,未按通过计入。
解决 main 第 40/41 轮(Linux 支持 + Web/HTTP 能力)与本分支阶段 1-5 的冲突。

文本冲突(4 处,均为两侧并列新增,双方保留)
- config/registry.rs:theme_family / theme_mode / image_budget_bytes 与
  http_access_token 四个配置键及其描述符并存。
- database/clipboard_query.rs:fetch_item_by_id_locked 同时执行
  hydrate_media 与 hydrate_tags。
- hotkey/manager.rs:main 仅把 tests 模块从文件头移到文件尾,本分支在文件头
  版本上新增了 2 个用例,保留文件头版本并删除文件尾重复模块。
- window/controller.rs:合并导入,serde::Serialize(main 的 WindowStatus)与
  Monitor / AtomicUsize(本分支的窗口状态恢复)并存。

语义冲突(main 新增代码未含阶段 3 新字段)
- database/ocr.rs、http/diagnostics.rs 测试夹具补 image_sources。
- http/dto.rs 测试夹具补 media。
- http/mod.rs 图片夹具补 image_sources: Vec::new(),该空值会走 insert 内部
  合成 PNG 源表示的默认路径。

图片端点适配 v8 存储模型
- main 的 /api/clipboard/:id/image 与 :id/thumbnail 原本从 item.content 解析
  data URL,而阶段 3 已把图片字节迁入 binary_blobs,端点因此返回 400。
- 两个端点改为读取 canonical 表示(始终为 PNG);缩略图仍按调用方请求的边长
  实时渲染,不复用固定 192px 的 thumbnail 表示。
- 随之移除已无调用者的 images::decode_png_data_url 及其 2 个用例,并更新
  images.rs 模块文档以反映 v8 存储模型。

验证:pnpm verify 全绿(前端 24 文件 201 用例、Rust 229 + 2 + 6 用例、
fmt/clippy 无警告、contrast/i18n/tokens 三道门禁)。
sources 只在 Windows 分支通过 append 追加位图表示,非 Windows 目标下顶层的
mut 绑定成为多余,触发 -D unused-mut 导致 Backend (Linux) 编译失败。改为在
Windows 的 cfg 块内重新绑定获得可变性,不用 allow 掩盖 lint。
@AllureCurtain
AllureCurtain merged commit c353d0f into main Aug 26, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant