# 双手画形 PRD

## 1. 行为配置

| 字段 | 类型 | 值与规则 |
|---|---|---|
| catalogKey / section | string | `hands_shapes` / `hands-shapes` |
| taskId | string | `gentle:20261009:body-triangles-sticks`；科学文案和动作条目键 |
| behaviorId / variantId | string或null | `gentle:20261009:body-triangles-sticks` / `null`；null不可作为正式完成标识提交 |
| behaviorName / categoryId | string | 双手画形 / `agility` |
| durationLabel | string | `30秒`；仅入口预计时间，不是播放预算或动作剂量 |
| deviceRequirements | array | [camera]；使用前置摄像头识别左右双手的位置，不申请麦克风；授权与异常处理复用肩颈放松 |
| illustration | 资源引用 | 统一页hands-shapes配图；入口与详情共用 |
| science.shared | string | 调动大脑双侧运动控制网络，提升手脑协调性与双侧独立控制力。 |
| science.completion | string | 经典双侧运动实验证实，当左右手同时绘制不同几何图形时，大脑必须调用辅助运动区（SMA）与胼胝体抑制回路，克服双肢天然的“空间耦合”干扰。刚才的双手分控，正是在挑战高阶的双侧独立运动控制。 |
| steps | string[] | 下列顺序常驻展开 |
| rewardType / rewardAmount | enum / integer | energy（元气） / 15；奖励配置不代替真实回执 |

`steps`：

1. 坐稳，双脚着地，把手机放在前方看得到的位置。
2. 双手自然握拳，抬到舒适高度，让双拳和手腕完整入镜，不用用力攥紧。画面左侧对应你的左手，右侧对应你的右手。
3. 先看上方示范：左手连续画圆，右手沿三角形在角点换向。
4. 双手识别就绪后开始。两手同时在空中画形，每轮8秒，共2轮；上方看示范，下方看两只手留下的轨迹。
5. 收束时慢慢放下双手、放松。

| 执行配置 | 类型 | 值与校验 |
|---|---|---|
| pathVariant | enum | circle-triangle；左圆、右三角形 |
| demoMs / cycleMs / totalCycles / endingMs | integer，毫秒 / integer | 6000 / 8000 / 2 / 2700 |
| totalGuideMs | integer，毫秒 | 24700；示范6000＋跟做16000＋收束2700 |
| targetPaths | object | 左圆、右三角的完整目标路径及顶部起点；每轮各绕一周；与下方对应轨迹左右一致 |
| trajectorySource | enum | 正式执行为hand_tracking，来自本次摄像头的双手位置；低保真样例为simulated_fixture，只作状态展示，不生成用户轨迹或业务证据 |
| trackingTarget / trackingPoint | enum | both_hands / palm_center；识别各手的手腕与掌部，取掌部中心作为笔尖，不用头、肩或指尖驱动笔迹；握拳是动作提示，不设握拳评分 |
| cameraFacing / mirrored | enum / boolean | front / true；左右手身份按用户身体侧别，镜像画面左侧对应用户左手；显示坐标只镜像一次 |
| readyCondition | 条件 | 权限允许、相机可用、同一用户两只手和手腕完整可见、左右身份可区分、两手跟踪点均有效；全部满足才启用开始练习 |
| recognitionConfig | object或null | 模型与适用设备、位置置信门限、有效识别稳定窗口、异常跳点门限；数值按识别验证回填，不使用肩颈角度与舒适转头范围 |
| traceStyle | object | 当前轮累计笔迹、当前位置、短尾；第2轮保留第1轮淡迹；轨迹按实测位置保留偏差，不吸附目标、不补成圆或三角；缺失区间断开 |
| mediaSource | 资源引用或null | 正式连续动画或视频资源，须含完整示范、2轮跟做及回位收尾 |
| cueTimeline | object[]或null | 每项cueId、phase、startMs、endMs、prompt、aux、cycleIndex；共用同一媒体时轴，区间前闭后开，无重叠倒序 |
| completionPolicy | object或null | null；正式业务必填，含policyId、服务校验规则及所需独立证据；播放结束不得推断身体完成 |

