Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(mastery): show teach-first guidance and localized next step (#1527)

Bingxi Zhao (Frank)5b4c15afec60
diff --git a/web/app/(workspace)/learning/mastery/[pathId]/page.tsx b/web/app/(workspace)/learning/mastery/[pathId]/page.tsx
index 953ddae8f..6202c6a38 100644
--- a/web/app/(workspace)/learning/mastery/[pathId]/page.tsx
+++ b/web/app/(workspace)/learning/mastery/[pathId]/page.tsx
@@ -55,39 +55,7 @@ import {
type TopicSession,
} from "@/lib/learning-api";
import { setPendingPrompt } from "@/lib/pending-prompt";
-
-const NEXT_LABELS: Record<string, { zh: string; en: string }> = {
- probe: {
- zh: "先用一道探查题看看你是否已经掌握",
- en: "Start with a probe and test out if you already know it",
- },
- practice: {
- zh: "继续练习,直到稳定越过掌握门槛",
- en: "Practice until you reliably clear the mastery gate",
- },
- assess: {
- zh: "用自己的话讲清楚这个概念",
- en: "Explain this clearly in your own words",
- },
- review: { zh: "复习这个记忆信标", en: "Revisit this memory beacon" },
- answer_pending: {
- zh: "完成导师正在等待的回答",
- en: "Complete the answer your tutor is waiting for",
- },
- complete: {
- zh: "整片疆域已经点亮",
- en: "The whole territory is illuminated",
- },
-};
-
-const NEXT_CTA_LABELS: Record<string, { zh: string; en: string }> = {
- review: { zh: "开始本次复习", en: "Start this review" },
- answer_pending: {
- zh: "回到原会话作答",
- en: "Answer in the original session",
- },
- complete: { zh: "继续自由探索", en: "Keep exploring" },
-};
+import { NEXT_CTA_LABELS, NEXT_LABELS } from "@/components/space/learning/next-step-copy";
export default function MasteryTopicPage() {
const params = useParams<{ pathId: string }>();
diff --git a/web/components/space/learning/LearnerProfileCard.tsx b/web/components/space/learning/LearnerProfileCard.tsx
index 2165f772e..400df3e20 100644
--- a/web/components/space/learning/LearnerProfileCard.tsx
+++ b/web/components/space/learning/LearnerProfileCard.tsx
@@ -4,6 +4,7 @@ import { UserRound } from "lucide-react";
import { useTranslation } from "react-i18next";
import type { LearnerProfile } from "@/lib/learning-api";
+import { TEACH_FIRST_PROFILE_LABEL } from "./next-step-copy";
/**
* What the tutor knows about the person learning this goal.
@@ -16,14 +17,22 @@ import type { LearnerProfile } from "@/lib/learning-api";
* here would be a second writer with no way to do that second half.
*/
export function LearnerProfileCard({ profile }: { profile: LearnerProfile | null }) {
- const { t } = useTranslation();
+ const { t, i18n } = useTranslation();
+ const teachFirst = profile?.teaching_strategy === "teach_first"
+ ? i18n.language?.toLowerCase().startsWith("zh")
+ ? TEACH_FIRST_PROFILE_LABEL.zh
+ : TEACH_FIRST_PROFILE_LABEL.en
+ : "";
+ const teachingPreference = [profile?.preferences?.trim(), teachFirst]
+ .filter(Boolean)
+ .join(" · ");
const rows: [string, string][] = profile
? (
[
[t("Already knows"), profile.prior_knowledge],
[t("Wants to reach"), profile.target_level],
[t("Time available"), profile.time_budget],
- [t("How to teach it"), profile.preferences],
+ [t("How to teach it"), teachingPreference],
[t("Other"), profile.notes],
] as [string, string][]
).filter(([, value]) => value.trim())
diff --git a/web/components/space/learning/next-step-copy.ts b/web/components/space/learning/next-step-copy.ts
new file mode 100644
index 000000000..9faa2c9ff
--- /dev/null
+++ b/web/components/space/learning/next-step-copy.ts
@@ -0,0 +1,44 @@
+type LocalizedCopy = { zh: string; en: string };
+
+export const TEACH_FIRST_PROFILE_LABEL: LocalizedCopy = {
+ zh: "先讲解,再检查理解",
+ en: "Teach first, then check understanding",
+};
+
+export const NEXT_LABELS: Record<string, LocalizedCopy> = {
+ probe: {
+ zh: "先用一道探查题看看你是否已经掌握",
+ en: "Start with a probe and test out if you already know it",
+ },
+ teach: {
+ zh: "先讲解这个知识点,再检查你是否理解",
+ en: "Learn this knowledge point before checking understanding",
+ },
+ practice: {
+ zh: "继续练习,直到稳定越过掌握门槛",
+ en: "Practice until you reliably clear the mastery gate",
+ },
+ assess: {
+ zh: "用自己的话讲清楚这个概念",
+ en: "Explain this clearly in your own words",
+ },
+ review: { zh: "复习这个记忆信标", en: "Revisit this memory beacon" },
+ answer_pending: {
+ zh: "完成导师正在等待的回答",
+ en: "Complete the answer your tutor is waiting for",
+ },
+ complete: {
+ zh: "整片疆域已经点亮",
+ en: "The whole territory is illuminated",
+ },
+};
+
+export const NEXT_CTA_LABELS: Record<string, LocalizedCopy> = {
+ teach: { zh: "开始学习这个知识点", en: "Learn this knowledge point" },
+ review: { zh: "开始本次复习", en: "Start this review" },
+ answer_pending: {
+ zh: "回到原会话作答",
+ en: "Answer in the original session",
+ },
+ complete: { zh: "继续自由探索", en: "Keep exploring" },
+};
diff --git a/web/lib/learning-api.ts b/web/lib/learning-api.ts
index ecb5b1ad9..354b7d353 100644
--- a/web/lib/learning-api.ts
+++ b/web/lib/learning-api.ts
@@ -553,6 +553,7 @@ export interface LearnerProfile {
target_level: string;
time_budget: string;
preferences: string;
+ teaching_strategy?: "probe_first" | "teach_first";
notes: string;
updated_at: number;
}
diff --git a/web/tests/mastery-teach-copy.spec.tsx b/web/tests/mastery-teach-copy.spec.tsx
new file mode 100644
index 000000000..6e882b313
--- /dev/null
+++ b/web/tests/mastery-teach-copy.spec.tsx
@@ -0,0 +1,79 @@
+import { render, screen } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+
+import { LearnerProfileCard } from "@/components/space/learning/LearnerProfileCard";
+import { ModeSwitch } from "@/components/space/learning/ModeSwitch";
+import {
+ NEXT_CTA_LABELS,
+ NEXT_LABELS,
+ TEACH_FIRST_PROFILE_LABEL,
+} from "@/components/space/learning/next-step-copy";
+import type { LearnerProfile } from "@/lib/learning-api";
+
+const locale = vi.hoisted(() => ({ language: "zh-CN" }));
+vi.mock("react-i18next", () => ({
+ useTranslation: () => ({
+ t: (value: string) => value,
+ i18n: { language: locale.language },
+ }),
+}));
+
+afterEach(() => {
+ locale.language = "zh-CN";
+});
+
+const emptyProfile: LearnerProfile = {
+ prior_knowledge: "",
+ target_level: "",
+ time_budget: "",
+ preferences: "",
+ notes: "",
+ updated_at: 1,
+};
+
+it("gives the teach action explicit Chinese and English next steps", () => {
+ expect(NEXT_LABELS.teach.zh).toContain("先讲解");
+ expect(NEXT_LABELS.teach.en).toContain("Learn this knowledge point");
+ expect(NEXT_CTA_LABELS.teach.zh).toContain("开始学习");
+ expect(NEXT_CTA_LABELS.teach.en).toContain("Learn this knowledge point");
+});
+
+it("shows a profile whose only preference is teach first", () => {
+ render(
+ <LearnerProfileCard
+ profile={{ ...emptyProfile, teaching_strategy: "teach_first" }}
+ />,
+ );
+
+ expect(screen.getByText(TEACH_FIRST_PROFILE_LABEL.zh)).toBeInTheDocument();
+ expect(screen.queryByText(/has not asked about you yet/)).not.toBeInTheDocument();
+});
+
+it("shows the teaching sequence alongside a free text preference", () => {
+ locale.language = "en";
+ render(
+ <LearnerProfileCard
+ profile={{
+ ...emptyProfile,
+ preferences: "Use diagrams",
+ teaching_strategy: "teach_first",
+ }}
+ />,
+ );
+
+ expect(
+ screen.getByText(`Use diagrams · ${TEACH_FIRST_PROFILE_LABEL.en}`),
+ ).toBeInTheDocument();
+});
+
+it("explains why a mode cannot change during a live turn", () => {
+ render(<ModeSwitch mode="study" onSelect={vi.fn()} disabled />);
+
+ for (const button of screen.getAllByRole("button")) {
+ expect(button).toBeDisabled();
+ expect(button).not.toHaveAttribute("title");
+ expect(
+ document.getElementById(button.getAttribute("aria-describedby")!),
+ ).toHaveTextContent("Wait for the tutor to finish before changing mode");
+ }
+});