# 肩颈放松｜动作引导与反馈 PRD

版本：v1.5 · 2026-09-30 · 通用机制与动作配置分层
适用角色：产品、客户端、视觉、动效、音频、QA

# A. 开发执行规格

A 部分是开发执行规格，分为稳定的通用交互机制与可替换的动作配置。页面流程、目标反馈、阶段衔接、奖励与状态管理按通用机制实现；每个动作的方向、路径、角度、时长、次序和轮次由动作配置驱动。B 部分为产品说明 / 评审备注，可整体删除，不影响开发。

## 1. 通用机制与可替换配置

| 配置项 | 开发规则 |
|---|---|
| 适用场景 | 面向日常久坐、感觉颈部紧绷的普通成年人；不作为颈痛、损伤或术后康复处方 |
| 行动名称 / 标识 | 显示名称“肩颈放松”；内部标识 `shoulder_relaxation`；动作版本随配置记录 |
| 输入 | 手机前置摄像头估计头部左右转动；控制点位置必须来自有效实时输入 |
| 当前动作配置 | 坐姿左右转头；每侧在用户确认的舒适参考位置连续保持 2 秒；左右各 3 次，共 3 轮。变更动作时按第 2 节配置表更新 |
| 时长 | 卡片与详情页显示整分钟预期标签“1 分钟”；实际执行时长由动作配置和用户完成进度决定。权限、说明与范围准备单独计 |
| 核心循环 | 控制点沿当前动作段路径经过已配置的过程目标 → 到保持目标持续完成配置操作 → 段落完成反馈 → 按配置回到衔接点 → 显示下一动作段 |
| 视觉表现 | 使用实时跟随用户头颈位置的红色中心控制点、蓝色圆形目标、蓝白水彩目标反馈及已配置的元气/灵感图标；命中水波与星点效果局限在目标附近；目标数量和类型由动作配置决定 |
| 奖励 | 目标命中分值作为当前 session 的过程反馈，不直接记入账户；首次有效完成后账户奖励由《今日行动总体页面架构 PRD》按 completionId 结算；重复练习不产生新账户奖励 |
| 会话 | 不提供暂停与续练；退出或中止后不保存可续练进度；完成记录保留且幂等提交 |

参数、页面文案、输入判定和验收用例均以 A 部分为准。摄像头、音效、触觉及健康结果未经设备实测或临床验证时，不得标记为已验证。

## 2. 通用交互机制与动作配置边界

### 2.1 稳定的通用交互机制

所有舒缓动作复用同一套页面和反馈机制：选择行动 → 行动介绍与行为说明 → 摄像头/输入准备 → 正式引导 → 完成结算。正式引导由“显示当前动作段 → 输入控制点跟随路径 → 命中路径目标 → 在保持目标完成要求的操作 → 显示下一段引导 → 完成最后动作段并结算”组成。

- 路线、红色中心控制点、动作提示和目标状态在同一执行页中呈现。红色中心控制点代表摄像头识别到的用户当前头颈位置，随有效输入实时沿路径移动；蓝色目标点代表待完成目标，中央空心环代表回正衔接点，三者视觉上清楚区分。当前动作段由文字、方向箭头和路径共同引导。
- 红色中心控制点有效经过配置的过程目标时，立即触发该目标命中反馈、更新目标状态，并按奖励服务显示元气/灵感图标及分值。目标命中反馈由目标局部的短促压缩回弹、快速扩散的水波纹及向外迸发的小星点组成，目标本体同步显色；效果贴近目标，不遮住控制点、路径或主动作提示。
- 进入配置的保持目标后，进度表现随连续有效操作逐步推进；达到配置条件后播放段落完成反馈，并切换为返回/过渡提示。
- 每个动作段完成后，页面先显示该段完成反馈；控制点回到中央衔接点后，页面再显露下一段的动作提示、路径及目标。控制点到达下一段起点并满足进入条件后，开始追踪新段。用户页面只显示轮次进度（如“第 1/3 轮”）；当前方向、保持或回正通过动作提示表达，不显示“第 1/6 段”。内部六动作段的判定与记录保持不变。过渡与新手势提示在同一执行页连续完成，不插入额外说明页。
- 最后一段完成所需的收尾动作通过后，提交完成事件并进入统一完成页；页面标题、四层结构和账户奖励回执读取《今日行动总体页面架构 PRD》，本 PRD 仅提供动作完成信息和 `science_completion_copy`。

### 2.2 可替换的动作配置

单个动作的运动学参数和动作顺序由独立配置表定义。动作替换时更新配置，不改变上列页面链路与通用反馈机制。

| 配置字段 | 当前“肩颈放松”动作值 | 影响范围 |
|---|---|---|
| `action_id` / 显示名称 | `shoulder_relaxation` / 肩颈放松 | 行动识别、列表、详情及执行标题 |
| `input_mode` | 前置摄像头估计头部左右旋转，控制点跟随 | 输入适配器与控制点映射 |
| `body_setup` | 坐姿，肩放松，下巴水平 | 详情说明与准备提示 |
| `segments` | 左、右交替，共 6 段；每侧 3 段 | 动作段次序、轮次进度、路线生成 |
| `path_targets` | 每段 3 个过程目标，末端 1 个保持目标 | 目标生成、过程奖励事件、段落完成触发 |
| `comfortable_range` | 每次会话分别采集左右舒适参考 | 目标位置与头部输入归一化 |
| `hold_duration_ms` | 2000 | 持续进度显示和保持完成时机 |
| `return_rule` | 每段完成后回到中央稳定区；最后一段回到中央后结算 | 段间衔接与完成条件 |
| `rounds` / `repetitions` | 3 轮；每轮左右各一段 | 进度显示与动作段总数 |
| `durationLabel` | 1 分钟 | 选择页与详情页的整分钟预期时间标签；不作为动作完成条件 |
| `science_card_copy` / `science_detail_copy` / `science_completion_copy` | 见 2.4 | 首页、详情、结算文案 |

