games-development-ai/docs-design/Technical Design Document.md

# Technical Design Document

# 绘境AI生态平台MVP Technical Design Document

## Product Overview

Context for the technical design.

本技术设计文档面向将要实现绘境AI生态平台MVP的工程团队，基于现有PRD目标，将“一句话AI生成轻量小游戏、游戏流即点即玩、创作者发布与基础数据反馈、运营审核与推荐管理”落地为可实施的系统架构、数据模型、接口设计、测试方案和部署方案。

MVP技术策略采用“模板约束生成 + Web运行容器 + 异步任务队列 + 规则推荐”的方案，优先保障端到端闭环稳定性，而不是追求完全开放式代码生成。生成结果以配置化游戏工程为主，通过统一运行时容器在Web端加载运行，便于性能控制、内容审核、埋点采集和后续扩展。

### Purpose

- 解决的问题

  - 非技术创作者无法将游戏创意快速转化为可试玩作品。
  - 玩家发现轻量小游戏成本高，传统游戏分发依赖下载、安装和复杂选择。
  - 平台早期需要验证AI创作供给、游戏流消费和数据反馈是否能形成生态闭环。
- 技术机会

  - 使用大模型理解自然语言Prompt，并映射到受控玩法模板和参数配置。
  - 使用Web小游戏运行容器实现即点即玩，降低分发门槛。
  - 使用事件埋点和内容质量信号，为后续推荐和商业化提供数据基础。
  - 使用内容安全检测与审核后台，降低UGC和AI生成内容的合规风险。
- 典型用户场景

  - 创作者输入“做一个像素风太空躲避游戏，飞船躲避陨石并收集能量，坚持60秒获胜”，系统生成可预览小游戏，并允许编辑标题、封面和发布。
  - 玩家进入首页后像刷短视频一样上下滑动试玩小游戏，支持点赞、收藏、分享和举报。
  - 运营人员进入后台审核新发布游戏，试玩后执行通过、拒绝、下架或加入精选池。
  - 团队通过数据看板查看生成成功率、游戏加载时间、试玩转化、互动率和举报率。

### Target Audience

- 普通创作者 / 非技术用户

  - 需求：无需编程、美术和引擎知识即可生成可玩游戏。
  - 技术支持：Prompt输入、模板选择、异步生成进度、浏览器预览、保存草稿、发布到站内游戏流。
- 进阶UGC创作者 / 游戏达人

  - 需求：快速批量产出轻量小游戏，观察数据并优化标题、封面、规则和标签。
  - 技术支持：模板参数可调、版本覆盖更新、基础数据看板、分享链接和渠道参数。
- 玩家 / 轻量游戏消费者

  - 需求：无需下载，低决策成本连续发现和试玩小游戏。
  - 技术支持：移动优先游戏流、资源预加载、CDN加速、错误自动跳过、互动反馈。
- 平台运营人员

  - 需求：控制内容质量、安全合规和冷启动推荐效果。
  - 技术支持：审核队列、试玩预览、风险标记、精选池、曝光限制和操作日志。
- 系统管理员 / 工程团队

  - 需求：监控生成任务、运行错误、服务健康度、权限边界和安全风险。
  - 技术支持：结构化日志、指标看板、告警、RBAC、审计日志和回滚机制。

### Expected Outcomes

- 短期业务结果

  - MVP上线后8周内支持500名注册创作者。
  - 至少100名创作者完成1款游戏发布。
  - 累计上线300款可试玩小游戏。
  - 玩家单次会话平均试玩不少于3款游戏。
- 技术结果

  - 生成任务成功率不低于85%。
  - 平台核心链路可用性不低于99%。
  - 游戏流首屏可交互时间P75低于3秒，P95低于6秒。
  - 游戏加载或运行阻断性错误率低于3%。
  - 核心事件上报成功率不低于99%。
- 长期影响

  - 为后续可视化编辑器、个性化推荐、广告分成、多渠道自动发布和素材市场建立可扩展架构。
  - 沉淀Prompt、模板参数、互动行为和内容质量数据，用于优化生成质量和推荐策略。

## Architecture

The structural design of the system.

### High-Level Architecture

- 推荐技术栈

  - Frontend：Next.js 14、React、TypeScript、Tailwind CSS、Zustand、React Query。
  - Game Runtime：Phaser 3 + 自研Game SDK桥接层，优先支持2D轻量小游戏。
  - Backend：NestJS、TypeScript、REST API，按模块化单体起步，预留服务拆分边界。
  - Database：PostgreSQL 15，使用Prisma ORM管理Schema和Migration。
  - Cache / Queue：Redis 7，BullMQ用于异步生成、审核、资源打包、事件聚合任务。
  - Object Storage：阿里云OSS或AWS S3，存储封面、上传素材、生成素材和游戏包。
  - CDN：阿里云CDN、CloudFront或Cloudflare，用于游戏资源、封面图和静态前端加速。
  - Search / Analytics MVP：PostgreSQL聚合表 + ClickHouse可选；MVP先用PostgreSQL分区事件表，增长后迁移ClickHouse。
  - Auth：JWT + Refresh Token，匿名游客使用anonymous_id Cookie / localStorage标识。
  - Observability：OpenTelemetry、Prometheus、Grafana、Sentry、Loki或云日志服务。
- 主要组件

  - Web App

    - 创作工作台：Prompt输入、模板选择、生成状态、预览、发布。
    - 玩家游戏流：游戏卡片、预加载、滑动切换、互动、举报。
    - 创作者后台：我的游戏、数据概览、草稿和发布状态。
    - 运营后台：审核、试玩、推荐池、下架、用户权限。
  - API Server

    - 账号与权限模块。
    - 游戏与版本管理模块。
    - 生成任务模块。
    - 发布与审核模块。
    - 游戏流推荐模块。
    - 互动与埋点模块。
    - 文件上传与资源签名模块。
  - Generation Worker

    - 接收Prompt生成任务。
    - 调用LLM解析游戏意图。
    - 选择玩法模板并生成GameConfig。
    - 调用素材生成服务或使用内置素材库。
    - 打包游戏资源并输出可运行Manifest。
  - Moderation Worker

    - 检测Prompt、标题、简介、封面和上传素材。
    - 输出风险等级、命中策略和审核建议。
  - Event Worker

    - 批量消费前端埋点。
    - 写入事件表并更新聚合指标。
  - Recommendation Service

    - MVP为规则策略，可在API Server内实现。
    - 根据精选池、新发布、质量分、用户互动和加载错误率返回游戏列表。
