# 2026-06-29 Pro 会员增强

## 用户目标

- 接手 TagLauncher Pro 会员增强需求，基于 PM 实施计划完成：
  - Pro 自定义标签颜色。
  - 免费用户最多 3 条自定义应用备注，Pro 无限备注。
  - 快捷键、标签、数据、关于页面统一展示免费 / Pro 状态与权益差异。
- 同批处理快捷键页 UI 问题：锁定功能的操作按钮文字与 Pro 标识必须在同一个按钮里。
- 按用户要求参考 Mindraw 原始来源 `0629-pro-ui`，并让 UI 子 agent 阅读设计经验教训后检查对齐。

## 已完成事项

- 扩展 `ProFeature.customTagColors`，将免费备注额度改为 3，并更新 Pro 提示、卡片、功能列表和 29 语种文案。
- 在标签数据中新增 `TagCustomColor` 和 `TagDef.customColor` 可选字段；旧数据缺字段仍可读取。
- 标签展示链路已传播自定义颜色：AppGrid 分组、标签导航、主界面标签 pill 均优先显示自定义色，回退基础色。
- `TagEditorView` 保留基础色选择，并新增自定义颜色入口：
  - 免费态为带 Pro 胶囊的按钮，只触发 Pro 提示。
  - Pro 态使用 macOS 原生 `ColorPicker` / color well。
  - 切回基础色会清除 `customColor`。
- 备注额度改为免费 3 条：第 1-3 条允许，第 4 条阻止并弹 Pro 提示；编辑已有备注和删除释放额度保留。
- 设置页 Pro 状态 UI 已统一：
  - 快捷键、标签、数据、关于页使用统一状态卡。
  - Pro 态加入页面收益句，例如“可以自定义快捷键 / 可以自定义标签颜色 / 可以备份、导出、导入和恢复分类与布局”。
  - About 页新增“免费版与 Pro 版差异”对比表。
  - Data/About 改为垂直 ScrollView，降低 1000x640 设置窗口截断风险。
- 更新 `CODEGRAPH.md`，补充自定义标签颜色、3 条备注额度、统一 Pro 状态 UI 和新增 QA 脚本。

## 关键决策

- 不新增标签图标、上传图标、标签数量限制、单个 App 标签数限制、SmartStart 默认标签集调整。
- 自定义标签颜色只作为 `TagDef.customColor` 可选字段保存；导入导出沿用标签配置 JSON，自动保留该字段。
- 免费用户已有自定义颜色继续显示；新增或修改自定义颜色必须 Pro；改回基础色允许。
- Data 页可以展示紧凑 Pro 状态概览，但不得放营销式大卡挤压数据管理主内容。

## 文件变更

- 主要源码：
  - `src/Apptag/ProEntitlement.swift`
  - `src/Apptag/ProAccessViews.swift`
  - `src/Apptag/DataLayer.swift`
  - `src/Apptag/TagEditorView.swift`
  - `src/Apptag/ContentView.swift`
  - `src/Apptag/AppGridCollectionView.swift`
  - `src/Apptag/TagNavigationView.swift`
  - `src/Apptag/PreferencesView.swift`
  - `src/Apptag/Localization/*.json`
- QA：
  - `src/Scripts/pro_feature_gate_qa.sh`
  - `src/Scripts/pro_localization_qa.sh`
  - `src/Scripts/pro_tag_custom_color_qa.sh`
  - `src/Scripts/pro_notes_quota_qa.sh`
  - `src/Scripts/pro_custom_hotkeys_qa.sh`
- 文档：
  - `CODEGRAPH.md`

## QA 结论

- 自动化 QA 均通过：
  - `bash Scripts/pro_feature_gate_qa.sh`
  - `bash Scripts/pro_localization_qa.sh`
  - `bash Scripts/pro_tag_custom_color_qa.sh`
  - `bash Scripts/pro_notes_quota_qa.sh`
  - `bash Scripts/theme_settings_qa.sh`
  - `bash Scripts/app_ordering_data_qa.sh`
  - `bash Scripts/pro_custom_hotkeys_qa.sh`
  - `bash build.sh`
- 真实 GUI / AX 验证：
  - 免费态快捷键页：状态卡、待解锁列表、按钮文字与 Pro 胶囊同按钮可见。
  - 免费态标签页：基础色保留，自定义颜色入口为“自定义颜色, Pro”，AX Help 为 Pro 功能说明。
  - 免费态 About 页：有免费 / Pro 差异对比表。
  - Pro 态快捷键页：显示“Pro 已解锁 / 您当前是尊贵的 Pro 用户 / 可以自定义快捷键”，行按钮不再显示 Pro 门禁。
  - Pro 态标签页：自定义颜色入口为系统 color well，AX 暴露 `Show color panel`，验证为原生颜色交互。
  - Pro 态数据页：显示统一状态卡与数据备份能力，页面有垂直滚动容器。
- GUI 颜色测试曾把 `任务与 GTD`、`笔记` 两个标签写入临时 `customColor`；已在退出 App 后精确删除，备份保存在 `/Users/ar/Library/Application Support/TagLauncher/tags.json.codex-backup-20260629-121105.bak`。

## 未决问题与风险

- About 页 Pro 态窗口在最后一次自动化尝试中未能稳定重新打开；免费态 About 对比表和 Pro 态 Hotkeys/Tags/Data 状态卡已实测，About Pro 态由静态代码与本地化 QA 覆盖。
- 全屏坐标截图在当前多窗口/多显示器环境中不稳定，最终 UI 证据以 Computer Use 的实时截图和 AX 树为准。
- 工作区已有大量与本轮无关的 `docs/`、`src/Release/` 删除和未跟踪文档，本轮未回退也未处理。

## 后续建议

- 如进入发布前验收，建议人工再快速看一遍 About 页 Pro 态，重点确认对比表在滚动底部无截断。
- 颜色选择器真实改色建议在隔离的 QA 数据目录执行，避免触碰用户当前 `~/Library/Application Support/TagLauncher/tags.json`。