How to Build a Flashcard Study App with Next.js and MongoDB

npx create-next-app@latest flash-cards --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm

cd flash-cards
npm install mongoose

services:
  mongodb:
    image: mongo:7
    container_name: flashstudy-mongodb
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:

docker compose up -d

MONGODB_URI=mongodb://localhost:27017/flashcards

MONGODB_URI=mongodb+srv://username:[email protected]/flashcards?retryWrites=true&w=majority

flash-cards/
├── src/
│   ├── app/              # 页面和 API 路由
│   │   ├── api/          # 后端 API 端点
│   │   ├── subjects/     # 主题列表和详情页面
│   │   ├── study/        # 学习模式页面
│   │   └── progress/     # 进度跟踪页面
│   ├── components/       # 可复用的 UI 组件
│   └── lib/              # 工具和数据库代码
│       ├── db.ts         # MongoDB 连接
│       └── models/       # Mongoose 模式
├── .env.local            # 环境变量（你创建此文件）
├── docker-compose.yml    # MongoDB 的 Docker 配置
└── package.json

import mongoose from "mongoose";

const MONGODB_URI = process.env.MONGODB_URI || "mongodb://localhost:27017/flashcards";

interface MongooseCache {
  conn: typeof mongoose | null;
  promise: Promise<typeof mongoose> | null;
}

declare global {
  var mongoose: MongooseCache | undefined;
}

let cached: MongooseCache = global.mongoose || { conn: null, promise: null };

if (!global.mongoose) {
  global.mongoose = cached;
}

async function dbConnect(): Promise<typeof mongoose> {
  if (cached.conn) return cached.conn;

  if (!cached.promise) {
    cached.promise = mongoose.connect(MONGODB_URI, {
      bufferCommands: false,
    });
  }

  cached.conn = await cached.promise;
  return cached.conn;
}

export default dbConnect;

import mongoose, { Schema, model, models } from "mongoose";

export interface ISubject {
  _id: string;
  name: string;
  description?: string;
  color: string;
  createdAt: Date;
  updatedAt: Date;
}

const SubjectSchema = new Schema(
  {
    name: { type: String, required: true },
    description: { type: String },
    color: { type: String, default: "#6366f1" },
  },
  { timestamps: true }
);

export default models.Subject || model<ISubject>("Subject", SubjectSchema);

import mongoose, { Schema, model, models } from "mongoose";

export interface IFlashcard {
  _id: string;
  subjectId: string;
  front: string;
  back: string;
  createdAt: Date;
  updatedAt: Date;
}

const FlashcardSchema = new Schema(
  {
    subjectId: { type: Schema.Types.ObjectId, ref: "Subject", required: true },
    front: { type: String, required: true },
    back: { type: String, required: true },
  },
  { timestamps: true }
);

export default models.Flashcard || model<IFlashcard>("Flashcard", FlashcardSchema);

import mongoose, { Schema, model, models } from "mongoose";

export interface IProgress {
  _id: string;
  flashcardId: string;
  subjectId: string;
  correct: boolean;
  reviewedAt: Date;
}

const ProgressSchema = new Schema(
  {
    flashcardId: { type: Schema.Types.ObjectId, ref: "Flashcard", required: true },
    subjectId: { type: Schema.Types.ObjectId, ref: "Subject", required: true },
    correct: { type: Boolean, required: true },
    reviewedAt: { type: Date, default: Date.now },
  },
  { timestamps: true }
);

export default models.Progress || model<IProgress>("Progress", ProgressSchema);

import { NextResponse } from "next/server";
import dbConnect from "@/lib/db";
import Subject from "@/lib/models/Subject";

export async function GET() {
  try {
    await dbConnect();
    const subjects = await Subject.find({}).sort({ createdAt: -1 });
    return NextResponse.json(subjects);
  } catch (error) {
    console.error("获取主题时出错:", error);
    return NextResponse.json(
      { error: "无法获取主题" },
      { status: 500 }
    );
  }
}

export async function POST(request: Request) {
  try {
    await dbConnect();
    const body = await request.json();
    const { name, description, color } = body;

    if (!name) {
      return NextResponse.json(
        { error: "主题名称是必填项" },
        { status: 400 }
      );
    }

    const subject = await Subject.create({
      name,
      description: description || "",
      color: color || "#6366f1",
    });

    return NextResponse.json(subject);
  } catch (error) {
    console.error("创建主题时出错:", error);
    return NextResponse.json(
      { error: "无法创建主题" },
      { status: 500 }
    );
  }
}

