功能概述

• 功能类型：性能提升（冷启动与TTI优化）
• 目标：在典型用户设备上缩短应用冷启动时间与可交互时间（TTI），提升首屏渲染稳定性与可操作性
• 目标指标：
  • TTI（Time To Interactive，用户可进行第一步交互的时间）≤ 1.2 秒（A14 及以上）
  • 首帧渲染时间 < 800 毫秒（A14 及以上）
  • A14 及以上设备相较当前生产版本 TTI 下降 ≥ 30%
  • 能耗指标下降（以系统能耗报告与应用内监控为依据）
  • 崩溃率与 ANR（应用无响应）不升

用户场景

• 典型场景：用户频繁打开“清单匠 iOS”进行任务记录与查看（全天多次打开，碎片时段使用）
• 用户群体：
  • 普通用户：快速查看当日任务清单，添加新任务
  • 高级用户：在多清单、多标签视图间切换并进行批量操作
  • 企业用户：在组织空间内查看共享任务板、审核或分派任务
• 用户流程（冷启动）：
  1. 点击应用图标，展示启动页
  2. 首屏首帧快速呈现（无闪烁、Skeleton 占位一致）
  3. 首屏关键交互元素按优先级加载（例如“添加任务”按钮、今日清单摘要、搜索入口）
  4. 后续模块与数据增量加载（如统计图表、历史清单、插件入口）
• 交互要点：
  • 启动页稳定、无闪烁；布局在首帧与后续加载间保持一致性，不跳动
  • 关键操作元素可见且可点，低优先级内容逐步填充
  • 加载状态通过轻量化占位（Skeleton、占位图）指示，不阻断操作

功能特性

• 启动阶段优化
  • 按需加载模块（Lazy Load）：仅加载首屏必需模块，次级模块延迟初始化
  • 并行初始化（Swift Concurrency）：将可并行的服务初始化拆分并行执行
  • 数据库预热（Pre-warm）：在后台线程完成持久化层轻量预热，加速首屏查询
  • 延迟第三方 SDK 初始化：将非关键 SDK 的初始化推迟至首屏可交互后
  • 图片解码与缓存优化：关键图片资源预解码与内存/磁盘双层缓存策略
• 稳定与监控
  • os_signpost 埋点：精确标记启动阶段关键路径（进程启动、应用启动、首帧、可交互）
  • Instruments 检测：Time Profiler/Points of Interest/GPU/Network 检测并迭代优化
  • 指标看板：构建 TTI、首帧、能耗、崩溃率的可视化面板，灰度期间滚动观察
• 兼容与体验
  • iOS 14+ 支持：保证优化方案在 iOS 14 及以上版本正常运行
  • 一致性：Skeleton、首屏布局与后续加载一致，避免元素跳动导致的视觉负担

技术实现

• 术语说明
  • 冷启动：应用从未在内存中运行状态到首次启动的过程
  • TTI（Time To Interactive）：从用户点开应用到首屏可执行首次有效交互（点击/输入）的时间
  • 首帧渲染：首个可见帧完成渲染的时间点（UI 稳定且可见）
• 架构与启动管线
  • 启动分层：划分为“进程启动 → AppDelegate/SceneDelegate → UI 首帧 → 首屏可交互 → 次级模块加载”
  • 服务容器：建立 Service Registry，区分“关键路径服务”（配置、路由、首屏数据读取）与“延迟服务”（统计、推送扩展、非关键网络探测）
  • 主线程策略：主线程仅负责 UI 构建与必要调度，业务初始化尽可能转移至后台线程
• 模块按需加载
  • 首屏关键模块（必须）：路由、首屏 ViewModel、任务列表基础数据、轻量缓存读取
  • 延迟模块（可选）：统计与埋点、深度分析、云同步非关键分支、富媒体组件、插件容器
  • 方案：通过特性开关（Feature Flag）与依赖图，控制模块加载时机
• Swift Concurrency 并行初始化
  • 使用 async/await 与 TaskGroup 并行启动可独立的初始化任务（例如本地配置读取、轻量索引构建、会话验证检查）
  • 使用 Actor 或串行队列保护共享状态（避免数据竞态）
  • 设定超时与取消策略，防止慢任务阻塞可交互
