games-development-ai/docs-design/Deployment for AI.md

tl;dr

绘境AI生态平台MVP要验证从“自然语言创意”到“可试玩Web轻量小游戏”，再到“发布、审核、游戏流分发、玩家互动与数据反馈”的最小生态闭环。产品面向无代码游戏创作者、轻量游戏玩家和平台运营人员，核心能力包括AI模板化生成、浏览器即时试玩、发布审核、移动端游戏流、互动反馈和创作者基础数据看板。

Goals

Business Goals

• MVP上线8周内完成创作、发布、审核、分发、试玩、互动和基础数据反馈的端到端闭环验证。
  • Metric：核心链路E2E验收通过率达到100%，P0流程无阻断缺陷。
• 获取首批高质量创作者供给。
  • Metric：注册创作者达到500人，其中至少100人发布至少1款游戏。
• 建立可持续内容供给池。
  • Metric：MVP阶段累计上线300款可试玩AI小游戏，其中至少30款达到平台推荐标准。
• 验证游戏流消费模式。
  • Metric：玩家单次会话平均试玩游戏数不低于3款，玩家7日留存率不低于15%。
• 为后续商业化和创作者激励预留数据与技术基础。
  • Metric：完成广告、内购、打赏或创作者分成中至少1类商业化机制的数据埋点和字段预留。

User Goals

• 创作者可以用一句自然语言描述快速生成可试玩小游戏，无需编程、美术或游戏引擎知识。
• 创作者可以通过模板、风格标签、素材上传和基础参数调整，提高生成结果的稳定性和可控性。
• 玩家可以像刷短视频一样连续发现、试玩、跳过、点赞、收藏和分享轻量小游戏，无需下载安装。
• 运营人员可以审核、推荐、下架和限制曝光游戏，保障内容安全和游戏流质量。
• 产品与技术团队可以通过统一埋点和数据看板判断生成质量、内容质量、推荐效果和系统稳定性。

Non-Goals

• MVP不实现完整商业化闭环，不建设复杂广告竞价、付费道具商城、创作者结算和跨渠道收入分账。
• MVP不支持大型多人在线游戏、复杂3D开放世界、重度实时竞技或高并发同步玩法。
• MVP不提供专业级游戏编辑器，不支持复杂脚本系统、完整关卡编辑器、插件市场或多人协作编辑。
• MVP不追求开放式任意代码生成，优先采用“LLM理解Prompt + 受控模板配置生成 + 统一Web Runtime运行”的稳定方案。

User Stories

Persona 1：无代码游戏创作者

• As a 无代码游戏创作者, I want to 用一句话描述游戏想法, so that 我可以快速把创意变成可试玩小游戏。
• As a 无代码游戏创作者, I want to 选择玩法模板和美术风格, so that AI生成结果更稳定、更符合我的预期。
• As a 无代码游戏创作者, I want to 上传少量角色或背景参考图, so that 游戏视觉表达更贴近我的创意。
• As a 无代码游戏创作者, I want to 在浏览器中立即预览和试玩生成结果, so that 我能在发布前确认游戏可玩。
• As a 无代码游戏创作者, I want to 查看游戏发布后的曝光、试玩、完玩和互动数据, so that 我可以判断玩家是否喜欢并继续迭代。

Persona 2：进阶UGC创作者

• As a 进阶UGC创作者, I want to 快速批量生成多个轻量游戏原型, so that 我可以测试不同题材和玩法的市场反馈。
• As a 进阶UGC创作者, I want to 调整模板参数，例如速度、敌人数量、关卡时长和胜负条件, so that 我可以优化游戏节奏。
• As a 进阶UGC创作者, I want to 复制分享链接并带渠道参数, so that 我可以在社群或外部渠道测试传播效果。
• As a 进阶UGC创作者, I want to 更新已发布游戏版本, so that 我可以根据数据反馈优化线上作品。

Persona 3：轻量游戏玩家

• As a 轻量游戏玩家, I want to 打开首页后直接进入游戏流, so that 我可以低成本发现新游戏。
• As a 轻量游戏玩家, I want to 无需下载即可立即试玩, so that 我不会因为安装成本放弃体验。
• As a 轻量游戏玩家, I want to 上滑或点击跳过不感兴趣的游戏, so that 我可以快速找到喜欢的内容。
• As a 轻量游戏玩家, I want to 点赞、收藏和分享喜欢的游戏, so that 我能表达偏好并推荐给朋友。
• As a 轻量游戏玩家, I want to 举报违规、低质或无法正常运行的游戏, so that 平台内容更安全可信。

Persona 4：平台运营人员

• As a 平台运营人员, I want to 查看待审核游戏列表和风险等级, so that 我可以优先处理高风险内容。
• As a 平台运营人员, I want to 在审核页试玩游戏并查看Prompt、素材和安全检测结果, so that 我可以做出准确审核决策。
• As a 平台运营人员, I want to 将优质游戏加入精选池, so that 冷启动阶段游戏流质量可控。
• As a 平台运营人员, I want to 下架、拒绝或限制曝光问题游戏, so that 我可以保护平台体验和合规安全。

