iOS故事板场景描述生成器

导航栏与返回

• 顶部透明导航栏，滚动至标题区后渐变为不透明，显示商品标题（单行省略）。
• 左：返回按钮。右：客服入口（耳机图标）与分享（可选）。
• 搜索入口非必需（避免干扰决策，保持“简单”）。

主体滚动容器

• 垂直 ScrollView，内容分区清晰分块；价格区与操作条突出视觉权重。
• 顶部“下拉查看大图”提示在轮播区上方显示，当到达顶部时可拉动触发预览。

商品图轮播（缩放/预览）

• 占位区域：16:9 或接近全宽正方形（以商品图比例为准），居上。
• 水平分页轮播（TabView.page 或 UICollectionView paging），底部圆点指示器/计数器。
• 每页包一层 UIScrollView（UIViewRepresentable）以支持双击/捏合缩放；越界回弹关闭。
• 占位图：灰色/模糊占位，图片加载后渐进淡入。

价格区与促销标签

• 主价：大号粗体，采用品牌色；辅价（划线价/到手价说明）小号灰色。
• 促销标签：水平排列的Chip（满减/券/会员价），可点击展开促销说明（底部半屏弹窗）。
• 价格区底部显示“店铺入口”按钮（小型次要按钮），点击进入店铺首页。

标题与卖点

• 标题：多行，最大2-3行。
• 卖点：1-3个短标签（如“次日达”“7天无理由”），视觉弱于价格强于正文。

规格/尺码选择与库存状态

• 单行摘要（例如“已选：黑色 / 42码 | 有货”），右侧“选择”箭头。
• 点击进入底部弹出面板：分组属性+SKU格子；禁用缺货项；顶部展示当前SKU图、价、库存。
• 库存状态：有货/仅剩X件/缺货（缺货禁用加购与立即购买）。

数量步进器

• 位于规格弹层内与主页面摘要区下方（主页面可只显示当前数量或隐藏，简化交互）。
• “- / +”大触控区，展示限购/最小起购提示。

底部操作条（固定）

• 左侧：店铺入口（图标+文字）、客服入口（图标）。
• 右侧：加入购物车（主按钮次一级色）、立即购买（主品牌色）。
• 考虑安全区和横向小屏收纳（图标+短文案）。

评价概览与筛选

• 评分星级+好评率+总评数。
• 快捷筛选：有图/追评/本地/最新（Chip样式，点击更新当前页面的评价摘要或跳转评价列表页）。
• 展示2-3条精选评价预览（含图）并提供“查看全部”。

图文详情/参数/保障切换

• 分段控制（SegmentedControl）吸顶（sticky），切换下方内容区。
• 图文详情：长图与文本混排；参数：表格样式；保障：服务与政策说明卡片。
• 在主信息块末尾放“上拉查看详情”提示，滚动到达临界点时自动吸顶并切换到详情区。

推荐商品瀑布流

• 位于详情区末尾，2列自适应高度网格（简化为固定两列，文本两行内省略，主图等高裁切）。
• 卡片含图、标题两行、价格、加购小按钮（可选）。

返回顶部

• 浮动按钮（出现于滚动超过一屏时），右下角，避开底部操作条与安全区。

骨架屏与占位图

• 首屏加载：价格区、标题区、卖点、按钮、评价卡片显示 .redacted 占位。
• 轮播使用统一占位图，详情长图使用渐进加载（按屏幕进入时再加载）。

首次进入

• 显示骨架屏，发起并行请求：商品基础信息、SKU与库存、促销、评价摘要、推荐。
• 收到基础信息后先行渲染标题、价、卖点；图片分批加载；库存/促销返回后刷新按钮可用性与价格。
• 错误时显示内联错误与重试按钮（不遮挡底部操作条）。

轮播与预览

• 左右滑动切换图片；双击或捏合图片放大；放大后可平移；再次双击还原。
• 下拉查看大图：在轮播处下拉超过阈值触发全屏预览（分页浏览，黑底，支持分享/保存），释放返回。

上拉查看详情

• 用户向上滚动至主信息末尾，提示“继续上拉查看详情”；超过阈值后自动将分段控制吸顶，并滚动到“图文详情”锚点。
• 切换分段时平滑滚动到对应锚点并更新高亮。

规格/尺码选择与库存联动

• 点击规格摘要打开底部弹层；点选属性组合，实时查询/计算对应SKU库存与价格。
• 缺货SKU禁用选择；仅剩X件时在数量步进器附近提示。
• 确认后更新主页面摘要。“加入购物车/立即购买”按钮基于库存状态启用/禁用。

