--- description: Figma、飞书产品文档与 current-main iOS 代码的 revision-aware 同源、漂移和待确认项 status: request_changes updated: 2026-08-28 sources: - figma://UR45i9TtpX95auUs46rsHL/2391:25876 - feishu://wiki/OPTZwOQC7ilug3klEPtca8Drnfs - repo://ailoha-agent-iOS@5e6ac6e41c53780c85808c92290d2bd38f809123 - repo://ailoha-agent-iOS@6922f359ad08da70242e4ec0c5c4a1486bc2908d - repo://ailoha-brain/reports/ios-frontend-refactor-map/evidence/current-main-product-design-alignment-2026-08-28/product-design-alignment-audit.json - https://app.notion.com/p/3caa444a6c0081d987a0dc871c7e5688 confidence: medium-high sensitivity: internal --- # 产品 / 设计 / 代码对齐 ## 先纠正一条会误导重构的旧判断 本页此前把历史/Release 的 Chat 双轨写成了 current main 事实。2026-08-28 的 revision-bound 审计已纠正： - **fact / current main：** `Router` 只构造 `TaskChatPageV2`；`TaskChatPage.swift` 与 `ChatPageDebugFlags.swift` 在 `main@6922f359` 已不存在；启动时还会删除旧 rollout cache。current main 不是“V1/V2 双跑、默认 V1”。 - **fact / current main：** 底部导航只有 `todo / contact / calendar` 三项；`discover` 仍保留在 Router 与主壳 switch 中，但不是可见 tab。 - **fact / current main：** Onboarding 是 12 个可恢复 route 的完整流程，包含姓名、权限、Google Calendar、Action Button、Shortcuts、Try It 与终章；只是旧 questionnaire 的可见输入已经收缩为 `nameSetup`，动态问卷 renderer 不存在。 - **fact / current main：** design-token manifest → generated Swift → Widget consumer 的链已经成立；同时 `ALHColors.primaryAccent` 仍维护 light/dark 自适应色，迁移只完成一部分。 - **unknown / Figma：** 2026-08-28 再次 fresh read 时仍被 Professional View-seat MCP 调用额度阻断。节点 `2391:25876` 只能叫 2026-08-11 已观察的历史视觉证据，不能叫 current target。 机器收据：[product-design-alignment-audit.json](evidence/current-main-product-design-alignment-2026-08-28/product-design-alignment-audit.json)。它只证明所列 current-main 代码事实，不证明当前设计正确、用户喜欢或目标方案已经接受。 给另一台电脑或新 Agent 的冷读、实施与验收入口：[Ailoha iOS｜current main × Figma × 重构验收控制面](https://app.notion.com/p/3caa444a6c0081d987a0dc871c7e5688)。 ## 判断口径 - Figma 决定当前可见节点的视觉事实，不决定完整业务状态机。 - 飞书决定文档中的产品/协作意图，但 2026-06-22 之后的代码可推翻实现事实。 - 运行代码决定当前客户端行为；代码中的 dormant flag/TODO 不自动等于产品承诺。 - 用户意图以 Ailoha 核心循环约束：首轮先产生深度价值，外部动作可见、可确认、可恢复。 ## 对齐矩阵 | Surface | Figma / 飞书意图 | 当前代码事实 | 状态 | 决策含义 | |---|---|---|---|---| | Onboarding questionnaire | 2026-08-11 历史 Figma 节点：dark 393×852、Lora 24 标题、Manrope 按钮、5 选项、disabled Continue、24pt inset；2026-08-28 fresh read 再次受 View-seat MCP 调用额度限制，生命周期未知 | current main 有 12-route Onboarding；旧 questionnaire 的可见输入只剩 `nameSetup`，但 coordinator 仍加载三题 fallback、只积累 `fullName` 并用该 config version 提交 | `runtime/config-drift/fact + production/design-lifecycle/unknown` | 先用 DEV 请求裁决服务端；姓名输入采用独立 name-only contract 或恢复真实可见问卷。design owner 再标记历史节点 current/dormant/superseded；详见 [Onboarding 设计合同调查](current-main-onboarding-design-contract-gap-2026-08-28.md) | | Onboarding value | 产品目标是首轮展示深度价值 | Try It 用本地常量模拟消息、Dynamic Island、联系人和日历结果，不触发真实后端能力 | `gap/fact` | 模拟教学与能力验证要分轨；至少明确“演示”并在稍后提供低风险真实闭环 | | Home IA | 飞书 Home 文档描述 5 tabs/Discover | current main 的 visible bottom nav 精确为 Task / Contact / Calendar；Discover route 仍能被 Router/主壳表示，但没有 visible tab consumer | `drift/fact` | 先确认三 Tab 是正式信息架构还是阶段收缩；若正式，给 Discover route 明确 deep-link-only 用途或删除条件 | | Chat renderer | 飞书只描述 V1 `ScrollView + LazyVStack` | current main 只构造 `TaskChatPageV2`；旧页与 debug flag 文件已删除，旧 rollout cache 启动即清 | `doc-stale/main-closed/fact` | 不再设计 V1/V2 双跑；更新飞书 successor，并用 Release 集成状态、V2 长会话性能与回归证据关闭迁移 | | Task state | 飞书称 TaskStateManager 是 single source | HomeViewModel 另持 REST pagination/category/optimistic task list state | `partial/fact` | 重构目标应是 canonical repository + query projections，不是给现状换名 | | Calendar truth | 飞书称后端权威、EventKit 镜像 | `ExternalCalendarSyncService` 基本遵守；UI 仍有独立五分钟 cache 与 editor state | `aligned-with-gap` | 保留后端权威不变量，同时明确 UI cache invalidation/account scope | | Contact | 飞书描述列表、详情、cluster 与事件/任务关系 | ContactManager 实际承载这些能力并加 ARPC merge/cache/search/edit | `aligned-but-concentrated` | 不是删功能，而是拆 canonical entity、query/session 和 effects | | Screenshot/Live Activity | 文档描述跨进程截图、任务创建、卡片动作 | current main 有 task-bound activity、精确 end 与 pending-end 等支点；同时允许多张非终态卡、只注册一组 activity id/update token，并由 Widget 直接选择 21 个 rich field 的显示 | `aligned-with-product-policy-gap` | 先由产品选择单卡/多卡、D0–D4 披露和直接动作边界，再实现 versioned state、identity、ordering 与 recovery；见[共同决策包](current-main-live-activity-product-policy-decisions-2026-08-28.md) | | Theme | Figma/current UI 明显暗色 | ThemeManager 保存 system/light/dark preference，但 `currentColorScheme` 固定返回 dark | `contract-mismatch/fact` | 如果产品确定 dark-only，应删除无效选项；若支持主题，则实现并测试，而非保留伪设置 | | Design tokens | 历史 Figma 节点使用 `#C8F04A`；设计生命周期未知 | current main manifest 已把 `#C8F04A / #D6FE51 / #00C8B3` 命名为 `accent / brightAccent / tealAccent`，生成 Swift 且 Widget 已消费；`ALHColors.primaryAccent` 的自适应 light/dark 定义仍并存 | `generated-chain-established + migration-partial/fact` | 保留三个语义角色，不机械合并；建立剩余 consumer 迁移/删除账本和 App/Widget 视觉回归后再关闭 legacy adaptive path | ## Figma → SwiftUI 映射判断 只有 design owner 明确确认历史问卷节点仍是 current target 时，才应按下面的 SwiftUI 语义实现；在此之前，这张表是**映射候选**，不是实现授权： | Figma signal | Idiomatic SwiftUI | 当前审计重点 | |---|---|---| | 线性 Onboarding flow | reducer-driven `NavigationStack` / root gate | route owner 是否唯一、resume 是否可恢复 | | 五个互斥选项 | enum selection +语义 `Button`/`Picker` | selected trait、VoiceOver label、disabled reason | | Continue disabled | `Button` + `.disabled(selection == nil)` | 不能只靠颜色表达 disabled | | Lora/Manrope custom fonts | `.custom(size:relativeTo:)` 或由设计确认换系统字体 | 先确认字体仍属于 current target，再以最大 Dynamic Type 与裁切截图验收 | | brand accent | semantic asset/token | 不能在每个 view 重复 raw hex | | 24pt horizontal inset | adaptive layout/系统容器后再校准 | 不复制绝对 position/offset | `inference`：当前问题不是缺少像素还原能力，而是缺少 Figma variable/component → Swift token/component → accessibility/test 的可追踪合同。发布组件搜索为空只能说明当前公开搜索没有资产，不能证明 Figma 文件内部不存在本地变量或组件。 ## 当前文档 freshness 问题 1. 飞书 iOS index 与十个子文档都停在 2026-06-22，而 current main 已是 12-route Onboarding、V2-only Chat、三 Tab、生成 token 链与新的 Live Activity 支点；Figma 问卷节点的设计生命周期尚未确认。 2. 旧版文档仍保留完整正文，缺少 `superseded_by`、适用 commit/build 与生效日期。 3. `【ios】架构重构调整` 实际正文是 Agent/backend 架构，标题会让搜索与新人 onboarding 误路由。 4. Figma 节点没有与飞书 successor、current-main commit 和 release build 建立 revision tuple；Chat 的旧 feature flag 已从 main 删除，不能再拿它当 current tuple 成员。 ## 2026-08-28 current-main 补充：页面、配置和提交合同也必须同源 视觉 revision tuple 只回答“应该长什么样”，还不够。Onboarding 这次出现的是更隐蔽的漂移：页面已经迁到 Setup 2.0，旧问卷配置和提交 version 仍是运行 authority。以后每个可配置流程还要固定： ```text surface_id visible_steps + rendered fields config/schema version + required fields authoritative prefill / explicit skip rules submission endpoint + payload field names accepted next state + recoverable error state ``` 自动 guard 的最小不变量是：每个 required field 必须被页面渲染、由可信来源预填、明确允许跳过，或从提交 schema 删除。截图验收同时覆盖 ready、去敏请求、成功 next state 与 validation recovery，不只覆盖像素。 ## 建议的同源合同 每个长期 surface 建立一条轻量 revision tuple： ```text surface_id product_doc: feishu node + edited_at + successor design: figma file/node + design version/status implementation: repo + commit + feature flag verification: test/visual/a11y evidence + observed_at owner + next_review_at ``` 只有稳定输入输出、重复 drift 和明确 owner 后才自动化。建议先在 Onboarding、Task Chat、Bottom Nav、Design Tokens 四个高漂移 surface 试点，不全量迁移历史文档。 ## 需要人工确认的问题 1. 产品是否正式选择三 Tab，并准备删除/归档 Discover？ 2. Try It 的目标是“教学演示”还是“第一次真实价值验证”？两者的成功指标不同。 3. App 是 dark-only 还是应支持 system/light？当前设置与运行行为相互矛盾。 4. `#C8F04A`、`#D6FE51`、`#00C8B3` 分别是什么语义角色，而不是“哪一个是正确绿色”？ 5. 谁负责把飞书 Chat 文档升级为 V2-only successor，并用哪条 Release/运行证据关闭旧 V1 说明？ 6. Figma 问卷节点是 current、dormant 还是 superseded；若已替代，successor file/node 是什么？