Persona 5：系统管理员与工程团队

• As a 系统管理员, I want to 管理用户角色和后台权限, so that 不同用户只能访问授权功能。
• As a 工程团队成员, I want to 监控生成任务、队列积压、API延迟和Game Runtime错误, so that 我可以快速定位系统问题。
• As a 数据分析人员, I want to 导出或查询核心埋点数据, so that 团队可以复盘MVP表现并制定下一阶段优先级。

Functional Requirements

• AI游戏创作工作台 (Priority: P0)

  • Prompt生成游戏：创作者输入10至1,000字符的游戏描述，系统创建异步生成任务，基于受控模板生成GameConfig和GameManifest，并在成功后创建可预览草稿游戏。
  • 模板化创作入口：MVP提供3至5个稳定玩法模板，建议首批包含躲避、跑酷、射击、解谜、点击收集。每个模板必须有JSON Schema、默认参数、示例Prompt和运行时适配。
  • 风格标签：支持选择像素风、卡通风、赛博朋克、童话风、国风、太空、奇幻等风格标签，用于影响素材选择、UI文案和主题参数。
  • 素材上传：支持上传图片素材作为角色、背景或参考图。文件必须校验MIME、扩展名、大小、尺寸和安全检测结果。MVP建议单文件不超过5MB，单次最多5个素材。
  • 生成状态展示：前端展示queued、running、succeeded、failed、timed_out、canceled等状态，并展示当前步骤，例如“理解玩法”“生成配置”“处理资源”“准备预览”。
  • 失败重试：生成失败时展示错误分类和可操作建议。用户可一键重试或返回修改Prompt。LLM超时、内容安全拒绝、模板置信度低、Manifest校验失败应有不同提示。
  • 预览与轻量编辑：生成成功后展示游戏预览容器和编辑面板。允许修改标题、简介、封面、标签、操作说明和模板基础参数。
  • 草稿保存：未发布游戏以draft状态保存，创作者可从“我的游戏”继续编辑。

• 游戏运行容器与Runtime (Priority: P0)

  • Web即时试玩：所有MVP游戏必须可在浏览器内运行，无需下载、安装或跳转外部应用。
  • 统一Manifest加载：Game Runtime根据GameManifest加载runtimeVersion、configUrl、assetList、hash、preloadPolicy和bundleSizeBytes。
  • Phaser 3运行时：MVP使用Phaser 3实现轻量2D游戏模板，支持移动端触控和桌面键盘控制。
  • iframe sandbox：游戏在受控iframe中运行，禁止访问父页面DOM、Cookie、localStorage和非白名单网络请求。
  • Game SDK事件：Runtime必须通过SDK上报load_start、load_success、load_failed、play_start、play_30s、complete、runtime_error等标准事件。
  • 资源限制：单个游戏总资源不超过10MB，首屏关键资源不超过2MB。超过限制时生成失败并提示用户简化内容。

• 游戏发布与管理 (Priority: P0)

  • 发布前检查：发布前必须检查游戏可加载、标题存在、简介存在、封面存在、标签存在、适龄提示存在、内容安全通过。
  • 状态流转：Game状态必须支持draft、pending_review、published、rejected、unpublished、deleted。非法状态转换应被服务端拒绝。
  • 审核提交：发布后创建ReviewRecord，并根据内容安全结果进入自动通过、人工审核或自动拒绝流程。
  • 基础版本管理：MVP支持覆盖式更新当前线上版本，同时保留GameVersion记录和版本号。暂不支持对玩家的A/B版本分流。
  • 分享链接：已发布游戏生成独立分享链接，包含Open Graph元数据、封面、标题、简介和立即游玩入口。
  • 创作者列表：创作者可查看我的游戏列表，包括封面、标题、状态、曝光、试玩、互动、最后更新时间和操作入口。

• 游戏流与玩家体验 (Priority: P0)

  • 首页游戏流：玩家进入首页后默认展示移动优先的连续游戏流。桌面端可使用居中游戏容器加侧边信息栏。
  • 上下滑切换：移动端支持纵向滑动切换游戏；桌面端支持滚轮、键盘方向键或点击下一款。
  • 预加载策略：当前游戏加载完成后预加载下一款游戏的Manifest和关键资源，降低切换等待。
  • 即点即玩：第一屏展示封面、标题、作者、玩法说明和开始按钮。玩家点击开始后加载游戏并进入试玩。
  • 自动跳过失败游戏：游戏加载失败时展示简短错误提示，记录game_load_failed事件，并允许玩家跳过到下一款。
  • 互动反馈：支持点赞、收藏、分享和举报。未登录用户可试玩，点赞和收藏触发登录引导；举报可要求登录或做匿名限频，具体由风控策略控制。
  • 基础推荐：MVP采用规则排序，结合精选池、新发布、质量分、互动率、举报率、运行错误率和新作保底曝光。

