games-development-ai/docs/architecture/系统概要设计-开发团队版.md

绘境AI游戏生态平台 — 系统概要设计（开发团队版）

文档编号：HJ-ARCH-003 版本：v2.0 受众：全栈工程师 / 前端工程师 / AI 工程师 / QA 定位：开发者日常参考手册——环境搭建、模块职责、编码规范、联调协议、提交流程 生成时间：2026-06-07 前置阅读：

• 技术决策版（架构全貌）：系统概要设计-技术决策版.md
• 技术架构与模块（Doc B，13 模块）：技术架构与模块.md

---

1. 快速上手

1.1 仓库结构

绘境AI 项目由 3 个独立 Git 仓库组成：

game-cloud/        后端（Yudao Cloud fork + 游戏业务模块）
game-admin/        管理后台前端（yudao-ui-admin-vue3 fork）
game-studio/       产品端前端（Vue3 + Vant，创作者+玩家）

1.2 本地环境要求

工具	版本	用途
JDK	17+	后端编译运行
Maven	3.9+	后端依赖管理
Node.js	20+	前端构建
pnpm	9+	前端包管理
Docker & Docker Compose	24+	中间件 + AI 引擎
Git	2.40+	版本控制
IDE	IntelliJ IDEA（后端）/ VS Code（前端）	开发

1.3 一键启动（本地开发）

# 1. 启动中间件（MySQL/Redis/Nacos/RocketMQ/MinIO）
cd game-cloud/deploy
docker compose -f docker-compose.middleware.yml up -d

# 2. 启动 AI 引擎（Dify + OpenGame + ComfyUI）
docker compose -f docker-compose.ai.yml up -d
# 注意：ComfyUI 需要 GPU（或 CPU 模式启动，速度慢 10x）
# 无 GPU 时可跳过 ComfyUI，图片生成走 mock 或外部 API

# 3. 初始化数据库
cd game-cloud
mvn flyway:migrate -pl game-module-system-biz  # 基础表
mvn flyway:migrate -pl game-module-project-biz # 业务表
# ... 各模块依次执行

# 4. 导入 seed 数据（开发用测试账号/模板/示例游戏）
mysql -u root -p huijing_dev < deploy/sql/seed-dev.sql

# 5. 启动后端（单体模式，所有模块一个进程）
mvn spring-boot:run -pl game-server

# 6. 启动管理后台前端
cd game-admin && pnpm install && pnpm dev

# 7. 启动产品端前端
cd game-studio && pnpm install && pnpm dev

启动完成后：

• 管理后台：http://localhost:1024（admin / admin123）
• 产品端：http://localhost:3000
• 后端 API：http://localhost:48080
• Nacos 控制台：http://localhost:8848/nacos（nacos / nacos）
• Dify：http://localhost:3001
• ComfyUI：http://localhost:8188
• MinIO：http://localhost:9001（minioadmin / minioadmin）
• OpenGame Agent：http://localhost:8100

---

2. 后端模块地图

2.1 目录结构