动作可以替换方向、舒适角度、段落顺序、目标数量、保持时长、轮次、重复次数、起点与收尾方式。配置描述动作本身的要求；输入映射、目标反馈、段落切换、状态记录和结算仍由通用机制处理。

## 2.3 当前动作科学描述字段

### 2.3.1 当前动作执行内容

| 字段 | 本行动值 |
|---|---|
| 动作名称 | 坐姿左右转头 |
| 起始姿势 | 坐稳，肩放松，下巴水平，手机稳定放在正前方 |
| 动作方向 | 只做左右旋转；不包含侧倾、低头、仰头或绕颈 |
| 单侧动作 | 缓慢转向该侧舒适位置，连续保持 2 秒，再回到正中 |
| 重复次数 | 左右各 3 次；左右各完成一次计为一轮，共 3 轮 |
| 动作边界 | 使用自然、舒适的活动范围完成动作；以当前配置目标作为路径引导 |

### 2.4 三个页面字段

三个科学描述字段随动作配置提供。换动作时同步更新动作参数和文案值，字段职责及页面位置保持一致。详情页依次呈现名称、配图、常驻行为说明、可展开“怎么做”和开始操作；行为说明仅保留依据与练习收获，操作步骤归入“怎么做”，研究来源保留在 B 部分。通用交互机制读取配置驱动路径、目标与阶段提示。

| 字段键 | 页面 | 编写规则 | 本行动示例 |
|---|---|---|---|
| `science_card_copy` | 首页行动选择卡 | 一句话包含可信来源/依据与用户可理解的潜在收获；简短、有点击动机，不承诺即时疗效 | **NHS 的颈部旋转练习，帮助保持颈部活动度与柔韧性，让转头更自在。** |
| `science_detail_copy` | 行动详情页 | 常驻显示行为说明正文与练习收获；正文直接从说明内容开始；不重复“怎么做”的动作步骤，不在产品页展示研究来源署名 | NHS 将颈部旋转列为帮助改善颈部活动度与柔韧性的练习。**练习收获：**为颈部提供温和、重复的旋转活动，帮助维持颈部活动度与柔韧性。 |
| `science_completion_copy` | 完成结算页 | 一句鼓励 + 明确本次完成的练习/对应能力；不声称系统未测量的改善，不把一次练习写成治疗结果 | **完成了 3 轮左右转头！你为颈部活动度与柔韧性完成了一次练习。慢慢回到自然位置，感受一下颈部现在的状态。** |

科学字段显示要求：

- 首页卡片同步显示辅助信息从动作配置生成（当前为“左右转头 · 1 分钟 · 需摄像头”）。
- 详情页把 `science_detail_copy` 放入常驻的“行为说明”区域；“怎么做”可保持折叠；主操作按钮为“准备开始”。行为说明无需勾选确认，不单独弹免责声明。
- 完成页在 `science_completion_copy` 下方显示实际结算回执；若奖励待确认，单独显示奖励状态，不把奖励文案混入科学收获。
- 文案使用“帮助保持/改善颈部活动度与柔韧性”“帮助放松紧绷的颈部肌肉”等有来源支持的目标描述；不得写“50 秒消除颈痛”“治愈颈椎病”“预防损伤”“排出乳酸”“已检测疲劳下降”。
- 相机角度只用于交互判定，不输出为临床活动度、疼痛程度、恢复情况或健康评分。

## 3. 当前动作配置的执行顺序与预计时长

### 3.1 动作段顺序

当前配置为：准备完成 → 左 1 → 回正 → 右 1 → 回正 → 左 2 → 回正 → 右 2 → 回正 → 左 3 → 回正 → 右 3 → 最后回正 → 完成。

当前配置共 3 轮，每轮左右各一段；每段包含 3 个路径过程目标、1 个端点保持目标和一次回正。界面仅按动作配置展示当前轮次；左右方向、保持及回正由动作提示表达，不展示段数。内部仍按 6 个动作段执行判定和记录。更新动作时，动作段数、成组方式、移动顺序、回正要求和预计时长均从对应配置读取。

### 3.2 预计时长与正式时钟

当前动作在首页/详情显示“1 分钟”整分钟预期时间标签。实际执行按用户输入事件逐段推进，不以标签时间自动完成。系统从首段引导显示时记录正式动作经过时间，完成页与准备页不计入；正式完成条件取自当前动作配置定义的动作段、保持和收尾事件。

## 4. 页面与跳转

今日行动选择 → 行动介绍 → 摄像头与动作范围准备 → 正式执行 → 完成 / 未完成结果 → 今日行动。

首次授权系统框仅在点击“开启摄像头”后出现。介绍与准备保留为两个页面；准备内的对准、左右学习与试玩是同页逐步状态，不连续弹教学对话框。

### P0 今日行动选择页