• 创作者数据看板 (Priority: P1)

  • 单游戏数据概览：展示曝光、加载成功、试玩开始、30秒游玩、完成、平均游玩时长、点赞、收藏、分享、举报、加载失败率。
  • 近7天趋势：按日展示核心指标趋势，帮助创作者判断修改效果。
  • 漏斗视图：展示曝光到加载、加载到试玩、试玩到30秒、试玩到完成、试玩到互动的转化。
  • 简单建议：基于规则给出提示，例如“加载失败率偏高，请减少资源体积”“曝光高但试玩低，建议优化封面和标题”。
  • 渠道参数：P1支持分享链接utm或channel参数，并在看板中展示粗略来源表现。

• 内容审核与运营后台 (Priority: P0)

  • 审核队列：运营可按状态、风险等级、发布时间、标签、创作者筛选待审核游戏。
  • 审核详情：展示试玩预览、Prompt、GameConfig摘要、标题、简介、封面、素材列表、安全检测结果和历史审核记录。
  • 审核操作：支持通过、拒绝、下架、备注、加入精选池、限制曝光。所有操作必须写入AuditLog。
  • 内容安全检测：Prompt、标题、简介、封面、上传素材和举报内容均需检测。输出pass、review、reject和原因。
  • 举报处理：举报达到阈值后自动降低曝光并进入运营复核队列。

• 账号与权限 (Priority: P0)

  • 登录注册：至少支持邮箱登录或手机号登录中的一种。后续可扩展第三方登录。
  • 匿名访问：玩家可匿名浏览和试玩，系统分配anonymous_id用于会话和基础推荐信号。
  • RBAC：支持player、creator、operator、admin四类角色。创作、发布、审核、精选、下架和后台访问必须进行权限校验。
  • 资源归属：创作者只能编辑自己的游戏和素材。运营与管理员可以审核和管理公开内容，但操作必须审计。

• 数据埋点与分析 (Priority: P0)

  • 批量事件上报：前端和Game Runtime通过统一/events/batch接口上报事件，支持每10条或每5秒批量发送，并使用sendBeacon兜底。
  • 事件聚合：Event Worker增量聚合GameDailyStats和quality_score。
  • 数据导出：MVP至少支持团队内部查询或导出关键运营数据，用于阶段复盘。

• 外部分发验证 (Priority: P1)

  • 分享页适配：分享页适配移动端社交平台内置浏览器，提供Open Graph和社交卡片元数据。
  • 渠道参数：分享链接支持utm_source、utm_medium、utm_campaign和channel参数。
  • 多渠道发布预留：数据库预留渠道元数据、外部审核状态和游戏包导出字段，但MVP不实现复杂自动分发。

User Experience

Entry Point & First-Time Experience

创作者首次访问平台时，从首页主CTA“开始创作”进入创作工作台。首屏突出“一句话生成游戏”，并提供模板入口、风格标签和3个可点击示例Prompt。首次使用引导需要明确说明MVP适合轻量2D小游戏，不适合复杂3D、多人在线或大型开放世界。

玩家首次访问平台时默认进入游戏流，无需登录即可浏览和试玩。用户点击点赞、收藏、发布创作或部分举报动作时触发登录弹窗，登录后返回原上下文。运营人员通过独立后台入口登录，进入审核队列和推荐管理页面。

空状态处理：

• 创作者无草稿时展示“用一句话生成你的第一款游戏”引导卡片。
• 生成任务列表为空时展示模板示例和最近热门Prompt。
• 游戏流暂无内容时展示运营精选占位、刷新按钮和“稍后再来”提示。
• 审核队列为空时展示“当前无待审核内容”和历史处理入口。

Core Experience

• Step 1：创作者进入创作工作台

  • UI elements：顶部导航、Prompt大文本框、模板卡片、风格标签多选、素材上传入口、示例Prompt按钮、开始生成按钮。
  • Validation：Prompt不能为空；长度限制10至1,000字符；上传文件必须符合格式与大小限制；命中安全风险时禁用提交并提示修改。
  • Navigation：点击开始生成后创建任务并跳转生成状态页。

• Step 2：AI生成任务运行

  • UI elements：步骤进度条、当前步骤文案、预计等待时间、后台继续按钮、取消任务按钮、错误重试入口。
  • Behavior：前端每2秒轮询任务状态。超过120秒提示“生成仍在进行，你可以离开页面，完成后从我的游戏查看”。超过系统超时阈值后任务进入timed_out。
  • Failure states：内容不合规、描述不清晰、模板匹配置信度低、LLM超时、资源处理失败、Manifest校验失败、系统繁忙。

• Step 3：预览与轻量编辑

  • UI layout：桌面端左侧为游戏预览iframe，右侧为编辑面板；移动端优先展示预览，下方抽屉编辑基础信息。
  • Editable fields：标题、简介、封面、标签、操作说明、适龄提示、部分模板参数。
  • Actions：试玩、保存草稿、重新生成、提交发布、返回任务历史。
  • Validation：标题最多80字符，简介最多500字符，标签最多10个，封面必须通过安全检测。

