zizi 38357c3dc0 docs: 架构文档补全 5 份 P0 新档(鉴权与权限 / 产物执行沙箱 / 契约总览 / 数据模型总图 / 变现端到端,均无 AI 味散文 + mermaid,逐份审过)+ 接进架构 / 后端 / 运营三域索引

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-21 17:45:23 +00:00

10 KiB

Raw Blame History

后端域 · 服务实现视角

这是什么：绘境AI 后端域的入口文档,从"这 13 个业务模块在工程上怎么落地、怎么组织代码"这个角度切入——也就是服务实现视角(包结构、分层约定、模块归属、构建与运行形态)。它不重复回答"每个模块各自管什么领域、彼此怎么依赖",那是架构域(../架构/)的职责。 给谁看:要动后端代码的工程师、做后端 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/落地)"。两者各守一摊、互不重复,这样无论是改架构还是改代码,都只有一处需要更新。

把这套实现视角浓缩成一张图,就是下面这个分层与依赖示意:

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。那是结构权威:T-id 只增不改号、废弃打墓碑标记。本页若再列一遍模块卡片,只会制造第二份会过期的副本。
工程落地现状与代码锚点(HOW/实现现状) —— 包名怎么命名、-api/-server 怎么分、Flyway 迁移脚本放哪、错误码段怎么分配、哪些模块已经建成接入单体、哪些还是桩——这些随代码演进而变的实时状态,归 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,后端域不展开。

建设现状(随代码演进,以权威源为准):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 模块卡片(职责 / IN-OUT 边界 / 依赖)、全部 `T-{模块}-{nn}` 技术功能注册表、横切关注点 owner	要查某模块边界、某条 T-id、模块间依赖时
../架构/README.md	架构骨架:六层分层图、关键选型的"为什么"、13 模块全局依赖图	要建立后端整体技术认知、理解选型理由时
game-cloud/.agent	工程现状:目录规划、`-api`/`-server` 落地、Flyway 版本、各 Wave 建设进度、代码锚点	要实际改代码、看哪些已建成 / 还是桩时
鉴权与权限.md	鉴权权威:谁能做什么——OAuth2/RBAC、B 端 RBAC 与 C 端归属隔离两套并存模型、匿名 / 登录准入矩阵、网关双重校验纠偏	要判某端点该不该登录 / 有没有权限、写鉴权代码时
数据模型.md	数据权威:全平台数据模型总图——按 Flyway 真实表的跨域 ER、五条业务链路、软关联与数据语义坑	要动表结构、写跨模块查询、做数据侧 review 时

纪律:后端域只讲"后端的工程形状与边界",不重抄模块详设(在 13模块.md)、不重抄实现现状(在 game-cloud/.agent)、不重抄进度(在 MVP进度总账.md)。这份文档薄,是因为它的价值在于把人准确导到对的权威源,而不是再造一份会过期的副本。

10 KiB Raw Blame History Unescape Escape