Simplify SmartStart default categories

Ariver

2026-06-27 28be00ea53666fd5500a702a3c187c0e27dd90ad

 CODEGRAPH.md

@@ -1,65 +1,214 @@
# CODEGRAPH
# TagLauncher CODEGRAPH

## Stable Modules
最后更新：2026-06-27

- App entry and overlay state: `src/Apptag/ContentView.swift`
  - Reads user defaults for AppGrid display, theme, tag navigation, usage tips, and hotkeys.
  - Owns the AppGrid full-window background rendering.
  - Reuses the last complete AppLibrary snapshot before showing startup loading UI.
  - Calls `AppGridCollectionView` for AppKit grid rendering.
用途：本文件是 TagLauncher 的长期工程地图。修改用户可见行为、状态模型、构建/发布入口、核心源码或 QA 入口前，应先读本文件，再读指向的真实源码。若本文件与源码不一致，以源码为准，并在同一任务内更新本文件。

- App library snapshot assembly: `src/Apptag/AppLibraryController.swift`
  - Scans apps, reconciles tags, runs SmartStart when needed, and assembles AppGrid/Quick Search snapshots.
  - Keeps the most recent in-process `AppLibrarySnapshot` so newly-created overlay views can render immediately while background refresh catches up.
## 项目边界

- AppGrid collection renderer: `src/Apptag/AppGridCollectionView.swift`
  - AppKit `NSCollectionView` implementation for grouped app layout, drag/drop, app ordering, bubbles, and usage tips overlay.
  - Should not own full-screen AppGrid theme gradients; it receives theme only for derived glass readability.
- 仓库根目录：`/Users/ar/Projects/Taglauncher`
- 唯一源码根目录：`/Users/ar/Projects/Taglauncher/src`
- macOS App 源码：`src/Apptag/`
- 构建入口：`src/build.sh`
- DMG 打包入口：`src/make_dmg.sh`
- 发布资料：`src/Release/`
- QA 脚本：`src/Scripts/`

- AppGrid theme model: `src/Apptag/AppGridTheme.swift`
  - Central source for theme IDs, localization keys, preview swatches, full-screen background gradients, derived glass tone, and edit-mode contrast tokens.
  - Persistent key: `appGridThemeID`.
## 核心入口

- Settings surface: `src/Apptag/PreferencesView.swift`
  - Custom SwiftUI settings tabs.
  - Theme tab writes only `appGridThemeID`; it must not mutate tags, app ordering, or category data.
  - Can be opened with an initial target tab from AppKit/overlay notifications.
- `src/Apptag/ApptagApp.swift`
  - `TagLauncherApp`：SwiftUI App 入口。
  - `AppDelegate`：菜单栏状态项、Dock 显示策略、热键注册、窗口打开、Quick Search 触发、App 生命周期。
  - 支持从标签导航双击进入设置页的 Tags tab。
  - 启动时初始化 `ProEntitlementCenter`，保证免费 / Pro / 老用户自动 Pro 状态进入全局同步快照。
  - 菜单栏下拉菜单包含免费 / Pro 当前身份状态项；免费状态点击进入 About 页的 Pro 卡片，Pro 状态使用金色皇冠图标。
- `src/Apptag/OverlayWindowController.swift`
  - `OverlayPanel` / `OverlayWindowController`：AppGrid 浮层窗口与显示/隐藏控制。
- `src/Apptag/ContentView.swift`
  - `ContentView`：AppGrid 主界面、标签导航、编辑模式、拖拽处理、Quick Search 数据刷新、使用技巧浮层入口。
  - 读取 `appGridThemeID` 并负责 AppGrid 全屏主题背景渲染。
  - 编辑模式使用 runtime theme override：任何主题下进入编辑都临时显示默认浅色毛玻璃。
  - 使用最近一次完整 `AppLibrarySnapshot` 先渲染 AppGrid，再后台刷新，避免启动/重开时立刻显示转圈。
  - 使用技巧关闭提醒由 `ContentView` 统一弹 modal 并写入 `hideUsageTips` / `skipUsageTipsCloseReminder`。
  - Quick Search 点击 TagLauncher 自身结果时只关闭当前浮层，不走外部自启动，避免 AppGrid 被重新拉起。
