zizi 9735142518 docs: 文档治理——单一事实源去冲突 + 版本历史清理 + 文件名去日期

- 删除 4 个已过时文档（v2 架构选型审阅版 / v2 模块架构与MVP覆盖度 / 2 份已归档 review），
  架构文档收敛为 6 份、agent-specs 收敛为 1 份
- 消除冲突与陈旧值：基础设施成本 ¥3,800→¥4,300；生成成功率 85% 消歧为
  "远期蓝图 / MVP 验收 80%"；技术决策版架构图补 studio（12→13 模块）；
  契约口径全仓统一为 8 类（7 个 Day-0 contracts/ 文件 + Prompt Registry 第 8 类）
- 清理各文档内部历史/迁移/changelog 段落与失效引用（已删"业务能力全景"章节号引用、
  LayaAir 导出快手等事实错误）
- 8 个保留文档文件名去日期，全仓 markdown 链接与蒸馏来源引用联动更新；
  AGENTS.md 必读清单（7→5 份）与 CLAUDE.md 目录结构同步
- docs/memorys/ 按全局约定豁免（保留带日期归档），docs-design/ 不在本次范围

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-07 17:46:17 +00:00

58 KiB

Raw Blame History

绘境AI游戏生态平台 — 系统概要设计（技术决策版）

文档编号：HJ-ARCH-001 版本：v2.0 受众：技术合伙人 / CTO / 首席架构师 生成时间：2026-06-06 关联文档：

业务需求：docs-design/MVP PRD.md、docs-design/Product Strategy Document.md

竞品分析：docs-design/竞品分析报告.md

产品需求/技术模块/映射三文档：docs/architecture/产品需求清单.md、docs/architecture/技术架构与模块.md、docs/architecture/需求模块映射.md

1. 背景与目标

1.1 业务背景

绘境AI 是一个 AI 驱动的全民游戏创作与变现生态平台。核心命题：让零基础创作者用一句话做出可上线、可变现的轻量小游戏，让玩家像刷短视频一样发现和试玩，让平台通过广告分成、订阅、B端定制实现商业闭环。

竞品格局（详见竞品分析报告）：

极逸 SOON：技术最强，无流量
TapTap 制造：有流量，封闭且变现弱
FunloomAI：有付费验证，品类窄

绘境的差异化 = 全闭环：生成 + 流量 + 变现三件事同时解决。

1.2 系统目标

维度	目标	量化指标
功能完整性	创作→生成→预览→发布→审核→游戏流→试玩→互动→变现全链路闭环	端到端可走通
生成能力	自然语言输入，3-5 分钟产出可玩 Web 游戏	生成成功率 ≥85%（远期蓝图目标；MVP 验收线 ≥80%）
运行性能	游戏流首屏可交互	P75 < 3s, P95 < 6s
可用性	核心链路服务可用	≥ 99.5%（MVP）, ≥ 99.9%（正式）
扩展性	支持从单体启动平滑迁移到微服务	模块可独立部署
成本可控	MVP 阶段基础设施月成本	< 5000 元/月

1.3 非目标（明确不做）

不做 3D 开放世界游戏生成
不做专业级游戏引擎（Unity/Unreal 级别）
不做海外市场（MVP 阶段）
不做完全开放式代码生成（用模板约束保证稳定性）
不自研大模型（接入通用 LLM + 开源 Agent 框架）

2. 业务架构

2.1 核心业务域

graph LR
  subgraph 创作域
    A0[资产管理] --> A1[游戏设计]
    A1 --> A2[AI 辅助生成]
    A2 --> A3[组装/编辑/调试]
    A3 --> A4[预览试玩]
    A4 --> A5[质量校验]
    A5 --> A6[发布申请]
  end

  subgraph 分发域
    B1[审核通过] --> B2[游戏流推荐]
    B2 --> B3[玩家试玩]
    B3 --> B4[互动反馈]
    B4 --> B5[分享传播]
  end

  subgraph 变现域
    C1[广告植入] --> C2[广告展示]
    C2 --> C3[收益归集]
    C3 --> C4[创作者结算]
    C4 --> C5[提现]
  end

  subgraph 数据域
    D1[事件采集] --> D2[质量评分]
    D2 --> D3[推荐优化]
    D3 --> D4[AI 优化建议]
    D4 --> A3
  end

  A5 --> B1
  B3 --> C2
  B4 --> D1

2.2 用户角色与权限模型

graph TB
  VISITOR[访客<br/>可浏览试玩] --> PLAYER[玩家<br/>+互动/收藏/举报]
  PLAYER --> CREATOR[创作者<br/>+创建/生成/发布]
  CREATOR --> PRO_CREATOR[专业创作者<br/>+批量/编排/B端]
  
  OPERATOR[运营<br/>审核/推荐/下架] --> ADMIN[管理员<br/>+系统配置/权限]
  
  B_CLIENT[B端客户<br/>需求/验收/报告]

角色	权限边界	对应系统入口
访客	浏览游戏流 + 试玩（无需登录）	game-studio
玩家	+点赞/收藏/分享/举报/评论	game-studio（登录后）
创作者	+创建项目/生成/编辑/发布/数据看板/收益	game-studio
专业创作者	+批量生成/工作流编排/素材市场/B端接单	game-studio（高级功能）
运营	审核/推荐/下架/精选/内容安全	game-admin
管理员	+系统配置/用户管理/权限/字典/监控	game-admin
B端客户	需求提交/进度查看/验收/报告	独立 B 端门户（P1）

2.3 核心业务流程

创作者主流程（三种模式）

模式 A：一句话生成（小白路径）

sequenceDiagram
  participant C as 创作者
  participant S as game-studio
  participant GW as Gateway
  participant AIGC as aigc-module
  participant DIFY as Dify(编排)
  participant OG as OpenGame(生成)
  participant RT as runtime-module
  participant PRJ as project-module
  participant BPM as bpm-module

  C->>S: 输入 Prompt + 选择风格/模板
  S->>GW: POST /api/aigc/generate
  GW->>AIGC: 转发（鉴权通过）
  AIGC->>AIGC: 创建生成任务（MQ）
  AIGC-->>S: 202 Accepted {taskId}
  S->>S: 轮询/SSE 监听任务状态

  AIGC->>DIFY: HTTP 调用 Workflow API
  DIFY->>DIFY: 节点1: Prompt 安全检测
  DIFY->>DIFY: 节点2: 意图解析 + 模板匹配
  DIFY->>DIFY: 节点3: GameConfig 生成 + Schema 校验
  DIFY->>OG: 节点4: HTTP 调用 OpenGame Agent
  OG->>OG: 6阶段 Pipeline（脚手架→设计→素材→代码→验证→修正）
  OG-->>DIFY: 返回游戏代码包
  DIFY->>DIFY: 节点5: 质量评估
  DIFY-->>AIGC: 返回完整 GamePackage

  AIGC->>RT: 编译 + 打包 + 上传 OSS
  RT-->>AIGC: packageUrl + manifest
  AIGC->>PRJ: 写入草稿版本（含生成的资产）
  AIGC-->>S: 任务完成通知

  C->>S: 预览试玩（iframe 加载）
  C->>S: 编辑标题/简介/封面/标签
  C->>S: 点击发布
  S->>GW: POST /api/project/publish
  GW->>PRJ: 提交发布审核
  PRJ->>BPM: 发起审核工作流
  BPM-->>C: 通知审核结果

模式 B：资产驱动创作（进阶路径，详见下方"创作工作台核心设计"）

创作者先在资产空间中逐步积累游戏素材（角色/关卡/音乐/机制），然后选择模板组装为完整游戏。AI 在每个环节辅助生成单项资产，但最终决策权在创作者。

模式 C：工作流编排（专业路径）

专业创作者可进入 Dify 暴露的可视化编排界面，自定义生成流程的节点、参数和条件分支。适用于批量生产、品牌定制等场景。

玩家游戏流主流程

