diff --git a/docs/agent-specs/2026-06-09-agent-loop-v1/orchestrator/sql/permission-fixture.sql b/docs/agent-specs/2026-06-09-agent-loop-v1/orchestrator/sql/permission-fixture.sql
new file mode 100644
index 00000000..e8ccbac1
--- /dev/null
+++ b/docs/agent-specs/2026-06-09-agent-loop-v1/orchestrator/sql/permission-fixture.sql
@@ -0,0 +1,43 @@
+-- =============================================================================
+-- aigc:dify:callback 权限补丁（HJ-AGENT-LOOP-EXEC-001 §8.6，staging 专用）
+--
+-- 【执行前提（探活优先、不盲改库）】仅当 §12.3-① 权限探针返回 403/无权限时才执行本脚本；
+-- 探针返回 1-101-000-000（任务不存在）= 权限已通（yudao 超管租户角色对 @ss.hasPermission 全放行），无需执行。
+-- 【执行方式（utf8mb4 纪律，含中文必须显式字符集）】
+-- ssh mini-desktop 后：
+-- cd ~/game-staging/infra && set -a && . ./.env && set +a
+-- docker exec -i game-staging-mysql mysql -uroot -p"$MYSQL_ROOT_PASSWORD" \
+-- --default-character-set=utf8mb4 ruoyi-vue-pro < permission-fixture.sql
+-- 【回滚】按 permission='aigc:dify:callback' 反查 menu id，删除 system_role_menu 关联行与 system_menu 行即可。
+-- =============================================================================
+
+-- 第一步：建按钮型权限菜单（type=3 按钮；parent_id=0 顶层挂靠，仅作权限位，不在前端菜单树展示）
+INSERT INTO system_menu (name, permission, type, sort, parent_id, path, icon, component, component_name,
+ status, visible, keep_alive, always_show, creator, updater, deleted)
+SELECT 'Dify回调', 'aigc:dify:callback', 3, 99, 0, '', '', '', NULL,
+ 0, b'1', b'1', b'1', 'agent-loop', 'agent-loop', b'0'
+WHERE NOT EXISTS (
+ -- 幂等：已存在同 permission 菜单则不重复插入
+ SELECT 1 FROM system_menu WHERE permission = 'aigc:dify:callback' AND deleted = b'0'
+);
+
+-- 第二步：把该权限绑到测试 admin 所属角色
+-- role_id 取值说明：B1 验证用的 staging 测试 admin（Bearer test1 对应账号）所属角色——
+-- 先用下行查询确认 role_id 再替换（通常 yudao 种子库超管 role_id=1）：
+-- SELECT ur.role_id FROM system_user_role ur
+-- JOIN system_users u ON u.id = ur.user_id WHERE u.username = 'admin' AND ur.deleted = b'0';
+INSERT INTO system_role_menu (role_id, menu_id, creator, updater, deleted, tenant_id)
+SELECT 1, m.id, 'agent-loop', 'agent-loop', b'0', 1
+FROM system_menu m
+WHERE m.permission = 'aigc:dify:callback' AND m.deleted = b'0'
+ AND NOT EXISTS (
+ -- 幂等：该角色已绑此菜单则不重复插入
+ SELECT 1 FROM system_role_menu rm
+ WHERE rm.role_id = 1 AND rm.menu_id = m.id AND rm.deleted = b'0'
+ );
+
+-- 验证：两行应各返回 1 条
+SELECT id, name, permission, type FROM system_menu WHERE permission = 'aigc:dify:callback' AND deleted = b'0';
+SELECT rm.id, rm.role_id, rm.menu_id FROM system_role_menu rm
+ JOIN system_menu m ON m.id = rm.menu_id
+WHERE m.permission = 'aigc:dify:callback' AND rm.deleted = b'0';
diff --git a/game-cloud/game-module-aigc/game-module-aigc-api/src/main/java/cn/wanxiang/game/module/aigc/enums/ErrorCodeConstants.java b/game-cloud/game-module-aigc/game-module-aigc-api/src/main/java/cn/wanxiang/game/module/aigc/enums/ErrorCodeConstants.java
index 4db0b9cf..1097125b 100644
--- a/game-cloud/game-module-aigc/game-module-aigc-api/src/main/java/cn/wanxiang/game/module/aigc/enums/ErrorCodeConstants.java
+++ b/game-cloud/game-module-aigc/game-module-aigc-api/src/main/java/cn/wanxiang/game/module/aigc/enums/ErrorCodeConstants.java
@@ -7,7 +7,7 @@ import cn.iocoder.yudao.framework.common.exception.ErrorCode;
*
* aigc 模块，独占 1-101-***-*** 段（见 .agents/rules/engineering-conventions.md §1.3）。
* 约定：禁止与其它模块错误码段重叠；新增错误码在此登记。
- * 段内细分：000 任务基础校验 / 002 状态机非法流转（取值对齐契约 aigc.yaml）。
+ * 段内细分：000 任务基础校验 / 002 状态机非法流转（取值对齐契约 aigc.yaml）/ 003 Dify 回调（HJ-AGENT-LOOP-EXEC-001 §8）。
*
* @author 绘境AI
*/
@@ -29,4 +29,10 @@ public interface ErrorCodeConstants {
/** 重试非法：仅终态失败（failed/timed_out）可重试（契约 aigc.yaml retry：错误码 1-101-002-002） */
ErrorCode AIGC_TASK_CANNOT_RETRY = new ErrorCode(1_101_002_002, "仅失败或超时的任务可重试");
+ // ========== Dify 回调 1-101-003-***（HJ-AGENT-LOOP-EXEC-001 §8.4 回调状态机门禁）==========
+ /** 回调终态拒重入：任务已 failed/timed_out/canceled，回调拒绝再次驱动状态机（编排器对该任务走新任务重放，不复用旧 traceId） */
+ ErrorCode AIGC_CALLBACK_TASK_FINAL = new ErrorCode(1_101_003_001, "任务已终态，回调拒绝重入");
+ /** 回调参数非法：status 取值非 succeeded/failed，或 failed 分支 failureReason 不在契约#6 七值枚举内 */
+ ErrorCode AIGC_CALLBACK_STATUS_INVALID = new ErrorCode(1_101_003_002, "回调 status 取值非法");
+
}
diff --git a/game-cloud/game-module-aigc/game-module-aigc-server/pom.xml b/game-cloud/game-module-aigc/game-module-aigc-server/pom.xml
index 0c312fb9..f3df1b5f 100644
--- a/game-cloud/game-module-aigc/game-module-aigc-server/pom.xml
+++ b/game-cloud/game-module-aigc/game-module-aigc-server/pom.xml
@@ -32,6 +32,20 @@
${revision}
+
+
+ cn.iocoder.cloud
+ game-module-project-api
+ ${revision}
+
+
+
+
+ cn.iocoder.cloud
+ game-module-runtime-api
+ ${revision}
+
+
cn.iocoder.cloud
diff --git a/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/controller/admin/task/AdminAigcTaskController.java b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/controller/admin/task/AdminAigcTaskController.java
index 9ef4a93c..d1cce78f 100644
--- a/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/controller/admin/task/AdminAigcTaskController.java
+++ b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/controller/admin/task/AdminAigcTaskController.java
@@ -5,6 +5,7 @@ import cn.wanxiang.game.module.aigc.controller.admin.task.vo.DifyCallbackReqVO;
import cn.wanxiang.game.module.aigc.controller.app.task.vo.AigcTaskRespVO;
import cn.wanxiang.game.module.aigc.convert.task.AigcTaskConvert;
import cn.wanxiang.game.module.aigc.dal.dataobject.task.AigcTaskDO;
+import cn.wanxiang.game.module.aigc.service.callback.DifyCallbackService;
import cn.wanxiang.game.module.aigc.service.task.AigcTaskService;
import cn.iocoder.yudao.framework.common.pojo.CommonResult;
import cn.iocoder.yudao.framework.common.pojo.PageResult;
@@ -37,6 +38,9 @@ public class AdminAigcTaskController {
@Resource
private AigcTaskService aigcTaskService;
+ @Resource
+ private DifyCallbackService difyCallbackService;
+
@GetMapping("/task/page")
@Operation(summary = "生成任务全量分页", description = "跨创作者排障，按状态/模板/traceId 检索（T-TEL-14）")
@PreAuthorize("@ss.hasPermission('aigc:task:query')")
@@ -46,18 +50,15 @@ public class AdminAigcTaskController {
}
@PostMapping("/dify/callback")
- @Operation(summary = "[对接点] Dify workflow 完成回调", description = "契约#6 output → 驱动任务状态机；不在 MVP 实现")
+ @Operation(summary = "Dify workflow 完成回调（实做）",
+ description = "契约#6 output → 驱动任务状态机：succeeded 走三表同事务落包链（version+package+task），"
+ + "failed 落 failure_reason 置 3；agent 闭环伪装 Dify 出参与未来真 Dify 共用（HJ-AGENT-LOOP-EXEC-001 §8.4）")
@PreAuthorize("@ss.hasPermission('aigc:dify:callback')")
public CommonResult difyCallback(@Valid @RequestBody DifyCallbackReqVO reqVO) {
- // TODO 外部依赖对接点（仅契约，不实现、不 mock）：
- // Dify 6 节点工作流完成后回调本端点，以契约#6 output 形态驱动 game_aigc_task 状态机：
- // succeeded → 据 traceId 定位任务，置 status=2 + 回填 version_id 关联 + 生成元数据(gen_task_id)；
- // 不写 game_version 的 package_url/checksum/bundle_size（权威写者=runtime 编译成功后回写，见 runtime V3.0.0）；
- // failed → 落 failure_reason 置 status=3。
- // 幂等：同一 traceId 重复回调只生效一次（落幂等表 / 状态机终态拒重入）。
- // 正式实现需加服务间签名校验；LLM 实名充值为人工闸门，本端点不触发计费。
- log.warn("[difyCallback] 对接点未实现，仅受理占位 traceId={} status={}", reqVO.getTraceId(), reqVO.getStatus());
- return success(true);
+ // 实做（HJ-AGENT-LOOP-EXEC-001 §8.4）：委托回调服务执行「定位/幂等→受理→薄校验→建版本→组包→落包→回填」；
+ // 事务边界与写链失败补偿在 Service 层承载（外层编排 + 内层独立事务 Bean，Spring 代理陷阱方案②）。
+ // TODO 对接点（M-b 真 Dify 接入时）：补服务间签名校验；LLM 实名充值为人工闸门，本端点不触发计费。
+ return success(difyCallbackService.handleCallback(reqVO));
}
}
diff --git a/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/controller/admin/task/vo/DifyCallbackReqVO.java b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/controller/admin/task/vo/DifyCallbackReqVO.java
index d278cba2..07f4ab11 100644
--- a/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/controller/admin/task/vo/DifyCallbackReqVO.java
+++ b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/controller/admin/task/vo/DifyCallbackReqVO.java
@@ -5,16 +5,20 @@ import jakarta.validation.constraints.NotBlank;
import lombok.Data;
import java.math.BigDecimal;
+import java.util.List;
+import java.util.Map;
/**
- * Dify workflow 完成回调 Request VO（对齐契约 aigc.yaml DifyCallbackReqVO / 契约#6 output）
+ * Dify workflow 完成回调 Request VO（对齐契约 aigc.yaml DifyCallbackReqVO / 契约#6 dify-workflow-io.json output）
*
- * 【外部依赖对接点，仅定义契约，不实现、不 mock】形态对齐契约#6 dify-workflow-io.json 的 output。
- * gameConfig/assets 等复杂结构在 MVP 骨架阶段不展开建模，正式对接时按契约#6 补全。
+ * 形态严格对齐契约#6 output（status/traceId/templateId/gameConfig/assets/qualityScore/failureReason）。
+ * 回调实做（HJ-AGENT-LOOP-EXEC-001 §8.4）：succeeded 走「建版本→组包→落包→回填任务」三表同事务写入链；
+ * failed 走「定位→受理→置 failed + failure_reason」终态落库。深度 schema 校验权威在裁决引擎（编排器侧），
+ * 后端只做非空 + 模板一致薄校验（职责分界见 DifyCallbackTxService）。
*
* @author 绘境AI
*/
-@Schema(description = "管理后台 - Dify 完成回调 Request VO（对接点）")
+@Schema(description = "管理后台 - Dify 完成回调 Request VO（契约#6 output 形态）")
@Data
public class DifyCallbackReqVO {
@@ -31,10 +35,17 @@ public class DifyCallbackReqVO {
@Schema(description = "最终匹配/使用的模板 ID", example = "dodge")
private String templateId;
+ @Schema(description = "生成的可玩配置（契约#6 output.gameConfig → 注入 GamePackage.gameConfig；succeeded 必带，"
+ + "缺失视为业务性失败 config_invalid）", example = "{\"templateId\":\"clicker\",\"title\":\"点点乐\",\"target\":10}")
+ private Map gameConfig;
+
+ @Schema(description = "生成资源引用列表（契约#6 output.assets → 合入 GamePackage.assets；可空，空则落 []）")
+ private List> assets;
+
@Schema(description = "生成质量分(0-1)，对齐契约#6 output 0-1", example = "0.86")
private BigDecimal qualityScore;
- @Schema(description = "失败原因分类（status=failed 必填，取值对齐契约#6 output.failureReason）", example = "llm_error")
+ @Schema(description = "失败原因分类（status=failed 必填，取值对齐契约#6 output.failureReason 七值枚举）", example = "llm_error")
private String failureReason;
}
diff --git a/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/dal/mysql/task/AigcTaskMapper.java b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/dal/mysql/task/AigcTaskMapper.java
index 2a97ac4f..0c92305c 100644
--- a/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/dal/mysql/task/AigcTaskMapper.java
+++ b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/dal/mysql/task/AigcTaskMapper.java
@@ -7,6 +7,10 @@ import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.framework.mybatis.core.mapper.BaseMapperX;
import cn.iocoder.yudao.framework.mybatis.core.query.LambdaQueryWrapperX;
import org.apache.ibatis.annotations.Mapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.List;
/**
* 生成任务 Mapper
@@ -16,6 +20,31 @@ import org.apache.ibatis.annotations.Mapper;
@Mapper
public interface AigcTaskMapper extends BaseMapperX {
+ /** 接口内日志器（default 方法多条告警用；接口无实例字段，按惯例取静态 Logger） */
+ Logger LOGGER = LoggerFactory.getLogger(AigcTaskMapper.class);
+
+ /**
+ * 按 traceId 定位生成任务（Dify 回调对接点；idx_trace 索引，traceId 为 UUID 生成实际唯一，
+ * selectOne 语义兜底取第一条并告警多条——不抛错，保证回调链路在脏数据下仍可定位任务）
+ *
+ * @param traceId 贯穿全链路 traceId（契约#6 output.traceId）
+ * @return 任务 DO；未命中返回 null
+ */
+ default AigcTaskDO selectByTraceId(String traceId) {
+ // V2.0.0 DDL idx_trace 为非唯一索引，traceId 由 UUID 生成实际唯一；防御性取列表
+ List list = selectList(new LambdaQueryWrapperX()
+ .eq(AigcTaskDO::getTraceId, traceId)
+ .orderByAsc(AigcTaskDO::getId)); // 万一多条按 ID 升序，稳定取最早一条
+ if (list.isEmpty()) {
+ return null;
+ }
+ if (list.size() > 1) {
+ // 理论不可达（traceId UUID 唯一）；命中即数据异常，告警留痕便于排障，不阻断回调
+ LOGGER.warn("[selectByTraceId] traceId 命中多条任务，兜底取最早一条 traceId={}, count={}", traceId, list.size());
+ }
+ return list.get(0);
+ }
+
/**
* 「我的生成任务」分页（app 端，创作者只见自己数据）
*
diff --git a/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackService.java b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackService.java
new file mode 100644
index 00000000..4331eaf4
--- /dev/null
+++ b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackService.java
@@ -0,0 +1,31 @@
+package cn.wanxiang.game.module.aigc.service.callback;
+
+import cn.wanxiang.game.module.aigc.controller.admin.task.vo.DifyCallbackReqVO;
+
+/**
+ * Dify 回调 Service 接口（HJ-AGENT-LOOP-EXEC-001 §8.4，agent 闭环 / 未来真 Dify 共用回调面）
+ *
+ * 承载契约#6 output → game_aigc_task 状态机驱动 + 内联 PackageFactory 落包链：
+ * succeeded → 定位/幂等 → 受理置 1 → 薄校验 → 建版本（project-api）→ 组包（GamePackage JSON 两段序列化）
+ * → 落包（runtime-api storeForVersion）→ 回填任务（completeWithVersion），三表同事务；
+ * failed → 定位/幂等 → 受理置 1 → failureReason 七值校验 → 置 status=3 + failure_reason + finishTime。
+ * 写链失败（建版本/组包/落包/回填任一抛错）→ 内层事务三表全回滚 → 补偿新事务置 failed(llm_error)，禁止带病 succeeded（Z1）。
+ *
+ * @author 造梦AI
+ */
+public interface DifyCallbackService {
+
+ /**
+ * 处理 Dify workflow 完成回调（外层入口：非事务编排 + 写链失败补偿）
+ *
+ * 事务结构（§8.4 Spring 代理陷阱方案②）：本方法不开事务，委托独立 Bean {@code DifyCallbackTxService}
+ * 的 @Transactional 方法执行三表写入（经 Spring 代理调用，事务注解真实生效）；
+ * 写链异常 catch 后经同 Bean 的补偿方法（新事务）置任务 failed(llm_error)，再向上抛出。
+ * 幂等：同 traceId 重复回调安全（任务已成功终态短路返回 true）；任务已失败终态拒重入（1-101-003-001）。
+ *
+ * @param reqVO 回调入参（契约#6 output 形态）
+ * @return true=回调受理完成（含幂等短路与业务性失败落库两类正常返回）
+ */
+ Boolean handleCallback(DifyCallbackReqVO reqVO);
+
+}
diff --git a/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackServiceImpl.java b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackServiceImpl.java
new file mode 100644
index 00000000..c2f44f72
--- /dev/null
+++ b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackServiceImpl.java
@@ -0,0 +1,90 @@
+package cn.wanxiang.game.module.aigc.service.callback;
+
+import cn.wanxiang.game.module.aigc.controller.admin.task.vo.DifyCallbackReqVO;
+import cn.iocoder.yudao.framework.common.exception.ServiceException;
+import cn.iocoder.yudao.framework.common.exception.enums.GlobalErrorCodeConstants;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.util.Set;
+
+import static cn.wanxiang.game.module.aigc.enums.ErrorCodeConstants.AIGC_CALLBACK_STATUS_INVALID;
+import static cn.wanxiang.game.module.aigc.enums.ErrorCodeConstants.AIGC_CALLBACK_TASK_FINAL;
+import static cn.wanxiang.game.module.aigc.enums.ErrorCodeConstants.AIGC_TASK_NOT_EXISTS;
+
+/**
+ * Dify 回调 Service 实现（HJ-AGENT-LOOP-EXEC-001 §8.4 外层：非事务编排 + 写链失败补偿）
+ *
+ * 【Spring 代理陷阱方案②落地】本类自身不开事务，只负责把请求转交独立 Bean {@link DifyCallbackTxService}：
+ * 内层 handleCallbackTx 经 Spring 代理调用 → @Transactional 真实生效（若内外层同类自调用则事务静默失效，
+ * Z1 三表回滚断言全盘落空——这就是拆 Bean 的原因，详见 DifyCallbackTxService 类注释）。
+ * 【补偿语义（§8.4 失败路径）】写链异常（建版本/组包/落包/回填，步骤④-⑦）→ 内层事务已整体回滚 →
+ * 本层 catch 后经代理调内层补偿方法（新事务）置任务 failed(llm_error) → 向上抛 ServiceException
+ * （编排器收到非 0 code 按 infra 处理，F5：不重试同 traceId，resume 走新任务）。禁止带病 succeeded。
+ * 【不补偿的业务校验异常】任务不存在/终态拒重入/参数非法三类——发生在写链之前（或属调用方参数错误，
+ * 事务回滚后任务回原态可被正确回调重新处理），补偿置 failed 反而有害（如终态拒重入时会破坏既有终态）。
+ *
+ * @author 造梦AI
+ */
+@Slf4j
+@Service
+public class DifyCallbackServiceImpl implements DifyCallbackService {
+
+ /**
+ * 不触发补偿的业务校验错误码（写链前置校验段抛出，无三表写入或仅有可回滚的受理置 1）：
+ * 1-101-000-000 任务不存在 / 1-101-003-001 终态拒重入 / 1-101-003-002 回调参数非法
+ */
+ private static final Set NO_COMPENSATE_CODES = Set.of(
+ AIGC_TASK_NOT_EXISTS.getCode(),
+ AIGC_CALLBACK_TASK_FINAL.getCode(),
+ AIGC_CALLBACK_STATUS_INVALID.getCode());
+
+ /** 内层事务 Bean（构造器注入：Spring 推荐写法，亦便于单测直接组装真实内外层验证补偿链路） */
+ private final DifyCallbackTxService txService;
+
+ public DifyCallbackServiceImpl(DifyCallbackTxService txService) {
+ this.txService = txService;
+ }
+
+ @Override
+ public Boolean handleCallback(DifyCallbackReqVO reqVO) {
+ log.info("[handleCallback] 收到 Dify 回调 traceId={}, status={}, templateId={}",
+ reqVO.getTraceId(), reqVO.getStatus(), reqVO.getTemplateId());
+ try {
+ // 经 Spring 代理调用内层事务方法（三表同事务写入链，§8.4 七步序列）
+ return txService.handleCallbackTx(reqVO);
+ } catch (ServiceException e) {
+ if (NO_COMPENSATE_CODES.contains(e.getCode())) {
+ // 业务校验异常：不补偿，原样上抛（任务不存在/终态拒重入/参数非法——见类注释）
+ throw e;
+ }
+ // 写链 ServiceException（如 createForPackage/storeForVersion 经 getCheckedData 抛出）：补偿后原样上抛
+ compensateQuietly(reqVO.getTraceId(), "写链 ServiceException code=" + e.getCode() + ", msg=" + e.getMessage());
+ throw e;
+ } catch (Exception e) {
+ // 写链非业务异常（组包序列化失败/NPE 等）：补偿后包装为 ServiceException 上抛（编排器按非 0 code 处理）
+ compensateQuietly(reqVO.getTraceId(), "写链异常 " + e.getClass().getSimpleName() + ": " + e.getMessage());
+ log.error("[handleCallback] 回调写链异常（三表已回滚，已补偿置 failed）traceId={}", reqVO.getTraceId(), e);
+ throw new ServiceException(GlobalErrorCodeConstants.INTERNAL_SERVER_ERROR.getCode(),
+ "回调写链异常：" + e.getMessage());
+ }
+ }
+
+ /**
+ * 静默补偿（补偿自身失败只留痕、不吞原异常——原写链异常必须继续向上抛给编排器）
+ *
+ * @param traceId 回调 traceId
+ * @param causeSummary 写链失败真因摘要（入补偿日志留痕）
+ */
+ private void compensateQuietly(String traceId, String causeSummary) {
+ try {
+ // 经 Spring 代理调用（新事务）：主事务此刻已回滚结束，REQUIRED 传播即开新事务写补偿
+ txService.compensateMarkFailed(traceId, causeSummary);
+ } catch (Exception compensateEx) {
+ // 补偿失败：任务停留 queued（可被编排器 resume 新任务重放），log.error 留痕排障，不掩盖原异常
+ log.error("[compensateQuietly] 补偿置 failed 自身失败，任务停留原态 traceId={}, 原因={}",
+ traceId, causeSummary, compensateEx);
+ }
+ }
+
+}
diff --git a/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackTxService.java b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackTxService.java
new file mode 100644
index 00000000..70690d88
--- /dev/null
+++ b/game-cloud/game-module-aigc/game-module-aigc-server/src/main/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackTxService.java
@@ -0,0 +1,461 @@
+package cn.wanxiang.game.module.aigc.service.callback;
+
+import cn.wanxiang.game.module.aigc.controller.admin.task.vo.DifyCallbackReqVO;
+import cn.wanxiang.game.module.aigc.dal.dataobject.task.AigcTaskDO;
+import cn.wanxiang.game.module.aigc.dal.mysql.task.AigcTaskMapper;
+import cn.wanxiang.game.module.aigc.enums.AigcTaskStatusEnum;
+import cn.wanxiang.game.module.aigc.enums.FailureReasonEnum;
+import cn.wanxiang.game.module.aigc.service.task.AigcTaskService;
+import cn.wanxiang.game.module.project.api.ProjectVersionApi;
+import cn.wanxiang.game.module.project.dto.ProjectVersionCreateForPackageReqDTO;
+import cn.wanxiang.game.module.runtime.api.RuntimePackageApi;
+import cn.wanxiang.game.module.runtime.dto.RuntimePackageStoreReqDTO;
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.annotation.Resource;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.util.StringUtils;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.time.LocalDateTime;
+import java.time.ZoneId;
+import java.time.format.DateTimeFormatter;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Objects;
+
+import static cn.wanxiang.game.module.aigc.enums.ErrorCodeConstants.AIGC_CALLBACK_STATUS_INVALID;
+import static cn.wanxiang.game.module.aigc.enums.ErrorCodeConstants.AIGC_CALLBACK_TASK_FINAL;
+import static cn.wanxiang.game.module.aigc.enums.ErrorCodeConstants.AIGC_TASK_NOT_EXISTS;
+import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
+
+/**
+ * Dify 回调内层事务服务（HJ-AGENT-LOOP-EXEC-001 §8.4，独立 Bean）
+ *
+ * 【为什么拆独立 Bean（Spring 代理陷阱方案②）】@Transactional 基于 Spring AOP 代理生效：若内层事务方法与外层
+ * 编排方法放同一个类，外层 {@code this.handleCallbackTx(...)} 是自调用、不经过代理，事务注解静默失效，
+ * Z1「三表全回滚」断言全盘落空。故把事务方法拆到本独立 Bean——外层 {@code DifyCallbackServiceImpl} 注入本 Bean
+ * 经 Spring 代理调用，@Transactional 真实生效；补偿写 failed 同理经代理走新事务（调用时主事务已回滚结束，
+ * REQUIRED 传播即开新事务，不违反「事务内禁 REQUIRES_NEW」纪律）。
+ *
+ * 【事务模式（§8.2 铁律）】注入 {@link ProjectVersionApi} + {@link RuntimePackageApi}（仅 -api，禁依赖对方 -server——守门④）；
+ * MVP 单体内由对方 @RestController @Primary ApiImpl 就地解析（同进程方法调用，非真实 Feign/HTTP），
+ * 与发布编排同款模式（范本 PublishOrchestrationServiceImpl）；事务内禁止 Feign/HTTP/@Async/REQUIRES_NEW。
+ *
+ * @author 造梦AI
+ */
+@Slf4j
+@Service
+public class DifyCallbackTxService {
+
+ /** 契约#6 output.status 合法值：成功 */
+ private static final String STATUS_SUCCEEDED = "succeeded";
+ /** 契约#6 output.status 合法值：失败 */
+ private static final String STATUS_FAILED = "failed";
+ /** checksum 自指消解占位：64 位 '0'（与真实 sha256 hex 等长，T0→T1 字节布局稳定） */
+ private static final String CHECKSUM_PLACEHOLDER = "0".repeat(64);
+ /** GamePackage meta.title 上限（契约#4 maxLength 60） */
+ private static final int META_TITLE_MAX = 60;
+ /** GamePackage meta.summary 上限（契约#4 maxLength 500） */
+ private static final int META_SUMMARY_MAX = 500;
+ /** GamePackage meta.title 防御回落值（薄校验不验 title 深度，空时兜底保契约 minLength 1；深度校验权威在裁决引擎） */
+ private static final String META_TITLE_FALLBACK = "未命名小游戏";
+ /** GamePackage meta.cover 占位（1px 透明 gif data URI，沿 game-studio inject.ts demo 包同款，满足契约 format=uri） */
+ private static final String META_COVER_PLACEHOLDER =
+ "data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==";
+
+ /**
+ * 组包专用 Jackson 序列化器（§8.4-5 字节可复现根基）：Jackson 默认配置、不开属性重排序、不开缩进，
+ * 输入用 LinkedHashMap 保插入序 → 同输入两次序列化字节一致（单测断言）。静态只读实例线程安全。
+ */
+ private static final ObjectMapper PACKAGE_MAPPER = new ObjectMapper();
+
+ @Resource
+ private AigcTaskMapper aigcTaskMapper;
+
+ @Resource
+ private AigcTaskService aigcTaskService;
+
+ /**
+ * project 建版本 seam（仅依赖 -api）。MVP 单体由 project 模块 ProjectVersionApiImpl(@RestController @Primary)
+ * 就地解析，事务内本地调用（非 Feign），抛错则回调事务整体回滚。
+ */
+ @Resource
+ private ProjectVersionApi projectVersionApi;
+
+ /**
+ * runtime 落包 seam（仅依赖 -api）。MVP 单体由 runtime 模块 RuntimePackageApiImpl(@RestController @Primary)
+ * 就地解析，事务内本地调用（非 Feign），抛错则回调事务整体回滚。
+ */
+ @Resource
+ private RuntimePackageApi runtimePackageApi;
+
+ /**
+ * 回调三表事务写入（§8.4 七步序列；succeeded 写链 = game_aigc_task + game_version + game_runtime_package）
+ *
+ * 必须经 Spring 代理调用（由 {@code DifyCallbackServiceImpl} 注入本 Bean 调用），@Transactional 方可生效；
+ * 步骤④-⑦ 任一抛异常 → 本事务整体回滚（受理置 1 / game_version / game_runtime_package 三表全回滚），
+ * 补偿由外层 catch 后调 {@link #compensateMarkFailed} 走新事务，禁止带病 succeeded（Z1）。
+ *
+ * @param reqVO 回调入参（契约#6 output 形态）
+ * @return true=受理完成（含幂等短路与业务性失败落库）
+ */
+ @Transactional(rollbackFor = Exception.class)
+ public Boolean handleCallbackTx(DifyCallbackReqVO reqVO) {
+ // ===== 步骤①：定位与幂等 =====
+ AigcTaskDO task = aigcTaskMapper.selectByTraceId(reqVO.getTraceId());
+ if (task == null) {
+ // 未命中：无任何写入直接拒绝（编排器/权限探针场景预期返回 1-101-000-000）
+ log.warn("[handleCallbackTx] 回调 traceId 未命中任务，拒绝 traceId={}", reqVO.getTraceId());
+ throw exception(AIGC_TASK_NOT_EXISTS);
+ }
+ if (Objects.equals(task.getStatus(), AigcTaskStatusEnum.SUCCEEDED.getStatus()) && task.getVersionId() != null) {
+ // 幂等短路：任务已成功终态且版本已回填，重复回调安全，零写入
+ log.info("[handleCallbackTx] 任务已成功终态，回调幂等短路 taskId={}, traceId={}, versionId={}",
+ task.getId(), reqVO.getTraceId(), task.getVersionId());
+ return Boolean.TRUE;
+ }
+ if (isFinalFailed(task.getStatus())) {
+ // 终态拒重入：failed/timed_out/canceled 不可被回调再驱动（编排器对该任务走新任务重放，§7.2）
+ log.warn("[handleCallbackTx] 任务已终态，回调拒绝重入 taskId={}, traceId={}, status={}",
+ task.getId(), reqVO.getTraceId(), task.getStatus());
+ throw exception(AIGC_CALLBACK_TASK_FINAL);
+ }
+
+ // ===== 步骤②：受理置 1（F5：状态机 running 首获写入方；同事务，写链失败随事务回滚） =====
+ AigcTaskDO running = new AigcTaskDO();
+ running.setId(task.getId());
+ running.setStatus(AigcTaskStatusEnum.RUNNING.getStatus());
+ aigcTaskMapper.updateById(running);
+
+ // ===== 步骤③：薄校验（status 取值门禁；深度 schema 校验权威在裁决引擎/编排器侧，后端只做非空+模板一致薄校验） =====
+ if (!STATUS_SUCCEEDED.equals(reqVO.getStatus()) && !STATUS_FAILED.equals(reqVO.getStatus())) {
+ // status 非法：参数级拒绝（抛错回滚受理置 1，任务回到原态可被正确回调重新处理）
+ log.warn("[handleCallbackTx] 回调 status 取值非法 taskId={}, traceId={}, status={}",
+ task.getId(), reqVO.getTraceId(), reqVO.getStatus());
+ throw exception(AIGC_CALLBACK_STATUS_INVALID);
+ }
+
+ // ----- failed 分支：校验 failureReason 七值 → 置失败终态落库 -----
+ if (STATUS_FAILED.equals(reqVO.getStatus())) {
+ if (!isValidFailureReason(reqVO.getFailureReason())) {
+ log.warn("[handleCallbackTx] 回调 failureReason 不在契约#6 七值枚举内 taskId={}, traceId={}, failureReason={}",
+ task.getId(), reqVO.getTraceId(), reqVO.getFailureReason());
+ throw exception(AIGC_CALLBACK_STATUS_INVALID);
+ }
+ markTaskFailed(task.getId(), reqVO.getFailureReason());
+ log.info("[handleCallbackTx] 回调 failed 落库完成 taskId={}, traceId={}, failureReason={}",
+ task.getId(), reqVO.getTraceId(), reqVO.getFailureReason());
+ return Boolean.TRUE;
+ }
+
+ // ----- succeeded 分支薄校验：gameConfig 非空 + task.gameId 非空 + 模板一致；不满足 = 业务性失败 -----
+ // （这不是写链异常：同事务置 failed(config_invalid) 后正常提交返回 true，不回滚、不补偿）
+ String templateId = StringUtils.hasText(reqVO.getTemplateId()) ? reqVO.getTemplateId() : task.getTemplateId();
+ String invalidCause = validateSucceededPayload(task, reqVO, templateId);
+ if (invalidCause != null) {
+ markTaskFailed(task.getId(), FailureReasonEnum.CONFIG_INVALID.getReason());
+ log.warn("[handleCallbackTx] succeeded 薄校验不过，业务性失败置 config_invalid taskId={}, traceId={}, cause={}",
+ task.getId(), reqVO.getTraceId(), invalidCause);
+ return Boolean.TRUE;
+ }
+
+ // ===== 步骤④：建版本（project-api，既有幂等：同 genTaskId 复用已建版本） =====
+ // checksum 鸡蛋环决断（§8.4-4 / §16-3）：GamePackage JSON 内含 versionId，sha256 必须在拿到 versionId
+ // 之后才能计算 → game_version 行的 checksum/bundleSize 落空串/0，v1 不回写（宿主完整性校验链
+ // 只依赖 game_runtime_package 行，V3 DDL 决策5 该两字段权威写者=runtime）。
+ ProjectVersionCreateForPackageReqDTO versionReq = new ProjectVersionCreateForPackageReqDTO();
+ versionReq.setGameId(task.getGameId());
+ versionReq.setGenTaskId(String.valueOf(task.getId()));
+ versionReq.setPackageUrl("");
+ versionReq.setBundleSize(0L);
+ versionReq.setChecksum("");
+ Long versionId = projectVersionApi.createForPackage(versionReq).getCheckedData();
+ log.info("[handleCallbackTx] 建版本完成 taskId={}, traceId={}, versionId={}", task.getId(), reqVO.getTraceId(), versionId);
+
+ // ===== 步骤⑤：组包（GamePackage JSON，契约#4 全必填字段；checksum 两段序列化 T0→C→T1） =====
+ PackedManifest packed = buildGamePackage(task, reqVO, templateId, versionId);
+
+ // ===== 步骤⑥：落包（runtime-api storeForVersion：建 game_runtime_package 行 status=0 + 写 package_json，Z1 缺行问题在此闭合） =====
+ RuntimePackageStoreReqDTO storeReq = new RuntimePackageStoreReqDTO();
+ storeReq.setGameId(task.getGameId());
+ storeReq.setVersionId(versionId);
+ storeReq.setTemplateId(templateId);
+ storeReq.setManifestJson(packed.json());
+ storeReq.setChecksum(packed.checksum());
+ storeReq.setBundleSize(packed.bundleSize());
+ storeReq.setEntry("index.html");
+ storeReq.setRuntimeVersion("1.0.0");
+ storeReq.setPreloadPolicy("eager");
+ Long pkgId = runtimePackageApi.storeForVersion(storeReq).getCheckedData();
+ log.info("[handleCallbackTx] 落包完成 taskId={}, traceId={}, versionId={}, pkgId={}, checksum={}, bundleSize={}",
+ task.getId(), reqVO.getTraceId(), versionId, pkgId, packed.checksum(), packed.bundleSize());
+
+ // ===== 步骤⑦：回填任务（既有幂等：置 status=2 + version_id + progress 100 + finishTime） =====
+ aigcTaskService.completeWithVersion(task.getId(), versionId);
+ log.info("[handleCallbackTx] 回调 succeeded 三表写入链完成 taskId={}, traceId={}, versionId={}",
+ task.getId(), reqVO.getTraceId(), versionId);
+ return Boolean.TRUE;
+ }
+
+ /**
+ * 写链失败补偿（§8.4 失败路径）：新事务置任务 failed(llm_error)，必须经 Spring 代理调用方可生效
+ *
+ * 调用时机：外层 catch 写链异常后（主事务已回滚结束，本方法 REQUIRED 传播即开新事务）。
+ * failureReason 归桶决断（§16-2）：FailureReasonEnum 七值冻结且无 internal_error 桶，取 llm_error 为
+ * 「生成执行链异常」最近桶；真因走本方法 log.error + 编排器账本，不丢失。
+ *
+ * @param traceId 回调 traceId（重新定位任务——主事务已回滚，按 traceId 取库内当前态）
+ * @param causeSummary 写链失败真因摘要（仅入日志留痕，不落库）
+ */
+ @Transactional(rollbackFor = Exception.class)
+ public void compensateMarkFailed(String traceId, String causeSummary) {
+ AigcTaskDO task = aigcTaskMapper.selectByTraceId(traceId);
+ if (task == null) {
+ // 理论不可达（写链失败前任务必已命中）；防御留痕
+ log.error("[compensateMarkFailed] 补偿目标任务未命中，跳过 traceId={}, cause={}", traceId, causeSummary);
+ return;
+ }
+ if (!AigcTaskStatusEnum.isCancelable(task.getStatus())) {
+ // 防御：任务已是终态（succeeded/failed/timed_out/canceled）不覆写，避免补偿破坏既有终态
+ log.warn("[compensateMarkFailed] 任务已终态，补偿跳过 taskId={}, traceId={}, status={}, cause={}",
+ task.getId(), traceId, task.getStatus(), causeSummary);
+ return;
+ }
+ markTaskFailed(task.getId(), FailureReasonEnum.LLM_ERROR.getReason());
+ log.error("[compensateMarkFailed] 回调写链失败已补偿置 failed(llm_error) taskId={}, traceId={}, 真因={}",
+ task.getId(), traceId, causeSummary);
+ }
+
+ // ============================== 组包（内联 PackageFactory）==============================
+
+ /**
+ * 组包结果（落库文本 + 对外校验值；checksum = sha256(json)，宿主对 manifest 端点响应原文同源校验）
+ *
+ * @param json GamePackage 落库文本 T1（manifest.checksum 字段内值 = C 仅作包内自述）
+ * @param checksum sha256(T1)，game_runtime_package.checksum 列与取包 RespVO.checksum 的权威值
+ * @param bundleSize 包总字节（T_base 文本 UTF-8 字节数，确定性近似，见 buildGamePackage 注释）
+ */
+ private record PackedManifest(String json, String checksum, long bundleSize) {
+ }
+
+ /**
+ * 构建 GamePackage JSON（契约#4 全必填字段 + checksum 自指消解两段序列化，§8.4 步骤⑤）
+ *
+ * checksum 自指消解：包内 manifest.checksum 字段值依赖序列化文本、文本又含该字段 → 先以 64 位 '0' 占位
+ * 序列化得 T0 → C=sha256(T0) → 把 C 写回 manifest.checksum 重序列化得 T1。落库与对外校验对象一律为 T1，
+ * 期望值 = sha256(T1)（宿主 fetchAndVerifyManifest 对响应原文算 sha256 与 RespVO.checksum 比对，两者同源即过）；
+ * manifest.checksum 字段内值 = C 仅作包内自述，不参与宿主校验。
+ * bundleSize 取值：在 checksum 环之外另有一层自指（bundleSize 也在文本内），取「bundleSize=0 + checksum 占位」
+ * 基准文本 T_base 的 UTF-8 字节数为确定性近似（与最终文本差≤数字位数级，门禁语义足够；关键是同输入可复现）。
+ * 字节可复现保证：LinkedHashMap 保插入序 + PACKAGE_MAPPER 固定配置 + generatedAt 取任务创建时间（非墙钟，
+ * 否则两次组包字节必不一致，§8.7 用例 2 无法成立）。
+ *
+ * @param task 生成任务（gameId/promptHash/traceId/createTime 来源）
+ * @param reqVO 回调入参（gameConfig/assets 来源）
+ * @param templateId 已定模板 ID（reqVO.templateId 回落 task.templateId 后的终值）
+ * @param versionId 建版本产出的版本 ID
+ * @return 组包结果（T1 文本 + sha256(T1) + bundleSize）
+ */
+ private PackedManifest buildGamePackage(AigcTaskDO task, DifyCallbackReqVO reqVO, String templateId, Long versionId) {
+ // LinkedHashMap 逐键插入：键序 = 构建序，序列化字节确定
+ Map pkg = new LinkedHashMap<>();
+ pkg.put("schemaVersion", "1.0");
+ pkg.put("gameId", String.valueOf(task.getGameId()));
+ pkg.put("versionId", String.valueOf(versionId));
+ pkg.put("templateId", templateId);
+ pkg.put("gameConfig", reqVO.getGameConfig());
+ pkg.put("assets", reqVO.getAssets() == null ? Collections.emptyList() : reqVO.getAssets());
+
+ // manifest：bundleSize/checksum 先占位，按 T_base→T0→C→T1 三步回填
+ Map manifest = new LinkedHashMap<>();
+ manifest.put("runtimeVersion", "1.0.0");
+ manifest.put("entry", "index.html");
+ manifest.put("preloadPolicy", "eager");
+ manifest.put("bundleSize", 0L);
+ manifest.put("checksum", CHECKSUM_PLACEHOLDER);
+ pkg.put("manifest", manifest);
+
+ // meta：title=gameConfig.title 截 60（空回落防御值保契约 minLength 1）；summary=designIntent 或 theme 截 500
+ Map meta = new LinkedHashMap<>();
+ meta.put("title", truncate(textOf(reqVO.getGameConfig(), "title", META_TITLE_FALLBACK), META_TITLE_MAX));
+ String summary = textOf(reqVO.getGameConfig(), "designIntent", null);
+ if (summary == null) {
+ summary = textOf(reqVO.getGameConfig(), "theme", "");
+ }
+ meta.put("summary", truncate(summary, META_SUMMARY_MAX));
+ meta.put("cover", META_COVER_PLACEHOLDER);
+ meta.put("ageRating", "all");
+ pkg.put("meta", meta);
+
+ // provenance：可追溯来源（契约#4 全字段可选）。model 不落——契约#6 output 无该字段、回调无真实来源，
+ // 不硬编码编排器侧模型名（避免错误耦合）；generatedAt 取任务创建时间保证字节可复现（见方法注释）。
+ Map provenance = new LinkedHashMap<>();
+ if (StringUtils.hasText(task.getPromptHash())) {
+ provenance.put("promptHash", task.getPromptHash());
+ }
+ provenance.put("traceId", task.getTraceId());
+ String generatedAt = formatGeneratedAt(task.getCreateTime());
+ if (generatedAt != null) {
+ provenance.put("generatedAt", generatedAt);
+ }
+ pkg.put("provenance", provenance);
+
+ try {
+ // T_base：bundleSize=0 + checksum 占位 → 基准文本，bundleSize := 其 UTF-8 字节数（确定性近似）
+ String tBase = PACKAGE_MAPPER.writeValueAsString(pkg);
+ long bundleSize = tBase.getBytes(StandardCharsets.UTF_8).length;
+ manifest.put("bundleSize", bundleSize);
+ // T0：bundleSize 已定 + checksum 仍占位 → C = sha256(T0)
+ String t0 = PACKAGE_MAPPER.writeValueAsString(pkg);
+ String innerChecksum = sha256Hex(t0);
+ // T1：写回 C（与占位等长 64 位 hex，布局稳定）→ 落库文本；对外校验值 = sha256(T1)
+ manifest.put("checksum", innerChecksum);
+ String t1 = PACKAGE_MAPPER.writeValueAsString(pkg);
+ return new PackedManifest(t1, sha256Hex(t1), bundleSize);
+ } catch (JsonProcessingException e) {
+ // 组包序列化异常属写链失败（步骤⑤）：上抛触发事务回滚 + 外层补偿置 failed(llm_error)
+ throw new IllegalStateException("GamePackage 组包序列化失败 taskId=" + task.getId()
+ + ", traceId=" + task.getTraceId(), e);
+ }
+ }
+
+ // ============================== 私有校验/工具 ==============================
+
+ /**
+ * succeeded 分支薄校验（§8.4 步骤③：非空 + 模板一致；深度 schema 校验权威在裁决引擎，职责分界）
+ *
+ * @param task 生成任务
+ * @param reqVO 回调入参
+ * @param templateId 已回落的终值模板 ID
+ * @return null=校验通过；非 null=业务性失败原因摘要（置 config_invalid 落库）
+ */
+ private String validateSucceededPayload(AigcTaskDO task, DifyCallbackReqVO reqVO, String templateId) {
+ if (reqVO.getGameConfig() == null || reqVO.getGameConfig().isEmpty()) {
+ return "succeeded 回调缺 gameConfig";
+ }
+ if (task.getGameId() == null) {
+ return "任务缺 gameId（GamePackage.gameId 必填，无法组包）";
+ }
+ if (!StringUtils.hasText(templateId)) {
+ return "templateId 缺失（回调与任务均为空，GamePackage.templateId 必填）";
+ }
+ Object configTemplateId = reqVO.getGameConfig().get("templateId");
+ if (configTemplateId != null && !templateId.equals(String.valueOf(configTemplateId))) {
+ return "gameConfig.templateId 与包级 templateId 不一致：" + configTemplateId + " != " + templateId;
+ }
+ return null;
+ }
+
+ /**
+ * 置任务失败终态（status=3 + failure_reason + finishTime；failed 分支与业务性失败/补偿共用）
+ *
+ * @param taskId 任务 ID
+ * @param failureReason 失败原因（契约#6 七值枚举内取值）
+ */
+ private void markTaskFailed(Long taskId, String failureReason) {
+ AigcTaskDO update = new AigcTaskDO();
+ update.setId(taskId);
+ update.setStatus(AigcTaskStatusEnum.FAILED.getStatus());
+ update.setFailureReason(failureReason);
+ update.setFinishTime(LocalDateTime.now());
+ aigcTaskMapper.updateById(update);
+ }
+
+ /**
+ * 是否失败类终态（failed/timed_out/canceled——回调拒重入对象；succeeded 由幂等短路单独处理）
+ *
+ * @param status 任务状态值
+ * @return true=失败类终态
+ */
+ private static boolean isFinalFailed(Integer status) {
+ return Objects.equals(AigcTaskStatusEnum.FAILED.getStatus(), status)
+ || Objects.equals(AigcTaskStatusEnum.TIMED_OUT.getStatus(), status)
+ || Objects.equals(AigcTaskStatusEnum.CANCELED.getStatus(), status);
+ }
+
+ /**
+ * failureReason 是否在契约#6 七值枚举内（七值冻结，校验逻辑在此承载、不动 FailureReasonEnum 文件）
+ *
+ * @param reason 回调 failureReason
+ * @return true=合法
+ */
+ private static boolean isValidFailureReason(String reason) {
+ return StringUtils.hasText(reason)
+ && Arrays.stream(FailureReasonEnum.values()).anyMatch(e -> e.getReason().equals(reason));
+ }
+
+ /**
+ * 从 gameConfig 取文本字段（非空白才取；非 String 值 toString 兜底）
+ *
+ * @param gameConfig 回调 gameConfig
+ * @param key 键名
+ * @param fallback 缺省值
+ * @return 字段文本或缺省值
+ */
+ private static String textOf(Map gameConfig, String key, String fallback) {
+ if (gameConfig == null) {
+ return fallback;
+ }
+ Object value = gameConfig.get(key);
+ if (value == null || !StringUtils.hasText(String.valueOf(value))) {
+ return fallback;
+ }
+ return String.valueOf(value);
+ }
+
+ /**
+ * 按上限截断文本（GamePackage meta 字段长度门禁）
+ *
+ * @param text 原文本
+ * @param max 最大字符数
+ * @return 截断后文本
+ */
+ private static String truncate(String text, int max) {
+ if (text == null) {
+ return "";
+ }
+ return text.length() <= max ? text : text.substring(0, max);
+ }
+
+ /**
+ * 格式化 provenance.generatedAt（ISO 8601 带时区；取任务创建时间而非墙钟——保证同输入组包字节可复现）
+ *
+ * @param createTime 任务创建时间（可空，空则省略该键）
+ * @return ISO 8601 文本；createTime 为空返回 null
+ */
+ private static String formatGeneratedAt(LocalDateTime createTime) {
+ if (createTime == null) {
+ return null;
+ }
+ return createTime.atZone(ZoneId.systemDefault()).format(DateTimeFormatter.ISO_OFFSET_DATE_TIME);
+ }
+
+ /**
+ * 计算文本 UTF-8 字节的 sha256（hex 小写 64 位；契约#4 manifest.checksum 口径）
+ *
+ * @param text 待摘要文本
+ * @return 64 位小写 hex
+ */
+ private static String sha256Hex(String text) {
+ try {
+ MessageDigest digest = MessageDigest.getInstance("SHA-256");
+ byte[] hash = digest.digest(text.getBytes(StandardCharsets.UTF_8));
+ StringBuilder sb = new StringBuilder(hash.length * 2);
+ for (byte b : hash) {
+ sb.append(Character.forDigit((b >> 4) & 0xF, 16)).append(Character.forDigit(b & 0xF, 16));
+ }
+ return sb.toString();
+ } catch (NoSuchAlgorithmException e) {
+ // JVM 必带 SHA-256，理论不可达；防御性上抛（写链失败语义，外层补偿兜底）
+ throw new IllegalStateException("SHA-256 算法不可用", e);
+ }
+ }
+
+}
diff --git a/game-cloud/game-module-aigc/game-module-aigc-server/src/test/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackServiceImplTest.java b/game-cloud/game-module-aigc/game-module-aigc-server/src/test/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackServiceImplTest.java
new file mode 100644
index 00000000..7b6afd90
--- /dev/null
+++ b/game-cloud/game-module-aigc/game-module-aigc-server/src/test/java/cn/wanxiang/game/module/aigc/service/callback/DifyCallbackServiceImplTest.java
@@ -0,0 +1,406 @@
+package cn.wanxiang.game.module.aigc.service.callback;
+
+import cn.wanxiang.game.module.aigc.controller.admin.task.vo.DifyCallbackReqVO;
+import cn.wanxiang.game.module.aigc.dal.dataobject.task.AigcTaskDO;
+import cn.wanxiang.game.module.aigc.dal.mysql.task.AigcTaskMapper;
+import cn.wanxiang.game.module.aigc.enums.AigcTaskStatusEnum;
+import cn.wanxiang.game.module.aigc.service.task.AigcTaskService;
+import cn.wanxiang.game.module.project.api.ProjectVersionApi;
+import cn.wanxiang.game.module.project.dto.ProjectVersionCreateForPackageReqDTO;
+import cn.wanxiang.game.module.runtime.api.RuntimePackageApi;
+import cn.wanxiang.game.module.runtime.dto.RuntimePackageStoreReqDTO;
+import cn.iocoder.yudao.framework.common.exception.ServiceException;
+import cn.iocoder.yudao.framework.common.pojo.CommonResult;
+import cn.iocoder.yudao.framework.test.core.ut.BaseMockitoUnitTest;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.mockito.InOrder;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.time.LocalDateTime;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import static cn.wanxiang.game.module.aigc.enums.ErrorCodeConstants.*;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.Mockito.*;
+
+/**
+ * {@link DifyCallbackServiceImpl} + {@link DifyCallbackTxService} 单元测试（纯 Mockito，不依赖 DB）
+ *
+ * 组装方式：内层事务 Bean 用 @InjectMocks 注入 mock 依赖（真实逻辑），外层编排手工 new 并持内层真实例——
+ * 外层补偿链（catch 写链异常 → compensateMarkFailed 置 failed(llm_error)）可端到端验证。
+ * 验证边界（§8.7 注，诚实记录）：单测不经 Spring 代理，@Transactional 真回滚无法用 Mockito 验证——
+ * 以「写链异常向上传播」断言把关（异常抛出即代理事务必回滚），三表回滚正向断言由 §12.3 staging 冒烟补位。
+ * 覆盖 §8.7 全部 10 项要求（含 gameConfig 缺失/task.gameId 空拆分为两用例 + status 非法补充用例，共 12 用例）。
+ *
+ * 注意：mock {@code BaseMapper.insert/updateById} 一律用 {@code any(AigcTaskDO.class)} 消歧——
+ * BaseMapper 存在 insert(T)/updateById(T) 与 Collection 重载，裸 {@code any()} 会因重载编译失败。
+ *
+ * @author 造梦AI
+ */
+class DifyCallbackServiceImplTest extends BaseMockitoUnitTest {
+
+ /** 内层事务 Bean（真实逻辑，注入下方 mock 依赖） */
+ @InjectMocks
+ private DifyCallbackTxService txService;
+
+ @Mock
+ private AigcTaskMapper aigcTaskMapper;
+
+ @Mock
+ private AigcTaskService aigcTaskService;
+
+ @Mock
+ private ProjectVersionApi projectVersionApi;
+
+ @Mock
+ private RuntimePackageApi runtimePackageApi;
+
+ /** 外层编排（被测入口，手工组装持内层真实例） */
+ private DifyCallbackServiceImpl callbackService;
+
+ /** 解析组包 JSON 用（仅测试侧读取断言，与生产序列化器无共享状态） */
+ private static final ObjectMapper JSON = new ObjectMapper();
+
+ @BeforeEach
+ void setUpService() {
+ // MockitoExtension 已完成 @InjectMocks 注入，此处组装外层（构造器注入内层真实例）
+ callbackService = new DifyCallbackServiceImpl(txService);
+ }
+
+ // ============================== 用例1：succeeded 全链 ==============================
+
+ @Test
+ void testHandleCallback_succeededFullChain() throws Exception {
+ // 准备：queued 任务命中 + 建版本/落包 mock 成功
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenReturn(queuedTask());
+ when(projectVersionApi.createForPackage(any(ProjectVersionCreateForPackageReqDTO.class)))
+ .thenReturn(CommonResult.success(2048L));
+ when(runtimePackageApi.storeForVersion(any(RuntimePackageStoreReqDTO.class)))
+ .thenReturn(CommonResult.success(99L));
+
+ // 调用
+ Boolean result = callbackService.handleCallback(succeededReq());
+ assertTrue(result);
+
+ // InOrder 断言调用顺序：建版本 → 落包 → 回填任务（§8.4 步骤④⑥⑦）
+ ArgumentCaptor versionCaptor =
+ ArgumentCaptor.forClass(ProjectVersionCreateForPackageReqDTO.class);
+ ArgumentCaptor storeCaptor =
+ ArgumentCaptor.forClass(RuntimePackageStoreReqDTO.class);
+ InOrder inOrder = inOrder(projectVersionApi, runtimePackageApi, aigcTaskService);
+ inOrder.verify(projectVersionApi).createForPackage(versionCaptor.capture());
+ inOrder.verify(runtimePackageApi).storeForVersion(storeCaptor.capture());
+ inOrder.verify(aigcTaskService).completeWithVersion(77L, 2048L);
+
+ // 建版本入参断言（checksum 鸡蛋环 §16-3：v1 不回写 version 的 checksum/bundleSize，落空串/0）
+ ProjectVersionCreateForPackageReqDTO versionReq = versionCaptor.getValue();
+ assertEquals(5L, versionReq.getGameId());
+ assertEquals("77", versionReq.getGenTaskId()); // genTaskId = String(taskId) 幂等键
+ assertEquals("", versionReq.getPackageUrl());
+ assertEquals(0L, versionReq.getBundleSize());
+ assertEquals("", versionReq.getChecksum());
+
+ // 组包 JSON 过 GamePackage（契约#4）必填字段断言
+ RuntimePackageStoreReqDTO storeReq = storeCaptor.getValue();
+ JsonNode root = JSON.readTree(storeReq.getManifestJson());
+ assertEquals("1.0", root.get("schemaVersion").asText());
+ assertEquals("5", root.get("gameId").asText()); // 字符串化
+ assertEquals("2048", root.get("versionId").asText()); // 字符串化
+ assertEquals("clicker", root.get("templateId").asText());
+ assertEquals(12, root.get("gameConfig").get("target").asInt()); // gameConfig 原样注入
+ assertTrue(root.get("assets").isArray()); // assets 空则 []
+ JsonNode manifest = root.get("manifest");
+ assertEquals("1.0.0", manifest.get("runtimeVersion").asText());
+ assertEquals("index.html", manifest.get("entry").asText());
+ assertEquals("eager", manifest.get("preloadPolicy").asText());
+ assertTrue(manifest.get("bundleSize").asLong() > 0); // T_base 字节数已回填
+ assertEquals(64, manifest.get("checksum").asText().length()); // 包内自述 C（64 位 hex，非占位全 0）
+ assertNotEquals("0".repeat(64), manifest.get("checksum").asText());
+ JsonNode meta = root.get("meta");
+ assertEquals("魔法点点乐", meta.get("title").asText());
+ assertTrue(meta.get("summary").asText().contains("魔法森林")); // summary 回落 theme
+ assertTrue(meta.get("cover").asText().startsWith("data:image/gif"));
+ assertEquals("all", meta.get("ageRating").asText());
+ assertEquals("hash-xyz", root.get("provenance").get("promptHash").asText());
+
+ // checksum 自洽（§8.4-5）：对外 checksum = sha256(落库文本 T1)——与宿主对 manifest 端点原文校验同源
+ assertEquals(sha256Hex(storeReq.getManifestJson()), storeReq.getChecksum());
+ // bundleSize 入库值与包内 manifest.bundleSize 一致
+ assertEquals(manifest.get("bundleSize").asLong(), storeReq.getBundleSize());
+ // 落包入参元数据
+ assertEquals(5L, storeReq.getGameId());
+ assertEquals(2048L, storeReq.getVersionId());
+ assertEquals("clicker", storeReq.getTemplateId());
+ }
+
+ // ============================== 用例2：组包字节可复现 ==============================
+
+ @Test
+ void testHandleCallback_packageBytesReproducible() {
+ // 准备：每次返回全新等值 queued 任务（不发生幂等短路，两次都走完整组包）
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenAnswer(inv -> queuedTask());
+ when(projectVersionApi.createForPackage(any(ProjectVersionCreateForPackageReqDTO.class)))
+ .thenReturn(CommonResult.success(2048L));
+ when(runtimePackageApi.storeForVersion(any(RuntimePackageStoreReqDTO.class)))
+ .thenReturn(CommonResult.success(99L));
+
+ // 同输入回调两次
+ callbackService.handleCallback(succeededReq());
+ callbackService.handleCallback(succeededReq());
+
+ // 断言：两次组包文本逐字节一致 + checksum 一致（LinkedHashMap 插入序 + 固定序列化器 + generatedAt 取任务创建时间）
+ ArgumentCaptor captor = ArgumentCaptor.forClass(RuntimePackageStoreReqDTO.class);
+ verify(runtimePackageApi, times(2)).storeForVersion(captor.capture());
+ List reqs = captor.getAllValues();
+ assertEquals(reqs.get(0).getManifestJson(), reqs.get(1).getManifestJson());
+ assertEquals(reqs.get(0).getChecksum(), reqs.get(1).getChecksum());
+ assertEquals(reqs.get(0).getBundleSize(), reqs.get(1).getBundleSize());
+ }
+
+ // ============================== 用例3：failed 分支 ==============================
+
+ @Test
+ void testHandleCallback_failedBranch() {
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenReturn(queuedTask());
+ DifyCallbackReqVO reqVO = baseReq("failed");
+ reqVO.setFailureReason("intent_unclear"); // 契约#6 七值之一
+
+ assertTrue(callbackService.handleCallback(reqVO));
+
+ // updateById 序列：受理置 1 → 置失败终态（status=3 + failure_reason + finishTime）
+ ArgumentCaptor captor = ArgumentCaptor.forClass(AigcTaskDO.class);
+ verify(aigcTaskMapper, times(2)).updateById(captor.capture());
+ assertEquals(AigcTaskStatusEnum.RUNNING.getStatus(), captor.getAllValues().get(0).getStatus());
+ AigcTaskDO last = captor.getAllValues().get(1);
+ assertEquals(AigcTaskStatusEnum.FAILED.getStatus(), last.getStatus());
+ assertEquals("intent_unclear", last.getFailureReason());
+ assertNotNull(last.getFinishTime());
+ // failed 分支不触发任何跨模块 -api 调用
+ verifyNoInteractions(projectVersionApi, runtimePackageApi);
+ verify(aigcTaskService, never()).completeWithVersion(anyLong(), anyLong());
+ }
+
+ // ============================== 用例4：幂等短路 ==============================
+
+ @Test
+ void testHandleCallback_succeededIdempotentShortCircuit() {
+ // 任务已 SUCCEEDED 且 version_id 非空 → 幂等短路返回 true，零写入
+ AigcTaskDO task = queuedTask();
+ task.setStatus(AigcTaskStatusEnum.SUCCEEDED.getStatus());
+ task.setVersionId(2048L);
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenReturn(task);
+
+ assertTrue(callbackService.handleCallback(succeededReq()));
+
+ verify(aigcTaskMapper, never()).updateById(any(AigcTaskDO.class)); // 带类型消歧
+ verifyNoInteractions(projectVersionApi, runtimePackageApi);
+ }
+
+ // ============================== 用例5：终态拒重入 ==============================
+
+ @Test
+ void testHandleCallback_finalStateRejected() {
+ // 任务已 FAILED 终态 → 抛 1-101-003-001，零写入（编排器对该任务走新任务重放）
+ AigcTaskDO task = queuedTask();
+ task.setStatus(AigcTaskStatusEnum.FAILED.getStatus());
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenReturn(task);
+
+ ServiceException ex = assertThrows(ServiceException.class,
+ () -> callbackService.handleCallback(succeededReq()));
+ assertEquals(AIGC_CALLBACK_TASK_FINAL.getCode(), ex.getCode());
+ verify(aigcTaskMapper, never()).updateById(any(AigcTaskDO.class)); // 终态不被补偿覆写（不补偿白名单）
+ verifyNoInteractions(projectVersionApi, runtimePackageApi);
+ }
+
+ // ============================== 用例6：traceId 未命中 ==============================
+
+ @Test
+ void testHandleCallback_traceIdNotFound() {
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenReturn(null);
+
+ ServiceException ex = assertThrows(ServiceException.class,
+ () -> callbackService.handleCallback(succeededReq()));
+ assertEquals(AIGC_TASK_NOT_EXISTS.getCode(), ex.getCode());
+ verify(aigcTaskMapper, never()).updateById(any(AigcTaskDO.class)); // 无任何写入
+ }
+
+ // ============================== 用例7a：gameConfig 缺失 → 业务性失败 ==============================
+
+ @Test
+ void testHandleCallback_missingGameConfig_configInvalid() {
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenReturn(queuedTask());
+ DifyCallbackReqVO reqVO = baseReq("succeeded"); // 不带 gameConfig
+
+ // 业务性失败：不抛异常，正常返回 true（同事务置 failed+config_invalid 后提交）
+ assertTrue(callbackService.handleCallback(reqVO));
+
+ ArgumentCaptor captor = ArgumentCaptor.forClass(AigcTaskDO.class);
+ verify(aigcTaskMapper, times(2)).updateById(captor.capture()); // 受理置 1 + 置失败
+ AigcTaskDO last = captor.getAllValues().get(1);
+ assertEquals(AigcTaskStatusEnum.FAILED.getStatus(), last.getStatus());
+ assertEquals("config_invalid", last.getFailureReason());
+ assertNotNull(last.getFinishTime());
+ verifyNoInteractions(projectVersionApi, runtimePackageApi); // 不进写链
+ }
+
+ // ============================== 用例7b：task.gameId 空 → 业务性失败 ==============================
+
+ @Test
+ void testHandleCallback_missingTaskGameId_configInvalid() {
+ AigcTaskDO task = queuedTask();
+ task.setGameId(null); // GamePackage.gameId 必填，无法组包
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenReturn(task);
+
+ assertTrue(callbackService.handleCallback(succeededReq()));
+
+ ArgumentCaptor captor = ArgumentCaptor.forClass(AigcTaskDO.class);
+ verify(aigcTaskMapper, times(2)).updateById(captor.capture());
+ AigcTaskDO last = captor.getAllValues().get(1);
+ assertEquals(AigcTaskStatusEnum.FAILED.getStatus(), last.getStatus());
+ assertEquals("config_invalid", last.getFailureReason());
+ verifyNoInteractions(projectVersionApi, runtimePackageApi);
+ }
+
+ // ============================== 用例8：createForPackage 抛错 → 上抛 + 补偿 ==============================
+
+ @Test
+ void testHandleCallback_createForPackageError_compensates() {
+ // 每次返回全新 queued 任务（补偿方法内部会再次 selectByTraceId 定位）
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenAnswer(inv -> queuedTask());
+ when(projectVersionApi.createForPackage(any(ProjectVersionCreateForPackageReqDTO.class)))
+ .thenThrow(new ServiceException(999_000_001, "建版本失败（模拟写链异常）"));
+
+ // 写链 ServiceException 原样上抛（异常传播 = 代理事务回滚的把关断言，§8.7 注）
+ ServiceException ex = assertThrows(ServiceException.class,
+ () -> callbackService.handleCallback(succeededReq()));
+ assertEquals(999_000_001, ex.getCode());
+
+ // 补偿置 failed(llm_error)：updateById 序列 = 受理置 1 → 补偿置失败（§16-2 归桶）
+ ArgumentCaptor captor = ArgumentCaptor.forClass(AigcTaskDO.class);
+ verify(aigcTaskMapper, times(2)).updateById(captor.capture());
+ AigcTaskDO last = captor.getAllValues().get(1);
+ assertEquals(AigcTaskStatusEnum.FAILED.getStatus(), last.getStatus());
+ assertEquals("llm_error", last.getFailureReason());
+ assertNotNull(last.getFinishTime());
+ // 写链断在建版本：不触发落包与回填
+ verifyNoInteractions(runtimePackageApi);
+ verify(aigcTaskService, never()).completeWithVersion(anyLong(), anyLong());
+ }
+
+ // ============================== 用例9：storeForVersion 抛错 → 上抛 + 补偿 ==============================
+
+ @Test
+ void testHandleCallback_storeForVersionError_compensates() {
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenAnswer(inv -> queuedTask());
+ when(projectVersionApi.createForPackage(any(ProjectVersionCreateForPackageReqDTO.class)))
+ .thenReturn(CommonResult.success(2048L));
+ when(runtimePackageApi.storeForVersion(any(RuntimePackageStoreReqDTO.class)))
+ .thenThrow(new ServiceException(1_102_001_001, "运行包不存在或未就绪（模拟落包失败）"));
+
+ ServiceException ex = assertThrows(ServiceException.class,
+ () -> callbackService.handleCallback(succeededReq()));
+ assertEquals(1_102_001_001, ex.getCode());
+
+ // 补偿置 failed(llm_error)；回填不被触发（写链断在落包步骤⑥）
+ ArgumentCaptor captor = ArgumentCaptor.forClass(AigcTaskDO.class);
+ verify(aigcTaskMapper, times(2)).updateById(captor.capture());
+ AigcTaskDO last = captor.getAllValues().get(1);
+ assertEquals(AigcTaskStatusEnum.FAILED.getStatus(), last.getStatus());
+ assertEquals("llm_error", last.getFailureReason());
+ verify(aigcTaskService, never()).completeWithVersion(anyLong(), anyLong());
+ }
+
+ // ============================== 用例10：failureReason 非法 ==============================
+
+ @Test
+ void testHandleCallback_invalidFailureReason() {
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenReturn(queuedTask());
+ DifyCallbackReqVO reqVO = baseReq("failed");
+ reqVO.setFailureReason("oops_not_in_enum"); // 不在契约#6 七值枚举内
+
+ ServiceException ex = assertThrows(ServiceException.class,
+ () -> callbackService.handleCallback(reqVO));
+ assertEquals(AIGC_CALLBACK_STATUS_INVALID.getCode(), ex.getCode());
+ // 参数非法属不补偿白名单：仅受理置 1 一次写入（随真实事务回滚），无补偿置 failed
+ verify(aigcTaskMapper, times(1)).updateById(any(AigcTaskDO.class));
+ verifyNoInteractions(projectVersionApi, runtimePackageApi);
+ }
+
+ // ============================== 用例11（补充）：status 非法 ==============================
+
+ @Test
+ void testHandleCallback_invalidStatus() {
+ when(aigcTaskMapper.selectByTraceId("aigc-trace-1")).thenReturn(queuedTask());
+ DifyCallbackReqVO reqVO = baseReq("running"); // 契约#6 仅 succeeded/failed
+
+ ServiceException ex = assertThrows(ServiceException.class,
+ () -> callbackService.handleCallback(reqVO));
+ assertEquals(AIGC_CALLBACK_STATUS_INVALID.getCode(), ex.getCode());
+ verify(aigcTaskMapper, times(1)).updateById(any(AigcTaskDO.class)); // 同用例10：不补偿
+ verifyNoInteractions(projectVersionApi, runtimePackageApi);
+ }
+
+ // ============================== 测试夹具 ==============================
+
+ /** 构造排队中的生成任务（id=77/gameId=5/clicker；createTime 固定——组包 generatedAt 字节可复现的输入面） */
+ private static AigcTaskDO queuedTask() {
+ AigcTaskDO task = new AigcTaskDO();
+ task.setId(77L);
+ task.setGameId(5L);
+ task.setTemplateId("clicker");
+ task.setStatus(AigcTaskStatusEnum.QUEUED.getStatus());
+ task.setTraceId("aigc-trace-1");
+ task.setPromptHash("hash-xyz");
+ task.setCreateTime(LocalDateTime.of(2026, 6, 9, 12, 0, 0));
+ return task;
+ }
+
+ /** 构造指定 status 的回调骨架（traceId 对齐夹具任务） */
+ private static DifyCallbackReqVO baseReq(String status) {
+ DifyCallbackReqVO reqVO = new DifyCallbackReqVO();
+ reqVO.setTraceId("aigc-trace-1");
+ reqVO.setStatus(status);
+ return reqVO;
+ }
+
+ /** 构造合法 succeeded 回调（带 clicker gameConfig；LinkedHashMap 保键序与生产反序列化形态一致） */
+ private static DifyCallbackReqVO succeededReq() {
+ DifyCallbackReqVO reqVO = baseReq("succeeded");
+ reqVO.setTemplateId("clicker");
+ Map config = new LinkedHashMap<>();
+ config.put("templateId", "clicker");
+ config.put("title", "魔法点点乐");
+ config.put("theme", "魔法森林收集星星");
+ config.put("scoreLabel", "星星");
+ config.put("target", 12);
+ reqVO.setGameConfig(config);
+ return reqVO;
+ }
+
+ /** 测试侧独立 sha256（与生产实现独立实现同口径，交叉验证 checksum 自洽） */
+ private static String sha256Hex(String text) {
+ try {
+ MessageDigest digest = MessageDigest.getInstance("SHA-256");
+ byte[] hash = digest.digest(text.getBytes(StandardCharsets.UTF_8));
+ StringBuilder sb = new StringBuilder(hash.length * 2);
+ for (byte b : hash) {
+ sb.append(Character.forDigit((b >> 4) & 0xF, 16)).append(Character.forDigit(b & 0xF, 16));
+ }
+ return sb.toString();
+ } catch (Exception e) {
+ throw new IllegalStateException("SHA-256 不可用", e);
+ }
+ }
+
+}
diff --git a/game-cloud/game-module-runtime/game-module-runtime-api/src/main/java/cn/wanxiang/game/module/runtime/api/RuntimePackageApi.java b/game-cloud/game-module-runtime/game-module-runtime-api/src/main/java/cn/wanxiang/game/module/runtime/api/RuntimePackageApi.java
index 185531e8..19764010 100644
--- a/game-cloud/game-module-runtime/game-module-runtime-api/src/main/java/cn/wanxiang/game/module/runtime/api/RuntimePackageApi.java
+++ b/game-cloud/game-module-runtime/game-module-runtime-api/src/main/java/cn/wanxiang/game/module/runtime/api/RuntimePackageApi.java
@@ -1,13 +1,16 @@
package cn.wanxiang.game.module.runtime.api;
+import cn.wanxiang.game.module.runtime.dto.RuntimePackageStoreReqDTO;
import cn.wanxiang.game.module.runtime.enums.ApiConstants;
import cn.iocoder.yudao.framework.common.pojo.CommonResult;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
/**
@@ -59,4 +62,22 @@ public interface RuntimePackageApi {
@Parameter(name = "versionId", description = "版本 ID", required = true, example = "1024")
CommonResult getStatus(@RequestParam("versionId") Long versionId);
+ /**
+ * 落包（agent 闭环/未来真 Dify 共用）：建 game_runtime_package 行（status=0 预览就绪）+ 写整包 manifest（package_json）
+ *
+ * 事务约束（与本接口既有纪律一致）：MVP 单体内由 RuntimePackageApiImpl(@RestController @Primary) 就地解析，
+ * 调用方（aigc 回调）在本地 @Transactional 内调用，本方法抛错则回调事务整体回滚（三表全回滚）；
+ * 事务内禁止 Feign/HTTP/@Async/REQUIRES_NEW。拆微服务后按 {@link ApiConstants#NAME} 走真实 Feign（届时回调事务边界另议，列 M-b）。
+ * 幂等（upsert by versionId，uk_version 唯一键）：
+ * - 无行 → 插入新行 status=0 + 写 manifest；
+ * - 已有行且 status=0 → 更新元数据列 + 覆写 manifest（同 genTaskId 重放安全）；
+ * - 已有行且 status=1 已发布：req.checksum 与行内一致 → 幂等返回；不一致 → 抛 1-102-001-001（保护已发布包，禁止事后篡改）。
+ *
+ * @param req 落包入参（gameId/versionId/templateId/manifestJson 原始 JSON 文本/checksum/bundleSize/entry/runtimeVersion/preloadPolicy）
+ * @return 运行包行 ID（CommonResult 包裹）
+ */
+ @PostMapping(PREFIX + "/store-for-version")
+ @Operation(summary = "落包：建运行包行(status=0)+写 manifest（agent 闭环/Dify 共用）")
+ CommonResult storeForVersion(@RequestBody @Valid RuntimePackageStoreReqDTO req);
+
}
diff --git a/game-cloud/game-module-runtime/game-module-runtime-api/src/main/java/cn/wanxiang/game/module/runtime/dto/RuntimePackageStoreReqDTO.java b/game-cloud/game-module-runtime/game-module-runtime-api/src/main/java/cn/wanxiang/game/module/runtime/dto/RuntimePackageStoreReqDTO.java
new file mode 100644
index 00000000..eecb9b1c
--- /dev/null
+++ b/game-cloud/game-module-runtime/game-module-runtime-api/src/main/java/cn/wanxiang/game/module/runtime/dto/RuntimePackageStoreReqDTO.java
@@ -0,0 +1,79 @@
+package cn.wanxiang.game.module.runtime.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Pattern;
+import lombok.Data;
+
+/**
+ * 落包跨模块入参（aigc 回调 PackageFactory → runtime，对应表 game_runtime_package 的写入镜像）
+ *
+ * 用途：aigc 回调实做（HJ-AGENT-LOOP-EXEC-001 §8.4 步骤⑥）组包成功后调
+ * {@code RuntimePackageApi.storeForVersion} 建 game_runtime_package 行（status=0 预览就绪）+ 写整包 manifest，
+ * agent 闭环 / 未来真 Dify 共用同一落包面。
+ * 幂等（upsert by versionId，uk_version 唯一键）：三分支语义见 {@code RuntimePackageApi#storeForVersion} javadoc。
+ * 字节一致性约束（§3.4 C4）：manifestJson 为 GamePackage 原始 JSON 文本，存储与返回均不 parse/re-serialize，
+ * 宿主对 manifest 端点响应原文算 sha256 与 checksum 严格比对，任何重序列化都会破坏校验。
+ * sandbox_attr/allow_origins 不入参：沿表默认值（宿主现版本硬编码 sandbox 属性，GamePlayer.vue:437）；
+ * package_url 不入参：留表默认空串，RuntimeConvert 据空值回落 DB manifest 路径（MVP 无 OSS 形态）。
+ *
+ * @author 造梦AI
+ */
+@Data
+public class RuntimePackageStoreReqDTO {
+
+ /**
+ * 游戏 ID（game_runtime_package.game_id；必填）
+ */
+ @NotNull(message = "gameId 不能为空")
+ private Long gameId;
+
+ /**
+ * 版本 ID（game_runtime_package.version_id；必填，uk_version 幂等键）
+ */
+ @NotNull(message = "versionId 不能为空")
+ private Long versionId;
+
+ /**
+ * 玩法模板 ID（game_runtime_package.template_id；必填，宿主据此选 Runtime 容器）
+ */
+ @NotBlank(message = "templateId 不能为空")
+ private String templateId;
+
+ /**
+ * GamePackage 原始 JSON 文本（→ game_runtime_package.package_json；必填。
+ * 存储与返回均不 parse/re-serialize，保字节一致——§3.4 C4 既有纪律）
+ */
+ @NotBlank(message = "manifestJson 不能为空")
+ private String manifestJson;
+
+ /**
+ * 整包 sha256（game_runtime_package.checksum；必填，64 位 hex。
+ * = sha256(manifestJson 落库文本)，与宿主对 manifest 端点响应原文的校验同源）
+ */
+ @NotBlank(message = "checksum 不能为空")
+ @Pattern(regexp = "^[a-f0-9]{64}$", message = "checksum 必须为 64 位小写十六进制 sha256")
+ private String checksum;
+
+ /**
+ * 包总字节（game_runtime_package.bundle_size；必填，编译期门禁语义）
+ */
+ @NotNull(message = "bundleSize 不能为空")
+ private Long bundleSize;
+
+ /**
+ * 入口文件相对路径（game_runtime_package.entry；可空，服务端缺省 "index.html"）
+ */
+ private String entry;
+
+ /**
+ * 目标 Canvas Runtime 版本（game_runtime_package.runtime_version；可空，服务端缺省 "1.0.0"）
+ */
+ private String runtimeVersion;
+
+ /**
+ * 预加载策略（game_runtime_package.preload_policy；可空，服务端缺省 "eager"）
+ */
+ private String preloadPolicy;
+
+}
diff --git a/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/api/RuntimePackageApiImpl.java b/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/api/RuntimePackageApiImpl.java
index 3a48d066..467d7398 100644
--- a/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/api/RuntimePackageApiImpl.java
+++ b/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/api/RuntimePackageApiImpl.java
@@ -1,5 +1,6 @@
package cn.wanxiang.game.module.runtime.api;
+import cn.wanxiang.game.module.runtime.dto.RuntimePackageStoreReqDTO;
import cn.wanxiang.game.module.runtime.service.pkg.RuntimePackageService;
import cn.iocoder.yudao.framework.common.pojo.CommonResult;
import jakarta.annotation.Resource;
@@ -10,10 +11,11 @@ import org.springframework.web.bind.annotation.RestController;
import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
/**
- * 运行包发布 API 实现（黄金闭环 §3.2 C2，提供 RESTful 接口给跨模块 Feign 调用：发布编排翻包 + 可见态校验）
+ * 运行包发布 API 实现（黄金闭环 §3.2 C2，提供 RESTful 接口给跨模块 Feign 调用：发布编排翻包 + 可见态校验 + 落包）
*
* @RestController + @Primary：与 yudao DictDataApiImpl / 既有 ProjectApiImpl 同构——单体内同进程调用走本实现，拆微服务后走 Feign（守门④/§3.2 H5）。
- * 仅委托 {@link RuntimePackageService}：publish 翻包 0→1（不在此回写 version/project，那归 project 编排，Codex H6）；getStatus 供 feed 写侧可见态 enforce。
+ * 仅委托 {@link RuntimePackageService}：publish 翻包 0→1（不在此回写 version/project，那归 project 编排，Codex H6）；getStatus 供 feed 写侧可见态 enforce；
+ * storeForVersion 落包（HJ-AGENT-LOOP-EXEC-001 §8.5：aigc 回调事务内本地调用，抛错则回调三表事务整体回滚）。
*
* @author 造梦AI
*/
@@ -38,4 +40,10 @@ public class RuntimePackageApiImpl implements RuntimePackageApi {
return success(runtimePackageService.getPackageStatus(versionId));
}
+ @Override
+ public CommonResult storeForVersion(RuntimePackageStoreReqDTO req) {
+ // 落包：委托 RuntimePackageService.storeForVersion（建行 status=0 + 写 manifest；幂等三分支语义在 Service 承载）
+ return success(runtimePackageService.storeForVersion(req));
+ }
+
}
diff --git a/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageService.java b/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageService.java
index 44c64895..61fa0f50 100644
--- a/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageService.java
+++ b/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageService.java
@@ -1,6 +1,7 @@
package cn.wanxiang.game.module.runtime.service.pkg;
import cn.wanxiang.game.module.runtime.dal.dataobject.pkg.RuntimePackageDO;
+import cn.wanxiang.game.module.runtime.dto.RuntimePackageStoreReqDTO;
/**
* 版本运行包 Service 接口
@@ -49,4 +50,20 @@ public interface RuntimePackageService {
*/
Integer getPackageStatus(Long versionId);
+ /**
+ * 落包（HJ-AGENT-LOOP-EXEC-001 §8.5）：建 game_runtime_package 行（status=0 预览就绪）+ 写整包 manifest（package_json），一步完成
+ *
+ * 幂等三分支（upsert by versionId，uk_version 唯一键）：
+ * - 无行 → 插入新行 status=0 + 写 manifest；
+ * - 已有行且 status=0 → 更新元数据列 + 覆写 manifest（同 genTaskId 重放安全）；
+ * - 已有行且 status=1 已发布：req.checksum 与行内一致 → 幂等返回；不一致 → 抛 RUNTIME_PACKAGE_NOT_READY（保护已发布包，禁止事后篡改）。
+ * 内部序列：判幂等分支 → insert/update RuntimePackageDO → PackageStore.putManifest（此时行必已存在；
+ * putManifest 未命中行显式抛错回滚，杜绝带病链 Z1）。
+ * 事务语义：由调用方（aigc 回调 @Transactional）控制，本方法 REQUIRED 合并；抛错则调用方事务整体回滚。
+ *
+ * @param req 落包入参（gameId/versionId/templateId/manifestJson/checksum/bundleSize/entry/runtimeVersion/preloadPolicy）
+ * @return 运行包行 ID
+ */
+ Long storeForVersion(RuntimePackageStoreReqDTO req);
+
}
diff --git a/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageServiceImpl.java b/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageServiceImpl.java
index e0f760bc..a7aeddb7 100644
--- a/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageServiceImpl.java
+++ b/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageServiceImpl.java
@@ -2,11 +2,17 @@ package cn.wanxiang.game.module.runtime.service.pkg;
import cn.wanxiang.game.module.runtime.dal.dataobject.pkg.RuntimePackageDO;
import cn.wanxiang.game.module.runtime.dal.mysql.pkg.RuntimePackageMapper;
+import cn.wanxiang.game.module.runtime.dto.RuntimePackageStoreReqDTO;
import cn.wanxiang.game.module.runtime.enums.PackageStatusEnum;
import cn.wanxiang.game.module.runtime.enums.RuntimeSceneEnum;
+import cn.wanxiang.game.module.runtime.service.pkg.store.PackageStore;
import jakarta.annotation.Resource;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.util.StringUtils;
+
+import java.util.Objects;
import static cn.wanxiang.game.module.runtime.enums.ErrorCodeConstants.RUNTIME_PACKAGE_NOT_PUBLISHED;
import static cn.wanxiang.game.module.runtime.enums.ErrorCodeConstants.RUNTIME_PACKAGE_NOT_READY;
@@ -25,9 +31,22 @@ import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionU
@Service
public class RuntimePackageServiceImpl implements RuntimePackageService {
+ /** 落包入参缺省值：入口文件相对路径（对齐 GamePackage manifest.entry MVP 形态） */
+ private static final String DEFAULT_ENTRY = "index.html";
+ /** 落包入参缺省值：Canvas Runtime 版本（对齐 GamePackage manifest.runtimeVersion MVP 形态） */
+ private static final String DEFAULT_RUNTIME_VERSION = "1.0.0";
+ /** 落包入参缺省值：预加载策略（对齐 GamePackage manifest.preloadPolicy MVP 形态） */
+ private static final String DEFAULT_PRELOAD_POLICY = "eager";
+
@Resource
private RuntimePackageMapper runtimePackageMapper;
+ /**
+ * 整包 manifest 存储抽象（§3.4 C4）：MVP=DbPackageStore（写 game_runtime_package.package_json），M3 换 OSS impl 调用方不变。
+ */
+ @Resource
+ private PackageStore packageStore;
+
@Override
public RuntimePackageDO getPackageManifest(Long versionId, String scene, Long userId) {
// 取就绪运行包（uk_version 唯一）
@@ -87,6 +106,82 @@ public class RuntimePackageServiceImpl implements RuntimePackageService {
return pkg == null ? null : pkg.getStatus();
}
+ @Override
+ @Transactional(rollbackFor = Exception.class) // 与调用方（aigc 回调）事务 REQUIRED 合并；insert/update+putManifest 两写原子，任一失败全回滚
+ public Long storeForVersion(RuntimePackageStoreReqDTO req) {
+ // 幂等分支判定入口：按 versionId 取既有行（uk_version 唯一键，一个版本一行）
+ RuntimePackageDO existing = runtimePackageMapper.selectByVersionId(req.getVersionId());
+
+ // 分支①：无行 → 插入新行 status=0 预览就绪 + 写 manifest
+ if (existing == null) {
+ RuntimePackageDO insert = new RuntimePackageDO();
+ insert.setGameId(req.getGameId());
+ insert.setVersionId(req.getVersionId());
+ insert.setTemplateId(req.getTemplateId());
+ insert.setEntry(defaultIfBlank(req.getEntry(), DEFAULT_ENTRY));
+ insert.setRuntimeVersion(defaultIfBlank(req.getRuntimeVersion(), DEFAULT_RUNTIME_VERSION));
+ insert.setPreloadPolicy(defaultIfBlank(req.getPreloadPolicy(), DEFAULT_PRELOAD_POLICY));
+ insert.setBundleSize(req.getBundleSize());
+ insert.setChecksum(req.getChecksum());
+ insert.setStatus(PackageStatusEnum.PREVIEW_READY.getStatus());
+ // package_url/sandbox_attr/allow_origins 不设：沿 V3 DDL 表默认值
+ // （packageUrl 留空串 → RuntimeConvert 回落 DB manifest 路径，MVP 无 OSS 形态自动成立）
+ runtimePackageMapper.insert(insert);
+ // 行已存在后写整包 manifest（putManifest 未命中行显式抛错回滚，Z1 带病链在此杜绝）
+ packageStore.putManifest(req.getVersionId(), req.getManifestJson());
+ log.info("[storeForVersion] 落包新建运行包行 versionId={}, pkgId={}, checksum={}, bundleSize={}",
+ req.getVersionId(), insert.getId(), req.getChecksum(), req.getBundleSize());
+ return insert.getId();
+ }
+
+ // 分支③：已有行且 status=1 已发布 → 同 checksum 幂等返回；异 checksum 拒绝（保护已发布包，禁止事后篡改）
+ if (PackageStatusEnum.isPublished(existing.getStatus())) {
+ if (Objects.equals(existing.getChecksum(), req.getChecksum())) {
+ log.info("[storeForVersion] 已发布运行包同 checksum，幂等返回 versionId={}, pkgId={}",
+ req.getVersionId(), existing.getId());
+ return existing.getId();
+ }
+ log.error("[storeForVersion] 已发布运行包拒绝异 checksum 覆写（保护发布产物）versionId={}, pkgId={}, "
+ + "existingChecksum={}, reqChecksum={}", req.getVersionId(), existing.getId(),
+ existing.getChecksum(), req.getChecksum());
+ throw exception(RUNTIME_PACKAGE_NOT_READY);
+ }
+
+ // 防御分支：非 0/1 态（如 2 已失效）——spec §8.5 三分支未列该态，防御性拒绝（不可覆写、不可幂等通过）
+ if (!PackageStatusEnum.isPreviewReady(existing.getStatus())) {
+ log.error("[storeForVersion] 运行包状态非法，拒绝落包 versionId={}, pkgId={}, status={}",
+ req.getVersionId(), existing.getId(), existing.getStatus());
+ throw exception(RUNTIME_PACKAGE_NOT_READY);
+ }
+
+ // 分支②：已有行且 status=0 预览就绪 → 更新元数据列 + 覆写 manifest（同 genTaskId 重放安全）
+ RuntimePackageDO update = new RuntimePackageDO();
+ update.setId(existing.getId());
+ update.setGameId(req.getGameId());
+ update.setTemplateId(req.getTemplateId());
+ update.setEntry(defaultIfBlank(req.getEntry(), DEFAULT_ENTRY));
+ update.setRuntimeVersion(defaultIfBlank(req.getRuntimeVersion(), DEFAULT_RUNTIME_VERSION));
+ update.setPreloadPolicy(defaultIfBlank(req.getPreloadPolicy(), DEFAULT_PRELOAD_POLICY));
+ update.setBundleSize(req.getBundleSize());
+ update.setChecksum(req.getChecksum());
+ runtimePackageMapper.updateById(update);
+ packageStore.putManifest(req.getVersionId(), req.getManifestJson());
+ log.info("[storeForVersion] 落包覆写预览就绪行（重放安全）versionId={}, pkgId={}, checksum={}",
+ req.getVersionId(), existing.getId(), req.getChecksum());
+ return existing.getId();
+ }
+
+ /**
+ * 落包入参缺省值兜底（DTO 可空字段统一在服务端落缺省，保证表列 NOT NULL 语义）
+ *
+ * @param value 入参值
+ * @param defaultValue 缺省值
+ * @return 非空白入参原值，否则缺省值
+ */
+ private static String defaultIfBlank(String value, String defaultValue) {
+ return StringUtils.hasText(value) ? value : defaultValue;
+ }
+
/**
* 预览归属校验：仅版本 owner（创作者本人）可预览未发布运行包
*
diff --git a/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/store/DbPackageStore.java b/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/store/DbPackageStore.java
index ce514d75..bfc85121 100644
--- a/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/store/DbPackageStore.java
+++ b/game-cloud/game-module-runtime/game-module-runtime-server/src/main/java/cn/wanxiang/game/module/runtime/service/pkg/store/DbPackageStore.java
@@ -6,6 +6,9 @@ import jakarta.annotation.Resource;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
+import static cn.wanxiang.game.module.runtime.enums.ErrorCodeConstants.RUNTIME_PACKAGE_NOT_READY;
+import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
+
/**
* 整包 manifest 存储 DB 实现（黄金闭环 §3.4 C4，MVP 无 OSS：读写 game_runtime_package.package_json）
*
@@ -25,9 +28,11 @@ public class DbPackageStore implements PackageStore {
// 落包写入：按 versionId 定位运行包行，写 package_json 原始 JSON（不 parse/re-serialize，保字节一致 §3.4 C4）
RuntimePackageDO pkg = runtimePackageMapper.selectByVersionId(versionId);
if (pkg == null) {
- // 防御：无运行包行无法落 manifest（PackageFactory 应先建 game_runtime_package 再写 manifest）
- log.warn("[putManifest] 无对应运行包，跳过写入 manifest versionId={}", versionId);
- return;
+ // 显式失败（HJ-AGENT-LOOP-EXEC-001 §8.1 Z1 修正）：无运行包行即写链断裂，必须抛错让调用方事务回滚，
+ // 杜绝「manifest 静默丢失但事务提交」的带病链。原静默跳过（log.warn + return）行为已废弃——
+ // §2.1 已核全仓零既有生产调用方，爆炸半径 = 本案新落包链路自身。
+ log.error("[putManifest] 无对应运行包行，落 manifest 失败（调用方应先建 game_runtime_package 行）versionId={}", versionId);
+ throw exception(RUNTIME_PACKAGE_NOT_READY);
}
RuntimePackageDO update = new RuntimePackageDO();
update.setId(pkg.getId());
diff --git a/game-cloud/game-module-runtime/game-module-runtime-server/src/test/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageServiceImplTest.java b/game-cloud/game-module-runtime/game-module-runtime-server/src/test/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageServiceImplTest.java
index 47dbf607..ac3157eb 100644
--- a/game-cloud/game-module-runtime/game-module-runtime-server/src/test/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageServiceImplTest.java
+++ b/game-cloud/game-module-runtime/game-module-runtime-server/src/test/java/cn/wanxiang/game/module/runtime/service/pkg/RuntimePackageServiceImplTest.java
@@ -2,8 +2,10 @@ package cn.wanxiang.game.module.runtime.service.pkg;
import cn.wanxiang.game.module.runtime.dal.dataobject.pkg.RuntimePackageDO;
import cn.wanxiang.game.module.runtime.dal.mysql.pkg.RuntimePackageMapper;
+import cn.wanxiang.game.module.runtime.dto.RuntimePackageStoreReqDTO;
import cn.wanxiang.game.module.runtime.enums.PackageStatusEnum;
import cn.wanxiang.game.module.runtime.enums.RuntimeSceneEnum;
+import cn.wanxiang.game.module.runtime.service.pkg.store.PackageStore;
import cn.iocoder.yudao.framework.common.exception.ServiceException;
import cn.iocoder.yudao.framework.test.core.ut.BaseMockitoUnitTest;
import org.junit.jupiter.api.Test;
@@ -14,12 +16,15 @@ import org.mockito.Mock;
import static cn.wanxiang.game.module.runtime.enums.ErrorCodeConstants.*;
import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.Mockito.*;
/**
* {@link RuntimePackageServiceImpl} 单元测试（纯 Mockito，不依赖 DB）
*
- * 覆盖核心业务规则守卫：取包门禁（决策1：scene+status 权威判定 + 预览归属）、发布态回写状态机 + 幂等。
+ * 覆盖核心业务规则守卫：取包门禁（决策1：scene+status 权威判定 + 预览归属）、发布态回写状态机 + 幂等、
+ * 落包 storeForVersion 幂等三分支（HJ-AGENT-LOOP-EXEC-001 §8.5）。
*
* @author 绘境AI
*/
@@ -31,6 +36,9 @@ class RuntimePackageServiceImplTest extends BaseMockitoUnitTest {
@Mock
private RuntimePackageMapper runtimePackageMapper;
+ @Mock
+ private PackageStore packageStore;
+
// ============================== getPackageManifest 取包门禁 ==============================
@Test
@@ -114,6 +122,118 @@ class RuntimePackageServiceImplTest extends BaseMockitoUnitTest {
assertEquals(RUNTIME_PACKAGE_NOT_READY.getCode(), ex.getCode());
}
+ // ============================== storeForVersion 落包幂等三分支（§8.5）==============================
+
+ @Test
+ void testStoreForVersion_insertWhenAbsent() {
+ // 分支①：无行 → 插入新行 status=0 预览就绪 + 写 manifest
+ when(runtimePackageMapper.selectByVersionId(2048L)).thenReturn(null);
+ doAnswer(inv -> {
+ RuntimePackageDO d = inv.getArgument(0);
+ d.setId(31L); // 模拟自增 ID 回填
+ return 1;
+ }).when(runtimePackageMapper).insert(any(RuntimePackageDO.class));
+
+ Long pkgId = runtimePackageService.storeForVersion(storeReq());
+
+ assertEquals(31L, pkgId);
+ // 插入行字段映射断言（status=0 + 元数据列 + 缺省值兜底）
+ ArgumentCaptor captor = ArgumentCaptor.forClass(RuntimePackageDO.class);
+ verify(runtimePackageMapper).insert(captor.capture());
+ RuntimePackageDO saved = captor.getValue();
+ assertEquals(PackageStatusEnum.PREVIEW_READY.getStatus(), saved.getStatus());
+ assertEquals(1024L, saved.getGameId());
+ assertEquals(2048L, saved.getVersionId());
+ assertEquals("clicker", saved.getTemplateId());
+ assertEquals("index.html", saved.getEntry()); // 入参未带 entry → 服务端缺省
+ assertEquals("1.0.0", saved.getRuntimeVersion()); // 缺省
+ assertEquals("eager", saved.getPreloadPolicy()); // 缺省
+ assertEquals(666L, saved.getBundleSize());
+ assertEquals("a".repeat(64), saved.getChecksum());
+ // manifest 在行建立后写入（putManifest 未命中行会显式抛错，Z1 带病链杜绝）
+ verify(packageStore).putManifest(2048L, "{\"k\":\"v\"}");
+ }
+
+ @Test
+ void testStoreForVersion_overwriteWhenPreviewReady() {
+ // 分支②：已有行且 status=0 → 更新元数据列 + 覆写 manifest（同 genTaskId 重放安全）
+ RuntimePackageDO existing = pkg(PackageStatusEnum.PREVIEW_READY.getStatus());
+ existing.setId(31L);
+ when(runtimePackageMapper.selectByVersionId(2048L)).thenReturn(existing);
+
+ Long pkgId = runtimePackageService.storeForVersion(storeReq());
+
+ assertEquals(31L, pkgId);
+ ArgumentCaptor captor = ArgumentCaptor.forClass(RuntimePackageDO.class);
+ verify(runtimePackageMapper).updateById(captor.capture());
+ assertEquals(31L, captor.getValue().getId());
+ assertEquals("a".repeat(64), captor.getValue().getChecksum()); // 元数据被覆写
+ verify(runtimePackageMapper, never()).insert(any(RuntimePackageDO.class)); // 不重复建行
+ verify(packageStore).putManifest(2048L, "{\"k\":\"v\"}"); // manifest 覆写
+ }
+
+ @Test
+ void testStoreForVersion_publishedSameChecksumIdempotent() {
+ // 分支③-a：已有行且 status=1 已发布 + 同 checksum → 幂等返回，零写入
+ RuntimePackageDO existing = pkg(PackageStatusEnum.PUBLISHED.getStatus());
+ existing.setId(31L);
+ existing.setChecksum("a".repeat(64)); // 与入参一致
+ when(runtimePackageMapper.selectByVersionId(2048L)).thenReturn(existing);
+
+ Long pkgId = runtimePackageService.storeForVersion(storeReq());
+
+ assertEquals(31L, pkgId);
+ verify(runtimePackageMapper, never()).insert(any(RuntimePackageDO.class));
+ verify(runtimePackageMapper, never()).updateById(any(RuntimePackageDO.class));
+ verify(packageStore, never()).putManifest(anyLong(), anyString()); // 不覆写已发布包 manifest
+ }
+
+ @Test
+ void testStoreForVersion_publishedDiffChecksumRejected() {
+ // 分支③-b：已有行且 status=1 已发布 + 异 checksum → 抛 1-102-001-001（保护已发布包，禁止事后篡改）
+ RuntimePackageDO existing = pkg(PackageStatusEnum.PUBLISHED.getStatus());
+ existing.setId(31L);
+ existing.setChecksum("b".repeat(64)); // 与入参 a*64 不一致
+ when(runtimePackageMapper.selectByVersionId(2048L)).thenReturn(existing);
+
+ ServiceException ex = assertThrows(ServiceException.class,
+ () -> runtimePackageService.storeForVersion(storeReq()));
+ assertEquals(RUNTIME_PACKAGE_NOT_READY.getCode(), ex.getCode());
+ verify(runtimePackageMapper, never()).updateById(any(RuntimePackageDO.class));
+ verify(packageStore, never()).putManifest(anyLong(), anyString());
+ }
+
+ @Test
+ void testStoreForVersion_putManifestErrorPropagates() {
+ // putManifest 抛错 → storeForVersion 原样上抛（调用方回调事务整体回滚，Z1）
+ when(runtimePackageMapper.selectByVersionId(2048L)).thenReturn(null);
+ doAnswer(inv -> {
+ RuntimePackageDO d = inv.getArgument(0);
+ d.setId(31L);
+ return 1;
+ }).when(runtimePackageMapper).insert(any(RuntimePackageDO.class));
+ doThrow(new ServiceException(RUNTIME_PACKAGE_NOT_READY.getCode(), "运行包不存在或未就绪"))
+ .when(packageStore).putManifest(anyLong(), anyString());
+
+ ServiceException ex = assertThrows(ServiceException.class,
+ () -> runtimePackageService.storeForVersion(storeReq()));
+ assertEquals(RUNTIME_PACKAGE_NOT_READY.getCode(), ex.getCode());
+ }
+
+ @Test
+ void testStoreForVersion_expiredStatusRejected() {
+ // 防御分支：status=2 已失效（§8.5 三分支未列态）→ 拒绝落包（不可覆写、不可幂等通过）
+ RuntimePackageDO existing = pkg(PackageStatusEnum.EXPIRED.getStatus());
+ existing.setId(31L);
+ when(runtimePackageMapper.selectByVersionId(2048L)).thenReturn(existing);
+
+ ServiceException ex = assertThrows(ServiceException.class,
+ () -> runtimePackageService.storeForVersion(storeReq()));
+ assertEquals(RUNTIME_PACKAGE_NOT_READY.getCode(), ex.getCode());
+ verify(runtimePackageMapper, never()).updateById(any(RuntimePackageDO.class));
+ verify(packageStore, never()).putManifest(anyLong(), anyString());
+ }
+
// ============================== 测试夹具 ==============================
/** 构造指定状态的运行包 */
@@ -125,4 +245,16 @@ class RuntimePackageServiceImplTest extends BaseMockitoUnitTest {
return p;
}
+ /** 构造落包入参（entry/runtimeVersion/preloadPolicy 留空——覆盖服务端缺省值兜底） */
+ private static RuntimePackageStoreReqDTO storeReq() {
+ RuntimePackageStoreReqDTO req = new RuntimePackageStoreReqDTO();
+ req.setGameId(1024L);
+ req.setVersionId(2048L);
+ req.setTemplateId("clicker");
+ req.setManifestJson("{\"k\":\"v\"}");
+ req.setChecksum("a".repeat(64));
+ req.setBundleSize(666L);
+ return req;
+ }
+
}
diff --git a/game-cloud/game-module-runtime/game-module-runtime-server/src/test/java/cn/wanxiang/game/module/runtime/service/pkg/store/DbPackageStoreTest.java b/game-cloud/game-module-runtime/game-module-runtime-server/src/test/java/cn/wanxiang/game/module/runtime/service/pkg/store/DbPackageStoreTest.java
new file mode 100644
index 00000000..3283eced
--- /dev/null
+++ b/game-cloud/game-module-runtime/game-module-runtime-server/src/test/java/cn/wanxiang/game/module/runtime/service/pkg/store/DbPackageStoreTest.java
@@ -0,0 +1,60 @@
+package cn.wanxiang.game.module.runtime.service.pkg.store;
+
+import cn.wanxiang.game.module.runtime.dal.dataobject.pkg.RuntimePackageDO;
+import cn.wanxiang.game.module.runtime.dal.mysql.pkg.RuntimePackageMapper;
+import cn.iocoder.yudao.framework.common.exception.ServiceException;
+import cn.iocoder.yudao.framework.test.core.ut.BaseMockitoUnitTest;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+
+import static cn.wanxiang.game.module.runtime.enums.ErrorCodeConstants.RUNTIME_PACKAGE_NOT_READY;
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.*;
+
+/**
+ * {@link DbPackageStore} 单元测试（纯 Mockito，不依赖 DB）
+ *
+ * 覆盖 HJ-AGENT-LOOP-EXEC-001 §8.1 Z1 新行为：putManifest 未命中运行包行由「log.warn 静默跳过」改为
+ * 「抛 1-102-001-001 显式失败」——调用方（aigc 回调）事务据此整体回滚，杜绝 manifest 静默丢失的带病链。
+ *
+ * @author 造梦AI
+ */
+class DbPackageStoreTest extends BaseMockitoUnitTest {
+
+ @InjectMocks
+ private DbPackageStore dbPackageStore;
+
+ @Mock
+ private RuntimePackageMapper runtimePackageMapper;
+
+ @Test
+ void testPutManifest_missingRowThrows() {
+ // 新行为（Z1）：无对应运行包行 → 抛 1-102-001-001 显式失败（原静默跳过行为已废弃）
+ when(runtimePackageMapper.selectByVersionId(2048L)).thenReturn(null);
+
+ ServiceException ex = assertThrows(ServiceException.class,
+ () -> dbPackageStore.putManifest(2048L, "{\"k\":\"v\"}"));
+ assertEquals(RUNTIME_PACKAGE_NOT_READY.getCode(), ex.getCode());
+ verify(runtimePackageMapper, never()).updateById(any(RuntimePackageDO.class)); // 带类型消歧；无任何写入
+ }
+
+ @Test
+ void testPutManifest_hitRowWrites() {
+ // 命中行：写 package_json 原始 JSON（不 parse/re-serialize，保字节一致 §3.4 C4）
+ RuntimePackageDO pkg = new RuntimePackageDO();
+ pkg.setId(31L);
+ pkg.setVersionId(2048L);
+ when(runtimePackageMapper.selectByVersionId(2048L)).thenReturn(pkg);
+
+ dbPackageStore.putManifest(2048L, "{\"k\":\"v\"}");
+
+ ArgumentCaptor captor = ArgumentCaptor.forClass(RuntimePackageDO.class);
+ verify(runtimePackageMapper).updateById(captor.capture());
+ assertEquals(31L, captor.getValue().getId()); // 按行主键更新
+ assertEquals("{\"k\":\"v\"}", captor.getValue().getPackageJson()); // 原样字节写入
+ }
+
+}