feat: 一部分优化

Co-authored-by: Copilot <copilot@github.com>

server/utils/plazaPosts.ts

@@ -1,4 +1,6 @@
-// server/utils/plazaPosts.ts - 广场发布记录数据库操作：公开、取消公开和广场列表查询。
+// server/utils/plazaPosts.ts - 广场发布记录数据库操作：公开、取消公开、广场列表查询。
+// 广场帖子与 ImageGeneration 一对一关联，状态流转：PUBLIC → HIDDEN（用户自主） / REMOVED（管理员下架，不可恢复）。
+// 本文件不向调用方暴露上游响应、图床响应或内部错误字段。
 import type {
   IImagePublicStateData,
   IPlazaPostItem,
@@ -10,10 +12,18 @@ import {
 } from "~~/app/generated/prisma/client";
 import { prisma } from "~~/server/utils/prisma";
 
+/** 作者未设置昵称时的展示兜底文案 */
 const ANONYMOUS_AUTHOR_NAME = "匿名用户";
 
+/** 发布操作的三种结果：成功返回公开状态、记录不存在返回 null、已被管理员下架返回 "REMOVED" */
 export type PublishPlazaPostResult = IImagePublicStateData | null | "REMOVED";
 
+/**
+ * 将指定生图记录发布到广场。
+ * - 记录不存在或已软删除时返回 null。
+ * - 记录已被管理员 REMOVED 时返回 "REMOVED"，调用方应提示用户无法重新发布。
+ * - 其余情况 upsert 为 PUBLIC，允许重复调用（幂等）。
+ */
 export const publishImageGenerationToPlaza = async (
   userId: number,
   recordId: bigint
@@ -59,6 +69,12 @@ export const publishImageGenerationToPlaza = async (
   };
 };
 
+/**
+ * 将指定生图记录从广场隐藏（用户主动操作）。
+ * - 记录不存在或已软删除时返回 null。
+ * - 帖子不存在或已被 REMOVED 时 updateMany count 为 0，同样返回 null。
+ * - 不允许将 REMOVED 状态改为 HIDDEN，REMOVED 由管理员操作，不在此处处理。
+ */
 export const hideImageGenerationFromPlaza = async (
   userId: number,
   recordId: bigint
@@ -97,6 +113,17 @@ export const hideImageGenerationFromPlaza = async (
   };
 };
 
+/**
+ * 分页查询广场公开列表。
+ * 只返回满足以下全部条件的记录：
+ *   - PlazaPost.status = PUBLIC
+ *   - 关联的 ImageGeneration.status = SUCCEEDED
+ *   - 关联的 ImageGeneration 未软删除
+ *   - 关联的 ImageGeneration.hostedImageUrl 不为 null（图床归档完成）
+ *
+ * count 与 findMany 并行执行以减少网络往返耗时。
+ * 返回字段仅包含广场展示所需的公开信息，不含上游响应、图床响应或错误详情。
+ */
 export const listPlazaPosts = async ({
   page,
   pageSize
@@ -152,6 +179,11 @@ export const listPlazaPosts = async ({
   };
 };
 
+/**
+ * 将 Prisma 查询结果映射为广场展示条目。
+ * hostedImageUrl 在 where 条件中已过滤，此处二次检查是为了满足类型收窄。
+ * 映射失败（理论上不应发生）返回 null，由上层 filter 去除。
+ */
 const mapPlazaPostItem = (post: {
   id: bigint;
   publishedAt: Date;