feat(messaging,announcements): 前端 UI 集成星标/草稿/置顶/已读回执

- 消息星标：MessageList 卡片星标按钮（乐观更新+回滚）、MessageDetail 头部星标切换 - 消息草稿：MessageCompose 自动保存（2s 防抖）+ 手动保存按钮 + 状态指示器 + 发送后清理草稿 - 公告置顶：AnnouncementCard 管理端置顶按钮、AnnouncementDetail 置顶切换、置顶 Badge - 公告已读回执：用户端详情页自动标记已读 + 已读/未读 Badge、管理端已读人数显示 - i18n：新增 announcements.meta.readCount 翻译键
2026-06-23 17:24:26 +08:00
parent f75602d14e
commit 276577b66c
9 changed files with 395 additions and 34 deletions
--- a/src/modules/messaging/components/message-compose.tsx
+++ b/src/modules/messaging/components/message-compose.tsx
@@ -1,11 +1,11 @@
 "use client"

-import { useState } from "react"
+import { useEffect, useRef, useState } from "react"
 import Link from "next/link"
 import { useRouter } from "next/navigation"
 import { toast } from "sonner"
 import { useTranslations } from "next-intl"
-import { ArrowLeft, Send } from "lucide-react"
+import { ArrowLeft, Check, Loader2, Save, Send } from "lucide-react"

 import { Button } from "@/shared/components/ui/button"
 import { Card, CardContent, CardFooter, CardHeader, CardTitle } from "@/shared/components/ui/card"
@@ -20,10 +20,14 @@ import {
  SelectValue,
 } from "@/shared/components/ui/select"

-import { sendMessageAction } from "../actions"
+import { deleteMessageDraftAction, saveMessageDraftAction, sendMessageAction } from "../actions"
 import type { RecipientOption } from "../types"

 type FieldErrors = Record<string, string[]>