沿用已定布局和浅色配色。名称“肩颈放松”，行为类别“肩颈放松”，科学短描述读取动作配置，预计时长、设备标签和今日状态读取对应配置与今日行动服务。点击卡片进入 P1。已完成是否允许重做、每日奖额仍由今日行动统一规则提供，不在本行动自行决定或添加禁做状态。

### P1 行动介绍页

信息主顺序：返回 → 标题“肩颈放松” → 蓝白水彩质感目标缩略 → 常驻“行为说明” → 可展开“怎么做” → 主按钮“准备开始”。价值说明、动作配置生成的动作摘要、准备与适用说明分别并入对应内容区，不插入独立层打断该顺序。

- 操作说明：“沿路径依次命中小目标；到达较大的目标后保持 2 秒，完成反馈后回到正中。”
- 实际场景说明：“坐稳，双肘有支撑，手机放在正前方并保持稳定，肩放松、下巴水平。”按日常可用的手机摆放方式准备。
- 可见简短停止提示：“出现疼痛、头晕或不适，请停止。”展开项补充：近期颈部损伤/手术、已诊断颈部疾病或明显症状者不按本行动自行康复，应遵循专业指导。
- 非首次也保留本页；行为说明持续可见，“怎么做”沿用折叠规则。无“我已阅读”勾选、无单独免责弹窗。
- 返回不提示丢失进度，因为正式行动尚未开始。

### P2 摄像头、舒适范围与控制准备

1. **权限未授予**：说明“用前置摄像头让光点跟随转头。画面在设备上处理。”主按钮“开启摄像头”；返回可用。后半句是开发必须实现的隐私契约，若技术方案改变，必须同步改文案并重新评审。
2. **授权成功**：显示小幅实时人脸预览与对准框；正文“正视屏幕，让手机保持稳定”。检测单张脸、输入稳定后，记录当前正前方基线，光点进入中央。
3. **学习左侧舒适范围**：正文“轻轻向左转，到舒适位置即可”；底部固定按钮“这里合适”。用户在舒适位置确认左侧参考；随后明确“回到正中”。
4. **学习右侧舒适范围**：同左侧，单独记录；左右参考分别记录。
5. **回到中央**：简短原位演示“沿路径命中 → 大目标保持 2 秒并逐渐填色 → 回正换侧”。提供“声音开 / 关”和“震动开 / 关”控件，沿用系统偏好；底部“开始行动”。按下前不启动正式时钟。

范围学习在每次正式会话执行，分别采集当前动作所需的参考范围。按“这里合适”时读取点击前的稳定样本。若信号暂时无法稳定或与噪声难以区分，提示调整手机/光线并重新采样，或结束准备。

摄像头拒绝：同页持续说明“需要摄像头才能识别转头并移动控制点”，按平台能力显示“重试授权”或“前往设置”，以及返回。不得悄悄以手指拖动替代头控并记为完成。多人入镜、设备不支持、初始化失败分别给具体原位说明；不循环弹系统授权框。

### P3 正式执行页：布局

- 顶部：左侧显示当前动作名称“肩颈放松”；右侧退出 X；下方仅显示轮次进度（如“第 1/3 轮”），不显示动作段计数。
- 游戏有效区域左右留至少 24 dp。当前配置中央起点固定 x=50%，左右目标端点约 x=12% / 88%（相对于有效区域）。其他动作按配置设置起点、终点和路径坐标。
- 当前只突出当前动作段路线；当前配置在中央至端点的 22%、45%、68% 位置放置 3 个小型过程目标，端点放置大型保持目标。其他动作读取目标数、目标类型及位置配置。
- 当前头颈位置控制点：珊瑚红实心中心点，外加清晰的浅色细边/轻微光晕；它随摄像头有效输入沿路径实时移动，代表用户此刻被识别到的位置。控制点与蓝色目标、目标命中光效及中央空心回正环必须明显区分；不得将红点用作路径装饰或固定在某一目标上。
- 路径线与箭头展示当前段移动方向；回程路径展示返回下一动作段起点的方向。
- 小型目标建议视觉直径 12–16 dp，大型保持目标约 48 dp，进度环约 60 dp；目标判定继续使用独立的宽容区域。目标采用清晰的圆形结构，蓝白水彩笔触直接成为目标本体的填色/命中状态，呈现半透明叠色、颜料晕染和松散边缘。最终美术尺寸随屏幕适配，中心、方向、目标大小层级和状态保持清晰。
- 游戏区下方固定一行主动作提示，最多一行辅助提示；底部保留小型“不舒服，结束”入口。主要动作不能只靠颜色或声音表达。
- 执行区沿用近白底 #fafaf9、正文 #24272b、主蓝 #416a9b。红色控制点实时跟随识别到的头颈位置；有效经过蓝色目标才算命中。命中瞬间目标先短促压缩再回弹，目标本体由中心向外显色；同时从目标边缘快速荡开一至两圈局部水波纹，并迸发少量小星点，形成清晰的“啪”式击中感。水波和星点以目标为中心，在邻近区域迅速淡出，不扩展成全屏效果、不遮住动作路径和主提示。保持目标按有效保持时长从内向外分层填色，达到要求后再播放更强一级的局部水波与星点完成反馈。画面展示动作游戏区，摄像头使用状态遵循系统规范。

### P3.1 动作段之间的衔接

