xiner/NextEdu
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

refactor(announcements,messaging,notifications): V1+V2 审计重构 — i18n 命名空间独立 + 通知标题 i18n 化 + 服务端过滤 + 编排下沉 + 表单错误展示 + 架构图同步

Browse Source 
V1 改进（已完成）:
- P0-4/P1-4/P1-5: 通知组件和 CRUD Action 从 messaging 迁移至 notifications 模块
- P1-5: 新增 getMessagesPageData / getAdminAnnouncementsPageData 编排函数
- P1-6: announcements schema 添加 superRefine 条件校验
- P1-7: 新增 useMessageSearch hook（防抖 + 请求竞态取消）+ 客户端分页 UI
- P1-9: deleteMessage 事务化
- P2-11: 全模块 trackEvent 埋点
- 全模块 i18n 接入 + Error Boundary + a11y 改进

V2 改进（本次完成）:
- V2-P0-1: 通知 i18n 命名空间独立（notifications.json），useTranslations 从 "messages" 切换到 "notifications"
- V2-P0-2: 公告/消息通知标题 i18n 化，Server Action 中使用 getTranslations 生成通知标题
- V2-P1-1: AnnouncementList 纯服务端过滤，移除客户端 useState/useMemo
- V2-P1-2: MessageList 客户端过滤仅在初始数据时执行，搜索结果由服务端按 tab 过滤
- V2-P1-3: 消息详情页编排下沉，新增 getMessageDetailPageData 编排函数
- V2-P1-4: 表单服务端校验错误展示（fieldErrors + aria-invalid）
- V2-P2-1: 轮询间隔常量化（POLL_INTERVAL_MS）
- V2-P2-2: 架构图同步（004 + 005）
This commit is contained in:
SpecialX
2026-06-22 18:43:12 +08:00
parent 6d7838a210
commit 1fe30984b6
29 changed files with 1252 additions and 351 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
src/modules/announcements/actions.ts
View File