正式开始前校验身份、摄像头、双手跟踪、recognitionConfig、媒体、时间轴和completionPolicy；缺少必填配置时，业务开始禁用，不能提交完成。预览仅演示权限和识别状态，不请求系统权限，不创建业务完成或奖励。入口30秒仅为预计展示值。

## 2. 页面、字段与操作位置

| 页面 | 区域及顺序 | 字段与操作 |
|---|---|---|
| 今日行动 | 卡片 | 左配图；右名称与durationLabel，下方science.shared及元气图标；完成状态读取服务 |
| 行为详情 | 自上而下 | 返回、名称→配图→“行为说明”及science.shared→“怎么做”及steps→底部主操作；方法不折叠 |
| 行为详情 | 底部 | 未完成配置有效时“准备开始”进入摄像头准备；配置缺项“暂不可开始”；请求中禁用；今日已满3项禁用；已完成左查看结果、右再练一次 |
| 摄像头准备 | 公共容器 | 复用肩颈放松的返回、标题、矩形取景框、状态提示和底部操作；未授权说明“用前置摄像头识别双手，让下方笔迹跟随你的移动。画面在设备上处理。”；主操作开启摄像头 |
| 双手入镜 | 取景区 | 用左右双拳与手腕轮廓替换头肩轮廓；上方“举起双手，让双拳和手腕完整入镜”，左右下方分别显示未识别/已识别；头和肩膀不作就绪条件 |
| 双手入镜 | 底部 | 未就绪显示禁用的开始练习；双手就绪后启用开始练习；不增加左右手分步确认或转头范围校准 |
| 行为执行 | 顶部 | 左退出、右声音开/关，下方行为标题；通过双手准备后进入执行 |
| 行为执行 | 上方目标与示范区 | 左圆、右三角，完整浅色目标路径常驻；顶部起点与方向清楚。示范期突出当前位置，跟做期弱化；不放镜像人物 |
| 行为执行 | 中间提示区 | prompt及aux原位替换，不覆盖上下路径；示范“先看两手的路线”，跟做“两手一起，慢慢画”，收束“画到这里，放松双手” |
| 行为执行 | 下方完整轨迹区 | 左右对应显示用户双手的累计轨迹、当前笔尖和短尾；完整画布始终可见。第2轮保留前轮淡迹，不裁成短窗口或横向节拍带；丢失时保留旧迹并隐藏失效笔尖 |
| 行为执行 | 底部 | 示范/跟做/收束进度及“不舒服，结束”；结束显示引导结束，不显示用户画对数 |
| 结果 | 四层位置 | 引导事实或有效完成标题与科学文案→真实元气回执→今日进度→立即可用的返回今日行动 |