• Step 4：发布与审核

  • UI elements：发布前检查清单、检查状态图标、问题修复入口、提交审核按钮。
  • Behavior：检查通过后创建ReviewRecord并将游戏置为pending_review；低风险内容可按配置自动通过。
  • Result page：显示审核状态、预计处理时间、分享链接占位、返回我的游戏入口。

• Step 5：运营审核

  • UI layout：左侧审核列表，中间试玩预览，右侧审核信息和操作按钮。
  • Filters：状态、风险等级、发布时间、标签、创作者、举报数。
  • Actions：通过、拒绝、下架、加入精选池、限制曝光、备注。
  • Audit：每次操作写入AuditLog并记录actor、action、target、metadata、ip和user_agent。

• Step 6：玩家进入游戏流

  • UI elements：全屏或近全屏游戏卡片、封面、标题、作者、玩法说明、开始按钮、点赞、收藏、分享、举报、下一款手势提示。
  • Behavior：请求/api/v1/feed获取候选列表；加载当前游戏；预加载下一款Manifest和关键资源；上滑或点击跳过进入下一款。
  • Interaction：点赞和收藏更新本地状态并调用/interactions；分享打开系统分享或复制链接；举报打开原因选择弹窗。

• Step 7：玩家试玩与结果反馈

  • UI elements：游戏canvas、操作提示、暂停按钮、结果页、再玩一次、继续下一个、点赞收藏、分享按钮。
  • Runtime behavior：Game SDK发出标准事件，父页面统一批量上报。游戏结束后展示分数、通关状态或失败原因。
  • Error behavior：加载失败或运行错误时显示简短提示，记录错误并提供跳过按钮。

• Step 8：创作者查看数据并迭代

  • UI elements：我的游戏列表、状态标签、数据卡片、近7天趋势图、漏斗图、优化建议。
  • Actions：编辑并更新、复制分享链接、下架、查看详情、重新生成。
  • Navigation：从数据详情页可直接回到编辑页创建新版本。

Edge Cases

• Prompt过短或过长：提交按钮禁用或返回字段级错误，提示用户补充目标、规则、角色和胜负条件。
• Prompt命中安全风险：不创建生成任务，显示安全提示，不展示敏感命中细节。
• 模板匹配置信度低：返回推荐模板选择页，要求用户选择玩法模板或补充描述。
• LLM服务超时：任务标记timed_out，用户可重试；系统记录provider、error_code和duration_ms。
• Manifest校验失败：任务失败，不生成可发布草稿；提示“生成配置异常，请重试或简化描述”。
• 生成结果与预期不一致：预览页提供“调整描述并重新生成”入口，保留原Prompt和任务记录。
• 上传素材不合规：拒绝上传并提示支持格式、大小和安全要求。
• 游戏加载失败：玩家端可跳过；创作者端提示该游戏存在运行异常；后台降低曝光权重。
• 未登录用户互动：点赞、收藏和创作触发登录；试玩和浏览不强制登录。
• 审核拒绝：创作者看到拒绝原因、修改建议和重新提交入口。
• 游戏被下架：公开分享页展示“该游戏暂不可访问”，作者和运营可查看原因。
• 低端移动设备：启用低画质模式，限制粒子效果和音频预加载，目标30fps。
• 网络弱或离线：显示重试按钮；埋点使用本地短暂队列和sendBeacon兜底，但不保证离线长期缓存。
• 同一会话重复曝光：Feed在一个会话内尽量避免重复返回同一gameId，除非候选耗尽。

Narrative

小林是一名喜欢游戏和短视频的大学生，经常有很多游戏点子，但不会写代码，也没有稳定的美术资源。过去，他只能把想法发到社交平台，真正做成可玩的游戏需要找程序、美术和引擎工具，成本远超他的能力范围。

在绘境AI中，小林打开创作工作台，输入“做一个像素风太空躲避游戏，玩家控制飞船躲避陨石，收集能量块，坚持60秒获胜”。系统识别这是躲避类玩法，选择avoidance模板，生成结构化GameConfig并打包成可试玩Web小游戏。几分钟后，小林在浏览器中试玩，发现陨石速度偏慢，于是调整速度和生成频率，保存草稿并提交发布。

运营后台自动检测Prompt、封面和素材，低风险通过审核后游戏进入首页游戏流。玩家打开平台后像刷短视频一样连续试玩小游戏，有人给小林的作品点赞、收藏并分享到社群。第二天，小林在创作者数据看板看到游戏完玩率不错，但封面带来的点击较低，平台提示他优化标题和封面。他更新后曝光到试玩的转化提升。对小林而言，创意第一次低成本变成了作品；对玩家而言，他们获得了源源不断的新鲜小游戏；对平台而言，内容供给、消费和反馈形成了早期生态闭环。

Success Metrics

User Metrics

• 创作者激活率：注册创作者中完成首次生成任务的比例不低于40%。
• 首次发布转化率：完成首次生成的创作者中至少发布1款游戏的比例不低于25%。
• 创作者二次生成率：发布后7日内再次发起生成的创作者比例不低于25%。
• 玩家7日留存率：首日试玩过游戏的玩家在第7天仍有访问或试玩行为的比例不低于15%。
• 单次会话试玩游戏数：玩家每次访问平均试玩游戏数不低于3款。
• 游戏互动率：点赞、收藏、分享次数除以试玩次数不低于8%。
• 审核处理满意度：创作者对审核结果解释的满意度达到80%以上，可通过轻量反馈收集。