- 通信协议

  - 前端与后端：REST over HTTPS。
  - 生成任务状态：优先Server-Sent Events或轮询；MVP可使用2秒轮询，后续升级WebSocket。
  - Worker任务：BullMQ over Redis。
  - 静态资源：HTTPS + CDN。
  - 第三方AI服务：HTTPS API。
- 设计模式

  - Modular Monolith：MVP阶段降低部署和运维复杂度，同时保持模块边界。
  - Event-driven：生成、审核、发布、互动、埋点和指标聚合使用事件驱动。
  - CQRS Lite：写入操作走业务表，读取高频的游戏流和数据看板使用聚合表或缓存。
  - State Machine：GenerationTask、Game、ReviewRecord采用明确状态机，避免状态混乱。

### Data Structures & Algorithms

- 核心数据结构

  - GameConfig

    - JSON结构，描述玩法模板、参数、关卡、角色、素材、胜负条件和UI文案。
    - 选择理由：便于受控生成、版本管理、Web运行时加载和安全校验。
  - GameManifest

    - JSON结构，描述运行入口、资源列表、版本号、校验hash、SDK版本和预加载策略。
    - 选择理由：前端游戏容器可根据Manifest统一加载不同游戏。
  - FeedItem

    - 包含game_id、creator_id、score、reason、preload_assets、interaction_state。
    - 选择理由：解耦推荐计算和前端展示。
  - EventPayload

    - 标准化埋点结构：event_name、user_id、anonymous_id、game_id、session_id、timestamp、properties。
    - 选择理由：便于漏斗、留存和内容质量分析。
- GameConfig示例

```json
{
  "template": "avoidance_v1",
  "theme": "pixel_space",
  "durationSeconds": 60,
  "player": {
    "sprite": "ship_blue",
    "speed": 320,
    "hitPoints": 3
  },
  "objectives": \[
    { "type": "survive", "seconds": 60 },
    { "type": "collect", "item": "energy", "target": 20 }
  \],
  "enemies": \[
    { "type": "asteroid", "spawnRatePerSecond": 1.2, "speedRange": \[120, 260\] }
  \],
  "controls": {
    "mobile": "drag",
    "desktop": "arrow_keys"
  },
  "winCondition": "survive_and_collect",
  "loseCondition": "hp_zero"
}

```

- 关键算法

  - Prompt到模板映射

    - 输入：用户Prompt、用户选择模板、风格标签。
    - 输出：template_id、confidence、normalized_parameters。
    - MVP实现：LLM分类 + 规则兜底。
    - 复杂度：O(T)，T为模板数量，MVP模板数量小于10，性能可忽略。
  - 游戏配置校验

    - 输入：GameConfig。
    - 输出：validated_config或错误列表。
    - 规则：数值范围、必填字段、资源引用、关卡长度、资源体积、敏感词。
    - 复杂度：O(N)，N为配置节点数。
  - 游戏流排序

    - MVP评分公式：score = base_weight + recency_score + quality_score + interaction_score + creator_boost - risk_penalty - error_penalty。
    - 冷启动权重：精选池、最新发布、每个新作保底曝光。
    - 复杂度：候选集过滤O(N)，排序O(N log N)。N通过分页候选集控制在200以内。
  - 内容质量分

    - quality_score基于试玩完成率、30秒留存、点赞率、收藏率、举报率、加载失败率。
    - 每小时或每15分钟由Event Worker聚合更新。
- 扩展与性能考虑

  - 生成任务使用队列削峰，避免LLM和打包服务阻塞主API。
  - 游戏资源限制MVP单包不超过10MB，首屏关键资源不超过2MB。
  - 热门游戏Manifest和元数据缓存到Redis，TTL 60至300秒。
  - 游戏资源文件使用hash命名，启用长期CDN缓存。
  - 埋点批量上报，前端每10条或5秒flush一次，避免影响游戏帧率。

### System Interfaces

- API endpoints

|Method|Route|Purpose|Auth|
| --------| -------------------------------------------| ----------------------------------| ---------------|
|POST|/api/v1/auth/login|登录并返回访问令牌|Public|
|POST|/api/v1/auth/refresh|刷新访问令牌|Refresh Token|
|GET|/api/v1/me|获取当前用户资料与角色|User|
|POST|/api/v1/generation/tasks|创建AI生成任务|Creator|
|GET|/api/v1/generation/tasks/{taskId}|查询生成任务状态|Creator|
|POST|/api/v1/games|从生成结果创建游戏草稿|Creator|
|GET|/api/v1/games/{gameId}|获取游戏详情|Public/Owner|
|PATCH|/api/v1/games/{gameId}|更新标题、简介、封面、标签和参数|Owner|
|POST|/api/v1/games/{gameId}/publish|提交发布|Owner|
|GET|/api/v1/feed|获取游戏流列表|Public|
|POST|/api/v1/interactions|点赞、收藏、分享、举报|User|
|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|
|POST|/api/v1/admin/reviews/{reviewId}/decision|审核通过、拒绝或下架|Operator|
|POST|/api/v1/admin/featured-games|加入精选池|Operator|

- 创建生成任务请求示例

```json
{
  "prompt": "做一个像素风太空躲避游戏，玩家控制飞船躲避陨石，收集能量块，坚持60秒获胜。",
  "templateHint": "avoidance",
  "styleTags": \["pixel", "space"\],
  "uploadedAssetIds": \["asset_01HXYZ"\]
}

```

- 创建生成任务响应示例

