双手画形 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:
- 坐稳,双脚着地,把手机放在前方看得到的位置。
- 双手自然握拳,抬到舒适高度,让双拳和手腕完整入镜,不用用力攥紧。画面左侧对应你的左手,右侧对应你的右手。
- 先看上方示范:左手连续画圆,右手沿三角形在角点换向。
- 双手识别就绪后开始。两手同时在空中画形,每轮8秒,共2轮;上方看示范,下方看两只手留下的轨迹。
- 收束时慢慢放下双手、放松。
| 执行配置 | 类型 | 值与校验 |
|---|---|---|
| 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轮保留前轮淡迹,不裁成短窗口或横向节拍带;丢失时保留旧迹并隐藏失效笔尖 |
| 行为执行 | 底部 | 示范/跟做/收束进度及“不舒服,结束”;结束显示引导结束,不显示用户画对数 |
| 结果 | 四层位置 | 引导事实或有效完成标题与科学文案→真实元气回执→今日进度→立即可用的返回今日行动 |
入口、详情、已有完成记录与滚动位置复用公共页面与结算§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并重新检查相机与双手;已授权不重复弹授权框 | 双手准备就绪后从首帧开始;首次记录、首次回执及今日进度不变 |
弹层焦点与未知请求恢复遵循公共页面与结算§3。退出继续的本项规则优先于通用恢复;冻结时间不得变成额外身体保持或自动计完成。
5. 完成记录与结果字段
完成记录、幂等与回执字段精确复用公共页面与结算§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不覆盖首次表现、回执与今日进度;返回立即可用 |
| 窄屏与静音 | 上下两个区域及完整笔迹均可见,提示不遮挡,退出和返回可用;不依赖声音或颜色理解左右画法 |