Business Metrics

• 注册创作者规模：MVP上线8周内达到500名注册创作者。
• 首发创作者规模：MVP上线8周内至少100名创作者发布至少1款游戏。
• 内容供给规模：MVP阶段累计发布300款可试玩游戏。
• 优质内容占比：达到平台推荐标准的游戏占已发布游戏比例不低于10%。
• 外部分发贡献：来自分享链接或外部渠道的访问占比不低于20%。
• 冷启动精选池规模：上线前准备至少50款可用游戏，其中至少20款通过运营精选。

Technical Metrics

• 生成任务成功率：生成任务成功完成并可预览的比例不低于85%。
• 生成任务耗时：P75小于120秒，P95小于240秒。
• 平台核心API可用性：不低于99%。
• 游戏流首屏可交互时间：P75小于3秒，P95小于6秒。
• 游戏运行阻断性错误率：低于3%。
• 游戏流API响应：/api/v1/feed P95小于300ms，P99小于800ms。
• 批量事件上报响应：/api/v1/events/batch P95小于200ms。
• 埋点事件接收成功率：不低于99%。
• 中端移动设备平均帧率：不低于45fps；低端设备低画质模式不低于30fps。

Key Events to Track

• User lifecycle
  • user_signup
  • user_login
  • creator_onboarding_start
  • creator_onboarding_complete
  • anonymous_session_start
• Creation funnel
  • prompt_submit
  • template_select
  • asset_upload_start
  • asset_upload_success
  • asset_upload_failed
  • generation_task_created
  • generation_start
  • generation_success
  • generation_failed
  • generation_timeout
  • game_preview_start
  • draft_save
  • game_config_edit
• Publishing and review
  • game_publish_submit
  • game_publish_check_failed
  • game_publish_success
  • game_review_queue_enter
  • game_review_approve
  • game_review_reject
  • game_unpublish
  • game_feature_add
  • game_feature_remove
• Feed and gameplay
  • feed_view
  • feed_item_impression
  • game_load_start
  • game_load_success
  • game_load_failed
  • game_play_start
  • game_play_30s
  • game_complete
  • game_skip
  • runtime_error
• Interaction and sharing
  • game_like
  • game_unlike
  • game_favorite
  • game_unfavorite
  • game_share
  • share_link_open
  • game_report
• Analytics and creator dashboard
  • creator_dashboard_view
  • game_stats_view
  • optimization_tip_view
  • optimization_tip_click
• Channel and conversion
  • external_channel_visit
  • visitor_to_player_convert
  • player_to_creator_convert

Technical Considerations

• 生成策略必须采用受控生成，而不是开放式任意代码生成。LLM负责Prompt理解、模板分类和参数生成；平台负责JSON Schema校验、Manifest生成、资源约束和Runtime执行。
• GameConfig必须结构化、版本化并通过模板级JSON Schema校验。任何超出模板约束的字段应被过滤或导致生成失败。
• GameManifest必须包含runtimeVersion、configUrl、assetList、hash、preloadPolicy和bundleSizeBytes，Runtime只按Manifest加载资源，不直接信任用户输入。
• 生成任务、审核任务、资源处理和事件聚合必须通过队列异步执行，避免阻塞API请求和前端体验。
• Game、GenerationTask和ReviewRecord必须使用显式状态机，服务端拒绝非法状态流转。
• 玩家端游戏流应移动优先，资源加载必须严格控制大小，避免AI生成内容导致移动端性能不可控。
• 内容安全必须覆盖Prompt、标题、简介、封面、上传素材、用户资料和举报内容。高风险自动拒绝，中风险人工审核，低风险按配置自动通过或进入普通审核。
• 游戏运行必须沙箱隔离。iframe sandbox和Content Security Policy必须限制脚本源、网络访问、存储访问和父页面DOM访问。
• Feed推荐MVP采用规则排序，不引入复杂个性化模型。规则必须可解释、可调参，并能被运营精选池干预。
• 数据分析MVP可使用PostgreSQL事件分区表和聚合表；增长阶段再迁移ClickHouse或外部分析工具。
• 系统必须支持匿名anonymous_id，用于未登录玩家的试玩、曝光和基础行为分析，但匿名用户权限必须受限。
• 日志不得记录敏感Token、API Key、密码、完整敏感Prompt命中结果或未经脱敏的用户隐私信息。

UI Architecture

• Framework：Next.js 14 App Router、React 18、TypeScript。
• Component Library：shadcn/ui作为后台、表单、弹窗、列表、标签、Toast和数据卡片基础组件；游戏流和Runtime容器使用定制组件。
• Styling：Tailwind CSS，使用CSS变量定义主题色、间距、圆角和暗色模式预留。
• State Management：
  • React Query用于服务端状态、API请求缓存、轮询生成任务和Feed分页。
  • Zustand用于轻量客户端状态，例如游戏流当前索引、播放器状态、登录弹窗状态和创作草稿临时状态。
  • React Hook Form + Zod用于表单状态和字段校验。