```json
{
  "taskId": "gt_01HZA9Z9H4Q7",
  "status": "queued",
  "estimatedSeconds": 90,
  "pollingIntervalMs": 2000
}

```

- 查询生成任务响应示例

```json
{
  "taskId": "gt_01HZA9Z9H4Q7",
  "status": "succeeded",
  "progress": 100,
  "currentStep": "preview_ready",
  "gameDraft": {
    "gameId": "game_01HZAA1M0KQ8",
    "buildId": "build_01HZAA1R9QA3",
    "previewUrl": "https://cdn.example.com/games/build_01HZAA1R9QA3/index.html"
  },
  "error": null
}

```

- 获取游戏流请求示例

```http
GET /api/v1/feed?cursor=eyJzY29yZSI6MTIzfQ&limit=10&device=mobile
Authorization: Bearer optional

```

- 获取游戏流响应示例

```json
{
  "items": \[
    {
      "gameId": "game_01HZAA1M0KQ8",
      "title": "像素太空逃亡",
      "description": "躲避陨石并收集能量，坚持60秒。",
      "coverUrl": "https://cdn.example.com/covers/game_01HZAA1M0KQ8.webp",
      "creator": {
        "userId": "user_123",
        "nickname": "小林"
      },
      "manifestUrl": "https://cdn.example.com/manifests/build_01HZAA1R9QA3.json",
      "preloadAssets": \[
        "https://cdn.example.com/assets/ship.webp",
        "https://cdn.example.com/assets/bg.webp"
      \],
      "interactionState": {
        "liked": false,
        "favorited": false
      },
      "reason": "featured_and_new"
    }
  \],
  "nextCursor": "eyJzY29yZSI6MTE5fQ"
}

```

- 批量埋点请求示例

```json
{
  "sessionId": "sess_01HZAB",
  "anonymousId": "anon_abc",
  "events": \[
    {
      "eventName": "game_impression",
      "occurredAt": "2026-05-28T10:00:00.000Z",
      "gameId": "game_01HZAA1M0KQ8",
      "properties": {
        "position": 1,
        "feedRequestId": "feed_req_123"
      }
    },
    {
      "eventName": "game_play_30s",
      "occurredAt": "2026-05-28T10:00:32.000Z",
      "gameId": "game_01HZAA1M0KQ8",
      "properties": {
        "fpsAvg": 52,
        "loadTimeMs": 1800
      }
    }
  \]
}

```

- Third-party integrations

  - LLM Provider

    - 用途：Prompt理解、模板分类、参数生成、失败解释。
    - 协议：HTTPS JSON API。
    - 要求：设置超时30秒、最大重试2次、供应商错误降级到默认模板建议。
  - 图片生成或素材服务

    - MVP可选，建议优先使用内置素材库与风格包，减少生成不确定性。
    - 若接入图片生成，需进行内容安全检测和资源压缩。
  - 内容安全服务

    - 用途：文本、图片、用户资料、封面和Prompt检测。
    - 协议：HTTPS API。
    - 输出：pass、review、reject三类结果。
  - 对象存储和CDN

    - 用途：上传素材、生成资源、游戏包、封面和Manifest。
    - 要求：私有源站，CDN公开只读；上传使用服务端签名URL。
  - 数据分析工具

    - MVP内部事件表即可，后续可对接GrowingIO、神策、Mixpanel或自建ClickHouse。
- Internal modules

  - AuthModule：登录、Token、角色、匿名用户升级。
  - UserModule：用户资料、创作者主页。
  - AssetModule：上传、扫描、压缩、对象存储签名。
  - GenerationModule：任务创建、状态机、Prompt解析、GameConfig生成。
  - GameModule：草稿、版本、发布、详情、Manifest管理。
  - ReviewModule：审核队列、审核记录、下架、精选。
  - FeedModule：候选集、排序、分页、曝光保底。
  - InteractionModule：点赞、收藏、分享、举报。
  - AnalyticsModule：事件接收、聚合、看板。
  - AdminModule：后台权限、操作审计、系统配置。

### User Interface

- 创作工作台

  - 主区域：Prompt输入框、模板卡片、风格标签、上传素材入口。
  - 任务页：生成状态、当前步骤、预计等待时间、失败原因和重试入口。
  - 预览页：左侧游戏预览容器，右侧基础信息编辑面板。
  - 发布页：发布前检查清单、审核状态说明、分享链接。
- 玩家游戏流

  - 移动优先，全屏或近全屏纵向滑动。
  - 每个游戏项包含封面、标题、作者、玩法提示、开始按钮、点赞、收藏、分享、举报。
  - 游戏资源预加载下一项，当前项加载失败时显示错误提示并自动允许跳过。
  - 低端设备启用低画质模式，限制帧率到30fps。
- 创作者后台

  - 我的游戏列表：封面、标题、状态、曝光、试玩、互动、最后更新时间。
  - 数据详情：近7天趋势、曝光到试玩漏斗、平均游玩时长、加载失败率、举报率。
  - 操作：编辑、更新、下架、复制分享链接。
- 运营后台

  - 审核队列：状态筛选、风险等级、发布时间、创作者、标签。
  - 审核详情：游戏试玩、Prompt、生成配置、素材列表、安全检测结果、历史记录。
  - 操作：通过、拒绝、下架、备注、加入精选池、限制曝光。
- 交互模式

  - 关键流程必须有明确状态：加载中、成功、失败、禁用、重试。
  - 生成任务超过120秒提示后台等待，不阻断用户离开页面。
  - 所有破坏性操作使用二次确认，例如下架、删除草稿、拒绝审核。
- 可访问性与响应式设计

  - 移动端优先适配360px至430px宽度。
  - 桌面端优先优化创作工作台和运营后台。
  - 文本对比度符合WCAG AA基础要求。
  - 核心按钮支持键盘访问和可读ARIA标签。
  - 错误提示不只依赖颜色表达，应同时使用文本和图标。

## Data Model

How data is structured, stored, and accessed.

### Entities