+type SaveStatus = "idle" | "saving" | "saved"
+
+/** 自动保存防抖延迟（毫秒） */
+const AUTOSAVE_DEBOUNCE_MS = 2000

 export function MessageCompose({
  recipients,
@@ -42,13 +46,61 @@ export function MessageCompose({
  const router = useRouter()
  const [isWorking, setIsWorking] = useState(false)
  const [receiverId, setReceiverId] = useState(defaultReceiverId ?? "")
+  const [subject, setSubject] = useState(defaultSubject ?? "")
+  const [content, setContent] = useState("")
  const [fieldErrors, setFieldErrors] = useState<FieldErrors>({})
+  const [draftId, setDraftId] = useState<string | null>(null)
+  const [saveStatus, setSaveStatus] = useState<SaveStatus>("idle")
+  const draftIdRef = useRef<string | null>(null)
+
+  // Keep draftIdRef in sync so auto-save callback reads the latest value
+  useEffect(() => {
+    draftIdRef.current = draftId
+  }, [draftId])

  const getFieldError = (field: string): string | null => {
    const errs = fieldErrors[field]
    return errs && errs.length > 0 ? errs[0] : null
  }

+  // 自动保存草稿（防抖 2 秒）
+  useEffect(() => {
+    // 没有内容时不保存
+    if (!subject.trim() && !content.trim()) return
+
+    let cancelled = false
+    const timeout = setTimeout(() => {
+      if (cancelled) return
+      const formData = new FormData()
+      const currentDraftId = draftIdRef.current
+      if (currentDraftId) formData.set("draftId", currentDraftId)
+      if (receiverId) formData.set("receiverId", receiverId)
+      if (subject) formData.set("subject", subject)
+      if (content) formData.set("content", content)
+      if (parentMessageId) formData.set("parentMessageId", parentMessageId)
+
+      setSaveStatus("saving")
+      void saveMessageDraftAction(null, formData)
+        .then((res) => {
+          if (cancelled) return
+          if (res.success && res.data) {
+            setDraftId(res.data)
+            setSaveStatus("saved")
+          } else {
+            setSaveStatus("idle")
+          }
+        })
+        .catch(() => {
+          if (!cancelled) setSaveStatus("idle")
+        })
+    }, AUTOSAVE_DEBOUNCE_MS)
+
+    return () => {
+      cancelled = true
+      clearTimeout(timeout)
+    }
+  }, [subject, content, receiverId, parentMessageId])
+
  const handleSubmit = async (formData: FormData) => {
    if (!receiverId) {
      toast.error(t("form.selectRecipient"))
@@ -64,6 +116,10 @@ export function MessageCompose({
    try {
      const res = await sendMessageAction(null, formData)
      if (res.success) {
+        // 发送成功后删除草稿（如有）
+        if (draftIdRef.current) {
+          void deleteMessageDraftAction(draftIdRef.current)
+        }
        toast.success(res.message)
        router.push("/messages")
        router.refresh()
@@ -81,16 +137,59 @@ export function MessageCompose({
    }
  }

+  const handleSaveDraft = async () => {
+    setSaveStatus("saving")
+    const formData = new FormData()
+    if (draftId) formData.set("draftId", draftId)
+    if (receiverId) formData.set("receiverId", receiverId)
+    if (subject) formData.set("subject", subject)
+    if (content) formData.set("content", content)
+    if (parentMessageId) formData.set("parentMessageId", parentMessageId)
+
+    try {
+      const res = await saveMessageDraftAction(null, formData)
+      if (res.success && res.data) {
+        setDraftId(res.data)
+        setSaveStatus("saved")
+        toast.success(t("messages.draftSaved"))
+      } else {
+        setSaveStatus("idle")
+        toast.error(res.message)
+      }
+    } catch {
+      setSaveStatus("idle")
+      toast.error(t("messages.sendFailed"))
+    }
+  }
+
  return (
    <Card>
      <CardHeader>
-        <div className="flex items-center gap-2">
-          <Button asChild variant="ghost" size="icon" aria-label={t("actions.back")}>
-            <Link href={backHref}>
-              <ArrowLeft className="h-4 w-4" />
-            </Link>
-          </Button>
-          <CardTitle>{parentMessageId ? t("title.reply") : t("title.newMessage")}</CardTitle>
+        <div className="flex items-center justify-between gap-2">
+          <div className="flex items-center gap-2">
+            <Button asChild variant="ghost" size="icon" aria-label={t("actions.back")}>
+              <Link href={backHref}>
+                <ArrowLeft className="h-4 w-4" />
+              </Link>
+            </Button>
+            <CardTitle>{parentMessageId ? t("title.reply") : t("title.newMessage")}</CardTitle>
+          </div>
+          {/* 草稿保存状态指示器 */}
+          {saveStatus !== "idle" ? (
+            <span className="text-muted-foreground flex items-center gap-1 text-xs">
+              {saveStatus === "saving" ? (
+                <>
+                  <Loader2 className="h-3 w-3 animate-spin" aria-hidden="true" />
+                  {t("actions.saveDraft")}...
+                </>
+              ) : (
+                <>
+                  <Check className="h-3 w-3 text-green-500" aria-hidden="true" />
+                  {t("messages.draftSaved")}
+                </>
+              )}
+            </span>
+          ) : null}
        </div>
      </CardHeader>
      <CardContent>
@@ -122,7 +221,8 @@ export function MessageCompose({
              id="subject"
              name="subject"
              placeholder={t("form.subjectPlaceholder")}
-              defaultValue={defaultSubject ?? ""}
+              value={subject}
+              onChange={(e) => setSubject(e.target.value)}
              maxLength={255}
              aria-invalid={!!getFieldError("subject")}
            />
@@ -138,6 +238,8 @@ export function MessageCompose({
              name="content"
              placeholder={t("form.contentPlaceholder")}
              className="min-h-[200px]"
+              value={content}
+              onChange={(e) => setContent(e.target.value)}
              required
              aria-invalid={!!getFieldError("content")}
            />
@@ -150,6 +252,15 @@ export function MessageCompose({
            <Button
              type="button"
              variant="outline"
+              onClick={handleSaveDraft}
+              disabled={isWorking || saveStatus === "saving"}
+            >
+              <Save className="mr-2 h-4 w-4" />
+              {t("actions.saveDraft")}
+            </Button>
+            <Button
+              type="button"
+              variant="ghost"
              onClick={() => router.push(backHref)}
              disabled={isWorking}
            >
--- a/src/modules/messaging/components/message-detail.tsx
+++ b/src/modules/messaging/components/message-detail.tsx
@@ -5,17 +5,17 @@ import Link from "next/link"
 import { useRouter } from "next/navigation"
 import { toast } from "sonner"
 import { useTranslations } from "next-intl"
-import { ArrowLeft, Mail, Reply, Trash2 } from "lucide-react"
+import { ArrowLeft, Mail, Reply, Star, Trash2 } from "lucide-react"

 import { Badge } from "@/shared/components/ui/badge"
 import { Button } from "@/shared/components/ui/button"
 import { Card, CardContent, CardHeader, CardTitle } from "@/shared/components/ui/card"
 import { ConfirmDeleteDialog } from "@/shared/components/ui/confirm-delete-dialog"
-import { formatDate } from "@/shared/lib/utils"
+import { cn, formatDate } from "@/shared/lib/utils"
 import { usePermission } from "@/shared/hooks/use-permission"
 import { Permissions } from "@/shared/types/permissions"

-import { deleteMessageAction } from "../actions"
+import { deleteMessageAction, toggleMessageStarAction } from "../actions"
 import type { Message } from "../types"

 export function MessageDetail({
@@ -31,6 +31,8 @@ export function MessageDetail({
  const router = useRouter()
  const [isWorking, setIsWorking] = useState(false)
  const [deleteOpen, setDeleteOpen] = useState(false)
+  const [isStarred, setIsStarred] = useState(message.isStarred)
+  const [isTogglingStar, setIsTogglingStar] = useState(false)
  const { hasPermission } = usePermission()
  const canSend = hasPermission(Permissions.MESSAGE_SEND)
  const canDelete = hasPermission(Permissions.MESSAGE_DELETE)
@@ -58,6 +60,29 @@ export function MessageDetail({
    }
  }

+  const handleToggleStar = async () => {
+    setIsTogglingStar(true)
+    const prevStarred = isStarred
+    // 乐观更新
+    setIsStarred(!prevStarred)
+    try {
+      const res = await toggleMessageStarAction(message.id)
+      if (res.success) {
+        toast.success(t("messages.starToggled"))
+      } else {
+        // 回滚
+        setIsStarred(prevStarred)
+        toast.error(res.message)
+      }
+    } catch {
+      // 回滚
+      setIsStarred(prevStarred)
+      toast.error(t("messages.sendFailed"))
+    } finally {
+      setIsTogglingStar(false)
+    }
+  }
+
  const replyHref = canSend
    ? `/messages/compose?parentId=${message.id}&receiverId=${isReceived ? message.senderId : message.receiverId}&subject=${encodeURIComponent(
        message.subject?.startsWith("Re:") ? message.subject : `Re: ${message.subject ?? ""}`
@@ -76,6 +101,16 @@ export function MessageDetail({
          <h2 className="text-2xl font-bold tracking-tight">{t("title.detail")}</h2>
        </div>
        <div className="flex flex-wrap items-center gap-2">
+          <Button
+            onClick={handleToggleStar}
+            disabled={isTogglingStar}
+            variant={isStarred ? "default" : "outline"}
+          >
+            <Star
+              className={cn("mr-2 h-4 w-4", isStarred && "fill-current")}
+            />
+            {isStarred ? t("actions.unstar") : t("actions.star")}
+          </Button>
          {canSend ? (
            <Button asChild variant="outline">
              <Link href={replyHref ?? "#"}>
@@ -104,6 +139,12 @@ export function MessageDetail({
            ) : (
              <Badge variant="outline">{t("status.sent")}</Badge>
            )}
+            {isStarred ? (
+              <span className="inline-flex items-center gap-1 text-xs text-yellow-600">
+                <Star className="h-3.5 w-3.5 fill-yellow-400 text-yellow-400" aria-hidden="true" />
+                {t("actions.star")}
+              </span>
+            ) : null}
          </div>
          <CardTitle className="text-2xl">{message.subject ?? t("meta.noSubject")}</CardTitle>
          <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
--- a/src/modules/messaging/components/message-list.tsx
+++ b/src/modules/messaging/components/message-list.tsx
@@ -1,9 +1,10 @@
 "use client"

-import { useMemo, useState } from "react"
+import { useCallback, useMemo, useState } from "react"
 import Link from "next/link"
-import { Mail, MailOpen, Plus, Send, Inbox, Search, Loader2, ChevronLeft, ChevronRight } from "lucide-react"
+import { Mail, MailOpen, Plus, Send, Inbox, Search, Loader2, ChevronLeft, ChevronRight, Star } from "lucide-react"
 import { useTranslations } from "next-intl"
+import { toast } from "sonner"

 import { Badge } from "@/shared/components/ui/badge"
 import { Button } from "@/shared/components/ui/button"
@@ -15,7 +16,7 @@ import { cn, formatDate } from "@/shared/lib/utils"
 import { usePermission } from "@/shared/hooks/use-permission"
 import { Permissions } from "@/shared/types/permissions"

-import { getMessagesAction } from "../actions"
+import { getMessagesAction, toggleMessageStarAction } from "../actions"
 import { useMessageSearch } from "../hooks/use-message-search"
 import type { Message, MessageType } from "../types"

@@ -36,6 +37,8 @@ export function MessageList({
  const t = useTranslations("messages")
  const [tab, setTab] = useState<Tab>(initialType === "sent" ? "sent" : "inbox")
  const [currentPage, setCurrentPage] = useState(1)
+  const [starredOverride, setStarredOverride] = useState<Record<string, boolean>>({})
+  const [togglingStarId, setTogglingStarId] = useState<string | null>(null)
  const { hasPermission } = usePermission()
  const canSend = hasPermission(Permissions.MESSAGE_SEND)

@@ -69,6 +72,38 @@ export function MessageList({
    setCurrentPage(1)
  }

+  const getIsStarred = (m: Message): boolean => {
+    const override = starredOverride[m.id]
+    return override === undefined ? m.isStarred : override
+  }
+
+  const handleToggleStar = useCallback(
+    async (e: React.MouseEvent, messageId: string, currentStarred: boolean): Promise<void> => {
+      e.preventDefault()
+      e.stopPropagation()
+      setTogglingStarId(messageId)
+      // 乐观更新
+      setStarredOverride((prev) => ({ ...prev, [messageId]: !currentStarred }))
+      try {
+        const res = await toggleMessageStarAction(messageId)
+        if (res.success) {
+          toast.success(t("messages.starToggled"))
+        } else {
+          // 回滚
+          setStarredOverride((prev) => ({ ...prev, [messageId]: currentStarred }))
+          toast.error(res.message)
+        }
+      } catch {
+        // 回滚
+        setStarredOverride((prev) => ({ ...prev, [messageId]: currentStarred }))
+        toast.error(t("messages.sendFailed"))
+      } finally {
+        setTogglingStarId(null)
+      }
+    },
+    [t]
+  )
+
  return (
    <div className="space-y-6">
      <div className="flex flex-wrap items-center justify-between gap-3">
@@ -128,6 +163,7 @@ export function MessageList({
              const isReceived = m.receiverId === currentUserId
              const counterpart = isReceived ? m.senderName : m.receiverName
              const unread = isReceived && !m.isRead
+              const isStarred = getIsStarred(m)
              return (
                <Link key={m.id} href={`/messages/${m.id}`} className="block" aria-label={m.subject ?? t("meta.noSubject")}>
                  <Card className={cn("transition-colors hover:bg-accent/50", unread && "border-primary/40")}>
@@ -143,14 +179,33 @@ export function MessageList({
                            {m.subject ?? t("meta.noSubject")}
                          </span>
                          {unread ? <Badge variant="default" className="text-xs">{t("status.new")}</Badge> : null}
+                          {isStarred ? (
+                            <Star className="h-3.5 w-3.5 fill-yellow-400 text-yellow-400" aria-hidden="true" />
+                          ) : null}
                        </div>
                        <p className="text-muted-foreground text-xs">
                          {isReceived ? t("meta.from") : t("meta.to")}: {counterpart ?? t("meta.unknown")}
                        </p>
                      </div>
-                      <span className="text-muted-foreground shrink-0 text-xs">
-                        {formatDate(m.createdAt)}
-                      </span>
+                      <div className="flex shrink-0 items-center gap-1">
+                        <button
+                          type="button"
+                          onClick={(e) => void handleToggleStar(e, m.id, isStarred)}
+                          disabled={togglingStarId === m.id}
+                          aria-label={isStarred ? t("actions.unstar") : t("actions.star")}
+                          className="text-muted-foreground hover:text-foreground inline-flex size-7 items-center justify-center rounded-md transition-colors hover:bg-accent disabled:opacity-50"
+                        >
+                          <Star
+                            className={cn(
+                              "h-4 w-4 transition-colors",
+                              isStarred && "fill-yellow-400 text-yellow-400"
+                            )}
+                          />
+                        </button>
+                        <span className="text-muted-foreground text-xs">
+                          {formatDate(m.createdAt)}
+                        </span>
+                      </div>
                    </CardHeader>
                    <CardContent className="pt-0">
                      <p className="text-muted-foreground line-clamp-2 text-sm whitespace-pre-wrap">