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

feat(ai): 新增 AI 模块并集成至备课/错题集/试卷/改题四大业务场景

Browse Source 
- 新增 src/modules/ai 独立模块，遵循三层架构（actions → services → shared/lib/ai）
- 通过 AiClientProvider + useAiClient 实现 React Context 依赖注入，业务组件零直接 import
- 6 个 Server Actions 均调用 requirePermission() 权限校验，返回 ActionState<T>
- withAiTracking 统一埋点，覆盖 chat/similar_question/grading_assist/lesson_content/question_variant/weakness_analysis
- 集成场景：作业批改 AiGradingAssist、错题集 AiErrorBookAnalysis、备课 AiLessonContentGenerator、试卷 AiQuestionVariantGenerator
- 全量 i18n（en/zh-CN ai.json），Error Boundary + Skeleton 边界处理
- 同步架构图 004/005，新增审计报告 ai-module-audit-report.md
This commit is contained in:
SpecialX
2026-06-23 00:52:39 +08:00
parent ec87cd9efa
commit 21c5eba96c
40 changed files with 4885 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
src/modules/lesson-preparation/actions-ai.ts
View File

@@ -4,10 +4,11 @@ import { getTranslations } from "next-intl/server";
import { requirePermission, PermissionDeniedError } from "@/shared/lib/auth-guard";
import { Permissions } from "@/shared/types/permissions";
import { suggestKnowledgePoints } from "./ai-suggest";
import type { ActionState, LessonPlanDocument } from "./types";
import { suggestKnowledgePointsSchema } from "./schema";
import type { ActionState } from "@/shared/types/action-state";
export async function suggestKnowledgePointsAction(input: {
doc: LessonPlanDocument;
doc: unknown;
textbookId?: string;
chapterId?: string;
}): Promise<
@@ -17,12 +18,24 @@ export async function suggestKnowledgePointsAction(input: {
> {
const t = await getTranslations("lessonPreparation");
try {
await requirePermission(Permissions.LESSON_PLAN_READ);
await requirePermission(Permissions.AI_CHAT);
const parsed = suggestKnowledgePointsSchema.safeParse(input);
if (!parsed.success) {
return { success: false, errors: parsed.error.flatten().fieldErrors };
}
// 并行校验两个权限点
await Promise.all([
requirePermission(Permissions.LESSON_PLAN_READ),
requirePermission(Permissions.AI_CHAT),
]);
// 从 unknown 安全提取 nodes 数组：Zod 已校验 doc 是对象
const doc = parsed.data.doc;
const nodes = Array.isArray(doc.nodes) ? doc.nodes : [];
const suggestions = await suggestKnowledgePoints(
input.doc,
input.textbookId,
input.chapterId,
{ nodes },
parsed.data.textbookId,
parsed.data.chapterId,
);
return { success: true, data: { suggestions } };
} catch (e) {

41
src/modules/lesson-preparation/ai-suggest.ts
View File

@@ -1,24 +1,43 @@
import "server-only";
import { z } from "zod";
import { env } from "@/env.mjs";
import { createAiChatCompletion } from "@/shared/lib/ai";
import {
getKnowledgePointsByTextbookId,
getKnowledgePointsByChapterId,
} from "@/modules/textbooks/data-access";
import type { LessonPlanDocument } from "./types";
const SuggestedKpSchema = z.object({
id: z.string().min(1),
name: z.string().min(1),
reason: z.string(),
});
const SuggestedKpListSchema = z.array(SuggestedKpSchema);
/** 从 unknown 节点安全提取文本（类型守卫从 unknown 收窄） */
const extractNodeText = (node: unknown): string => {
if (!node || typeof node !== "object") return ""
// 从 unknown 收窄为 Record<string, unknown> 以进行字段检查
const record = node as Record<string, unknown>
const data = record.data
if (!data || typeof data !== "object") return ""
// 从 unknown 收窄为 Record<string, unknown> 以进行字段检查
const dataRecord = data as Record<string, unknown>
const html = typeof dataRecord.html === "string" ? dataRecord.html : ""
const sourceText = typeof dataRecord.sourceText === "string" ? dataRecord.sourceText : ""
return html || sourceText || ""
}
export async function suggestKnowledgePoints(
doc: LessonPlanDocument,
doc: { nodes: unknown[] },
textbookId?: string,
chapterId?: string,
): Promise<{ id: string; name: string; reason: string }[]> {
// 1. 提取课案纯文本
const text = doc.nodes
.map((b) => {
const d = b.data as { html?: string; sourceText?: string };
return d.html ?? d.sourceText ?? "";
})
.map((b) => extractNodeText(b))
.join("\n")
.slice(0, 3000);
@@ -51,14 +70,12 @@ ${text}
// 尝试从返回内容中提取 JSON 数组
const jsonMatch = content.match(/\[[\s\S]*\]/);
if (!jsonMatch) return [];
const parsed = JSON.parse(jsonMatch[0]) as {
id: string;
name: string;
reason: string;
}[];
const parsed: unknown = JSON.parse(jsonMatch[0]);
const validated = SuggestedKpListSchema.safeParse(parsed);
if (!validated.success) return [];
// 过滤掉不在候选池中的 id
const validIds = new Set(kpList.map((k) => k.id));
return parsed.filter((p) => validIds.has(p.id));
return validated.data.filter((p) => validIds.has(p.id));
} catch {
return [];
}

87
src/modules/lesson-preparation/components/node-edit-panel.tsx
View File

@@ -1,11 +1,15 @@
"use client";
import { useState } from "react";
import { useTranslations } from "next-intl";
import { Sparkles, ChevronDown, ChevronUp } from "lucide-react";
import { useLessonPlanEditor } from "../hooks/use-lesson-plan-editor";
import { BlockRenderer } from "../config/block-registry";
import { LessonPlanErrorBoundary } from "./lesson-plan-error-boundary";
import { Button } from "@/shared/components/ui/button";
import { Trash2, X } from "lucide-react";
import { AiLessonContentGenerator } from "@/modules/ai/components/ai-lesson-content-generator";
import { useAiClientOptional } from "@/modules/ai/context/ai-client-provider";
interface Props {
textbookId?: string;
@@ -15,8 +19,11 @@ interface Props {
export function NodeEditPanel({ textbookId, chapterId, classes }: Props) {
const t = useTranslations("lessonPreparation");
const tAi = useTranslations("ai");
const { doc, selectedNodeId, updateNode, removeNode, selectNode } =
useLessonPlanEditor();
const aiClient = useAiClientOptional();
const [showAiPanel, setShowAiPanel] = useState(false);
const node = doc.nodes.find((n) => n.id === selectedNodeId);
@@ -28,15 +35,45 @@ export function NodeEditPanel({ textbookId, chapterId, classes }: Props) {
);
}
// 正文节点不在侧边面板编辑（直接在画布上交互）
if (node.type === "textbook_content") {
return (
<div className="h-full flex flex-col border-l border-outline-variant bg-surface">
<div className="flex items-center gap-2 px-4 py-2 border-b border-outline-variant">
<span className="flex-1 font-title-md text-title-md">
{t("editor.textbookContent")}
</span>
<Button
variant="ghost"
size="sm"
onClick={() => selectNode(null)}
aria-label={t("action.close")}
>
<X className="w-4 h-4" aria-hidden="true" />
</Button>
</div>
<div className="flex-1 overflow-y-auto p-4 text-sm text-on-surface-variant">
{t("editor.textbookContentEmpty")}
</div>
</div>
);
}
// 教学节点：通过类型守卫收窄为 LessonPlanNode
const lessonNode = node as import("../types").LessonPlanNode;
// 从节点标题提取主题用于 AI 内容生成
const aiTopic = lessonNode.title || t("editor.textbookContent");
return (
<div className="h-full flex flex-col border-l border-outline-variant bg-surface">
{/* 面板头部 */}
<div className="flex items-center gap-2 px-4 py-2 border-b border-outline-variant">
<input
value={node.title}
onChange={(e) => updateNode(node.id, { title: e.target.value })}
value={lessonNode.title}
onChange={(e) => updateNode(lessonNode.id, { title: e.target.value })}
className="flex-1 bg-transparent font-title-md text-title-md focus:outline-none"
aria-label={node.title}
aria-label={lessonNode.title}
/>
<Button
variant="ghost"
@@ -52,17 +89,49 @@ export function NodeEditPanel({ textbookId, chapterId, classes }: Props) {
<div className="flex-1 overflow-y-auto p-3">
<LessonPlanErrorBoundary>
<BlockRenderer
type={node.type}
blockId={node.id}
data={node.data}
type={lessonNode.type}
blockId={lessonNode.id}
data={lessonNode.data}
textbookId={textbookId}
chapterId={chapterId}
classes={classes}
onUpdate={(d) => updateNode(node.id, { data: d })}
onUpdate={(d) => updateNode(lessonNode.id, { data: d })}
/>
{/* BlockRenderer 返回 null 时显示未知类型提示 */}
<UnknownBlockHint type={node.type} t={t} />
<UnknownBlockHint type={lessonNode.type} t={t} />
</LessonPlanErrorBoundary>
{/* AI 内容生成区（可折叠） */}
{aiClient ? (
<div className="mt-4 border-t border-outline-variant pt-3">
<Button
variant="ghost"
size="sm"
className="w-full justify-between"
onClick={() => setShowAiPanel(!showAiPanel)}
aria-expanded={showAiPanel}
>
<span className="flex items-center gap-1">
<Sparkles className="w-3.5 h-3.5 text-primary" />
{tAi("lessonPrep.generateContent")}
</span>
{showAiPanel ? (
<ChevronUp className="w-3.5 h-3.5" />
) : (
<ChevronDown className="w-3.5 h-3.5" />
)}
</Button>
{showAiPanel ? (
<div className="mt-2">
<AiLessonContentGenerator
topic={aiTopic}
textbookId={textbookId}
chapterId={chapterId}
/>
</div>
) : null}
</div>
) : null}
</div>
{/* 底部操作 */}
@@ -71,7 +140,7 @@ export function NodeEditPanel({ textbookId, chapterId, classes }: Props) {
variant="outline"
size="sm"
className="text-error"
onClick={() => removeNode(node.id)}
onClick={() => removeNode(lessonNode.id)}
>
<Trash2 className="w-3 h-3 mr-1" aria-hidden="true" />
{t("action.delete")}