```text
User
  - id: uuid (primary key)
  - phone: varchar(32) (nullable, unique)
  - email: varchar(255) (nullable, unique)
  - password_hash: varchar(255) (nullable)
  - nickname: varchar(64) (not null)
  - avatar_url: text (nullable)
  - role: enum(player, creator, operator, admin) (not null, default player)
  - status: enum(active, suspended, deleted) (not null, default active)
  - created_at: timestamptz (not null)
  - updated_at: timestamptz (not null)

```

```text
CreatorProfile
  - id: uuid (primary key)
  - user_id: uuid (unique, foreign key User.id)
  - slug: varchar(64) (unique, not null)
  - bio: varchar(500) (nullable)
  - total_games: integer (not null, default 0)
  - total_plays: bigint (not null, default 0)
  - created_at: timestamptz (not null)
  - updated_at: timestamptz (not null)

```

```text
Asset
  - id: uuid (primary key)
  - owner_id: uuid (foreign key User.id)
  - type: enum(image, audio, json, game_bundle, manifest) (not null)
  - source: enum(uploaded, generated, system) (not null)
  - storage_key: text (not null)
  - public_url: text (nullable)
  - mime_type: varchar(128) (not null)
  - size_bytes: integer (not null)
  - width: integer (nullable)
  - height: integer (nullable)
  - hash_sha256: char(64) (not null)
  - moderation_status: enum(pending, passed, review, rejected) (not null, default pending)
  - created_at: timestamptz (not null)

```

```text
PromptRecord
  - id: uuid (primary key)
  - user_id: uuid (foreign key User.id)
  - raw_prompt: text (not null)
  - normalized_prompt: text (nullable)
  - template_hint: varchar(64) (nullable)
  - style_tags: text\[\] (not null, default empty)
  - moderation_status: enum(pending, passed, review, rejected) (not null)
  - moderation_reason: text (nullable)
  - created_at: timestamptz (not null)

```

```text
GenerationTask
  - id: uuid (primary key)
  - user_id: uuid (foreign key User.id)
  - prompt_record_id: uuid (foreign key PromptRecord.id)
  - status: enum(queued, running, succeeded, failed, canceled, timed_out) (not null)
  - progress: integer (0 to 100)
  - current_step: varchar(64) (nullable)
  - template_id: varchar(64) (nullable)
  - llm_request_id: varchar(128) (nullable)
  - error_code: varchar(64) (nullable)
  - error_message: text (nullable)
  - started_at: timestamptz (nullable)
  - completed_at: timestamptz (nullable)
  - created_at: timestamptz (not null)
  - updated_at: timestamptz (not null)

```

```text
Game
  - id: uuid (primary key)
  - creator_id: uuid (foreign key User.id)
  - title: varchar(80) (not null)
  - description: varchar(500) (not null)
  - cover_asset_id: uuid (foreign key Asset.id, nullable)
  - status: enum(draft, pending_review, published, rejected, unpublished, deleted) (not null)
  - visibility: enum(private, public, limited) (not null, default private)
  - tags: text\[\] (not null, default empty)
  - age_rating: enum(all, teen, mature) (not null, default all)
  - current_version_id: uuid (nullable)
  - published_at: timestamptz (nullable)
  - created_at: timestamptz (not null)
  - updated_at: timestamptz (not null)

```

```text
GameVersion
  - id: uuid (primary key)
  - game_id: uuid (foreign key Game.id)
  - version_number: integer (not null)
  - generation_task_id: uuid (foreign key GenerationTask.id, nullable)
  - config_json: jsonb (not null)
  - manifest_asset_id: uuid (foreign key Asset.id)
  - bundle_asset_id: uuid (foreign key Asset.id, nullable)
  - runtime_version: varchar(32) (not null)
  - status: enum(draft, active, archived, failed) (not null)
  - created_at: timestamptz (not null)

```

```text
ReviewRecord
  - id: uuid (primary key)
  - game_id: uuid (foreign key Game.id)
  - version_id: uuid (foreign key GameVersion.id)
  - status: enum(pending, approved, rejected, escalated) (not null)
  - risk_level: enum(low, medium, high) (not null, default low)
  - reviewer_id: uuid (foreign key User.id, nullable)
  - reason_code: varchar(64) (nullable)
  - comment: text (nullable)
  - created_at: timestamptz (not null)
  - decided_at: timestamptz (nullable)

```

```text
Interaction
  - id: uuid (primary key)
  - user_id: uuid (foreign key User.id, nullable)
  - anonymous_id: varchar(128) (nullable)
  - game_id: uuid (foreign key Game.id)
  - type: enum(like, favorite, share, report) (not null)
  - status: enum(active, canceled) (not null, default active)
  - reason: varchar(128) (nullable, for report)
  - created_at: timestamptz (not null)
  - updated_at: timestamptz (not null)

```

```text
EventLog
  - id: uuid (primary key)
  - event_name: varchar(64) (not null)
  - user_id: uuid (nullable)
  - anonymous_id: varchar(128) (nullable)
  - session_id: varchar(128) (not null)
  - game_id: uuid (nullable)
  - properties: jsonb (not null)
  - occurred_at: timestamptz (not null)
  - received_at: timestamptz (not null)

```

```text
GameDailyStats
  - id: uuid (primary key)
  - game_id: uuid (foreign key Game.id)
  - stat_date: date (not null)
  - impressions: bigint (not null, default 0)
  - load_success: bigint (not null, default 0)
  - load_failed: bigint (not null, default 0)
  - play_starts: bigint (not null, default 0)
  - play_30s: bigint (not null, default 0)
  - completes: bigint (not null, default 0)
  - likes: bigint (not null, default 0)
  - favorites: bigint (not null, default 0)
  - shares: bigint (not null, default 0)
  - reports: bigint (not null, default 0)
  - avg_play_duration_ms: integer (nullable)
  - created_at: timestamptz (not null)
  - updated_at: timestamptz (not null)

```

