## 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，再评估应用回滚。