99 lines
10 KiB
Markdown
99 lines
10 KiB
Markdown
# 后端域 · 服务实现视角
|
||
|
||
> **这是什么**：绘境AI 后端域的入口文档,从"**这 13 个业务模块在工程上怎么落地、怎么组织代码**"这个角度切入——也就是服务实现视角(包结构、分层约定、模块归属、构建与运行形态)。它不重复回答"每个模块各自管什么领域、彼此怎么依赖",那是架构域([../架构/](../架构/README.md))的职责。
|
||
> **给谁看**:要动后端代码的工程师、做后端 code review 的人、排查跨模块依赖的人。
|
||
> **怎么读**:本页很短,先建立"后端长什么样、边界划在哪、权威源在哪"的认知;真要写某个模块、查某个 T-id、看某条依赖,直接跳到文末三个权威源。
|
||
|
||
---
|
||
|
||
## 1. 边界声明:本域 = 13 个后端业务模块的服务实现视角
|
||
|
||
绘境AI 的后端不是一个空泛的"服务端",而是一组**边界清晰、各管一摊**的业务模块:从创作编排(studio)、无状态生成原子(aigc)、编译与多渠道发布(runtime),到项目生命周期(project)、游戏信息流(feed)、遥测数据底座(telemetry),再到支付(pay)、分账结算(trade)、社区互动(community)、素材与授权(ip)、内容安全与审核(compliance)、B 端定制(biz)、广告引擎(ad)——一共 **13 个 game 业务模块**,叠加在 Huijing Cloud(一套基于 Spring Cloud Alibaba 的开源 Java 企业级后台框架,我们 fork 它做二次开发;下文简称 Huijing)提供的用户、权限、工作流、文件等基座能力之上。
|
||
|
||
需要先讲清楚一件事:**"13 个模块各自负责什么领域、它们之间的依赖关系"属于架构域,不在本页展开**。本页只回答工程落地层面的问题——这些模块在代码里怎么摆、包怎么命名、构建产物长什么样、当前哪些已经建成在跑。换句话说,架构域回答"模块是什么(WHAT/边界)",本后端域回答"模块在工程上怎么实现(HOW/落地)"。两者各守一摊、互不重复,这样无论是改架构还是改代码,都只有一处需要更新。
|
||
|
||
把这套实现视角浓缩成一张图,就是下面这个分层与依赖示意:
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph HJ["Huijing fork — 基座(开箱即用,不属于业务)"]
|
||
SYS["system<br/>用户 / 权限 / OAuth2"]
|
||
INFRA["infra<br/>文件 / 任务 / 日志"]
|
||
BPM["bpm 工作流"]
|
||
PAYN["pay(huijing 原生)<br/>当前未接入单体"]
|
||
end
|
||
subgraph BIZ["13 个 game 业务模块 — 本域主体"]
|
||
direction LR
|
||
STU["studio 创作编排"]
|
||
AGC["aigc 生成原子"]
|
||
RT["runtime 编译/发布"]
|
||
PRJ["project 生命周期"]
|
||
FED["feed 游戏流"]
|
||
TEL["telemetry 遥测"]
|
||
TRD["trade 分账结算"]
|
||
CMU["community 社区"]
|
||
IP["ip 素材/授权<br/>(seam 寄宿 compliance)"]
|
||
CMP["compliance 安全/审核"]
|
||
BIZM["biz B端定制"]
|
||
AD["ad 广告"]
|
||
end
|
||
subgraph PKG["每个模块的两段式工程结构"]
|
||
API["-api 包<br/>枚举 / 错误码段 / 跨模块 DTO·Feign"]
|
||
SRV["-server 包<br/>controller / service / dal / convert"]
|
||
end
|
||
BIZ --> HJ
|
||
STU --> PKG
|
||
AGC --> PKG
|
||
RT --> PKG
|
||
note["全部以 jar 聚合进 huijing-server 单体运行<br/>包名统一 com.wanxiang.huijing.game.module.{模块}.{层}"]
|
||
PKG -.-> note
|
||
```
|
||
|
||
> 图里把 pay 单独画在基座里:**pay 是 Huijing 原生模块**,MVP 阶段还没接入这套单体;而 **ip 不独立建模块,而是作为一条 seam(接缝/横切能力)寄宿在 compliance 里**。这两点是后端实现上的两个特殊归属,后面"权威源"里有完整说明。
|
||
|
||
---
|
||
|
||
## 2. 为什么这份文档这么薄
|
||
|
||
一句话:**逐模块的详细设计不该有两份。** 这份后端域 README 刻意保持薄,是为了防止它变成一份和架构域内容重叠、却又各自漂移的"影子文档"——那是文档治理里最该避免的反模式(同一件事写两遍,迟早一份过期、读者不知道信哪份)。
|
||
|
||
具体来说,后端的知识天然分布在三个层次,各有各的归宿,不该在本页重抄:
|
||
|
||
- **模块边界与技术功能注册表(WHAT/结构权威)** —— 每个模块的职责、IN/OUT 边界、依赖关系,以及每一项技术功能的 `T-{模块}-{nn}` 编号(例如 `T-AGC-04` = aigc 模块的"GameConfig 结构化生成 + JSON Schema 校验"),全部集中在架构域的 [13模块.md](../架构/13模块.md)。那是结构权威:T-id 只增不改号、废弃打墓碑标记。本页若再列一遍模块卡片,只会制造第二份会过期的副本。
|
||
- **工程落地现状与代码锚点(HOW/实现现状)** —— 包名怎么命名、`-api`/`-server` 怎么分、Flyway 迁移脚本放哪、错误码段怎么分配、哪些模块已经建成接入单体、哪些还是桩——这些随代码演进而变的实时状态,归 [game-cloud/.agent](../../../game-cloud/.agent)。它跟着代码走,改了结构就改它,是后端工程现状的单一事实源。
|
||
- **横切进度与 13 模块完成度** —— 哪个模块是真实现、哪个是桩、哪个未建,以 `docs/mvp/MVP进度总账.md` 的 §2 矩阵为准(它是模块进度的单一 SoT)。
|
||
|
||
把这三层钉死在各自的权威源,本页就只需要做一件事:讲清楚"后端是什么形状、边界划在哪",然后把读者**准确地**导到该去的地方。这不是偷懒,而是治理纪律——薄,是为了不和权威源打架。
|
||
|
||
至于一条冲突该信谁,后端工程沿用架构域定下的读序:**状态 > 实现 > 结构**。也就是说,进度总账里的真/桩/未建状态最高,其次是 game-cloud 里的实现现状,最后才是 13模块.md 的结构定义;当三者表述不一致时,按这个优先级裁断。
|
||
|
||
---
|
||
|
||
## 3. 几条贯穿全后端的工程约定(速记,细节见权威源)
|
||
|
||
下面这些约定不是新规定,而是把散落在 `.agents/rules/engineering-conventions.md` 和 game-cloud `.agent` 里、且对"看懂后端长什么样"最关键的几条拎出来速记。任何一条的完整版都在那两处,本页只给指针级的一句话:
|
||
|
||
- **包名统一**:所有业务代码都在 `com.wanxiang.huijing.game.module.{模块}.{层}` 之下(例如 `...game.module.project.service`)。这条命名规则也是端前缀自动生效的前提——控制器按包路径 `**.controller.app/admin.**` 通配,Huijing 框架据此自动给上 `/app-api`、`/admin-api` 两个端前缀,控制器代码本身零改。
|
||
- **两段式模块结构**:每个 game 模块拆成 `-api` 与 `-server` 两个 Maven 子模块。`-api` 只放对外契约面——枚举、错误码常量、跨模块 DTO 与 Feign 接口;`-server` 放真正的实现——controller(app/admin 双端)、service、dal(DO/Mapper)、convert。跨模块只能依赖对方的 `-api`,不能直接碰 `-server`,这是低耦合的硬边界。
|
||
- **错误码分段**:错误码格式为 `1-{模块段}-***-***`,每个模块独占一段、互不重叠(例如 project 占段 100,Wave1 闭环脊柱 4 模块 aigc/runtime/feed/telemetry 顺延占段 101–104)。完整分配表在 `.agents/rules/engineering-conventions.md §1.3`。
|
||
- **契约不放后端**:API/DB/SDK/event 等 8 类跨端契约的单一事实源是仓根的 `contracts/`,后端只引用它、不在模块里另立一份。数据库 schema 的源在 `contracts/db-schemas/`,Flyway 执行副本放在 `huijing-server/.../db/migration/`(两边 diff 必须一致,因为 Flyway 对校验和敏感)。
|
||
- **物理形态 = 单体**:13 个模块是**逻辑划分**,物理上全部以 jar 聚合进 `huijing-server` 单体进程运行(monorepo 先行、后续再拆独立仓)。Nacos、RocketMQ 等是框架自带的远期形态,MVP 阶段并未部署。
|
||
- **技术栈基线**:Java 17 + Spring Cloud Alibaba + MySQL 8.0 + Redis 7 + Flyway;生成主线是便宜 LLM(如 DeepSeek / MiniMax)经 new-api 网关(一个 OpenAI 兼容的多模型 LLM 网关)直出,配合 SAA(Spring AI Alibaba)裸图编排——这部分的现行架构归架构域的[生成引擎](../架构/生成引擎/)子文档,不在后端域展开(另有第二条 tier2 自治富游戏轨,是待验证的 long-term premium 轨、同归该子树,MVP 未部署)。
|
||
- **两条生成线的控制面 / 管理面**:把生成线配置、观测、审计、管起来的治理层(D12 运行治理门 + 配置注册表 + 观测审计仓,其中 D12 现仅覆盖 SAA、tier2 待接),设计同样归架构域的[生成引擎/agentic集成架构.md](../架构/生成引擎/agentic集成架构.md),后端域不展开。
|
||
|
||
**建设现状(随代码演进,以权威源为准)**:13 个模块中已建成并接入单体的有 11 个(project / aigc / runtime / feed / telemetry / ad / trade / compliance / studio,以及 Wave4 的 community / biz);ip 作为 seam 寄宿 compliance、不独立建;pay 为 Huijing 原生、当前未接入单体。这个数字会变,**任何时候都以 `docs/mvp/MVP进度总账.md` §2 矩阵 + game-cloud `.agent` 为准,不以本页为准**。
|
||
|
||
---
|
||
|
||
## 4. 权威源指针:要动后端,去这三处
|
||
|
||
本页到此为止只做了"定形状、划边界"。真正要写代码、查 T-id、看依赖、对进度,请直接去下面三个权威源——它们才是各自维度上"读它 = 当前真相"的单一事实源:
|
||
|
||
| 权威源 | 它是什么维度的真相 | 什么时候去 |
|
||
|---|---|---|
|
||
| [../架构/13模块.md](../架构/13模块.md) | **结构权威**:13 模块卡片(职责 / IN-OUT 边界 / 依赖)、全部 `T-{模块}-{nn}` 技术功能注册表、横切关注点 owner | 要查某模块边界、某条 T-id、模块间依赖时 |
|
||
| [../架构/README.md](../架构/README.md) | **架构骨架**:六层分层图、关键选型的"为什么"、13 模块全局依赖图 | 要建立后端整体技术认知、理解选型理由时 |
|
||
| [game-cloud/.agent](../../../game-cloud/.agent) | **工程现状**:目录规划、`-api`/`-server` 落地、Flyway 版本、各 Wave 建设进度、代码锚点 | 要实际改代码、看哪些已建成 / 还是桩时 |
|
||
|
||
> **纪律**:后端域只讲"后端的工程形状与边界",不重抄模块详设(在 13模块.md)、不重抄实现现状(在 game-cloud/.agent)、不重抄进度(在 MVP进度总账.md)。这份文档薄,是因为它的价值在于**把人准确导到对的权威源**,而不是再造一份会过期的副本。
|