Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative
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 表目录更新。
|
||||
@@ -0,0 +1,729 @@
|
||||
# bark-battle 2D Runtime 前端技术方案（2026-05-11）
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
本方案基于 `.hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md`，为“汪汪声浪大作战 / bark-battle”细化前端与浏览器游戏 runtime 的技术实现路线。
|
||||
|
||||
本任务只产出技术方案，不直接实现代码。后续编码应以本文作为 runtime 层设计约束，再按 TDD 小步落地。
|
||||
|
||||
### 1.1 玩法定位
|
||||
|
||||
`bark-battle` 是一个声控拔河式 2D 浏览器小游戏：玩家对麦克风发出狗叫声，系统根据音量峰值、有效叫声次数和节奏计算本方声浪推动力，在限时 30 秒内推动顶部红蓝能量条，时间结束后按能量条偏向判定胜负。
|
||||
|
||||
### 1.2 本文范围
|
||||
|
||||
本文覆盖：
|
||||
|
||||
- Phaser + TypeScript + Vite 栈选择
|
||||
- simulation / render / HUD 边界
|
||||
- 建议目录结构
|
||||
- 核心 domain 类型
|
||||
- Web Audio 输入适配
|
||||
- Phaser Scene 切分
|
||||
- DOM HUD 设计
|
||||
- 移动端与权限降级
|
||||
- 测试与验证命令
|
||||
|
||||
本文不覆盖：
|
||||
|
||||
- 后端表结构、持久化成绩、作品发布、广场接入
|
||||
- 实时多人对战协议
|
||||
- 复杂 AI 狗叫识别模型
|
||||
- 美术素材正式生产流程
|
||||
|
||||
## 2. 技术栈选择
|
||||
|
||||
### 2.1 推荐栈
|
||||
|
||||
```text
|
||||
Runtime Renderer: Phaser 3
|
||||
Language: TypeScript
|
||||
Build: Vite
|
||||
Host UI: React / DOM overlay
|
||||
Audio Input: Web Audio API + MediaDevices.getUserMedia
|
||||
Test: Vitest + Testing Library + 浏览器 smoke / Playwright 可选
|
||||
```
|
||||
|
||||
### 2.2 选择理由
|
||||
|
||||
1. 玩法是横版 2D 舞台，核心表现是狗狗 sprite、声浪、拟声词、粒子、屏幕震动与能量条反馈，Phaser 对 2D 渲染、时间循环、sprite animation、camera、粒子和 Scene 生命周期支持成熟。
|
||||
2. 当前项目主前端已使用 TypeScript + Vite，继续复用现有构建和测试体系，避免引入独立构建链。
|
||||
3. 文字密集、权限提示、结算、设置和移动端响应式布局适合 DOM HUD；Canvas 保持负责 playfield 和动态特效。
|
||||
4. Web Audio API 可以在浏览器端完成 MVP 所需音量采样、RMS/peak 计算、环境噪音校准和输入归一化，不需要首版接入后端音频处理。
|
||||
|
||||
### 2.3 不选择其它路线的原因
|
||||
|
||||
- 不使用 Three.js / 3D：当前玩法画面是 2D 横版舞台，不需要 3D 相机、模型和材质管线。
|
||||
- 不把 HUD 全部塞入 Phaser Canvas：权限说明、重试、结算、移动端布局和可访问性更适合 DOM。
|
||||
- 不在前端实现正式业务真相：浏览器 runtime 可承载单局即时 simulation，但若后续涉及成绩、作品、排行榜、发布和奖励，必须交给后端投影/API 裁决。
|
||||
|
||||
## 3. 总体架构
|
||||
|
||||
### 3.1 分层总览
|
||||
|
||||
```text
|
||||
React Runtime Shell
|
||||
├─ DOM HUD / Panels
|
||||
│ ├─ PermissionPanel
|
||||
│ ├─ TopEnergyBar
|
||||
│ ├─ TimerChip
|
||||
│ └─ ResultPanel
|
||||
│
|
||||
├─ Application Controller
|
||||
│ ├─ permission / calibration orchestration
|
||||
│ ├─ simulation tick
|
||||
│ ├─ audio sample submission
|
||||
│ └─ snapshot publish
|
||||
│
|
||||
├─ Pure Domain / Simulation
|
||||
│ ├─ BarkBattleSession
|
||||
│ ├─ BarkDetector
|
||||
│ ├─ EnergyTugOfWar
|
||||
│ ├─ BarkBattleScoring
|
||||
│ └─ OpponentStrategy
|
||||
│
|
||||
├─ Infrastructure Adapters
|
||||
│ ├─ BrowserMicrophoneInput
|
||||
│ ├─ AudioAnalyserSampler
|
||||
│ └─ PhaserGameHost
|
||||
│
|
||||
└─ Phaser Renderer
|
||||
├─ BootScene
|
||||
├─ PreloadScene
|
||||
├─ BattleScene
|
||||
├─ FxScene / DebugScene（可选）
|
||||
└─ Asset manifest
|
||||
```
|
||||
|
||||
### 3.2 强制边界
|
||||
|
||||
1. `domain/` 不依赖 Phaser、Web Audio、DOM、React、浏览器全局对象或后端 API。
|
||||
2. `domain/` 只接收 plain data，例如时间增量、归一化音量样本、对手 power、配置参数。
|
||||
3. `application/` 负责编排权限、校准、音频输入、AI 对手、tick 和 snapshot 分发。
|
||||
4. Phaser Scene 只消费 `BarkBattleSnapshot`，把 snapshot 映射成 sprite、动画、粒子、camera 和 sound effect；不得持有核心胜负、计数和能量条规则。
|
||||
5. DOM HUD 只消费 snapshot 和少量 runtime UI 状态，负责展示、按钮和弹层；不得重复实现核心胜负规则。
|
||||
6. 若后续接入平台作品/成绩/排行榜，前端只调用后端 API 和展示投影，不在本地绕过后端生成正式结论。
|
||||
|
||||
## 4. 建议目录结构
|
||||
|
||||
首版建议以独立 runtime 原型落在 `src/games/bark-battle/`，避免提前侵入平台创作链路。
|
||||
|
||||
```text
|
||||
src/games/bark-battle/
|
||||
domain/
|
||||
BarkBattleTypes.ts
|
||||
BarkBattleSession.ts
|
||||
BarkDetector.ts
|
||||
EnergyTugOfWar.ts
|
||||
BarkBattleScoring.ts
|
||||
OpponentStrategy.ts
|
||||
__tests__/
|
||||
BarkDetector.test.ts
|
||||
EnergyTugOfWar.test.ts
|
||||
BarkBattleSession.test.ts
|
||||
BarkBattleScoring.test.ts
|
||||
|
||||
application/
|
||||
BarkBattleController.ts
|
||||
BarkBattleConfig.ts
|
||||
BarkBattleSnapshotStore.ts
|
||||
__tests__/
|
||||
BarkBattleController.test.ts
|
||||
|
||||
infrastructure/
|
||||
BrowserMicrophoneInput.ts
|
||||
AudioAnalyserSampler.ts
|
||||
MicrophonePermission.ts
|
||||
__tests__/
|
||||
BrowserMicrophoneInput.test.ts
|
||||
AudioAnalyserSampler.test.ts
|
||||
|
||||
phaser/
|
||||
BarkBattleGameHost.ts
|
||||
scenes/
|
||||
BarkBattleBootScene.ts
|
||||
BarkBattlePreloadScene.ts
|
||||
BarkBattleScene.ts
|
||||
BarkBattleFxScene.ts
|
||||
assets/
|
||||
barkBattleAssetManifest.ts
|
||||
|
||||
ui/
|
||||
BarkBattleRuntimeShell.tsx
|
||||
BarkBattleHud.tsx
|
||||
BarkBattlePermissionPanel.tsx
|
||||
BarkBattleResultPanel.tsx
|
||||
BarkBattleMobileControls.tsx
|
||||
BarkBattleHud.css
|
||||
__tests__/
|
||||
BarkBattleHud.test.tsx
|
||||
BarkBattlePermissionPanel.test.tsx
|
||||
BarkBattleResultPanel.test.tsx
|
||||
```
|
||||
|
||||
若后续进入 Genarrative 正式玩法类型闭环，再按 `genarrative-play-type-integration` 扩展到：
|
||||
|
||||
```text
|
||||
src/components/bark-battle-runtime/BarkBattleRuntimeShell.tsx
|
||||
src/components/bark-battle-result/BarkBattleResultView.tsx
|
||||
src/services/barkBattleRuntimeClient.ts
|
||||
packages/shared/src/contracts/barkBattle.ts
|
||||
server-rs/crates/shared-contracts/src/bark_battle.rs
|
||||
```
|
||||
|
||||
首版不建议直接新增后端表或正式作品链路，除非产品明确要求成绩、发布和广场能力。
|
||||
|
||||
## 5. 核心 Domain 类型
|
||||
|
||||
### 5.1 基础枚举与数值约定
|
||||
|
||||
```ts
|
||||
export type BarkBattlePhase =
|
||||
| 'permission'
|
||||
| 'calibration'
|
||||
| 'countdown'
|
||||
| 'playing'
|
||||
| 'finished'
|
||||
| 'unavailable'
|
||||
|
||||
export type BarkBattleSide = 'player' | 'opponent'
|
||||
|
||||
export type BarkBattleWinner = BarkBattleSide | 'draw' | null
|
||||
|
||||
export type BarkBattleDifficulty = 'easy' | 'normal' | 'hard'
|
||||
|
||||
export type BarkBattleUiState =
|
||||
| 'idle'
|
||||
| 'permission-ready'
|
||||
| 'microphone-authorized'
|
||||
| 'calibrating'
|
||||
| 'ready-countdown'
|
||||
| 'playing'
|
||||
| 'finished'
|
||||
| 'microphone-unavailable'
|
||||
|
||||
export type MicrophoneFailureReason =
|
||||
| 'unsupported'
|
||||
| 'permission-denied'
|
||||
| 'non-secure-context'
|
||||
| 'not-found'
|
||||
| 'not-readable'
|
||||
| 'audio-context-blocked'
|
||||
| 'calibration-timeout'
|
||||
| 'calibration-sample-unreadable'
|
||||
| 'unknown'
|
||||
```
|
||||
|
||||
关键数值：
|
||||
|
||||
- `energy`: `-100..100`，正数偏玩家侧，负数偏对手侧。
|
||||
- `currentVolume`: `0..1`，音频采样归一化后的瞬时音量。
|
||||
- `recentPeak`: `0..1`，短窗口内峰值。
|
||||
- `power`: `0..1` 或 `0..100` 二选一，建议 domain 内统一 `0..1`，HUD 显示再转百分比。
|
||||
- `remainingMs`: 单局剩余毫秒。
|
||||
|
||||
### 5.2 Snapshot
|
||||
|
||||
```ts
|
||||
export type BarkBattleSnapshot = {
|
||||
phase: BarkBattlePhase
|
||||
uiState: BarkBattleUiState
|
||||
errorReason: MicrophoneFailureReason | null
|
||||
statusMessageKey: BarkBattleStatusMessageKey | null
|
||||
elapsedMs: number
|
||||
remainingMs: number
|
||||
countdownMs: number
|
||||
energy: number
|
||||
player: BarkSideState
|
||||
opponent: BarkSideState
|
||||
winner: BarkBattleWinner
|
||||
result: BarkBattleResult | null
|
||||
lastEvents: BarkBattleVisualEvent[]
|
||||
}
|
||||
|
||||
export type BarkSideState = {
|
||||
side: BarkBattleSide
|
||||
barkCount: number
|
||||
currentVolume: number
|
||||
recentPeak: number
|
||||
combo: number
|
||||
power: number
|
||||
isBarking: boolean
|
||||
lastBarkAtMs: number | null
|
||||
maxVolume: number
|
||||
}
|
||||
|
||||
export type BarkBattleResult = {
|
||||
winner: BarkBattleWinner
|
||||
finalEnergy: number
|
||||
playerBarkCount: number
|
||||
playerMaxVolume: number
|
||||
playerAveragePower: number
|
||||
score: number
|
||||
}
|
||||
|
||||
export type BarkBattleStatusMessageKey =
|
||||
| 'microphone-unsupported'
|
||||
| 'microphone-permission-denied'
|
||||
| 'microphone-non-secure-context'
|
||||
| 'microphone-not-found'
|
||||
| 'microphone-not-readable'
|
||||
| 'microphone-audio-context-blocked'
|
||||
| 'microphone-calibration-timeout'
|
||||
| 'microphone-calibration-sample-unreadable'
|
||||
| 'microphone-unknown-error'
|
||||
```
|
||||
|
||||
### 5.3 输入样本与叫声事件
|
||||
|
||||
```ts
|
||||
export type BarkAudioSample = {
|
||||
atMs: number
|
||||
volume: number
|
||||
peak: number
|
||||
rms: number
|
||||
}
|
||||
|
||||
export type BarkDetectedEvent = {
|
||||
id: string
|
||||
atMs: number
|
||||
side: BarkBattleSide
|
||||
volume: number
|
||||
strength: number
|
||||
combo: number
|
||||
}
|
||||
```
|
||||
|
||||
### 5.4 视觉事件
|
||||
|
||||
视觉事件由 domain 或 application 生成，但只包含 plain data，不包含 Phaser 对象：
|
||||
|
||||
```ts
|
||||
export type BarkBattleVisualEvent =
|
||||
| {
|
||||
type: 'bark-word'
|
||||
id: string
|
||||
side: BarkBattleSide
|
||||
atMs: number
|
||||
strength: number
|
||||
text: 'BARK' | 'WOOF' | 'WAN' | 'WANGOOF'
|
||||
}
|
||||
| {
|
||||
type: 'shockwave'
|
||||
id: string
|
||||
side: BarkBattleSide
|
||||
atMs: number
|
||||
strength: number
|
||||
}
|
||||
| {
|
||||
type: 'combo-burst'
|
||||
id: string
|
||||
side: BarkBattleSide
|
||||
atMs: number
|
||||
combo: number
|
||||
}
|
||||
```
|
||||
|
||||
Phaser 只根据这些事件播放一次性特效，并维护已消费事件 ID，避免重复播放。
|
||||
|
||||
## 6. Domain 模块职责
|
||||
|
||||
### 6.1 BarkDetector
|
||||
|
||||
职责：把连续音频样本转换为有效叫声事件。
|
||||
|
||||
输入：
|
||||
|
||||
- `BarkAudioSample`
|
||||
- 校准后的 `ambientNoiseFloor`
|
||||
- `barkThreshold`
|
||||
- `minBarkGapMs`
|
||||
- `minBarkDurationMs`
|
||||
- `maxBarkDurationMs`
|
||||
|
||||
规则建议：
|
||||
|
||||
1. 音量超过动态阈值进入 candidate 状态。
|
||||
2. 峰值回落到阈值以下或持续时长达到上限时结束 candidate。
|
||||
3. candidate 持续时间在 `80ms..1200ms` 且与上一次有效叫声间隔足够时，记为一次叫声。
|
||||
4. 长时间持续噪音不应无限计数，只能按冷却和峰值回落形成新事件。
|
||||
5. MVP 不要求识别“是否真狗叫”，先基于音量峰值、时长和间隔判断。
|
||||
|
||||
### 6.2 EnergyTugOfWar
|
||||
|
||||
职责：更新红蓝拉锯条。
|
||||
|
||||
建议公式：
|
||||
|
||||
```text
|
||||
playerPower = volumeScore * 0.65 + barkRateScore * 0.35 + comboBonus
|
||||
opponentPower = opponentStrategy.tick(...)
|
||||
energyDelta = (playerPower - opponentPower) * deltaSeconds * balanceFactor
|
||||
energy = clamp(energy + energyDelta, -100, 100)
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
- `EnergyTugOfWar` 不知道玩家来自麦克风还是 mock input。
|
||||
- `EnergyTugOfWar` 不知道 Phaser 能量条宽度。
|
||||
- 平衡参数集中在 `BarkBattleConfig`，不要散落在 Scene 或 HUD 中。
|
||||
|
||||
### 6.3 BarkBattleSession
|
||||
|
||||
职责：管理局内 phase、计时、胜负和 snapshot。
|
||||
|
||||
状态机建议：
|
||||
|
||||
```text
|
||||
permission → calibration → countdown → playing → finished
|
||||
↘ unavailable
|
||||
```
|
||||
|
||||
`phase` 只表达 runtime 是否可继续参与局内流程；所有麦克风不可用、权限失败、非安全上下文和校准失败都统一收敛到 `phase: 'unavailable'`，再通过 `uiState: 'microphone-unavailable'` 与 `errorReason` 区分 HUD 展示和重试策略，避免把基础设施错误枚举直接扩散成 domain 阶段。
|
||||
|
||||
关键规则：
|
||||
|
||||
- `countdown` 结束才进入 `playing`。
|
||||
- `playing` 时 `remainingMs` 随 tick 递减。
|
||||
- `remainingMs <= 0` 后进入 `finished`。
|
||||
- `energy > drawThreshold` 判定玩家胜利。
|
||||
- `energy < -drawThreshold` 判定对手胜利。
|
||||
- `abs(energy) <= drawThreshold` 判定平局。
|
||||
|
||||
### 6.4 OpponentStrategy
|
||||
|
||||
职责：为单机 MVP 提供对手推动力。
|
||||
|
||||
```ts
|
||||
export interface OpponentStrategy {
|
||||
tick(input: OpponentTickInput): OpponentTickOutput
|
||||
}
|
||||
```
|
||||
|
||||
普通难度建议：
|
||||
|
||||
- 周期性小叫声提供基础压力。
|
||||
- 每 3~6 秒一次短爆发。
|
||||
- 玩家大幅领先时可轻微增强，但不能追到不可赢。
|
||||
|
||||
## 7. Web Audio 输入适配
|
||||
|
||||
### 7.1 BrowserMicrophoneInput
|
||||
|
||||
职责：封装浏览器麦克风权限与音频流生命周期。
|
||||
|
||||
建议 API：
|
||||
|
||||
```ts
|
||||
export interface MicrophoneInputPort {
|
||||
isSupported(): boolean
|
||||
requestPermission(): Promise<MicrophoneSession>
|
||||
stop(): void
|
||||
}
|
||||
|
||||
export interface MicrophoneSession {
|
||||
sample(atMs: number): BarkAudioSample
|
||||
stop(): void
|
||||
}
|
||||
```
|
||||
|
||||
实现要点：
|
||||
|
||||
1. 使用 `navigator.mediaDevices?.getUserMedia({ audio: true })`。
|
||||
2. 在用户点击“开始”后创建或 resume `AudioContext`，避免移动端自动播放策略拦截。
|
||||
3. 使用 `AnalyserNode` 读取时域数据，计算 RMS 与 peak。
|
||||
4. 输出归一化样本，不把 `MediaStream`、`AudioContext`、`AnalyserNode` 泄漏到 domain。
|
||||
5. 退出、重开、页面卸载时停止 track，避免麦克风占用残留。
|
||||
|
||||
### 7.2 校准流程
|
||||
|
||||
`calibration` 阶段建议持续 `800ms..1500ms`：
|
||||
|
||||
1. 收集静默环境样本。
|
||||
2. 计算 `ambientNoiseFloor`，例如 `p75` 或均值 + 标准差。
|
||||
3. 设置动态阈值：
|
||||
|
||||
```text
|
||||
barkThreshold = clamp(ambientNoiseFloor + 0.12, 0.18, 0.55)
|
||||
```
|
||||
|
||||
4. 若环境噪音过高，HUD 给出简短提示和“继续 / 重新校准”入口，但不要把长说明常驻在画面上。
|
||||
|
||||
### 7.3 权限与错误分类
|
||||
|
||||
```ts
|
||||
export type MicrophoneFailureReason =
|
||||
| 'unsupported'
|
||||
| 'permission-denied'
|
||||
| 'non-secure-context'
|
||||
| 'not-found'
|
||||
| 'not-readable'
|
||||
| 'audio-context-blocked'
|
||||
| 'calibration-timeout'
|
||||
| 'calibration-sample-unreadable'
|
||||
| 'unknown'
|
||||
```
|
||||
|
||||
错误来源与分层归属：
|
||||
|
||||
| 失败原因 | 主要检测位置 | controller snapshot 表达 | HUD 可区分状态 |
|
||||
| --- | --- | --- | --- |
|
||||
| 浏览器无 `mediaDevices.getUserMedia` | `BrowserMicrophoneInput.isSupported()` | `phase: 'unavailable'`, `uiState: 'microphone-unavailable'`, `errorReason: 'unsupported'` | 设备或浏览器不支持麦克风输入，只提供返回入口，不展示可开始声控按钮 |
|
||||
| 非安全上下文 | `BrowserMicrophoneInput.isSupported()` 或 `MicrophonePermission` 预检 `window.isSecureContext` | `phase: 'unavailable'`, `errorReason: 'non-secure-context'` | 当前环境无法使用麦克风，提示使用受支持的安全环境或返回 |
|
||||
| 用户拒绝授权 | `BrowserMicrophoneInput.requestPermission()` 捕获 `NotAllowedError` / `SecurityError` | `phase: 'unavailable'`, `errorReason: 'permission-denied'` | 提供重新授权或返回入口，不进入 calibration/countdown/playing |
|
||||
| 未检测到设备 | `getUserMedia` 捕获 `NotFoundError` / `DevicesNotFoundError` | `phase: 'unavailable'`, `errorReason: 'not-found'` | 展示麦克风不可用，可重试授权或返回 |
|
||||
| 设备被占用或不可读 | `getUserMedia` 捕获 `NotReadableError` / `TrackStartError` | `phase: 'unavailable'`, `errorReason: 'not-readable'` | 展示麦克风不可用，可重试授权或返回 |
|
||||
| AudioContext 被移动端策略拦截 | 用户手势后创建 / resume `AudioContext` 失败 | `phase: 'unavailable'`, `errorReason: 'audio-context-blocked'` | 提示点击重试，不自动循环请求 |
|
||||
| 校准超时 | `BarkBattleController` 在 calibration 阶段等待样本超出 `calibrationMaxWaitMs` | `phase: 'unavailable'`, `errorReason: 'calibration-timeout'` | 展示麦克风输入不可用，提供重试校准入口 |
|
||||
| 校准样本不可读 | `AudioAnalyserSampler.sample()` 持续返回空样本、NaN 或无法读取 buffer | `phase: 'unavailable'`, `errorReason: 'calibration-sample-unreadable'` | 展示麦克风输入不可用，提供重试校准入口 |
|
||||
|
||||
前端只根据错误分类展示可操作状态：重试授权、重试校准、返回、或使用调试备用输入。不要把浏览器原始错误堆栈展示给玩家。
|
||||
|
||||
## 8. Phaser Scene 切分
|
||||
|
||||
### 8.1 BarkBattleBootScene
|
||||
|
||||
职责：
|
||||
|
||||
- 初始化 Phaser 全局配置。
|
||||
- 注册 scale、background color、全局事件桥。
|
||||
- 不加载重资源，不处理玩法规则。
|
||||
|
||||
### 8.2 BarkBattlePreloadScene
|
||||
|
||||
职责：
|
||||
|
||||
- 根据 `barkBattleAssetManifest` 加载背景、狗狗 sprite、声浪 FX、拟声词 bitmap / atlas、轻量音效。
|
||||
- 使用稳定 manifest key，不在 gameplay 代码中散写文件路径。
|
||||
- 加载完成后进入 `BarkBattleScene`。
|
||||
|
||||
### 8.3 BarkBattleScene
|
||||
|
||||
职责：
|
||||
|
||||
- 创建横版舞台、左右狗狗、背景层、声浪层、拟声词层。
|
||||
- 每帧读取最新 `BarkBattleSnapshot`。
|
||||
- 根据 snapshot 更新：
|
||||
- 狗狗 idle / bark / win / lose 动画
|
||||
- 声浪强度
|
||||
- camera shake
|
||||
- transient bark words
|
||||
- shockwave
|
||||
- 把可选的调试输入 action 传给 controller，但不处理麦克风和规则。
|
||||
|
||||
不得在 Scene 中实现：
|
||||
|
||||
- 叫声计数
|
||||
- 胜负判定
|
||||
- 能量条规则
|
||||
- 权限流程
|
||||
- 结算数据计算
|
||||
|
||||
### 8.4 BarkBattleFxScene（可选）
|
||||
|
||||
如果特效复杂，可拆出叠加 Scene：
|
||||
|
||||
- 专门处理拟声词、粒子、冲击波和 camera shake。
|
||||
- 通过视觉事件 ID 去重。
|
||||
- 对 `prefers-reduced-motion` 或低端设备降级。
|
||||
|
||||
首版也可以先把 FX 保持在 `BarkBattleScene` 内，但必须仍然只消费 snapshot / visual events。
|
||||
|
||||
## 9. DOM HUD 设计
|
||||
|
||||
### 9.1 HUD 层级
|
||||
|
||||
DOM HUD 建议覆盖在 Phaser Canvas 上方：
|
||||
|
||||
```text
|
||||
BarkBattleRuntimeShell
|
||||
├─ <div className="bark-battle-canvas-host" />
|
||||
└─ <BarkBattleHud snapshot={snapshot} uiState={uiState} />
|
||||
```
|
||||
|
||||
HUD 分区：
|
||||
|
||||
- 顶部：红蓝声浪能量条 + 小型剩余时间。
|
||||
- 中央：仅在倒计时、关键提示或结算时短暂展示大号状态。
|
||||
- 左右边缘：双方简洁状态，例如叫声次数 / combo chip。
|
||||
- 底部角落：麦克风状态、重试、小菜单。
|
||||
- 结算：独立居中面板，显示胜负、叫声次数、最大音量、评分、再来一局、返回。
|
||||
|
||||
### 9.2 Playfield 保护
|
||||
|
||||
遵循 game UI 约束：
|
||||
|
||||
1. 正常 playing 阶段保持中心和下中部 playfield 清爽，不常驻长文案。
|
||||
2. 不把规则说明、长控制说明、多段提示默认铺在画面上。
|
||||
3. 权限、设置、结算使用独立面板或弹层，不在当前面板下面展开一大块内容。
|
||||
4. 移动端优先保证顶部能量条、倒计时、狗狗和重试入口可见可点。
|
||||
5. 大动效不能遮挡顶部能量条和倒计时。
|
||||
|
||||
### 9.3 CSS 设计建议
|
||||
|
||||
- 使用局部 CSS class 或 CSS module，避免污染全站。
|
||||
- 使用 CSS 变量定义主题：
|
||||
- `--bark-player-color`
|
||||
- `--bark-opponent-color`
|
||||
- `--bark-panel-bg`
|
||||
- `--bark-safe-bottom`
|
||||
- 使用 `dvh` / `svh` 和 safe-area inset 处理移动端地址栏与刘海。
|
||||
- `pointer-events` 分层：HUD 容器默认 `pointer-events: none`，按钮和面板恢复 `pointer-events: auto`。
|
||||
|
||||
## 10. 移动端与权限降级
|
||||
|
||||
### 10.1 移动端输入约束
|
||||
|
||||
移动端浏览器通常要求用户手势才能启动 AudioContext。开局流程必须是：
|
||||
|
||||
```text
|
||||
玩家点击“开始” → requestPermission → 创建/恢复 AudioContext → calibration → countdown → playing
|
||||
```
|
||||
|
||||
不要在页面加载时自动请求或自动启动 AudioContext。
|
||||
|
||||
### 10.2 响应式布局
|
||||
|
||||
移动端建议：
|
||||
|
||||
- 横屏优先呈现完整舞台；竖屏可保持舞台居中并缩小 HUD。
|
||||
- 顶部能量条高度保持可读，但不要占满大面积。
|
||||
- 结算面板宽度使用 `min(92vw, 420px)`。
|
||||
- 底部按钮避开 `env(safe-area-inset-bottom)`。
|
||||
- 非关键设置折叠进小菜单。
|
||||
|
||||
### 10.3 权限失败降级
|
||||
|
||||
权限失败时：
|
||||
|
||||
- `unsupported`：展示“当前浏览器不支持麦克风输入”，提供返回入口，不展示开始声控按钮。
|
||||
- `non-secure-context`：展示“当前环境无法使用麦克风”，提示切换到受支持的安全环境或返回。
|
||||
- `permission-denied`：展示简短说明和“重新授权”入口。
|
||||
- `not-found`：提示未检测到麦克风，提供重试授权或返回入口。
|
||||
- `not-readable`：提示麦克风被占用或暂时不可读，提供重试授权或返回入口。
|
||||
- `audio-context-blocked`：提示点击重试。
|
||||
- `calibration-timeout` / `calibration-sample-unreadable`：提示麦克风输入不可用，提供“重新校准”和返回入口。
|
||||
|
||||
可选开发调试降级：
|
||||
|
||||
- 本地 dev 可启用键盘 mock input，例如按住空格模拟音量峰值。
|
||||
- mock input 必须标记为开发/调试能力，不作为正式竞技能力。
|
||||
|
||||
## 11. 测试策略
|
||||
|
||||
### 11.1 Domain 单元测试（优先）
|
||||
|
||||
目标：不接 Phaser、不接 DOM、不接 Web Audio。
|
||||
|
||||
建议测试：
|
||||
|
||||
- `BarkDetector`：超过阈值且间隔足够时计为一次有效叫声。
|
||||
- `BarkDetector`：持续噪音不会无限计数。
|
||||
- `BarkDetector`：低于环境噪音阈值不计入叫声。
|
||||
- `EnergyTugOfWar`：玩家 power 高于对手时 energy 向玩家侧移动。
|
||||
- `EnergyTugOfWar`：energy clamp 在 `-100..100`。
|
||||
- `BarkBattleSession`：倒计时结束进入 playing。
|
||||
- `BarkBattleSession`：剩余时间归零进入 finished。
|
||||
- `BarkBattleSession`：按 energy 和 drawThreshold 判定胜 / 负 / 平。
|
||||
|
||||
### 11.2 Application 测试
|
||||
|
||||
目标：验证输入样本、AI、tick 和 snapshot 编排。
|
||||
|
||||
建议测试：
|
||||
|
||||
- 权限允许后进入校准，再进入倒计时。
|
||||
- 权限拒绝后 `phase` 为 `unavailable`、`errorReason` 为 `permission-denied`，不进入 playing。
|
||||
- 非安全上下文、设备未找到、设备不可读、AudioContext 被拦截时，controller snapshot 都进入 `phase: 'unavailable'`，并保留可供 HUD 区分的 `errorReason`。
|
||||
- 校准超时或样本持续不可读时，controller snapshot 使用 `errorReason: 'calibration-timeout'` 或 `calibration-sample-unreadable`，并提供重试校准动作。
|
||||
- 提交 mock audio sample 后 snapshot 中玩家状态更新。
|
||||
- AI 对手 power 参与能量条拉锯。
|
||||
- `lastEvents` 只发布新增视觉事件。
|
||||
|
||||
### 11.3 HUD 组件测试
|
||||
|
||||
目标：验证 snapshot 到 DOM 的展示映射。
|
||||
|
||||
建议测试：
|
||||
|
||||
- playing 阶段展示倒计时和能量条。
|
||||
- energy 正负值映射到玩家 / 对手侧比例。
|
||||
- `errorReason: 'permission-denied'` 展示重试授权入口。
|
||||
- `errorReason: 'unsupported'` 展示返回入口且不展示开始声控按钮。
|
||||
- `not-found`、`not-readable`、`non-secure-context`、`audio-context-blocked`、`calibration-timeout`、`calibration-sample-unreadable` 分别映射到可区分的简短状态文案和对应操作。
|
||||
- finished 展示胜负、叫声次数和再来一局。
|
||||
- 移动端 class / 结构不依赖 Phaser Canvas 才能渲染。
|
||||
|
||||
### 11.4 Phaser 集成与 smoke
|
||||
|
||||
自动化层面不强行在 Vitest 中完整启动 Phaser。建议：
|
||||
|
||||
- 用 adapter mock 测试 Scene 消费 snapshot 的纯映射函数。
|
||||
- 浏览器 smoke 验证真实 Canvas、Web Audio 和动画。
|
||||
- 若后续引入 Playwright，再做最小视觉和交互 smoke。
|
||||
|
||||
## 12. 验证命令建议
|
||||
|
||||
文档阶段只需要编码检查和 diff 检查：
|
||||
|
||||
```bash
|
||||
npm run check:encoding
|
||||
git diff -- docs/prd/BARK_BATTLE_BDD_2026-05-11.md docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
|
||||
```
|
||||
|
||||
后续实现 domain 后建议：
|
||||
|
||||
```bash
|
||||
npm run test -- --run src/games/bark-battle/domain/**/*.test.ts
|
||||
npm run typecheck
|
||||
npm run check:encoding
|
||||
```
|
||||
|
||||
后续实现 infrastructure/application 错误状态后建议：
|
||||
|
||||
```bash
|
||||
npm run test -- --run src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts src/games/bark-battle/application/__tests__/BarkBattleController.test.ts
|
||||
npm run typecheck
|
||||
npm run check:encoding
|
||||
```
|
||||
|
||||
后续实现 HUD 后建议：
|
||||
|
||||
```bash
|
||||
npm run test -- --run src/games/bark-battle/ui/**/*.test.tsx
|
||||
npm run lint:eslint
|
||||
npm run typecheck
|
||||
npm run check:encoding
|
||||
```
|
||||
|
||||
后续接入浏览器 runtime 后建议：
|
||||
|
||||
```bash
|
||||
npm run dev:web
|
||||
# 人工 smoke：授权麦克风 → 校准 → 发声 → 能量条变化 → 结算 → 再来一局
|
||||
```
|
||||
|
||||
若未来接入 Genarrative 正式玩法类型、后端持久化或发布链路，再追加对应契约、api-server 和 SpacetimeDB 验证；首版 runtime 原型不应提前新增这些命令作为门槛。
|
||||
|
||||
## 13. 后续落地顺序
|
||||
|
||||
建议后续实现按以下顺序推进：
|
||||
|
||||
1. 先建 `domain/` 和纯单元测试。
|
||||
2. 实现 `BarkDetector`、`EnergyTugOfWar`、`BarkBattleSession` 的最小规则。
|
||||
3. 建 `application/` controller，用 mock audio sample 跑通 snapshot。
|
||||
4. 实现 DOM HUD 的 permission / energy / timer / result 展示。
|
||||
5. 接入 `BrowserMicrophoneInput` 和校准流程。
|
||||
6. 接入 Phaser host、Scene 和 asset manifest，占位素材先跑通视觉反馈。
|
||||
7. 做移动端视口和权限失败 smoke。
|
||||
8. 产品确认后再决定是否进入正式玩法类型、作品发布和后端真相链。
|
||||
|
||||
## 14. 关键技术决策
|
||||
|
||||
1. 默认采用 Phaser 3 + TypeScript + Vite，符合 2D 浏览器游戏默认路线。
|
||||
2. 核心 simulation 放在纯 TypeScript domain，严格不依赖 Phaser / Web Audio / DOM。
|
||||
3. Web Audio 只作为输入 adapter，输出归一化 `BarkAudioSample`。
|
||||
4. Phaser Scene 是 renderer，只消费 snapshot 和 visual events，不承载规则真相。
|
||||
5. HUD 使用 DOM overlay，承载权限、能量条、倒计时、结算和移动端响应式布局。
|
||||
6. MVP 不做复杂狗叫语义识别，先用音量峰值、持续时长、冷却和环境噪音校准。
|
||||
7. MVP 建议玩家 vs AI 单机 runtime，正式成绩、排行榜、发布和奖励后续再交给后端链路。
|
||||
1055
docs/technical/BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md
Normal file
1055
docs/technical/BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -47,7 +47,7 @@
|
||||
|
||||
用户完成热身关所有步骤后，进入关卡选择。
|
||||
|
||||
当前后续游戏仍在设计中。热身结束后可先展示“开始游戏”按钮作为关卡选择占位，用户点击后进入下一关占位界面。
|
||||
热身结束后展示“开始游戏”按钮，用户点击后进入宝贝识物首关本地 Demo。该入口只用于热身关后的本地体验验证；正式平台体验仍必须通过“宝贝识物”创作模板发布后，在寓教于乐板块进入。
|
||||
|
||||
### 3.3 固定流程顺序
|
||||
|
||||
@@ -642,7 +642,7 @@
|
||||
|
||||
1. `src/ChildMotionDemoApp.tsx` 挂载独立 Demo 应用壳。
|
||||
2. `src/components/child-motion-demo/childMotionWarmupModel.ts` 维护热身步骤、圆环目标、2 秒保持判定、热身校准记录和当前运行时会话完成标记。
|
||||
3. `src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 实现横屏舞台、背景虚化占位层、角色剪影、绿色圆环、手势引导、热身记录面板、热身完成后的“开始游戏”按钮和下一关占位界面。
|
||||
3. `src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 实现横屏舞台、背景虚化占位层、角色剪影、绿色圆环、手势引导、热身记录面板、热身完成后的“开始游戏”按钮，并复用宝贝识物运行态进入首关本地 Demo。
|
||||
4. `src/services/child-motion-demo/childMotionDebugInput.ts` 保留开发者调试输入适配层，后续可被正式动作识别 SDK 适配层替换或并行接入。
|
||||
5. `src/routing/appRoutes.tsx` 新增 `/child-motion-demo` 独立路由，并复用 `VITE_ENABLE_EDUTAINMENT_ENTRY` 开关；开关关闭时不允许通过该直达路径进入 Demo。
|
||||
|
||||
@@ -669,19 +669,27 @@
|
||||
当前未接入但已保留边界：
|
||||
|
||||
1. 正式语音播报接口暂不接入，当前先展示热身文案。
|
||||
2. 正式 gpt-image-2 视觉资源暂不接入，当前使用 CSS 占位表达相同位置和状态。
|
||||
3. 后续关卡安全边界暂停逻辑暂未落地，当前只完成热身记录和下一关按钮占位。
|
||||
2. 后续关卡安全边界暂停逻辑暂未落地，当前只完成热身记录和宝贝识物首关本地 Demo 衔接。
|
||||
|
||||
## 16. 当前视觉资产与生图口径补充
|
||||
|
||||
儿童动作 Demo 的视觉口径已经统一收敛到绘本风格草地舞台：
|
||||
|
||||
1. 舞台主环境采用卡通绘本风格、明亮草地、天空、小山坡和树木的组合，默认背景环境需要保证中心与下方前景留空，便于角色轮廓和地面指示环叠加。
|
||||
2. `src/index.css` 中的热身舞台、摄像头背景层、地面、角色轮廓、地面圆环、开始按钮和横屏提示均按绘本草地风格重做，未生成真实背景图时由 CSS 兜底。
|
||||
3. 真实背景图的默认输出路径固定为 `public/child-motion-demo/picture-book-grass-stage.webp`。
|
||||
4. 生成脚本固定为 `scripts/generate-child-motion-demo-assets.mjs`，并通过 `npm run assets:child-motion-demo` 触发；脚本使用 `gpt-image-2-all` 调用 VectorEngine `POST /v1/images/generations`。
|
||||
5. 当前本机工作区未检测到 `VECTOR_ENGINE_BASE_URL` 与 `VECTOR_ENGINE_API_KEY`，因此暂时只能完成 dry-run 或代码层接入，不能直接产出真实 image-2 资产。
|
||||
6. 若后续补齐 VectorEngine 私密配置，再运行 live 生成即可把真实绘本背景写入上述固定路径，页面会自动读取。
|
||||
2. 该卡通绘本草地风格是儿童动作 Demo 后续场景、物品、UI 资源的全局风格要求；新增资源不得切回暗色科技风、真实照片风或后台面板风。
|
||||
3. `src/index.css` 中的热身舞台、摄像头背景层、地面、角色轮廓、地面圆环、开始按钮和横屏提示均按绘本草地风格接入真实资源；资源加载失败时保留 CSS 兜底。
|
||||
4. 生成脚本固定为 `scripts/generate-child-motion-demo-assets.mjs`，并通过 `npm run assets:child-motion-demo` 触发；脚本使用 `gpt-image-2-all` 调用 VectorEngine `POST /v1/images/generations`，透明资源先生成品红底源图，再在本地移除色键，源图写入 `tmp/child-motion-demo-assets/`。
|
||||
5. 当前已生成并接入以下正式 Demo 资源：
|
||||
- `public/child-motion-demo/picture-book-grass-stage.png`：默认草地舞台背景。
|
||||
- `public/child-motion-demo/picture-book-foreground-grass-v2.png`：底部前景草坪条，只覆盖舞台下沿，不作为整块地板拉伸。
|
||||
- `public/child-motion-demo/picture-book-ground-ring-v2.png`：已按透视绘制的地面椭圆指示环，CSS 只等比缩放。
|
||||
- `public/child-motion-demo/picture-book-character-outline-v2.png`：半透明用户角色轮廓，使用独立去背后处理避免内部填充被误删。
|
||||
- `public/child-motion-demo/picture-book-hud-strip-v2.png`：顶部 HUD 细长软纸条。
|
||||
- `public/child-motion-demo/picture-book-calibration-strip-v2.png`：右下角五格热身状态条。
|
||||
- `public/child-motion-demo/picture-book-start-panel-v2.png`：开始按钮背后的轻盈托盘。
|
||||
- `public/child-motion-demo/picture-book-ui-button-v2.png`：开始按钮绘本风按钮底图。
|
||||
6. v2 资源按最终用途拆分，CSS 必须按资源原始比例、`aspect-ratio` 或 `background-size: contain / auto` 等方式等比使用；禁止把方形面板强行拉伸为 HUD、状态条或地板，也禁止把底部草坪扩展成覆盖角色脚下的大色块。
|
||||
7. 若后续补充或重绘资源，应先运行 `npm run assets:child-motion-demo -- --dry-run` 核对 prompt 和输出路径，再使用 `--live --only <asset-id>` 小批量生成；仅调整透明去背、裁切、画布归一或品红边缘时，可用 `npm run assets:child-motion-demo -- --live --postprocess-only --force --only <asset-id>` 复用 `tmp/child-motion-demo-assets/` 中的源图，不额外请求 image-2；不得把 `VECTOR_ENGINE_API_KEY`、源图或中间预览图提交到仓库。
|
||||
|
||||
已执行的定向验证命令：
|
||||
|
||||
|
||||
@@ -76,3 +76,16 @@
|
||||
3. 只有用户显式修改或重置密码后，才允许密码登录。
|
||||
|
||||
后续迁移到 SpacetimeDB 表时，保持同一语义：密码哈希字段允许为空，密码登录 reducer 不承担注册能力，验证码登录 reducer 承担“无账号则自动注册”的唯一注册入口。
|
||||
|
||||
## 5. 2026-05-12 快照同步修复
|
||||
|
||||
重置密码和修改密码都会改变认证真相：`password_hash`、`password_login_enabled`、`token_version`，重置密码还会立即创建新的 refresh session。因此 API 层在 `POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后，必须和密码登录、手机号登录、刷新、退出一样调用 `sync_auth_store_snapshot_to_spacetime()`。
|
||||
|
||||
若只更新本地 `InMemoryAuthStore` 而不同步 SpacetimeDB 认证快照，`api-server` 重启时可能从旧的 SpacetimeDB 表或旧快照恢复账号状态，表现为用户已通过忘记密码重设成功，但再次密码登录仍返回“手机号或密码错误”。启动恢复时应从 SpacetimeDB 表、SpacetimeDB 快照记录和本地 `GENARRATIVE_AUTH_STORE_PATH` 文件中选择可判断的最新快照；当本地文件更新且远端表无更新时间戳时，优先使用本地文件并尝试回写 SpacetimeDB，避免旧远端状态覆盖刚重设的密码。
|
||||
|
||||
验证命令：
|
||||
|
||||
```bash
|
||||
cargo test -p module-auth password --manifest-path server-rs/Cargo.toml
|
||||
cargo test -p api-server password --manifest-path server-rs/Cargo.toml
|
||||
```
|
||||
|
||||
@@ -4,8 +4,12 @@
|
||||
|
||||
## 文档列表
|
||||
|
||||
- [WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md](./WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md)：记录微信小程序 `web-view` 壳的最小接入范围、需要填写的 H5 业务域名、微信后台配置、`npm run check:wechat-miniprogram-auth` 可重复登录链路 smoke 和后续原生化边界。
|
||||
- [BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md](./BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md)：冻结“汪汪声浪大作战 / bark-battle”后端 DDD 技术方案，明确 `server-rs + Axum + SpacetimeDB` 分层边界、shared contracts、作品配置、runtime run、派生成绩、排行榜、`work_play_start` 埋点、migration/绑定生成策略，以及不保存原始麦克风音频的隐私与反作弊约束。
|
||||
- [BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md](./BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md)：冻结“汪汪声浪大作战 / bark-battle”2D 浏览器 runtime 技术方案，明确 Phaser + TypeScript + Vite 选型、纯 TS simulation 与 Phaser renderer/DOM HUD 边界、Web Audio 输入适配、移动端权限降级和后续测试验证命令。
|
||||
- [PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md](./PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md)：记录直接访问公开作品详情深链时作品不存在或已下架的回首页修复，避免关闭提示后停在 `work-detail` 空状态白屏。
|
||||
- [PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md](./PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md)：冻结移动端推荐页隐藏顶部品牌栏、扩大推荐卡片可用高度，以及只在底部作品信息区承接切换作品手势的布局口径。
|
||||
- [BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md](./BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md)：冻结寓教于乐 `宝贝识物` 模板创作发布线程的前端入口、契约、service、结果页、发布标签和后端 image-2 接口预留边界。
|
||||
- [CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md](./CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md)：冻结儿童动作识别互动玩法 Demo 固定热身关的开发落地规格，覆盖横屏展示、摄像头背景虚化、角色剪影、绿色圆环 2 秒保持、动作教学、当前会话内空间边界记录和后续关卡安全暂停规则。
|
||||
- [RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md](./RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md)：记录运行态输入设备抽象层，明确鼠标、触控、mocap 等设备统一归一为通用拖拽语义，玩法组件只负责解释目标和落点。
|
||||
- [RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md](./RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md)：记录 `server-rs` Cargo 依赖集中配置口径，第三方版本和 workspace 内部 crate path 统一维护在根 `server-rs/Cargo.toml`，成员 crate 只保留 feature/optional 差异；同时冻结 `shared-contracts` 不得反向依赖 `platform-*`，避免 SpacetimeDB 模块发布时拉入 `wasm-bindgen`。
|
||||
|
||||
@@ -92,6 +92,25 @@
|
||||
2. 若是并入已有手机号正式账号，则返回目标正式账号快照，当前实现会保持其账号主登录方式，例如 `loginMethod = phone`。
|
||||
3. 但 access token 中的 `provider` 仍按**本次登录来源**签发，不依赖账号主登录方式推断，因此微信绑定后的当前会话仍会签发 `provider = wechat`。
|
||||
|
||||
### 3.4 `POST /api/auth/wechat/miniprogram-login`
|
||||
|
||||
职责固定为：
|
||||
|
||||
1. 接收微信小程序原生壳通过 `wx.login` 拿到的 `code`。
|
||||
2. 在 `Axum` 内调用微信 `jscode2session`，兑换 `openid/unionid`。
|
||||
3. 复用 `resolve_login` 处理 `unionid/openid -> user_id` 的查找、补写和待绑定账号创建。
|
||||
4. 签发本系统 access token，并创建 refresh session。
|
||||
5. 返回：
|
||||
- `token`
|
||||
- `bindingStatus`
|
||||
- `user`
|
||||
|
||||
关键约束：
|
||||
|
||||
1. 小程序壳不能把裸 `openid` 直接拼给 H5 做登录。
|
||||
2. H5 仍只消费本系统 `auth_token`，小程序壳只是把这枚 token 放入既有 hash 回调格式。
|
||||
3. 小程序请求必须补传 `x-client-type=mini_program` 与 `x-client-runtime=wechat_mini_program`，用于 refresh session 记录来源。
|
||||
|
||||
## 4. 当前最小实现策略
|
||||
|
||||
当前阶段为了先打通 Rust 后端闭环，采用以下最小实现：
|
||||
@@ -125,6 +144,7 @@
|
||||
4. `GET /api/auth/wechat/start`
|
||||
5. `GET /api/auth/wechat/callback`
|
||||
6. `POST /api/auth/wechat/bind-phone`
|
||||
7. `POST /api/auth/wechat/miniprogram-login`
|
||||
|
||||
## 6. 环境变量
|
||||
|
||||
@@ -139,11 +159,14 @@
|
||||
7. `WECHAT_AUTHORIZE_ENDPOINT`
|
||||
8. `WECHAT_ACCESS_TOKEN_ENDPOINT`
|
||||
9. `WECHAT_USER_INFO_ENDPOINT`
|
||||
10. `WECHAT_STATE_TTL_MINUTES`
|
||||
11. `WECHAT_MOCK_USER_ID`
|
||||
12. `WECHAT_MOCK_UNION_ID`
|
||||
13. `WECHAT_MOCK_DISPLAY_NAME`
|
||||
14. `WECHAT_MOCK_AVATAR_URL`
|
||||
10. `WECHAT_JS_CODE_SESSION_ENDPOINT`
|
||||
11. `WECHAT_MINI_PROGRAM_APP_ID`
|
||||
12. `WECHAT_MINI_PROGRAM_APP_SECRET`
|
||||
13. `WECHAT_STATE_TTL_MINUTES`
|
||||
14. `WECHAT_MOCK_USER_ID`
|
||||
15. `WECHAT_MOCK_UNION_ID`
|
||||
16. `WECHAT_MOCK_DISPLAY_NAME`
|
||||
17. `WECHAT_MOCK_AVATAR_URL`
|
||||
|
||||
## 7. 与后续 SpacetimeDB 的衔接要求
|
||||
|
||||
|
||||
@@ -100,6 +100,9 @@ real 模式行为固定为：
|
||||
| `WECHAT_AUTHORIZE_ENDPOINT` | 否 | 默认桌面二维码授权地址 |
|
||||
| `WECHAT_ACCESS_TOKEN_ENDPOINT` | 否 | 默认 access_token 接口 |
|
||||
| `WECHAT_USER_INFO_ENDPOINT` | 否 | 默认用户信息接口 |
|
||||
| `WECHAT_JS_CODE_SESSION_ENDPOINT` | 否 | 默认小程序 `jscode2session` 接口 |
|
||||
| `WECHAT_MINI_PROGRAM_APP_ID` | 小程序 `real` 模式必填 | 微信小程序 AppID；不填时回退 `WECHAT_APP_ID` |
|
||||
| `WECHAT_MINI_PROGRAM_APP_SECRET` | 小程序 `real` 模式必填 | 微信小程序 AppSecret；不填时回退 `WECHAT_APP_SECRET` |
|
||||
| `WECHAT_STATE_TTL_MINUTES` | 否 | state 有效期，默认 `15` 分钟 |
|
||||
|
||||
补充说明：
|
||||
@@ -225,7 +228,46 @@ https://game.example.com
|
||||
- `wechatBound = true`
|
||||
- `bindingStatus` 已更新为目标状态
|
||||
|
||||
## 8. 账号命中规则
|
||||
## 8. 小程序 web-view 登录联调步骤
|
||||
|
||||
小程序壳走原生 `wx.login`，不走网页 OAuth callback。联调前需要额外确认：
|
||||
|
||||
```bash
|
||||
WECHAT_AUTH_ENABLED=true
|
||||
WECHAT_AUTH_PROVIDER=real
|
||||
WECHAT_MINI_PROGRAM_APP_ID="你的微信小程序 AppID"
|
||||
WECHAT_MINI_PROGRAM_APP_SECRET="你的微信小程序 AppSecret"
|
||||
```
|
||||
|
||||
在 `miniprogram/config.js` 中确认：
|
||||
|
||||
```js
|
||||
const WEB_VIEW_ENTRY_URL = 'https://你的H5业务域名/';
|
||||
const API_BASE_URL = 'https://你的服务器域名/';
|
||||
const MINI_PROGRAM_APP_ID = '你的微信小程序 AppID';
|
||||
```
|
||||
|
||||
联调流程：
|
||||
|
||||
1. 微信开发者工具打开项目根目录。
|
||||
2. 小程序启动后调用 `wx.login`。
|
||||
3. 小程序壳请求：
|
||||
|
||||
```http
|
||||
POST /api/auth/wechat/miniprogram-login
|
||||
```
|
||||
|
||||
4. 后端通过 `jscode2session` 兑换 `openid/unionid`。
|
||||
5. 后端返回系统 `token`、`bindingStatus` 与 `user`。
|
||||
6. 小程序壳打开 H5，并在 hash 中附加：
|
||||
- `auth_provider=wechat`
|
||||
- `auth_token=...`
|
||||
- `auth_binding_status=active|pending_bind_phone`
|
||||
7. H5 消费 hash 后通过 `/api/auth/me` 恢复登录态。
|
||||
|
||||
这里不能把裸 `openid` 作为 web-view query 登录凭证；`openid` 只能留在后端身份绑定层，H5 只消费本系统 JWT。
|
||||
|
||||
## 9. 账号命中规则
|
||||
|
||||
当前实现固定按以下顺序命中已有账号：
|
||||
|
||||
@@ -238,7 +280,7 @@ https://game.example.com
|
||||
1. 若按 `unionid` 命中了已有微信身份，但本次微信回调带来了新的 `openid`，后端会把新的 `openid -> user_id` 映射补齐
|
||||
2. 若后续绑定手机号时发现该手机号已经属于正式账号，则会把微信身份并入这个正式账号
|
||||
|
||||
## 9. 前端验收点
|
||||
## 10. 前端验收点
|
||||
|
||||
前端联调时至少检查以下行为：
|
||||
|
||||
|
||||
187
docs/technical/WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md
Normal file
187
docs/technical/WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# 微信小程序 web-view 壳接入记录
|
||||
|
||||
日期：`2026-05-03`
|
||||
|
||||
## 1. 目标
|
||||
|
||||
本次先用微信小程序 `web-view` 承载现有 H5，不重写 React/Vite 主前端，也不把 SpacetimeDB SDK 或业务规则搬进小程序端。
|
||||
|
||||
当前小程序壳只承担五件事：
|
||||
|
||||
1. 提供微信开发者工具可识别的 `miniprogram/` 工程根目录。
|
||||
2. 在原生小程序壳中调用 `wx.login` 获取小程序 `code`。
|
||||
3. 调用服务器域名下的 `/api/auth/wechat/miniprogram-login`，由 Rust `api-server` 兑换微信身份并签发系统登录态。
|
||||
4. 若后端返回 `pending_bind_phone`，先在小程序原生层通过 `button open-type="getPhoneNumber"` 取得用户同意后的手机号动态令牌，再调用 `/api/auth/wechat/bind-phone` 完成绑定。
|
||||
5. 用一个全屏 `web-view` 打开现有 H5 入口，并把系统 `auth_token` 放入 H5 现有登录回调 hash。
|
||||
|
||||
重要边界：
|
||||
|
||||
1. `openid` 只作为后端微信身份绑定依据，不直接暴露给 H5 当登录凭证。
|
||||
2. H5 继续消费本系统 JWT，也就是 `#auth_provider=wechat&auth_token=...&auth_binding_status=...`。
|
||||
3. 这与 [`WECHAT_LOGIN_AXUM_IMPLEMENTATION_DESIGN_2026-04-21.md`](./WECHAT_LOGIN_AXUM_IMPLEMENTATION_DESIGN_2026-04-21.md) 中“微信只提供三方身份，Axum 签发系统 JWT”的边界一致。
|
||||
|
||||
## 2. 文件入口
|
||||
|
||||
| 文件 | 说明 |
|
||||
| --- | --- |
|
||||
| `project.config.json` | 指定 `miniprogramRoot: "miniprogram/"`。 |
|
||||
| `miniprogram/app.json` | 小程序全局配置，注册 `pages/web-view/index`。 |
|
||||
| `miniprogram/config.js` | 业务域名入口配置，需要部署时填写。 |
|
||||
| `miniprogram/pages/web-view/index.*` | 最小 web-view 页面。 |
|
||||
| `server-rs/crates/api-server/src/wechat_auth.rs` | 新增小程序登录接口 `/api/auth/wechat/miniprogram-login`。 |
|
||||
| `server-rs/crates/platform-auth/src/lib.rs` | 新增 `jscode2session` 兑换能力。 |
|
||||
|
||||
## 3. 需要手工填写的配置
|
||||
|
||||
在 `miniprogram/config.js` 中填写：
|
||||
|
||||
```js
|
||||
const WEB_VIEW_ENTRY_URL = 'https://你的H5业务域名/';
|
||||
const API_BASE_URL = 'https://你的服务器域名/';
|
||||
const MINI_PROGRAM_APP_ID = '你的微信小程序 AppID';
|
||||
const MINI_PROGRAM_ENV = 'develop';
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
1. 必须是 `https`。
|
||||
2. 不能是 `localhost` 或 IP。
|
||||
3. `WEB_VIEW_ENTRY_URL` 域名需要在微信小程序后台配置为业务域名。
|
||||
4. `API_BASE_URL` 域名需要在微信小程序后台配置为 request 合法域名。
|
||||
5. H5 页面里的 API、图片、音视频、iframe 等外链也要满足微信侧域名与证书要求。
|
||||
|
||||
在 `api-server` 环境变量中填写：
|
||||
|
||||
```bash
|
||||
WECHAT_AUTH_ENABLED=true
|
||||
WECHAT_AUTH_PROVIDER=real
|
||||
WECHAT_MINI_PROGRAM_APP_ID="你的微信小程序 AppID"
|
||||
WECHAT_MINI_PROGRAM_APP_SECRET="你的微信小程序 AppSecret"
|
||||
WECHAT_JS_CODE_SESSION_ENDPOINT="https://api.weixin.qq.com/sns/jscode2session"
|
||||
WECHAT_STABLE_ACCESS_TOKEN_ENDPOINT="https://api.weixin.qq.com/cgi-bin/stable_token"
|
||||
WECHAT_PHONE_NUMBER_ENDPOINT="https://api.weixin.qq.com/wxa/business/getuserphonenumber"
|
||||
```
|
||||
|
||||
如果开放平台网页 OAuth 与小程序使用同一个 AppID/Secret，也可以继续使用已有：
|
||||
|
||||
```bash
|
||||
WECHAT_APP_ID="你的微信 AppID"
|
||||
WECHAT_APP_SECRET="你的微信 AppSecret"
|
||||
```
|
||||
|
||||
但正式部署建议把小程序配置写到 `WECHAT_MINI_PROGRAM_APP_ID` 与 `WECHAT_MINI_PROGRAM_APP_SECRET`，避免和网页 OAuth 配置混淆。
|
||||
|
||||
`WEB_VIEW_SOURCE_QUERY` 默认附加：
|
||||
|
||||
```text
|
||||
clientType=mini_program
|
||||
clientRuntime=wechat_mini_program
|
||||
```
|
||||
|
||||
小程序壳调用登录接口时会补传：
|
||||
|
||||
```text
|
||||
x-client-type=mini_program
|
||||
x-client-runtime=wechat_mini_program
|
||||
x-client-platform=ios|android|unknown
|
||||
x-client-instance-id=<小程序本地持久化随机值>
|
||||
x-mini-program-app-id=<MINI_PROGRAM_APP_ID>
|
||||
x-mini-program-env=<MINI_PROGRAM_ENV>
|
||||
```
|
||||
|
||||
这些字段会进入 refresh session 的客户端身份快照；URL query 只作为 H5 识别宿主来源的轻量标记，不作为鉴权依据。
|
||||
|
||||
## 4. 登录链路
|
||||
|
||||
当前登录链路固定为：
|
||||
|
||||
1. 小程序页面启动。
|
||||
2. 调用 `wx.login` 获取一次性 `code`。
|
||||
3. 小程序壳请求：
|
||||
|
||||
```http
|
||||
POST /api/auth/wechat/miniprogram-login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"code": "wx.login 返回的 code"
|
||||
}
|
||||
```
|
||||
|
||||
4. `api-server` 调用微信 `jscode2session` 兑换 `openid/unionid`。
|
||||
5. `api-server` 复用现有微信身份逻辑：
|
||||
- 先按 `unionid` 命中已有身份
|
||||
- 再按 `openid` 命中已有身份
|
||||
- 都没有命中时创建 `pending_bind_phone` 的微信壳账号
|
||||
6. `api-server` 签发系统 access token，并写入 refresh session。
|
||||
7. 如果返回 `bindingStatus=active`，小程序壳打开：
|
||||
|
||||
```text
|
||||
https://你的H5业务域名/#auth_provider=wechat&auth_token=<系统JWT>&auth_binding_status=active
|
||||
```
|
||||
|
||||
8. 如果返回 `bindingStatus=pending_bind_phone`，小程序壳暂不打开 H5，而是展示原生 `getPhoneNumber` 按钮。用户点击并同意后，小程序把 `bindgetphonenumber` 事件里的 `detail.code` 作为 `wechatPhoneCode` 传给：
|
||||
|
||||
```http
|
||||
POST /api/auth/wechat/bind-phone
|
||||
Authorization: Bearer <小程序登录返回的系统JWT>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"wechatPhoneCode": "getPhoneNumber 返回的 code"
|
||||
}
|
||||
```
|
||||
|
||||
9. `api-server` 通过微信 `stable_token` 获取小程序 `access_token`，再调用 `getuserphonenumber` 换取平台验证后的手机号，并复用现有微信待绑定账号合并逻辑。成功后重新签发 `active` 系统 token。
|
||||
10. H5 复用 `consumeAuthCallbackResult()` 消费 `auth_token` 并进入现有登录态恢复流程。
|
||||
|
||||
补充：H5 里的旧短信验证码绑定页继续保留为非小程序环境兜底；小程序原生手机号授权只替代“手动输入手机号 + 短信验证码”这一步，不代表后台静默读取本机号码。
|
||||
|
||||
## 5. 微信后台配置
|
||||
|
||||
至少需要在小程序后台配置：
|
||||
|
||||
1. `业务域名`：承载 H5 的域名。
|
||||
2. `request 合法域名`：`API_BASE_URL` 对应的服务器域名。
|
||||
3. `socket 合法域名`：若后续小程序原生层直连 WebSocket 才需要；当前不启用。
|
||||
|
||||
当前仓库的 H5 仍建议通过同域 `/api/*` 访问 Rust `api-server`，避免在小程序和 H5 中分别维护跨域白名单。
|
||||
|
||||
## 6. 当前不做的事
|
||||
|
||||
本次不做原生小程序页面迁移，原因是当前主前端依赖：
|
||||
|
||||
1. React DOM 挂载、浏览器 history 和 `window.location`。
|
||||
2. `localStorage` / `sessionStorage`。
|
||||
3. 浏览器 `fetch` 与 `ReadableStream` SSE。
|
||||
4. DOM、Canvas、Three.js 等浏览器渲染能力。
|
||||
|
||||
这些能力不能稳定原样运行在原生小程序宿主中。后续如要原生化，应新建小程序端宿主，复用 `packages/shared` 契约和 `api-server` BFF，而不是把 `src/` 整体搬过去。
|
||||
|
||||
本次也不做 `openid` query 直登。原因是 `openid` 不是本系统签发的登录凭证，不能表达 token 版本、会话 ID、绑定状态、角色与过期时间，也不能被 H5 直接信任。
|
||||
|
||||
## 7. 验收口径
|
||||
|
||||
可重复自动化 smoke：
|
||||
|
||||
```bash
|
||||
npm run check:wechat-miniprogram-auth
|
||||
```
|
||||
|
||||
该命令固定覆盖三段链路：
|
||||
|
||||
1. 静态确认 `miniprogram/pages/web-view/index.js` 会请求 `/api/auth/wechat/miniprogram-login`，携带 `mini_program / wechat_mini_program` 客户端来源头，并把 `auth_provider/auth_token/auth_binding_status` 拼入 H5 hash。
|
||||
2. 运行 `api-server` 定向测试 `wechat_miniprogram_login_returns_system_token_and_marks_session_source`，断言小程序登录返回 `token/bindingStatus/user`、写入 refresh cookie，并且 `/api/auth/sessions` 能看到 `clientType=mini_program`、`clientRuntime=wechat_mini_program`、`miniProgramAppId`。
|
||||
3. 静态确认小程序壳在 `pending_bind_phone` 时使用 `getPhoneNumber` 和 `wechatPhoneCode` 调用 `/api/auth/wechat/bind-phone`，而不是打开 H5 后再要求手输手机号。
|
||||
4. 运行前端 `authService` 定向测试，断言 `consumeAuthCallbackResult()` 会消费 `#auth_provider=wechat&auth_token=...&auth_binding_status=...`、保存 access token，并清理地址栏 hash。
|
||||
|
||||
手工联调仍按以下口径确认真实微信与域名配置：
|
||||
|
||||
1. 微信开发者工具打开项目根目录后，识别 `miniprogram/` 为小程序源码目录。
|
||||
2. 未填写 `WEB_VIEW_ENTRY_URL` 或 `API_BASE_URL` 时，页面显示配置提示，不出现空白页。
|
||||
3. 填写已配置业务域名后，小程序先请求 `/api/auth/wechat/miniprogram-login`。
|
||||
4. 后端返回 `token/bindingStatus/user`，并写入 refresh cookie。
|
||||
5. 若返回 `pending_bind_phone`，先看到小程序原生授权手机号按钮；用户同意后，小程序请求 `/api/auth/wechat/bind-phone` 且请求体包含 `wechatPhoneCode`。
|
||||
6. 绑定成功后首页全屏打开 H5，URL hash 中包含 `auth_provider=wechat`、`auth_token`、`auth_binding_status=active`。
|
||||
7. H5 内 `consumeAuthCallbackResult()` 消费 hash 后，`/api/auth/me` 能返回当前用户。
|
||||
8. `/api/auth/sessions` 能看到来源为 `mini_program / wechat_mini_program` 的会话记录。
|
||||
Reference in New Issue
Block a user