• 数据库预热
  • 在后台线程进行轻量查询预热（例如当日清单摘要），建立必要索引或缓存
  • 避免在主线程执行重查询；将首次渲染所需数据序列化为轻量模型
  • 针对所用持久化技术（如 Core Data/SQLite/Realm）遵循其并发模型与上下文管理规范
• 图片解码与缓存优化
  • 首屏关键图片（图标/头像）在后台预解码，使用内存 LRU + 磁盘缓存组合
  • 限制解码并发度，避免阻塞主线程与 GPU 过载
  • 占位图与真实图切换平滑过渡，避免闪烁
• 第三方 SDK 延迟初始化
  • 将非关键 SDK（统计、广告、A/B 等）放置在首屏可交互后初始化
  • 事件缓冲：在 SDK 初始化前将关键事件写入本地队列，初始化后批量上报，确保数据完整性
  • 合规：如涉及用户跟踪或 IDFA，遵循 App Tracking Transparency（ATT）与隐私规范，初始化与弹窗时机符合苹果审核要求
• 监控与度量
  • os_signpost：对启动关键节点打点（process_start、didFinishLaunching、first_frame、interactive_ready）
  • Instruments：Time Profiler、Points of Interest、Energy Log、Network、GPU Frame Debugger
  • 生产环境指标：结合系统与自研监控统计分位数（P50/P90）与设备等级（A14+）
• 能耗与资源控制
  • 控制启动期 CPU/GPU 峰值与 IO 竞争；限制并发度与缓存大小
  • 避免过度预热造成内存膨胀；设定内存水位与清理策略

验收标准

• 指标达成（A14 及以上）
  • 冷启动 TTI ≤ 1.2 秒，首帧渲染 < 800 毫秒
  • 相较当前生产版本，TTI 下降 ≥ 30%
  • 能耗指标在启动阶段下降（以 Energy Log 报告与线上监控为依据）
• 稳定性与质量
  • 崩溃率不升；ANR 不升（以崩溃分析与用户会话停滞率为依据）
  • 启动页无闪烁；首屏元素按优先级可操作
• 测试要点
  • 设备矩阵：A14（iPhone 12 系列）及以上，iOS 14–最新稳定版本
  • 冷启动场景：系统重启后首次启动、清理应用后首次启动、网络良好与受限两种场景
  • 分位数校验：P50/P90 TTI 与首帧时间；样本量满足统计显著性
  • 功能回归：关键操作（添加任务、搜索、切换清单）在首屏可交互后可用
• 验收资料
  • Instruments 报告与 os_signpost 关键节点日志
  • 线上指标看板截图与灰度期间趋势对比
  • 测试报告（包含能耗、稳定性、交互一致性）

依赖关系

• 平台与语言
  • iOS 14+；Swift 5.5（支持 Swift Concurrency）
• 第三方与内部系统
  • 第三方 SDK 支持延迟初始化与事件缓冲
  • 崩溃与性能监控平台（符号化与版本区分）
• 研发与协作
  • 产品与设计：首屏元素优先级、Skeleton 与占位规范
  • 后端与数据：必要接口的低延迟保证、指标看板搭建与数据口径确认
  • QA：设备矩阵、性能与能耗专项测试、灰度期间回归
  • 运维与发布：灰度策略与回滚机制、特性开关与远程配置

风险评估

• 技术风险
  • 并行初始化引入竞态/死锁，需 Actor 或队列保护与超时控制
  • 过度预热导致内存峰值升高与回收压力增大
  • 延迟第三方 SDK 可能影响埋点完整性与归因准确性
  • 监控打点过多带来额外开销影响启动时间
• 业务与合规风险
  • 调整 ATT 或隐私相关 SDK 的初始化时机需符合苹果审核与用户授权流程
  • 指标口径不一致导致优化效果评估偏差
• 应对措施
  • 建立关键路径守护与熔断策略，异常退回同步初始化或降级路径
  • 事件缓冲与重试机制，确保数据完整性
  • 打点白名单与采样控制，监控开销可测可控
  • 指标口径统一文档与看板校验流程