- 保持目标满足当前动作配置条件时，立即显示该段完成反馈，并将主提示切换为本段的回正或下一步动作提示。
- 控制点按当前路线回到配置的过渡点；回正通过后，当前目标组淡出，下一动作段的路线、目标、方向提示和进度编号同步显露。
- 下一段目标组的位置与当前配置的输入方向一致；方向语音/提示在新段开始时播放一次，控制点以当下实时输入驱动。
- 每完成配置的一个动作段，内部段落状态立即更新；用户可见轮次进度按配置的分组规则更新，方向、保持及回正状态由动作提示表达。
- 最后一段完成所需的收尾动作通过后，进入完成结算页，展示本次动作完成内容与奖励服务回执。
- 过渡动画与路径显露可重叠播放；新动作提示在目标可见时同步出现，用户能连续理解“上一段完成 → 回到衔接点 → 下一段开始”。

### P4 完成页

最后一段要求的回正通过即判定本次动作完成并提交完成事件。随后进入《今日行动总体页面架构 PRD》的完成结算页；完成标题、固定四层结构、账户奖励状态和返回入口均按总 PRD 展示，本 PRD 提供 `science_completion_copy` 及本次动作完成信息，不单独定义结果页标题或布局。

途中命中提示使用当前 session 的过程分值映射；账户奖励只在首次有效完成后由总 PRD 的 completionId 奖励事务结算。奖励处理中、失败或未知时，完成记录仍保持有效，页面显示总 PRD 定义的奖励状态和查询入口。

### P5 未完成页

标题“本次未完成”；按原因显示“已退出本次行动”“这次先到这里，休息一下”“未能稳定识别，本次先结束”等，并根据状态显示对应收尾提示。主按钮“返回今日行动”。只有非不适原因可有次按钮“重新准备”，从 P2 完整重新进入，不续接路径命中或保持进度。不适退出不推送立即再练。

## 5. 通用动作阶段提示与反馈

| 阶段 / 触发 | 屏幕固定文案 | 声音 | 动画 / 触觉 | 弹窗 |
|---|---|---|---|---|
| 首个动作段引导出现 | 由动作配置生成的首段动作提示 | 播放与动作配置对应的首段提示一次 | 按动作段方向展示对应箭头，控制点由实时输入移动 | 不弹 |
| 进入后续动作段 | 由动作配置生成的动作提示 | 对应动作提示一次 | 当前路线收束后显示下一段路线和目标，衔接完成后立即开始新阶段 | 不弹 |
| 控制点有效经过第 1、2、3 个小目标 | 原动作文案保持 | 命中瞬间播放一次短促、清晰的目标命中音；音高可按顺序轻微变化，响度不递增 | 目标本体先轻压缩后回弹，水彩颜色由靶心向外快速填亮，伴随短促颜料飞溅/扩散点；目标转为已命中状态。按服务配置显示当前 session 的过程分值和元气/灵感映射图标；该分值不代表账户到账。无过程分值配置时只显示命中确认。轻触觉可用，限频；不切开、不爆裂 | 不弹窗、不阻断；过程反馈贴近命中点后淡出 |
| 控制点进入大型保持目标且输入有效 | 保持 2 秒 / 停在这里即可 | “保持”一次；语音提示“保持”一次，进度由目标填色呈现 | 大目标出现清晰的未完成态；水彩填色从靶心开始，进度从 0% 启动 | 不弹 |
| 有效保持中 | 保持 2 秒 | 不增加重复语音；保持阶段不循环音效、不逐阶段催促 | 着色进度与连续有效保持时长严格同步：从内向外依次填色，未满 2 秒时只显示相应比例，不提前完成。目标轻微呼吸/明度变化持续表示输入仍有效；离开目标后按 §7 清零并在 200–250 ms 内柔和退回未完成态 | 不弹 |
| 连续有效保持达到 2 秒 | 轻轻回正 | “回到正中”一次；命中完成音与单次稍清楚的触觉同步。不加全屏震动 | 最后一圈在 2 秒判定点填满；靶点出现较强但短促的水彩扩散/外环弹开。若该保持有配置奖励，同步显示元气/灵感图标与配置分值；回正箭头立即出现，不等余效结束 | 不弹窗、不阻断 |
| 回正过程中 | 回到正中 / 跟随箭头回到起点 | 不反复催促 | 控制点回移，中央环高亮；没有新奖励 | 不弹 |
| 当前段衔接条件通过，仍有后续动作段 | 下一段动作提示 | 播放与下一段配置对应的提示一次 | 更新阶段/轮次，替换路线与目标并显露新引导 | 不弹 |
| 最后回正通过 | 本次行动已完成 | 温和完整收束音 | 完成运动状态机并进入 P4；动作完成与记录提交同步触发 | 不弹，直接结果页 |

动效建议：小目标命中压缩约 80–120 ms，回弹、水波扩散与星点余效约 300–500 ms；命中音/轻触觉与目标接触同帧触发。大型目标填色按真实有效保持时长推进，完成时触发更明显但仍局限于目标邻近区域的水波与星点，余效约 300–500 ms，可与回正提示重叠。目标本体、局部水波和星点共同制造冲击感，不使用全屏闪烁、镜头震动/缩放或长时间停顿，避免干扰前摄跟踪与控制。所有数值须真机调校；不能为等待动画延长颈部保持。快扫过多个目标时按顺序补绘已发生的接触，奖励提示不堆叠挡住路线、不诱导快速甩头。



