mindfulness/spec_kit/iPad Adaptation/plan.md

iPad Adaptation（技术计划）

1. 计划目标

基于 spec.md，落地“全应用 iPad 适配（含 iOS Widget）”实施方案，确保：

• 客户端所有页面在 iPad 下可用、可读、可交互；
• 以 竖屏 为主目标完成逐页适配与验收；
• iOS Widget 在 iPad 相关尺寸下展示稳定；
• 全过程保持 iPhone 零回归。

2. 默认技术决策

• 适配方式：React Native 断点 + 条件样式（不改 iPhone 基线参数）。
• iPad 判定：Platform.OS === 'ios' && Math.min(width, height) >= 768。
• 尺寸获取：统一使用 useWindowDimensions()，避免 Dimensions.get() 静态值问题。
• 布局原则：页面采用“最大内容宽度 + 居中 + 弹性留白”。
• 改造策略：按页面逐个交付，单页完成后冻结，待确认再进入下一页。

3. 工程配置基线（先决条件）

3.1 原生配置核查

• app.json 中 expo.ios.supportsTablet = true（已要求）。
• iOS 工程目标设备族支持 iPad（TARGETED_DEVICE_FAMILY 需包含 1,2）。
• 方向策略与产品要求一致（当前优先竖屏；若仅竖屏，则 iPad 也收敛为竖屏策略）。
• 避免 iPad 以 iPhone 兼容模式运行（该模式会导致系统黑边）。

3.2 运行模式与验收环境

• iPad 模拟器：至少 1 台主流尺寸（如 11-inch）。
• iPad 真机：至少 1 台（若可用），用于确认系统级显示行为。
• iPhone 回归机型：至少小屏 + 大屏各 1 个。

4. 页面适配实施策略（逐页）

4.1 页面分批顺序

1. 启动链路：splash / consent / index
2. Onboarding 全流程页
3. 主应用页：home、详情/弹层、设置、收藏等
4. 边缘页：modal、not-found、其他辅助页

4.2 单页改造标准模板

每页按以下模板执行：

1. 梳理页面结构：首屏视觉区、正文区、底部操作区、浮层区。
2. 抽离 iPad 分支参数：最大宽度、字号、行高、间距、按钮尺寸。
3. 保持 iPhone 参数不变：原样式分支保留。
4. 自测：
   • iPad 竖屏显示完整；
   • 文案不截断、按钮可点击；
   • iPhone 关键路径不回归。
5. 输出截图与验收点，待确认后冻结该页。

4.3 可复用样式基线（建议）

• 页面容器：flex: 1 + width/height: '100%' + alignSelf: 'stretch'。
• 内容最大宽度：按页面类型设置（例如 560/620/680 分级），统一居中。
• 底部操作区：基于安全区与窗口高度计算，不使用硬编码魔法值。
• 文案区：限制最大阅读宽度，iPad 适度增大字号与行高。
• 图片/插画：按比例缩放，优先保持构图稳定，不压缩变形。

5. iOS Widget 适配计划

5.1 覆盖范围

• 小/中/大组件在 iPad 下的展示一致性；
• 文案长度、换行与截断策略；
• 图形与文本的层级、边距、留白；
• 浅色模式基线（深色模式按资源情况补充）。

5.2 实施要点

• 统一组件内边距与字号层级映射；
• 对长文本提供优雅截断（避免溢出与跳变）；
• 验证不同语言长度对布局影响；
• 输出尺寸矩阵截图作为最终验收材料。

6. iPhone 零回归保障

• 所有 iPad 适配均以条件分支或断点参数实现；
• 禁止直接覆盖 iPhone 基线字号/间距；
• 每完成一页，执行 iPhone 冒烟回归：
  • 启动流程；
  • Onboarding 关键交互；
  • Home 关键按钮与弹层；
  • Settings/Favorites 基础可用性。

7. 验收清单与交付物

7.1 页面级验收清单

• 布局完整：无重叠、无错位、无异常黑边；
• 文案可读：不截断（可接受预期截断场景需说明）；
• 交互可用：触控面积合理、按钮不被遮挡；
• 状态一致：加载/空态/异常态显示正常；
• iPhone 回归：关键路径无变化。

7.2 交付物

• 每页适配说明（改动点 + 参数策略）；
• iPad 改前/改后截图；
• iPhone 回归截图；
• Widget 各尺寸截图；
• 最终页面覆盖矩阵与验收记录。

8. 分阶段里程碑

1. M1 基线搭建

   • 完成原生配置核查与适配基线工具/约定；
   • 输出页面清单与验收模板。

2. M2 页面逐页适配

   • 按既定顺序逐页改造；
   • 每页交付后等待确认，再继续下一页。

3. M3 Widget 收口

   • 完成 iPad 尺寸矩阵验证；
   • 修复文本/间距/层级问题。

4. M4 全量回归与发布前验收

   • iPad 全页验收 + iPhone 零回归确认；
   • 形成最终验收文档。

9. 风险与应对

• 风险：页面存在大量固定像素值，局部改动引发联动。
  应对：参数分层、按区块替换、单页冻结机制。

• 风险：iPad 多窗口/舞台管理导致尺寸波动。
  应对：以竖屏全屏为主验收，同时保留窗口变化最小兼容策略。

• 风险：多语言文案长度影响 widget 与页面稳定性。
  应对：统一截断/换行规则，增加长文案样本回归。