• Animations：Framer Motion用于游戏流切换、弹窗、Toast和步骤进度动效；Runtime内部动画由Phaser 3处理。
• Routing：
  • /：玩家游戏流首页。
  • /create：创作工作台。
  • /create/tasks/[taskId]：生成任务状态页。
  • /creator/games：创作者我的游戏。
  • /creator/games/[gameId]/edit：预览与编辑页。
  • /creator/games/[gameId]/stats：单游戏数据看板。
  • /games/[gameId]：游戏详情与分享页。
  • /admin/reviews：运营审核队列。
  • /admin/reviews/[reviewId]：审核详情。
• Responsive Design：
  • 玩家游戏流移动优先，重点适配360px至430px宽度。
  • 创作工作台桌面优先，移动端支持基础Prompt提交、任务状态和预览。
  • 运营后台桌面优先，最小建议宽度1024px。
  • 使用CSS Grid和Flex布局，避免固定宽度导致小屏溢出。
• Accessibility：
  • 目标满足WCAG 2.1 AA基础要求。
  • 核心按钮、表单、审核操作和游戏流切换支持键盘访问。
  • 重要图标必须提供aria-label。
  • 错误状态同时使用文本、图标和颜色表达。
  • 表单字段错误与输入控件通过aria-describedby关联。
  • 游戏canvas外层提供文字版操作说明。
• Frontend Error Handling：
  • 使用全局Error Boundary捕获页面级错误。
  • 使用Sentry捕获前端异常和Game Runtime异常。
  • API错误统一映射为用户可理解文案，并保留request_id用于客服和工程排查。
• Game Runtime Frontend Pattern：
  • 父页面负责鉴权、Feed、互动、埋点批量上报和错误显示。
  • iframe内游戏只负责加载配置、运行游戏和通过SDK向父页面postMessage发送事件。
  • 父页面必须校验postMessage来源和事件schema。

API & Backend

• Framework：NestJS + TypeScript，采用Modular Monolith架构，后续可按模块拆分服务。

• API Style：REST over HTTPS，统一路径前缀/api/v1。

• Database：PostgreSQL 15，Prisma ORM，JSONB存储GameConfig、Manifest元数据和事件properties。

• Cache and Queue：Redis 7 + BullMQ，用于生成任务、审核任务、资源处理、事件聚合、通知和短期缓存。

• Object Storage：阿里云OSS或AWS S3，配合CDN分发封面、Manifest和游戏资源。

• Authentication：JWT Access Token + Refresh Token。Access Token有效期15分钟，Refresh Token有效期7至30天，Refresh Token服务端存hash。

• Authorization：RBAC + resource ownership checks。角色包含player、creator、operator、admin。

• Hosting：

  • Frontend：Vercel、Netlify或对象存储加CDN。
  • Backend：Railway、Fly.io、AWS ECS、阿里云ECS/Kubernetes或Cloud Run。
  • Database and Redis：托管云服务优先。

• Backend Modules：

  • AuthModule：登录、刷新令牌、匿名ID、权限Guard。
  • UserModule：用户资料、角色、创作者主页。
  • AssetModule：上传签名、素材元数据、图片处理、hash和安全检测。
  • GenerationModule：生成任务创建、状态查询、Prompt记录、LLM调用适配。
  • GameModule：游戏草稿、版本、详情、编辑、发布、下架。
  • ReviewModule：审核队列、审核决策、风险记录。
  • FeedModule：候选池、规则排序、cursor分页、预加载信息。
  • InteractionModule：点赞、收藏、分享、举报和幂等处理。
  • AnalyticsModule：事件接收、事件校验、聚合统计、数据看板。
  • AdminModule：运营后台、精选池、审计日志。

• Key API endpoints：

Method	Endpoint	Purpose	Auth
POST	/api/v1/auth/login	登录并返回访问令牌	Public
POST	/api/v1/auth/refresh	刷新访问令牌	Refresh Token
GET	/api/v1/me	获取当前用户资料和角色	User
POST	/api/v1/assets/presign	获取上传签名URL	Creator
POST	/api/v1/assets/complete	提交上传完成并触发处理	Creator
POST	/api/v1/generation/tasks	创建AI生成任务	Creator
GET	/api/v1/generation/tasks/{taskId}	查询生成任务状态	Creator
POST	/api/v1/generation/tasks/{taskId}/cancel	取消生成任务	Owner
GET	/api/v1/games/{gameId}	获取游戏详情	Public/Owner
PATCH	/api/v1/games/{gameId}	更新标题、简介、封面、标签和配置	Owner
POST	/api/v1/games/{gameId}/publish	提交发布审核	Owner
POST	/api/v1/games/{gameId}/unpublish	创作者下架自己的游戏	Owner
GET	/api/v1/feed	获取游戏流列表	Public
POST	/api/v1/interactions	点赞、收藏、分享、举报	User/Anonymous limited
POST	/api/v1/events/batch	批量上报埋点事件	Public
GET	/api/v1/creator/games	获取创作者游戏列表	Creator
GET	/api/v1/creator/games/{gameId}/stats	获取单游戏数据看板	Owner
GET	/api/v1/admin/reviews	获取审核队列	Operator
GET	/api/v1/admin/reviews/{reviewId}	获取审核详情	Operator
POST	/api/v1/admin/reviews/{reviewId}/decision	提交审核决策	Operator
POST	/api/v1/admin/featured-games	加入精选池	Operator
DELETE	/api/v1/admin/featured-games/{id}	移出精选池	Operator