版本计划

• 开发迭代
  • Sprint 1：启动管线梳理与 os_signpost 埋点、首屏优先级定义、基础并行初始化
  • Sprint 2：数据库预热落地、图片解码与缓存优化、延迟 SDK 初始化与事件缓冲
  • Sprint 3：Instruments 深度分析与能耗优化、回归与稳定性加固
• 灰度发布
  • 阶段 1：10% 用户，观察 48–72 小时（TTI/首帧/能耗/崩溃）
  • 阶段 2：25% 用户，观察 48–72 小时，对比基线与前一阶段
  • 阶段 3：50% 用户，确认指标稳定与口径一致
  • 全量上线：达到验收标准后扩展至 100%，保留回滚开关
• 指标看板与滚动观察
  • 实时监控 P50/P90 TTI、首帧、能耗、崩溃率、ANR
  • 分设备等级（A14+）与版本分组对比
  • 异常阈值警报与快速回滚流程（特性开关）
• 文档与评审
  • 评审节点：技术方案评审、灰度复盘、全量上线复盘
  • 交付物：方案文档、测试报告、Instruments 报告、看板截图与数据说明

以上模板面向“清单匠 iOS”的性能提升需求，覆盖功能描述、技术实现、验收标准、风险与依赖、版本规划，并支持产品、开发、测试、数据等多角色协作与迭代管理。

智阅记 iOS 功能需求文档 — 阅读器深色模式配色与排版优化

功能概述

• 目标
  • 在深色模式下优化阅读器的配色与排版，提升夜间和弱光环境的可读性与舒适度，并在具备 OLED 屏幕的设备上尽可能降低能耗。
• 价值
  • 降低视觉疲劳、减小眩光，提升长时间阅读体验。
  • 保持界面与文档内容在深色模式下的一致性与品牌识别。
  • 在合理范围内利用纯黑背景等策略提升 OLED 省电效果。
• 范围
  • 涵盖：阅读器正文、代码块、公式渲染、图片展示策略、导航与弹窗的主题适配、主题切换交互与预览、每文档主题记忆。
  • 不涵盖（本期）：编辑器输入态、非阅读器模块的深色样式重构（可在后续版本统一推进）。

用户场景

• 典型用户与动机
  • 普通用户：夜间卧床阅读，避免刺眼白底，便于快速切换主题。
  • 高级用户：长时间技术文档阅读，对代码块与公式的对比度和配色有更高要求。
  • 开发者用户：验证深色模式在多种渲染与组件中的一致性，便于调试和扩展。
  • 测试用户：覆盖不同设备、不同字体与字号、不同系统主题策略下的稳定性和一致性测试。
• 使用流程（关键路径）
  1. 跟随系统自动切换
     • 用户在系统设置中启用深色模式 → 打开智阅记阅读器 → 界面自动应用深色主题 → 切换无闪烁、颜色一致。
  2. 手动覆盖
     • 阅读器内主题设置入口 → 切换为深色/浅色/纯黑（适用于 OLED） → 支持「仅此文档」与「全局」两种应用范围 → 即时预览并应用。
  3. 主题预览与每文档记忆
     • 打开主题预览 → 预览区展示段落文字、链接、代码块与公式 → 用户确认后应用 → 对于某文档选择「仅此文档」，再次打开该文档时自动记忆并恢复。

提示：术语说明

• 动态颜色：随系统外观（深色/浅色）或用户设置自动变化的颜色。
• WCAG AA：Web 内容无障碍指南（2.1），文本对比度标准；普通文本≥4.5:1，较大文本（≥18pt 或 14pt 粗体）≥3:1。
• OLED 省电：在 OLED 屏幕上，纯黑像素可关闭发光以降低能耗。
• 快照/截图 Diff：对同一场景进行截图并进行像素差异比对的自动化测试。
• A/B 测试：对比两个或多个方案在真实用户中的表现差异。

功能特性