数量步进器

• 点击 +/- 调整，若超过库存/限购提示并回退，轻度触感反馈（soft haptics）。

加入购物车/立即购买

• 校验已选SKU与数量；未选齐则自动展开规格弹层并高亮缺失项。
• 加购成功弹出轻提示“已加入购物车”，提供“去购物车”动作；失败显示错误与重试。
• 立即购买跳转确认订单页，携带选中SKU与数量。

评价概览与筛选

• 点击筛选Chip，刷新预览评价；“查看全部”跳到评价列表页面并传递已选筛选条件。

店铺入口与客服

• 店铺入口：push 店铺页。
• 客服入口：打开客服会话（若未登录，先引导登录）。

推荐瀑布流

• 滚动到达下方触发分页加载；点击卡片进入对应商品详情（支持深度链接）。

返回顶部

• 点击浮动按钮平滑滚动到顶部；顶部回弹显示“下拉查看大图”提示。

架构与数据流

• MVVM + Swift Concurrency（async/await）。单页ViewModel将产品、SKU、促销、评价、推荐拆分子仓储/服务。
• 模型建议：Product, SKU, StockInfo, Promotion, ReviewSummary, DetailSection, RecommendItem。
• 关键状态：selectedAttributes, selectedSKU, quantity, stockState, activeSection（详情/参数/保障）。

视图与布局

• SwiftUI ScrollView + LazyVStack 分块；价格区/分段控制使用 .background + GeometryReader 实现滚动吸顶与透明度过渡。
• 轮播：TabView with .tabViewStyle(.page)。每页嵌入 ZoomableScrollView（UIScrollViewRepresentable，min/maxZoomScale，双击缩放）。
• 瀑布流：LazyVGrid(columns: [GridItem(.flexible()), GridItem(.flexible())]) 简化两列；需要严格瀑布时可升级为 UIKit UICollectionViewCompositionalLayout + UIHostingConfiguration。

导航与交互

• 顶部透明到不透明过渡：通过滚动偏移计算导航栏背景不透明度。
• “下拉查看大图/上拉查看详情”：使用 ScrollView contentOffset 监听（PreferenceKey/GeometryReader）驱动阈值判定与滚动到锚点。
• 底部弹层：presentationDetents([.medium, .large])，规格较多时默认 .large。

网络与性能

• 图片加载：AsyncImage 或自定义缓存层（URLCache + URLSession）。首屏只预取前2-3张大图，其他懒加载。
• 内容分批加载：基础信息优先，详情长图按需加载（出现在视窗再发起）。
• 预取推荐列表分页；滚动性能监控（Instruments）确保主线程帧率稳定。
• SKU/库存联动：本地组合计算或后端接口返回可售组合；选择变更时只增量刷新相关区块。

占位与状态

• .redacted(reason: .placeholder) 显示骨架；图片使用渐进式淡入（.transition(.opacity)）。
• 错误状态采用内联卡片+重试按钮；重要操作错误（加购失败）使用alert/toast。

可访问性与国际化

• 动态字体支持（.font(.title).minimumScaleFactor）；VoiceOver：为轮播页添加 accessibilityLabel（序号/总数+图描述）。
• 控件可达44pt触控目标；色彩对比遵循WCAG AA；支持暗黑模式。
• 文案本地化；数字/货币使用 NumberFormatter。

代码结构建议（简要）

• Views/
  • ProductDetailView, PriceSectionView, PromotionChipsView
  • GalleryCarouselView(含ZoomableScrollPage)
  • SpecsSummaryRow, SpecsSheetView(+ QuantityStepper)
  • ReviewSummaryView, DetailSegmentedView, DetailContentView
  • RecommendGridView, BackToTopButton, CustomerServiceButton
• ViewModels/
  • ProductDetailViewModel, SpecsViewModel, ReviewViewModel, RecommendViewModel
• Services/
  • ProductService, StockService, PromotionService, ReviewService, RecommendService
• Routing/
  • ProductDetailRouter（店铺页、评价列表、订单确认）
• Utilities/
  • ImageCache, ScrollOffsetPreferenceKey, Haptics

事件埋点（可选）

• 曝光：首屏渲染完成、轮播首图曝光、详情锚点曝光。
• 交互：加购、立即购买、规格选择、客服点击、评价筛选、返回顶部。

安全与合规

• 价格/促销与库存一致性以后端为准；下单前再次校验库存/价格变更。
• 网络失败重试与兜底文案，避免空白页。

屏幕尺寸