• Core Data Models：

  • User：id、email、phone、nickname、avatar_url、role、status、created_at、updated_at。
  • CreatorProfile：user_id、slug、bio、total_games、total_plays。
  • Asset：owner_id、type、source、storage_key、public_url、mime_type、size_bytes、hash_sha256、moderation_status。
  • PromptRecord：user_id、raw_prompt、normalized_prompt、template_hint、style_tags、moderation_status、moderation_reason。
  • GenerationTask：user_id、prompt_record_id、status、progress、current_step、template_id、provider_request_id、error_code、error_message。
  • Game：creator_id、title、description、cover_asset_id、status、visibility、tags、age_rating、current_version_id、published_at。
  • GameVersion：game_id、version_number、generation_task_id、config_json、manifest_asset_id、runtime_version、status。
  • ReviewRecord：game_id、version_id、status、risk_level、reviewer_id、reason_code、comment、decided_at。
  • Interaction：user_id、anonymous_id、game_id、type、status、reason。
  • EventLog：event_name、user_id、anonymous_id、session_id、game_id、properties、occurred_at、received_at。
  • GameDailyStats：game_id、stat_date、impressions、load_success、load_failed、play_starts、play_30s、completes、likes、favorites、shares、reports、avg_play_duration_ms、quality_score。
  • FeaturedGame：game_id、operator_id、priority、start_at、end_at。
  • AuditLog：actor_id、action、target_type、target_id、metadata、ip_address、user_agent。

• State Machine Rules：

  • GenerationTask：queued → running → succeeded | failed | timed_out | canceled。
  • Game：draft → pending_review → published | rejected；published → unpublished；任意非deleted状态可进入deleted但需要权限。
  • ReviewRecord：pending → approved | rejected | escalated。
  • Game.status为published时必须存在current_version_id、cover_asset_id、title、description和至少一个approved ReviewRecord。

Performance & Scalability

• Optimizations：

  • Frontend使用Next.js路由级代码分割，玩家游戏流、创作工作台和运营后台独立加载。
  • 图片使用WebP/AVIF，多尺寸封面，CDN缓存。
  • 游戏流只保留当前、上一款和下一款游戏容器，避免多个canvas同时消耗内存。
  • 预加载下一款Manifest和关键资源，但禁止一次性预加载过多游戏。
  • Feed候选集使用Redis短TTL缓存，建议60秒。
  • 热门游戏详情和Manifest元数据缓存300秒。
  • Event上报批量insert，使用队列异步聚合，避免同步写入统计表。
  • LLM调用设置30秒单次超时、最多2次重试、熔断和供应商故障降级。
  • Worker按队列长度横向扩容，生成、审核、资源处理、事件聚合分队列隔离。

• Accessibility：

  • WCAG 2.1 AA作为目标标准。
  • 文本对比度、键盘导航、焦点样式、表单错误提示和ARIA标签必须覆盖P0页面。
  • 游戏玩法说明必须提供文字版，不能只依赖图像或动画表达。
  • 游戏流交互除手势外需提供按钮或键盘替代操作。

• Scalability：

  • MVP容量假设：日活玩家1,000至5,000，日活创作者100至500，日生成任务300至1,000，日试玩10,000至50,000。
  • MVP部署建议：API Server 2个实例，Generation Worker 1至3个实例，Event Worker 1至2个实例，PostgreSQL单主托管实例，Redis托管实例，CDN分发静态资源。
  • 增长阶段扩展：FeedModule拆分为独立服务；Analytics迁移ClickHouse；PostgreSQL增加只读副本；Generation Worker按模板和供应商拆分；推荐系统引入个性化模型。
  • 数据库分区：EventLog按occurred_at月度分区；高频查询字段建立索引，例如Game(status, published_at)、ReviewRecord(status, created_at)、Interaction(game_id, type)、GameDailyStats(game_id, stat_date)。
  • Cursor分页：Feed使用cursor分页，cursor包含lastScore、lastPublishedAt、lastGameId，避免offset深分页。