- `src/Apptag/PreferencesView.swift`
  - `PreferencesView`：设置窗口、语言、通用、主题、快捷键、标签、数据、关于等设置页。
  - Theme tab 只写视觉偏好 `appGridThemeID`，不得改变标签、排序、备注或分类数据。
  - Pro 升级 / 权益卡位于 About tab；Data tab 只承载分类方案、导入导出和气泡显示位置等数据管理入口。

- Defaults and migrations: `src/Apptag/AppDefaults.swift`
  - Registers first-run defaults.
  - Migrates legacy `useDarkAppGrid=true` to `appGridThemeID=deepBlue` when no new theme key exists.
## AppGrid 显示与交互

- Localization: `src/Apptag/Localization/*.json`
  - 29 language JSON files.
  - New user-visible settings keys must be present in all files.
- `src/Apptag/AppGridCollectionView.swift`
  - `AppGridCollectionView`：SwiftUI 到 AppKit `NSCollectionView` 的桥接。
  - `AppGridCollectionHostView`：滚动容器、背景/使用技巧层、空白拖放处理。
  - `AppGridGroupCollectionItem` / `AppGridGroupCardView`：分组容器、图标布局、分组标题、hover/高亮、容器内拖放。
  - `AppGridIconNSView`：应用图标单元、点击、hover 气泡、拖拽起点。
  - 底部使用技巧是原生 AppKit overlay，不允许改成 SwiftUI；必须拦截自身点击区域。
  - 不拥有 AppGrid 全屏渐变背景，只接收 theme 推导出的玻璃和文本可读性 token。
  - 样式 2 / 样式 3 的瀑布流容器布局会把未分类和 Mac 自带作为底部特殊容器：未分类倒数第二、Mac 自带最后，二者横向占满；普通列末尾会补齐到特殊容器上沿，避免底部参差空隙。
- `src/Apptag/AppGridTheme.swift`
  - AppGrid 主题事实源：theme id、localization key、设置页 swatch、全屏渐变背景、玻璃明暗、编辑模式 token。
  - 持久化 key：`appGridThemeID`。
  - 主题是否需要 Pro 只通过 `ProEntitlementConfig.freeThemes` 判断，不在主题 UI 中散落规则。
- `src/Apptag/ProEntitlement.swift`
  - `ProEntitlementCenter`：StoreKit 2 当前权益、购买、恢复、交易更新、离线缓存和 QA 状态注入。
  - `ProEntitlementPolicy`：数据层可同步调用的 Pro 门禁；覆盖主题、导入 / 导出、备注额度和应用排序持久化。
  - `ProEntitlementConfig`：一次性买断商品 ID、免费 + Pro 首个版本、免费主题集合、免费备注额度和 QA 环境变量的单一配置点。
- `src/Apptag/ProAccessViews.swift`
  - `ProStatusPill`：高级功能入口的小型 Pro 胶囊；Pro / 已锁定高级功能使用金色皇冠体系，免费状态使用中性胶囊。
  - `ProUpgradePromptView`：功能被锁时的统一解锁提示，购买 / 恢复动作由调用方闭包绑定。
- `src/Apptag/AppGridSupport.swift`
  - 图标气泡、基础 metrics、气泡 placement 支撑。
- `src/Apptag/TagNavigationView.swift`
  - AppKit 标签导航栏，支持标签 hover 滚动、选中、拖放、双击进入标签设置页。
- `src/Apptag/AppDragCoordinator.swift`
  - 全局拖拽目标注册、命中判断、容器间拖放、容器外空白移除标签。
  - 拖到容器外/容器之间空白区域时显示 Core Animation 碎纸预览；容器内部空白不触发解除标签预览。

## QA Entrypoints
## 数据层

- `src/Scripts/theme_settings_qa.sh`
  - Verifies 8 theme cases, Theme tab, legacy dark-grid UI removal, AppGrid-only rendering boundary, edit-mode default-theme override, migration path, and 29-language keys.
- `src/Scripts/appgrid_startup_loading_qa.sh`
  - Verifies AppGrid startup loading uses last-snapshot reuse and delayed spinner instead of immediately exposing empty-state loading.
- `src/Apptag/DataLayer.swift`
  - `AppInfo`：应用模型。
  - `AppDisplayNameResolver`：多语言应用显示名解析。
  - `AppIndexer`：扫描 `/Applications` 等应用来源，处理 bundle / wrapper / localized display name。
  - `TagGroup` / `TagColor`：标签分组与颜色。
  - `TagDatabase`：标签、备注、隐藏状态、分类方案、导入导出、备份和持久化。
  - `TagEditor`：把数据库中的标签/备注/隐藏状态标注回扫描到的 App 列表。