• P0（本期必做）
  • 跟随系统的深浅色自动切换，切换过程中无可感知闪烁。
  • 阅读器手动主题覆盖：浅色/深色/纯黑（OLED 优化），支持「仅此文档」与「全局」两种作用域。
  • 主题预览面板：展示正文、链接、代码块、公式、引用、列表等关键元素的预览。
  • 文档级主题记忆：按文档维度存储最近使用的主题，跨会话持久化。
  • 导航、工具栏、弹窗等系统组件的统一深色适配。
  • 可访问性与对比度达标：正文与主要文本满足 WCAG 2.1 AA。
  • 代码块与公式独立调色：提供与正文分离的安全对比度配色。
• P1（增强）
  • 纯黑模式下的更严格 OLED 省电策略（如避免高亮底色的大片使用）。
  • 图片反色白名单：为特定图片（如黑底白字的示意图）提供反色允许/禁止标记；默认不反色，按白名单启用。
  • 动态类型与字号兼容：在不同字号下保持合适的行距、字间距、段落间距和可读性。
• P2（后续）
  • 批量文档主题管理（多选应用/重置）。
  • 按文档类型（技术文档/小说/学术）定制的预设主题集合。

技术实现

• 架构设计
  • ThemeManager（单例/注入服务）
    • 负责主题源（跟随系统/手动覆盖/纯黑）的管理与合并策略。
    • 暴露统一的颜色与排版 Token（语义化，如 reader.background、reader.text.primary、code.background、math.symbol）。
    • 提供监听机制（NotificationCenter/Combine 发布）供 UIKit 与 SwiftUI 同步更新。
  • 持久化
    • 全局主题偏好：UserDefaults（键如 app.theme.mode）。
    • 文档主题偏好：以文档唯一 ID 为键（本地数据库或 UserDefaults 命名空间），记录 themeMode 与最后更新时间。
    • 迁移策略：当用户由「全局覆盖」变为「跟随系统」时，文档内优先使用文档级设置（如存在），否则回退到系统。
• UIKit 与 SwiftUI 适配
  • 颜色
    • 优先使用系统动态颜色（如 systemBackground、label、secondaryLabel 等）作为基线，保证可访问性与一致性。
    • 通过 UIColor(dynamicProvider:) 和 SwiftUI Color(UIColor) 暴露自定义动态颜色，支持纯黑分支（当用户选择纯黑时背景返回 #000000；否则返回系统的深色背景）。
  • 组件
    • 导航栏与工具栏：使用 UINavigationBarAppearance/UIToolbarAppearance 配置深色与纯黑变体；确保半透明/模糊材料在深色下可读（若用户开启“降低透明度”，退化为不透明背景）。
    • 弹窗/模态：UIAlertController、UIContextMenu、UISheetPresentationController 的外观与配色统一，避免混色。
  • 更新机制
    • 在 UIViewController.traitCollectionDidChange/_onChange(of: colorScheme) 中监听系统外观变化；当 ThemeManager 设置为“跟随系统”时，统一触发轻量级刷新。
    • 避免整页重建：对可重用区域（列表/富文本视图/WKWebView）仅更新样式，不重新加载数据。
• 排版与可读性
  • 行高与字距：根据动态字体大小，提供比例规则（例如正文行高 1.4–1.6 区间，视字号与字重微调）；在深色下适度增加行高以提升辨识。
  • 版心宽度：限制最大行宽，避免过长一行造成阅读负担（例如 60–80 字符宽，依据字体与语言调整）。
  • 链接与强调：确保链接在深色下可辨识，同时提供下划线或强调样式作为非颜色的提示。
• 代码块与公式
  • 代码块
    • 使用与正文区分的背景色与等宽字体，确保文本与背景对比度符合 AA。
    • 语法高亮色板在深色与浅色下分别定义；尽量使用语义色（keyword、string、comment、type、number）映射到 Token，便于统一管理。
  • 公式
    • 若使用 Web 渲染（如基于 WKWebView 的公式库）：为深色注入独立 CSS 变量（文本、符号、背景）；避免整体滤镜反色，优先“原生”深色样式。
    • 若使用富文本/矢量渲染：对绘制层应用主题 Token，确保线条与符号清晰。