sequenceDiagram
  participant P as 玩家
  participant S as game-studio
  participant GW as Gateway
  participant FEED as feed-module
  participant RT as runtime-module
  participant TEL as telemetry-module

  P->>S: 进入首页/游戏流
  S->>GW: GET /api/feed/list?cursor=xxx
  GW->>FEED: 推荐列表（规则+行为信号）
  FEED-->>S: [{gameId, title, cover, manifest_url}, ...]

  S->>S: 展示封面卡片 + 预加载下一款 manifest
  P->>S: 点击"开始玩"
  S->>RT: 加载 manifest → 资源 → 启动游戏（iframe sandbox）
  S->>TEL: 上报 game_load_start
  RT-->>S: 游戏启动
  S->>TEL: 上报 game_play_start

  P->>S: 游玩 30s+
  S->>TEL: 上报 game_play_30s
  P->>S: 游戏结束
  S->>TEL: 上报 game_complete
  P->>S: 点赞/收藏/分享
  S->>GW: POST /api/feed/interaction
  GW->>FEED: 记录互动

  P->>S: 上滑切换下一款
  S->>S: 销毁当前容器 + 激活预加载容器

创作工作台核心设计

设计原则：创作者不是"Prompt 输入者"，而是"游戏设计师"。AI 是助手，不是替代品。

创作工作台提供三种创作模式，覆盖从小白到专业的全链路：

模式	目标用户	交互方式	AI 角色
一句话生成	纯小白	Prompt → 一键出成品	AI 主导，人确认
资产驱动创作	进阶创作者	先设计资产，再组装游戏	AI 辅助生成单项资产
全自定义编排	专业创作者	可视化编排工作流 + 手动调参	AI 按需调用

创作者资产管理体系

每个创作者拥有独立的资产空间（Asset Workspace），所有创作素材归创作者所有：

graph TB
  subgraph 创作者资产空间
    direction TB
    
    subgraph 视觉资产
      IMG[角色立绘/场景图/UI 元素]
      TEX[贴图/材质/粒子效果]
      ANIM[动画/帧序列/Spine]
      COVER[封面/宣传图/分享卡片]
    end
    
    subgraph 音频资产
      BGM[背景音乐]
      SFX[音效]
      VOICE[角色语音/音色]
      MV[过场动画/MV]
    end
    
    subgraph 设计资产
      CHAR[角色设定<br/>外观/性格/能力/台词]
      LEVEL[关卡设计<br/>地图/难度曲线/触发条件]
      MECH[游戏机制<br/>玩法规则/胜负条件/计分]
      ECON[经济系统<br/>货币/道具/产出/消耗]
      STORY[剧情/对话树/分支]
    end
    
    subgraph 商业化资产
      SHOP[付费道具设计<br/>皮肤/复活/加速/关卡包]
      AD_CFG[广告位配置<br/>时机/类型/频次]
      SOCIAL[社交接入配置<br/>好友/排行/邀请/PK]
    end
  end
  
  IMG & TEX & ANIM & COVER --> GAME[游戏项目]
  BGM & SFX & VOICE & MV --> GAME
  CHAR & LEVEL & MECH & ECON & STORY --> GAME
  SHOP & AD_CFG & SOCIAL --> GAME

资产生成方式

每种资产都支持三种产出方式：

产出方式	说明	质量控制
AI 生成	自然语言描述 → AI 产出（图片/音乐/角色/关卡等）	平台合规检测 + 风格一致性校验
手动上传	创作者上传自有素材	格式/大小/安全扫描 + 版权声明
市场获取	从素材市场购买/获取他人共享的资产	授权链验证 + 使用范围限制

资产驱动的游戏组装流程

sequenceDiagram
  participant C as 创作者
  participant WS as 工作台
  participant ASSET as 资产服务
  participant AIGC as AI 生成
  participant COMP as 合规检测
  participant RT as 运行时

  Note over C,RT: 阶段一：准备资产
  C->>WS: 创建角色设定（描述性格/外观/能力）
  WS->>AIGC: AI 生成角色立绘（基于描述）
  AIGC->>COMP: 图像合规检测
  COMP-->>AIGC: 通过
  AIGC-->>WS: 角色立绘
  C->>ASSET: 保存到我的资产空间

  C->>WS: 设计关卡（描述地图/难度/触发器）
  WS->>AIGC: AI 生成关卡配置 JSON
  AIGC-->>WS: 关卡配置
  C->>WS: 手动微调数值（速度/生成频率/奖励）
  C->>ASSET: 保存关卡到资产空间

  C->>WS: 描述背景音乐风格
  WS->>AIGC: AI 生成 BGM
  AIGC->>COMP: 音频合规检测（版权/内容）
  COMP-->>AIGC: 通过
  C->>ASSET: 保存 BGM

  Note over C,RT: 阶段二：组装游戏
  C->>WS: 选择游戏模板/机制（如"躲避类"）
  C->>WS: 从资产空间拖入：角色 + 关卡 + BGM + 音效
  C->>WS: 配置游戏机制（胜负条件/计分规则）
  C->>WS: 配置付费道具（复活 = 看广告 or ¥1）
  C->>WS: 配置广告位（过关插屏 + 结算激励视频）
  WS->>RT: 编译组装 → GamePackage

  Note over C,RT: 阶段三：预览与调试
  C->>WS: 预览试玩（iframe 沙箱）
  WS->>WS: 实时调试面板（FPS/事件流/状态变量）
  C->>WS: 发现问题 → 调整参数 → 重新编译
  C->>WS: 满意 → 提交发布

质量与合规控制点

在创作全链路设置7 道门禁，确保产出质量和平台安全：

graph LR
  G1[① Prompt/描述<br/>安全检测] --> G2[② AI 产出<br/>合规校验]
  G2 --> G3[③ 资产入库<br/>版权声明+风格校验]
  G3 --> G4[④ 组装时<br/>Schema 完整性]
  G4 --> G5[⑤ 编译后<br/>性能门禁]
  G5 --> G6[⑥ 预览时<br/>可玩性自测]
  G6 --> G7[⑦ 发布前<br/>终审+合规+适龄]

门禁	检测内容	阻断条件	责任方
① Prompt 安全	违禁词/敏感意图/注入攻击	命中 → 拒绝 + 提示修改	compliance 模块
② AI 产出合规	图片涉黄涉暴/文本违规/音频侵权	检测不通过 → 不入库	compliance 模块
③ 资产入库	版权声明完整/风格与 IP 库比对/文件安全	疑似侵权 → 冻结 + 人工复核	ip 模块
④ 组装完整性	GameConfig JSON Schema/必填字段/资源引用有效	缺失 → 编译失败 + 提示	runtime 模块
⑤ 性能门禁	包体积 ≤10MB/首屏 ≤2MB/无外部网络请求	超限 → 阻断 + 优化建议	runtime 模块
⑥ 可玩性自测	加载成功/启动成功/30s 无崩溃/结束事件触发	失败 → 阻断发布	runtime 模块
⑦ 发布终审	标题/简介/封面/标签/适龄/全链路合规汇总	人工或自动决策	bpm + compliance

创作者自由度 vs 平台控制的边界

维度	创作者可以做	平台不允许
视觉	上传任意图片/AI 生成/购买素材	涉黄涉暴涉政/侵犯已知 IP
音频	上传/AI 生成/购买	侵权音乐/违规语音
玩法	任意配置机制/关卡/难度	赌博/欺诈/诱导未成年消费
付费设计	设计道具/定价/广告位	强制付费才能通关/虚假概率/过度广告
社交接入	排行榜/好友邀请/PK	获取用户隐私/骚扰
代码	通过模板参数控制逻辑	注入任意 JS/访问外部网络/操作 DOM

底线原则：创作者通过配置（不是代码）驱动游戏行为。平台对运行时代码拥有完全控制权，创作者不直接写 JS——这是安全和合规可控的基础。

3. 系统架构

3.1 整体分层

