From fe6079ba627b41d910925cdf9bcfb7a8d1c2eac9 Mon Sep 17 00:00:00 2001 From: lili Date: Tue, 7 Jul 2026 12:21:45 -0700 Subject: [PATCH] =?UTF-8?q?feat(contracts):=20WU2=E2=91=A3=20quota=5Fexhau?= =?UTF-8?q?sted=20=E8=B7=A8=E5=A5=91=E7=BA=A6=E5=85=B1=E4=BA=AB=E6=9E=9A?= =?UTF-8?q?=E4=B8=BE=E5=90=8C=E6=89=B9=E6=96=B0=E5=A2=9E=E4=B8=89=E5=A4=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 额度耗尽/池空要干净失败给用户可读拒因，而非含糊的「生成失败」。该失败因是跨契约 共享枚举（FailureReasonEnum 头注禁单边扩展），contract-first 同一批落三处保持一致： - FailureReasonEnum 加 QUOTA_EXHAUSTED("quota_exhausted","生成额度已用完")； - contracts/api-schemas/aigc.yaml FailureReason.enum； - contracts/dify-workflow-io.json output.failureReason.enum。 落库列 game_aigc_task.failure_reason(varchar(32)) 容得下（15 字符）。 Co-Authored-By: Claude Opus 4.8 (1M context) --- contracts/api-schemas/aigc.yaml | 5 ++-- contracts/dify-workflow-io.json | 2 +- .../module/aigc/enums/FailureReasonEnum.java | 5 +++- .../enums/FailureReasonEnumQuotaTest.java | 26 +++++++++++++++++++ 4 files changed, 34 insertions(+), 4 deletions(-) create mode 100644 game-cloud/game-module-aigc/game-module-aigc-server/src/test/java/com/wanxiang/huijing/game/module/aigc/enums/FailureReasonEnumQuotaTest.java diff --git a/contracts/api-schemas/aigc.yaml b/contracts/api-schemas/aigc.yaml index d6ce09d5..57b7e123 100644 --- a/contracts/api-schemas/aigc.yaml +++ b/contracts/api-schemas/aigc.yaml @@ -292,5 +292,6 @@ components: description: >- 生成失败原因分类（结构化错误码，映射用户可读提示）。取值与契约#6 dify-workflow-io.json output.failureReason 一致。 unsafe_prompt=Prompt 不安全 / intent_unclear=意图不清 / no_template_match=无匹配模板 / - config_invalid=配置校验失败 / llm_error=LLM 异常 / timeout=超时 / asset_gen_failed=素材生成失败。 - enum: [unsafe_prompt, intent_unclear, no_template_match, config_invalid, llm_error, timeout, asset_gen_failed] + config_invalid=配置校验失败 / llm_error=LLM 异常 / timeout=超时 / asset_gen_failed=素材生成失败 / + quota_exhausted=生成额度已用完（WU2 new-api per-user 额度耗尽/池空，网关 402/403）。 + enum: [unsafe_prompt, intent_unclear, no_template_match, config_invalid, llm_error, timeout, asset_gen_failed, quota_exhausted] diff --git a/contracts/dify-workflow-io.json b/contracts/dify-workflow-io.json index 60da6e23..66152029 100644 --- a/contracts/dify-workflow-io.json +++ b/contracts/dify-workflow-io.json @@ -47,7 +47,7 @@ "failureReason": { "description": "失败原因分类（status=failed 必填，映射用户可读提示）", "type": "string", - "enum": ["unsafe_prompt", "intent_unclear", "no_template_match", "config_invalid", "llm_error", "timeout", "asset_gen_failed"] + "enum": ["unsafe_prompt", "intent_unclear", "no_template_match", "config_invalid", "llm_error", "timeout", "asset_gen_failed", "quota_exhausted"] } } } diff --git a/game-cloud/game-module-aigc/game-module-aigc-api/src/main/java/com/wanxiang/huijing/game/module/aigc/enums/FailureReasonEnum.java b/game-cloud/game-module-aigc/game-module-aigc-api/src/main/java/com/wanxiang/huijing/game/module/aigc/enums/FailureReasonEnum.java index 83112655..1f34be51 100644 --- a/game-cloud/game-module-aigc/game-module-aigc-api/src/main/java/com/wanxiang/huijing/game/module/aigc/enums/FailureReasonEnum.java +++ b/game-cloud/game-module-aigc/game-module-aigc-api/src/main/java/com/wanxiang/huijing/game/module/aigc/enums/FailureReasonEnum.java @@ -21,7 +21,10 @@ public enum FailureReasonEnum { CONFIG_INVALID("config_invalid", "配置校验失败"), LLM_ERROR("llm_error", "LLM 异常"), TIMEOUT("timeout", "超时"), - ASSET_GEN_FAILED("asset_gen_failed", "素材生成失败"); + ASSET_GEN_FAILED("asset_gen_failed", "素材生成失败"), + // WU2 §3.9：new-api per-user 额度耗尽（网关 402/403）或派发期池空懒 claim 未果——干净失败给可读拒因， + // 区别于含糊的 llm_error。跨契约共享枚举，同批已加 aigc.yaml FailureReason.enum 与 dify-workflow-io.json output.failureReason.enum。 + QUOTA_EXHAUSTED("quota_exhausted", "生成额度已用完"); /** 失败原因码（落库 varchar，对齐契约枚举值） */ private final String reason; diff --git a/game-cloud/game-module-aigc/game-module-aigc-server/src/test/java/com/wanxiang/huijing/game/module/aigc/enums/FailureReasonEnumQuotaTest.java b/game-cloud/game-module-aigc/game-module-aigc-server/src/test/java/com/wanxiang/huijing/game/module/aigc/enums/FailureReasonEnumQuotaTest.java new file mode 100644 index 00000000..45830bfe --- /dev/null +++ b/game-cloud/game-module-aigc/game-module-aigc-server/src/test/java/com/wanxiang/huijing/game/module/aigc/enums/FailureReasonEnumQuotaTest.java @@ -0,0 +1,26 @@ +package com.wanxiang.huijing.game.module.aigc.enums; + +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +/** + * {@link FailureReasonEnum} 的 WU2 §3.9 新增值断言——把守 {@code quota_exhausted} 跨契约共享枚举存在且取值稳定。 + * + *

该值须与 contracts/api-schemas/aigc.yaml 的 FailureReason.enum、contracts/dify-workflow-io.json 的 + * output.failureReason.enum 三处一致（contract-first，docs 门对账）；落库列 game_aigc_task.failure_reason(varchar(32)) 容得下 15 字符。 + * + * @author 绘境AI + */ +class FailureReasonEnumQuotaTest { + + /** quota_exhausted 存在且码值/文案与契约一致（跨契约共享枚举，禁单边漂移）。 */ + @Test + void testQuotaExhaustedPresent() { + assertEquals("quota_exhausted", FailureReasonEnum.QUOTA_EXHAUSTED.getReason()); + assertEquals("生成额度已用完", FailureReasonEnum.QUOTA_EXHAUSTED.getMessage()); + // 落库列 varchar(32) 容量兜底（15 字符） + assertEquals(15, FailureReasonEnum.QUOTA_EXHAUSTED.getReason().length()); + } + +}