game-cloud/
├── game-gateway/                         # 网关（路由/限流/鉴权/CORS）
├── game-server/                          # 单体启动入口（引用所有模块）
├── game-framework/                       # 通用框架扩展
│   ├── game-common/                      #   通用工具/常量/异常定义
│   ├── game-spring-boot-starter-security/#   安全扩展（匿名 token）
│   ├── game-spring-boot-starter-mq/      #   MQ 消息定义 + 幂等消费基类
│   └── game-spring-boot-starter-test/    #   测试基类 + Testcontainers 配置
│
├── game-module-system/                   # 【Yudao】用户/权限/租户/OAuth2/短信
├── game-module-infra/                    # 【Yudao】文件/任务/日志/代码生成
├── game-module-bpm/                      # 【Yudao】工作流（Flowable）
│
├── game-module-project/                  # 游戏项目生命周期
│   ├── game-module-project-api/          #   DTO + Feign 接口 + 枚举
│   └── game-module-project-biz/          #   实现
│       ├── controller/admin/             #     后台接口（运营/管理员用）
│       ├── controller/app/              #     产品端接口（创作者用）
│       ├── service/                      #     业务逻辑
│       ├── dal/mysql/                    #     Mapper + DO
│       ├── convert/                      #     DO ↔ VO 转换器
│       └── job/                          #     定时任务
│
├── game-module-aigc/                     # AI 生成引擎
│   ├── game-module-aigc-api/
│   └── game-module-aigc-biz/
│       ├── controller/app/              #     创作者发起生成
│       ├── controller/admin/            #     模板/工作流管理
│       ├── service/task/                #     生成任务调度（MQ）
│       ├── service/dify/                #     Dify HTTP Client
│       ├── service/template/            #     模板引擎
│       ├── service/quality/             #     质量评估
│       └── mq/consumer/                 #     MQ 消费者（任务执行）
│
├── game-module-runtime/                  # 运行时/包构建/转换
│   ├── game-module-runtime-api/
│   └── game-module-runtime-biz/
│       ├── controller/app/              #     预览包交付端点（按版本）
│       ├── controller/admin/            #     包管理/转换管理
│       ├── service/compiler/            #     GameConfig → 可运行 Web 包（自研轻量 Runtime, <15KB）
│       ├── service/package/             #     包存储/版本化/checksum/CDN 刷新
│       └── service/conversion/          #     多渠道导出（微信格式包为枢纽）
│           ├── WechatPackager.java      #       产出微信小游戏格式包（导出枢纽）
│           ├── DouyinAdapter.java       #       抖音自有导出接口适配
│           └── KuaishouAdapter.java     #       快手：微信格式兼容转换（无专用接口）
├── game-module-feed/                     # 游戏流/推荐/互动
├── game-module-telemetry/                # 遥测/数据
├── game-module-pay/                      # 支付/订阅
├── game-module-trade/                    # 结算/钱包
├── game-module-community/                # 社区/通知
├── game-module-ip/                       # IP/素材/版权
├── game-module-compliance/               # 合规/安全
├── game-module-biz/                      # B端业务
├── game-module-ad/                       # 广告引擎
│
└── deploy/
    ├── docker-compose.middleware.yml      # 中间件
    ├── docker-compose.ai.yml             # Dify + OpenGame
    ├── docker-compose.yml                # 全栈（生产/staging）
    ├── sql/                              # 初始化 + seed
    ├── nacos/                            # Nacos 配置导入
    └── Dockerfile                        # 业务服务镜像

2.2 模块职责速查