@@ -2,8 +2,10 @@
import { revalidatePath } from "next/cache"
import { createId } from "@paralleldrive/cuid2"
import { getTranslations } from "next-intl/server"
import { requirePermission, PermissionDeniedError } from "@/shared/lib/auth-guard"
import { trackEvent } from "@/shared/lib/track-event"
import { Permissions } from "@/shared/types/permissions"
import type { ActionState } from "@/shared/types/action-state"
import { sendBatchNotifications } from "@/modules/notifications"
@@ -69,10 +71,14 @@ async function notifyAnnouncementPublished(announcement: Announcement): Promise<
const targetUserIds = await resolveTargetUserIds(announcement)
if (targetUserIds.length === 0) return
const t = await getTranslations("announcements")
const title = t("notification.publishedTitle", { title: announcement.title })
const content = t("notification.publishedContent")
const payloads: NotificationPayload[] = targetUserIds.map((userId) => ({
userId,
title: `新公告：${announcement.title}`,
content: announcement.content.slice(0, 200),
title,
content,
type: "info",
actionUrl: `/announcements/${announcement.id}`,
metadata: {
@@ -146,6 +152,14 @@ export async function createAnnouncementAction(
revalidatePath("/admin/announcements")
revalidatePath("/announcements")
void trackEvent({
event: isPublished ? "announcement.published" : "announcement.created",
userId: ctx.userId,
targetId: id,
targetType: "announcement",
properties: { type: input.type, status: input.status },
})
return { success: true, message: "Announcement created", data: id }
} catch (e) {
return handleActionError(e)
@@ -215,6 +229,13 @@ export async function updateAnnouncementAction(
revalidatePath(`/admin/announcements/${id}`)
revalidatePath("/announcements")
void trackEvent({
event: isPublished && !wasPublished ? "announcement.published" : "announcement.updated",
targetId: id,
targetType: "announcement",
properties: { type: input.type, status: input.status, wasPublished },
})
return { success: true, message: "Announcement updated", data: id }
} catch (e) {
return handleActionError(e)
@@ -233,6 +254,13 @@ export async function deleteAnnouncementAction(id: string): Promise<ActionState<
revalidatePath("/admin/announcements")
revalidatePath("/announcements")
void trackEvent({
event: "announcement.deleted",
targetId: id,
targetType: "announcement",
properties: { type: existing.type, status: existing.status },
})
return { success: true, message: "Announcement deleted" }
} catch (e) {
return handleActionError(e)
@@ -258,6 +286,13 @@ export async function publishAnnouncementAction(id: string): Promise<ActionState
revalidatePath(`/admin/announcements/${id}`)
revalidatePath("/announcements")
void trackEvent({
event: "announcement.published",
targetId: id,
targetType: "announcement",
properties: { type: existing.type },
})
return { success: true, message: "Announcement published" }
} catch (e) {
return handleActionError(e)
@@ -277,6 +312,13 @@ export async function archiveAnnouncementAction(id: string): Promise<ActionState
revalidatePath(`/admin/announcements/${id}`)
revalidatePath("/announcements")
void trackEvent({
event: "announcement.archived",
targetId: id,
targetType: "announcement",
properties: { type: existing.type },
})
return { success: true, message: "Announcement archived" }
} catch (e) {
return handleActionError(e)

31
src/modules/announcements/components/announcement-form.tsx
View File

@@ -23,6 +23,8 @@ import type { Announcement } from "../types"
type Mode = "create" | "edit"
type FieldErrors = Record<string, string[]>
export function AnnouncementForm({
mode,
announcement,
@@ -37,14 +39,21 @@ export function AnnouncementForm({
const t = useTranslations("announcements")
const router = useRouter()
const [isWorking, setIsWorking] = useState(false)
const [fieldErrors, setFieldErrors] = useState<FieldErrors>({})
const [type, setType] = useState<string>(announcement?.type ?? "school")
const [status, setStatus] = useState<string>(announcement?.status ?? "draft")
const [targetGradeId, setTargetGradeId] = useState<string>(announcement?.targetGradeId ?? "")
const [targetClassId, setTargetClassId] = useState<string>(announcement?.targetClassId ?? "")
const getFieldError = (field: string): string | null => {
const errs = fieldErrors[field]
return errs && errs.length > 0 ? errs[0] : null
}
const handleSubmit = async (formData: FormData) => {
setIsWorking(true)
setFieldErrors({})
try {
formData.set("type", type)
formData.set("status", status)
@@ -72,6 +81,10 @@ export function AnnouncementForm({
router.push("/admin/announcements")
router.refresh()
} else {
// 展示字段级错误（来自 Zod superRefine 校验）
if (res.errors) {
setFieldErrors(res.errors)
}
toast.error(res.message || t("messages.updateFailed"))
}
} catch {
@@ -98,7 +111,11 @@ export function AnnouncementForm({
placeholder={t("form.titlePlaceholder")}
defaultValue={announcement?.title ?? ""}
required
aria-invalid={!!getFieldError("title")}
/>
{getFieldError("title") ? (
<p className="text-destructive text-xs">{getFieldError("title")}</p>
) : null}
</div>
<div className="grid gap-2">
@@ -110,7 +127,11 @@ export function AnnouncementForm({
className="min-h-[160px]"
defaultValue={announcement?.content ?? ""}
required
aria-invalid={!!getFieldError("content")}
/>
{getFieldError("content") ? (
<p className="text-destructive text-xs">{getFieldError("content")}</p>
) : null}
</div>
<div className="grid grid-cols-1 gap-4 md:grid-cols-2">
@@ -148,7 +169,7 @@ export function AnnouncementForm({
<div className="grid gap-2 md:col-span-2">
<Label>{t("form.targetGrade")}</Label>
<Select value={targetGradeId} onValueChange={setTargetGradeId}>
<SelectTrigger>
<SelectTrigger aria-invalid={!!getFieldError("targetGradeId")}>
<SelectValue placeholder={t("form.targetGradePlaceholder")} />
</SelectTrigger>
<SelectContent>
@@ -160,6 +181,9 @@ export function AnnouncementForm({
</SelectContent>
</Select>
<input type="hidden" name="targetGradeId" value={targetGradeId} />
{getFieldError("targetGradeId") ? (
<p className="text-destructive text-xs">{getFieldError("targetGradeId")}</p>
) : null}
</div>
) : null}
@@ -167,7 +191,7 @@ export function AnnouncementForm({
<div className="grid gap-2 md:col-span-2">
<Label>{t("form.targetClass")}</Label>
<Select value={targetClassId} onValueChange={setTargetClassId}>
<SelectTrigger>
<SelectTrigger aria-invalid={!!getFieldError("targetClassId")}>
<SelectValue placeholder={t("form.targetClassPlaceholder")} />
</SelectTrigger>
<SelectContent>
@@ -179,6 +203,9 @@ export function AnnouncementForm({
</SelectContent>
</Select>
<input type="hidden" name="targetClassId" value={targetClassId} />
{getFieldError("targetClassId") ? (
<p className="text-destructive text-xs">{getFieldError("targetClassId")}</p>
) : null}
</div>
) : null}
</div>

25
src/modules/announcements/components/announcement-list.tsx
View File

@@ -1,6 +1,5 @@
"use client"
import { useMemo, useState } from "react"
import Link from "next/link"
import { useRouter } from "next/navigation"
import { Plus, Megaphone } from "lucide-react"
@@ -21,6 +20,14 @@ import type { Announcement, AnnouncementStatus } from "../types"
type Filter = "all" | AnnouncementStatus
/**
* 公告列表组件。
*
* 过滤模式：纯服务端过滤。
* - Select 切换时更新 URL `?status=`，触发 RSC 重新渲染
* - 父页面根据 `?status=` 查询并传入 `announcements` prop
* - 组件不再做客户端二次过滤，避免双重过滤逻辑冗余
*/
export function AnnouncementList({
announcements,
canManage,
@@ -36,7 +43,7 @@ export function AnnouncementList({
}) {
const t = useTranslations("announcements")
const router = useRouter()
const [filter, setFilter] = useState<Filter>(initialStatus ?? "all")
const filter: Filter = initialStatus ?? "all"
const filterOptions: { value: Filter; label: string }[] = [
{ value: "all", label: t("filter.all") },
@@ -45,13 +52,7 @@ export function AnnouncementList({
{ value: "archived", label: t("filter.archived") },
]
const filtered = useMemo(() => {
if (filter === "all") return announcements
return announcements.filter((a) => a.status === filter)
}, [announcements, filter])
const handleFilterChange = (value: string) => {
setFilter(value as Filter)
const handleFilterChange = (value: string): void => {
const params = new URLSearchParams()
if (value !== "all") params.set("status", value)
const qs = params.toString()
@@ -83,11 +84,11 @@ export function AnnouncementList({
) : null}
</div>
{filtered.length === 0 ? (
{announcements.length === 0 ? (
<EmptyState
title={t("empty.noAnnouncements")}
description={
announcements.length === 0
filter === "all"
? t("empty.noAnnouncementsDesc")
: t("empty.noMatch")
}
@@ -96,7 +97,7 @@ export function AnnouncementList({
/>
) : (
<div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
{filtered.map((a) => (
{announcements.map((a) => (
<AnnouncementCard
key={a.id}
announcement={a}

47
src/modules/announcements/data-access.ts
View File

@@ -8,6 +8,7 @@ import { announcements, users } from "@/shared/db/schema"
import type {
Announcement,
AnnouncementInsertData,
AnnouncementStatus,
AnnouncementUpdateData,
GetAnnouncementsParams,
} from "./types"
@@ -195,3 +196,49 @@ export async function archiveAnnouncementById(id: string): Promise<void> {
})
.where(eq(announcements.id, id))
}
/**
* 管理端公告列表页编排函数：一次性获取公告列表、年级列表、班级列表。
* 将原本散落在 page.tsx 中的多模块编排逻辑下沉到 data-access 层，
* 页面层只需调用单一函数，提升可复用性与可测试性。
*/
export async function getAdminAnnouncementsPageData(status?: AnnouncementStatus): Promise<{
announcements: Announcement[]
grades: { id: string; name: string }[]
classes: { id: string; name: string }[]
}> {
const { getGrades } = await import("@/modules/school/data-access")
const { getAdminClasses } = await import("@/modules/classes/data-access")
const [announcementList, gradeList, classList] = await Promise.all([
getAnnouncements({ status }),
getGrades(),
getAdminClasses(),
])
return {
announcements: announcementList,
grades: gradeList.map((g) => ({ id: g.id, name: g.name })),
classes: classList.map((c) => ({ id: c.id, name: c.name })),
}
}
/**
* 管理端公告编辑页编排函数：一次性获取公告详情和年级列表。
*/
export async function getEditAnnouncementPageData(id: string): Promise<{
announcement: Announcement | null
grades: { id: string; name: string }[]
}> {
const { getGrades } = await import("@/modules/school/data-access")
const [announcement, gradeList] = await Promise.all([
getAnnouncementById(id),
getGrades(),
])
return {
announcement,
grades: gradeList.map((g) => ({ id: g.id, name: g.name })),
}
}

50
src/modules/announcements/schema.ts
View File

@@ -1,5 +1,53 @@
import { z } from "zod"
/**
* 公告类型与目标受众的联合校验：
* - type=school：targetGradeId / targetClassId 必须为空
* - type=grade：targetGradeId 必填，targetClassId 必须为空
* - type=class：targetClassId 必填
*
* 避免"创建无受众公告"的数据完整性问题。
*/
const refineAudience = (
data: {
type?: "school" | "grade" | "class"
targetGradeId?: string | null
targetClassId?: string | null
},
ctx: z.RefinementCtx
): void => {
const type = data.type ?? "school"
const hasGrade = (data.targetGradeId ?? "").trim().length > 0
const hasClass = (data.targetClassId ?? "").trim().length > 0
if (type === "school" && (hasGrade || hasClass)) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
path: ["targetGradeId"],
message: "全校公告不应指定目标年级或班级",
})
return
}
if (type === "grade" && !hasGrade) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
path: ["targetGradeId"],
message: "年级公告必须指定目标年级",
})
return
}
if (type === "class" && !hasClass) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
path: ["targetClassId"],
message: "班级公告必须指定目标班级",
})
return
}
}
export const CreateAnnouncementSchema = z
.object({
title: z.string().trim().min(1).max(255),
@@ -10,6 +58,7 @@ export const CreateAnnouncementSchema = z
targetClassId: z.string().trim().optional().nullable(),
publishedAt: z.string().optional().nullable(),
})
.superRefine(refineAudience)
.transform((v) => ({
title: v.title,
content: v.content,
@@ -32,6 +81,7 @@ export const UpdateAnnouncementSchema = z
targetClassId: z.string().trim().optional().nullable(),
publishedAt: z.string().optional().nullable(),
})
.superRefine(refineAudience)
.transform((v) => ({
title: v.title,
content: v.content,