- `src/Apptag/AppLibraryController.swift`
  - App 刷新、SmartStart 应用、系统分类方案应用、重置未分类等业务入口。
  - 持有最近一次完整 `AppLibrarySnapshot`，供新建 overlay 立即复用。
- `src/Apptag/AppDefaults.swift`
  - UserDefaults 默认值注册与 schema 默认处理。
  - 旧 `useDarkAppGrid=true` 在没有新 theme key 时迁移到 `appGridThemeID=deepBlue`。
  - `hideUsageTips` 默认 `false`；`skipUsageTipsCloseReminder` 默认 `false`。

## Quick Search 与快捷键

- `src/Apptag/QuickSearch.swift`
  - `LauncherHotkey` / `LauncherHotkeyKind`：主面板和 Quick Search 快捷键定义。
  - `LauncherHotkeyRegistrationStore`：快捷键注册状态持久化。
  - `QuickSearchDocument` / `QuickSearchEngine`：搜索索引与排序。
  - `QuickSearchPanelPresentationView` / `QuickSearchOverlayView` / `QuickSearchResultListHostView`：Quick Search 浮层 UI 与结果列表。
  - `QuickSearchResultRowView`：结果行内部文字、图标、标签区域统一命中到整行，保证点击任意可见区域都能启动并关闭浮层。

## 智能分类与 Apple 默认应用资料

- `src/Apptag/SmartCategorization/SmartCategory.swift`
  - 内置智能分类定义。
  - `SmartCategoryDefaults.orderedIDs` 是 SmartStart 默认初始化标签事实源；当前默认方案为 15 个标签。
  - `SmartCategoryID.smartStartDefaultCategoryID` 负责把旧细分 catalog 分类归并到 15 个默认标签；这是新 SmartStart 写入前的归并，不做老用户旧标签自动迁移。
- `src/Apptag/SmartCategorization/SmartCategorizationDraft.swift`
  - 智能分类草稿、默认备注 provenance、未分配应用和 warning 模型。
- `src/Apptag/SmartCategorization/SmartStartService.swift`
  - SmartStart 初始化、catalog/notes 快照加载、分类结果生成。
- `src/Apptag/AppleDefaultAppCatalog.swift`
  - Apple 自带应用分类和本地化备注 catalog 加载。
- `src/Apptag/SmartStartNoticeOverlay.swift`
  - 首次智能整理提示弹窗。

## 本地化与文档

- `src/Apptag/L10n.swift`
  - 语言选择、translation JSON 加载、帮助文档入口。
- `src/Apptag/Localization/*.json`
  - App UI 本地化文案。新增用户可见文案时必须覆盖全部 29 个语言文件，并验证 JSON 合法。
  - `smart.category.*` 是 SmartStart/default system tag 的显示事实源；非英文语言不得直接复制英文初始化标签。
- `src/Apptag/Resources/`
  - SmartStart、Apple default catalog、帮助文档等运行时资源。
- `src/Docs/Requirements/`
  - 需求 todo、工作日志、QA 记录和重要实现结论。

## 构建与发布

- `src/Apptag/Info.plist`
  - App 版本、build、bundle metadata。
- `src/Apptag/TagLauncher.entitlements`
  - App sandbox / entitlement 配置。
- `src/build.sh`
  - 构建 `.app` 的主入口。
- `src/make_dmg.sh`
  - 生成 DMG 的主入口。
- `src/Release/`
  - 发布归档、App Store Connect metadata、审核说明、QA 证据。

## 主要 QA 入口

- `src/Scripts/macos14_availability_typecheck_qa.sh`
  - Typechecks for macOS 14.0 compatibility.
  - macOS 14 API 可用性/typecheck 检查。
- `src/Scripts/macos14_build_metadata_qa.sh`
  - Verifies build metadata and deployment target.
- `src/Scripts/usage_tips_qa.sh`
  - Verifies usage tips overlay and 29-language coverage.
  - build metadata 检查。
- `src/Scripts/apple_default_apps_resource_qa.sh`
  - Apple 默认应用 catalog 资源检查。
- `src/Scripts/apple_default_note_policy_qa.sh`
  - Apple 默认备注语言/策略检查。
