Cursor代码，Next.js项目

这是一篇关于Cursor代码Next.js项目的思维导图，主要内容包括：用白话的方式，让你看懂代码、理解代码、懂怎么改代码。有解释，有案例，有方法。（当然没有包含全部，因为代码无穷无尽的组合，学不完）但是基本能接触到的小白级都有了。

Cursor代码 Next.js项目

• • app 决定页面与流程， 且90%的事都在这里处理。 真正的页面，只存在于这里。 用户可见流程，全部由app/目标决定。
    • • • api 后端接口（AI、分析、识别） 整个组件是“幕后工作人员“，它不是页面。 api自己不会跳转页面，永远只是“返回数据“。 页面怎么走，是captrue/page.tsx决定的。
          • • analyze 分析层 /api/analyze 并发/顺序分析 做：真正做错题分析。
              • route.ts
            • detect-questions 做：判断哪里是题。
              • route.ts
            • extract 识别层/api/extract 自动识别、手动框选（canvas） 做：从图片中识别题目。
              • route.ts
      • • capture 路由。作用是：拍照、录入错题的页面。上传图片、自动识别/手动框选、点击“完成并生成分析“。 这个是改得最多，也最熟悉的页面。 拍照/录入页。目前这个是整个产品的“发动机“ 真实在做的是：上传图片----识别题目----生成分析----决定跳转
          • * page.tsx
      • • detail/[id] 错题解析详情页。 [id]是：某一道错题的唯一标识，页面职责只有一件事：把一条错题讲清楚. 不负责：拍照、识别、分析。只负责：展示、延展（同类题）、行为出口（再拍一题/返回首页） 作用：展示解析结果，同类题，“再拍一题“，“返回首页“。
          • * page.tsx
      • 次要页面
        • • frame 应用/框架。 流程中间页/辅助结构页。
            • * page.tsx
        • • pricing
            • * page.tsx
        • • review 应用/评论。 复习相关页面。 可以用于：标记已复习，复盘错题，不参与当前的“录入-解析“闭环。
            • * page.tsx
        • • trial-end
            • * page.tsx
        • • weekly 每周。周期性总结页（如：每周复习）
            • * page.tsx
        • # globals.css
        • * layout.tsx
          • 全站“外壳“ 比如：顶部结构、全局样式、所有页面的公共包裹。
      • * page.tsx
        • 首页。 作用：展示待复习数、错题数量，入口按钮 提供唯一主入口：“录入错题“。 它不是流程复杂点，而是“起点“。
  • components 组件。 可复用的UI零件。 Button按钮 Card卡片 Modal首都 Textarea文件区域 一般首页里用它们 整个组件是“UI零件箱“，不是流程。
    • • UI
        • badge.tsx
        • button.tsx
        • card.tsx
        • sonner.tsx
        • textares.tsx
      • MobileCaptureEntry.tsx
      • theme-provider.tsx
  • lib 工具函数/公共逻辑 时间处理 数据格式化 公共helper （知道它存在即可） lib是：给页面用的工具、不是页面本身、不决定流程。 整个组件是“UI零件箱“，不是流程。
    • • aiModel.ts
      • storage.ts
      • types.ts
      • utils.ts
  • 工程配置层（几乎不用碰）
    • public 公开 静态资源：图片/icon图标。
    • styles globals.css样式。 全局样式
    • { } components.json
    • JS next.config.mjs （Next.js的底层配置）
    • { } package.json （项目“依赖说明书“。出问题时才看，日常不要改）
    • ! pnpm-lock.yaml
    • JS postcss.config.mjs
    • README.md
    • TS tsconfig.json （TypeScript配置，不碰）
