feat(contracts): WU2④ quota_exhausted 跨契约共享枚举同批新增三处

额度耗尽/池空要干净失败给用户可读拒因，而非含糊的「生成失败」。该失败因是跨契约
共享枚举（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) <noreply@anthropic.com>

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]

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"]
         }
       }
     }

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;

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} 跨契约共享枚举存在且取值稳定。
+ *
+ * <p>该值须与 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());
+    }
+
+}