feat: 补充注释

server/utils/imageGenerationRecords.ts

@@ -1,3 +1,4 @@
+// server/utils/imageGenerationRecords.ts - 生图相关数据库操作：用户快照、生成记录、历史查询和统计。
 import type { IUserBasicData } from "#shared/types";
 import type {
   IImageGenerationStatsData,
@@ -238,8 +239,8 @@ export const getImageGenerationDetail = async (
   return {
     ...mapImageGenerationItem(record),
     imageMimeType: record.imageMimeType,
-    upstreamResponse: record.upstreamResponse,
-    hostedResponse: record.hostedResponse
+    upstreamResponse: null,
+    hostedResponse: null
   };
 };
 
@@ -295,6 +296,7 @@ const upsertGenerationStats = (update: Prisma.GenerationStatsUpdateInput) => {
   });
 };
 
+/** 更新统计失败不能影响主链路，避免统计表问题导致生图接口失败 */
 const safeUpsertGenerationStats = async (
   update: Prisma.GenerationStatsUpdateInput
 ) => {
@@ -307,6 +309,7 @@ const safeUpsertGenerationStats = async (
   }
 };
 
+/** upsert 创建统计行时，把本次 increment 转换为初始计数 */
 const buildStatsCreateInput = (update: Prisma.GenerationStatsUpdateInput) => {
   return {
     totalRequests: getIncrementValue(update.totalRequests),
@@ -318,6 +321,7 @@ const buildStatsCreateInput = (update: Prisma.GenerationStatsUpdateInput) => {
   };
 };
 
+/** 从 Prisma increment 操作里取出增量；非 increment 操作在创建时按 0 处理 */
 const getIncrementValue = (value: unknown): number => {
   if (
     value &&
@@ -331,6 +335,7 @@ const getIncrementValue = (value: unknown): number => {
   return 0;
 };
 
+/** 将 Prisma 记录转换为前端类型，BigInt/Date 在这里统一序列化 */
 const mapImageGenerationItem = (record: {
   id: bigint;
   userId: number;
@@ -360,17 +365,30 @@ const mapImageGenerationItem = (record: {
     imageUrl: record.imageUrl,
     hostedImageUrl: record.hostedImageUrl,
     revisedPrompt: record.revisedPrompt,
-    errorMessage: record.errorMessage,
+    errorMessage: getPublicRecordMessage(record.status, record.errorMessage),
     createdAt: record.createdAt.toISOString()
   };
 };
 
+/** 计算耗时并兜底为非负数，避免系统时间抖动导致负值 */
 const getDurationMs = (startedAt: Date, endedAt: Date) => {
   return Math.max(0, endedAt.getTime() - startedAt.getTime());
 };
 
+/** 保存到数据库的错误信息只保留可读摘要，不保存复杂错误对象 */
 const getSafeErrorMessage = (error: unknown): string => {
   if (error instanceof Error) return error.message;
   if (typeof error === "string") return error;
   return "图片生成失败";
 };
+
+/** 返回给前端的记录错误只保留本地泛化文案，具体内部错误留在数据库和服务端日志 */
+const getPublicRecordMessage = (
+  status: ImageGenerationStatus,
+  errorMessage: string | null
+): string | null => {
+  if (!errorMessage) return null;
+  return status === ImageGenerationStatus.SUCCEEDED
+    ? "图片归档失败"
+    : "图片生成失败";
+};