graph TB
  subgraph ACCESS[接入层]
    CDN[CDN<br/>静态资源/游戏包]
    NGINX[Nginx<br/>前端托管/SSL终结]
  end

  subgraph FE[前端应用]
    STUDIO[game-studio<br/>Vue3+Vant<br/>创作者+玩家]
    ADMIN[game-admin<br/>Vue3+ElementPlus<br/>运营+管理]
  end

  subgraph GW[网关层]
    GATEWAY[Spring Cloud Gateway<br/>路由/限流/鉴权/灰度]
  end

  subgraph BIZ[业务服务层]
    STU[studio<br/>创作编排/编辑器域]
    PRJ[project<br/>项目生命周期]
    AIGC[aigc<br/>AI生成引擎]
    RT[runtime<br/>运行时/包/转换]
    FEED[feed<br/>游戏流/推荐]
    TEL[telemetry<br/>遥测/数据]
    PAY[pay<br/>支付/订阅]
    TRADE[trade<br/>结算/钱包]
    COMM[community<br/>社区/通知]
    IP[ip<br/>素材/版权]
    COMP[compliance<br/>合规/安全]
    BIZSVC[biz<br/>B端业务]
    AD[ad<br/>广告引擎]
  end

  subgraph INFRA[基础设施层_Yudao原生]
    SYS[system<br/>用户/权限/OAuth2]
    INFRASVC[infra<br/>文件/任务/日志]
    BPM[bpm<br/>工作流]
  end

  subgraph AI[AI引擎层]
    DIFY[Dify<br/>DAG编排/多模型]
    OPENGAME[OpenGame Agent<br/>Python/代码生成]
  end

  subgraph MW[中间件层]
    NACOS[Nacos]
    MYSQL[MySQL 8.0]
    REDIS[Redis 7]
    MQ[RocketMQ 5]
    MINIO[MinIO/OSS]
  end

  subgraph OBS[可观测性]
    PROM[Prometheus]
    GRAFANA[Grafana]
    SENTRY[Sentry]
    JAEGER[Jaeger<br/>链路追踪]
  end

  NGINX --> STUDIO
  NGINX --> ADMIN
  STUDIO --> GATEWAY
  ADMIN --> GATEWAY
  GATEWAY --> PRJ
  GATEWAY --> AIGC
  GATEWAY --> RT
  GATEWAY --> FEED
  GATEWAY --> TEL
  GATEWAY --> PAY
  GATEWAY --> TRADE
  GATEWAY --> COMM
  GATEWAY --> IP
  GATEWAY --> COMP
  GATEWAY --> BIZSVC
  GATEWAY --> AD
  GATEWAY --> SYS
  GATEWAY --> INFRASVC
  GATEWAY --> BPM
  AIGC --> DIFY
  DIFY --> OPENGAME
  PRJ --> MYSQL
  PRJ --> REDIS
  PRJ --> MQ
  PRJ --> MINIO
  AIGC --> MYSQL
  AIGC --> REDIS
  AIGC --> MQ
  AIGC --> MINIO
  RT --> MYSQL
  RT --> REDIS
  RT --> MQ
  RT --> MINIO
  FEED --> MYSQL
  FEED --> REDIS
  FEED --> MQ
  FEED --> MINIO
  TEL --> MYSQL
  TEL --> REDIS
  TEL --> MQ
  TEL --> MINIO

3.2 部署拓扑（Docker Compose 阶段）

graph LR
  subgraph 宿主机
    subgraph 中间件容器
      nacos[Nacos:8848]
      mysql[MySQL:3306]
      redis[Redis:6379]
      rocketmq[RocketMQ:9876]
      minio[MinIO:9000]
    end

    subgraph 基础服务容器
      gateway[Gateway:8080]
      system[System:48081]
      infra[Infra:48082]
      bpm[BPM:48083]
    end

    subgraph 业务服务容器
      game_all[game-server:48090<br/>单体模式含全部13个业务模块]
    end

    subgraph AI引擎容器
      dify[Dify:3000+80]
      opengame[OpenGame:8100]
    end

    subgraph 前端容器
      admin_nginx[admin-nginx:80]
      studio_nginx[studio-nginx:81]
    end

    subgraph 可观测性容器
      prometheus[Prometheus:9090]
      grafana[Grafana:3001]
      jaeger[Jaeger:16686]
    end
  end

MVP 阶段单体启动：所有 13 个业务模块编译为同一个 JAR（game-server），通过 Spring Profile 控制模块加载。需要独立扩缩时，Nacos 配置一改即拆为独立服务。

3.3 模块间通信

通信方式	场景	协议
同步 HTTP	前端→Gateway→业务服务	REST JSON
同步 HTTP	aigc→Dify, Dify→OpenGame	REST JSON
同步 Feign	服务间同步调用（如 project→system 查用户）	Spring Cloud OpenFeign
异步 MQ	生成任务派发、审核通知、事件摄取、结算触发	RocketMQ
事件广播	发布成功→feed 刷新缓存、→telemetry 记录	RocketMQ Topic

3.4 平台 Game SDK 设计

为什么需要 SDK

生成的游戏运行在 iframe 沙箱中，与平台隔离。SDK 是平台能力注入游戏的唯一通道——没有 SDK，平台就是一个静态文件托管。

设计原则

原则	含义	约束
极轻	不增加用户感知加载时间	核心模块压缩后 < 8KB
非阻塞	所有 API 调用异步，不占游戏主线程	零同步等待
优雅降级	SDK 任何功能失败，游戏照常运行	try-catch 包裹每个模块
按需加载	非核心模块（广告/社交/支付）懒加载	首屏只加载 core
沙箱安全	通过 postMessage 与宿主通信	不暴露宿主 DOM/Cookie/网络
版本化	SDK 版本与平台版本解耦，向后兼容	semver 管理

SDK 模块分层

┌─────────────────────────────────────────────────────────────┐
│  HuijingGameSDK（注入到每个生成的游戏中）                      │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Core Layer（内联，< 8KB，游戏启动时加载）                 │ │
│  │  ├── Lifecycle   游戏生命周期管理                          │ │
│  │  ├── EventBus    SDK ↔ 宿主 postMessage 通信             │ │
│  │  ├── Telemetry   事件上报（批量/异步/sendBeacon 兜底）     │ │
│  │  └── ErrorTrack  错误捕获与上报                            │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                               │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Plugin Layer（按需懒加载，不影响首屏）                     │ │
│  │  ├── Ad          广告展示（激励视频/插屏/Banner）          │ │
│  │  ├── Pay         内购/打赏触发                             │ │
│  │  ├── Social      排行榜/好友/邀请/分享                    │ │
│  │  ├── Storage     云存档/进度保存                           │ │
│  │  └── Debug       调试面板（仅开发模式）                    │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

各模块能力清单

Core.Lifecycle（生命周期）— 必选，内联

API	说明	触发时机
`sdk.ready()`	通知宿主游戏初始化完成	游戏入口代码执行后
`sdk.started()`	通知宿主游戏开始运行	第一帧渲染后
`sdk.paused()`	通知宿主游戏暂停	用户切后台/广告弹出
`sdk.resumed()`	通知宿主游戏恢复	广告关闭/回到前台
`sdk.completed(result)`	通知宿主游戏结束	通关/失败/超时
`sdk.error(err)`	上报致命错误	游戏崩溃时
`sdk.onPause(cb)`	监听宿主要求暂停	切换游戏/销毁前
`sdk.onResume(cb)`	监听宿主要求恢复	回到当前容器

Core.Telemetry（事件上报）— 必选，内联

API	说明	约束
`sdk.track(event, data)`	上报自定义事件	异步，不返回 Promise
`sdk.trackTiming(label, ms)`	上报耗时	异步

内置自动上报（无需游戏代码调用）：

game_load_start / game_load_success / game_load_failed
game_play_start / game_play_30s / game_complete
game_error（window.onerror + unhandledrejection）
game_fps（每 10s 采样平均 FPS）

Core.ErrorTrack（错误捕获）— 必选，内联

能力	说明
全局 onerror 捕获	自动上报 JS 错误
unhandledrejection	自动上报 Promise 异常
错误去重	相同 stack 10s 内只报 1 次
错误不中断游戏	捕获后吞掉，游戏继续运行

Plugin.Ad（广告）— 按需加载