普通动作提示在状态进入时替换并持续到该状态结束。关键语音在状态进入时播一次；状态切换时同步切换当前语音提示。小目标命中音降低响度以让动作语音清楚；静音和关闭触觉时仍以填色、状态和分值提示表达命中，保持文字、箭头、目标状态与分值提示同步表达当前阶段。减少动态效果时保留渐进填色和完成状态，使用低幅度回弹/水彩扩散。

## 6. 识别、映射与判定

### 6.1 输入能力

采用设备端人脸方向估计（如 face Euler Y / yaw）驱动水平位置，鼻部标记只用于预览辅助；不能只拿鼻子在画面中的横向平移宣称已测到颈部旋转。采用何 SDK 由实现选择，但必须提供头部方向、跟踪有效性与时间戳。

前摄估计是头相对相机的方向，不是精密颈椎角度测量。设备平移、身体随头转、遮挡等可能影响识别；本版不承诺“已自动验证肩膀完全不动”。靠背、肘部支撑与准备教学降低代偿；手机自身运动可作为无效输入提示的辅助信号。若端侧模型无法稳定区分输入，不能上线为已可靠检测的运动产品。

### 6.2 会话映射

- 记录中心 yaw 基线及用户主动确认的左右舒适参考，分别计算两侧相对范围。映射方向需经真机测试，保证用户实际向左转头，红色中心控制点向屏幕左侧走；镜像预览不能反转指令。控制点沿配置路径连续表达当前识别位置，红点到达目标判定区时才触发该目标命中。
- 舒适参考定位为对应侧大型保持目标中心，回正定位为 x=50%。超过参考不再外移目标、不生成额外奖励，也不增加填色速度。
- 大型保持目标使用舒适参考附近的宽容区域，进入/离开采用滞回，减少边界抖动。小目标依据有效输入的连续区间跨越逐一命中；不要求垂直像素描线。
- 保持必须在跟踪有效且位于端点有效区的连续时段内满足 2 秒；相机无数据、超时样本和跨后台间隔不可累计。识别正常的微小抖动由滤波与滞回处理，不反复清零。
- 回正需进入中央有效区并短暂稳定，初值 300 ms；确认后只触发一次阶段切换。该值是防误触工程参数，不是额外健康保持要求。
- 样本按捕获时间戳单调处理；初值为相邻有效样本间隔不超过 200 ms、样本到达处理时距捕获不超过 200 ms。重复、乱序、过期样本丢弃；超过间隔阈值立即将连续保持清零。不能用两个相距 2 秒的样本证明连续保持。该 200 ms 是工程新鲜度初值，须按目标设备验证。

### 6.3 工程初值与待测项

| 项目 | 原型初值 / 策略 | 上线验证 |
|---|---|---|
| 中心采样 | 连续约 800 ms 稳定样本 | 不把启动抖动记录为正中 |
| 左右参考采样 | 用户按“这里合适”前约 300 ms 的稳定样本 | 点击晃动不改变范围；不追求最大活动度 |
| 可分辨范围 | 参考与中心差异必须显著超过本会话稳定噪声；初值为噪声标准差的 6 倍 | 不可分辨时调整拍摄条件，不要求加大动作 |
| 目标进入区 | 归一化单侧范围约 0.90–1.10 | 仅为命中容差，不输出为医学角度 |
| 目标离开区 | 超出约 0.85–1.15 才退出保持 | 参数不得使小范围用户受噪声触发 |
| 中央有效区 | 单侧归一化幅度绝对值 ≤0.10，持续 300 ms | 非对称左右范围分别归一化 |
| 目标命中输入 | 有效连续轨迹完整跨越当前小目标；每个目标每侧仅触发一次；上一帧缺失时不能跨缺口补算 | 模拟瞬移/掉帧不可一口气取得全部奖励；小目标命中只给过程反馈，不决定动作是否完成 |
| 样本时效 | 相邻间隔与处理新鲜度均 ≤200 ms，超时立即清零连续保持 | 两个相隔 2 秒的点、缓存补发或重复帧均不能完成保持 |
| 提示延迟 | 无效立即停止计数；持续约 300 ms 才显示丢失提示 | 显示延迟不等于计数宽限 |
| 连续丢失 | 10 秒仍未恢复则本次未完成结束 | 按跟踪恢复规则提示下一步动作 |

所有工程初值应配置化。完成真机测量前不得用这些阈值宣称医学动作准确。开发可以先实现状态机、界面和模拟输入；真实识别发布须通过 §10。

## 7. 偏离、异常、退出与提示优先级