模块	一句话	对外暴露	主要依赖
project	项目/版本/草稿/发布/审核	/app/project/**, /admin/project/**	bpm, system, infra
aigc	AI 生成任务调度 + Dify 调用	/app/aigc/**, /admin/aigc/**	project, compliance, Dify, OpenGame
runtime	编译打包 + 资源交付 + 小游戏转换	/app/runtime/**, /admin/runtime/**	project, OSS, CDN
feed	推荐列表 + 互动 + 分享	/app/feed/**, /admin/feed/**	project, telemetry, Redis
telemetry	事件摄取 + 聚合 + 看板	/app/telemetry/**, /admin/telemetry/**	MQ, MySQL
pay	充值/订阅/内购订单	/app/pay/**, /admin/pay/**	微信/支付宝 SDK
trade	广告分成/创作者钱包/提现	/app/trade/**, /admin/trade/**	pay, ad, telemetry
community	评论/关注/排行/通知	/app/community/**, /admin/community/**	project, system
ip	素材市场/版权/IP	/app/ip/**, /admin/ip/**	project, trade, compliance
compliance	内容安全/审核/RBAC	内部调用为主	外部安全 API
biz	B端定制/教育/文旅	/admin/biz/**	project, aigc, trade
ad	广告位/联盟对接/上报	/app/ad/**, /admin/ad/**	runtime, trade, telemetry

2.3 API 路径规范

/app/**    → 产品端接口（game-studio 调用），需要用户 Token
/admin/**  → 管理后台接口（game-admin 调用），需要管理员权限

URL 格式：/{端}/{模块}/{资源}/{动作}

示例：

POST   /app/aigc/generate          # 创作者发起生成
GET    /app/feed/list              # 游戏流列表
POST   /app/feed/interaction       # 点赞/收藏
GET    /app/project/my             # 我的项目
POST   /admin/project/review       # 审核操作
GET    /admin/telemetry/dashboard  # 运营看板

---

3. 前端模块地图

3.1 game-admin（管理后台）

game-admin/
├── src/
│   ├── api/game/                # 游戏业务 API 定义
│   │   ├── project.ts           #   项目管理
│   │   ├── review.ts            #   审核
│   │   ├── template.ts          #   模板管理
│   │   ├── feed.ts              #   推荐管理
│   │   ├── telemetry.ts         #   数据看板
│   │   ├── creator.ts           #   创作者管理
│   │   └── content-safety.ts    #   内容安全
│   ├── views/game/              # 游戏业务页面（二开新增）
│   │   ├── project/             #   项目列表/详情
│   │   ├── review/              #   审核队列
│   │   ├── template/            #   模板 CRUD
│   │   ├── feed/                #   精选池/降权
│   │   ├── telemetry/           #   数据看板
│   │   ├── creator/             #   创作者管理
│   │   └── content-safety/      #   违规/封禁
│   └── views/system/            # Yudao 原生（尽量不改）
├── .env.development             # 本地 API 地址
└── vite.config.ts

开发规范：

• 新增页面放 views/game/ 下，不改 Yudao 原生 views
• API 定义统一放 api/game/，使用 Yudao 的 request 封装
• 使用 Yudao 的 CRUD 组件（XTable / XForm / Dialog）保持风格一致

3.2 game-studio（产品端）

game-studio/
├── src/
│   ├── views/
│   │   ├── auth/                # 登录/注册
│   │   ├── feed/                # 游戏流（首页）
│   │   ├── play/                # 试玩/分享页
│   │   ├── creator/             # 创作工作台
│   │   │   ├── ProjectList.vue
│   │   │   ├── AssetWorkspace.vue    # 资产管理
│   │   │   ├── GameDesigner.vue      # 游戏设计/组装
│   │   │   ├── GenerationStatus.vue
│   │   │   ├── PreviewPlay.vue
│   │   │   └── PublishFlow.vue
│   │   └── profile/             # 创作者中心/数据
│   ├── components/
│   │   ├── game-runtime/        # 游戏运行时容器
│   │   │   ├── GameContainer.vue
│   │   │   ├── GameLoader.vue
│   │   │   └── DebugPanel.vue   # 调试面板（开发模式）
│   │   └── shared/
│   ├── api/                     # 后端 API 对接
│   ├── stores/                  # Pinia 状态
│   ├── sdk/                     # HuijingGameSDK 源码
│   │   ├── core/
│   │   │   ├── lifecycle.ts
│   │   │   ├── event-bus.ts
│   │   │   ├── telemetry.ts
│   │   │   └── error-track.ts
│   │   └── plugins/
│   │       ├── ad.ts
│   │       ├── pay.ts
│   │       ├── social.ts
│   │       └── storage.ts
│   └── router/
├── public/
└── vite.config.ts

---

4. 编码规范

4.1 后端（Java）

规则	说明
包命名	cn.huijing.game.module.{模块名}.{层}
类命名	Controller/Service/Mapper/DO/VO/DTO 后缀一致
DO	数据库映射对象，字段与数据库一一对应
VO	视图对象，面向前端，字段可裁剪/组合
DTO	模块间传输对象，定义在 -api 包中
异常处理	使用 Yudao 的 ServiceException + 错误码枚举
日志	@Slf4j，关键链路 INFO，错误 ERROR（含 trace_id）
注释	类注释 + 复杂方法注释（中文），字段注释
SQL	禁止 select *，必须指定字段；大表查询必须有索引
事务	@Transactional 只加在 Service 层，范围尽量小

错误码分配：

1-001-000-000 ~ 1-001-999-999  → system 模块
1-002-000-000 ~ 1-002-999-999  → infra 模块
1-100-000-000 ~ 1-100-999-999  → project 模块
1-101-000-000 ~ 1-101-999-999  → aigc 模块
1-102-000-000 ~ 1-102-999-999  → runtime 模块
1-103-000-000 ~ 1-103-999-999  → feed 模块
... 每个模块一个段，避免冲突

4.2 前端（TypeScript/Vue）

规则	说明
组件命名	PascalCase 单文件组件，如 GameContainer.vue
API 文件	按模块一个文件，函数名 = {HTTP方法}{资源}{动作}
状态管理	Pinia，按功能域拆 store
样式	game-admin 用 Element Plus 变量；game-studio 用 Vant + CSS Variables
类型	严格 TypeScript，禁止 any（除非有充分理由）
请求	统一使用封装的 request 实例，自动处理 Token/刷新/错误

4.3 SDK（TypeScript）

规则	说明
零依赖	SDK 不引入任何第三方库
体积预算	Core < 8KB（压缩后），每个 Plugin < 5KB
异步安全	所有对外 API 不返回 Promise（fire-and-forget）
错误隔离	每个 Plugin 内部 try-catch，不向游戏抛异常
版本兼容	新版本只增字段/方法，不删不改已有签名

---

5. Git 协作流程

5.1 分支策略

main          ← 始终可部署，保护分支
  └── develop ← 集成分支
       ├── feature/{module}-{brief}  ← 功能开发
       ├── fix/{module}-{brief}      ← Bug 修复
       └── release/x.y.z            ← 发版

5.2 日常开发流程

# 1. 从 develop 创建分支
git checkout develop && git pull
git checkout -b feature/aigc-dify-integration

# 2. 开发 + 本地测试
# ...编码...
mvn test -pl game-module-aigc-biz   # 跑单元测试

# 3. 提交（Conventional Commits）
git add .
git commit -m "feat(aigc): integrate Dify workflow API for game generation"

# 4. 推送 + 创建 PR
git push -u origin feature/aigc-dify-integration
# 在 GitHub/Gitea 创建 PR → develop

# 5. Review + CI 通过 → Merge

5.3 Commit 规范

<type>(<scope>): <subject>

type:   feat / fix / refactor / docs / test / chore / perf
scope:  模块名（aigc / project / feed / studio / admin / sdk ...）
subject: 动词开头，简明描述（中英文均可）

示例：

feat(aigc): integrate Dify workflow API for game generation
fix(feed): cursor pagination returns duplicate games
refactor(sdk): extract telemetry buffer into standalone module
test(project): add integration test for publish flow

5.4 PR 规范

## 变更内容
- [ ] 新功能 / Bug 修复 / 重构

## 影响范围
- 影响的模块：
- 影响的 API（如有变更）：
- 数据库迁移（如有）：

## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过（如涉及 DB/MQ）
- [ ] 本地手工验证

## 截图/录屏（如有 UI 变更）

---

6. 联调协议

6.1 前后端联调

规则	说明
接口文档	后端 Swagger（Knife4j），地址 http://localhost:48080/doc.html
Mock	接口未就绪时，前端使用 vite-plugin-mock 本地 mock
联调环境	dev 环境共用一套后端，前端各自本地连 dev
问题跟踪	联调 bug 提 Issue，标签 联调 + 模块名
契约对齐	后端先写 -api 包的 VO/DTO，前端据此定义 TypeScript 类型

6.2 后端与 AI 引擎联调

组件	地址	联调方式
Dify	http://localhost:3001	后端 DifyClient 调用 Workflow API，Dify UI 可查看执行日志
OpenGame	http://localhost:8100	Dify 节点调用，或直接 HTTP 测试 /generate 端点

6.3 SDK 与宿主联调

game-studio（宿主）启动开发模式：
  → iframe 加载本地游戏包（dev server）
  → SDK postMessage 通信可在 DevTools Console 观察
  → DebugPanel 组件展示实时事件流

---

7. 测试指南

7.1 后端测试

# 单元测试（快，无外部依赖）
mvn test -pl game-module-aigc-biz

# 集成测试（需要 Docker，Testcontainers 自动启动 MySQL/Redis）
mvn verify -pl game-module-project-biz -Pintegration

# 全模块测试
mvn test

测试文件规范：

• 单元测试：src/test/java/.../XxxServiceTest.java
• 集成测试：src/test/java/.../XxxServiceIntegrationTest.java
• 测试基类：继承 game-spring-boot-starter-test 提供的 BaseDbUnitTest / BaseDbAndRedisUnitTest

7.2 前端测试

# game-studio 单元测试
cd game-studio && pnpm test

# game-studio E2E（需要后端运行）
pnpm test:e2e

7.3 SDK 测试

cd game-studio/src/sdk
pnpm test          # 单元测试（模拟 postMessage）
pnpm test:size     # 体积检查（Core < 8KB）

---

8. 部署流程

8.1 本地 → dev 环境

# push 到 develop 分支后自动触发 CI：
# 1. lint + test
# 2. build Docker image
# 3. push to registry
# 4. deploy to dev（docker compose pull + up）

8.2 dev → staging → prod

develop ──merge──→ release/x.y.z
                      │
                      ├── CI: build + test + image
                      ├── auto deploy → staging
                      ├── smoke test（自动）
                      ├── 人工验证
                      └── 审批 → deploy → prod（滚动更新）

8.3 回滚

# 方式一：镜像回退（推荐，< 5min）
docker compose pull  # 拉取指定 tag
docker compose up -d

# 方式二：Gateway 流量切回（灰度场景）
# Nacos 配置修改路由权重 → 旧版本 100%

---

9. 常见问题

问题	解决
本地启动报 Nacos 连接失败	先 docker compose -f docker-compose.middleware.yml up -d，等 Nacos 就绪
Flyway 迁移冲突	不要修改已存在的迁移文件；新建迁移解决
前端 API 401	Token 过期，重新登录；检查 .env 中后端地址
生成任务一直 QUEUED	检查 Dify 是否启动 + RocketMQ Consumer 是否注册
SDK postMessage 收不到	检查 iframe origin 是否在白名单；查看 Console 错误
单元测试依赖 DB	应该用 Mock；如果需要真 DB，用集成测试 + Testcontainers
PR CI 失败	看 CI 日志；最常见：代码格式（Checkstyle）/ 测试未更新

---

10. 外部工具层开发指南

10.1 工具全景

工具	本地地址	对接模块	开发者需要了解的
Dify	http://localhost:3001	aigc	编排 workflow、调试节点、查看执行日志
OpenGame	http://localhost:8100	aigc（通过 Dify 节点调用）	测试 /generate 端点、查看 6 阶段日志
ComfyUI	http://localhost:8188	aigc（图片/素材生成）	设计 workflow、导出 API JSON、对接 Dify
多渠道导出	自研转换器 / Cocos 官方导出	runtime（多渠道导出）	以微信小游戏格式包为枢纽，抖音单独适配，快手经微信格式兼容转换
safe-content-ai	http://localhost:8200	compliance	图片 NSFW 快检 API
穿山甲/优量汇 SDK	宿主侧加载	ad + SDK Plugin.Ad	广告 SDK 集成、广告位 ID 配置
Stability Audio API	远程 API	aigc（音乐生成）	API Key 配置、调用封装
Fish Audio	远程 API	aigc（语音生成）	音色克隆训练、TTS 调用

10.2 Dify 开发流程

# 本地访问 Dify
open http://localhost:3001

# 创建/编辑游戏生成 Workflow：
# 1. Dify UI → Studio → 创建 Workflow
# 2. 添加节点：LLM / HTTP(OpenGame) / HTTP(ComfyUI) / 条件分支 / 变量赋值
# 3. 测试运行 → 查看每节点输入输出
# 4. 发布为 API → 获取 workflow_id

# 后端调用方式：
# DifyClient.java 调用 POST /v1/workflows/run
# Body: { "inputs": {"prompt": "...", "template_id": "..."}, "response_mode": "blocking" }

10.3 ComfyUI 开发流程

# 本地访问 ComfyUI
open http://localhost:8188

# 设计图片生成 workflow（节点拖拽）：
# 1. 加载模型节点（Flux/SDXL/自训练 LoRA）
# 2. 配置 prompt/negative_prompt/尺寸/步数
# 3. 运行验证效果
# 4. 导出 workflow 为 JSON（Save → API Format）

# 通过 API 调用：
# POST http://localhost:8188/prompt
# Body: { "prompt": <workflow_json>, "client_id": "..." }
# 轮询 /history/{prompt_id} 获取结果图片 URL

# 在 Dify 中集成：
# Dify HTTP Request 节点 → ComfyUI /prompt 端点
# 输入：风格描述 + 角色描述 → 填入 workflow JSON 的 prompt 字段

10.4 多渠道导出

导出枢纽 = 微信小游戏格式包。Tier1 自研 Canvas 自做 adapter，Tier2/3（远期）用 Cocos Creator 官方一键导出。各渠道路径：

• 微信：引擎导出官方格式，直接上架。
• 抖音：抖音有自有导出接口，单独适配。
• 快手：无专用导出接口，标准路径 = 导出微信包 → 快手开发者工具「微信格式兼容转换」。 （注：LayaAir 官方导出平台清单不含快手，旧文档「一键导出快手」为事实错误。）

# Tier2/3（远期，Cocos Creator）官方一键导出微信小游戏包
# Cocos Creator → 构建发布 → 微信小游戏平台 → 构建

# Tier1（MVP）自研 Canvas adapter 产出微信格式包：
# runtime 模块 service/conversion 调用自研转换器 → 产出微信小游戏包

# 快手：将微信格式包导入快手开发者工具做兼容转换，无一键 CLI
# 在 Java 中调用（runtime 模块）：
# ProcessBuilder/转换服务 → 异步等待 → 上传产物到 OSS

10.5 内容安全对接

# safe-content-ai 本地部署
# docker-compose.ai.yml 已包含

# 调用方式：
# POST http://localhost:8200/api/v1/detect
# Body: { "image_url": "..." } 或 multipart file
# Response: { "nsfw_score": 0.02, "label": "safe" }

# 阈值配置（Nacos）：
# safe-content.threshold.block = 0.7    # 直接拦截
# safe-content.threshold.review = 0.4   # 送人工审核
# safe-content.threshold.pass = 0.4     # 自动通过

---

11. 速查链接

资源	地址
后端 API 文档（Swagger）	http://localhost:48080/doc.html
Nacos 控制台	http://localhost:8848/nacos
Dify 编排界面	http://localhost:3001
ComfyUI 图片生成	http://localhost:8188
OpenGame Agent	http://localhost:8100
safe-content-ai	http://localhost:8200
MinIO 文件管理	http://localhost:9001
Grafana 监控	http://localhost:3002
设计文档目录	docs/architecture/
技术架构与模块（Doc B）	docs/architecture/技术架构与模块.md
Yudao 官方文档	https://cloud.iocoder.cn
Cocos Creator 文档（Tier2/3 远期）	https://docs.cocos.com/creator/3.8/manual/
ComfyUI 文档	https://docs.comfy.org
Dify 文档	https://docs.dify.ai

---

11. 模块开发 Checklist

新增一个业务模块时，按以下清单逐项完成：

• 创建 game-module-{name}-api 和 game-module-{name}-biz 两个 Maven 模块
• 在 -api 中定义 VO / DTO / 枚举 / Feign 接口 / 错误码
• 在 -biz 中创建 controller/admin/ + controller/app/ + service/ + dal/ + convert/
• 编写 Flyway 迁移脚本 V{x.y.z}__{desc}.sql
• 在 game-server 的 pom.xml 中引入新模块依赖
• 在 Nacos 中添加模块配置（如有模块级配置）
• 编写单元测试（Service 层）
• 编写集成测试（Controller 层，含 DB）
• 在 Swagger 中验证 API 文档自动生成
• 更新本文档的模块速查表
• 通知前端同学新接口已就绪（附 Swagger 地址 + 示例 curl）