API	说明	触发方式
`sdk.ad.showRewarded(opts)`	展示激励视频，回调结果	创作者在游戏配置中声明广告点
`sdk.ad.showInterstitial()`	展示插屏广告	关卡结束/游戏结束时自动触发
`sdk.ad.showBanner(position)`	展示 Banner	游戏启动时按配置展示
`sdk.ad.onReward(cb)`	监听激励完成	玩家看完广告后回调
`sdk.ad.onClose(cb)`	监听广告关闭	广告关闭后恢复游戏

降级策略：广告加载失败 → 跳过广告 → 游戏继续。绝不因广告问题阻断游戏体验。

Plugin.Pay（内购）— 按需加载

API	说明
`sdk.pay.purchase(itemId)`	发起购买（由宿主弹出支付 UI）
`sdk.pay.onSuccess(cb)`	支付成功回调
`sdk.pay.onCancel(cb)`	支付取消回调
`sdk.pay.queryOwned(itemId)`	查询是否已拥有

Plugin.Social（社交）— 按需加载

API	说明
`sdk.social.getLeaderboard(id)`	获取排行榜数据
`sdk.social.submitScore(id, score)`	提交分数
`sdk.social.getFriends()`	获取好友列表（需授权）
`sdk.social.invite(friendId)`	邀请好友
`sdk.social.share(data)`	触发分享（由宿主处理）

Plugin.Storage（云存档）— 按需加载

API	说明
`sdk.storage.save(key, data)`	保存进度到云端
`sdk.storage.load(key)`	加载云端进度
`sdk.storage.delete(key)`	删除存档

Plugin.Debug（调试面板）— 仅开发模式

能力	说明
实时 FPS 曲线	性能监控
事件流日志	SDK 所有事件实时展示
状态变量查看器	GameConfig 运行时状态
trace_id 展示	从生成到运行的全链路追踪 ID
网络请求拦截	监控 SDK 与宿主通信
一键性能快照	导出性能数据

SDK 与宿主通信协议

sequenceDiagram
  participant GAME as 游戏(iframe)
  participant SDK as HuijingGameSDK
  participant HOST as 宿主(game-studio)
  participant API as 后端 API

  Note over GAME,API: 游戏启动
  HOST->>SDK: postMessage({type:'init', config, trace_id})
  SDK->>SDK: 初始化 Core 模块
  SDK->>GAME: window.HuijingSDK 可用
  GAME->>SDK: sdk.ready()
  SDK->>HOST: postMessage({type:'lifecycle', event:'ready'})

  Note over GAME,API: 事件上报（异步批量）
  GAME->>SDK: sdk.track('level_complete', {level:1, score:100})
  SDK->>SDK: 加入缓冲队列（每 10 条 or 5s flush）
  SDK->>HOST: postMessage({type:'telemetry', events:[...]})
  HOST->>API: POST /api/telemetry/events/batch

  Note over GAME,API: 广告展示（懒加载）
  GAME->>SDK: sdk.ad.showRewarded({placement:'revive'})
  SDK->>SDK: 首次调用 → 动态加载 Ad Plugin
  SDK->>HOST: postMessage({type:'ad', action:'show_rewarded'})
  HOST->>HOST: 弹出广告覆盖层（iframe 外部渲染）
  HOST->>SDK: postMessage({type:'ad', event:'reward_granted'})
  SDK->>GAME: onReward callback 触发
  GAME->>GAME: 玩家复活，游戏继续

  Note over GAME,API: 广告失败降级
  HOST->>SDK: postMessage({type:'ad', event:'ad_failed'})
  SDK->>GAME: onReward callback({fallback:true})
  GAME->>GAME: 免费给复活（不阻断体验）

关键设计决策

决策	选择	为什么
广告渲染位置	宿主侧（iframe 外部）	广告 SDK 需要网络权限，游戏 iframe 禁止网络
支付 UI	宿主侧弹出	支付安全不能在游戏沙箱内完成
社交数据	宿主代理请求	游戏无网络权限，通过 postMessage 由宿主代理
事件缓冲	SDK 内 10 条/5s flush	减少 postMessage 频率，不影响游戏帧率
错误上报	捕获但不中断	游戏稳定性 > 数据完整性
插件加载	首次 API 调用时懒加载	首屏只需 8KB Core，广告/社交/支付按需

合规定位与降级原则

合规模型：同意即可用，拒绝即不可用。

用户注册/首次进入
  ↓
隐私协议 + 用户服务协议（必须同意）
  ↓
同意 → 进入平台 → SDK Core 全功能默认启用
拒绝 → 不可使用平台

法律基础：《个保法》第13条第(二)款——"为订立、履行合同所必需"。用户接受平台服务即构成合同关系，SDK 采集的数据（生命周期/互动/错误/性能）是提供推荐、质量保障、变现服务的必要数据。

与抖音/微信小游戏同一合规模式：用户不同意则不可玩免费游戏。

非核心能力降级原则（铁律）：

分类	模块	失败时游戏行为	用户感知
核心（异步不阻塞）	Lifecycle / Telemetry / ErrorTrack	上报失败 → 静默丢弃，游戏不受影响	零感知
非核心（失败即跳过）	Ad	广告加载失败/超时 → 跳过广告，给玩家免费奖励	"广告不可用，已赠送奖励"
非核心（失败即跳过）	Pay	支付网络异常 → 提示稍后重试，不阻断游戏	toast 提示
非核心（失败即跳过）	Social	排行榜/好友加载失败 → 展示本地缓存或空态	功能降级但可继续玩
非核心（失败即跳过）	Storage	云存档失败 → 回退 localStorage	下次换设备可能丢失进度

编码铁律：Plugin 层的任何代码都包裹在 try-catch 中，异常不向上抛。游戏主循环（requestAnimationFrame）永远不被 SDK 阻塞。

// SDK Plugin 调用的内部实现模式（伪代码）
async function safePluginCall(fn, fallback) {
  try {
    return await Promise.race([fn(), timeout(5000)])
  } catch (e) {
    sdk._core.telemetry.track('sdk_plugin_error', { module: fn.name, error: e.message })
    return fallback  // 游戏拿到 fallback 值继续运行
  }
}

合规所需的产品侧配套

文件/机制	说明	时机
隐私政策	明确列出 SDK 采集的所有数据类型、用途、保留期限	注册前强制展示
SDK 目录页	列出 HuijingGameSDK + 第三方 SDK（穿山甲/优量汇/微信支付等）	隐私政策附录
未成年人保护	识别未成年后：禁止广告展示 + 禁止付费 + 限制时长 + 最小采集	实名认证后触发
数据删除权	用户注销时清除关联的事件/画像数据	设置页提供入口

SDK 体积预算

模块	压缩后大小	加载时机
Core（Lifecycle + EventBus + Telemetry + ErrorTrack）	< 8KB	内联到游戏入口
Plugin.Ad	< 5KB（不含广告联盟 SDK）	首次调用 ad API 时
Plugin.Pay	< 3KB	首次调用 pay API 时
Plugin.Social	< 4KB	首次调用 social API 时
Plugin.Storage	< 2KB	首次调用 storage API 时
Plugin.Debug	< 15KB	仅开发模式加载
首屏总负担	< 8KB	—

SDK 与 runtime 模块的关系

runtime-module 编译 GamePackage 时：
1. 将 SDK Core 代码内联到游戏 entry.js 头部
2. 在 GameConfig 中声明需要的 Plugin（ad/pay/social/storage）
3. manifest.json 中记录 SDK 版本号
4. 宿主根据 manifest 决定加载哪些 Plugin chunk

游戏代码不直接引用广告联盟 SDK 或支付 SDK——这些由宿主在 iframe 外部管理。游戏只通过 sdk.ad.showRewarded() 等抽象 API 触发，具体实现对游戏透明。

4. 核心链路技术设计

4.1 AI 生成链路

架构决策：Dify（DAG 编排）+ OpenGame（代码生成）+ Java 壳（任务调度）

为什么选 Dify + OpenGame，不自研：

维度	自研	Dify + OpenGame
核心生成能力	3-6 个月	2-4 周集成验证
DAG 编排引擎	2-3 个月	Dify 开箱即用
可视化工作流 UI	1-2 个月	Dify 自带
多模型切换	2 周	Dify 原生
质量 benchmark	从零建立	OpenGame-Bench 现成
可观测性	自建	Dify 内置 trace
总周期	6-12 个月	4-6 周

