1

2026-05-13 00:28:07 +08:00
parent ef4f91a75e
commit 01c5ab985a
101 changed files with 10635 additions and 2292 deletions
--- a/docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md
+++ b/docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md
@@ -96,7 +96,7 @@ Match3D 必须形成独立玩法域，后续技术方案至少需要覆盖：
 2. 创建流程采用入口表单收集关键配置。
 3. 表单必须在进入结果页前确认：
   - 题材主题
-   - 3D 素材风格
+   - 2D 素材风格
   - 难度选项
 4. `需要消除次数` 与难度 `1~10` 数值不再作为独立输入框展示，由难度选项派生。
 5. 生成抓大鹅草稿消耗 `20` 光点，生成按钮必须显式展示。
@@ -110,7 +110,7 @@ Match3D 必须形成独立玩法域，后续技术方案至少需要覆盖：
 13. 清空圆形空间中全部物品即胜利。
 14. 倒计时结束或备选栏满即失败。
 15. 胜利 / 失败后展示结算界面。
-16. 入口页的 3D 素材风格选择会进入素材图提示词，并作为结果页手动 Rodin 3D 模型生成的默认提示词依据。
+16. 入口页的 2D 素材风格选择会进入素材图提示词，并作为后续物品素材新增和重绘的默认提示词依据。
 17. 点击、入槽、消除、失败、胜利的即时反馈效果由前端先行呈现，后端负责权威确认、状态落库和成绩可信性。

 ---
@@ -124,7 +124,7 @@ Match3D 必须形成独立玩法域，后续技术方案至少需要覆盖：
 3. 不做排行榜正式展示。
 4. 不做道具，但需要预留功能口。
 5. 不做洗牌、重置、旋转、放大等局内操作。
-6. 不做多批次真实 3D 模型生成；当前草稿生成只固定产出 `3` 个 GLB 模型并写入 OSS。
+6. 不做首屏真实 3D 模型生成；当前草稿生成以多视角 2D 物品素材为主，并写入 OSS。
 7. 不做真实 3D 物理遮挡。
 8. 不做真实物理碰撞结算。
 9. 不做必须试玩通关才能发布的门槛。
@@ -143,7 +143,7 @@ Match3D 首版参考拼图后期的入口表单收集方式，而不是早期的
 表单的职责是帮助用户确认可以直接编译 demo 的最小配置：

 1. 题材主题。
-2. 3D 素材风格。
+2. 2D 素材风格。
 3. 游戏难度选项。

 `需要消除次数` 与游戏难度数值仍属于后端会话配置，但不再要求用户手填。当前入口页固定采用以下映射：
@@ -152,7 +152,7 @@ Match3D 首版参考拼图后期的入口表单收集方式，而不是早期的
 轻松 -> 需要消除 8 次，难度 2
 标准 -> 需要消除 12 次，难度 4
 进阶 -> 需要消除 16 次，难度 6