• 图片反色白名单
  • 默认：不反色，保持图片原貌，避免品牌色与照片失真。
  • 白名单策略（两级）
    • 元数据标记：对内部资源或可识别的图示（如纯黑白线稿、SVG）标记为可反色（invertAllowed: true）。
    • Web 内容：为 增加 data-theme="invert" 或 class="invert-allowed"，CSS 在深色时仅对该类进行反色处理。
  • 后备方案：提供 per-document「图片反色」开关（默认关闭），以应对用户导入的特殊文档。
• 性能与无闪烁切换
  • 提前构建颜色表与外观对象（Appearance）缓存，切换时仅替换引用。
  • 对关键容器使用 UIView.performWithoutAnimation 或轻量过渡（transitionCrossDissolve，时长 ≤ 0.15s），避免闪烁与重排抖动。
  • WKWebView 内样式切换采用注入 CSS 变量的方式，避免整页 reload。
• 可访问性与系统协同
  • 对比度：正文≥4.5:1，较大文本≥3:1；对禁用/提示性文本以语义色控制透明度，保证仍可辨识。
  • 动态字体：适配 iOS 动态字体等级；在最大字号下也保持布局稳定、不截断。
  • 降低动态效果：若用户开启“减少动态效果”，关闭切换过渡动画与视差。
  • 颜色依赖减少：重要状态同时提供非颜色提示（图标形态、下划线、文本标签）。
• 日志与监控
  • 埋点：主题切换来源（系统/手动）、每文档主题命中率、回退到默认的次数、图片反色使用率。
  • 性能：主题切换耗时、帧率、WKWebView 样式更新耗时。
  • 能耗：通过 Instruments Energy Log 在典型场景采样，记录相对变化（作为观测指标，不设硬性阈值）。
• 平台要求
  • 系统 API 原生深色模式自 iOS 13 提供。若当前最低支持版本 < iOS 13，需要评估升级或提供降级策略（本期建议要求 ≥ iOS 13）。

验收标准

• 功能一致性
  • 跟随系统与手动覆盖互不干扰；切换后 200ms 内界面达到稳定，无明显闪烁、无延迟更新。
  • 导航、工具栏、弹窗外观与阅读器主体风格一致，无颜色割裂。
  • 每文档主题记忆：关闭应用并重启后，重新打开该文档仍保持上次选择；全局主题不被覆盖时作为默认回退。
• 可访问性
  • 对比度：正文与主要文本颜色对比度达到 WCAG 2.1 AA（普通文本≥4.5:1；较大文本≥3:1）。测试通过工具验证（设计稿与实机）。
  • 动态字体：在系统字体大小“最小/默认/最大”三档下布局无截断、无重叠、无关键信息缺失。
  • 降低动态效果开启时，不出现大幅动画或不必要的过渡。
• 代码块与公式
  • 代码块内容在深色与浅色下均清晰可读，语法高亮不影响对比度达标。
  • 公式渲染边缘、符号在深色背景下清晰，无发灰或锯齿异常。
• 图片策略
  • 默认不反色，白名单图片在深色模式下按策略反色；品牌 Logo 与人物照片不被误反色。
• 测试与自动化
  • 截图 Diff：在指定机型与系统版本（至少 1–2 个主流尺寸）进行暗/亮主题对照快照，对静态区域像素差为 0；动态区域设掩码或阈值，Diff 测试通过。
  • 性能：主题切换时主线程长任务 < 16ms（单帧预算），流畅度无明显下降。
  • 稳定性：新增功能相关崩溃率为 0 个已知阻断缺陷。
• 审核与合规
  • 符合 Apple 人机界面指南（HIG）关于深色模式、可访问性和动态字体的建议。
  • 不引入误导性 UI 或读取用户未授权数据的行为。

依赖关系

• 设计
  • 语义化颜色/排版 Token 清单与对照（浅色/深色/纯黑）。
  • 对比度校验报告（含关键元素：正文、次级文本、链接、代码、公式、提示）。
• 客户端
  • 主题管理器基础设施（UIKit/SwiftUI 双栈桥接）。
  • WKWebView/富文本渲染的注入样式机制（若使用 Web 渲染的代码或公式）。