• Monitoring：

  • Error Tracking：Sentry捕获前端、Game Runtime和后端异常。
  • APM and Tracing：OpenTelemetry覆盖前端请求、API、Worker、数据库和第三方服务调用。
  • Metrics：Prometheus + Grafana或云监控展示API延迟、错误率、队列积压、生成成功率、审核积压、游戏加载失败率、Runtime错误率、CDN命中率。
  • Logging：Loki或云日志服务存储结构化JSON日志，所有日志包含request_id、module、operation、duration_ms和status。
  • Alert thresholds：
    • API 5xx错误率5分钟内超过2%触发P1告警。
    • /feed P95超过800ms持续10分钟触发P1告警。
    • 生成成功率15分钟内低于70%触发P1告警。
    • generation_queue等待任务超过500或最老任务等待超过10分钟触发P1告警。
    • 游戏加载失败率超过8%持续15分钟触发P1告警。
    • 权限异常或后台接口未授权访问激增触发P0安全告警。

Integration Points

• LLM Provider

  • What it does：Prompt理解、玩法模板分类、参数生成、失败解释和优化建议。
  • SDK/library：优先使用官方Node.js SDK或标准HTTPS JSON API封装ProviderAdapter。
  • Configuration：API key、model name、timeout 30s、max retries 2、temperature建议0.2至0.5、JSON schema response mode、provider circuit breaker。
  • Notes：供应商故障时降级为默认模板建议，不允许LLM直接生成任意可执行代码。

• Content Safety Service

  • What it does：检测Prompt、标题、简介、封面、上传素材、用户资料和举报内容。
  • SDK/library：使用云厂商内容安全SDK或HTTPS API，封装ModerationAdapter。
  • Configuration：文本检测、图片检测、风险标签映射、pass/review/reject阈值、人工审核队列回调。
  • Notes：日志中不得输出完整敏感命中内容；只记录risk_level、reason_code和request_id。

• Object Storage and CDN

  • What it does：存储上传素材、系统素材、封面、Manifest、GameConfig和游戏资源，并通过CDN分发公开资源。
  • SDK/library：AWS SDK for S3或阿里云OSS Node.js SDK。
  • Configuration：private bucket用于原始上传，public bucket或CDN源站用于公开封面和游戏资源；上传使用服务端签名URL；路径包含gameId、versionId和hash。
  • Notes：公开资源只读，资源文件使用sha256 hash用于缓存和完整性校验。

• Authentication Provider

  • What it does：登录、注册、会话管理和角色识别。
  • SDK/library：MVP可自建JWT认证；如需加速可使用Clerk、NextAuth或Supabase Auth。
  • Configuration：Access Token 15分钟，Refresh Token 7至30天，密码hash使用Argon2或bcrypt，登录限频。
  • Notes：游客使用anonymous_id，不具备发布、收藏和后台权限。

• Email or Notification Service

  • What it does：发送生成完成、审核结果、发布状态和安全通知。
  • SDK/library：Resend、SendGrid、阿里云邮件推送或内部通知服务SDK。
  • Configuration：模板ID、发件域名、退订设置、队列异步发送。
  • Notes：MVP可先在站内通知和Toast完成，邮件作为P1。

• Analytics Pipeline

  • What it does：采集创作、发布、试玩、互动、审核和性能事件。
  • SDK/library：MVP使用自建/events/batch接口；后续可接入神策、Mixpanel、PostHog或ClickHouse。
  • Configuration：事件schema、匿名ID、session ID、批量大小10条、5秒flush、sendBeacon兜底。
  • Notes：事件必须区分occurred_at和received_at，避免客户端时间偏差影响分析。

• Error Tracking and Observability

  • What it does：捕获前端、后端、Worker和Game Runtime错误，追踪性能瓶颈。
  • SDK/library：Sentry SDK、OpenTelemetry SDK、Prometheus client、Grafana Agent或云监控Agent。
  • Configuration：environment、release version、sample rate、PII masking、alert routing。
  • Notes：Game Runtime错误需要包含gameId、versionId、runtimeVersion、templateId和device info。

• Social Sharing Platforms

  • What it does：支持微信、QQ、微博、浏览器原生分享和复制链接，展示分享卡片。
  • SDK/library：Web Share API、Open Graph meta tags；如需微信内置浏览器能力可集成微信JS-SDK。
  • Configuration：分享标题、简介、封面、canonical URL、utm/channel参数。
  • Notes：MVP优先保证链接分享和Open Graph预览，不依赖复杂平台授权。

• Payment or Monetization Provider

  • What it does：MVP不实现完整支付，但预留广告、打赏、内购或分成字段和事件。
  • SDK/library：暂不接入；后续可根据市场选择Stripe、微信支付、支付宝或广告平台SDK。
  • Configuration：预留monetization_type、revenue_event、creator_share_status等字段。
  • Notes：不得在MVP范围内建设结算、税务、提现和复杂分账流程。

• Feature Flag Service

  • What it does：控制生成链路、推荐策略、自动审核、外部素材生成等功能开关。
  • SDK/library：MVP可使用数据库配置或环境变量；增长阶段可接入LaunchDarkly、Unleash或GrowthBook。
  • Configuration：generation_v2_enabled、feed_ranking_v2_enabled、auto_review_enabled、external_asset_generation_enabled。
  • Notes：出现P0异常时优先关闭相关Flag，再评估应用回滚。