feat: add baby object match edutainment flow
Some checks failed
CI / verify (push) Has been cancelled
Some checks failed
CI / verify (push) Has been cancelled
This commit is contained in:
@@ -0,0 +1,164 @@
|
||||
# 宝贝识物创作发布实现方案 2026-05-11
|
||||
|
||||
## 1. 范围
|
||||
|
||||
本方案对应第 2 线程：创作发布线程。
|
||||
|
||||
本线程落地：
|
||||
|
||||
1. 创作入口配置；
|
||||
2. 模板表单；
|
||||
3. 本地草稿生成 service；
|
||||
4. 结果页；
|
||||
5. 发布 payload 约束；
|
||||
6. 本地 Demo 运行态；
|
||||
7. 后端 image-2 / 作品持久化 / 运行态接口预留形状。
|
||||
|
||||
本阶段运行态先做浏览器本地 Demo，并消费现有本地 mocap 动作数据源；正式硬件接口和摄像头调教在后续接口稳定后继续接入。
|
||||
|
||||
## 2. 前端接入点
|
||||
|
||||
新增玩法 ID：
|
||||
|
||||
```text
|
||||
baby-object-match
|
||||
```
|
||||
|
||||
用户展示名：
|
||||
|
||||
```text
|
||||
宝贝识物
|
||||
```
|
||||
|
||||
入口文件：
|
||||
|
||||
1. `src/config/newWorkEntryConfig.ts`
|
||||
2. `src/components/platform-entry/platformEntryCreationTypes.ts`
|
||||
3. `src/components/platform-entry/PlatformEntryCreationTypeModal.tsx`
|
||||
4. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
|
||||
`baby-object-match` 必须复用 `VITE_ENABLE_EDUTAINMENT_ENTRY` 开关；开关关闭时，创作类型弹层不展示 `宝贝识物`，创作页作品架不展示本地宝贝识物草稿或已发布作品卡，公开发现、搜索、详情、作品号和浏览历史也继续完全不可见。
|
||||
|
||||
新增阶段：
|
||||
|
||||
```text
|
||||
baby-object-match-workspace
|
||||
baby-object-match-generating
|
||||
baby-object-match-result
|
||||
baby-object-match-runtime
|
||||
```
|
||||
|
||||
## 3. 契约
|
||||
|
||||
前端共享契约放在：
|
||||
|
||||
```text
|
||||
packages/shared/src/contracts/edutainmentBabyObject.ts
|
||||
```
|
||||
|
||||
核心字段：
|
||||
|
||||
1. `BabyObjectMatchDraft.templateId = "baby-object-match"`；
|
||||
2. `BabyObjectMatchDraft.templateName = "宝贝识物"`；
|
||||
3. `BabyObjectMatchDraft.themeTags` 必须包含精确 `寓教于乐`；
|
||||
4. `BabyObjectMatchItemAsset.generationProvider` 首版允许为 `vector-engine-gpt-image-2` 或 `placeholder`；
|
||||
5. `BabyObjectMatchPublishRequest.draft.themeTags` 发布前必须归一化补齐 `寓教于乐`。
|
||||
|
||||
## 4. Service 边界
|
||||
|
||||
前端 service 放在：
|
||||
|
||||
```text
|
||||
src/services/edutainment-baby-object/babyObjectMatchClient.ts
|
||||
```
|
||||
|
||||
首版提供：
|
||||
|
||||
1. `createBabyObjectMatchDraft(payload)`；
|
||||
2. `saveBabyObjectMatchDraft(draft)`；
|
||||
3. `publishBabyObjectMatchWork(payload)`。
|
||||
|
||||
当前后端正式接口未在本线程扩表落地，因此 service 先走本地 Demo 存储，并把 asset 结果标记为 `placeholder`。后续后端接入时，应替换为：
|
||||
|
||||
```text
|
||||
POST /api/creation/edutainment/baby-object-match/drafts
|
||||
PUT /api/creation/edutainment/baby-object-match/drafts/{draftId}
|
||||
POST /api/creation/edutainment/baby-object-match/drafts/{draftId}/publish
|
||||
```
|
||||
|
||||
图片生成必须在后端调用 VectorEngine `gpt-image-2-all`，不得从前端直接调用外部图片接口。
|
||||
|
||||
## 5. UI 边界
|
||||
|
||||
工作台只展示两个必填输入和生成按钮。
|
||||
|
||||
结果页只展示草稿核心信息、两个物品、保存草稿、发布、试玩。不在 UI 内写玩法说明长文案。
|
||||
|
||||
移动端优先：表单和结果页使用单列布局，桌面端自然扩展为双列。
|
||||
|
||||
## 6. 运行态边界
|
||||
|
||||
前端运行态放在：
|
||||
|
||||
```text
|
||||
src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.tsx
|
||||
```
|
||||
|
||||
运行态直接消费 `BabyObjectMatchDraft`，必须使用草稿中的两个物品名称和物品图。
|
||||
每轮只随机当前从礼物盒跳出的物品；左右篮子不随机交换，左侧固定为草稿 `itemAssets[0]`，右侧固定为草稿 `itemAssets[1]`。
|
||||
|
||||
首关状态机：
|
||||
|
||||
1. `waiting`：礼物盒关闭，等待任意手抬起；
|
||||
2. `active`：当前物品停留在屏幕中央；
|
||||
3. `correct`：展示“真棒”反馈，成功次数加 1；
|
||||
4. `wrong`：展示“再想一想吧”反馈，当前物品回到中央；
|
||||
5. `complete`：成功次数达到 20，展示“恭喜你！小朋友！”和按钮。
|
||||
|
||||
动作输入：
|
||||
|
||||
1. 任意手完成一次 `open_palm -> grab` 抓握序列：打开礼物盒并生成当前物品；
|
||||
2. 左手连续横向移动达到阈值：将当前物品送入左侧篮子；
|
||||
3. 右手连续横向移动达到阈值：将当前物品送入右侧篮子。
|
||||
|
||||
运行态直接通过 `useMocapInput` 消费本地 mocap WebSocket `/stream`。选篮只使用明确 `leftHand` 或 `rightHand` 的连续横向轨迹阈值，不再通过 `wave_left_hand`、`wave_right_hand`、`wave` 等动作名触发；侧别为 `unknown` 的手部轨迹也不参与选篮，以避免多套判定误命中和连续误触发。当前本地 mocap 输出的 handedness 按摄像头视角标记，宝贝识物运行态必须先换算为用户身体视角：`rightHand` 轨迹映射玩家左手并进入左侧篮子，`leftHand` 轨迹映射玩家右手并进入右侧篮子。草稿试玩、发布后正式体验和热身关后的本地 Demo 都复用同一个运行态，因此三条入口都必须具备同一套动作控制能力。
|
||||
|
||||
开发者调试输入：
|
||||
|
||||
1. `F`：映射任意手抬起，打开礼物盒并生成当前物品；
|
||||
2. 鼠标左键按下并拖动：映射左手轨迹，抬起后将当前物品送入左侧篮子；
|
||||
3. 鼠标右键按下并拖动：映射右手轨迹，抬起后将当前物品送入右侧篮子。
|
||||
|
||||
运行态不得新增计时、失败次数、分数、体力或难度递增规则。
|
||||
|
||||
音效和语音播报当前只保留接口预留边界，正式语音接口后续接入。
|
||||
|
||||
## 7. 发布约束
|
||||
|
||||
发布前必须执行：
|
||||
|
||||
1. 两个物品名非空；
|
||||
2. 两个物品名对应的 asset 存在；
|
||||
3. 标签补齐精确 `寓教于乐`；
|
||||
4. `publicationStatus` 从 `draft` 变为 `published`。
|
||||
|
||||
发布后首版本地响应返回 `publicWorkCode`，用于分享弹窗；正式后端接入时 public code 生成规则需要纳入统一作品号服务。
|
||||
|
||||
## 8. 热身关衔接
|
||||
|
||||
`/child-motion-demo` 热身完成后的“开始游戏”按钮进入同一个 `BabyObjectMatchRuntimeShell`。
|
||||
|
||||
热身关独立 Demo 没有创作者草稿上下文，因此使用固定本地 Demo 草稿承载两个物品，仅用于热身关后验证首关体验；正式平台体验仍必须从 `宝贝识物` 模板创作发布后进入寓教于乐板块。
|
||||
|
||||
## 9. 验收命令
|
||||
|
||||
```bash
|
||||
npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.test.tsx src/components/child-motion-demo/ChildMotionWarmupDemo.test.tsx src/services/edutainment-baby-object/babyObjectMatchClient.test.ts
|
||||
npx vitest run src/components/platform-entry/platformEdutainmentVisibility.test.ts src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/custom-world-home/creationWorkShelf.test.ts src/services/useMocapInput.test.ts src/services/child-motion-demo/childMotionDebugInput.test.ts src/routing/appRoutes.test.ts
|
||||
npx eslint src/components/platform-entry/platformEntryCreationTypes.ts src/components/platform-entry/platformEntryCreationTypes.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --ext .ts,.tsx --max-warnings 0
|
||||
npm run check:encoding
|
||||
npm run typecheck
|
||||
npm run build:raw
|
||||
```
|
||||
|
||||
若后续接入真实 Rust API 和 SpacetimeDB 表，再补充 `npm run api-server`、`/healthz`、Rust contract / api-server / spacetime-client 定向测试和 migration 表目录更新。
|
||||
Reference in New Issue
Block a user