• 第三方/渲染库
  • 代码高亮引擎与公式渲染库的深色样式支持或可扩展 CSS。
  • 若有富文本/Markdown/HTML 渲染库，需确认其深色主题扩展点与自定义覆盖能力。
• 测试与数据
  • 快照测试框架与像素 Diff 工具链。
  • 远程配置/A/B 分流能力与埋点上报。
• 运营与发布
  • 分阶段灰度发布与回滚策略支持。
  • 支持文档与帮助中心更新（说明手动覆盖与每文档记忆）。

风险评估

• 技术风险
  • 第三方渲染库不支持深色主题，样式难以覆盖。
    • 缓解：优先注入 CSS 变量/主题 Hook；必要时隔离为可切换的渲染路径。
  • 品牌色在深色背景下对比度不足。
    • 缓解：为品牌色提供深色替代色或自动提升亮度/饱和度至达标阈值，保留最小识别度。
  • WKWebView 切换主题导致内容重排或闪烁。
    • 缓解：使用 CSS 变量即时替换，避免刷新；在切换瞬间禁用过渡动画。
  • 截图 Diff 脆弱（系统字体/渲染微差）。
    • 缓解：锁定测试机型与系统版本，设置动态区域掩码，采用阈值或感知差异算法。
• 业务风险
  • 用户对默认不反色图片产生可读性预期差异。
    • 缓解：提供文档级图片反色开关与说明，收集反馈逐步完善白名单策略。
  • 纯黑模式可能与部分设计风格冲突。
    • 缓解：纯黑仅在阅读场景启用，并作为可选项，默认使用系统深色配色。

版本计划

• 迭代拆分
  • v1（本期）
    • P0 全部：自动/手动切换、主题预览、每文档记忆、导航/弹窗适配、对比度达标、代码/公式独立调色、基本快照与对比度测试。
  • v1.1（增强）
    • P1：纯黑优化细化、图片反色白名单与文档级开关、动态字体高级适配、监控指标完善。
  • v1.2（后续）
    • P2：批量文档主题管理、按文档类型的预设主题集合、跨设备同步（如后端支持）。
• 里程碑与时间建议（示例，按人力可调）
  • 设计评审（1 周）
    • 输出 Token 清单与深/浅/纯黑规范；完成对比度校验。
  • 开发实现（2–3 周）
    • ThemeManager 与 Token 接入；UIKit/SwiftUI 适配；WKWebView 样式注入；每文档记忆与设置面板；基础监控。
  • 联调与测试（1–2 周）
    • 设备矩阵测试、对比度验证、截图 Diff 稳定化；性能与能耗观测。
  • A/B 验证与灰度（1–2 周）
    • 分流策略：新用户 20% → 50% → 100%，老用户 10% → 30% → 70% → 100%（视指标而定）。
    • 成功指标（正向）：夜间阅读时长、人均主题切换次数下降、反馈问题率下降；（负向监控）：崩溃率、异常闪烁反馈。
  • 全量发布与复盘（1 周）
    • 汇总数据、问题修复计划、下一版需求确认。
• 角色与协作
  • 产品：验收标准与分流策略确认，指标口径定义。
  • 设计：Token、样式规范、对比度校验与预览样例。
  • iOS 开发：主题架构、组件适配、性能优化与埋点。
  • 测试：用例覆盖（功能/可访问性/截图 Diff/性能），回归与灰度监控。
  • 数据/运营：A/B 配置、指标看板、公告与帮助文档更新。
• 回滚策略
  • 通过远程配置关闭手动覆盖与纯黑选项，回退到“仅跟随系统”。
  • 如需快速止损，可在不发版情况下关闭新主题 Token 下发（若有远程配置），或上架热修复版本（若变更涉及客户端渲染路径）。

以上文档遵循 Apple 人机界面指南与 App Store 审核规范，尽量使用系统语义色与无障碍能力，避免对内容进行不可预测的自动反色处理，通过白名单与可见开关在保证可读性的同时尊重用户预期与品牌一致性。