• 看代码
  • 不看具体代码，先看骨架
    • • 以后所有的新增 / 修改， 都只能发生在 ③ / ④ / ⑤ 这三块里。
        • “use client"=告诉Next.js这个页面要在“浏览器里跑
          • 因为这里用到了：相机、点击、useState使用状态 、localStorage本地存储， 这些浏览器才有，服务器没有。
            • 不要改它，不要删，永远放在第一行。
        • 第 ① 段：import区：只能看，不要乱动=把“外部工具”搬进来 import { useState, useEffect, useRef } from "react" import { useRouter } from "next/navigation" import { Button } from "@/components/ui/button"
          • 以后新增功能，唯一可能改 import 的情况是： 用了一个新组件（比如 Dialog） 用了一个新 hook（比如 useMemo）
            • 重要规则（再强调一遍）： import 只能在文件最上面 import 不能写在函数里 Cursor 一般会自动帮你补
        • 第 ② 段：type 定义区（“说明书”，不是逻辑） type ExtractItem = { id: string question_text: string student_answer: string }
          • “数据长什么样”的说明书，不是执行代码，不会真的运行。
            • 什么时候要动它？ API 返回字段变了 你要多用一个字段。 否则： ❌ 不碰 ❌ 不删 ❌ 不随便加
        • 第 ③ 段：状态 & 变量区（非常关键） export default function CapturePage() { const router = useRouter() const [imageUrl, setImageUrl] = useState("") const [autoMode, setAutoMode] = useState(true) const [candidates, setCandidates] = useState([]) 是 记状态？→ 第③段
          • 这一段用于定义“这个页面记得住的东西“
          • useState 你这样理解就够了 const [autoMode, setAutoMode] = useState(true)
          • autoMode = 当前状态
          • setAutoMode = 改它的按钮
          • true = 初始值
          • 规则（死规则）： useState 只能写在函数最外层 不能写在 if / for / 函数里面
            • 你以后什么时候来这里加代码？ 👉 当你需要 “页面记住一个新东西” 比如： 是否 loading 是否选中 当前步骤
        • 第 ④ 段：业务函数区（你最容易放错地方的） function handleImageUpload() { ... } async function analyzeSelected() { ... } async function analyzeManualBoxes() { ... } 是 做事情？→ 第④段
          • 这一段的本质是： “点按钮之后发生什么”
            • 规则： 所有「点击 / 提交 / 请求接口」 👉 都必须写在这里 ❌ 不准写 JSX ❌ 不准写 <div>
              • 你以后加功能，90% 是加在这里 例如你说过的： 点击后直接跳转 detail 点击“再拍一题”清空状态 加确认弹窗 👉 都是 加函数 or 改函数
        • 第 ⑤ 段：return（真正画页面的地方） return ( <main> <Button onClick={handleImageUpload}> 点击拍照 </Button> </main> ) 是 改样子？→ 第⑤段
          • 这一段只干一件事： 把页面“画出来”
            • 这里允许的只有： <div> <Button> {变量} {函数}
            • 这里绝对不允许有： const function useState import
              • ❌ 错误 2：在 return 里写逻辑 return ( const x = 1 ❌ ) 永远不允许。
              • ❌ 错误 3：在函数里 import function xxx() { import xxx ❌ } 绝对不允许。
          • {} 在这里的意义（重点）
            • <Button onClick={analyzeSelected}> 意思是： 点击时，调用 analyzeSelected 这个函数
            • {candidates.length} 意思是： 显示这个变量的值
• 改代码
  • 结构类（放哪）
    • react/Next的代码，本质是“三段式结构“
      • A：拿东西？→ import 区（最上面）
        • 只能在最上面，典型长这样： import { useState } from "react" import { Button } from "@/components/ui/button"
        • 规则： 不能放在函数里 不能放在return下面 只能在文件最上面
        • 只要是“从别的文件拿东西“，一定是import
      • B：算逻辑？→逻辑区（函数时，return之前）
        • 一般长这样： export default function CapturePage() { const [count, setCount] = useState(0) function handleClick() { setCount(count + 1) } return ( ... ) }
          • 这里可以放什么？
            • const XXX= ……
            • function XXX ( ) { }
            • useState
            • useEffect
            • 各种if/for/map的“准备逻辑“
          • 不能放什么？
            • HTML
            • <div>
            • 页面结构
      • C：画页面？→ UI区 （return里面）
        • 一般长这样： return ( <div> <Button onClick={handleClick}>点我</Button> </div> )
        • 规则： 只允许JSX（长得像HTML的东西） 不写逻辑定义 不写import
  • 语法类（符号）
    • { } 是什么？=“这里我要写JS，不是HTML
      • 举例：<Button>{count}</Button> 意思是：Button里面显示“变量count的值
        • <Button onClick={handleClick}> 等价于： <Button onClick={() => handleClick()}>
      • 规则： JSX里 凡是变量/函数/表达式 必须包{ }
    • [ ] 是什么？
      • =数组
        • const list = [1, 2, 3]
      • =useState的解构（非常重要）
        • const [value, setValue] = useState(0)
      • 意思是：value=当前值 setValue=修改它的方法 这是“固定写法，不是你发明的。
    • ( ) 是什么？
      • =调用函数
        • handleClick()
      • =包JSX（return必须）
        • return ( <div>...</div> )
      • =剪头函数
        • () => {}
    • </div> 是什么？
      • =HTML必须“有头有尾“
        • <div> <p>内容</p> </div>
      • <div> 一定要有</div> 少一个就会报错 顺序不能乱
        • 大部分报红，都是因为：少关一个标签或多关一个标签
  • 角色类（关键词）
    • import=从别的文件”拿东西“
      • import { Button } from "@/components/ui/button" 意思是：我要用Button，不是我pgnr，是别人写好的。
    • export default
      • export default function CapturePage() {} 意思是：这个文件对外“只提供一个东西→ 就是这个页面
    • function
      • function handleClick() {} 意思是：一段可以被反复执行的逻辑
    • return=“我最终交付什么“
      • 在函数里： return value
      • 在React页面里： return ( <div>页面</div> )
    • type=告诉TS：这个东西应该长什么样
      • 不是代码逻辑，是“说明书“ type Question = { id: string text: string }
  • JS、JSX、HTML
    • JS=JavaScript 本质：编程语言 核心作用：实现页面动态交互、逻辑处理 所属范畴：前端/后端能用
      • 是一门跨平台、面向对象的脚本语言，核心用于为网页添加动态交互能力（如按钮点击、表单验证、页面内容实时更新等）。
      • 定位：Web前端三大核心技术之一（HTML+CSS+JS），也是Node.js等后端环境的核心语言，属于“编程语言“范畴。
      • 简单示例： // 点击按钮弹出提示 document.getElementById("btn").onclick = function() { alert("你点击了按钮"); };
    • JSX：JaveScript XML 本质：JS扩展语法 核心作用：在JS中直观描述React UI结构 所属范畴：React框架专属
      • 可理解为“JavaScript扩展语法“，是React框架（前端主流框架）推出的语法糖，允许在JavaScript代码中直接编写类HTML的标记 核心作用：解决传统JS中拼接HTML字符串的繁琐问题，让前端开发者能以更直观的方式描述UI结构，且JSX最终会被编译成普通的JaveScript代码执行。
      • 定位：React的核心语法（非标准JS/HTML），属于“JS 的扩展语法“，本质是JS的一部分。
      • 简单示例： // React中用JSX描述UI const App = () => { return ( <div> <h1>Hello, JSX!</h1> <button onClick={() => alert("点击成功")}>点击我</button> </div> ); };
        • 编译后等价的纯JS代码（React.createElement 语法）： const App = () => { return React.createElement( "div", null, React.createElement("h1", null, "Hello, JSX!"), React.createElement( "button", { onClick: () => alert("点击成功") }, "点击我" ) ); };
    • HTML：HyperText Markup Language 本质：标记语言 核心作用：定义网页结构和静态内容 所属范畴：页面骨架
      • 超文本标记语言，是用于定义见面结构和内容的标记语言（非编程语言）
      • 定位：Web页面的“骨架“，负责描述页面有什么（如：标题、段落、图片、链接、表单等），通过标签（如：<div>、<p>、 <img>组织内容。
      • 简单示例： <!DOCTYPE html> <html> <body> <h1>我的第一个标题</h1> <p>我的第一个段落</p> <button id="btn">点击我</button> </body> </html>
    • 概要
      • JSX不是HTML：JSX语法上像HTML，但支持JS的特性（如大括号{ } 嵌入变量/表达式、事件绑定用 onClick 而非 onclick等），而HTML是纯静态标记。
      • JSX必须编译：浏览器无法直接识别JSX，需通过Babel等工具编译为普通JS后才能运行。
      • 三者协作（React场景）：HTML定义页面基础结构 → JS（通过JSX）控制UI渲染和交互逻辑 → 最终呈现完整的动态页面。
• 理解项目里的英文语义直觉
  • biji-cuoti-MicroSaas-AI
    • 文件夹名字
  • .next
    • 编译后的临时文件、缓存
      • 可以理解为“厨房垃圾桶“：不读、不改、不投喂给Cursor
    • 作用：编译后的临时文件、缓存
  • app=application应用
    • 所有“页面+路由+用户能看到的东西“。
    • 最重要的目录，没有之一。所有产品逻辑，90%都在这里。
    • api=接口
      • 作用：前端页面用来“请求数据“的后端逻辑。
        • 用户看不到，只能被调用。
        • analyze=分析
          • route.ts=意思是：/api/analyze这个接口的代码。这个接口的路由文件。 =这是一个api，不是页面。不会直接展示UI。
            • toute=路由
            • .ts：TypeScript=文件
        • detect-questions=检测问题=检测图片里“哪里是题目”
          • detect：检测
          • questions：题目问题
        • extract=提取物=从图片中“提取题目文字”
          • extract=提取
      • app/api=后厨=做事，但不露面。
    • capture=捕捉/拍摄
      • 语义就是：拍照、截图、录入 意思就是：用户拍照、框选、识别、分析的地方
        • page.tsx
          • page：页面
          • .tsx
            • .ts:TypeScript=文件
            • x=里面可以写UI（JSX）
      • 所有流程控制 所有分析成功/失败后的跳转 都应该在这里
    • detail=应用/详情
      • detail=详情
        • [id]
          • [ ]=动态路由（Next.js约定）
          • id=某一道错题的唯一编号
        • page.tsx
          • 错题详情页面本体
            • 展示：题目、解析、同类题、复习状态、“再拍一题“按钮
    • frame=框架/容器。常用于：过渡页、引导页、实验页
    • pricing=定价。付费说明、价格页
    • review=评论/复习。可能是错晚点再复习列表页
    • trial-end=试验结束。trial:试用。end：结束。试用结束提示页。
    • weekly=每周。周报/周复习.
    • #globals.css
      • global:全局
      • css：样式
      • 整个网站通用样式
    • layout.tsx=布局
      • 包裹所有页面，放header/footer/全局结构 类比：房子的骨架
  • component=组件/零件
    • 不直接是页面，被page.tsx引用
    • UI=用户界面
      • UI组件库（按钮、卡片等），通常来自：shadcn/ui
    • MobileCaptureEntry.tsx
      • Mobile:手机
      • Capture:拍照
      • Entry：入口
      • 整个含义：手机端拍照入口组件
    • theme-provider.tsx
      • theme：主题（深色/浅色）
      • provider：提供者
      • 负责全局主题状态
  • lib=工具箱=library
    • aiModel.ts
      • AI模型相关封装
    • storage.ts
      • 本地存储=localStorage
    • types.ts
      • 类型定义（TypeScript用）
    • utils.ts
      • 工具函数（通用小功能）
    • lib=给代码用的，不给用户看
  • node-modules=所有第三方依赖
  • public=民众=图片、静态资源
  • styles风格=样式文件夹（如果没用Tailwind)
  • components.json=shadcn/ui的配置文件
  • next.config.mjs=Next.js配置
  • tsconfig.json=TypeScript配置
  • package.json=项目“说明书+依赖清单“
  • pnpm-lock.yaml=依赖锁定文件
  • .env.local=环境变量，API KEY都在这
• 核心目录地图
  • app/------页面与流程核心
    • page.tsx------首页（/）
      • 职责：展示错题概览、提供入口按钮 禁止：不进行识别、不进行分析
    • capture/page.tsx------拍照/录入页（/capture)
      • 职责： 图片输入（拍照/上传） 题目识别（自动/手动） 调用分析接口 决定分析成功/失败后的跳转行为
      • 这是唯一的：流程控制页面。
    • detail/[id]/page.tsx------错题详情页(detail/[id])
      • 职责： 展示单条错题的解析结果 提供后续操作入口（如：再拍一题） 禁止： 不进行图片识别 不调用分析接口
    • api------后端接口（不控制页面跳转）
      • /api/extract ← 从图片中识别题目
      • /api/detect-questions ← 辅助识别题区域
      • /api/analyze ← 对题目进行错题分析
      • API 只返回数据 API 不负责页面跳转 页面跳转只能在 app/capture/page.tsx 中发生
  • components/ui------UI组件（默认不修改）
  • lib------工具与存储（默认不修改）
  • app/layout.tsx（默认不修改）
  • globals.css（默认不修改）
  • next.config.mjs（默认不修改）
  • tsconfig.json（默认不修改）
  • 其余目录------当前不参与主流程