为什么不选其他：

LangGraph：纯 Python 框架，无可视化 UI，运营无法参与编排
Coze：字节闭源，不可控
n8n：通用自动化，非 LLM 原生

生成任务状态机：

stateDiagram-v2
  [*] --> QUEUED: 创建任务
  QUEUED --> RUNNING: 消费消息
  RUNNING --> SUCCEEDED: 生成完成+质量通过
  RUNNING --> FAILED: 生成失败/质量不达标
  RUNNING --> TIMED_OUT: 超时(120s)
  FAILED --> QUEUED: 重试(≤2次)
  TIMED_OUT --> QUEUED: 重试(≤1次)
  SUCCEEDED --> [*]
  FAILED --> [*]: 超过重试次数
  TIMED_OUT --> [*]: 超过重试次数
  QUEUED --> CANCELED: 用户取消
  RUNNING --> CANCELED: 用户取消
  CANCELED --> [*]

性能指标：

生成 P50 耗时目标：< 60s
生成 P95 耗时目标：< 180s
生成成功率目标：≥ 85%（远期蓝图目标；MVP 验收线 ≥80%）
队列最大积压：500 任务，超过则返回 429

4.2 游戏运行时链路

三容器策略（参考抖音短视频预加载）：

[Container N-1]  [Container N]  [Container N+1]
  (销毁中)        (当前播放)      (预加载完成)

加载时序：

sequenceDiagram
  participant APP as game-studio
  participant CDN as CDN/OSS
  participant SANDBOX as iframe sandbox

  APP->>CDN: 请求 manifest.json（hash 缓存）
  CDN-->>APP: {entry, assets[], checksum}
  APP->>APP: 校验 manifest 完整性
  APP->>CDN: 并行请求 entry.js + 关键 assets
  APP->>SANDBOX: 创建 iframe（CSP + sandbox）
  APP->>SANDBOX: 注入 GameConfig + Game SDK bridge
  SANDBOX->>SANDBOX: 执行 entry.js → 初始化游戏
  SANDBOX->>APP: postMessage({type:'game_loaded'})
  APP->>APP: 隐藏 loading，展示游戏
  
  Note over APP,SANDBOX: 游玩中：SDK bridge 上报生命周期事件
  
  SANDBOX->>APP: postMessage({type:'game_complete', score})
  APP->>APP: 展示结果页 + 互动按钮

安全边界：

iframe sandbox="allow-scripts allow-same-origin"
CSP: script-src 'self'; connect-src 'none'（游戏内无网络请求）
postMessage 来源校验 + schema 校验
资源总大小 ≤ 10MB，首屏 ≤ 2MB

4.3 推荐引擎链路

MVP 推荐策略（规则 + 信号，非机器学习）：

Score = w1*quality_score + w2*freshness + w3*interaction_rate 
        - w4*skip_rate - w5*error_rate - w6*report_rate
        + bonus_new_creator + bonus_featured

信号	来源	权重方向
quality_score	telemetry 模块聚合	正向
freshness	发布时间衰减	正向（24h 内 boost）
interaction_rate	点赞+收藏+分享 / 曝光	正向
skip_rate	3s 内上滑 / 曝光	负向
error_rate	加载失败 / 试玩次数	负向（硬降权）
report_rate	举报数 / 曝光	负向（阈值触发人工审核）
bonus_new_creator	新创作者前 3 个作品	保底曝光
bonus_featured	运营精选池标记	固定加分

候选集生成：Redis Sorted Set，TTL 60s，cursor 分页。

5. 数据架构

5.1 核心实体 ER（精简）

