From d8b67d9510123320c78bf15c26c8a0177848b0b1 Mon Sep 17 00:00:00 2001 From: Ariver <shanghai3168@gmail.com> Date: Sun, 28 Jun 2026 04:42:09 +0800 Subject: [PATCH] Document ASC authentication handoff for 8.1.6 --- CODEGRAPH.md | 27 +++++++++++++++++++++++---- 1 files changed, 23 insertions(+), 4 deletions(-) diff --git a/CODEGRAPH.md b/CODEGRAPH.md index df98068..60ce67c 100644 --- a/CODEGRAPH.md +++ b/CODEGRAPH.md @@ -1,6 +1,6 @@ # TagLauncher CODEGRAPH -最后更新：2026-06-26 +最后更新：2026-06-27 用途：本文件是 TagLauncher 的长期工程地图。修改用户可见行为、状态模型、构建/发布入口、核心源码或 QA 入口前，应先读本文件，再读指向的真实源码。若本文件与源码不一致，以源码为准，并在同一任务内更新本文件。 @@ -19,8 +19,10 @@ - `src/Apptag/ApptagApp.swift` - `TagLauncherApp`：SwiftUI App 入口。 - `AppDelegate`：菜单栏状态项、Dock 显示策略、热键注册、窗口打开、Quick Search 触发、App 生命周期。 + - 支持外部 URL 唤起 `taglauncher://show`：只做 AppGrid show/focus，不做 toggle；冷启动时请求会排队到初始化完成后执行；不接管原生触控板手势。 - 支持从标签导航双击进入设置页的 Tags tab。 - 启动时初始化 `ProEntitlementCenter`，保证免费 / Pro / 老用户自动 Pro 状态进入全局同步快照。 + - 菜单栏下拉菜单包含免费 / Pro 当前身份状态项；免费状态点击进入 About 页的 Pro 卡片，Pro 状态使用金色皇冠图标。 - `src/Apptag/OverlayWindowController.swift` - `OverlayPanel` / `OverlayWindowController`：AppGrid 浮层窗口与显示/隐藏控制。 - `src/Apptag/ContentView.swift` @@ -29,9 +31,12 @@ - 编辑模式使用 runtime theme override：任何主题下进入编辑都临时显示默认浅色毛玻璃。 - 使用最近一次完整 `AppLibrarySnapshot` 先渲染 AppGrid，再后台刷新，避免启动/重开时立刻显示转圈。 - 使用技巧关闭提醒由 `ContentView` 统一弹 modal 并写入 `hideUsageTips` / `skipUsageTipsCloseReminder`。 + - Quick Search 点击 TagLauncher 自身结果时只关闭当前浮层，不走外部自启动，避免 AppGrid 被重新拉起。 - `src/Apptag/PreferencesView.swift` - `PreferencesView`：设置窗口、语言、通用、主题、快捷键、标签、数据、关于等设置页。 - Theme tab 只写视觉偏好 `appGridThemeID`，不得改变标签、排序、备注或分类数据。 + - 免费用户预览 Pro 主题时，Theme tab 状态行和当前预览主题卡片显示基于 `ProThemePreviewState.endsAt` 推导的 `MM:SS` 倒计时；倒计时到期只退出预览，不弹阻塞提示。 + - Pro 升级 / 权益卡位于 About tab；Data tab 只承载分类方案、导入导出和气泡显示位置等数据管理入口。 ## AppGrid 显示与交互 @@ -42,6 +47,7 @@ - `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`。 @@ -51,7 +57,7 @@ - `ProEntitlementPolicy`：数据层可同步调用的 Pro 门禁；覆盖主题、导入 / 导出、备注额度和应用排序持久化。 - `ProEntitlementConfig`：一次性买断商品 ID、免费 + Pro 首个版本、免费主题集合、免费备注额度和 QA 环境变量的单一配置点。 - `src/Apptag/ProAccessViews.swift` - - `ProStatusPill`：高级功能入口的小型 Pro 胶囊。 + - `ProStatusPill`：高级功能入口的小型 Pro 胶囊；Pro / 已锁定高级功能使用金色皇冠体系，免费状态使用中性胶囊。 - `ProUpgradePromptView`：功能被锁时的统一解锁提示，购买 / 恢复动作由调用方闭包绑定。 - `src/Apptag/AppGridSupport.swift` - 图标气泡、基础 metrics、气泡 placement 支撑。 @@ -85,11 +91,14 @@ - `LauncherHotkeyRegistrationStore`：快捷键注册状态持久化。 - `QuickSearchDocument` / `QuickSearchEngine`：搜索索引与排序。 - `QuickSearchPanelPresentationView` / `QuickSearchOverlayView` / `QuickSearchResultListHostView`：Quick Search 浮层 UI 与结果列表。 + - `QuickSearchResultRowView`：结果行内部文字、图标、标签区域统一命中到整行，保证点击任意可见区域都能启动并关闭浮层。 ## 智能分类与 Apple 默认应用资料 - `src/Apptag/SmartCategorization/SmartCategory.swift` - 内置智能分类定义。 + - `SmartCategoryDefaults.orderedIDs` 是 SmartStart 默认初始化标签事实源；当前默认方案为 12 个标签。 + - `SmartCategoryID.smartStartDefaultCategoryID` 负责把旧细分 catalog 分类归并到 12 个默认标签；`Meeting` 归入 `communication`，`finance` 和 `other` 返回 nil，回到未分类；这是新 SmartStart 写入前的归并，不做老用户旧标签自动迁移。 - `src/Apptag/SmartCategorization/SmartCategorizationDraft.swift` - 智能分类草稿、默认备注 provenance、未分配应用和 warning 模型。 - `src/Apptag/SmartCategorization/SmartStartService.swift` @@ -114,7 +123,7 @@ ## 构建与发布 - `src/Apptag/Info.plist` - - App 版本、build、bundle metadata。 + - App 版本、build、bundle metadata；注册公开 URL Scheme `taglauncher`，首期路由只支持 `taglauncher://show`。 - `src/Apptag/TagLauncher.entitlements` - App sandbox / entitlement 配置。 - `src/build.sh` @@ -140,6 +149,8 @@ - SmartStart catalog 资源检查。 - `src/Scripts/smart_category_localization_qa.sh` - SmartCategory/default system tag 初始化标签 29 语种本地化检查；禁止非英文语言包直接复制英文标签，保留 `PDF`、`DevOps` 等技术通用词例外。 +- `src/Scripts/smartstart_default_categories_qa.sh` + - SmartStart 默认初始化标签检查；验证 12 个默认分类、catalog 分类归并入口、`Meeting` 归入 `communication`、`finance` / `other` 回未分类、首次 starter tags 和关键多语言目标文案。 - `src/Scripts/quick_search_app_name_qa.sh` - Quick Search 应用显示名回归。 - `src/Scripts/quick_search_system_app_qa.sh` @@ -154,14 +165,18 @@ - Pro 文案 29 语种静态门禁；检查 `pro.*` 键完整、占位符完整、无生成污染和非英文语言无英文兜底复制。 - `src/Scripts/pro_feature_gate_qa.sh` - Pro 功能源码门禁；检查 StoreKit 权益、老用户自动 Pro、主题门禁、导入导出硬拦截、备注额度、排序预览和 Pro UI 提示。 +- `src/Scripts/pro_theme_preview_countdown_qa.sh` + - Pro 主题预览倒计时门禁；检查状态行倒计时、当前预览卡片 `MM:SS`、到期清理、29 语种 `%time%` 占位符和禁止写死体验时长。 - `src/Scripts/appgrid_startup_loading_qa.sh` - AppGrid 快照复用和延迟转圈回归。 +- `src/Scripts/url_scheme_activation_qa.sh` + - 外部 URL 唤起门禁；检查 `taglauncher://show` 注册、AppDelegate show/focus 语义、冷启动 pending、29 语种设置文案和禁止私有触控板捕获。 - `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/菜单栏相关逻辑回归。 + - 窗口层级、显示隐藏、Dock/菜单栏相关逻辑回归；Dock 项断言按当前 QA 构建路径过滤，避免本机固定正式版 App 时误判重复图标。 - `src/Scripts/app_ordering_data_qa.sh` - App 排序数据持久化回归。 @@ -171,6 +186,7 @@ - 不得把主题、视觉偏好、窗口状态混入 `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。 @@ -180,6 +196,8 @@ - 旧用户 `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 必须保持受控自动滚动；长按排序必须保留；双击可以打开标签设置页但不得替代前三者。 @@ -200,3 +218,4 @@ - 改 `DataLayer.swift` 通常会影响应用扫描、显示名、标签数据、导入导出和迁移，必须补数据 QA。 - 改 `PreferencesView.swift` 通常需要检查 29 个本地化 JSON、设置持久化和 macOS 14 UI 表现。 - 改 `ApptagApp.swift` 或 `OverlayWindowController.swift` 必须回归菜单栏、Dock 图标策略、热键、窗口层级、全屏/Split View 行为。 +- 改外部 URL 唤起、`Info.plist` URL Scheme 或第三方手势说明时，必须运行 `url_scheme_activation_qa.sh`，并确认不新增 Accessibility/Input Monitoring/private multitouch 依赖。 -- Gitblit v1.9.3