• iPhone SE：压缩横向空间，促销Chip自动换行；底部操作条按钮文字短化（“加购”“立即买”）。
• 大屏/Plus：轮播保持16:9或1:1，右侧可考虑并排展示部分概要信息（如库存/卖点）但“简单”方案保持单列。
• iPad：可两栏布局（左图右要点），但若非目标平台维持单列放大。

横竖屏

• 竖屏为主；横屏时：
  • 轮播高度按宽高比调整；分段控制仍吸顶。
  • 推荐区从2列增至3-4列。
  • 底部操作条扩大间距，确保触控目标。

动态字体与无障碍

• 文本支持Content Size Category；大号字体下Chip自动换行，按钮增长不截断（优先保留“立即购买”）。
• VoiceOver顺序：图轮播 → 价格 → 标题/卖点 → 规格摘要 → 操作条 → 评价 → 分段内容 → 推荐。

深色模式与对比

• 价格主色在深色模式下保持对比度；促销/卖点Chip使用系统语义色（.secondarySystemBackground 边框+文本色）。

RTL与本地化

• 轮播指示器、返回按钮遵循系统方向；金额格式与单位本地化。

推荐使用 UIKit + 组合式子视图的架构（LiveRoomViewController 作为容器，内部多层 overlay 管理），满足复杂层级与横竖屏切换需求；关键交互面板使用 UISheetPresentationController/自定义半屏面板。

根容器：LiveRoomViewController

• 背景层：主视频渲染区域
  • 播放器视图：占据安全区内顶部至底部的背景层，竖屏比例以 16:9 或按源等比填充，内容模式为 aspectFill；支持横屏全屏。
  • 主播视频窗口（主画面）：在播放器视图内全屏渲染；若处于 PK/连麦，则保留为主舞台。
  • 观众连麦画中画（PIP）容器：右下角悬浮的圆角小窗（约 120–160pt 宽，16:9 或 1:1），支持拖拽与吸附；多路连麦可网格排列（最多 2–4 个），超出折叠为分页点或栈叠角标。
• 顶部信息与控制条（置于安全区内，渐隐背景）
  • 左侧：返回按钮、房间标题/主播名、在线人数徽标（动态刷新）。
  • 中间：PK 状态栏（仅 PK 时显示）——对手头像与名称、比分、倒计时、弱网/延时徽标。
  • 右侧：关注按钮（大按钮，状态切换已关注）、分享按钮（调用 UIActivityViewController/自定义分享面板）。
• 右侧工具栏（纵向按钮栈，居中或偏下）
  • 申请连麦/麦位状态按钮（根据状态展示：申请、排队中、已连麦、麦位已满）。
  • 礼物入口按钮（红点提示新道具/活动）。
  • 观众列表按钮（显示在线用户与管理入口，仅主播/房管有管理工具）。
  • 设置按钮（音视频开关、音量、GPU 特效开关、清晰度/线路、举报入口）。
  • 横/竖屏切换按钮（竖屏时显示进入全屏，横屏时显示退出）。
• 底部互动层
  • 弹幕列表（半透明背景，竖屏底部 1/3 高度区域，支持滑动暂停、上滑隐藏；cell 使用轻量布局与异步绘制）。
  • 弹幕输入栏（置底安全区上方）：输入框、发送按钮、表情/快捷语、违规则提示条；非连麦时仅文字输入，连麦时可额外提供语音/静音控制。
  • 快捷礼物条（可选）：常用礼物横滑列表，支持连击按钮。
• 状态提示与公告
  • 房间公告条：顶部横幅，自动轮播，可点击弹出详情。
  • 弱网/降级提示：顶部贴边黄/红色 toast，附操作建议（如切换音频模式）。
  • 违规拦截提示：发送前校验失败时在输入栏上方显示红色条。
  • 引导蒙层：首次进入展示关键按钮引导（点击任一区域或“我知道了”关闭）。
• 底部连麦控制条（仅观众已上麦或主播端显示）
  • 麦克风开关、摄像头开关、前后摄切换、扬声器/耳机切换、音量滑杆（系统音量 UI 或自定义）、挂断按钮。
  • 麦位状态徽标：显示当前麦位序号、静音/闭麦标记、网络质量。
• 遮罩面板（Modal/Sheet）
  • 连麦申请队列与审批（主播端）：队列列表、同意/拒绝/移除、上麦时长、违规标识。
  • 麦位管理（主播端）：固定/解锁、禁麦、封禁、邀请上麦、麦序调整。
  • 礼物面板：礼物网格、连击入口、余额与充值入口、活动推荐位。
  • 观众列表：在线用户、关注、禁言/踢出（主播/房管可见）。
  • 设置面板：清晰度/线路、GPU 特效开关、低延迟模式切换、后台播放开关、问题反馈。
  • 分享面板：系统分享/深度链接/海报生成。

