games-development-ai/.agents/rules/engineering-conventions.md

工程编码与协作硬规范

本文是绘境AI 全栈工程师 / 前端 / AI 工程师 / QA 必须遵守的硬规则。违反即不通过 review。 蒸馏来源：docs/architecture/系统概要设计-开发团队版.md（§4 编码 / §5 Git / §6 联调 / §7 测试 / §11 Checklist）、docs/architecture/系统概要设计-技术决策版.md（§7.6-7.8 工程治理）、docs/superpowers/specs/mvp-execution-spec-design.md（§8 技术约束）。 配套：可靠性/安全红线见 security-and-reliability.md；元流程见 ../workflows/ai-development-protocol.md；事实蓝图见 ../knowledge/product-and-architecture.md；模块落地手册见 ../skills/add-business-module.md。

---

1. 后端（Java）编码规范

规则	硬要求
包命名	cn.huijing.game.module.{模块}.{层}，如 cn.huijing.game.module.aigc.service。模块名小写，与 game-module-{模块} 一致
类命名	后缀严格统一：XxxController / XxxService+XxxServiceImpl / XxxMapper / XxxDO / XxxVO / XxxDTO
异常处理	业务异常一律 throw exception(错误码枚举)（Yudao ServiceException），禁止裸抛 RuntimeException、禁止吞异常返回 null
日志	类上 @Slf4j；关键链路成功 INFO、失败 ERROR，错误日志必须含 trace_id 与关键业务 ID（如 taskId/versionId）
注释	类注释 +复杂方法注释 +字段注释，一律简体中文；对外接口、错误路径、补偿逻辑必须有注释
事务	@Transactional 只加在 Service 层，范围尽量小；事务内禁止远程调用（Feign/HTTP/MQ 发送放事务提交后）

1.1 DO / VO / DTO 分层语义（不可混用）

类型	定位	所在包	约束
DO	数据库映射对象，字段与表一一对应	-biz 的 dal/dataobject	不出现在 Controller 出入参；不做业务组合
VO	视图对象，面向前端，可裁剪/组合	-biz 的 controller/.../vo	仅 Controller 层使用；分 ReqVO/RespVO
DTO	模块间传输对象（Feign 契约）	-api 包	跨模块共享，消费方引用 -api，不得引用对方 -biz

1.2 SQL 规范

• 禁止 select *，必须显式列出字段。
• 大表查询必须命中索引；WHERE/ORDER BY/JOIN 字段需有对应索引，新查询要确认执行计划。
• 分页用游标或 LIMIT；禁止深分页 LIMIT 100000,20 这类全表扫描。
• 复杂查询走 MyBatis XML，简单 CRUD 用 MyBatis-Plus。

1.3 错误码分配（每模块独占一段，禁止冲突）

错误码格式 1-{模块段}-{业务}-{细分}，各模块独占一段：

段	模块	段	模块
1-001-***-***	system	1-104-***-***（推断顺延）	telemetry
1-002-***-***	infra	1-105-***-***（推断顺延）	pay
1-100-***-***	project	1-106-***-***（推断顺延）	trade
1-101-***-***	aigc	1-107-***-***（推断顺延）	community
1-102-***-***	runtime	1-108-***-***（推断顺延）	ip
1-103-***-***	feed	1-109-***-***（推断顺延）	compliance
1-002-***-*** 之后	bpm 等 Yudao 原生沿用 Yudao 既有段	1-110 / 1-111-***-***（推断顺延）	biz / ad

源档明确给出 system/infra/project/aigc/runtime/feed 六段；其余模块按"每模块一段顺延"规则分配（推断），新增模块时在 -api 的错误码常量类登记，避免与既有段重叠。

---

2. 前端（TypeScript / Vue）编码规范

规则	硬要求
组件命名	PascalCase 单文件组件，如 GameContainer.vue
API 文件	按模块一个文件（api/game/project.ts）；函数名 = {HTTP方法}{资源}{动作}，如 getProjectList / postProjectPublish
状态管理	Pinia，按业务域拆 store（一个域一个 store，禁止 god store）
样式	game-admin 用 Element Plus 变量；game-studio 用 Vant + CSS Variables（移动优先，适配 360-430px）
类型	严格 TypeScript，禁止 any（必须用时注释说明充分理由）
请求	统一使用封装的 request 实例，自动处理 Token 注入 / Refresh 刷新 / 错误提示；禁止裸 fetch/axios

admin 二开：新页面放 views/game/、API 放 api/game/，复用 Yudao CRUD 组件（XTable/XForm/Dialog），不改 Yudao 原生 views。