```text
FeaturedGame
  - id: uuid (primary key)
  - game_id: uuid (foreign key Game.id)
  - operator_id: uuid (foreign key User.id)
  - priority: integer (not null, default 0)
  - start_at: timestamptz (not null)
  - end_at: timestamptz (nullable)
  - created_at: timestamptz (not null)

```

```text
AuditLog
  - id: uuid (primary key)
  - actor_id: uuid (foreign key User.id)
  - action: varchar(128) (not null)
  - target_type: varchar(64) (not null)
  - target_id: uuid (not null)
  - metadata: jsonb (not null)
  - ip_address: inet (nullable)
  - user_agent: text (nullable)
  - created_at: timestamptz (not null)

```

### Relationships

- User → CreatorProfile：one-to-one；User删除时CreatorProfile软删除或保留匿名化记录。
- User → Game：one-to-many；creator_id限制只能访问和修改自己的游戏。
- User → Asset：one-to-many；上传素材归属用户，系统素材owner可为空或使用system user。
- PromptRecord → GenerationTask：one-to-many；同一Prompt允许多次重试生成。
- GenerationTask → GameVersion：one-to-one或one-to-many；一次成功生成可创建一个版本，重试可产生新版本。
- Game → GameVersion：one-to-many；Game.current_version_id指向当前线上或草稿版本。
- Game → ReviewRecord：one-to-many；每次发布提交生成一条审核记录。
- Game → Interaction：one-to-many；同一用户对同一游戏的like和favorite应有唯一约束。
- Game → GameDailyStats：one-to-many；按game_id和stat_date唯一。
- Game → FeaturedGame：one-to-many；可配置多个时间段的精选计划。
- ReviewRecord → User：many-to-one；reviewer_id为运营或管理员。
- 关键约束

  - Game.status为published时必须存在current_version_id、cover_asset_id、title、description。
  - GameVersion.config_json必须通过JSON Schema校验。
  - Interaction唯一约束：user_id + game_id + type，适用于like和favorite；share和report允许多条但需要限频。
  - EventLog按occurred_at月度分区，避免长期写入膨胀影响查询。
  - 所有后台操作写入AuditLog。

### Storage

- 数据库

  - PostgreSQL作为主库，承载用户、游戏、版本、审核、互动和聚合统计。
  - 使用Prisma Migration管理Schema变更。
  - 关键索引：

    - Game(status, published_at desc)
    - Game(creator_id, updated_at desc)
    - ReviewRecord(status, created_at asc)
    - Interaction(game_id, type)
    - EventLog(occurred_at, event_name)
    - GameDailyStats(game_id, stat_date)
- 缓存

  - Redis缓存游戏详情、Manifest元数据、Feed候选集、用户会话和限频计数。
  - Feed缓存TTL 60秒，热门游戏详情TTL 300秒。
  - 生成任务状态可写PostgreSQL为准，Redis用于短期进度加速读取。
- 队列

  - BullMQ队列：generation_queue、moderation_queue、asset_processing_queue、event_aggregation_queue、notification_queue。
  - 每类任务配置重试次数、退避策略和死信队列。
- 文件/blob存储

  - 原始上传素材：private bucket，需签名访问。
  - 处理后封面和公开素材：public-read via CDN或私有源站加CDN回源。
  - 游戏Manifest和bundle：版本化路径，例如/games/{gameId}/versions/{versionId}/manifest.json。
  - 所有资源文件保留sha256 hash，用于去重、缓存和完整性校验。

### Data Flow

- 创作生成流程

  1. 用户登录并进入创作工作台。
  2. 前端提交Prompt、模板提示、风格标签和素材ID。
  3. API Server创建PromptRecord和GenerationTask，写入generation_queue。
  4. Moderation Worker先检测Prompt和上传素材；若reject则任务失败并返回明确原因。
  5. Generation Worker调用LLM解析Prompt，选择模板并生成GameConfig。
  6. Worker使用JSON Schema和业务规则校验GameConfig。
  7. Worker生成或绑定素材，创建GameManifest并上传对象存储。
  8. Worker创建Game草稿和GameVersion，更新任务状态为succeeded。
  9. 前端轮询任务状态并跳转预览页。
- 发布审核流程

  1. 创作者编辑标题、简介、封面、标签和操作说明。
  2. 点击发布后，API执行发布前检查。
  3. 系统创建ReviewRecord并将Game置为pending_review。
  4. 低风险内容可自动通过或进入运营队列，具体由配置控制。
  5. 运营通过后Game置为published和public，写入AuditLog。
  6. Feed候选集下次刷新时包含该游戏，并为新作分配保底曝光。
- 玩家游戏流流程

  1. 玩家打开首页，前端请求/api/v1/feed。
  2. FeedModule从精选、最新、质量分候选池取数据并排序。
  3. 前端展示第一款游戏并预加载下一款Manifest和关键资源。
  4. 玩家开始试玩，Game SDK上报load、start、30s、complete和error事件。
  5. 前端批量调用/events/batch上报埋点。
  6. Event Worker聚合更新GameDailyStats和质量分。
  7. 后续Feed排序降低高错误、高举报游戏的曝光。
- 运营审核流程

  1. 运营登录后台，调用/admin/reviews获取待审核列表。
  2. 运营查看游戏详情、Prompt、安全检测结果和试玩预览。
  3. 运营提交通过、拒绝、下架或精选操作。
  4. API更新Game、ReviewRecord、FeaturedGame并写AuditLog。

## Testing Plan

How the product will be validated at every level.

### Testing Strategy

- Unit tests

  - 覆盖范围：Prompt解析适配器、GameConfig校验、状态机转换、Feed评分、权限Guard、事件聚合逻辑。
  - 框架：Vitest或Jest。
  - 覆盖目标：核心业务模块行覆盖率不低于80%，状态机和权限模块不低于90%。
- Integration tests

  - 覆盖范围：REST API、PostgreSQL、Redis Queue、对象存储Mock、内容安全Mock、LLM Mock。
  - 重点验证：生成任务创建到成功、发布审核、游戏流返回、互动写入、事件聚合。
  - 使用Testcontainers启动PostgreSQL和Redis，避免只依赖内存Mock。