import { NextResponse } from "next/server";
import dbConnect from "@/lib/db";
import Flashcard from "@/lib/models/Flashcard";

export async function GET(request: Request) {
  try {
    await dbConnect();
    const { searchParams } = new URL(request.url);
    const subjectId = searchParams.get("subjectId");

    const query = subjectId ? { subjectId } : {};
    const flashcards = await Flashcard.find(query)
      .populate("subjectId", "name color")
      .sort({ createdAt: -1 });

    return NextResponse.json(flashcards);
  } catch (error) {
    console.error("Error fetching flashcards:", error);
    return NextResponse.json(
      { error: "Failed to fetch flashcards" },
      { status: 500 }
    );
  }
}

export async function POST(request: Request) {
  try {
    await dbConnect();
    const body = await request.json();
    const { subjectId, front, back } = body;

    if (!subjectId || !front || !back) {
      return NextResponse.json(
        { error: "Subject, front, and back are required" },
        { status: 400 }
      );
    }

    const flashcard = await Flashcard.create({
      subjectId,
      front,
      back,
    });

    const populated = await Flashcard.findById(flashcard._id).populate(
      "subjectId",
      "name color"
    );

    return NextResponse.json(populated);
  } catch (error) {
    console.error("Error creating flashcard:", error);
    return NextResponse.json(
      { error: "Failed to create flashcard" },
      { status: 500 }
    );
  }
}

import { NextResponse } from "next/server";
import dbConnect from "@/lib/db";
import Subject from "@/lib/models/Subject";
import Flashcard from "@/lib/models/Flashcard";
import Progress from "@/lib/models/Progress";

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  try {
    await dbConnect();
    const { id } = await params;
    const subject = await Subject.findById(id);

    if (!subject) {
      return NextResponse.json({ error: "Subject not found" }, { status: 404 });
    }

    return NextResponse.json(subject);
  } catch (error) {
    console.error("Error fetching subject:", error);
    return NextResponse.json(
      { error: "Failed to fetch subject" },
      { status: 500 }
    );
  }
}

export async function PUT(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  try {
    await dbConnect();
    const { id } = await params;
    const body = await request.json();
    const { name, description, color } = body;

    const subject = await Subject.findByIdAndUpdate(
      id,
      { name, description, color },
      { new: true }
    );

    if (!subject) {
      return NextResponse.json({ error: "Subject not found" }, { status: 404 });
    }

    return NextResponse.json(subject);
  } catch (error) {
    console.error("Error updating subject:", error);
    return NextResponse.json(
      { error: "Failed to update subject" },
      { status: 500 }
    );
  }
}

export async function DELETE(
  _request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  try {
    await dbConnect();
    const { id } = await params;

    await Flashcard.deleteMany({ subjectId: id });
    await Progress.deleteMany({ subjectId: id });
    const subject = await Subject.findByIdAndDelete(id);

    if (!subject) {
      return NextResponse.json({ error: "Subject not found" }, { status: 404 });
    }

    return NextResponse.json({ message: "Subject deleted" });
  } catch (error) {
    console.error("Error deleting subject:", error);
    return NextResponse.json(
      { error: "Failed to delete subject" },
      { status: 500 }
    );
  }
}

- params : 在 Next.js 15+ 中，params 是一个 Promise。我们通过 await 获取 { id: "abc123" } 。

- findByIdAndUpdate(id, updates, { new: true }) : 更新文档并返回更新后的版本。{ new: true } 表示 "返回更新后的文档，而非原始文档"。

- DELETE : 删除主题时，我们也会删除其关联的卡片和进度记录。否则会产生孤立数据。

#### 按 ID 获取、更新、删除卡片

现在，我们为单个卡片创建动态路由。该路由将允许我们获取、更新或删除卡片。

在 src/app/api/flashcards/[id] 目录中，创建名为 route.ts 的文件并添加以下代码：

import { NextResponse } from "next/server";
import dbConnect from "@/lib/db";
import Progress from "@/lib/models/Progress";

export async function GET(request: Request) {
  try {
    await dbConnect();
    const { searchParams } = new URL(request.url);
    const subjectId = searchParams.get("subjectId");

    const query = subjectId ? { subjectId } : {};
    const progress = await Progress.find(query).sort({ reviewedAt: -1 });

    const stats = await Progress.aggregate([
      { $match: query },
      {
        $group: {
          _id: "$subjectId",
          total: { $sum: 1 },
          correct: { $sum: { $cond: ["$correct", 1, 0] } },
        },
      },
    ]);

    return NextResponse.json({ progress, stats });
  } catch (error) {
    console.error("Error fetching progress:", error);
    return NextResponse.json(
      { error: "Failed to fetch progress" },
      { status: 500 }
    );
  }
}