进房与初始化

1. 用户点击进入直播间，展示骨架屏，发起并行请求：房间元数据(REST)、在线人数与心跳(WebSocket/定时器)、公告、礼物配置(缓存+增量)、播放地址(主备线路)。
2. 播放器优先选择低延迟协议：观众默认 LL-HLS（低延迟 HLS/CMAF）；若正在 PK 或高互动房间，可提示“超低延迟模式”（RTC 下行）可切换。
3. WebSocket 连接建立后订阅：弹幕、礼物、上麦事件、PK 事件、麦位更新、房管指令、违规反馈。

申请连麦（观众）

1. 点击“连麦”按钮 → 弹出面板：摄麦授权检查、网络与耳机建议、连麦须知、同意条款。
2. 提交申请 → UI 进入“排队中”状态，按钮显示倒计时与取消；服务端进入申请队列。
3. 主播端在“连麦队列”面板看到新申请，可预览用户信息、历史违规；同意/拒绝/忽略。
4. 同意后，观众侧收到上麦邀请事件 → 弹框确认，上麦后：
   • 停止 LL-HLS 播放。
   • 建立 RTC 上下行（主播音视频下行 + 自己上行），完成设备启停与回声消除初始化。
   • UI 切换为“已连麦”，显示 PIP 小窗与连麦控制条。
5. 拒绝或超时 → 显示结果 toast，并回退到可申请状态。

麦位管理与状态

• 主播可在麦位管理面板：设定麦位数量、锁定空位、禁麦某位、移除上麦者、邀请指定观众上麦。
• 观众端实时显示自己与他人麦位状态（小窗角标：静音、禁麦、网络差）。
• 挂断流程：观众点击挂断或被主播移除 → 先行关闭上行、恢复 LL-HLS 播放、清理 RTC 资源和 UI。

弹幕与礼物

• 弹幕：输入发送 → 本地预渲染插入 → 服务端审核（命中拦截则回滚并提示原因）；支持敏感词提示、频控冷却。
• 礼物：打开礼物面板 → 选择礼物与连击次数 → 支付与发送 → 服务端下发礼物事件（包含动效素材与队列顺序）；终端按服务端时间戳对齐展示；连击在短时重复发送中合并叠加，显示连击计数与特效升级。

PK 流程

• 开始 PK 后顶部状态栏显示对手信息、比分与倒计时；可显示阵营热度条。
• 结束时展示胜负结果动画与引导关注/复盘。

音视频与弱网策略

• 用户可切换麦克风/摄像头、前后摄、扬声器；音量滑杆仅影响本地播放。
• 弱网提示：检测到丢包/抖动/带宽下降 → 顶部弱网条提示并自动降级：
  1. 优先切更低码率/分辨率；2) 降帧；3) 关闭美颜/特效；4) 最终切为“音频优先”模式（关闭上/下行视频）。
• 网络恢复后逐步回升策略，避免抖动。

横竖屏与全屏

• 竖屏默认：顶部信息 + 右侧工具栏 + 底部互动层。
• 点击全屏或横持设备：进入横屏，仅保留核心叠加（PK 状态、少量工具按钮、轻量弹幕）；滑动呼出隐藏工具栏；返回竖屏恢复完整 UI。

后台播放与中断

• 非连麦状态：允许后台音频播放（用户可在设置中开关），进入后台后保留音频，弹幕暂停渲染但保留消息缓冲。
• 连麦状态：为防止隐私与体验，默认禁止后台；若用户退到后台，自动挂断或切为仅听并提示（产品策略可配）。
• 处理中断（来电/闹钟）：使用 AVAudioSession 中断回调暂停/恢复 RTC 与播放。

连接重试

• WebSocket/媒体连接断开：指数退避重试 + 限次；重连成功后请求最近增量事件（礼物/弹幕/麦位状态）进行状态补偿。
• UI 显示“正在重连/已恢复”状态条。

播放器与低延迟

• 使用 AVPlayer 播放 LL-HLS（CMAF 低延迟）流；调优建议：
  • 减小 preferredForwardBufferDuration（或使用自动低延迟配置）、开启快速启动、控制最小缓冲段数。
  • 多线路/清晰度：主备 URL 切换与无缝重连；小范围卡顿优先切换分辨率，其次线路。
