fix: punctuation-proof review grouping and catalog-aware course attachment

- group keys strip whitespace and unify 、/，/·/－ variants so courses split
  by a single punctuation mark merge into one review group
- review groups resolve course attachment through the handbook catalog
  (name + aliases) before falling back to unmatched, so catalog-named and
  legacy-variant reviews attach to manifest course pages (mini-program
  course detail reviews included)

Author: shview

server/public-api-dto.mjs

@@ -31,9 +31,19 @@ export function normalizeReviewKeyPart(value) {
   return text(value, 120);
 }
 
+// 分组键专用：抹平空格与顿号/逗号/中点等符号差异，
+// 避免同一门课因「、/，」「多一个空格」被拆成两个评价组。
+function groupKeyPart(value) {
+  return normalizeReviewKeyPart(value)
+    .replace(/\s+/g, "")
+    .replace(/[、，,．。：:；;·—\-_/\\]/g, "")
+    .replace(/（/g, "(")
+    .replace(/）/g, ")");
+}
+
 export function reviewGroupKey(courseTitle, teacher) {
   return createHash("sha256")
-    .update(`${normalizeReviewKeyPart(courseTitle)}\0${normalizeReviewKeyPart(teacher)}`, "utf8")
+    .update(`${groupKeyPart(courseTitle)}\0${groupKeyPart(teacher)}`, "utf8")
     .digest("base64url")
     .slice(0, 24);
 }
@@ -100,20 +110,32 @@ export function publicReviewDto(review) {
   };
 }
 
-export function buildReviewGroups(manifest, reviewData) {
+export function buildReviewGroups(manifest, reviewData, courseCatalog = null) {
   const coursesByTitle = new Map();
   for (const course of manifest.courses || []) {
     const title = normalizeReviewKeyPart(course.title);
     if (!coursesByTitle.has(title)) coursesByTitle.set(title, course);
   }
+  const resolveCourse = (courseTitle) => {
+    const direct = coursesByTitle.get(courseTitle);
+    if (direct) return direct;
+    // 经课程目录解析：评价课程名 -> 目录条目（含别名） -> 再尝试其规范名与别名匹配课程库
+    const entry = courseCatalog?.find?.(courseTitle);
+    if (!entry) return null;
+    for (const candidate of [entry.name, ...(entry.aliases || [])]) {
+      const hit = coursesByTitle.get(normalizeReviewKeyPart(candidate));
+      if (hit) return hit;
+    }
+    return null;
+  };
   const groups = new Map();
   for (const review of reviewData?.reviews || []) {
     if (!approvedReview(review)) continue;
     const courseTitle = normalizeReviewKeyPart(review.courseTitle);
     const teacher = normalizeReviewKeyPart(review.teacher);
     if (!courseTitle || !teacher) continue;
     const key = reviewGroupKey(courseTitle, teacher);
-    const course = coursesByTitle.get(courseTitle) || null;
+    const course = resolveCourse(courseTitle);
     if (!groups.has(key)) {
       groups.set(key, { key, courseTitle, teacher, course, reviews: [] });
     }

server/public-api-service.mjs

@@ -75,7 +75,7 @@ export class PublicApiService {
     const manifest = this.readManifest();
     const reviewData = this.readReviews();
     if (!manifest || !Array.isArray(manifest.courses)) throw new Error("Runtime course data is unavailable.");
-    const groups = buildReviewGroups(manifest, reviewData);
+    const groups = buildReviewGroups(manifest, reviewData, this.courseCatalog);
     const normalizedGuides = normalizeGuideData(this.readGuides(), {
       courseIds: new Set(manifest.courses.map((course) => course.uid)),
       fallbackCorrectionUrl: this.guideCorrectionUrl,

test/public-api.test.mjs

@@ -200,3 +200,28 @@ test("mini-program review body maps into the shared submission service", async (
   assert.equal(submissions[1].input.content, "足够长的课程评价正文内容。");
   assert.equal(Object.hasOwn(submissions[1].input, "anonymous"), false);
 });
+
+test("review groups merge punctuation variants and resolve catalog aliases", async () => {
+  const { buildReviewGroups } = await import("../server/public-api-dto.mjs");
+  const manifest = { courses: [{ id: "c1", uid: "u1", title: "光、视觉与艺术" }] };
+  const reviewData = {
+    reviews: [
+      { id: "r1", courseTitle: "光、视觉与艺术", teacher: "张三", rating: 5, content: "a", status: "approved", createdAt: "2026-01-01" },
+      { id: "r2", courseTitle: "光，视觉与艺术", teacher: "张三", rating: 4, content: "b", status: "approved", createdAt: "2026-01-02" },
+      { id: "r3", courseTitle: "人工智能与创新 （C++）", teacher: "李四", rating: 5, content: "c", status: "approved", createdAt: "2026-01-03" },
+      { id: "r4", courseTitle: "人工智能与创新（C++）", teacher: "李四", rating: 3, content: "d", status: "approved", createdAt: "2026-01-04" },
+    ],
+  };
+  const groups = buildReviewGroups(manifest, reviewData);
+  assert.equal(groups.length, 2, "punctuation variants merge into one group each");
+  const guang = groups.find((g) => g.courseTitle === "光、视觉与艺术");
+  assert.equal(guang.reviews.length, 2);
+  assert.equal(guang.course?.id, "c1", "direct title attaches the course");
+
+  // 目录别名解析挂接
+  const fakeCatalog = { find: (name) => (name.includes("视觉") ? { name: "光、视觉与艺术", aliases: [] } : null) };
+  const manifest2 = { courses: [{ id: "c2", uid: "u2", title: "光、视觉与艺术" }] };
+  const reviewData2 = { reviews: [{ id: "r5", courseTitle: "光，视觉与艺术", teacher: "王五", rating: 5, content: "e", status: "approved", createdAt: "2026-01-05" }] };
+  const groups2 = buildReviewGroups(manifest2, reviewData2, fakeCatalog);
+  assert.equal(groups2[0].course?.id, "c2", "catalog alias resolution attaches unmatched titles");
+});