export async function POST(request: Request) {
  try {
    await dbConnect();
    const body = await request.json();
    const { flashcardId, subjectId, correct } = body;

    if (!flashcardId || !subjectId || typeof correct !== "boolean") {
      return NextResponse.json(
        { error: "flashcardId, subjectId, and correct are required" },
        { status: 400 }
      );
    }

    const progress = await Progress.create({
      flashcardId,
      subjectId,
      correct,
    });

    return NextResponse.json(progress);
  } catch (error) {
    console.error("Error recording progress:", error);
    return NextResponse.json(
      { error: "Failed to record progress" },
      { status: 500 }
    );
  }
}

- 聚合：MongoDB 的聚合管道。我们按 subjectId 进行分组，统计总评论数和正确答案数。$cond: ["$correct", 1, 0] 表示“如果 correct 为 true，则加 1，否则加 0”。

- 统计：返回类似 [{ _id: "subjectId123", total: 20, correct: 16 }] 的数据。前端使用这些数据来显示每个主题的“80%准确率”。

## UI 实现

现在我们将构建用户看到的页面。我们将使用 React 钩子（useState、useEffect）来管理数据和调用 API。

### 主题页面

加载时，我们从 API 获取主题。我们显示一个表单来创建新主题。每个主题以卡片形式展示，并链接到其详情页面。

关键逻辑：

- useEffect 在组件挂载时运行一次，并调用 fetch("/api/subjects")。

- 表单的 onSubmit 调用 fetch("/api/subjects", { method: "POST", ... })。

- 创建成功后，我们清空表单并调用 fetchSubjects() 以刷新列表。

### 主题详情页（创建和编辑闪卡）

该页面显示一个主题及其闪卡。用户可以添加新卡片或编辑/删除现有卡片。URL 是 /subjects/[id]，因此我们使用 useParams() 获取主题 ID。

- useParams() 从 URL 中获取 id。

- 在组件挂载时获取主题及其闪卡。

- “添加闪卡”显示一个表单。提交时，我们向 /api/flashcards 发送 POST 请求，包含 subjectId、front 和 back。

- 每张卡片都有“编辑”和“删除”按钮。编辑会切换到内联表单，而删除会调用 DELETE /api/flashcards/[id]。

### 学习页面 – 翻转卡片

学习页面有三个主要状态：

- 主题选择：用户选择要学习的主题。

- 准备开始：显示“开始学习”按钮及卡片数量。

- 学习中：一次显示一张卡片。用户点击翻转卡片，然后标记为正确或错误。我们进入下一张卡片并记录进度。

#### 翻转动画

我们使用 CSS 3D 变换来创建翻转动画。闪卡有两个面：一面是问题，另一面是答案。当 flipped 为 true 时，我们旋转卡片容器 180 度。我们还使用 backface-visibility: hidden 以确保在旋转过程中仅显示合适的面。

要添加翻转动画的样式，请打开 src/app/globals.css 并添加以下代码：

.preserve-3d {
  transform-style: preserve-3d;
}

.backface-hidden {
  backface-visibility: hidden;
}

/* 为卡片背景创建横线纸张效果 */
.lined-paper {
  background-image: repeating-linear-gradient(
    transparent,
    transparent 27px,
    #e5e7eb 27px,
    #e5e7eb 28px
  );
}

<div
  className={`preserve-3d transition-transform duration-500 ${
    flipped ? "[transform:rotateY(180deg)]" : ""
  }`}
>
  {/* 正面 - 问题 */}
  <div className="backface-hidden [transform:rotateY(0deg)]">
    {currentCard.front}
  </div>
  {/* 背面 - 答案 */}
  <div className="backface-hidden [transform:rotateY(180deg)]">
    {currentCard.back}
  </div>
</div>

const handleKnow = () => {
  recordProgress(true);
  setFlipped(false);
  if (currentIndex < flashcards.length - 1) {
    setCurrentIndex((i) => i + 1);
  } else {
    setStudyStarted(false);
    setCurrentIndex(0);
  }
};

const getSubjectStats = (subjectId) => {
  const stat = stats.find((s) => s._id === subjectId);
  return stat
    ? {
        total: stat.total,
        correct: stat.correct,
        pct: Math.round((stat.correct / stat.total) * 100),
      }
    : null;
};

// src/components/PaperclipIcon.tsx
export default function PaperclipIcon({ className }: { className?: string }) {
  return (
    <svg className={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
      <path d="M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48" />
    </svg>
  );
}