fix(ai): AiTaskState/AiTaskFailure 契约对齐前端——修复精修结果永不使用的根因 (P0)

Author: Aparencia

app/src-tauri/src/ai_task.rs

@@ -15,8 +15,14 @@ use serde::{Deserialize, Serialize};
 pub const SLICE_MAX_CHARS: usize = 8000;
 
 /// 任务状态（前端任务卡片：进行中(按片进度)/成功/失败(原因)）。
+///
+/// @ai-context: 契约修复（2026-08-21 真机"调用有记录但结果未使用"根因）：
+///              曾带 rename_all="camelCase" 把变体名小写化（"succeeded"/{"running"}），
+///              前端按 PascalCase 比较（"Succeeded"/"Running" in st）全部失配——
+///              任务后台真实成功、前端永久"排队中"、结果永不取回。
+///              现去掉 rename_all：变体名=默认 PascalCase，字段=snake_case，
+///              与前端 types.ts 逐字匹配（契约快照测试见 ai_task_tests.rs）。
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
 pub enum AiTaskState {
     Pending,
     Running {
@@ -30,6 +36,12 @@ pub enum AiTaskState {
 }
 
 /// 任务失败原因（降级链可见——不静默降级；前端按类引导出口）。
+///
+/// @ai-context: 契约修复（2026-08-21）：camelCase 下 InsufficientBalance →
+///              "insufficientBalance"、InvalidResponse → "invalidResponse"，
+///              前端期待 "balance"/"invalid"（四类出口）——显式 rename 对齐；
+///              其余变体 camelCase 转换后本就与前端匹配（unauthorized/network/
+///              quota/server/other）。
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub enum AiTaskFailure {
@@ -38,12 +50,14 @@ pub enum AiTaskFailure {
     /// 网络错误（引导重试）
     Network(String),
     /// 余额不足（引导充值/切免费档）
+    #[serde(rename = "balance")]
     InsufficientBalance(String),
     /// 配额受限（引导明日再试）
     Quota(String),
     /// 服务端错误（引导稍后重试）
     Server(String),
     /// 响应非法（已丢弃回退——本地版保留，不丢不假）
+    #[serde(rename = "invalid")]
     InvalidResponse(String),
     /// 其他
     Other(String),

app/src-tauri/src/ai_task_tests.rs

@@ -5,7 +5,7 @@
 //!              失败 kind/message 访问。
 
 use crate::ai_client::AiClientError;
-use crate::ai_task::{slice_note, AiTaskFailure, SLICE_MAX_CHARS};
+use crate::ai_task::{slice_note, AiTaskFailure, AiTaskState, SLICE_MAX_CHARS};
 
 #[test]
 fn short_note_single_slice() {
@@ -84,3 +84,63 @@ fn failure_mapping_from_client_error() {
         assert!(!f.message().is_empty());
     }
 }
+
+/// 契约快照测试（2026-08-21 真机"调用有记录但结果未使用"根因的回归护栏）：
+///
+/// @ai-context: 前端 types.ts 按 PascalCase 变体名 + snake_case 字段消费
+///              AiTaskState（"Pending"/{"Running":{finished_slices,...}}/
+///              "Succeeded"/{"Failed":{reason}}），失败原因按四类小写标签
+///              （unauthorized/network/balance/quota/server/invalid/other）。
+///              本测试断言 serde 输出 = 前端期望的 JSON 字面量——任何一端
+///              契约漂移立即红，杜绝"后端成功前端永久排队中"类事故复发。
+#[test]
+fn serde_contract_snapshot_matches_frontend() {
+    // AiTaskState：变体名 PascalCase（unit variant = 字符串字面量）
+    assert_eq!(serde_json::to_string(&AiTaskState::Pending).unwrap(), r#""Pending""#);
+    assert_eq!(serde_json::to_string(&AiTaskState::Succeeded).unwrap(), r#""Succeeded""#);
+    // struct variant：外部标签 PascalCase + 字段 snake_case
+    let running = AiTaskState::Running { finished_slices: 1, total_slices: 3 };
+    assert_eq!(
+        serde_json::to_string(&running).unwrap(),
+        r#"{"Running":{"finished_slices":1,"total_slices":3}}"#
+    );
+    // 失败嵌套 reason
+    let failed = AiTaskState::Failed { reason: AiTaskFailure::Unauthorized("x".into()) };
+    assert_eq!(
+        serde_json::to_string(&failed).unwrap(),
+        r#"{"Failed":{"reason":{"unauthorized":"x"}}}"#
+    );
+    // AiTaskFailure：四类出口标签（camelCase + 两个显式 rename）
+    assert_eq!(
+        serde_json::to_string(&AiTaskFailure::Unauthorized("a".into())).unwrap(),
+        r#"{"unauthorized":"a"}"#
+    );
+    assert_eq!(
+        serde_json::to_string(&AiTaskFailure::Network("n".into())).unwrap(),
+        r#"{"network":"n"}"#
+    );
+    assert_eq!(
+        serde_json::to_string(&AiTaskFailure::InsufficientBalance("b".into())).unwrap(),
+        r#"{"balance":"b"}"#
+    );
+    assert_eq!(
+        serde_json::to_string(&AiTaskFailure::Quota("q".into())).unwrap(),
+        r#"{"quota":"q"}"#
+    );
+    assert_eq!(
+        serde_json::to_string(&AiTaskFailure::Server("s".into())).unwrap(),
+        r#"{"server":"s"}"#
+    );
+    assert_eq!(
+        serde_json::to_string(&AiTaskFailure::InvalidResponse("i".into())).unwrap(),
+        r#"{"invalid":"i"}"#
+    );
+    assert_eq!(
+        serde_json::to_string(&AiTaskFailure::Other("o".into())).unwrap(),
+        r#"{"other":"o"}"#
+    );
+    // 反序列化回环（任务注册表存 JSON——恢复路径依赖）
+    let v = serde_json::to_value(&running).unwrap();
+    let back: AiTaskState = serde_json::from_value(v).unwrap();
+    assert_eq!(back, running);
+}