• 横屏全屏：使用 AVPlayerLayer 或自定义渲染视图，支持画面旋转与填充裁剪。

实时连麦（RTC）

• 使用实时音视频 SDK（WebRTC 技术栈），区分角色：主播（Pub+Sub）、连麦观众（Pub+Sub）、纯观众（Sub）。
• 音频会话：AVAudioSession category = .playAndRecord，options 包含 .defaultToSpeaker、.allowBluetooth；连麦时开启回声消除、噪声抑制；非连麦回退到 .playback。
• 设备权限：进入连麦面板前检查/请求麦克风、相机权限；无权限给出引导。
• 媒体切换：从 LL-HLS 切到 RTC 下行需无缝静音过渡，先停 HLS 再拉起 RTC，完成后打开本地上行；挂断时反向顺序。

信令与数据流

• 信令通道：WebSocket（房间心跳、在线人数、连麦申请/审批、礼物、弹幕、PK、麦位、违规/系统通知）。
• 心跳：进入房间后按固定间隔发送，服务端返回在线人数与房间状态；断开超过阈值触发回收与 UI 提示。
• 时间对齐：获取服务端时间偏移，用于礼物连击窗口、PK 计时与动效同步。
• 状态机：连麦申请/审批/上麦/挂断、弱网降级/恢复、PK 开始/进行/结束使用显式状态机管理，避免 UI 与媒体状态错位。

UI 架构与性能

• 模块划分：PlayerModule、RTCModule、DanmakuModule、GiftModule、SeatModule、PKModule、ModerationModule、ShareFollowModule、SettingsModule。
• 数据绑定：使用 Combine 或 async/await + MainActor 驱动 UI；列表使用 diffable data source。
• 动效：礼物特效使用 Lottie/Metal Shader/CAEmitterLayer，统一动画调度与资源缓存；在弱网或高温降级关闭高耗能特效。
• 弹幕优化：异步文本排版（CoreText/UILabel + prelayout）、复用池、限帧插入（如每帧最多 N 条）、超量丢弃低优先级。
• 无障碍与触达：按钮有足够触控面积（≥44pt）、动态字体兼容、VoiceOver 描述。

安全与合规

• 违规拦截：客户端本地敏感词快速过滤 + 服务端审核回执；违规内容拦截 toast；严重违规触发只读模式或禁言。
• 设备与温控：监控帧率/温度，触发 GPU 特效开关建议；持久高温时降低帧率/分辨率。

代码结构建议

• LiveRoomViewController：协调器（Coordinator）管理子模块生命周期与横竖屏切换。
• ViewModel 分层：RoomViewModel（房态/心跳）、PlayerViewModel（LL-HLS）、RTCViewModel（连麦）、SeatsViewModel（麦位）、InteractionViewModel（弹幕/礼物/关注分享）、PKViewModel。
• 统一事件总线：RoomEventBus（WebSocket -> 各模块），确保线程安全与主线程 UI 更新。
• 错误与日志：统一错误码映射、可观测日志与性能埋点（首帧时延、卡顿率、丢包、重连次数、动效触发量）。

屏幕尺寸与布局

• Auto Layout + Safe Area，关键按钮避开传感器区域；iPad 使用 Split/Popover 优化面板，横屏可启用多列布局（礼物与弹幕并列）。
• PIP 小窗尺寸按屏宽百分比自适应（约 0.25–0.3 宽），支持拖拽吸附四角；多路连麦在小屏限制最多 2 路并启用分页。
• 动态字体：输入与列表遵循 Content Size Category，弹幕字号有独立设置项。

横竖屏策略

• 支持界面方向：竖屏优先；播放区域可强制横屏全屏，非核心叠加元素最小化；切换时使用过渡动画（淡入/尺寸过渡）避免跳闪。
• 状态保持：横竖屏切换时保留连麦与播放状态、不重建连接；仅重排布局。

后台与系统特性

• Background Modes 勾选 Audio；非连麦可后台播放音频；连麦时根据策略禁止或切换仅听。
• Picture in Picture（系统级）：仅在纯播放（非连麦、非特效叠加依赖）场景下开放；进入 PiP 自动收起互动层，回前台恢复。
• 来电/耳机插拔：遵循 AVAudioSession 通知更新路由与 UI 状态。

弱网与设备差异

• 基于网络质量与设备性能分级策略：老设备/高温默认关闭 GPU 特效；弱网自动降级视频参数。
• 国际与多语言：UI 文案长度自适应，分享与敏感词库按地区配置。