- E2E tests

  - 框架：Playwright。
  - 覆盖关键用户流：创作者生成游戏、预览发布、运营审核、玩家游戏流试玩互动、创作者查看数据。
  - 移动端视口必须覆盖iPhone和Android常见宽度。
- Performance tests

  - 工具：k6。
  - 目标：

    - /feed P95低于300ms，不含CDN资源加载。
    - /events/batch P95低于200ms。
    - /generation/tasks创建任务P95低于500ms。
    - 500并发玩家浏览Feed时错误率低于1%。
    - 每分钟5,000条事件写入时队列无持续积压。
- Game runtime tests

  - 使用自动化脚本加载每个模板生成的Manifest。
  - 验证资源存在、启动成功、SDK事件发出、低端设备模拟下帧率不低于30fps。
  - 对每个模板维护golden config样例。

### Testing Tools

- Frontend

  - Vitest：组件逻辑和工具函数。
  - React Testing Library：UI状态和交互。
  - Playwright：跨浏览器和移动视口E2E。
  - Lighthouse CI：性能、可访问性和最佳实践检查。
- Backend

  - Jest或Vitest：服务、控制器和状态机单测。
  - Supertest：API集成测试。
  - Testcontainers：PostgreSQL和Redis依赖环境。
  - Prisma migrate diff：Schema变更验证。
- Game runtime

  - Playwright：加载游戏容器并监听SDK事件。
  - 自定义Manifest Validator：校验Manifest资源、hash和字段完整性。
- Performance and security

  - k6：API压测。
  - OWASP ZAP Baseline Scan：基础Web安全扫描。
  - npm audit、pnpm audit、Snyk或GitHub Dependabot：依赖漏洞扫描。
- CI integration

  - Pull Request阶段：lint、type check、unit tests、API integration tests、build。
  - Merge to main阶段：完整测试、Docker镜像构建、安全扫描、部署到staging。
  - Release阶段：staging E2E、性能冒烟、手动批准生产部署。
- Code coverage

  - 全仓库最低70%。
  - 核心后端业务模块最低80%。
  - 权限、审核和发布状态机最低90%。
  - 覆盖率不达标阻断合并。

### Key Test Cases

- 创作链路Happy Path

  - 创作者登录。
  - 输入合法Prompt并选择模板。
  - 创建生成任务成功。
  - Worker生成GameConfig和Manifest。
  - 前端预览成功加载游戏。
  - 创作者填写标题、封面、标签并保存。
- 发布与审核

  - 发布前缺少标题时返回明确错误。
  - 内容安全reject时不得进入公开Feed。
  - pending_review游戏只有作者和运营可访问。
  - 运营通过后游戏出现在Feed候选集中。
  - 运营拒绝后创作者看到原因且可修改重提。
- 玩家游戏流

  - 未登录用户可以浏览和试玩。
  - 未登录用户点击点赞时触发登录引导，并在登录后恢复操作上下文。
  - 游戏加载失败时记录game_load_failed并允许跳过。
  - 上下滑动切换不会重复曝光同一游戏，除非列表耗尽。
  - 下一款游戏资源成功预加载。
- 互动与埋点

  - 同一用户重复点赞不会重复计数。
  - 收藏取消后状态更新为canceled。
  - 举报行为触发风险信号并对同一匿名用户限频。
  - 批量事件中部分无效事件不影响有效事件写入。
  - Event Worker聚合后数据看板数值正确。
- 权限与安全敏感操作

  - 普通用户不能访问/admin接口。
  - 创作者不能编辑他人游戏。
  - 运营操作必须写入AuditLog。
  - 已删除或下架游戏不能在公开Feed返回。
  - 上传非图片或超大文件会被拒绝。
- 性能边界

  - 单个游戏Manifest资源超过大小限制时生成失败并返回可理解原因。
  - 高并发Feed请求不造成数据库慢查询。
  - Redis不可用时Feed可降级为数据库读取并告警。
  - LLM超时后任务进入failed或timed_out，允许用户重试。

### Reporting

- CI报告

  - GitHub Actions或GitLab CI展示每次PR的测试、覆盖率、构建和安全扫描结果。
  - 失败测试必须阻断合并。
- 质量看板

  - Grafana展示API错误率、P95延迟、队列长度、生成成功率、游戏加载失败率。
  - Sentry展示前端错误、游戏运行错误和后端异常。
  - 每日自动生成MVP质量报告：生成任务数、成功率、平均生成时长、审核积压、Feed错误率。
- 缺陷管理

  - P0：核心链路不可用、权限绕过、数据丢失、安全事故。
  - P1：生成成功率显著下降、游戏流加载异常、审核流程阻塞。
  - P2：单页面体验问题、非关键统计延迟、文案错误。

## Deployment Plan

How the product moves from code to production.

### Environment Setup

- Development

  - 本地运行Docker Compose：PostgreSQL、Redis、MinIO、本地邮件或通知Mock。
  - 前端Next.js热更新运行在localhost:3000。
  - 后端NestJS运行在localhost:4000。
  - Worker独立进程运行generation、moderation和event aggregation。
  - 使用seed脚本创建管理员、运营、示例创作者、示例游戏和模板数据。
  - LLM和内容安全默认使用Mock Provider，可通过环境变量切换真实Provider。
- Staging

  - 与生产同构但缩小规格。
  - 使用独立PostgreSQL、Redis、OSS bucket和CDN域名。
  - 接入真实内容安全服务，LLM可使用较低成本模型。
  - 仅允许白名单用户访问创作和后台。
  - 每次main合并自动部署。
- Production

  - 云基础设施建议：

    - API Server运行在Kubernetes、ECS、Cloud Run或Render/Fly.io等容器平台。
    - Worker按队列类型独立部署，可横向扩容。
    - PostgreSQL使用云托管数据库，开启自动备份和只读副本预留。
    - Redis使用托管版，开启持久化和监控。
    - 静态前端部署到Vercel、Netlify或对象存储加CDN。
  - 生产访问必须使用HTTPS。
  - 所有Secrets从云Secret Manager或Vault读取，不写入代码仓库。