- `src/Scripts/apple_default_note_migration_qa.sh`
  - Apple 默认备注迁移检查。
- `src/Scripts/smartstart_catalog_resource_qa.sh`
  - SmartStart catalog 资源检查。
- `src/Scripts/smart_category_localization_qa.sh`
  - SmartCategory/default system tag 初始化标签 29 语种本地化检查；禁止非英文语言包直接复制英文标签，保留 `PDF`、`DevOps` 等技术通用词例外。
- `src/Scripts/smartstart_default_categories_qa.sh`
  - SmartStart 默认初始化标签检查；验证 15 个默认分类、catalog 分类归并入口、首次 starter tags 和关键多语言目标文案。
- `src/Scripts/quick_search_app_name_qa.sh`
  - Quick Search 应用显示名回归。
- `src/Scripts/quick_search_system_app_qa.sh`
  - Quick Search 系统应用回归。
- `src/Scripts/tag_navigation_hover_scroll_qa.sh`
  - Verifies tag hover scroll semantics remain guarded.
  - 标签导航 hover 滚动回归。
- `src/Scripts/tag_double_click_preferences_qa.sh`
  - Verifies double-clicking a tag navigation item opens Preferences on the Tags tab while preserving single-click activation, hover scroll, and long-press reorder wiring.
  - 标签双击进入标签设置页回归。
- `src/Scripts/theme_settings_qa.sh`
  - 8 个主题、Theme tab、旧深色偏好迁移、编辑模式默认浅色 override、29 语种主题文案回归。
- `src/Scripts/pro_localization_qa.sh`
  - Pro 文案 29 语种静态门禁；检查 `pro.*` 键完整、占位符完整、无生成污染和非英文语言无英文兜底复制。
- `src/Scripts/pro_feature_gate_qa.sh`
  - Pro 功能源码门禁；检查 StoreKit 权益、老用户自动 Pro、主题门禁、导入导出硬拦截、备注额度、排序预览和 Pro UI 提示。
- `src/Scripts/appgrid_startup_loading_qa.sh`
  - AppGrid 快照复用和延迟转圈回归。
- `src/Scripts/usage_tips_qa.sh`
  - AppGrid 使用技巧 AppKit 横幅、主题可读性、防穿透、关闭按钮、29 语种文案回归。
- `src/Scripts/usage_tips_close_reminder_qa.sh`
  - 使用技巧关闭提醒、modal 防穿透、设置页预览、29 语种文案回归。
- `src/Scripts/window_logic_qa.sh`
  - 窗口层级、显示隐藏、Dock/菜单栏相关逻辑回归。
- `src/Scripts/app_ordering_data_qa.sh`
  - App 排序数据持久化回归。

## Protected Behavior
## 受保护行为