-硬核 -> 需要消除 20 次，难度 8
+硬核 -> 需要消除 21 次，难度 8
 ```

 ## 6.2 必填配置
@@ -161,7 +161,7 @@ Match3D 首版参考拼图后期的入口表单收集方式，而不是早期的

 题材决定后续生成或选择物品素材的方向。用户可以自定义主题，例如水果、玩具、食物、符号等。

-当前抓大鹅草稿生成会固定生成 `3` 个题材物品：素材图切割出的独立图片会作为 Rodin 图生 3D 参考图，生成出的 GLB 模型必须转存 OSS，并随作品 profile 的 `generatedItemAssets` 持久化。运行态优先使用这些生成模型；只有模型缺失、加载失败或未进入 3D 渲染模式时，才回退到 25 个默认积木件视觉键。默认素材不使用透明气泡，也不在图案上放文字标识。
+当前抓大鹅草稿会按难度生成题材物品：素材图切割出的多视角 2D 图片必须转存 OSS，并随作品 profile 的 `generatedItemAssets` 持久化。运行态优先使用这些生成图片；只有图片缺失、读取失败或未进入生成素材模式时，才回退到默认积木件视觉键。默认素材不使用透明气泡，也不在图案上放文字标识。

 可消除物尺寸使用五档相对体积规则：XL 型相对体积为 `1.60~2.30`，L 型为 `1.25~1.60`，M 型为 `1.00`，XS 型为 `0.65~0.85`，S 型为 `0.35~0.50`。单局中 XL / L / M / XS / S 按本局使用的消除物类型数的 `20% / 30% / 30% / 15% / 5%` 分配；非整数配额按最大余数补齐，确保总数等于本局使用类型数量。同一关卡内同一个颜色和造型的物品只能对应一个尺寸档位；可存在同尺寸但不同颜色和造型的物品。后端运行态通过 `radius` 下发权威尺寸，前端只按快照表现。

@@ -183,19 +183,25 @@ Match3D 首版参考拼图后期的入口表单收集方式，而不是早期的

 首版 demo 中，用户只需凭感觉选择难度；具体难度规则由系统内部解释。后续优化阶段再细化难度曲线、生成算法和遮挡策略。

-### 3D 素材风格
+### 2D 素材风格

-入口页在题材主题与难度之间展示 `3D素材风格` 横向滑动选择。首批固定选项为：
+入口页在题材主题与难度之间展示 `2D素材风格` 横向滑动选择。首批固定选项为：

 ```text
-黏土手作 / 低多边形 / 玩具塑料 / 木质雕刻 / 体素积木 / 金属机甲 / 自定义
+扁平图标 / 赛璐璐卡通 / 像素复古 / 手绘水彩 / 贴纸描边 / 厚涂图标 / 自定义
 ```

 每个内置选项使用 VectorEngine `gpt-image-2-all` 生成的画风参考图展示；参考图保存在 `public/match3d-style-references/`，只作为入口选择的视觉提示，不作为用户上传参考图。选择内置风格时，前端提交 `assetStyleId`、`assetStyleLabel` 与对应 `assetStylePrompt`。选择 `自定义` 时必须弹出独立面板，用户填写描述后才允许应用；自定义描述作为 `assetStylePrompt` 进入后端生成链路。

 ## 6.3 参考图片

-抓大鹅入口页不展示参考图片上传。题材表现由题材文本和草稿切割图片链路承接；草稿生成阶段会直接以切割图片作为 Rodin 图生模型参考图生成首批 GLB。结果页 `3D素材` Tab 仍可对单个素材触发重新生成。
+抓大鹅入口页不展示参考图片上传。题材表现由题材文本和草稿切割图片链路承接；草稿生成阶段会生成多视角 2D 物品素材并写入作品 profile。结果页 `素材配置 > 物品` 继续承接物品素材预览、删除、批量新增和音效配置。
+
+## 6.4 生成音效开关
+
+抓大鹅入口页在生成按钮前提供 `生成音效` Toggle，默认关闭。关闭时，草稿生成只保存 `generatedItemAssets[].soundPrompt`，不调用 Vidu 生成点击音效。
+
+用户打开 Toggle 后，前端在创建会话和执行 `match3d_compile_draft` 时提交 `generateClickSound=true`。后端完成物品名称与 `soundPrompt` 生成后，在图片素材生成阶段为每个生成物品调用 Vidu 生成点击音效，并把结果写入对应 `generatedItemAssets[].clickSound`。音效生成复用通用创作音频接口和资产落点；结果页仍保留单个物品音效的手动补生成入口。

 ---

@@ -222,9 +228,9 @@ Match3D 首版参考拼图后期的入口表单收集方式，而不是早期的

 ## 7.3 素材生成边界

-抓大鹅草稿生成链路会生成首批 `3` 个题材物品素材：文本模型生成物品名，VectorEngine 生成 `2*2` 素材图并切割独立图片，再以每张独立图片调用 Rodin 图生 3D，下载 `.glb` 并转存 OSS。入口页选择的 `assetStylePrompt` 必须写入素材图提示词；结果页手动 Rodin 图生模型时，继续以该物品图片和默认提示词作为起点。
+抓大鹅草稿生成链路会根据难度生成题材物品素材：文本模型生成物品名，VectorEngine 分批生成 `1:1` 素材图并切割为每个物品 `5` 张不同视角图片，再转存 OSS。入口页选择的 `assetStylePrompt` 必须写入素材图提示词；结果页批量新增物品时继续以该风格作为默认提示词起点。

-生成出的独立图片与 GLB 模型都必须作为草稿页 `3D素材` Tab 的预览资产返回。模型生成成功时 `generatedItemAssets[].status = model_ready`，并携带 `modelSrc`、`modelObjectKey`、`modelFileName`、`taskUuid` 和 `subscriptionKey`；正式平台资产绑定和更完整的二次编辑流程以后续技术方案为准。
+生成出的独立图片必须作为结果页 `素材配置 > 物品` 的预览资产返回。图片素材生成成功时 `generatedItemAssets[].status = image_ready`，并携带 `imageViews[]`，兼容字段 `imageSrc` / `imageObjectKey` 指向首张视角图；正式平台资产绑定和更完整的二次编辑流程以后续技术方案为准。

 ## 7.4 发布前试玩

@@ -277,13 +283,16 @@ totalItemCount = clearCount * 3

 每种物品数量必须是 `3` 的倍数，避免生成无法通关的局。

-生成的消除物类型数由用户填写的需要消除次数决定：
+生成的消除物类型数由难度档位决定：

 ```text