### CI/CD Pipeline

- Build steps

  1. 安装依赖：pnpm install --frozen-lockfile。
  2. 静态检查：eslint、prettier check。
  3. 类型检查：tsc --noEmit。
  4. 单元测试：vitest/jest with coverage。
  5. 集成测试：Testcontainers PostgreSQL和Redis。
  6. 前端构建：next build。
  7. 后端构建：nest build。
  8. Docker镜像构建并打tag。
  9. 依赖漏洞扫描和镜像扫描。
- Deployment trigger

  - Pull Request：创建Preview Deployment，仅连接staging级别Mock服务。
  - Merge to main：自动部署Staging。
  - Production：手动批准发布，建议每周固定窗口或MVP阶段按需发布。
- Preview deployments

  - 每个PR生成前端预览URL。
  - 后端可共享staging API或部署临时环境。
  - Preview环境禁止使用真实用户数据和真实支付/广告相关配置。

### Deploy Process

1. 准备发布版本

- 确认main分支CI全绿。
- 确认数据库Migration已在staging成功执行。
- 确认Feature Flag默认值符合发布策略。
- Verification checkpoint：staging smoke tests通过，错误率无异常。

2. 执行数据库迁移

- 在生产数据库执行向后兼容Migration。
- 禁止直接删除字段或重命名字段；采用expand-migrate-contract策略。
- Verification checkpoint：迁移执行成功，关键表读写正常。

3. 部署后端API

- 使用滚动发布或蓝绿部署。
- 保持旧版本至少可服务5至10分钟，确保无中断。
- Verification checkpoint：/health、/ready、登录、Feed接口正常。

4. 部署Worker

- 先暂停或降低新任务消费。
- 部署Worker新版本。
- 恢复队列消费并观察失败率。
- Verification checkpoint：generation_queue和event_aggregation_queue无异常积压。

5. 部署前端

- 发布Next.js前端或静态资源。
- 刷新CDN缓存中需要更新的HTML和Manifest加载脚本。
- Verification checkpoint：创作工作台、游戏流、后台入口可访问。

6. 灰度开启功能

- 使用Feature Flag先对内部用户开放。
- 观察30至60分钟后扩大到种子用户。
- Verification checkpoint：生成成功率、Feed错误率、Sentry错误无异常增长。

### Rollback Strategy

- 应用回滚

  - 保留最近3个稳定Docker镜像。
  - API和Worker可通过部署平台一键回滚到上一版本。
  - 前端可通过Vercel/Netlify回滚或CDN切回上一构建。
- 数据库回滚

  - 优先使用向后兼容Migration避免必须回滚数据库。
  - 对高风险Migration预先准备rollback SQL。
  - 删除数据类操作必须先备份，MVP阶段原则上不做破坏性Migration。
- Feature flags

  - generation_v2_enabled：控制新生成链路。
  - feed_ranking_v2_enabled：控制新推荐评分。
  - auto_review_enabled：控制自动审核通过。
  - external_asset_generation_enabled：控制外部图片生成服务。
  - 任何P0异常优先关闭相关Flag，而不是全站回滚。
- 队列回滚

  - Worker新版本异常时暂停队列消费。
  - 将失败任务标记为retryable或保持queued，待旧版本恢复后继续消费。
  - 对不兼容任务payload使用version字段区分处理逻辑。

### Post-Deploy Verification

- Smoke tests

  - 用户登录成功。
  - 创建生成任务成功，Mock或真实低成本生成可完成。
  - 预览游戏可加载并触发game_load_success。
  - 游戏可提交审核。
  - 运营可通过审核。
  - 已发布游戏可出现在Feed。
  - 点赞、收藏和埋点上报成功。
- Monitoring dashboards

  - API Latency：P50、P95、P99。
  - API Error Rate：4xx、5xx分布。
  - Queue Health：等待数、处理中、失败数、平均处理时长。
  - Generation Health：成功率、失败原因、平均生成时长。
  - Game Runtime：加载成功率、运行错误率、平均FPS、资源加载时长。
  - Database：CPU、连接数、慢查询、锁等待。
  - CDN：命中率、回源错误、流量峰值。
- Alert thresholds

  - API 5xx错误率5分钟内超过2%触发P1告警。
  - /feed P95超过800ms持续10分钟触发P1告警。
  - 生成成功率15分钟内低于70%触发P1告警。
  - generation_queue等待任务超过500或最老任务等待超过10分钟触发P1告警。
  - 游戏加载失败率超过8%持续15分钟触发P1告警。
  - 数据库连接使用率超过85%持续10分钟触发P1告警。
  - 权限相关异常或后台接口未授权访问激增触发P0安全告警。

## Security & Performance

Non-functional requirements and how they are addressed.

### Security

- Authentication

  - 使用JWT Access Token和Refresh Token。
  - Access Token有效期15分钟，Refresh Token有效期7至30天。
  - Refresh Token存储hash，支持注销和设备级撤销。
  - 游客使用anonymous_id，只允许浏览和试玩，不允许发布、收藏和后台操作。
- Authorization

  - 使用RBAC：player、creator、operator、admin。
  - 所有修改游戏、审核、精选、下架和查看后台接口必须校验角色和资源归属。
  - 后台接口单独命名空间/admin，并增加IP风险监控和操作审计。
- Input validation and sanitization

  - API使用Zod或class-validator校验请求。
  - Prompt长度限制，例如10至1,000字符。
  - 标题限制80字符，简介限制500字符，标签数量限制10个。
  - 上传文件限制MIME、扩展名、大小和尺寸。
  - 所有用户可见文本输出做HTML escaping，禁止直接渲染未清洗HTML。
- Game sandboxing

  - 游戏运行在受控iframe或隔离容器中。
  - 禁止生成游戏访问任意网络、Cookie、localStorage和父页面DOM。
  - Game SDK只暴露有限能力：事件上报、结束游戏、读取配置。
  - 设置Content Security Policy限制脚本源、资源源和frame权限。