- Theme changes are visual preferences and must not change tag data, app ordering, notes, SmartStart/category scheme, quick search, drag/drop behavior, or import/export data.
- AppGrid startup and repeated overlay creation must not immediately show a spinner just because a new `ContentView` starts with `allApps.isEmpty`; it should first reuse the last complete in-process snapshot and only show loading after a short delay if no snapshot is available.
- Editing mode uses a temporary runtime theme override: regardless of the stored `appGridThemeID`, editing renders as the default light glass AppGrid and restores the stored theme when edit mode exits.
- Individual AppGrid containers must remain a consistent translucent glass surface. They may use a derived light/dark glass tone for readability, but must not receive per-theme internal gradients.
- Edit mode controls must use the runtime rendered theme, not the stored theme, so editing stays visually identical to the default light AppGrid.
- Deep Blue and Black use dark glass. Bright Pink, Purple, Green, Blue, and Colorful themes use light glass to keep the theme bright and readable.
- The default theme preserves the original light AppGrid background.
- Legacy users with `useDarkAppGrid=true` must land on the `deepBlue` theme.
- Tag navigation single-click must keep immediate scroll behavior. Hover must keep guarded auto-scroll. Long-press must keep tag reorder behavior. Double-click may open Preferences on the Tags tab but must not replace those existing behaviors.
- 不得擅自改变源码根目录边界：App 源码只在 `src/` 下维护。
- 不得把主题、视觉偏好、窗口状态混入 `TagDatabase` 的分类/标签业务数据。
- 主题变化只允许影响 AppGrid 视觉，不得改变标签数据、排序、备注、SmartStart/category scheme、Quick Search、拖拽语义或导入导出。
- Pro 门禁不得写脏免费用户真实数据：主题预览不写 `appGridThemeID`，排序预览不写 `containerAppOrder`，第 6 个新备注不写 `appNotes` / `appNoteMetadata`，导入 / 导出拦截必须早于文件面板和文件读写。
- Pro 升级 / 权益卡应放在 About tab；Data tab 不承载 Pro 营销卡，避免挤压数据管理布局。
- 免费主题固定为默认、深蓝、黑色；其它主题只能预览或在 Pro 解锁后持久化。
- `originalAppVersion` 早于免费 + Pro 首个版本的历史用户必须自动获得 Pro；`originalPurchaseDate` 只能作为版本不可判断时的兜底。
- 默认主题必须保留原浅色毛玻璃 AppGrid。
- 黑色主题背景必须为 100% 纯黑；深蓝和黑色使用深色玻璃；粉色、紫色、绿色、蓝色、炫彩使用浅色玻璃以保证明亮和可读。
- 单个 AppGrid 容器保持统一半透明玻璃面板，不做容器内部渐变。
- 编辑模式无论当前主题是什么，都临时渲染为默认浅色毛玻璃，退出编辑后恢复用户主题。
- 旧用户 `useDarkAppGrid=true` 必须迁移到 `deepBlue` 主题。
- AppGrid 启动或重开不应因为新 `ContentView` 初始 `allApps.isEmpty` 立刻显示转圈；应先复用最近一次完整快照，并延迟显示 loading。
- Quick Search 显示标题应优先使用解析后的 `AppInfo.displayName`，内部 bundle 名只作为搜索字段。
- Quick Search 结果行内部文字 / 图标区域不得吞掉点击；点中行内任意可见区域都应按结果启动路径处理。
- Quick Search-only 点击 TagLauncher 自身结果必须关闭浮层，不得重新打开 AppGrid。
- Apple 默认应用备注必须按当前语言显示，不允许 A 语言出现 B 语言备注。
- SmartStart/default system tag 初始化标签必须按当前语言显示；升级用户启动后应重刷带 `systemCategoryID` 的系统标签，不能长期保留旧英文初始化标签。
- 标签导航单击必须立即滚动；hover 必须保持受控自动滚动；长按排序必须保留；双击可以打开标签设置页但不得替代前三者。
- 容器外空白拖放才可触发解除标签；容器内部空白不算解除标签。
- 拖到解除标签区域的碎纸预览只能是视觉反馈，不能跳过放手后的原确认流程。
- AppGrid 使用技巧浮层必须拦截自身点击，不能穿透到底层应用图标，也不能导致 AppGrid 消失。
- 使用技巧必须保持原生 AppKit overlay，不改为 SwiftUI；只有箭头 hit 区域能翻页。
- 使用技巧标题/正文在默认、深色、亮色主题下都必须可读，且 29 语种文案完整。
- 关闭使用技巧时应先显示提醒；确认后才写入隐藏状态；“不再提醒”只在用户明确勾选并确认后生效。
- 设置页应避免依赖不同 macOS 版本表现不一致的 SwiftUI 默认 TabView 外观。
- macOS 14 兼容是当前发布目标之一，新增 API 或 UI 技术选择必须考虑 macOS 14。

Last updated: 2026-06-24, tag double-click opens Tags settings.
## 修改提醒

- 改 `ContentView.swift` 通常会影响 AppGrid 主流程、编辑模式、Quick Search 数据刷新或浮层层级，必须做对应 smoke。
- 改 `AppGridCollectionView.swift` 通常会影响 AppGrid 布局、拖拽、hover、使用技巧、容器显示和性能，必须扩大视觉/交互回归。
- 改 `AppGridTheme.swift` 必须验证全部主题、编辑模式 override、亮/暗玻璃可读性和设置页文案。
- 改 `DataLayer.swift` 通常会影响应用扫描、显示名、标签数据、导入导出和迁移，必须补数据 QA。
- 改 `PreferencesView.swift` 通常需要检查 29 个本地化 JSON、设置持久化和 macOS 14 UI 表现。
- 改 `ApptagApp.swift` 或 `OverlayWindowController.swift` 必须回归菜单栏、Dock 图标策略、热键、窗口层级、全屏/Split View 行为。