| 事件 | 当下处理与提示 | 恢复 / 结束规则 | 是否弹窗 |
|---|---|---|---|
| 保持中明显离开端点 | 立即停止有效计时；显示“轻轻回正，再试这一侧”，中央回程箭头出现 | 当前未完成的 2 秒计时与对应填色清零；已命中小目标保留，奖励不重复触发。回正后大型保持目标恢复未完成态，再尝试本侧；不补左右时间 | 不弹；正式总时钟继续 |
| 单帧/短暂丢失 | 红色控制点灰化、不外推；保持连续计时清零 | 恢复后按阶段处理；若刚在保持，先回正再试，避免长时间悬在端点 | 不弹 |
| 丢失持续超过 300 ms | “请正对屏幕，让手机保持稳定”；若在侧端点先提示“轻轻回正” | 恢复稳定后继续当前未完成侧；丢失 10 秒或达到跟踪结束条件后结束本次行动 | 不弹，原位持续提示 |
| 手机明显改变位置 / 多人入镜 | 停止计数，提示“请稳住手机” / “请让画面中只保留你” | 基线失效时结束本次，提供重新准备，不在正式行动里悄悄重设中心 | 不弹 |
| 点 X / 系统返回 | 打开“退出本次行动？”；正文“退出后，本次进度不保留。”并保留“轻轻回正”提示 | 按钮“继续本次 / 退出行动”。对话框期间停止输入采集；取消后先确认正中再继续当前动作段 | 弹唯一的主动退出确认 |
| 点“不舒服，结束” | 立即停止判定和采集；语音“停止练习，回到舒适姿势” | 本次未完成，不要求再做一段回正测试，不推立即重练 | 不二次确认 |
| App 进入后台 / 锁屏 / 系统打断 | 完成事件提交前，结束本次正式行动并关闭相机 | 未完成会话回来显示“本次行动已结束，进度未保留”，去 P5；不支持续接。完成事件已提交时，按《今日行动总体页面架构 PRD》进入公共完成结算页并保留完成记录及奖励状态 | 不弹退出确认 |
| 系统音量为零 / 触觉不支持 | 保持文字、箭头、目标填色阶段与分值提示 | 不改变有效判定，也不弹设备能力提醒 | 不弹 |
| 正式行动中网络断开 | 相机与状态本地继续 | 若本地完成，持久化待同步记录；恢复网络后重查同一记录 | 执行中不弹网络框 |

提示优先级：不适结束 > 相机及位置问题 > 回正/重试 > 当前动作 > 命中奖励提示。屏幕同时最多一条主指令和一条辅助说明；短暂奖励浮层不得遮挡路线或主要动作提示。未知错误不能盖在“保持 2 秒”上仍继续催用户保持。

**中断恢复的精确分界：**若该侧保持尚未满 2 秒，退出框取消或跟踪恢复后，当前保持与填色清零，回正确认后重做当前侧；已命中的小目标不重复计分或弹奖励。若已满 2 秒、正在 RETURN_CENTER，则在本次仍有效的会话内保留“该侧保持已完成”标记，只补回正确认，随后进入下一侧，不再要求重复保持。不适、主动确认退出、基线失效、后台或超时均为终止，不适用此恢复规则。终止后的下一次会话从零开始。

## 8. 完成条件、记录与业务字段

### 8.1 正式状态

会话内部状态：PREPARE → MOVE_SEGMENT → HIT_TARGETS → HOLD_TARGET → TRANSITION / RETURN_CENTER → NEXT_SEGMENT / COMPLETE。实际状态由动作配置生成；跟踪恢复与退出确认作为通用中断状态。终态为 COMPLETE / INCOMPLETE。

完成必要条件由动作配置定义的各动作段全部完成及要求的最后回正事件通过构成。通过后提交一次完成原子事件，随后导航至结果页；页面跳转不参与完成判定。

退出或重新开始不可把前次保持拼入后次。终态不可回退；动画退出、奖励超时或重复请求不使已完成变未完成。

### 8.2 字段语义

| 字段 | 来源 / 格式 | 更新与显示 |
|---|---|---|
| 行动标识 / 方案版本 | `shoulder_relaxation` / 当前动作配置版本 | 与总 PRD 的 `behaviorId` 一致；与完成记录一起保存，区分后续动作配置版本 |
| 会话标识 | 每次正式开始生成唯一值 | 完成提交、重查和奖励幂等依据 |
| 适用人群 / 科学来源版本 | 内容配置 | P1 展示必要适用说明；科学来源版本在产品说明中维护，更新须审查动作差异 |
| 动作配置版本 | 参数化配置对象 | 页面、输入判断、状态机、段落提示及验收读取同一版本 |
| 当前轮次 / 当前动作段 / 当前阶段 | 本地状态机 | 驱动红色控制点、路线、箭头、目标、文案及下一段衔接 |
| 侧段完成数 | 0–6 | 每侧保持后仅预标记，回正后确认该侧完成 |
| 本侧已命中小目标数 | 0–3 | 驱动目标已命中状态；单目标事件去重；不作为运动完成独立凭据 |
| 当前连续有效保持时长 | 0–2000 ms | 驱动大型目标从内向外填色；退出有效保持按 §7 清零 |
| 本次过程分值提示 | 当前 session 的目标命中反馈映射 | 展示本次过程分值；不记入账户，不单独创建到账记录 |
| 正式已用时间 | 单调时钟毫秒 | 展示当前动作实际执行时长并记录会话数据 |
| 跟踪可用性 / 位置基线 | 端侧模型与会话准备 | 原始图像不入日志；基线结束后销毁 |
| 完成结果 / 中止原因 | 完成或未完成 + 枚举原因 | 结果页和分析使用；未完成不展示百分比成就 |
| 今日行动计数资格 | 既有今日行动服务返回 | 本行动仅提交真实完成事件，不自行改变任意 3 项规则 |
| 奖励资格 / 到账状态 | 既有服务返回 | 可为不发奖、待确认、已到账；与运动终态分离 |

### 8.3 持久化与资源边界

保留已完成记录及结算重查标识；未完成的可续练状态不持久化。可记录必要的中止原因与时长统计，但不能在下次恢复原路线。原始相机视频、截图、完整人脸轨迹不得保存或上传。

重复提交使用同一会话标识去重；离线完成先保存本地结果，联网后提交同一事件。今日重复该行动是否给奖励、完成三项后是否仍可进入，调用现有今日行动统一规则；本 PRD 不擅自把尚未确认的业务方案定成新规则。返回列表时刷新权威状态，结算失败不能诱导用户重复做动作。

