feat(阶段4): 教程 / 练习 / AI 学情报告的后台接口

GET/POST admin/tutorials GET/PUT/DELETE admin/tutorials/:id PUT admin/tutorials/:id/visibility GET admin/tutorials/:id/exercises POST admin/exercises PUT/DELETE admin/exercises/:id GET admin/ai/reports （?pinnedOnly=true 不分页） GET admin/ai/reports/:id POST admin/ai/reports/:id/pin 几处判断： - 练习改成挂在教程下的嵌套路径，旧后端是 ?tutorial_id= 查询参数。本来就是一对多的从属关系，嵌套更贴事实，也省掉「忘了传 tutorial_id」这类错误。 - 删教程必须先删练习。Django 的 on_delete=CASCADE 是应用层实现的，库里外键实际是 NO ACTION（核对过 pg_constraint.confdeltype='a'），直接删会撞外键变 500。已实测：带 2 个练习的教程能正常删掉且练习一并清除。**后台每个 DELETE 都要照此核一遍子表**，这是本阶段的通用陷阱。 - 改可见性不动 updatedAt —— 上下架不是内容修改，改了会打乱按更新时间排序的直觉。 - AI 报告的 data / systemPrompt / userPrompt 一律不下发，里面是喂给模型的原始学情数据与提示词。列表只给 120 字摘要，与旧 AIAnalysisListSerializer 一致。实测：匿名 401 / 学生 403 / 超管 200；教程练习增删改查、非法 type 400、挂到不存在的教程 404、置顶互斥（同一学生至多一份）、再钉一次取消，全部符合预期。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-07 07:10:34 -06:00
parent 9a6c3ba225
commit af9cb796bd
5 changed files with 441 additions and 19 deletions
@@ -0,0 +1,185 @@
+import {
+  adminExerciseSchema,
+  adminTutorialGroupsSchema,
+  adminTutorialSchema,
+  createExerciseRequestSchema,
+  createTutorialRequestSchema,
+  setTutorialVisibilityRequestSchema,
+  updateExerciseRequestSchema,
+  updateTutorialRequestSchema,
+} from "@oj2/contract"
+import { asc, desc, eq } from "drizzle-orm"
+import { Hono } from "hono"
+
+import { requireSuperAdmin, type AppEnv } from "../../auth/middleware"
+import { db, schema } from "../../db"
+import { failure, success } from "../../http"
+import { objectValue, queryInteger, sampleUser } from "../helpers"
+
+export const adminTutorialRoutes = new Hono<AppEnv>()
+
+function serializeTutorial(row: {
+  tutorial: typeof schema.tutorial.$inferSelect
+  user: typeof schema.user.$inferSelect
+  realName: string | null
+}) {
+  return adminTutorialSchema.parse({
+    id: row.tutorial.id,
+    title: row.tutorial.title,
+    content: row.tutorial.content,
+    code: row.tutorial.code,
+    isPublic: row.tutorial.isPublic,
+    order: row.tutorial.order,
+    type: row.tutorial.type,
+    createdBy: sampleUser(row.user, row.realName),
+    createdAt: row.tutorial.createdAt,
+    updatedAt: row.tutorial.updatedAt,
+  })
+}
+
+function selectTutorial(id: number) {
+  return db
+    .select({ tutorial: schema.tutorial, user: schema.user, realName: schema.userProfile.realName })
+    .from(schema.tutorial)
+    .innerJoin(schema.user, eq(schema.tutorial.createdById, schema.user.id))
+    .leftJoin(schema.userProfile, eq(schema.userProfile.userId, schema.user.id))
+    .where(eq(schema.tutorial.id, id))
+    .limit(1)
+}
+
+adminTutorialRoutes.get("/tutorials", requireSuperAdmin, async (c) => {
+  const rows = await db
+    .select({ tutorial: schema.tutorial, user: schema.user, realName: schema.userProfile.realName })
+    .from(schema.tutorial)
+    .innerJoin(schema.user, eq(schema.tutorial.createdById, schema.user.id))
+    .leftJoin(schema.userProfile, eq(schema.userProfile.userId, schema.user.id))
+    .orderBy(asc(schema.tutorial.order), desc(schema.tutorial.createdAt))
+  const all = rows.map(serializeTutorial)
+  // 分组返回，形状对齐旧 TutorialAdminAPI.get；列表 schema omit 掉了 content/code，Zod 会 strip
+  return success(c, adminTutorialGroupsSchema.parse({
+    python: all.filter((item) => item.type === "python"),
+    c: all.filter((item) => item.type === "c"),
+  }))
+})
+
+adminTutorialRoutes.post("/tutorials", requireSuperAdmin, async (c) => {
+  const parsed = createTutorialRequestSchema.safeParse(await c.req.json().catch(() => null))
+  if (!parsed.success) {
+    return failure(c, 400, "invalid-request", parsed.error.issues[0]?.message ?? "Invalid payload")
+  }
+  const now = new Date().toISOString()
+  const [created] = await db.insert(schema.tutorial).values({
+    ...parsed.data,
+    createdAt: now,
+    updatedAt: now,
+    createdById: c.get("user")!.id,
+  }).returning({ id: schema.tutorial.id })
+  const [row] = await selectTutorial(created!.id)
+  return success(c, serializeTutorial(row!), 201)
+})
+
+adminTutorialRoutes.get("/tutorials/:id", requireSuperAdmin, async (c) => {
+  const [row] = await selectTutorial(queryInteger(c.req.param("id"), 0, { min: 1 }))
+  if (!row) return failure(c, 404, "tutorial-not-found", "Tutorial does not exist")
+  return success(c, serializeTutorial(row))
+})
+
+adminTutorialRoutes.put("/tutorials/:id", requireSuperAdmin, async (c) => {
+  const id = queryInteger(c.req.param("id"), 0, { min: 1 })
+  const parsed = updateTutorialRequestSchema.safeParse(await c.req.json().catch(() => null))
+  if (!parsed.success) {
+    return failure(c, 400, "invalid-request", parsed.error.issues[0]?.message ?? "Invalid payload")
+  }
+  const updated = await db.update(schema.tutorial)
+    .set({ ...parsed.data, updatedAt: new Date().toISOString() })
+    .where(eq(schema.tutorial.id, id)).returning({ id: schema.tutorial.id })
+  if (updated.length === 0) return failure(c, 404, "tutorial-not-found", "Tutorial does not exist")
+  const [row] = await selectTutorial(id)
+  return success(c, serializeTutorial(row!))
+})
+
+adminTutorialRoutes.put("/tutorials/:id/visibility", requireSuperAdmin, async (c) => {
+  const id = queryInteger(c.req.param("id"), 0, { min: 1 })
+  const parsed = setTutorialVisibilityRequestSchema.safeParse(await c.req.json().catch(() => null))
+  if (!parsed.success) return failure(c, 400, "invalid-request", "isPublic is required")
+  // 只改可见性，不动 updatedAt —— 上下架不是内容修改，改了会打乱按更新时间排序的直觉
+  const updated = await db.update(schema.tutorial)
+    .set({ isPublic: parsed.data.isPublic })
+    .where(eq(schema.tutorial.id, id)).returning({ id: schema.tutorial.id })
+  if (updated.length === 0) return failure(c, 404, "tutorial-not-found", "Tutorial does not exist")
+  const [row] = await selectTutorial(id)
+  return success(c, serializeTutorial(row!))
+})
+
+adminTutorialRoutes.delete("/tutorials/:id", requireSuperAdmin, async (c) => {
+  const id = queryInteger(c.req.param("id"), 0, { min: 1 })
+  // 必须先删练习。Django 的 on_delete=CASCADE 是**应用层**实现的，
+  // 库里的外键实际是 NO ACTION（已核对 pg_constraint.confdeltype='a'），
+  // 直接删教程会撞外键约束、变成 500。后台每个 DELETE 都要照此核一遍子表。
+  const deleted = await db.transaction(async (tx) => {
+    await tx.delete(schema.exercise).where(eq(schema.exercise.tutorialId, id))
+    return tx.delete(schema.tutorial).where(eq(schema.tutorial.id, id))
+      .returning({ id: schema.tutorial.id })
+  })
+  if (deleted.length === 0) return failure(c, 404, "tutorial-not-found", "Tutorial does not exist")
+  return success(c, null)
+})
+
+// ---------------------------------------------------------------- 练习
+
+function serializeExercise(row: typeof schema.exercise.$inferSelect) {
+  return adminExerciseSchema.parse({
+    id: row.id,
+    type: row.type,
+    data: objectValue(row.data),
+    order: row.order,
+  })
+}
+
+// 练习挂在教程下，路径嵌套 —— 旧后端是 ?tutorial_id= 查询参数，
+// 但它本来就是一对多的从属关系，嵌套路径更贴事实，也省掉「忘了传 tutorial_id」这类错误
+adminTutorialRoutes.get("/tutorials/:id/exercises", requireSuperAdmin, async (c) => {
+  const rows = await db.select().from(schema.exercise)
+    .where(eq(schema.exercise.tutorialId, queryInteger(c.req.param("id"), 0, { min: 1 })))
+    .orderBy(asc(schema.exercise.order), asc(schema.exercise.id))
+  return success(c, rows.map(serializeExercise))
+})
+
+adminTutorialRoutes.post("/exercises", requireSuperAdmin, async (c) => {
+  const parsed = createExerciseRequestSchema.safeParse(await c.req.json().catch(() => null))
+  if (!parsed.success) {
+    return failure(c, 400, "invalid-request", parsed.error.issues[0]?.message ?? "Invalid payload")
+  }
+  const [tutorial] = await db.select({ id: schema.tutorial.id }).from(schema.tutorial)
+    .where(eq(schema.tutorial.id, parsed.data.tutorialId)).limit(1)
+  if (!tutorial) return failure(c, 404, "tutorial-not-found", "Tutorial does not exist")
+  const [created] = await db.insert(schema.exercise).values({
+    tutorialId: parsed.data.tutorialId,
+    type: parsed.data.type,
+    data: parsed.data.data,
+    order: parsed.data.order,
+    createdAt: new Date().toISOString(),
+  }).returning()
+  return success(c, serializeExercise(created!), 201)
+})
+
+adminTutorialRoutes.put("/exercises/:id", requireSuperAdmin, async (c) => {
+  const parsed = updateExerciseRequestSchema.safeParse(await c.req.json().catch(() => null))
+  if (!parsed.success) {
+    return failure(c, 400, "invalid-request", parsed.error.issues[0]?.message ?? "Invalid payload")
+  }
+  const [updated] = await db.update(schema.exercise)
+    .set({ type: parsed.data.type, data: parsed.data.data, order: parsed.data.order })
+    .where(eq(schema.exercise.id, queryInteger(c.req.param("id"), 0, { min: 1 })))
+    .returning()
+  if (!updated) return failure(c, 404, "exercise-not-found", "Exercise does not exist")
+  return success(c, serializeExercise(updated))
+})
+
+adminTutorialRoutes.delete("/exercises/:id", requireSuperAdmin, async (c) => {
+  const deleted = await db.delete(schema.exercise)
+    .where(eq(schema.exercise.id, queryInteger(c.req.param("id"), 0, { min: 1 })))
+    .returning({ id: schema.exercise.id })
+  if (deleted.length === 0) return failure(c, 404, "exercise-not-found", "Exercise does not exist")
+  return success(c, null)
+})