-itemTypeCount = clearCount <= 25 ? clearCount : 25
+轻松 = 3
+标准 = 9
+进阶 = 15
+硬核 = 21
 ```

-当 `clearCount <= 25` 时，本局生成的 `itemTypeId` 数量等于 `clearCount`，每种类型默认生成 `3` 件；当 `clearCount > 25` 时，本局最多生成 `25` 种 `itemTypeId`，后续消除组按这 `25` 种类型轮转补齐，且每种类型最终数量仍必须保持 `3` 的倍数。
+当前四档难度分别生成 `3 / 9 / 15 / 21` 种 `itemTypeId`。历史草稿若仍保留 `clearCount = 20` 的硬核配置，运行时和素材生成都必须兼容映射为 `21` 种物品，不得回退成 `20` 种。

 同一局内这些类型必须分别使用不同的形状和颜色组合，不能出现两个组看起来像同一种物体的情况。

@@ -297,13 +306,13 @@ itemTypeCount = clearCount <= 25 ? clearCount : 25

 ## 8.5 物品资产

-当前 demo 使用生成 GLB 优先、默认积木兜底的物品资产策略。
+当前 demo 使用生成 2D 图片优先、默认积木兜底的物品资产策略。

-1. demo 至少提供 `25` 种彼此不同的颜色与几何造型组合默认素材，支撑 `clearCount > 25` 时的类型上限和 GLB 缺失兜底。
-2. 有 `generatedItemAssets[].modelSrc` 或 `modelObjectKey` 时，运行态与备选栏必须优先读取该 GLB；默认积木件只作为加载失败、模型缺失或 2D 回退时的兜底素材池。
-3. 前端读取生成模型必须通过 `/api/assets/read-bytes` 获取私有 OSS 字节，再交给 Three.js `GLTFLoader` 解析；不得直接把 `/generated-match3d-assets/...` 当裸 URL 请求。
-4. 当前固定 `clearCount = 3` 的生成草稿中，运行态 `match3d-type-01/02/03` 按类型编号顺序映射到生成出的 `3` 个模型；后续恢复更大生成数量时，模型列表顺序必须继续与类型编号稳定对应。
-5. 默认积木视觉键仍需映射为无文字的纯色 2D 图标和程序化 3D 积木模型，不能显示为透明气泡或文字标记。
+1. demo 至少提供 `25` 种彼此不同的颜色与几何造型组合默认素材，支撑 `clearCount > 25` 时的类型上限和图片缺失兜底。
+2. 有 `generatedItemAssets[].imageViews`、`imageSrc` 或 `imageObjectKey` 时，运行态与备选栏必须优先读取该 2D 图片素材；默认积木件只作为加载失败或图片缺失时的兜底素材池。
+3. 前端读取 generated legacy 图片必须通过 `/api/assets/read-url` 换签后加载；不得直接把 `/generated-match3d-assets/...` 当裸 URL 请求。
+4. 运行态 `match3d-type-01/02/03` 等类型按类型编号顺序映射到生成出的图片素材列表；后续更大生成数量时，素材列表顺序必须继续与类型编号稳定对应。
+5. 默认积木视觉键仍需映射为无文字的纯色 2D 图标，不能显示为透明气泡或文字标记。
 6. 用户题材主题后续会映射为符合常识预期的物品集合。

 示例：水果题材可以对应红色苹果、黄色香蕉、紫色葡萄等。
@@ -334,7 +343,7 @@ itemTypeCount = clearCount <= 25 ? clearCount : 25

 飞行动画过程中，物品不再与其他物品产生碰撞。

-当前 3D 实验模式下，物品进入备选栏后必须从圆形空间的物理世界移除；备选栏只展示该物品同款 3D 模型的独立预览，固定为斜 `45` 度便于识别，不再参与场内碰撞、重力或堆叠。
+物品进入备选栏后必须从圆形空间的可点击列表移除；备选栏展示该物品同款 2D 素材图，不再参与场内点击、遮挡或堆叠。

 前端播放即时反馈的同时，必须向后端提交点击意图。后端确认后固化入槽结果；后端拒绝时，前端恢复物品位置和备选栏表现。

@@ -344,7 +353,7 @@ itemTypeCount = clearCount <= 25 ? clearCount : 25

 1. 每次点击进入即时反馈流程后，前端先把物品表现为进入备选栏。
 2. 备选栏中每出现 `3` 个相同物品 id，前端立即播放自动消除效果并腾出格子。
-3. 3D 模式下，备选栏格子展示从场内取出的同款 3D 模型预览，视角固定斜 `45` 度，不使用另一套不一致的 UI 图标；托盘预览必须共享一个 WebGL renderer，并按 `7` 格容器实际宽高把模型居中摆放到对应格子，不能因多个预览上下文导致中心场地模型不可见；WebGL 回退或 `2D` 模式下才使用保留的 2D 图标。
+3. 备选栏格子展示从场内取出的同款 2D 素材图，不使用另一套不一致的 UI 图标；图片缺失或读取失败时才使用保留的默认图标。
 4. 后端确认后固化真实备选栏和消除结果；若后端返回状态不一致，前端必须以最新后端快照校正。
 5. 如果备选栏满且无法消除，前端可以立即展示失败过渡，最终失败状态以后端确认为准。

@@ -671,11 +680,12 @@ GET /api/runtime/match3d/runs/:runId

 ## 14.2 入口表单

-入口表单只展示三个输入块：
+入口表单只展示四个输入块：

 1. `想做一个什么题材的抓大鹅？` 大文本输入框。
-2. `3D素材风格` 横向滑动风格卡，最后一个为 `自定义`。
+2. `2D素材风格` 横向滑动风格卡，最后一个为 `自定义`。
 3. `难度` 选项按钮。
+4. `生成音效` Toggle，默认关闭。

 入口页不展示参考图、`需要消除次数` 数值输入、`难度数值` 滑杆，也不展示 `题材 / 物品 / 难度` 三个摘要框。`需要消除次数` 和 `difficulty` 由难度选项派生后提交给后端。

@@ -704,24 +714,25 @@ GET /api/runtime/match3d/runs/:runId
 首版 PRD 对应 demo 验收标准：

 1. 用户可从平台创作入口进入“抓大鹅”模板。
-2. 入口表单能确认题材主题、3D 素材风格和难度选项，并提交派生后的消除次数与难度数值。
+2. 入口表单能确认题材主题、2D 素材风格和难度选项，并提交派生后的消除次数与难度数值。
 3. 入口页不展示参考图上传。
 4. 内置风格显示画风参考图，自定义风格通过独立面板填写并进入提交 payload。
 5. 移动端入口页所有内容一屏展示，不产生纵向滚动。
-6. 系统可生成待发布结果页，并在草稿中返回首批切割图片与 OSS GLB 模型素材预览。
-7. 用户可编辑游戏名称、标签、封面图等基础信息。
-8. 用户可发布前试玩，且试玩失败不阻断发布。
-9. 运行态能展示圆形空间、倒计时、物品和 `7` 格备选栏；存在 `generatedItemAssets` 模型时必须优先展示生成 GLB，而不是默认积木素材。
-10. 物品可重叠、遮挡、堆叠。
-11. 被完全遮挡物品不可点击，露出可点击区域的物品可点击。
-12. 点击通过后物品飞入备选栏。
-13. 备选栏中 `3` 个相同物品 id 自动消除。
-14. 清空空间中全部物品后胜利。
-15. 倒计时结束或备选栏满后失败。
-16. 胜利结算展示使用时间。
-17. 失败结算展示完成进度和重新开始按钮。
-18. 局内即时反馈由前端先行呈现，关键状态以后端确认快照校正。
-19. 相关中文文档通过编码检查。
+6. `生成音效` 关闭时草稿生成不产生 `clickSound`；打开时首批生成物品随图片素材生成并持久化点击音效。
+7. 系统可生成待发布结果页，并在草稿中返回首批多视角 2D 切割图片素材预览。
+8. 用户可编辑游戏名称、标签、封面图等基础信息。
+9. 用户可发布前试玩，且试玩失败不阻断发布。
+10. 运行态能展示圆形空间、倒计时、物品和 `7` 格备选栏；存在 `generatedItemAssets` 图片素材时必须优先展示生成 2D 素材，而不是默认积木素材。
+11. 物品可重叠、遮挡、堆叠。
+12. 被完全遮挡物品不可点击，露出可点击区域的物品可点击。
+13. 点击通过后物品飞入备选栏。
+14. 备选栏中 `3` 个相同物品 id 自动消除。
+15. 清空空间中全部物品后胜利。
+16. 倒计时结束或备选栏满后失败。
+17. 胜利结算展示使用时间。
+18. 失败结算展示完成进度和重新开始按钮。
+19. 局内即时反馈由前端先行呈现，关键状态以后端确认快照校正。
+20. 相关中文文档通过编码检查。

 ---

--- a/docs/prd/PROFILE_LEGAL_INFO_AND_AUTH_AGREEMENT_PRD_2026-05-12.md
+++ b/docs/prd/PROFILE_LEGAL_INFO_AND_AUTH_AGREEMENT_PRD_2026-05-12.md
@@ -0,0 +1,90 @@
+# “我的”页签法律信息与登录协议确认 PRD
+
+## 1. 目标
+
+在平台“我的”页签底部补齐法律信息入口和备案信息；同时在登录弹窗中增加协议确认，用户首次登录必须手动勾选同意后才能继续登录。
+
+## 2. 入口与布局
+
+### 2.1 “我的”页签常用功能
+
+- 已登录用户在“我的”页签看到常用功能区。
+- 常用功能区移动端和网页端都使用 3 列网格。
+- 每个功能入口保持图标、主标题、短副标题结构。
+- 不新增独立“我的”页面，只扩展现有个人页签。
+
+### 2.2 法律信息区
+
+法律信息区放在“我的”页签底部、设置入口之后。
+
+区块内容：
+
+- 区块标题：`法律信息`。
+- 三个列表入口：
+  - `用户协议`
+  - `隐私政策`
+  - `免责声明`
+- 每个入口点击后打开独立模态面板，不在当前页签下方展开内容。
+- 备案信息固定显示在法律入口下方：
+  - 文案：`京ICP备2026025677号`
+  - 点击跳转到 `https://beian.miit.gov.cn/`
+  - 外链在新窗口打开，并使用 `rel="noreferrer"`。
+
+## 3. 法律内容面板
+
+### 3.1 内容来源
+
+三份法律内容读取仓库现有 Markdown 文件：
+
+- `media/files/user_agreement.md`
+- `media/files/privacy_policy.md`
+- `media/files/disclaimer.md`
+
+### 3.2 展示规则
+
+- 使用平台主题变量渲染，暗色和亮色主题都必须可读。
+- 面板最大高度不超过视口，正文区域内部滚动。
+- 标题固定在面板顶部，底部保留确认按钮 `我知道了`。
+- Markdown 首版只需要支持标题、段落、列表和加粗文本。
+- 不把 Markdown 原文作为纯文本整段堆叠，必须保留基本阅读层级。
+
+## 4. 登录协议确认
+
+### 4.1 展示位置
+
+登录弹窗的短信登录和密码登录表单都在提交按钮上方展示协议确认行：
+
+`我已阅读并同意《用户协议》《隐私政策》和《免责声明》`
+
+其中三段蓝色链接分别打开对应法律内容面板。
+
+### 4.2 勾选规则
+
+- 使用本地存储 key `genarrative.auth.legal-consent.v1` 记录是否已经确认。
+- 首次打开登录弹窗时，如果没有本地确认记录，勾选框默认为未选中。
+- 后续打开登录弹窗时，如果本地已有确认记录，勾选框默认为选中。
+- 用户未勾选时：
+  - 登录按钮禁用。
+  - 点击法律链接只打开内容面板，不自动勾选。
+- 用户勾选后：
+  - 立即写入本地确认记录。
+  - 短信登录和密码登录都可继续使用。
+
+## 5. 验收
+
+- 已登录“我的”页签常用功能区为 3 列。
+- “我的”页签底部出现 `法律信息`、三个入口和 `京ICP备2026025677号`。
+- 三个法律入口都能打开独立可滚动面板。
+- 备案号点击打开 `https://beian.miit.gov.cn/`。
+- 首次登录弹窗协议勾选为空，登录按钮禁用。
+- 勾选协议后登录按钮恢复可用，并持久化本地确认状态。
+- 再次打开登录弹窗时协议勾选默认选中。
+
+## 6. 2026-05-12 落地记录
+
+- 法律文档解析与弹窗复用 `src/components/common/legalDocuments.ts` 和 `src/components/common/LegalDocumentModal.tsx`。
+- “我的”页签在 `src/components/rpg-entry/RpgEntryHomeView.tsx` 中接入 3 列常用功能、法律入口和备案链接。
+- 登录协议确认在 `src/components/auth/LoginScreen.tsx` 中接入，短信登录和密码登录共用同一确认行。
+- 定向验证：
+  - `npm run test -- src/components/auth/AuthGate.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`
+  - `npx eslint src/components/auth/LoginScreen.tsx src/components/auth/AuthGate.test.tsx src/components/common/LegalDocumentModal.tsx src/components/common/legalDocuments.ts src/components/rpg-entry/RpgEntryHomeView.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx --max-warnings 0`
--- a/docs/prd/README.md
+++ b/docs/prd/README.md
@@ -12,6 +12,7 @@
 - [AI 原生拼图玩法创作工具与玩法系统 PRD](./AI_NATIVE_PUZZLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-22.md)：拼图玩法创作、结果页、发布、广场和运行时主链路。
 - [AI 原生方洞挑战玩法创作工具与玩法系统 PRD](./AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)：方洞挑战创作、发布与试玩闭环。
 - [后台管理独立前端工程 PRD](./ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)：后台管理端产品边界。
+- [“我的”页签法律信息与登录协议确认 PRD](./PROFILE_LEGAL_INFO_AND_AUTH_AGREEMENT_PRD_2026-05-12.md)：定义个人页法律入口、备案链接、法律内容弹窗和首次登录协议勾选规则。

 ## 使用规则