---

3. SDK（HuijingGameSDK，TypeScript）编码规范

规则	硬要求
零依赖	SDK 不引入任何第三方库
体积预算	Core（Lifecycle+EventBus+Telemetry+ErrorTrack）压缩后 < 8KB；每个 Plugin < 5KB（Ad<5 / Pay<3 / Social<4 / Storage<2 / Debug<15，仅 dev）；首屏只加载 Core
异步安全	所有对外 API 不返回 Promise（fire-and-forget），零同步等待，不占游戏主线程
错误隔离	每个 Plugin 内部 try-catch，异常绝不向游戏抛；游戏主循环（requestAnimationFrame）永不被 SDK 阻塞
版本兼容	新版本只增字段/方法，不删不改已有签名；semver 管理，manifest 记录版本号

SDK 降级铁律与合规定位（同意即可用/未成年保护）属可靠性红线，详见 security-and-reliability.md。

---

4. 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	运营看板

权限在网关 +注解双重校验；/app/** 走用户 Token + DataPermission（创作者只见自己数据），/admin/** 走 RBAC。前端不可作为唯一边界，详见 security-and-reliability.md。

---

5. API 契约与版本管理

维度	规则
URL 版本	URL Path 版本 /api/v1/...，大版本不兼容才升 v2
兼容判定	新增字段不算 breaking；删除/重命名字段 = 新版本
并行期	新版本上线后，旧版本保留 ≥ 3 个月；废弃用 Header Deprecation: true + Sunset: <date>
服务间契约	每个模块 -api 包声明 Feign 接口 + DTO，消费方引用该包；API 变更必须在 PR 描述标注受影响的消费方
契约对齐	后端先写 -api 的 VO/DTO，前端据此定义 TS 类型；联调前锁定契约（见 ../skills/contract-first-development.md）

5.1 事件 Schema 版本（telemetry / MQ 事件）

规则	说明
带版本号	每个事件类型带 schema_version（如 game_play_start.v2）
向后兼容	新增字段给默认值；老消费者忽略未知字段
不兼容变更	用新事件名（如 game_play_start_v3），新老并行消费直到老版本下线

---

6. Git 协作规范

6.1 分支策略

main          ← 始终可部署，保护分支（禁直推）
  └── develop ← 集成分支，CI 通过才能合入
       ├── feature/{module}-{brief}   ← 功能开发（MVP 期可用 feature/{ws}-{module}-{brief}）
       ├── fix/{module}-{brief}       ← Bug 修复
       └── release/x.y.z              ← 发版（冻结后只修 bug）

6.2 Commit 规范（Conventional Commits）

<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。

6.3 PR 规范

• 单次 < 500 行变更，超过必须拆分。
• 至少 1 人 review + CI 通过（main 强制）才能合入。
• PR 描述模板要点：

区块	必填内容
变更内容	新功能 / Bug 修复 / 重构
影响范围	影响的模块 / 影响的 API（如变更）/ 数据库迁移（如有）
测试	单元测试通过 / 集成测试通过（涉及 DB/MQ）/ 本地手工验证
截图	UI 变更附截图或录屏

---

7. 测试规范（测试金字塔）

层级	覆盖范围	工具	运行时机	目标覆盖率
单元	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 末 + 上线前	满足性能指标
安全	OWASP Top 10 / 渗透	ZAP + 人工渗透	上线前 + 季度	无 Critical/High

硬约束：

• 测试文件命名：单元测试 XxxServiceTest.java，集成测试 XxxServiceIntegrationTest.java。
• 测试基类：继承 game-spring-boot-starter-test 的 BaseDbUnitTest / BaseDbAndRedisUnitTest。
• 单测应 Mock 外部依赖；需要真 DB 的场景一律用集成测试（Testcontainers），不要让单测连真库。

---

8. 数据库迁移规范（Flyway）

规则	硬要求
命名	V{版本号}__{描述}.sql，如 V1.0.0__create_game_project.sql
只增不回滚	已合入的迁移文件禁止修改；需回滚则写新的补偿迁移
DDL/DML 分开	结构变更与数据变更拆成不同迁移文件
CI 阻断	CI 阶段执行 flyway validate，不通过则阻断合入
大表变更	用 gh-ost / pt-online-schema-change 不锁表

---

9. 模块开发 Checklist

新增一个业务模块时按下列清单逐项完成（完整 playbook 见 ../skills/add-business-module.md）：

• 创建 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（Knife4j）验证 API 文档自动生成
• 更新模块速查表，并通知前端接口就绪（附 Swagger 地址 + 示例 curl）