erDiagram
  USER ||--o{ GAME_PROJECT : owns
  GAME_PROJECT ||--o{ GAME_VERSION : has
  GAME_VERSION ||--|| GAME_PACKAGE : builds_to
  GAME_VERSION ||--o{ GENERATION_TASK : generated_by
  GAME_VERSION ||--o{ REVIEW_RECORD : reviewed_in
  
  USER ||--o{ INTERACTION : performs
  INTERACTION }o--|| GAME_PROJECT : targets
  
  USER ||--o{ WALLET : has
  WALLET ||--o{ TRANSACTION : records
  
  GAME_PROJECT ||--o{ AD_SLOT : contains
  AD_SLOT ||--o{ AD_IMPRESSION : tracks

  USER {
    string id PK
    string email
    string phone
    string display_name
    string avatar_url
    string[] roles
    datetime created_at
  }

  GAME_PROJECT {
    string id PK
    string owner_id FK
    string title
    string slug
    string status
    string[] tags
    string cover_url
    float quality_score
    datetime published_at
  }

  GAME_VERSION {
    string id PK
    string project_id FK
    int version_number
    string status
    string config_json
    string package_url
    string manifest_url
    datetime created_at
  }

  GENERATION_TASK {
    string id PK
    string version_id FK
    string status
    string prompt
    string template_id
    string dify_workflow_id
    int retry_count
    int duration_ms
    string error_code
    datetime created_at
  }

  GAME_PACKAGE {
    string id PK
    string version_id FK
    string storage_path
    string checksum_sha256
    int size_bytes
    string manifest_json
    datetime built_at
  }

5.2 存储选型

数据类型	存储	理由
业务实体（用户/项目/版本/订单）	MySQL 8.0	Yudao 原生，事务一致性
游戏包/素材/封面	MinIO(本地) / 阿里云 OSS(生产)	对象存储，CDN 加速
推荐候选集/热数据	Redis 7	低延迟，Sorted Set 排序
事件流（埋点）	MySQL 分区表(MVP) → ClickHouse(增长期)	先简后扩
搜索（游戏/素材）	MySQL FULLTEXT(MVP) → Elasticsearch(增长期)	先简后扩
配置/注册	Nacos	Yudao 原生
分布式锁/限流	Redis	高性能

5.3 数据流向总览

graph LR
  STUDIO[game-studio] -->|事件上报| TEL_API[telemetry /events/batch]
  TEL_API -->|异步| MQ[RocketMQ]
  MQ -->|消费入库| MYSQL[(MySQL 事件表)]
  MYSQL -->|定时聚合| AGG[GameDailyStats]
  AGG -->|写入| REDIS_FEED[Redis 候选集]
  REDIS_FEED -->|读取| FEED[feed-module]
  FEED -->|返回| STUDIO

  AIGC[aigc-module] -->|生成产物| OSS[(MinIO/OSS)]
  OSS -->|CDN分发| CDN[CDN]
  CDN -->|加载| STUDIO

6. 技术选型决策记录

6.1 后端框架

候选	选择	理由
Yudao Cloud (Java 17 + Spring Cloud Alibaba)	✅ 选用	60%+ 后台能力开箱即用；RBAC/OAuth2/BPM/文件/通知/审计/代码生成/多租户全覆盖；社区活跃(60k+ star)；fork 二开可控
NestJS (Node.js)	❌ 放弃	v1 已验证单体可行但缺乏企业级基础设施；微服务生态弱于 Java；后台管理/工作流需从零建
Go (Kratos/go-zero)	❌ 放弃	性能好但后台基础设施缺失；RBAC/BPM/代码生成无现成方案

6.2 AI 生成引擎

候选	选择	理由
Dify(编排) + OpenGame(生成)	✅ 选用	Dify: DAG 可视化/多模型/可观测性开箱即用；OpenGame: SOTA 效果/6 阶段 pipeline/论文验证；组合 4-6 周跑通
纯自研	❌ 放弃	6-12 个月，时间不允许
LangGraph	❌ 放弃	无可视化 UI，运营无法参与编排
Coze	❌ 放弃	闭源不可控，依赖字节

6.3 前端

候选	选择	理由
Vue3 + Element Plus (admin)	✅ 选用	Yudao 官方主推，文档最全，二开友好
Vue3 + Vant (studio)	✅ 选用	移动优先组件库，适配游戏流滑动体验
React + Next.js	❌ 放弃	与 Yudao 前端生态不一致，二开成本高

6.4 数据库

候选	选择	理由
MySQL 8.0	✅ 选用	Yudao 默认，社区方案最多，迁移成本最低
PostgreSQL	❌ 放弃	虽然 JSONB/全文检索更强，但 Yudao 适配成本高

6.5 消息队列

候选	选择	理由
RocketMQ 5	✅ 选用	Yudao 默认集成，延迟消息/事务消息/死信队列完整，适合生成任务调度
Kafka	❌ 放弃	偏大数据流，运维重，MVP 阶段过度
Redis Stream	❌ 放弃	可靠性不如 RocketMQ，无死信/事务消息

6.6 游戏运行时与多渠道导出

运行时按产物复杂度分层（Tier1/2/3），不同层选不同引擎。

候选	选择	理由
自研轻量 Canvas Runtime（Tier1：Web 预览/游戏流）	✅ 选用	< 15KB，首屏极快（P75 < 3s），AI 生成纯 JS 直接可运行，平台完全控制沙箱/SDK 注入，是护城河；MVP 唯一交付层
Cocos Creator 3.8.8 + MCP（Tier2/3：复杂 2D+3D / 独立 App）	✅ 选用	一栈覆盖复杂 2D+3D+原生与小游戏导出；MCP（158 工具）可 AI 驱动、出功能快；MVP 仅至多 1 个探针 demo
Three.js	❌ 放弃	仅 web3D，与 Cocos 能力重复（已移除）
Phaser 3 全栈	❌ 放弃	纯 2D 游戏引擎，多渠道导出能力弱，小游戏适配需自研
LayaAir 全栈（运行时+编辑器+导出）	❌ 放弃	引擎过重影响游戏流加载；无 AI/MCP 生态；官方导出平台清单不含快手（旧"一键导出快手"为事实错误）
Unity	❌ 放弃	AI 适配差、启动重（7-10s），与 P75 < 3s 冲突

分层架构（Tier1 自研 Canvas + Tier2/3 Cocos-MCP）：

AI 生成 → 纯 JS/Canvas 游戏代码（Tier1，OpenGame 文生代码）
  ↓ Web 预览/游戏流
自研轻量 Runtime（iframe sandbox + SDK Core）→ 即时加载，< 15KB
  ↓ 复杂 2D/3D/独立 App（Tier2/3，远期）
Cocos Creator 3.8.8 + MCP → 官方一键导出小游戏包
  ↓ 多渠道导出枢纽 = 微信小游戏格式包
微信=引擎官方格式；抖音=自有导出接口；快手=经"微信格式兼容转换"（快手开发者工具，无专用接口）

为什么分层：

Web 预览和游戏流需要极快加载（P75 < 3s），Tier1 轻量 Runtime 满足，MVP 仅交付此层
复杂 2D/3D/原生产物（Tier2/3）需成熟引擎，复用 Cocos 而非自研（自研 3D/原生引擎工期数十人月不可行），且 MCP 使 AI 驱动可行
导出以微信小游戏格式包为统一中转，可异步离线进行，不影响实时预览体验

6.7 AI 素材生成工具链

环节	工具	类型	选用理由
图片/贴图/角色/场景	ComfyUI（自部署）	开源	节点化 workflow，支持 Flux/SDXL/ControlNet/LoRA；可训练 IP 风格模型；有 HTTP API 直接对接 Dify 节点
背景音乐/音效	Stability Audio API	商用 API	6 分钟商用级音乐生成，版权清晰（全授权训练数据），API 调用即用
角色语音/音色克隆	Fish Audio / 阿里 CosyVoice	API+开源	中文效果最佳；Fish Audio 支持 few-shot 音色克隆；CosyVoice 开源可自部署
封面/宣传图	ComfyUI（复用上面实例）	开源	同一套基础设施，不同 workflow

为什么选 ComfyUI 而不是直接调 Midjourney/DALL-E API：

ComfyUI 可训练 IP 风格 LoRA，生成风格一致的系列素材（角色/场景/UI）
节点化 workflow 可被 Dify 编排调用，形成端到端自动化
自部署无 API 限制/审查，游戏场景（武器/战斗）不被拒绝
长期成本远低于商用 API（GPU 固定成本 vs 按次付费）

6.8 内容安全

环节	工具	类型	选用理由
图片 NSFW/涉政/涉暴	safe-content-ai（自部署）+ 阿里云内容安全（兜底）	开源+商用	自部署做首道快检（免费/低延迟），高风险样本二次送阿里云确认
文本违禁/语义	阿里云文本审核	商用 API	违禁词库持续更新，语义理解强于规则匹配
音频内容	阿里云音频审核	商用 API	涉黄涉政语音识别
AI 输出风控	Dify 节点内置 Guardrails	自研规则	Prompt 注入检测 + LLM 输出 schema 校验

6.9 工具层全景图

graph TB
  subgraph AI生成工具层
    DIFY[Dify<br/>编排引擎]
    OG[OpenGame<br/>代码生成]
    COMFY[ComfyUI<br/>图片/素材生成]
    AUDIO[Stability Audio<br/>音乐生成]
    VOICE[Fish Audio/CosyVoice<br/>语音/音色]
  end

  subgraph 运行时工具层
    CANVAS_RT[自研轻量 Runtime<br/><15KB Canvas]
    LAYA_CLI[LayaAir CLI<br/>多渠道导出]
    SDK[HuijingGameSDK<br/>平台能力注入]
  end

  subgraph 安全工具层
    SAFE_IMG[safe-content-ai<br/>图片快检]
    ALI_SEC[阿里云内容安全<br/>兜底确认]
    GUARD[Dify Guardrails<br/>AI输出风控]
  end

  subgraph 商业化工具层
    CSJ[穿山甲SDK<br/>字节广告]
    GDT[优量汇SDK<br/>腾讯广告]
    WXPAY[微信支付<br/>Yudao集成]
    ALIPAY[支付宝<br/>Yudao集成]
  end

  subgraph 基础设施工具层
    YUDAO[Yudao Cloud<br/>RBAC/BPM/文件/通知]
    NACOS[Nacos<br/>注册/配置]
    MINIO[MinIO<br/>对象存储]
    JPUSH[极光推送<br/>通知]
  end

  DIFY --> OG & COMFY & AUDIO & VOICE
  OG --> CANVAS_RT
  CANVAS_RT --> SDK
  CANVAS_RT --> LAYA_CLI
  SAFE_IMG --> ALI_SEC

7. 非功能性设计与工程治理

7.1 性能

指标	MVP 目标	正式目标	应对策略
游戏流首屏	P75 < 3s	P75 < 1.5s	CDN + 预加载 + 资源压缩 + HTTP/2
API 平均延迟	P95 < 500ms	P95 < 200ms	Redis 缓存 + 连接池 + 读写分离
生成任务耗时	P50 < 60s	P50 < 30s	Dify 并行节点 + 模型优化 + 产物缓存
并发玩家	1,000 DAU	100,000 DAU	水平扩缩 + 推荐缓存 + CDN 卸载
数据库 QPS	—	单表 < 5000 万行	超过则分区/归档，事件表 → ClickHouse

性能测试节奏：Phase 3 结束后跑首次压测（wrk/k6），上线前必须通过目标值。

7.2 可靠性与高可用

策略	实现	落地阶段
服务注册/发现	Nacos 集群（3 节点，生产）	Phase 4
熔断降级	Sentinel（Yudao 集成），per-API 规则	Phase 1 配置
数据库高可用	MySQL 主从（生产）；MVP 单节点 + 每日备份	上线前
消息可靠	RocketMQ 同步刷盘 + 死信队列 + 延迟消息	Phase 2
生成降级	LLM 不可用 → 确定性 Fallback 生成器	Phase 2
游戏加载降级	加载超时 5s → 自动跳过 + 错误记录 + 降权	Phase 3
备份恢复	MySQL: 每日全量 + binlog；OSS: 跨区域复制	Phase 1
回滚	每次部署保留前 3 个版本镜像，5 分钟内可回退	CI/CD 内置

SLO 定义：

服务	SLO	Error Budget（月）
游戏流 API	99.5% 可用	3.6 小时不可用
AI 生成	99%（允许更高失败率）	7.2 小时
支付	99.9%	43 分钟

7.3 幂等性与分布式一致性

幂等性设计

场景	问题	方案
用户重复点击"生成"	重复创建生成任务	前端防抖 + 后端 idempotency_key（Redis 5min 去重）
MQ 重复消费	同一消息处理多次	每条消息携带 message_id，消费前查 Redis 已处理集合
支付回调重复	重复入账	订单状态机 + 乐观锁（version 字段），已完成的订单不可重入
发布重复提交	重复创建审核流程	project_version 唯一约束 + 状态前置校验

分布式事务

原则：尽量避免分布式事务，用最终一致性 + 补偿替代。

场景	涉及模块	方案
生成成功 → 写版本 + 扣积分	aigc → project + pay	本地事务写版本 + MQ 通知扣积分；扣积分失败 → 补偿（标记版本为待支付）
发布审核通过 → 上架 + 刷新 feed	bpm → project + feed	审核通过本地事务写状态 + MQ 广播 feed 刷新缓存
支付成功 → 发货 + 通知	pay → project/ad + community	支付本地事务 + MQ 事件扇出（各模块独立消费）

兜底机制：定时任务扫描"中间态"超 5 分钟的记录 → 重试或告警。

7.4 安全

层面	措施	落地阶段
接入防护	WAF（阿里云/Cloudflare）+ DDoS 高防	上线前
传输	全站 HTTPS + HSTS + TLS 1.3	Phase 1
鉴权	OAuth2 + JWT + Refresh Token 轮换（7天/30天）	Phase 1
权限	RBAC + DataPermission（创作者只看自己的项目/资产）	Phase 1
游戏沙箱	iframe sandbox + CSP + postMessage 来源+Schema 校验	Phase 2
内容安全	Prompt 检测 + 图片检测 + AI 输出校验 + 音频检测	Phase 2
注入防护	Prompt 注入 + SQL 参数化 + XSS 过滤 + SSRF 白名单	Phase 1
密钥管理	Nacos 加密 / K8s Secret（生产）；密钥 90 天轮换	Phase 1
审计	全操作日志 + 180 天保留 + 关键操作实时告警	Phase 1
渗透测试	上线前一次 + 每季度一次	上线前/季度

7.5 可观测性

graph LR
  APP[业务服务] -->|Metrics| PROM[Prometheus]
  APP -->|Traces| JAEGER[Jaeger]
  APP -->|Logs| LOKI[Loki/ELK]
  APP -->|Errors| SENTRY[Sentry]
  PROM --> GRAFANA[Grafana Dashboard]
  JAEGER --> GRAFANA
  LOKI --> GRAFANA
  GRAFANA --> ALERT[告警通道<br/>飞书/钉钉/短信]

日志规范：

规则	说明
格式	JSON 结构化（timestamp / level / trace_id / span_id / module / message / context）
级别	ERROR（需人处理）/ WARN（可能需关注）/ INFO（关键链路）/ DEBUG（开发用）
脱敏	Token/密码/手机号/身份证 → 脱敏后输出（`138****1234`）
trace_id	Gateway 入口注入，全链路透传（含 Dify/OpenGame 调用）
保留	ERROR/WARN: 90 天；INFO: 30 天；DEBUG: 仅 dev 环境

告警升级链：

级别	条件	通知方式	响应时间
P0 Critical	服务不可用 / 数据丢失 / 安全事件	电话 + 短信 + 群	5 分钟
P1 High	5xx > 2% / 生成成功率 < 70% / 支付异常	短信 + 群	15 分钟
P2 Medium	P95 > 800ms / MQ 积压 > 500 / 错误率上升	群通知	1 小时
P3 Low	非核心模块降级 / 日志异常增长	群通知	工作时间处理

7.6 工程协作与 DevOps

CI/CD Pipeline

graph LR
  DEV[开发推送] --> LINT[代码检查<br/>Checkstyle/ESLint]
  LINT --> TEST[自动化测试<br/>单元+集成]
  TEST --> BUILD[构建镜像<br/>Docker Build]
  BUILD --> SCAN[安全扫描<br/>依赖漏洞/镜像扫描]
  SCAN --> DEPLOY_STG[部署 Staging]
  DEPLOY_STG --> SMOKE[冒烟测试]
  SMOKE --> APPROVE[人工审批<br/>（prod 才需要）]
  APPROVE --> DEPLOY_PROD[滚动部署 Prod]
  DEPLOY_PROD --> VERIFY[健康检查+流量验证]
  VERIFY --> DONE[完成]
  VERIFY -->|失败| ROLLBACK[自动回滚]

工具选型：

CI：GitHub Actions（或 GitLab CI，根据代码托管平台）
镜像仓库：阿里云 ACR / Harbor（自建）
部署：Docker Compose（MVP）→ K8s ArgoCD（正式）
安全扫描：Trivy（镜像）+ Snyk（依赖）

分支策略

main          ← 始终可部署，保护分支
  └── develop ← 集成分支，CI 通过才能合入
       ├── feature/xxx  ← 功能开发
       ├── fix/xxx      ← Bug 修复
       └── release/x.y  ← 发版分支（冻结后只修 bug）

规则	说明
main 保护	禁止直推，必须 PR + 至少 1 人 review + CI 通过
feature 命名	`feature/{module}-{brief}`，如 `feature/aigc-dify-integration`
commit 规范	Conventional Commits（`feat:`/`fix:`/`chore:`/`docs:`）
PR 大小	单次 < 500 行变更，超过必须拆分

环境管理

环境	用途	数据	部署方式
local	开发者本机	Docker Compose + seed 数据	手动
dev	联调/集成	共享数据库（可随时重置）	push develop 自动部署
staging	预发布验证	生产数据脱敏子集	merge to release 自动部署
prod	线上	真实数据	审批后滚动部署

数据库迁移

工具	Flyway（Java 标准，Yudao 已集成）
文件命名	`V{版本号}__{描述}.sql`，如 `V1.0.0__create_game_project.sql`
规则	只新增、不回滚（需回滚则写新迁移补偿）；DDL 和 DML 分开
检查	CI 阶段自动执行 `flyway validate`，不通过则阻断
大表变更	pt-online-schema-change 或 gh-ost，不锁表

7.7 API 契约与版本管理

API 版本策略

方式	说明
URL Path 版本	`/api/v1/feed/list`，大版本不兼容时升 v2
向后兼容	新增字段不算 breaking；删除/重命名字段 = 新版本
并行期	新版本上线后，旧版本保留至少 3 个月
废弃通知	Response Header `Deprecation: true` + `Sunset: date`

服务间契约

机制	说明
Feign 接口定义	每个模块的 `-api` 包声明 Feign 接口 + DTO，消费方引用此包
契约测试	Provider 端 Pact 验证 + Consumer 端 Stub 测试（P2，正式阶段引入）
变更通知	API 变更必须在 PR 描述中标注影响的消费方

事件 Schema 演进

规则	说明
版本号	每个事件类型带 schema_version 字段（如 `game_play_start.v2`）
向后兼容	新增字段给默认值；老版本消费者忽略未知字段
不兼容变更	新事件名（如 `game_play_start_v3`），老版本并行消费直到下线
Schema Registry	MVP 用文档管理；正式阶段引入 Schema Registry（如 Confluent 兼容方案）

7.8 测试策略

                    ┌─────────────────┐
                    │   E2E 测试       │  少（核心链路 5-10 条）
                    │   Playwright     │
                ┌───┴─────────────────┴───┐
                │      集成测试            │  中（模块间 + 外部依赖）
                │   Testcontainers        │
            ┌───┴─────────────────────────┴───┐
            │          单元测试                 │  多（业务逻辑/工具类）
            │       JUnit 5 + Mockito          │
            └─────────────────────────────────┘

层级	覆盖范围	工具	运行时机	目标覆盖率
单元测试	Service/Util/Validator	JUnit 5 + Mockito	每次 push	核心逻辑 > 80%
集成测试	Controller + DB + MQ + 外部 API	Testcontainers（MySQL/Redis/RocketMQ）	PR merge	核心链路 100%
E2E 测试	前端 → 后端 → DB 全链路	Playwright（前端）+ RestAssured（API）	部署 staging 后	核心 happy path
性能测试	API 吞吐/延迟/并发	k6 / wrk	Phase 3 结束 + 上线前	满足 §7.1 指标
安全测试	OWASP Top 10 / 渗透	ZAP + 人工渗透	上线前 + 季度	无 Critical/High

7.9 灰度发布与 Feature Flag

灰度发布

策略	实现	适用场景
按百分比	Gateway 路由权重（5% → 20% → 50% → 100%）	新版本服务全量前验证
按用户标签	Gateway Header 匹配（内部用户/种子用户/创作者等级）	新功能定向开放
按地域	Gateway IP/地域规则	区域性功能或合规要求
回滚	路由权重调回 0% + 旧版本容器不销毁	发现异常 5 分钟内回退

Feature Flag

工具	Nacos 配置中心（MVP）→ Unleash/LaunchDarkly（正式）
用法	代码中 `if (featureFlag.isEnabled("new-recommend-algo")) { ... }`
管理	admin 后台可开关，无需重新部署
清理	Feature Flag 上线稳定 2 周后必须删除，不留死代码

7.10 扩展性设计

扩展方向	预留机制
新玩法模板	模板注册（Dify Workflow + 模板 JSON Schema + 示例 Prompt）
新 LLM 供应商	Dify 原生多模型管理 + 模型 A/B 测试
新广告联盟	AdProvider SPI 接口
新支付渠道	PayChannel SPI 接口（Yudao 原生支持）
新分发渠道	ConversionAdapter SPI 接口
单体→微服务	Spring Profile 控制模块加载 + Nacos 路由
MySQL→ClickHouse	事件表 DAO 抽象 + 双写期
SDK 版本升级	manifest 中声明 SDK 版本 + 向后兼容 + 运行时按版本加载
多端适配（小程序壳/APP壳）	SDK + 宿主分离；宿主可替换为微信/抖音小程序容器
Prompt 版本管理	Dify 内置工作流版本 + 环境隔离（draft/published）
生成产物缓存	相同 Prompt hash → 缓存命中 → 跳过 LLM 调用（节省成本/加速）

8. 关键技术风险与应对

#	风险	概率	影响	应对策略	降级方案
1	LLM 调用不稳定（超时/限流/幻觉）	高	高	Dify 内置重试+熔断；多供应商切换	确定性 Fallback 生成器
2	生成游戏质量不可控	高	高	JSON Schema 强校验 + 可玩性自动测试 + 模板约束	质量不达标不入库
3	游戏沙箱逃逸	低	极高	CSP + sandbox + 无网络 + postMessage 校验	检测到异常立即销毁 iframe
4	OpenGame 社区停更	中	中	fork 维护 + 核心 pipeline 逻辑简单可自维护	退化为纯 Dify + 模板生成
5	Dify 版本升级不兼容	中	中	锁定版本 + 壳层隔离	自部署可控
6	广告联盟审核不通过	中	高	提前申请资质 + 内容合规前置	延迟广告上线，先做订阅/B端
7	多模块单体启动内存不足	低	中	8GB+ JVM + 模块懒加载	拆分 2-3 个 JVM
8	MQ 重复消费导致数据不一致	中	高	消息幂等消费（§7.3）	定时任务修复 + 告警
9	分布式事务部分失败	中	高	最终一致性 + 补偿机制（§7.3）	中间态扫描 + 人工介入
10	CI/CD 流水线瘫痪	低	中	多 runner + 镜像缓存	手动部署备案流程
11	第三方 SDK 数据泄露	低	极高	广告/支付 SDK 宿主侧隔离 + 最小权限	紧急下线第三方 SDK

9. 演进路线

gantt
  title v2.0 实施路线
  dateFormat YYYY-MM-DD
  axisFormat %m/%d

  section Phase 1：基座（2周）
  Fork yudao-cloud + 本地跑通全栈    :p1a, 2026-06-09, 3d
  创建 13 个 game-module 骨架         :p1b, after p1a, 3d
  Dify + OpenGame Docker 部署         :p1c, after p1a, 3d
  game-admin fork + game views 骨架   :p1d, after p1a, 4d
  game-studio 项目初始化              :p1e, after p1a, 3d
  Docker Compose 全栈可启动           :p1f, after p1c, 3d

  section Phase 2：创作链路（3周）
  project 模块 CRUD + 状态机          :p2a, after p1f, 4d
  aigc→Dify→OpenGame 集成验证         :p2b, after p1f, 5d
  runtime 编译+打包+预览交付          :p2c, after p2b, 4d
  studio 创作工作台 UI                :p2d, after p2a, 7d
  生成质量门禁（Schema+可玩性）       :p2e, after p2c, 3d

  section Phase 3：分发链路（3周）
  feed 推荐引擎 + API                 :p3a, after p2e, 5d
  studio 游戏流 UI + 三容器预加载     :p3b, after p3a, 5d
  compliance 内容安全 + 审核(BPM)     :p3c, after p2e, 5d
  telemetry 事件摄取 + 看板           :p3d, after p3a, 5d
  互动（点赞/收藏/分享/举报）         :p3e, after p3b, 3d

  section Phase 4：变现+部署（2周）
  ad 广告位定义 + 联盟 SDK 集成       :p4a, after p3e, 5d
  trade 创作者钱包 + 分成结算         :p4b, after p4a, 4d
  pay 积分充值（微信/支付宝）         :p4c, after p4a, 3d
  deploy 文档 + healthcheck + seed    :p4d, after p4b, 3d
  全链路冒烟测试                      :p4e, after p4d, 2d

  section Phase 5：打磨+上线（1周）
  性能优化（CDN/缓存/预加载）         :p5a, after p4e, 3d
  安全加固 + 渗透测试                 :p5b, after p4e, 3d
  灰度发布 + 种子用户内测             :p5c, after p5a, 4d

总周期：约 11 周（2.5 个月），产出完整 MVP 闭环。

10. 成本估算

10.1 基础设施成本（MVP 阶段，月度）

资源	规格	月费估算
云服务器（业务）	4C16G × 2	¥1,200
云服务器（AI引擎）	4C16G × 1（Dify + OpenGame）	¥600
MySQL RDS	2C8G	¥400
Redis	2G	¥200
OSS + CDN	100GB 存储 + 500GB 流量	¥300
LLM API 调用	~10,000 次/月 × ¥0.1	¥1,000
域名 + SSL	—	¥100
监控/备份/冗余	Prometheus/Grafana/Sentry + 备份	¥500
合计		~¥4,300/月（上限 < 5000 元/月，与投资人版核算口径一致）

10.2 团队配置（建议最小）

角色	人数	职责
后端工程师	2	yudao 二开 + 业务模块 + API
前端工程师	1	game-studio + game-admin 二开
AI/生成工程师	1	Dify 编排 + OpenGame 集成 + 质量
产品/运营	1	PRD + 种子用户 + 审核
合计	5 人

11. 附录

11.1 术语表

术语	含义
GameConfig	游戏配置 JSON，描述玩法/关卡/角色/规则
GamePackage	可运行的游戏包（代码 + 资源 + manifest）
DAG	有向无环图，用于描述生成工作流节点编排
Game Skill	OpenGame 的经验积累机制，类似 few-shot 模板
quality_score	基于玩家行为信号聚合的游戏质量评分
Feed	游戏流推荐列表
Manifest	游戏包描述文件（入口/资源列表/hash/大小）

11.2 决策记录索引

决策	文档位置
模块划分（13 个业务模块）	`技术架构与模块.md`
AI 引擎选型（Dify + OpenGame）	本文 §6.2

11.3 后续文档规划

文档	受众	状态
系统概要设计-技术决策版（本文）	CTO/技术合伙人	✅ 完成
系统概要设计-投资人版	投资人/融资	✅ 完成
系统概要设计-开发团队版	工程师	✅ 完成
接口契约文档	前后端工程师	Phase 2 产出
数据库设计文档	后端工程师	Phase 1 产出

58 KiB Raw Blame History Unescape Escape