fix(frontend): cap envelope mismatch

frontend/lib/api-envelope.ts

@@ -0,0 +1,68 @@
+/**
+ * OpenFlare 统一 API 响应信封解析。
+ * 与后端 internal/common/response.Response 及 axios api-client 约定一致。
+ */
+
+export interface ApiEnvelope<T = unknown> {
+  error_msg: string;
+  data: T | null;
+}
+
+export class ApiEnvelopeError extends Error {
+  readonly status: number;
+
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = 'ApiEnvelopeError';
+    this.status = status;
+  }
+}
+
+function hasEnvelopeShape(value: unknown): value is ApiEnvelope<unknown> {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  return 'error_msg' in value && 'data' in value;
+}
+
+/**
+ * 解析 fetch 响应体中的 { error_msg, data } 信封。
+ * - HTTP 非 2xx：优先使用 error_msg
+ * - HTTP 200 但 error_msg 非空：视为业务失败
+ */
+export async function readApiEnvelope<T>(
+  res: Response,
+  fallbackMessage: string,
+): Promise<ApiEnvelope<T>> {
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch {
+    throw new ApiEnvelopeError(fallbackMessage, res.status);
+  }
+
+  if (!hasEnvelopeShape(body)) {
+    throw new ApiEnvelopeError(fallbackMessage, res.status);
+  }
+
+  const envelope = body as ApiEnvelope<T>;
+  if (!res.ok) {
+    throw new ApiEnvelopeError(envelope.error_msg || fallbackMessage, res.status);
+  }
+  if (envelope.error_msg) {
+    throw new ApiEnvelopeError(envelope.error_msg, res.status);
+  }
+
+  return envelope;
+}
+
+export async function readApiData<T>(
+  res: Response,
+  fallbackMessage: string,
+): Promise<T> {
+  const envelope = await readApiEnvelope<T>(res, fallbackMessage);
+  if (envelope.data == null) {
+    throw new ApiEnvelopeError(fallbackMessage, res.status);
+  }
+  return envelope.data;
+}

frontend/lib/cap-solver.ts

@@ -7,6 +7,8 @@
 
 // ——— Challenge / Redeem API types ———
 
+import {readApiData} from '@/lib/api-envelope';
+
 export interface ChallengeResponse {
   challenge: { c: number; s: number; d: number };
   token: string;
@@ -138,10 +140,10 @@ export async function getCapToken(scope = 'login'): Promise<string> {
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ scope }),
   });
-  if (!challengeRes.ok) {
-    throw new Error('获取人机验证难题失败');
-  }
-  const challenge: ChallengeResponse = await challengeRes.json();
+  const challenge = await readApiData<ChallengeResponse>(
+    challengeRes,
+    '获取人机验证难题失败',
+  );
   const { c: count, s: size, d: difficulty } = challenge.challenge;
 
   console.groupCollapsed('[Cap] 人机验证 PoW 求解开始');
@@ -174,7 +176,10 @@ export async function getCapToken(scope = 'login'): Promise<string> {
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ token: challenge.token, solutions, scope }),
   });
-  const redeemData: RedeemResponse = await redeemRes.json();
+  const redeemData = await readApiData<RedeemResponse>(
+    redeemRes,
+    '人机验证失败',
+  );
   if (!redeemData.success || !redeemData.token) {
     throw new Error(redeemData.error || '人机验证失败');
   }