入口、详情、已有完成记录与滚动位置复用[公共页面与结算](https://fuguang-design.pages.dev/daily-island/prd/overall.html)§1—2。独立资格校验通过且已提交完成后展示科学完成原文，包含pending／unknown；提交明确失败、资格不满足、预览或仅播放结束时隐藏完成原文。资源和今日进度仍等待服务确认。

## 3. 执行状态与判定

权限生命周期、系统弹框、拒绝后的设置/重试、返回与相机不可用处理复用肩颈放松；仅替换识别部位、用途文案和取景引导。系统授权弹框不另画成APP页面。已授权直接进入双手入镜，不重复申请。

| 准备状态 | 提示与画面 | 操作与去向 |
|---|---|---|
| permission_unknown | 双拳/手腕占位轮廓及摄像头用途 | 开启摄像头触发系统授权；允许进入align，拒绝进入permission_denied；返回详情 |
| permission_denied | “需要摄像头才能识别双手并记录移动轨迹” | 沿肩颈按平台提供前往设置或重试授权；不反复自动弹框；返回详情 |
| camera_error | 相机占用、启动失败或设备不支持的对应原因 | 可恢复时重试；无法使用时返回详情；不提供触屏代替双手并完成 |
| align / no_hands | “举起双手，让双拳和手腕完整入镜”；左右均未识别 | 开始练习禁用；双手有效转ready |
| left_only | 左手已识别、右手未识别；“请让右拳和手腕进入画面” | 开始练习禁用；保持左手标记，等待右手 |
| right_only | 右手已识别、左手未识别；“请让左拳和手腕进入画面” | 开始练习禁用；保持右手标记，等待左手 |
| ambiguous | 双手交叠、左右身份无法区分或出现额外手；“请让双手稍微分开，画面只保留你的双手” | 开始练习禁用；不得按画面横坐标交换左右身份 |
| ready | “双手已就绪”；两侧均已识别 | 开始练习进入demo；识别失效立即回相应准备状态，不保留可开始标志 |

| phase | 时长与画面 | 推进与下一状态 |
|---|---|---|
| demo | 6000ms；上方目标和动态路线示范，下方不生成跟做笔迹 | 两手共用示范时钟；结束进入follow |
| follow | 16000ms；上方保留弱示范，下方累计左右手实测轨迹及当前笔尖 | 每8000ms一轮，共2轮；第二轮保留第一轮淡迹；轮间不插入停顿 |
| ending | 2700ms；保留两轮笔迹，笔尖和尾流淡退，提示放松双手 | 不补成标准闭合形，不出现“画对/闭合成功”；收束后进入ended |
| ended | 保留本段笔迹及引导结束事实 | 仅产生guideEnded；按独立资格策略决定业务去向 |

上方示范：左手从圆顶部顺时针连续移动；右手从三角顶部沿左边向左下、底边向右、右边回顶，角点减速换向。两条示范路径共用同一轮进程，每轮各走一周；转向和循环不需要手动确认。用户按舒适幅度跟随，不强制实际轨迹与示范同步或闭合。

上方目标和示范由媒体时轴驱动；下方笔迹只由本次双手有效位置驱动，不从示范路径复制。示范期下方不画跟做笔迹；跟做期按handId分别追加采样点。两手可有不同移动速度和偏差，不把上方进程直接赋给用户笔尖，不要求靠近目标才显示笔迹。

相机坐标先按镜像约定转换，再以固定映射分别进入下方左右画布；一次会话中不自动改变比例、旋转或重置起点。每段有效轨迹记录实际采样时间；不补齐缺帧、不把噪声或跳点接成长线。未知左右身份时停采，不用屏幕位置猜测身份。原始画面仅在设备内处理，不录像或上传；准备进入执行继续使用同一相机，返回详情、返回列表或会话终止时关闭相机。

| 执行识别状态 | 画面与处理 | 恢复 |
|---|---|---|
| tracking_valid | 上方示范与跟做时轴推进，下方追加两手实测轨迹 | 持续跟踪 |
| tracking_lost_left / tracking_lost_right / tracking_lost_both | 提示对应手或双手和手腕回到画面；两手采样与示范/跟做时钟一起冻结，保留全部旧迹；失效笔尖隐藏 | 双手重新有效且身份对应后，从原有效时刻继续；新增轨迹段，不跨丢失区间补连 |
| tracking_ambiguous | 提示双手分开；冻结时轴和两手采样，不交换左右轨迹 | 左右重新可区分后按丢失恢复处理 |
| camera_unavailable / permission_revoked | 冻结轨迹与时轴，进入同一准备容器的相机异常/权限状态；保留本次未完成快照 | demo/follow恢复后重新确认双手，继续原阶段；ending仅继续剩余收束，不重新要求举手或采样；主动结束清除，后台按中断处理 |

识别状态不产生动作命中、画对数、连击、得分或健康变化。跟踪有效与业务完成资格分别处理。

进入ending时停止新增轨迹，保留已采集笔迹并完成2.7秒收束；此时允许用户放下双手，不再因双手离镜进入追踪暂停。相机故障和系统中断仍按对应异常处理。

加载、卡顿、退出确认与后台时间不累计有效播放；关闭声音不停止字幕和轨迹。重复结束事件按同一playbackRunId去重。

| 运行字段 | 类型与范围 | 更新规则与用途 |
|---|---|---|
| phase | enum | demo / follow / ending / ended；加载与恢复使用公共异常状态 |
| playbackRunId | string | 每次从首帧完整重开时生成；区分重开和继续 |
| mediaTimeMs / clock | number，毫秒 / number，秒 | mediaTimeMs为0—24700；预览clock为0—24.7，二者按1000换算；同一前台有效时轴，不按后台墙钟补算 |
| cueId / prompt / aux | string | 取当前cue，静音时完整可读 |
| cycleIndex / cycleProgress | integer，0—1 / number，0—1 | follow内当前轮及轮内进程；其他阶段不计跟做轮数 |
| leftProgress / rightProgress | number，0—1 | 仅上方左右示范路径进程；圆连续运动，三角逐边缓入缓出；不得作为下方用户笔迹输入 |
| cameraPermission / cameraState | enum | unknown / granted / denied；idle / opening / ready / unavailable；准备、返回、撤权时同步更新 |
| trackingState | enum | no_hands / left_only / right_only / ambiguous / ready / valid / lost_left / lost_right / lost_both / unavailable |
| hands | object | left、right分别含handId、valid、timestampMs、position{x,y}、confidence；缺失位置为null，不沿用旧点冒充新采样 |
| traces | object | 按左右、轮次与segmentId保存本次有效采样点{t,x,y}及前轮淡迹；丢失/跳点后新开segment，不修改已有点 |
| pausedReason / frozenClock | enum或null / number | 缺手、身份模糊、退出或相机异常的冻结原因及有效播放位置；未冻结为null |
| lastAcceptedSampleAt | number或null，毫秒 | 只接收当前sessionId中时间递增的有效采样；拒绝重复、乱序、过期和其他会话样本 |
| paused | boolean | 退出确认期间同步冻结示范、字幕、笔迹和声音 |
| guideEnded | boolean | 自然播完24700ms并收束后为true；跳播或审阅跳转不补判 |
| qualified | boolean | 仅业务身份、completionPolicy及独立证据校验通过才true；不得直接等于guideEnded |

## 4. 结束、退出、中断与重练

| 条件 | 状态处理 | 可见内容与去向 |
|---|---|---|
| 点退出 | 先处理已到的媒体边界，再同步冻结上下示范、笔迹、字幕与声音 | 公共双按钮“继续行动 / 结束本次”；正文提示“慢慢放下双手，放松坐稳。结束后，本次引导进度将清除。” |
| 退出继续 | 保留退出前phase、媒体时间、累计笔迹；demo/follow重新确认双手位置和左右身份后继续，断开冻结前后的轨迹段；ending只继续剩余收束，不要求举手或重新采样；不补算冻结时间 | 有效时返回原执行，失效时原位提示找回双手，不增加教程页 |
| 确认结束或不适 | 停止引导，清除本次未完成过程；不适时提示慢慢放下双手，放松坐稳 | 返回原今日行动；不催补做，不产生本次完成 |
| 后台、锁屏或关闭页面 | 停止并结束半途引导；不补算后台时间 | 回前台今日行动；再次开始为新sessionId，从首帧开始 |
| 引导自然结束 | 封存本次播放事实，按独立资格策略校验 | 仅播放事实进入引导结果；资格有效再按公共完成路径 |
| 已获有效自然完成再退出或系统中断 | 保留表现、原sessionId完成请求和回执 | 进入结果查询原请求，不重复提交 |
| 再练一次 | 按公共重复提醒；继续创建新的repeat session并重新检查相机与双手；已授权不重复弹授权框 | 双手准备就绪后从首帧开始；首次记录、首次回执及今日进度不变 |

弹层焦点与未知请求恢复遵循[公共页面与结算](https://fuguang-design.pages.dev/daily-island/prd/overall.html)§3。退出继续的本项规则优先于通用恢复；冻结时间不得变成额外身体保持或自动计完成。

## 5. 完成记录与结果字段

完成记录、幂等与回执字段精确复用[公共页面与结算](https://fuguang-design.pages.dev/daily-island/prd/overall.html)§4—5：`businessDate、sessionId、repeatSession、completionId、completedAt、completionStatus、failureReason、rewardStatus、rewardReceipt、completedCount、firstResult、firstResult.completedCountAtCompletion`。

| 本项字段 | 类型 | 生成、读取及约束 |
|---|---|---|
| guideEnded / guideEndedAt | boolean / 带时区ISO时间或null | 本次有效自然播放及收尾结束事实；与身体完成分开 |
| guideProgress | object | 记录媒体源、playbackRunId、实际媒体进度与收尾cue，不含用户动作次数 |
| performance | string | 示范播放进度及实际收束预算；不输出用户画对数或动作完成数 |
| completionPolicyId / sessionEvidence | string或null / object或null | 正式完成须满足经配置的业务策略；不得伪造相机信号或从媒体位置生成身体动作证据 |
| qualified | boolean | completionPolicy为null、身份缺项或证据不满足时固定false |

| 结果条件 | 第一层 | 资源与今日进度 |
|---|---|---|
| 仅引导结束或预览收束 | “引导结束”＋本项播放事实；不显示以身体完成为前提的science.completion | 不创建completionId或奖励事务；资源无回执显示“待确认”，今日进度显示服务已确认值，无值“待确认” |
| 资格有效且已提交完成 | completionStatus为pending或unknown时显示“完成状态确认中”、行为名、本局实际表现及science.completion；success时标题按公共§5 | pending／unknown时资源“待确认”，查询原sessionId，进度不增加；完成成功后显示实际奖励回执与服务进度 |
| completionStatus为failed | “本次未完成”、可展示失败原因及本局表现；隐藏science.completion | 不显示本次奖励；刷新服务实际进度，不自行增加 |
| 重练且资格有效 | “本次练习完成”＋本次表现；首次记录不变 | 读取首次回执并显示“本次新增0”；今日进度不增加 |
| 已完成详情查看结果 | 读取当日首次有效完成记录 | 查询首次completionId回执；服务当前业务日进度 |

查询沿用原sessionId或completionId，不重新播放、不重复发奖；返回今日行动始终立即可用。

## 6. 验收条件

| 操作或边界 | 通过条件 |
|---|---|
| 页面布局 | 上方左圆右三角目标/弱示范，下方为完整左右轨迹画布；没有人物或横向节拍带 |
| 时间与轮数 | 示范6秒、跟做2轮每轮8秒、收束2.7秒，共24.7秒；入口仍显示30秒 |
| 累计轨迹 | 当前轮已走路径持续可见，第2轮保留第1轮淡迹；轻偏差和不完美闭合保留，无自动修形或正确提示 |
| 同轴与换向 | 上方示范共用媒体时轴，圆持续、三角角点减速，轮间自然衔接；下方笔尖/短尾按各手实际采样变化，不按示范改速度或路径 |
| 权限与准备 | 未授权由用户点开启；拒绝/设置/重试/错误沿肩颈流程；只改识别部位，未就绪不能开始；已授权不重复申请 |
| 识别部位 | 只使用左右手腕与掌部的位置；举拳为准备引导，头肩不驱动轨迹，不新增握拳判分 |
| 真实输入 | 正式下方轨迹来自双手位置，停止手部移动不会继续自动画形；单手移动只改变对应轨迹；预设路径只能用于审阅样例 |
| 丢失恢复 | 单手丢失、交叠无法辨左右、相机故障时冻结时轴和采样；保留旧迹，找回后新开线段、不跨空白补连或交换左右 |
| 放手收束 | 进入ending后停止采样；放下双手不触发丢失暂停，2.7秒自然结束；不把新位置补入已结束轨迹 |
| 退出与中断 | 退出同步冻结，继续保留全部笔迹；结束清局，后台不续接，不补算完成或奖励 |
| 结果与原文 | science两字段逐字匹配taskId；元气15；只有播放事实时不显示身体完成原文或到账 |
| 首次结果与重练 | 查看结果读取首次记录；新repeat session不覆盖首次表现、回执与今日进度；返回立即可用 |
| 窄屏与静音 | 上下两个区域及完整笔迹均可见，提示不遮挡，退出和返回可用；不依赖声音或颜色理解左右画法 |