## 9. 素材与开发拆分

美术最小清单：中央空心起点、珊瑚红实时控制点、小目标待命/命中状态、大型保持目标未完成/渐进填色/完成状态、局部水波纹与迸发星点、左右路线箭头、3 轮进度文字样式、元气与灵感图标及浮动分值样式。水彩笔触用于目标本体的填色与命中反馈；水波纹和星点围绕命中目标短暂扩散；背景不设置外围鱼群或环形装饰。目标数量、路线和阶段状态按本 PRD 配置。声音包括小目标命中音、保持开始提示、保持完成提示与全程完成音；触觉仅在已定义的命中/完成事件轻触一次，不在保持过程中连续震动；语音包含左右、保持、回正、识别恢复、结束。

首轮开发顺序：页面字段与状态机 → 模拟输入走完整流程 → 真机前摄/镜像映射与舒适范围准备 → 动画/音触觉同步 → 结果及幂等。评审稿的控制点不得由定时器自动走完全程来冒充实际检测。

## 10. 可验收标准

| 编号 | 场景 | 必须观察到的结果 |
|---|---|---|
| A01 | 首屏布局与左/右段 | 起点在有效区域精确水平中央；左右端点镜像；不复用旧图的右侧起点 |
| A02 | 未听讲解的首次理解测试 | 目标用户能指出自己控制哪个标记、首段往哪走、哪里停、完成后回哪；至少做 5 人小样本，记录困惑，不将此当健康研究 |
| A03 | 左右实际转头 | 光点随实际方向对应移动，镜像开关和前摄方向不反转指令 |
| A03a | 首次观察执行页 | 用户能区分珊瑚红实时控制点、蓝色待命/命中目标和中央空心回正点；红点随有效头颈输入移动，只有红点实际经过目标才触发该目标反馈 |
| A04 | 仅移动手机 / 整体挪动身体 / 遮挡 | 核对误判；不能只因鼻尖横移就宣称颈部旋转正确。达不到稳定标准时阻断正式发布并调整识别方案 |
| A05 | 有效保持 1.9 秒离开 | 大目标仅显示未完成填色；离开后按规则清零，不与下一次短保持拼成 2 秒 |
| A06 | 连续有效保持 2 秒 | 填色在 2 秒判定点完成一次，并触发较强视觉/音触反馈与回正提示；不等长动画结束才让用户回正 |
| A07 | 相机掉帧/跟踪丢失 | 缺失时间不累计；目标不会被虚拟轨迹一口气采完；恢复按 §7 执行 |
| A07b | 两有效帧间隔超过 200 ms / 旧帧补发 | 连续保持清零；恢复后须重新连续有效 2 秒，不因时间戳跨度直接完成 |
| A07c | 当前段完成、过渡中打开退出框后取消 | 保留当前段完成状态；回到对应的过渡提示后进入下一动作段 |
| A08 | 全程正常完成 | 左右各 3 次、每次 2 秒、最终回正后完成；预计时长来自当前动作配置，阶段按真实事件推进 |
| A09 | 动作段衔接与退出确认 | 每段完成后显示下一段提示、路径和目标；页面仅更新轮次进度与动作提示，不出现“第 1/6 段”等段计数；内部段落判定照常更新，最后一段完成后进入结算 |
| A10 | 不适退出 / 后台 | 立即结束、无续练、无逼迫回到检测点才能离开的条件 |
| A11 | 静音 / 关闭触觉 / 减少动态 | 仍能靠主文字、箭头、目标状态完成，不丢关键信息 |
| A12 | 390 px 及更小支持屏幕、系统大字号 | 目标、路线、提示不截断重叠；退出与不适结束始终可达 |
| A13 | 重复提交 / 离线后重连 | 同会话只完成/结算一次；奖励失败不要求用户重做 |
| A14 | 相机权限拒绝 / 多脸 / 参考范围不可分辨 | 无虚假成功、无要求扩大颈部幅度来通过；有明确设置/返回路径 |
| A15 | 有效经过小目标 | 命中时目标短促压缩回弹，局部水波纹荡开并迸发少量星点；水彩填色与命中音/轻触觉同步；过程反馈按映射显示本次分值和对应元气/灵感图标，不表示账户到账；不切片、不生成连击倍率；同一目标不重复触发 |
| A16 | 配置保持目标进度 | 填色比例与配置中的连续有效时长一致；达到设定值时完成反馈与下一步提示立即出现 |
| A17 | 路过但漏掉一个小目标 | 不显示该目标的过程分值，但动作仍可按有效端点保持与回正规则继续完成，不诱导用户加大转头幅度补追 |

健康内容发布前，需由具备相关资质的人员审阅适用性及文案；真实手机检测需要在目标设备上验证。文档本身已经选定动作与参数，这两项验证不以“做过竞品调研”代替。

## 11. 公共服务接口与实现约束

客户端必须调用今日行动统一服务获取重复行动资格、完成奖励配置与目标命中过程反馈映射；本行动只提交真实命中/完成事件，不自行计算账户奖励额度或决定已完成行动资格。目标命中产生的过程分值只用于本次会话反馈；账户奖励由首次完成对应的 completionId 事务返回。服务返回的账户奖励类型、数值、资格和到账状态作为页面结算的唯一依据。