- Secrets management

  - 本地开发使用.env.local，不提交仓库。
  - Staging和Production使用Secret Manager或Vault。
  - LLM、内容安全、OSS、数据库和Redis凭证定期轮换。
  - 日志中禁止输出Token、手机号、邮箱、Prompt敏感检测明文结果和第三方API Key。
- Dependency vulnerability scanning

  - Pull Request阶段运行pnpm audit或Snyk。
  - Docker镜像使用Trivy或云厂商镜像扫描。
  - Dependabot自动提交安全升级PR。
- OWASP Top 10 considerations

  - Broken Access Control：RBAC、资源归属校验、后台审计。
  - Cryptographic Failures：HTTPS、数据库备份加密、敏感字段加密或脱敏。
  - Injection：Prisma参数化查询，禁止拼接SQL；Prompt不直接作为系统指令执行。
  - Insecure Design：状态机限制非法发布和审核状态转换。
  - Security Misconfiguration：CSP、CORS白名单、生产关闭debug、对象存储私有源站。
  - Vulnerable Components：依赖扫描和锁文件审计。
  - Identification and Authentication Failures：Refresh Token轮换、登录限频、密码hash使用Argon2或bcrypt。
  - Software and Data Integrity Failures：游戏Manifest hash校验，CI签名镜像可选。
  - Security Logging and Monitoring Failures：后台操作、登录失败、安全拒绝全部记录。
  - SSRF：后端不允许用户提交任意URL抓取资源；如后续支持，必须使用URL allowlist和内网IP阻断。
- Content safety and compliance

  - Prompt、标题、简介、封面和上传素材均经过内容安全检测。
  - risk_level为high时自动拒绝，medium进入人工审核，low可进入普通审核或自动通过。
  - 举报达到阈值时自动限制曝光并进入运营复核。
  - 针对未成年人保护、版权素材和暴力色情等内容建立可配置策略。

### Performance

- Targets

  - 游戏流API响应：P95低于300ms，P99低于800ms。
  - 游戏详情API响应：P95低于200ms。
  - 埋点批量上报API响应：P95低于200ms。
  - 生成任务创建API响应：P95低于500ms。
  - 生成任务完成时长：P75低于120秒，P95低于240秒。
  - 游戏流首屏可交互时间：P75低于3秒，P95低于6秒。
  - 游戏运行帧率：中端移动设备平均不低于45fps，低端设备低画质不低于30fps。
  - 平台吞吐：MVP支持500并发浏览用户、每分钟5,000条埋点事件、每日1,000次生成任务。
- Optimization

  - 前端

    - Next.js路由级代码分割。
    - 游戏流只保留当前、前一、后一三个游戏容器。
    - 图片使用WebP/AVIF，封面多尺寸裁剪。
    - 下一款游戏Manifest和关键资源预加载。
    - 埋点异步批量发送，使用sendBeacon兜底。
  - 后端

    - 高频读接口使用Redis缓存。
    - Feed候选集预计算或短TTL缓存。
    - 事件写入走批量insert，聚合异步执行。
    - 数据库连接池按实例规格配置，避免连接耗尽。
  - 资源

    - 游戏bundle hash命名，CDN长期缓存。
    - 限制单游戏总资源大小和首屏关键资源大小。
    - 音频延迟加载，非关键图片懒加载。
  - Worker

    - 生成Worker按队列长度自动扩容。
    - LLM调用设置超时、重试和熔断。
    - 资产处理使用并发限制，避免CPU尖峰。
- Monitoring

  - APM：OpenTelemetry trace跨API、Worker和数据库。
  - Error tracking：Sentry捕获前端、Game Runtime和后端异常。
  - Custom metrics：生成成功率、审核积压、Feed曝光、游戏加载失败率、互动率。
- Scaling

  - MVP阶段：API Server 2个实例，Worker按队列1至3个实例，PostgreSQL单主实例，Redis托管实例。
  - 增长阶段：

    - API Server水平扩容。
    - Generation Worker按任务量独立扩容。
    - Event Worker和Analytics迁移到ClickHouse或数据仓库。
    - Feed Service从API Server拆分为独立服务。
    - PostgreSQL增加只读副本，读多写少接口走读副本。
  - Auto-scaling配置

    - API：CPU超过65%或RPS超过阈值扩容。
    - Worker：队列等待任务数超过100或最老任务等待超过2分钟扩容。
    - Event Worker：事件队列积压超过10,000条扩容。

### Observability

- Logging strategy

  - 使用结构化JSON日志。
  - 所有日志包含request_id、user_id可选、anonymous_id可选、module、operation、duration_ms、status。
  - 生成任务日志包含task_id、template_id、provider、error_code，但不直接记录敏感Prompt全文。
  - 审核和后台操作写AuditLog并长期保存。
  - 日志保留：应用日志30天，审计日志至少180天，安全日志至少180天。
- Metrics

  - Product metrics

    - creator_activation_rate。
    - generation_success_rate。
    - first_publish_conversion_rate。
    - feed_session_games_played。
    - game_interaction_rate。
    - player_d7_retention。
  - System metrics

    - API RPS、latency、error rate。
    - Queue depth、processing time、failure count。
    - Database CPU、connections、slow queries、locks。
    - Redis memory、hit rate、evictions。
    - CDN hit rate、origin error rate。
  - Game metrics

    - game_load_time_ms。
    - game_load_failed_rate。
    - runtime_error_rate。
    - fps_avg。
    - asset_size_bytes。
- Alerting

  - 告警渠道：飞书、Slack、邮件或短信，按严重级别区分。
  - P0响应：核心链路不可用、安全事故、数据丢失，15分钟内响应。
  - P1响应：生成失败率异常、Feed延迟异常、队列严重积压，工作时间30分钟内响应。
  - P2响应：非核心页面错误、低频统计延迟，下一工作日处理。
  - 每个告警必须包含Runbook链接：问题现象、排查仪表盘、常见原因、回滚步骤和负责人。