mindfulness/spec_kit/iPad Adaptation/spec.md

iPad Adaptation Spec

Background

当前应用主要按 iPhone 体验实现，iPad 上存在以下问题：

• 页面布局在竖屏/横屏或不同窗口尺寸下出现留黑边、内容拥挤、元素比例失衡。
• 各页面对 iPad 的适配策略不统一，样式行为不可预测。
• iOS Widget 在 iPad 场景下缺少完整的尺寸与排版一致性规范。

本需求定义“全应用 iPad 适配”高层规范，覆盖客户端全部页面与 iOS 小组件，确保不回归现有 iPhone 体验。

Goals

1. 为客户端所有页面建立统一的 iPad 适配规范（优先竖屏，兼容 iPad 常见窗口模式）。
2. 完成全部页面在 iPad 下的布局、间距、字号、交互可用性优化。
3. 完成 iOS Widget 在 iPad 相关尺寸上的视觉与信息层级适配。
4. 明确“iPad 适配不影响 iPhone”的约束、验收与回归策略。

Non-Goals

• 不重做品牌视觉与核心交互流程。
• 不引入与 iPad 适配无关的新业务功能。
• 不调整后端接口契约（除非为 Widget 展示字段做最小兼容补充）。

Scope

In Scope

• client/app/ 下所有用户可见页面（启动、协议、onboarding、home、modal、not-found 等）。
• 共享组件与页面级组件在 iPad 场景下的布局策略（容器宽度、断点、字号、触控面积、safe area 处理）。
• iPad 竖屏主流程视觉一致性与可用性。
• iOS Widget（小/中/大尺寸）在 iPad 的展示、文本截断、间距与点击目标。
• iPad 相关工程配置核查（如设备家族支持、方向策略与运行模式）。

Out of Scope

• Android 平板专项适配。
• Web 端平板适配。
• 新增 widget 类型或新增推荐策略。

Core Requirements

R1. 统一适配基线

• 定义 iPad 判定与布局断点策略，避免各页面各自实现。
• 页面默认使用“内容最大宽度 + 居中 + 弹性留白”模式，不出现视觉黑边误判。
• 明确安全区、状态栏、底部操作区在 iPad 下的通用规则。

R2. 页面逐页适配

• 按页面清单逐页交付，单页可独立验收。
• 每页适配需覆盖：首屏构图、正文可读性、底部操作区、长文案换行与触控可用性。
• 已完成页面进入“冻结状态”，未经确认不回改。

R3. iPhone 零回归

• 所有 iPad 样式调整必须使用条件分支或断点方案，不修改 iPhone 基线参数。
• 每次页面适配后执行 iPhone 快速回归（关键路径与关键组件）。

R4. iOS Widget 适配

• 覆盖 iPad 下 widget 尺寸与展示密度差异，保证文本与图形不溢出、不遮挡。
• 小组件与主 App 的主题、字体层级、文案截断策略保持一致。
• 提供 widget 预览/截图验收基线（至少包含浅色模式）。

R5. 验收与质量

• 建立页面级验收清单：布局完整性、可读性、点击可达性、状态一致性、异常文案表现。
• 关键页面提供 iPad 对比截图（改前/改后）与 iPhone 回归截图。
• 适配完成后输出覆盖清单，确保无遗漏页面。

Acceptance Criteria

1. 应用在 iPad 真机/模拟器上以 iPad 模式运行，不出现 iPhone 兼容模式导致的系统黑边。
2. 全部页面在 iPad 竖屏下通过视觉与交互验收，页面无明显错位、截断、重叠。
3. iPhone 主流尺寸下关键路径无样式与交互回归。
4. iOS Widget 在 iPad 对应尺寸下通过展示验收。
5. 提供最终“页面覆盖矩阵 + 验收记录”。

Risks

• 现有页面存在大量固定像素值，逐页改造可能引入局部联动风险。
• iPad 多窗口/舞台管理会带来额外窗口尺寸变化，需要明确支持级别。
• Widget 文案长度受多语言影响，需预留截断与回退策略。

Milestones (High-Level)

1. 基线与清单：完成断点策略、页面与组件清单、验收模板。
2. 页面适配：按“启动链路 -> onboarding -> 主页面 -> 弹层/边缘页面”逐页交付。
3. Widget 适配：完成尺寸验证与视觉一致性收口。
4. 全量回归：iPad 全页检查 + iPhone 零回归确认 + 发布前验收。