工程阈值为明确的可配置初值，真机验证后修订并留版本。若验证结果与舒适范围、动作时长与配置冲突，必须回到动作/时长评审，不悄悄降低完成条件或播放动画代做。


# B. 产品说明 / 评审备注（本模块可整体删除，不作为开发规格）

## 1. 动作依据与文案边界

- NHS 是英国国家医疗服务体系发布的官方公众健康信息来源，可作为一般健康练习与动作说明的权威来源；它不是本行动的临床试验，也不意味着每个动作剂量均由独立试验验证。
- NHS 柔韧性练习页将颈部旋转描述为改善颈部活动度和柔韧性；NHS inform 颈部练习页给出舒适范围内转头、每侧停留 2 秒、初次 2–3 次等执行指导。本 PRD 采用每侧 3 次及 2 秒保持。
- 研究和官方建议支持动作的目标与入门执行方式；没有证据证明本产品约 50 秒游戏能立即消除疼痛或改善颈部功能。详情文案因此说活动度/柔韧性练习的目的，不把活动效果承诺为治疗效果。
- 来源：
  - NHS — [Flexibility exercises](https://www.nhs.uk/live-well/exercise/flexibility-exercises/)：颈部旋转与活动度、柔韧性的目标说明。
  - NHS inform — [Exercises for neck problems](https://www.nhsinform.scot/illnesses-and-conditions/muscle-bone-and-joints/neck-and-back-problems-and-conditions/exercises-for-neck-problems)：Head turn、舒适范围、保持时长、初次重复次数及停止提示。
  - RJAH — [Neck Pain](https://www.rjah.nhs.uk/our-services/therapy/supported-self-care/neck-pain/)：坐姿、头部转动与舒适范围补充；未采用该页不同剂量。

## 2. 机制与反馈设计依据

反馈方案依据：Fruit Ninja Kinect 2 的官方说明把多目标命中与组合奖励关联；动作游戏影响感研究总结命中动画、音效同步等可共同加强命中感，也提醒反馈过量会影响清晰度。本行动借用“命中立刻确认、分值紧跟、保持进度连续可见”的节奏，不复制切开水果、连击竞速、炸弹惩罚或快速挥动要求。这里“目标局部压缩 + 水波纹/星点扩散 + 同步音效 + 水彩填色/奖励图标”的组合，是依据现有研究和颈部头控情境作出的产品设计推断；不采用镜头抖动/缩放或全屏 hit-stop，以免扰动实时头控画面。


- 参考论文：[Camera-Based Monitoring of Neck Movements](https://pmc.ncbi.nlm.nih.gov/articles/PMC8004650/) §3.1–3.1.3、图 7–8。论文原型提供前摄头控、按序选择圆形目标等交互参考；本产品的路径、目标和动作剂量均由产品配置定义，不能表述为论文验证。
- 游戏反馈参考：[Fruit Ninja Kinect 2 官方手册](https://dlassets-ssl.xboxlive.com/public/content/866f0a16-3a62-4e82-a72b-62e8e655761d/GameManual/0bbf3c90-1ccf-4c46-b227-79f91cc185bf/en-US/index.html)中的即时命中与分值关联；[动作游戏命中反馈研究](https://arxiv.org/abs/2208.06155)讨论动画、音效等对命中感的影响。将其迁移为本产品的水彩填色、局部回弹、同步音效和奖励图标属于设计推断，不是医疗或本产品可用性证据。
- 前摄方向估计能力参考：[Google ML Kit — Face detection concepts](https://developers.google.com/ml-kit/vision/face-detection/face-detection-concepts)。人脸方向估计不等于临床颈椎角度测量。

## 3. 决策记录

- 普通久坐人群为初始使用人群；此功能不是康复处方。
- 当前功能名为“肩颈放松”；执行画面采用红色实时中心控制点、路径和蓝色圆形目标，水彩质感用于目标本体反馈。红色控制点表示实时识别位置，不表示目标或奖励图标。
- 页面状态参考：[肩颈放松_未完成轨迹参考图.png](../references/shoulder-route.png)；原位命中反馈参考：[肩颈放松_红点水波击中示意图.png](../references/shoulder-hit.png)。两图沿用既定执行页布局，用于核对轨迹与目标局部反馈。
- [视觉参考图_水彩目标质感.png](../references/shoulder-material.png)只用于目标本体水彩材质参考，不作为页面构图、动作路径或交互规则参考。
- 用户确认小目标命中要即时反馈；保持目标须在完整保持期间持续显示未完成进度，满 2 秒才完成；元气/灵感只按既有奖励服务显示。
- 路径、动作段、目标类型、保持时间、回正、方向、次序与轮次均由动作配置定义。通用页面、交互反馈、状态管理和奖励机制保持稳定。
- 当前执行画面采用路径控制点与目标反馈；用户提供的参考图仅指导水彩质感。

## 4. 尚待外部验证的事项

- 具备相关资质的专业人员须在健康内容发布前审核动作适用性和用户文案。
- 真机需验证前摄镜像映射、舒适范围学习、肩/躯干代偿误判、掉帧恢复、触觉与音效同步、不同屏幕尺寸及减少动态模式。
- 小目标过程奖励类型/数量和最终奖励资格由今日行动统一奖励服务提供；本行动不定义兑换率或钱包规则。
- 当前动作预计约 50 秒是动作配置提供的参考时长，后续动作按各自参数调整，不设统一执行时长上限。
