docs: move News section to BEFORE Who This Is For / 适合谁

Move News section from after Who This Is For to before it for all language READMEs to match the correct structure: 1. Why Easy-Vibe / 为什么需要 Easy-Vibe 2. 🔥 News 3. Who This Is For / 适合谁 4. Your Learning Paths / 你的学习路径 Files updated: - README.md - docs-readme/zh-CN/README.md - docs-readme/zh-TW/README.md - docs-readme/en-US/README.md - docs-readme/ja-JP/README.md - docs-readme/es-ES/README.md - docs-readme/fr-FR/README.md - docs-readme/ko-KR/README.md - docs-readme/ar-SA/README.md - docs-readme/vi-VN/README.md - docs-readme/de-DE/README.md
2026-03-29 19:37:03 +08:00
parent 02ce40433a
commit 90842adccf
21 changed files with 2242 additions and 116 deletions
@@ -1534,6 +1534,30 @@ Sitemap: ${siteUrl}/sitemap.xml
                {
                  text: '大作业 2：在线考试与管理系统',
                  link: '/zh-cn/stage-2/assignments/exam-management-express/'
+                },
+                {
+                  text: '扩展作业：现代网页落地页',
+                  link: '/zh-cn/stage-2/assignments/modern-landing-page/'
+                },
+                {
+                  text: '扩展作业：自制 Dify 智能体平台',
+                  link: '/zh-cn/stage-2/assignments/custom-dify-agent-platform/'
+                },
+                {
+                  text: '扩展作业：智能旅游规划 Agent 平台',
+                  link: '/zh-cn/stage-2/assignments/travel-planning-agent-platform/'
+                },
+                {
+                  text: '扩展作业：电影推荐网（Spring Boot）',
+                  link: '/zh-cn/stage-2/assignments/movie-recommendation-springboot/'
+                },
+                {
+                  text: '扩展作业：简单买菜微服务网站',
+                  link: '/zh-cn/stage-2/assignments/simple-grocery-microservices/'
+                },
+                {
+                  text: '扩展作业：交通大数据可视化分析（Go）',
+                  link: '/zh-cn/stage-2/assignments/traffic-data-visualization-go/'
                }
              ]
            }
@@ -21,6 +21,32 @@
  </ClientOnly>
 </div>

+## 先看全景：你最终要做出来的不是“一个页面”，而是一条完整业务链路
+
+很多人第一次做全栈项目，最容易犯的错不是不会写代码，而是只盯着某一个页面，结果首页挺好看，后端没接上；生成按钮能点，历史记录没保存；支付能跳转，但数据库根本没更新。
+
+这个项目真正要交付的，是下面这条完整链路：
+
+```mermaid
+flowchart TD
+  visitor["访客"] --> home["首页 / 落地页"]
+  home --> auth["注册 / 登录"]
+  auth --> dashboard["用户工作台"]
+  dashboard --> generate["生成接口 /api/generate"]
+  generate --> llm["LLM 文案生成"]
+  generate --> generations["generations 表"]
+  dashboard --> history["历史记录读取"]
+  dashboard --> billing["套餐页 /billing"]
+  billing --> stripe["Stripe Checkout"]
+  stripe --> webhook["支付回调 Webhook"]
+  webhook --> subscriptions["subscriptions 表"]
+  subscriptions --> profile["profiles.plan 更新"]
+  profile --> admin["管理后台 /admin"]
+  admin --> report["查看用户 / 生成记录 / 支付状态"]
+```
+
+只要上面这张图能跑通，你做的就不是课堂 Demo，而是一个真正像产品的最小 SaaS。
+
 ## 为什么选这个题目？

 因为它恰到好处——**涵盖了现代网站该有的所有要素，又不会复杂到失控**。
@@ -34,6 +60,18 @@

 难度适中：不会简单到只有一个表单，也不会复杂到做一周还找不着北。

+### 先锁定项目边界，别一上来就做“大而全”
+
+为了让你真的能按时做完，这个项目建议你先只做 **最小可用版本**：
+
+- 只做 **邮箱注册 / 登录**，先不要接第三方 OAuth
+- 支付只做 **免费版 + Pro 版** 两档，先不要做优惠券、年付月付切换
+- AI 生成功能只做 **单次文案生成**，先不要做批量任务队列
+- 管理后台先做 **查看**，暂时不要求复杂运营操作
+- 权限只区分 **user / admin** 两种角色
+
+你会发现，真正难的不是“还能不能继续加功能”，而是“能不能先把主流程稳定交付”。
+
 ## 1. 定主题：先搞清楚要做什么

 网站名称：**LaunchKit**
@@ -103,6 +141,22 @@ subscriptions (

 到这一步，整个网站的骨架已经清晰。

+### 推荐开发顺序
+
+不要按“想到什么做什么”，而要按依赖关系推进：
+
+```mermaid
+flowchart LR
+  A["首页 / 登录 / Dashboard 骨架"] --> B["Supabase Auth"]
+  B --> C["profiles / generations / subscriptions"]
+  C --> D["生成接口 + 历史记录"]
+  D --> E["Stripe 支付 + 套餐限制"]
+  E --> F["Admin 后台"]
+  F --> G["部署 / README / 演示视频"]
+```
+
+这个顺序的好处是：每一步都能看到阶段性成果，也更容易排查问题。
+
 <div style="margin: 32px 0;">
  <ClientOnly>
    <StepBar :active="1" :items="[
@@ -382,6 +436,20 @@ subscriptions (
 - Admin 后台截图
 - 60 秒左右演示视频

+## 验收标准
+
+如果你想判断这个作业到底算不算“完成”，不要只看页面有没有写完，而要看下面这几个维度是不是都达标：
+
+| 维度 | 最低达标 | 加分项 |
+|------|------|------|
+| 产品完整度 | 首页、登录、Dashboard、Billing、Admin 都能访问 | 首页文案和视觉风格明显像真实 SaaS |
+| 业务闭环 | 用户可以注册、登录、生成并查看历史 | 免费 / Pro 权限差异清晰可见 |
+| 数据正确性 | 生成结果和支付状态都会写入数据库 | 有明确的错误提示、空状态和 Loading |
+| 权限与安全 | 未登录不能访问受保护页面，普通用户不能进 Admin | 有基本的输入校验和服务端鉴权 |
+| 工程交付 | 项目可本地启动，也可部署到公网 | README 清楚，演示视频结构完整 |
+
+如果你现在还觉得任务太大，就记住一个标准：**优先保证“能跑通”，再去追求“做漂亮”。**
+
 ## 5. 最终成果

 按这篇指南做完，你拿到的不是"练习页"，而是一个**最小但完整的 SaaS 产品**：
@@ -413,5 +481,5 @@ subscriptions (
 </el-card>

 ::: tip 🚀 下一篇
-完成这个网站后，继续阅读 [大作业 2：现代前端组件库 + Trae 实战](../2.2-modern-frontend-trae/)，把界面质量再提升一层。
+完成这个网站后，继续阅读 [使用现代组件库更新你的界面](../../frontend/2.7-modern-component-library/)，把产品界面的完成度再提升一层。
 :::
@@ -1,7 +1,289 @@
 # 自制 Dify 智能体平台

-::: warning 🚧 建设中
+如果你已经会用 Dify，下一步最值得挑战的不是“再配一个工作流”，而是自己做一个“类 Dify 平台”。

-本文档正在编写中，内容可能会有较大变动。请关注更新。
+这个大作业会带你完成一个简化但完整的智能体平台：支持创建智能体、配置 Prompt、接知识库、发起对话、查看日志和调用统计。

+::: tip 🎯 这次做什么？
+打造一个 **最小可用的智能体平台（Mini Dify）**。平台至少包含：智能体管理、会话问答、知识库接入（可选第一版简化）、调用记录与基础权限控制。目标是让用户能“创建一个智能体并真实对话”。
+:::
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="0" :items="[
+      { title: '定能力边界', description: '先明确第一版做什么，不做什么' },
+      { title: '搭平台骨架', description: '完成前后端结构、鉴权与数据库设计' },
+      { title: '接智能体链路', description: '跑通创建智能体到对话返回的主流程' },
+      { title: '上线交付', description: '补日志、文档、部署与演示材料' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 为什么这个题目值得做？
+
+因为它几乎覆盖了 AI 应用工程化的核心能力：
+
+- 从“调用一个模型”升级到“管理多个智能体”
+- 从“单页 Demo”升级到“有后台、有数据、有权限的平台”
+- 从“能回答”升级到“可配置、可追踪、可维护”
+
+如果你未来想做 Agent 产品、企业知识助手或 AI SaaS，这个项目会是非常有含金量的一次训练。
+
+## 先看全景：平台核心模块
+
+```mermaid
+flowchart LR
+  user["平台用户"] --> web["Web 控制台"]
+  web --> auth["登录与鉴权"]
+  web --> agent["智能体管理"]
+  web --> chat["会话对话页"]
+  web --> logs["调用日志页"]
+  agent --> api["后端 API"]
+  chat --> api
+  logs --> api
+  api --> db["PostgreSQL"]
+  api --> llm["LLM Provider"]
+  api --> kb["知识库检索(可选第一版)"]
+  api --> trace["日志/成本统计"]
+```
+
+核心目标只有一个：用户能在后台创建智能体，然后在对话页选择该智能体并得到可追踪的回答。
+
+## 1. 定能力边界：第一版先收住
+
+### MVP 范围（建议）
+
+- 用户注册/登录
+- 智能体 CRUD（创建、编辑、启停、删除）
+- 每个智能体可配置：名称、系统提示词、模型、温度
+- 对话页可选择智能体进行聊天
+- 记录每轮会话和调用日志
+
+### 第一版暂不做
+
+- 多租户复杂权限
+- 复杂工作流编排器
+- 工具调用沙箱
+- 向量数据库高级检索策略
+- 计费系统与支付闭环
+
+### 角色与页面规划
+
+| 角色 | 页面 | 核心动作 |
+|------|------|------|
+| 普通用户 | `/agents` | 创建/编辑自己的智能体 |
+| 普通用户 | `/chat` | 选择智能体并发起对话 |
+| 普通用户 | `/logs` | 查看调用记录和错误信息 |
+| 管理员（可选） | `/admin/users` | 查看用户与资源使用情况 |
+
+### 数据模型建议
+
+```sql
+profiles (
+  id uuid primary key,
+  email text,
+  role text,                 -- user / admin
+  created_at timestamptz
+)
+
+agents (
+  id uuid primary key,
+  user_id uuid,
+  name text,
+  system_prompt text,
+  model text,
+  temperature numeric,
+  status text,               -- active / inactive
+  created_at timestamptz
+)
+
+conversations (
+  id uuid primary key,
+  user_id uuid,
+  agent_id uuid,
+  title text,
+  created_at timestamptz
+)
+
+messages (
+  id uuid primary key,
+  conversation_id uuid,
+  role text,                 -- user / assistant
+  content text,
+  token_usage int,
+  created_at timestamptz
+)
+
+llm_logs (
+  id uuid primary key,
+  user_id uuid,
+  agent_id uuid,
+  model text,
+  latency_ms int,
+  prompt_tokens int,
+  completion_tokens int,
+  status text,               -- success / error
+  error_message text,
+  created_at timestamptz
+)
+```
+
+## 2. 搭平台骨架：前后端先跑起来
+
+### 推荐技术栈
+
+- **Next.js App Router**（前端 + 部分 BFF）
+- **TypeScript**
+- **Tailwind CSS + shadcn/ui**
+- **Node.js + Express/NestJS**（如你想分离后端）
+- **PostgreSQL / Supabase**
+- **OpenAI / 兼容 OpenAI 协议模型接口**
+
+### 第一步：让 AI IDE 先搭骨架
+
+```text
+请帮我创建一个 Mini Dify 平台骨架（Next.js + TypeScript + Tailwind）。
+
+页面要求：
+1. /login 登录页
+2. /agents 智能体管理页（列表 + 新建弹窗）
+3. /chat 对话页（左侧会话列表 + 右侧聊天区）
+4. /logs 调用日志页（表格 + 状态筛选）
+
+后端要求：
+- 提供 /api/agents、/api/chat、/api/logs 的基础接口
+- 所有接口只允许登录用户访问
+
+先用 mock 数据跑通页面交互，再补真实数据库。
+```
+
+### 第二步：补鉴权与数据库
+
+你可以继续让 AI IDE 分步骤落地：
+
+```text
+请把我当成 0 基础，带我完成 Mini Dify 的鉴权和数据库接入。
+
+目标：
+1. 用户可以注册、登录、退出
+2. 登录后才能访问 /agents、/chat、/logs
+3. 创建 agents 表并实现新增/查询
+4. 只有 agent 所有者可编辑自己的 agent
+
+要求：
+- 说明每步修改了哪些文件
+- 明确需要在数据库后台操作的 SQL
+- 完成后给我一份验证清单
+```
+
+## 3. 接智能体主链路：从“创建”到“回答”
+
+### 智能体调用时序图
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as 用户
+  participant FE as 前端对话页
+  participant API as 后端 /api/chat
+  participant DB as 数据库
+  participant LLM as 模型服务
+
+  U->>FE: 选择智能体并发送问题
+  FE->>API: POST /api/chat {agentId, message}
+  API->>DB: 读取 agent 配置与历史消息
+  API->>LLM: 组装 system prompt + 历史上下文
+  LLM-->>API: 返回回答
+  API->>DB: 保存 user/assistant 消息 + 日志
+  API-->>FE: 返回回答内容
+  FE-->>U: 渲染回复
+```
+
+### 第三步：实现聊天接口（最小版本）
+
+第一版聊天接口建议做到：
+
+- 接收 `agentId` 和用户输入
+- 根据 `agentId` 加载对应系统提示词
+- 调用模型并返回结果
+- 将问答落库到 `messages`
+- 将耗时/状态写入 `llm_logs`
+
+提示词示例：
+
+```text
+请帮我实现 /api/chat 接口。
+
+业务规则：
+1. 必须校验用户是否已登录
+2. 必须校验 agent 属于当前用户
+3. 请求体包含 agentId 和 message
+4. 调用 LLM 前拼接系统提示词和最近 10 条上下文
+5. 返回 assistant 内容并写入消息表
+6. 无论成功失败都写一条 llm_logs
+
+请给出：
+- 路由层代码
+- service 层代码
+- 错误处理策略
+- 如何本地测试
+```
+
+### 第四步：可选接入知识库（加分项）
+
+你可以给每个智能体增加一个“知识库开关”：
+
+- 开启后先检索知识片段，再和用户问题一起发送给模型
+- 关闭后按普通对话模式响应
+
+第一版不必追求复杂 RAG，只要有“检索结果可见、调用链路可解释”即可。
+
+## 4. 上线与交付：把平台做成可演示产品
+
+### 部署前检查
+
+- 所有核心接口都做了登录校验
+- 智能体归属权限检查通过
+- 会话记录、日志记录真实落库
+- 模型 Key 使用环境变量，不硬编码
+- 错误提示可在前端看到，不只打控制台
+
+### 交付物
+
+- 可访问演示链接
+- 源码仓库链接
+- 智能体管理页截图
+- 对话页截图
+- 日志页截图
+- 60 秒演示视频（创建智能体 -> 对话 -> 查看日志）
+- README（架构、运行、环境变量、接口说明）
+
+## 验收标准
+
+| 维度 | 最低达标 | 加分项 |
+|------|------|------|
+| 平台完整度 | `agents/chat/logs` 三页可用 | 有清晰导航与统一设计语言 |
+| 业务闭环 | 可创建智能体并真实对话 | 支持多智能体切换与历史会话 |
+| 数据与追踪 | 消息与调用日志可查询 | 有 token/耗时统计看板 |
+| 权限安全 | 仅登录用户可访问核心接口 | 资源归属校验完善 |
+| 工程交付 | 可部署、可演示、README 清晰 | 接入知识库并可解释检索结果 |
+
+## 提交前最后检查
+
+<el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
+  <template #header>
+    <div style="font-weight: bold; font-size: 16px;">提交前最后看一眼</div>
+  </template>
+
+  <ul style="list-style-type: none; padding-left: 0;">
+    <li><label><input type="checkbox" disabled /> 登录后可访问智能体管理、对话、日志页面</label></li>
+    <li><label><input type="checkbox" disabled /> 至少可以创建 1 个智能体并成功对话</label></li>
+    <li><label><input type="checkbox" disabled /> 每轮问答都能在数据库查到记录</label></li>
+    <li><label><input type="checkbox" disabled /> 调用失败时前端可见错误信息且日志已记录</label></li>
+    <li><label><input type="checkbox" disabled /> 项目已部署，README 和演示视频齐全</label></li>
+  </ul>
+</el-card>
+
+::: tip 🚀 完成后你会得到什么？
+你将获得一个真正有平台感的 AI 项目，而不只是单点功能 Demo。这会显著提升你在“AI 产品工程化”方向的说服力。
 :::
@@ -1,6 +1,425 @@
 # 大作业 2：在线考试与管理系统

-自动出题答题、后台记录每次测试、有管理员和学生模式。。。支持正常登录。。 
+做完第一个 SaaS 项目后，下一步不只是“再做一个网站”，而是要进入更接近真实业务系统的场景。

-有管理系统、前端正常页面系统。。。。使用现代组件库。
-> 本章节正在编写中，敬请期待...
+在线考试系统就是一个很典型的练手题：
+
+- 前台不再只有一个工作台，而是有 **学生端完整考试流程**
+- 后台不再只是看数据，而是要有 **题库管理、考试管理、成绩管理**
+- 权限不再只是“登录/未登录”，而是要处理 **学生 / 管理员** 两种角色
+- 数据也不再是一张结果表，而是会涉及 **考试、题目、答卷、成绩、用户** 多种实体
+
+::: tip 🎯 这次做什么？
+打造一个 **在线考试与管理系统**。学生登录后可查看考试列表、开始答题、提交试卷、查看历史成绩；管理员可以创建考试、维护题库、查看提交记录，并根据题目规则完成自动判分或人工复核。
+:::
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="0" :items="[
+      { title: '定角色与范围', description: '先把参与者、页面和数据模型定下来' },
+      { title: '搭前台', description: '学生端和管理端页面骨架先跑起来' },
+      { title: '写接口', description: '用 Express 接通登录、考试、提交、批改' },
+      { title: '上线交付', description: '部署、README、演示材料全部补齐' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 为什么这个题目值得做？
+
+因为它特别适合练“业务系统思维”。
+
+你会发现，考试系统不是把几个页面摆在一起就结束了，它必须处理很多真实约束：
+
+- 学生只能看到自己该看的考试和成绩
+- 管理员要能发布考试、维护题目、查看提交情况
+- 一场考试通常会有开始时间、结束时间、作答时长、是否允许重复提交等规则
+- 题目可能有单选、多选、判断、简答，不同题型的判分方式也不一样
+
+这些问题会逼着你第一次认真面对：
+
+- **角色权限**
+- **数据建模**
+- **接口设计**
+- **提交流程与状态流转**
+
+这正是从“会写页面”到“会做系统”的关键一步。
+
+## 先看全景：这个系统到底由哪些部分组成？
+
+```mermaid
+flowchart TD
+  student["学生"] --> studentPages["学生端页面"]
+  admin["管理员"] --> adminPages["管理端页面"]
+  studentPages --> auth["登录鉴权"]
+  adminPages --> auth
+  studentPages --> api["Express API"]
+  adminPages --> api
+  api --> exam["exams / questions"]
+  api --> submission["submissions / answers"]
+  api --> profile["users / profiles"]
+  api --> grading["自动判分 / 结果计算"]
+  grading --> score["scores / 统计"]
+  score --> studentPages
+  score --> adminPages
+```
+
+你最终要交付的，不是一套静态页面，而是一套能让两类角色都跑通核心业务的系统。
+
+## 1. 定角色与范围：先把“做什么”说清楚
+
+### 角色设计
+
+这次只保留两种角色，先把范围收住：
+
+| 角色 | 核心动作 |
+|------|------|
+| 学生 | 登录、查看考试列表、开始答题、提交试卷、查看历史成绩 |
+| 管理员 | 登录、创建考试、维护题库、查看提交记录、查看成绩统计 |
+
+### 核心页面规划
+
+按下面这些页面来做，已经足够覆盖主要能力：
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 首页 | `/` | 说明平台用途，提供登录入口 |
+| 登录页 | `/login` | 学生和管理员共用登录入口 |
+| 学生考试列表 | `/student/exams` | 展示可参加的考试和状态 |
+| 学生答题页 | `/student/exams/:id` | 显示题目、倒计时、提交按钮 |
+| 学生成绩页 | `/student/history` | 查看历史考试记录和分数 |
+| 管理后台首页 | `/admin` | 后台概览与导航 |
+| 考试管理 | `/admin/exams` | 创建、发布、下线考试 |
+| 题库管理 | `/admin/questions` | 新增和编辑题目 |
+| 提交记录 | `/admin/submissions` | 查看学生提交和判分结果 |
+
+### 建议先做的业务边界
+
+为了确保你能完成，第一版建议只做这些：
+
+- 题型先支持 **单选、判断、简答** 三种
+- 自动判分先覆盖 **单选、判断**
+- 简答题先做 **人工复核**，或者展示“待批改”
+- 每场考试先只允许 **提交一次**
+- 不做复杂防作弊，不做随机组卷，不做监考录像
+
+### 数据模型
+
+推荐至少有下面这几张表：
+
+```sql
+profiles (
+  id uuid primary key,
+  email text,
+  role text,              -- student / admin
+  created_at timestamptz
+)
+
+exams (
+  id uuid primary key,
+  title text,
+  description text,
+  duration_minutes int,
+  status text,            -- draft / published / closed
+  created_by uuid,
+  created_at timestamptz
+)
+
+questions (
+  id uuid primary key,
+  type text,              -- single / judge / short
+  stem text,
+  options jsonb,
+  correct_answer text,
+  score int,
+  created_at timestamptz
+)
+
+exam_questions (
+  id uuid primary key,
+  exam_id uuid,
+  question_id uuid,
+  sort_order int
+)
+
+submissions (
+  id uuid primary key,
+  exam_id uuid,
+  student_id uuid,
+  status text,            -- in_progress / submitted / reviewed
+  total_score numeric,
+  submitted_at timestamptz
+)
+
+submission_answers (
+  id uuid primary key,
+  submission_id uuid,
+  question_id uuid,
+  answer_text text,
+  is_correct boolean,
+  score numeric
+)
+```
+
+### 关键时序图
+
+学生参加考试时，系统的主链路大致长这样：
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor Student as 学生
+  participant Frontend as 学生端页面
+  participant API as Express API
+  participant DB as 数据库
+
+  Student->>Frontend: 进入考试列表页
+  Frontend->>API: GET /api/exams
+  API->>DB: 查询已发布考试
+  DB-->>API: 返回考试列表
+  API-->>Frontend: 返回可参加考试
+  Student->>Frontend: 点击开始考试
+  Frontend->>API: POST /api/submissions/start
+  API->>DB: 创建 submission
+  API-->>Frontend: 返回试卷与 submissionId
+  Student->>Frontend: 作答并提交
+  Frontend->>API: POST /api/submissions/:id/submit
+  API->>API: 自动判分客观题
+  API->>DB: 保存答案与总分
+  API-->>Frontend: 返回提交结果
+```
+
+到这一步，你应该已经能看清这个作业的真正重点了：不是“页面多”，而是“状态和数据流更多”。
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="1" :items="[
+      { title: '定角色与范围', description: '先把参与者、页面和数据模型定下来' },
+      { title: '搭前台', description: '学生端和管理端页面骨架先跑起来' },
+      { title: '写接口', description: '用 Express 接通登录、考试、提交、批改' },
+      { title: '上线交付', description: '部署、README、演示材料全部补齐' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 2. 搭前台：先让学生端和管理端“看得见、点得动”
+
+这一步先不要急着把所有后端写完，先把页面骨架搭出来。
+
+### 推荐技术栈
+
+- **Next.js / React**：负责前端页面
+- **TypeScript**：保证类型清晰
+- **Tailwind CSS + shadcn/ui**：快速搭建专业界面
+- **Express**：编写 REST API
+- **PostgreSQL / Supabase Postgres**：存业务数据
+
+### 第一步：让 AI IDE 先帮你起出页面骨架
+
+```text
+请帮我创建一个在线考试与管理系统的前端页面骨架。
+
+技术栈要求：
+- Next.js App Router
+- TypeScript
+- Tailwind CSS
+- shadcn/ui
+
+页面清单：
+1. 首页 /
+2. 登录页 /login
+3. 学生考试列表页 /student/exams
+4. 学生答题页 /student/exams/[id]
+5. 学生成绩页 /student/history
+6. 管理后台首页 /admin
+7. 考试管理页 /admin/exams
+8. 题库管理页 /admin/questions
+9. 提交记录页 /admin/submissions
+
+要求：
+- 学生端页面强调清晰、专注、易答题
+- 管理端页面使用侧边栏 + 顶部栏布局
+- 先使用 mock 数据，不接真实接口
+- 注意桌面端和移动端的基本可用性
+```
+
+### 第二步：完善学生答题页
+
+答题页是学生端最重要的一页，至少要包含这些内容：
+
+- 考试标题、剩余时间、进度提示
+- 当前题目内容与选项
+- 上一题 / 下一题导航
+- 已作答状态提示
+- 提交确认弹窗
+
+你可以继续给 AI IDE 这样的提示：
+
+```text
+请继续完善学生答题页。
+
+这是一个在线考试系统的答题页面，需要包含：
+- 顶部显示考试标题、倒计时、已答题数量
+- 中间显示题干和选项
+- 支持单选、判断、简答三种题型
+- 左侧或顶部有答题卡，显示每道题是否已作答
+- 点击提交前弹出确认框
+
+先用 mock 数据实现交互，不接真实接口。
+
+要求：
+- 界面简洁，不要像后台表格页
+- 倒计时要醒目，但不要制造过强压迫感
+- 有空状态和 loading 状态
+```
+
+### 第三步：完善管理员后台
+
+管理员后台不是越复杂越好，第一版先做三个核心区域：
+
+- **考试管理**：创建考试、设置时长、发布状态
+- **题库管理**：新增题目、编辑题目、按题型筛选
+- **提交记录**：查看学生提交、分数、时间
+
+如果你卡住了，可以回头看这些章节：
+
+- [从数据库到 Supabase](../../backend/2.2-database-supabase/)
+- [应用后端接口设计与开发](../../backend/2.3-ai-interface-code/)
+- [使用现代组件库更新你的界面](../../frontend/2.7-modern-component-library/)
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="2" :items="[
+      { title: '定角色与范围', description: '先把参与者、页面和数据模型定下来' },
+      { title: '搭前台', description: '学生端和管理端页面骨架先跑起来' },
+      { title: '写接口', description: '用 Express 接通登录、考试、提交、批改' },
+      { title: '上线交付', description: '部署、README、演示材料全部补齐' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 3. 写接口：让 Express 真正接管业务逻辑
+
+这一步，项目才真正进入“系统开发”状态。
+
+### 第四步：完成登录与权限控制
+
+```text
+请把我当成 0 基础，帮我完成在线考试系统的登录与权限控制。
+
+后端使用 Express。
+
+目标：
+1. 学生和管理员都可以登录
+2. 登录后返回用户角色
+3. 学生只能访问 /student/* 相关接口
+4. 管理员只能访问 /admin/* 相关接口
+5. 未登录用户访问受保护页面时跳转 /login
+
+实现要求：
+- 给出清晰的目录结构建议
+- 明确说明中间件负责什么
+- 涉及环境变量的地方不要硬编码
+- 完成后说明如何验证权限是否生效
+```
+
+### 第五步：完成考试与题库管理接口
+
+建议先做这几组接口：
+
+| 模块 | 推荐接口 |
+|------|------|
+| 考试管理 | `GET /api/exams`、`POST /api/admin/exams`、`PATCH /api/admin/exams/:id` |
+| 题库管理 | `GET /api/admin/questions`、`POST /api/admin/questions` |
+| 开始考试 | `POST /api/submissions/start` |
+| 提交试卷 | `POST /api/submissions/:id/submit` |
+| 成绩记录 | `GET /api/student/history`、`GET /api/admin/submissions` |
+
+如果你想让 AI IDE 一步步带你完成，可以直接这样说：
+
+```text
+请帮我为在线考试系统设计并实现 Express API。
+
+功能范围：
+- 管理员创建考试
+- 管理员维护题库
+- 学生查看已发布考试
+- 学生开始考试并创建 submission
+- 学生提交答案后自动判分单选题和判断题
+- 简答题先标记为待复核
+- 学生查看自己的历史成绩
+- 管理员查看所有提交记录
+
+要求：
+- 接口命名清晰
+- 返回统一 JSON 结构
+- 代码中区分 controller、service、middleware、db 层
+- 说明每个接口如何测试
+```
+
+### 第六步：实现判分逻辑
+
+这一部分很适合练后端思维。
+
+- 单选题：用户答案与标准答案一致则得分
+- 判断题：同样可以自动判分
+- 简答题：第一版可以先只保存答案，分数为空，状态为 `reviewed = false`
+
+如果你想再加一点 AI 能力，也可以让管理员在后台输入“主题 + 难度”，由模型先生成一批候选题，再人工审核后入库。但这属于加分项，不是必须项。
+
+## 4. 上线与交付：把项目从“做完”变成“可展示”
+
+### 部署建议
+
+- 前端部署到 Vercel / Zeabur
+- Express API 部署到 Zeabur / Railway / Render
+- 数据库用 Supabase Postgres 或托管 PostgreSQL
+
+部署前至少检查这些内容：
+
+- 环境变量是否齐全
+- 前后端 API 地址是否正确
+- 登录态是否在生产环境正常工作
+- 管理员账号是否能真实访问后台
+- README 是否包含启动、部署、测试说明
+
+### 你至少要准备的交付物
+
+- 首页截图
+- 学生考试列表截图
+- 学生答题页截图
+- 管理后台截图
+- 60 秒左右演示视频
+- 一份写清楚环境变量和启动方式的 README
+
+## 验收标准
+
+| 维度 | 最低达标 | 加分项 |
+|------|------|------|
+| 页面完整度 | 学生端和管理端主要页面都可访问 | 页面风格统一，状态清晰，移动端也基本可用 |
+| 业务闭环 | 学生可登录、参加考试、提交并查看成绩 | 管理员可完整创建并发布考试 |
+| 数据正确性 | 提交答案后能写入数据库，客观题能自动判分 | 简答题支持人工复核或 AI 辅助建议 |
+| 权限控制 | 学生与管理员访问边界清晰 | 服务端接口也有角色校验，不只做前端隐藏 |
+| 工程交付 | 项目可运行、可部署、README 清晰 | 有演示视频和测试说明 |
+
+## 提交前最后检查
+
+<el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
+  <template #header>
+    <div style="font-weight: bold; font-size: 16px;">提交前最后看一眼</div>
+  </template>
+
+  <ul style="list-style-type: none; padding-left: 0;">
+    <li><label><input type="checkbox" disabled /> 首页、登录页、学生端、管理端页面均已完成</label></li>
+    <li><label><input type="checkbox" disabled /> 学生可以正常开始考试并提交答案</label></li>
+    <li><label><input type="checkbox" disabled /> 管理员可以创建考试并查看提交记录</label></li>
+    <li><label><input type="checkbox" disabled /> 客观题分数能够自动计算并写入数据库</label></li>
+    <li><label><input type="checkbox" disabled /> 学生与管理员权限边界已验证</label></li>
+    <li><label><input type="checkbox" disabled /> 项目已部署或具备完整本地运行说明</label></li>
+  </ul>
+</el-card>
+
+::: tip 🚀 完成后你会得到什么？
+如果你把这个项目真正做完，你收获的就不只是“又写了几个页面”，而是第一次完整处理了一个多角色业务系统。
+
+这会让你在后续做教培、SaaS、后台管理、内容平台类项目时，明显更有底气。
+:::
@@ -1,7 +1,228 @@
 # 现代网页落地页

-::: warning 🚧 建设中
+很多同学会写功能页，但一到“让用户第一次看到就愿意注册”的落地页就卡住了。

-本文档正在编写中，内容可能会有较大变动。请关注更新。
+这份大作业就是专门练这件事：你要做一个真正能承接流量、讲清价值、引导转化的现代落地页，而不是“看起来像作业”的静态展示页。

+::: tip 🎯 这次做什么？
+打造一个 **可上线的现代产品落地页**。页面需要包含价值主张、核心功能展示、用户证言、价格方案、FAQ、明确 CTA（注册/预约演示）以及基础数据埋点，最终可以用于真实投放或作品集展示。
+:::
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="0" :items="[
+      { title: '定定位', description: '先锁定目标用户、价值主张与转化目标' },
+      { title: '搭结构', description: '搭出页面区块、导航和响应式骨架' },
+      { title: '做转化', description: '补齐文案、视觉、CTA 与埋点' },
+      { title: '上线交付', description: '性能优化、部署与演示材料整理' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 为什么这个题目值得做？
+
+因为落地页不是“前端练习题”，而是产品和增长的交叉点。
+
+- 你会练到结构化表达：30 秒内让用户知道你是谁、你解决什么问题
+- 你会练到工程能力：组件化、响应式、性能优化、SEO 基础
+- 你会练到转化意识：CTA 设计、表单路径、埋点事件、A/B 迭代
+
+做完这个项目，你不仅能做“页面”，还能做“会转化的页面”。
+
+## 先看全景：一张图看懂这个作业
+
+```mermaid
+flowchart TD
+  ad["流量来源: 社媒 / 搜索 / 社群"] --> landing["落地页首页"]
+  landing --> value["价值主张区"]
+  landing --> features["功能展示区"]
+  landing --> social["用户证言 / 案例"]
+  landing --> pricing["价格与方案"]
+  landing --> faq["常见问题"]
+  value --> cta["主 CTA: 立即注册 / 预约演示"]
+  pricing --> cta
+  faq --> cta
+  cta --> form["注册/预约表单"]
+  form --> success["成功页 / 感谢页"]
+  form --> event["埋点事件上报"]
+```
+
+这张图表达的核心是：你的目标不是把每个模块都写出来，而是让用户自然走到 CTA 并完成动作。
+
+## 1. 定定位：先把“做给谁看”讲清楚
+
+### 建议你先写出这 4 句话
+
+1. 我们的产品是什么？
+2. 目标用户是谁？
+3. 用户最痛的一个问题是什么？
+4. 用户看完页面后希望他做什么动作？
+
+### 项目边界（MVP）
+
+第一版请严格控制范围：
+
+- 只做 **单页落地页**，不要先做完整后台
+- CTA 先聚焦 **一个主动作**（注册或预约演示二选一）
+- 只做 **一个核心受众**，不要同时覆盖所有人群
+- 先做静态内容 + 基础交互，不做复杂动画大片
+- 埋点只做关键 3~5 个事件，不做全链路数据平台
+
+### 页面模块规划
+
+| 模块 | 目标 | 最低要求 |
+|------|------|------|
+| Hero 区 | 5 秒内传达价值 | 标题、副标题、主 CTA、视觉主图 |
+| 功能区 | 解释“怎么解决” | 3~6 个核心能力卡片 |
+| 信任区 | 提升可信度 | 用户证言、Logo、案例之一 |
+| 价格区 | 降低决策成本 | 至少两档方案，强调推荐方案 |
+| FAQ | 处理犹豫 | 4~8 个高频问题 |
+| Footer | 完整闭环 | 联系方式、隐私/条款入口 |
+
+## 2. 搭结构：先做骨架，再做精修
+
+### 推荐技术栈
+
+- **Next.js App Router** 或 **Vite + React**
+- **TypeScript**
+- **Tailwind CSS**
+- **shadcn/ui**（可选）
+- **Vercel Analytics / 自定义埋点**
+
+### 第一步：生成可运行的页面骨架
+
+你可以先让 AI IDE 生成第一版结构：
+
+```text
+请帮我创建一个现代 SaaS 落地页（Next.js + TypeScript + Tailwind）。
+
+页面区块：
+1. 顶部导航（logo、锚点、登录、注册）
+2. Hero 区（主标题、副标题、CTA）
+3. 功能介绍区（6 张卡片）
+4. 用户证言区
+5. 价格区（Free/Pro/Team）
+6. FAQ 区（手风琴）
+7. 页脚
+
+要求：
+- 风格现代、简洁，不要像课堂作业
+- 先实现响应式布局
+- 所有 CTA 有 hover/active 状态
+- 预留事件埋点函数
+```
+
+### 第二步：补齐文案与信息层级
+
+很多页面做不出转化，根因是信息顺序错了。你可以继续给 AI IDE：
+
+```text
+请优化我的落地页文案结构，目标是提高注册转化率。
+
+背景：
+- 目标用户：独立开发者和小团队
+- 核心价值：用 AI 自动生成营销内容
+- 主转化动作：点击“免费开始”
+
+请输出：
+1. Hero 标题 5 个备选
+2. 副标题 5 个备选
+3. CTA 按钮文案 5 个备选
+4. 每个功能卡片的一句话价值描述
+5. FAQ 建议问题列表
+```
+
+### 第三步：加关键交互与状态
+
+至少补齐这几项：
+
+- CTA 点击 loading 状态
+- 表单提交成功/失败反馈
+- 页面锚点平滑滚动
+- 移动端菜单展开/收起
+- 表单字段基础校验
+
+## 3. 做转化：从“好看”走向“有效”
+
+### 最小埋点方案
+
+建议先只做以下事件：
+
+| 事件名 | 触发时机 | 目的 |
+|------|------|------|
+| `view_hero` | 首屏展示 | 统计曝光 |
+| `click_primary_cta` | 点击主 CTA | 统计主转化意图 |
+| `view_pricing` | 价格区进入视口 | 评估价格区关注度 |
+| `submit_lead_form` | 提交表单 | 统计核心转化 |
+| `submit_lead_form_error` | 提交失败 | 发现转化阻塞点 |
+
+### 转化路径时序图
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor User as 访客
+  participant Page as 落地页
+  participant Form as 注册表单
+  participant API as 提交接口
+  participant Analytics as 埋点系统
+
+  User->>Page: 打开页面
+  Page->>Analytics: view_hero
+  User->>Page: 点击主 CTA
+  Page->>Analytics: click_primary_cta
+  Page->>Form: 打开表单
+  User->>Form: 填写并提交
+  Form->>API: POST /api/leads
+  API-->>Form: success / error
+  Form->>Analytics: submit_lead_form 或 submit_lead_form_error
+  Form-->>User: 显示成功或失败反馈
+```
+
+## 4. 上线交付：从“能跑”到“能展示”
+
+### 部署前检查
+
+- Lighthouse 移动端性能建议 75+（第一版即可）
+- 图片已压缩并使用现代格式
+- 标题、描述、OG 基础信息已配置
+- 所有 CTA 都有真实目标行为
+- 关键事件埋点可在控制台看到
+
+### 交付物
+
+- 线上链接（Vercel/Netlify 等）
+- 项目仓库地址
+- 主要页面截图（桌面端 + 移动端）
+- 60 秒演示视频（讲清目标用户与转化路径）
+- README（启动方式、技术栈、埋点说明）
+
+## 验收标准
+
+| 维度 | 最低达标 | 加分项 |
+|------|------|------|
+| 页面完整度 | Hero/功能/价格/FAQ/页脚完整 | 信息密度与视觉层级优秀 |
+| 转化设计 | 有明确主 CTA 和提交流程 | CTA 文案与位置经过对比优化 |
+| 工程质量 | 响应式正常、交互状态完整 | 组件拆分清晰、复用性高 |
+| 数据意识 | 关键事件埋点可用 | 有初步转化漏斗分析 |
+| 交付能力 | 可访问链接 + README + 演示视频 | Lighthouse、SEO、无障碍基础优化 |
+
+## 提交前最后检查
+
+<el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
+  <template #header>
+    <div style="font-weight: bold; font-size: 16px;">提交前最后看一眼</div>
+  </template>
+
+  <ul style="list-style-type: none; padding-left: 0;">
+    <li><label><input type="checkbox" disabled /> 页面核心区块已全部完成并可访问</label></li>
+    <li><label><input type="checkbox" disabled /> 主 CTA 路径可真实触发提交动作</label></li>
+    <li><label><input type="checkbox" disabled /> 桌面端和移动端布局都可正常使用</label></li>
+    <li><label><input type="checkbox" disabled /> 至少 3 个关键埋点事件已验证</label></li>
+    <li><label><input type="checkbox" disabled /> 项目已部署并准备演示材料</label></li>
+  </ul>
+</el-card>
+
+::: tip 🚀 完成后你会得到什么？
+这会是你作品集中最“有商业味道”的页面之一。它证明你不只会做界面，还能围绕目标用户和转化结果来做产品页面。
 :::
@@ -1,7 +1,294 @@
 # 电影推荐网 (Spring Boot)

-::: warning 🚧 建设中
+推荐系统是最典型的“看起来简单，做起来很像真实业务系统”的题目。

-本文档正在编写中，内容可能会有较大变动。请关注更新。
+这次大作业你会从“电影列表网站”升级到“可登录、可评分、可推荐、可管理”的完整产品原型。

+::: tip 🎯 这次做什么？
+打造一个 **电影推荐网站（Spring Boot）**。用户登录后可浏览电影、搜索筛选、评分收藏，并获得个性化推荐；管理员可维护电影数据、查看用户行为统计与推荐效果。
 :::
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="0" :items="[
+      { title: '定边界', description: '先锁定推荐策略和第一版业务范围' },
+      { title: '搭基础', description: '先做用户、电影、评分这些核心页面' },
+      { title: '做推荐', description: '接通 Spring Boot 接口与推荐逻辑' },
+      { title: '上线交付', description: '补齐后台、部署和演示材料' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 为什么这个题目适合 Stage 2？
+
+因为它能一次性把你带过 5 个关键能力：
+
+- **后端工程化**：Controller / Service / Repository 分层
+- **数据建模**：用户、电影、标签、评分、推荐结果
+- **业务逻辑**：搜索筛选、评分行为、收藏与历史
+- **推荐算法入门**：规则推荐或协同过滤
+- **管理能力**：后台维护数据与查看指标
+
+做完后你不仅能讲“我写了个网站”，还能讲清楚“推荐是怎么跑起来的”。
+
+## 先看系统全景
+
+```mermaid
+flowchart LR
+  user["用户端"] --> fe["Web 前端"]
+  admin["管理员"] --> adminfe["后台页面"]
+  fe --> api["Spring Boot API"]
+  adminfe --> api
+  api --> mysql["MySQL"]
+  api --> redis["Redis (可选缓存)"]
+  api --> rec["推荐服务层"]
+  rec --> feature["用户偏好特征"]
+  rec --> movieFeature["电影标签特征"]
+  rec --> result["推荐结果"]
+  result --> fe
+```
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as 用户
+  participant FE as 前端
+  participant API as Spring Boot
+  participant REC as 推荐模块
+  participant DB as MySQL
+
+  U->>FE: 浏览电影并评分
+  FE->>API: POST /api/ratings
+  API->>DB: 写入评分记录
+  U->>FE: 打开“为你推荐”
+  FE->>API: GET /api/recommendations
+  API->>REC: 计算推荐候选
+  REC->>DB: 读取用户偏好与电影标签
+  DB-->>REC: 返回特征数据
+  REC-->>API: 返回推荐列表
+  API-->>FE: 返回电影卡片数据
+```
+
+## 1. 定边界：别一上来就做“工业级推荐系统”
+
+### 角色设计
+
+| 角色 | 核心动作 |
+|------|------|
+| 普通用户 | 注册登录、浏览电影、搜索筛选、评分收藏、查看推荐 |
+| 管理员 | 电影信息管理、标签管理、用户行为统计、推荐结果抽查 |
+
+### 核心页面规划
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 首页 | `/` | 热门电影与推荐入口 |
+| 登录/注册 | `/login` `/register` | 用户认证 |
+| 电影列表 | `/movies` | 搜索、筛选、分页 |
+| 电影详情 | `/movies/:id` | 简介、标签、评分、评论 |
+| 推荐页 | `/recommendations` | 个性化推荐结果 |
+| 收藏页 | `/favorites` | 收藏电影管理 |
+| 管理后台 | `/admin` | 电影与标签维护、统计看板 |
+
+### 第一版推荐策略（建议）
+
+第一版只做一套简单但稳定的推荐规则：
+
+- 基于用户历史评分的 **标签偏好加权**
+- 再叠加热门度分数（避免冷启动全空）
+- 去掉用户已看/已评分电影
+
+先把可解释、可跑通的推荐做出来，比复杂算法更重要。
+
+## 2. 搭基础：先完成“非推荐功能闭环”
+
+### 推荐技术栈
+
+- 后端：Spring Boot 3 + Spring Web + Spring Data JPA
+- 数据库：MySQL 8
+- 缓存：Redis（可选）
+- 前端：Vue/React 任一（可由 AI IDE 生成）
+- 鉴权：JWT
+
+### 数据模型建议
+
+```sql
+users (
+  id bigint primary key auto_increment,
+  email varchar(120),
+  password_hash varchar(255),
+  role varchar(20), -- user / admin
+  created_at datetime
+)
+
+movies (
+  id bigint primary key auto_increment,
+  title varchar(200),
+  summary text,
+  release_year int,
+  poster_url varchar(500),
+  created_at datetime
+)
+
+movie_tags (
+  id bigint primary key auto_increment,
+  movie_id bigint,
+  tag varchar(50)
+)
+
+ratings (
+  id bigint primary key auto_increment,
+  user_id bigint,
+  movie_id bigint,
+  score int, -- 1~5
+  created_at datetime
+)
+
+favorites (
+  id bigint primary key auto_increment,
+  user_id bigint,
+  movie_id bigint,
+  created_at datetime
+)
+```
+
+### 第一步：用 AI IDE 生成 Spring Boot 骨架
+
+```text
+请帮我搭建一个 Spring Boot 电影推荐网站后端骨架。
+
+要求：
+- Java 17 + Spring Boot 3
+- 分层结构：controller / service / repository / model / dto
+- MySQL + JPA
+- JWT 登录鉴权
+
+接口优先实现：
+1. 用户注册登录
+2. 电影列表查询（分页+关键词）
+3. 电影详情
+4. 用户评分
+5. 收藏与取消收藏
+
+请先给出目录结构和关键类清单，再逐步生成代码。
+```
+
+### 第二步：补齐前端基础页面
+
+```text
+请帮我生成一个电影推荐网站前端页面骨架。
+
+页面包括：
+- 首页
+- 电影列表页（筛选+分页）
+- 电影详情页（评分+收藏）
+- 推荐页
+- 个人中心
+- 管理后台
+
+要求：
+- 组件化开发
+- 有 loading、空态、错误提示
+- 先接 mock 接口，再切换真实 API
+```
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="1" :items="[
+      { title: '定边界', description: '先锁定推荐策略和第一版业务范围' },
+      { title: '搭基础', description: '先做用户、电影、评分这些核心页面' },
+      { title: '做推荐', description: '接通 Spring Boot 接口与推荐逻辑' },
+      { title: '上线交付', description: '补齐后台、部署和演示材料' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 3. 做推荐：先做“可解释推荐”，再做“更聪明推荐”
+
+### 推荐模块拆分建议
+
+| 模块 | 职责 |
+|------|------|
+| CandidateService | 召回候选电影（未看、同标签、热门） |
+| RankingService | 按偏好分数排序并截断 TopN |
+| ExplainService | 生成“为什么推荐这部电影”文案 |
+| RecommendationController | 对外提供推荐接口 |
+
+### 推荐流程图
+
+```mermaid
+flowchart TD
+  A["读取用户评分历史"] --> B["统计用户标签偏好"]
+  B --> C["召回候选电影"]
+  C --> D["计算综合分数"]
+  D --> E["过滤已看电影"]
+  E --> F["生成 Top N 推荐"]
+  F --> G["返回推荐原因与标签命中"]
+```
+
+### 第三步：让 AI IDE 帮你实现推荐接口
+
+```text
+请帮我实现 Spring Boot 推荐接口 GET /api/recommendations。
+
+业务规则：
+1. 根据用户最近评分记录统计偏好标签权重
+2. 从同标签电影中召回候选
+3. 结合全站热门度做加权
+4. 去掉用户已经评分过的电影
+5. 返回前 12 条推荐，并附带推荐理由
+
+要求：
+- Service 层拆分清晰
+- SQL 或 JPA 查询可读
+- 返回结构包含 movieId、title、score、reason
+- 给出最小可跑通的单元测试示例
+```
+
+### 第四步：补管理员统计页
+
+第一版至少展示这些指标：
+
+- 总用户数
+- 总电影数
+- 最近 7 天评分次数
+- 推荐接口成功率与平均耗时
+
+这样你可以快速发现系统是否健康，而不是“看起来能用但实际经常失败”。
+
+## 4. 上线与交付
+
+### 交付物
+
+- Spring Boot 后端仓库（含数据库初始化脚本）
+- 前端项目仓库（或单仓 monorepo）
+- 可访问演示地址
+- README（本地启动、环境变量、部署方式）
+- 60 秒演示视频
+
+### 验收标准
+
+| 维度 | 最低达标 | 加分项 |
+|------|------|------|
+| 基础功能 | 注册登录、电影浏览、评分收藏都可用 | 评论、观看历史等拓展功能 |
+| 推荐质量 | 推荐列表可生成且有理由 | 支持冷启动策略与个性化解释 |
+| 工程质量 | 接口分层清晰，错误可追踪 | 有单测与缓存优化 |
+| 管理能力 | 管理员可维护电影和标签 | 有统计看板和告警阈值 |
+| 交付能力 | 可部署、文档完整、可复现 | CI/CD 或自动化脚本 |
+
+## 提交前最后检查
+
+<el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
+  <template #header>
+    <div style="font-weight: bold; font-size: 16px;">提交前最后看一眼</div>
+  </template>
+
+  <ul style="list-style-type: none; padding-left: 0;">
+    <li><label><input type="checkbox" disabled /> 用户可注册登录并浏览电影</label></li>
+    <li><label><input type="checkbox" disabled /> 评分与收藏数据已写入数据库</label></li>
+    <li><label><input type="checkbox" disabled /> 推荐页能返回个性化结果</label></li>
+    <li><label><input type="checkbox" disabled /> 推荐结果包含“推荐理由”字段</label></li>
+    <li><label><input type="checkbox" disabled /> 管理后台可维护电影与标签</label></li>
+    <li><label><input type="checkbox" disabled /> 项目可部署且 README 可复现</label></li>
+  </ul>
+</el-card>
@@ -1,7 +1,253 @@
 # 简单买菜微服务网站

-::: warning 🚧 建设中
+做完单体应用后，很多同学会进入一个新困惑：功能越来越多，代码还能写，但项目越来越难维护。

-本文档正在编写中，内容可能会有较大变动。请关注更新。
+这个大作业的目标，就是让你在一个可控规模里，体验一次“从单体到微服务”的完整过程。

+::: tip 🎯 这次做什么？
+打造一个 **简单买菜微服务网站**。用户可以浏览商品、下单、查看订单；管理员可以管理商品与库存。后端拆成多个服务，通过 API 网关统一对外提供接口。
+:::
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="0" :items="[
+      { title: '定边界', description: '先明确服务拆分和业务范围' },
+      { title: '搭基础', description: '网关、鉴权、数据库连接先跑通' },
+      { title: '接业务', description: '商品、订单、库存链路打通' },
+      { title: '交付上线', description: '部署、文档、演示材料补齐' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 为什么这个项目值得做？
+
+这个题目看起来是“买菜网站”，本质上练的是三个能力：
+
+- **拆服务**：学会按业务边界拆分，而不是按技术层硬拆
+- **控复杂度**：在多服务协作下保持清晰的接口和数据流
+- **做稳定链路**：让“下单 -> 扣库存 -> 查订单”能够稳定可追踪
+
+这会直接影响你后续做电商、SaaS 后台、内容平台等多模块项目的上限。
+
+## 先看全景：系统由哪些模块组成？
+
+```mermaid
+flowchart LR
+  user["用户端 Web"] --> gateway["API Gateway"]
+  admin["管理端 Web"] --> gateway
+  gateway --> auth["Auth 服务"]
+  gateway --> catalog["商品服务"]
+  gateway --> order["订单服务"]
+  gateway --> inventory["库存服务"]
+  order --> inventory
+  catalog --> db1["Catalog DB"]
+  order --> db2["Order DB"]
+  inventory --> db3["Inventory DB"]
+  auth --> db4["User DB"]
+```
+
+这张图的核心意思是：前端不用直接找多个服务，只和网关交互。复杂性由网关和服务间协作承担。
+
+## 1. 定边界：先把范围控制住
+
+### 建议服务拆分
+
+第一版只保留 4 个核心服务：
+
+| 服务 | 职责 |
+|------|------|
+| `auth-service` | 登录、注册、令牌校验、角色识别 |
+| `catalog-service` | 商品列表、商品详情、分类查询 |
+| `inventory-service` | 库存查询、库存扣减、库存回滚 |
+| `order-service` | 创建订单、查询订单、订单状态管理 |
+
+### 建议角色与页面
+
+| 角色 | 页面 | 关键动作 |
+|------|------|------|
+| 用户 | 首页、商品页、购物车、订单页 | 浏览商品、下单、看订单 |
+| 管理员 | 商品管理、库存管理、订单管理 | 上下架商品、调库存、查看异常订单 |
+
+### 范围控制（一定要先做“能交付”的版本）
+
+- 只做最小支付模拟，不接真实支付网关
+- 不做复杂促销（满减、优惠券、拼团）
+- 不做推荐算法，商品排序先按上架时间或销量
+- 不做分布式事务框架，先用“本地事务 + 失败补偿”思路
+- 不做消息中间件集群，第一版可同步调用
+
+## 2. 架构与时序
+
+### 请求路由链路
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as 用户
+  participant FE as 前端
+  participant GW as API Gateway
+  participant AUTH as Auth
+  participant CATALOG as Catalog
+  participant ORDER as Order
+  participant INV as Inventory
+
+  U->>FE: 打开商品页并下单
+  FE->>GW: POST /api/orders
+  GW->>AUTH: 校验 JWT
+  AUTH-->>GW: 用户身份合法
+  GW->>ORDER: 创建订单请求
+  ORDER->>INV: 扣减库存
+  INV-->>ORDER: 扣减结果
+  ORDER-->>GW: 订单创建成功
+  GW-->>FE: 返回订单号和状态
+```
+
+### 失败补偿思路（避免“扣了库存却没订单”）
+
+```mermaid
+flowchart TD
+  A["创建订单请求"] --> B["校验库存是否足够"]
+  B -->|不足| C["返回失败"]
+  B -->|充足| D["预扣库存"]
+  D --> E["写入订单记录"]
+  E -->|成功| F["确认扣减完成"]
+  E -->|失败| G["回滚库存"]
+  G --> H["记录补偿日志"]
+  F --> I["返回下单成功"]
+```
+
+## 3. 推荐技术栈
+
+- **前端**：Next.js + TypeScript + Tailwind CSS + shadcn/ui
+- **服务端**：Node.js + Express / Fastify
+- **网关**：Express Gateway 或自建 BFF 网关
+- **数据库**：PostgreSQL（每个服务独立库或独立 schema）
+- **缓存（可选）**：Redis（热商品列表、会话短缓存）
+- **部署**：Docker Compose（本地）+ Zeabur / Railway（云端）
+
+## 4. 分步实现路径（可直接照做）
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="1" :items="[
+      { title: '定边界', description: '先明确服务拆分和业务范围' },
+      { title: '搭基础', description: '网关、鉴权、数据库连接先跑通' },
+      { title: '接业务', description: '商品、订单、库存链路打通' },
+      { title: '交付上线', description: '部署、文档、演示材料补齐' }
+    ]" />
+  </ClientOnly>
+</div>
+
+### 第一步：起项目骨架与网关
+
+```text
+请帮我搭建一个买菜微服务项目骨架。
+
+要求：
+1. 创建 api-gateway、auth-service、catalog-service、inventory-service、order-service 五个服务目录
+2. 每个服务都包含最小可运行的 Express 入口
+3. gateway 支持把 /api/catalog/* 转发到 catalog-service，把 /api/orders/* 转发到 order-service
+4. 使用 TypeScript
+5. 给出本地启动脚本（可用 pnpm workspace 或 npm workspaces）
+```
+
+### 第二步：先做鉴权，再做业务接口
+
+先完成：
+
+- 用户注册 / 登录
+- JWT 发放和校验中间件
+- 网关统一鉴权（白名单接口可放行）
+
+```text
+请帮我实现 auth-service 的最小鉴权链路。
+
+目标：
+1. POST /register
+2. POST /login
+3. 输出 access token
+4. gateway 中间件可以验证 token 并把 userId、role 注入请求上下文
+5. 提供一个受保护示例接口用于测试
+```
+
+### 第三步：商品与库存服务
+
+优先做这几个接口：
+
+- `GET /api/catalog/products`
+- `GET /api/catalog/products/:id`
+- `PATCH /api/inventory/:productId`（管理员）
+
+### 第四步：订单服务打通主链路
+
+优先做下单和查单：
+
+- `POST /api/orders`
+- `GET /api/orders/:id`
+- `GET /api/orders/my`
+
+下单流程必须至少包含：
+
+1. 鉴权通过
+2. 校验商品和库存
+3. 创建订单
+4. 扣减库存
+5. 失败时回滚或补偿
+
+### 第五步：管理端最小闭环
+
+管理员界面先做三块就够：
+
+- 商品列表 + 上下架按钮
+- 库存调整表单
+- 订单列表（含状态筛选）
+
+### 第六步：部署与文档
+
+至少完成：
+
+- 一份项目结构图
+- 一份服务启动说明
+- 一份关键接口说明
+- 一份本地联调步骤
+
+## 5. 交付物要求
+
+你至少要提交这些内容：
+
+- 可运行项目代码（网关 + 4 个服务 + 前端）
+- 演示地址或本地可复现说明
+- README（含架构图、启动方式、接口概览）
+- 60 秒到 120 秒演示视频
+- 关键页面截图（用户下单、管理员改库存、订单详情）
+
+## 6. 验收标准
+
+| 维度 | 最低达标 | 加分项 |
+|------|------|------|
+| 架构清晰度 | 服务边界明确，网关可用 | 有统一错误码和服务间追踪日志 |
+| 业务闭环 | 浏览商品 -> 下单 -> 查单跑通 | 有库存不足、下单失败等异常处理 |
+| 权限控制 | 用户与管理员权限隔离 | 服务端接口也有角色校验，不只前端隐藏 |
+| 工程质量 | 项目可启动、接口可调试 | 有 Docker Compose、一键启动脚本 |
+| 交付完整度 | README、截图、演示视频齐全 | 有性能优化或缓存策略说明 |
+
+## 7. 提交前最后检查
+
+<el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
+  <template #header>
+    <div style="font-weight: bold; font-size: 16px;">提交前最后看一眼</div>
+  </template>
+
+  <ul style="list-style-type: none; padding-left: 0;">
+    <li><label><input type="checkbox" disabled /> 网关已接入鉴权并能正确转发请求</label></li>
+    <li><label><input type="checkbox" disabled /> 商品、库存、订单三个核心服务已打通</label></li>
+    <li><label><input type="checkbox" disabled /> 下单失败时有清晰错误提示和补偿处理</label></li>
+    <li><label><input type="checkbox" disabled /> 用户端和管理端都可完成核心操作</label></li>
+    <li><label><input type="checkbox" disabled /> README、架构图、演示视频已准备完整</label></li>
+    <li><label><input type="checkbox" disabled /> 项目已部署或有完整本地复现步骤</label></li>
+  </ul>
+</el-card>
+
+::: tip
+这个作业最重要的不是“服务越多越好”，而是你能不能把边界、协作和失败处理讲清楚并做扎实。
 :::
@@ -1,7 +1,239 @@
 # 交通大数据可视化分析 (Go项目)

-::: warning 🚧 建设中
+很多同学学 Go 时会卡在一个问题：会写接口，但不知道怎么把“数据处理能力”和“业务展示能力”组合成一个完整项目。

-本文档正在编写中，内容可能会有较大变动。请关注更新。
+这个大作业就是为了解这个问题。你会做一个可运行的交通数据平台，从数据接入、清洗、聚合，到可视化展示和告警，一条链路走完。

+::: tip 🎯 这次做什么？
+打造一个 **交通大数据可视化分析平台（Go 后端）**。系统可以接收交通流量数据，完成时间窗口聚合与异常检测，并在可视化页面展示趋势、拥堵热力、路口排名和告警记录。
+:::
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="0" :items="[
+      { title: '定场景', description: '先明确数据来源、指标口径和展示目标' },
+      { title: '搭管道', description: '接入、清洗、存储、聚合链路先跑通' },
+      { title: '做分析', description: '完成趋势图、热力图和异常告警' },
+      { title: '交付上线', description: '部署、文档、演示材料补齐' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 为什么这个项目值得做？
+
+这个题目同时练了三种在真实项目里非常关键的能力：
+
+- **工程能力**：Go 接口设计、并发处理、任务调度
+- **数据能力**：时间序列聚合、指标建模、异常检测
+- **产品能力**：把分析结果变成可读、可操作的可视化页面
+
+做完后，你不只是“写了个后端”，而是能说清一个数据产品如何从输入走到决策。
+
+## 1. 项目全景与范围控制
+
+### 系统模块图
+
+```mermaid
+flowchart LR
+  source["数据源<br/>路口设备 / CSV / 模拟器"] --> ingest["Go Ingest API"]
+  ingest --> clean["数据清洗与标准化"]
+  clean --> rawdb["原始数据表"]
+  clean --> agg["聚合任务（1m/5m/1h）"]
+  agg --> aggdb["聚合结果表"]
+  agg --> detect["异常检测任务"]
+  detect --> alertdb["告警表"]
+  aggdb --> dashboard["可视化看板"]
+  alertdb --> dashboard
+```
+
+### 建议分析维度
+
+第一版只聚焦这些核心指标：
+
+- 时间窗口车流量（每分钟 / 每 5 分钟 / 每小时）
+- 路口拥堵指数（可用速度反比或排队长度估算）
+- TOP 拥堵路口排名
+- 异常突增告警（同比前 5 分钟或滑动均值）
+
+### 范围控制（防止项目失控）
+
+- 第一版不做实时流处理平台（如 Kafka/Flink 集群）
+- 第一版不做复杂地图引擎，热力可先用网格或散点替代
+- 第一版不做机器学习预测，先用规则阈值异常检测
+- 第一版不做多租户权限系统，只保留普通用户 + 管理员
+
+## 2. 数据链路与时序
+
+### 数据从接入到看板的主流程
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Device as 数据源
+  participant API as Go API
+  participant DB as PostgreSQL
+  participant Job as 聚合任务
+  participant FE as Dashboard
+
+  Device->>API: POST /api/traffic/events
+  API->>API: 参数校验与标准化
+  API->>DB: 写入 raw_traffic_events
+  Job->>DB: 定时读取原始数据
+  Job->>DB: 写入 traffic_agg_1m / traffic_agg_5m
+  Job->>DB: 写入 alerts
+  FE->>API: GET /api/dashboard/overview
+  API->>DB: 查询聚合结果与告警
+  API-->>FE: 返回图表数据
+```
+
+### 异常检测逻辑（简版）
+
+```mermaid
+flowchart TD
+  A["读取最近 10 分钟聚合值"] --> B["计算近 5 分钟均值"]
+  B --> C["当前值 > 均值 * 阈值?"]
+  C -->|否| D["正常，无告警"]
+  C -->|是| E["生成告警记录"]
+  E --> F["标记级别（低/中/高）"]
+  F --> G["写入 alerts 表"]
+```
+
+## 3. 推荐技术栈
+
+- **后端**：Go + Gin / Fiber
+- **数据处理**：Go `cron` / `robfig/cron`（定时聚合）
+- **数据库**：PostgreSQL（可选 TimescaleDB）
+- **缓存（可选）**：Redis（热点看板数据）
+- **前端**：React / Next.js + ECharts / AntV
+- **部署**：Docker Compose + Zeabur / Railway / 自托管
+
+## 4. 分步实现路径
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="1" :items="[
+      { title: '定场景', description: '先明确数据来源、指标口径和展示目标' },
+      { title: '搭管道', description: '接入、清洗、存储、聚合链路先跑通' },
+      { title: '做分析', description: '完成趋势图、热力图和异常告警' },
+      { title: '交付上线', description: '部署、文档、演示材料补齐' }
+    ]" />
+  </ClientOnly>
+</div>
+
+### 第一步：搭 Go 项目骨架和数据模型
+
+```text
+请帮我创建一个 Go 交通数据分析项目骨架。
+
+要求：
+1. 使用 Gin（或 Fiber）创建 API 服务
+2. 按 handler / service / repository / model 分层
+3. 设计并创建数据表：
+   - raw_traffic_events
+   - traffic_agg_1m
+   - traffic_agg_5m
+   - alerts
+4. 提供一个健康检查接口 /health
+5. 给出本地启动步骤（含数据库连接配置）
+```
+
+### 第二步：完成数据接入接口
+
+先做事件写入：
+
+- `POST /api/traffic/events`
+- 字段至少包含：`intersection_id`、`timestamp`、`vehicle_count`、`avg_speed`
+
+```text
+请帮我实现 POST /api/traffic/events。
+
+要求：
+1. 做参数校验（空值、类型、时间格式）
+2. 标准化 timestamp 到统一时区
+3. 写入 raw_traffic_events
+4. 返回统一 JSON 结构（code、message、data）
+5. 提供一组可直接用于调试的 curl 示例
+```
+
+### 第三步：实现聚合任务
+
+至少完成：
+
+- 1 分钟窗口聚合
+- 5 分钟窗口聚合
+- 聚合结果接口 `GET /api/dashboard/trend`
+
+### 第四步：实现告警规则
+
+建议第一版规则：
+
+- 当前流量 `> 近 5 分钟均值 * 1.8` 触发中级告警
+- 当前平均速度 `< 阈值` 且持续 3 个窗口，触发高级拥堵告警
+
+### 第五步：完成可视化页面
+
+建议页面模块：
+
+- 总览卡片：今日总车流、当前告警数、最拥堵路口
+- 趋势图：近 24 小时车流曲线
+- 路口排行：拥堵指数 TOP10
+- 告警面板：实时/历史告警列表
+
+### 第六步：补齐部署与文档
+
+至少包含：
+
+- 数据口径说明（每个指标如何计算）
+- 接口文档（输入/输出示例）
+- 本地与线上部署步骤
+- 示例数据导入方法
+
+## 5. 可直接使用的接口清单（最小可用）
+
+| 模块 | 接口 |
+|------|------|
+| 数据接入 | `POST /api/traffic/events` |
+| 总览数据 | `GET /api/dashboard/overview` |
+| 趋势数据 | `GET /api/dashboard/trend?range=24h` |
+| 热点路口 | `GET /api/dashboard/intersections/top` |
+| 告警列表 | `GET /api/alerts?level=high&status=open` |
+| 告警处理 | `PATCH /api/alerts/:id/resolve` |
+
+## 6. 交付物要求
+
+- 可运行项目代码（Go API + 可视化前端）
+- 数据库表结构与初始化脚本
+- README（架构图、运行说明、指标解释）
+- 关键页面截图（趋势图、排名、告警）
+- 60 秒到 120 秒演示视频
+
+## 7. 验收标准
+
+| 维度 | 最低达标 | 加分项 |
+|------|------|------|
+| 数据链路 | 接入、存储、聚合、展示完整跑通 | 支持重放历史数据和批量导入 |
+| 分析能力 | 有趋势、排名、告警三个核心模块 | 告警支持分级与处理状态流转 |
+| Go 工程质量 | 代码分层清晰，错误处理明确 | 有结构化日志与基础性能优化 |
+| 可视化质量 | 关键图表可读，指标口径一致 | 增加地图层或交互筛选能力 |
+| 交付完整度 | README、截图、演示视频齐全 | 有线上演示地址和压测说明 |
+
+## 8. 提交前最后检查
+
+<el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
+  <template #header>
+    <div style="font-weight: bold; font-size: 16px;">提交前最后看一眼</div>
+  </template>
+
+  <ul style="list-style-type: none; padding-left: 0;">
+    <li><label><input type="checkbox" disabled /> 数据接入接口可稳定写入原始事件</label></li>
+    <li><label><input type="checkbox" disabled /> 聚合任务能按窗口产出统计结果</label></li>
+    <li><label><input type="checkbox" disabled /> 告警规则生效并可在页面查看</label></li>
+    <li><label><input type="checkbox" disabled /> 看板页面可展示趋势、排名和告警</label></li>
+    <li><label><input type="checkbox" disabled /> README 已写清口径、接口和运行步骤</label></li>
+    <li><label><input type="checkbox" disabled /> 项目已部署或可完整本地复现</label></li>
+  </ul>
+</el-card>
+
+::: tip
+这个作业的关键，不是图表多炫，而是你能不能保证“口径一致、链路闭环、告警可信”。
 :::
@@ -1,7 +1,282 @@
 # 智能旅游规划 Agent 平台

-::: warning 🚧 建设中
+很多人做 AI 项目时，常见问题不是模型不会调，而是应用链路不完整：能聊天，但不能真正“规划一趟旅行”。

-本文档正在编写中，内容可能会有较大变动。请关注更新。
+这个大作业的目标，就是把一个“会说话的 Demo”做成“可执行的产品原型”。

+::: tip 🎯 这次做什么？
+打造一个 **智能旅游规划 Agent 平台**。用户输入出发地、目的地、日期、预算和偏好后，系统自动生成每日行程、预算拆分、景点与餐饮建议，并支持导出或保存计划。管理员可查看热门目的地、生成成功率和用户反馈。
 :::
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="0" :items="[
+      { title: '定范围', description: '先锁定场景、角色和最小功能闭环' },
+      { title: '搭前台', description: '把搜索、行程页、历史页先做出来' },
+      { title: '接智能', description: '把 Agent 编排、外部数据和存储接通' },
+      { title: '交付上线', description: '补齐后台、部署、README 和演示' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 为什么这个题目值得做？
+
+因为它同时覆盖了现代 AI 应用最关键的 4 类能力：
+
+- **结构化输入**：把用户偏好转成可计算参数
+- **Agent 编排**：任务拆解、信息收集、行程生成与校验
+- **真实业务约束**：预算、时长、交通可行性、营业时间
+- **产品化交付**：保存历史、查看详情、导出分享
+
+做完这个项目，你学到的不只是“会调用 LLM”，而是“会做一个可落地的 AI 产品”。
+
+## 先看全景：系统主链路是什么？
+
+```mermaid
+flowchart TD
+  user["用户"] --> form["填写旅行需求"]
+  form --> orchestrator["Agent 编排层"]
+  orchestrator --> planner["行程生成器"]
+  orchestrator --> poi["POI / 景点与餐饮数据"]
+  orchestrator --> weather["天气与交通信息"]
+  planner --> validator["预算与时间校验"]
+  validator --> result["输出每日行程"]
+  result --> db["保存到数据库"]
+  db --> history["历史计划页"]
+  result --> export["导出 PDF / 图片 / 文本"]
+```
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as 用户
+  participant FE as 前端页面
+  participant API as 后端 API
+  participant AG as Agent 服务
+  participant DB as 数据库
+
+  U->>FE: 输入目的地、日期、预算、偏好
+  FE->>API: POST /api/trips/plan
+  API->>AG: 创建规划任务
+  AG->>AG: 拆解子任务并生成草案行程
+  AG-->>API: 返回结构化计划
+  API->>DB: 保存 trip 与 itinerary
+  API-->>FE: 返回计划详情
+  U->>FE: 调整偏好并再次生成
+  FE->>API: POST /api/trips/:id/regenerate
+```
+
+## 1. 定范围：先把题目收住，避免“越做越大”
+
+### 角色设计
+
+| 角色 | 核心动作 |
+|------|------|
+| 普通用户 | 创建旅行计划、查看每日行程、调整偏好、保存与导出 |
+| 管理员 | 查看使用统计、热门城市、失败任务日志、用户反馈 |
+
+### 核心页面
+
+| 页面 | 路径 | 说明 |
+|------|------|------|
+| 首页 | `/` | 介绍产品价值与创建入口 |
+| 规划页 | `/planner` | 填写需求并发起生成 |
+| 行程详情页 | `/trips/:id` | 查看每日计划与预算拆分 |
+| 历史记录页 | `/history` | 查看过去的规划任务 |
+| 管理后台 | `/admin` | 查看统计数据与任务健康状态 |
+
+### 第一版边界（强烈建议）
+
+- 只做单人行程，不做多人协同编辑
+- 只支持 1 个目的地，不做多城市跳转
+- 只做 3-7 天行程，不做超长旅行计划
+- 先使用一种语言输出，不做多语言切换
+- 先接一个外部信息源，避免数据接入过多导致失控
+
+## 2. 搭前台：先把“用户可见闭环”跑通
+
+### 推荐技术栈
+
+- 前端：Next.js / React + TypeScript + Tailwind CSS + 组件库
+- 后端：Node.js (Nest/Express) 或 Spring Boot
+- 数据库：PostgreSQL / Supabase
+- AI：OpenAI / Claude / Gemini 任选其一
+- 可选：Redis（缓存热门目的地与提示词模板）
+
+### 第一步：生成页面骨架
+
+把这段提示词给你的 AI IDE：
+
+```text
+请帮我生成一个“智能旅游规划 Agent 平台”的前端骨架。
+
+技术栈：
+- Next.js App Router
+- TypeScript
+- Tailwind CSS
+
+页面：
+1. 首页 /
+2. 规划页 /planner
+3. 行程详情页 /trips/[id]
+4. 历史记录页 /history
+5. 管理页 /admin
+
+要求：
+- 规划页左侧是需求表单，右侧是计划预览
+- 行程详情按 Day1 / Day2 分段展示
+- 有 loading、空状态、错误提示
+- 移动端可用
+```
+
+### 第二步：补齐规划页交互
+
+```text
+请完善 /planner 页面。
+
+输入字段：
+- 出发地
+- 目的地
+- 出行日期（开始/结束）
+- 总预算
+- 旅行偏好（自然风光/历史文化/亲子/美食）
+- 每日节奏（轻松/标准/高强度）
+
+输出区域：
+- 每日行程卡片
+- 预算拆分
+- 交通建议
+- 注意事项
+
+要求：
+- 点击“生成行程”后显示任务进度
+- 失败时显示可重试按钮
+- 首屏有示例数据引导
+```
+
+<div style="margin: 32px 0;">
+  <ClientOnly>
+    <StepBar :active="1" :items="[
+      { title: '定范围', description: '先锁定场景、角色和最小功能闭环' },
+      { title: '搭前台', description: '把搜索、行程页、历史页先做出来' },
+      { title: '接智能', description: '把 Agent 编排、外部数据和存储接通' },
+      { title: '交付上线', description: '补齐后台、部署、README 和演示' }
+    ]" />
+  </ClientOnly>
+</div>
+
+## 3. 接智能：让 Agent 真正参与业务
+
+### 数据模型建议
+
+```sql
+users (
+  id uuid primary key,
+  email text,
+  role text, -- user / admin
+  created_at timestamptz
+)
+
+trip_plans (
+  id uuid primary key,
+  user_id uuid,
+  origin text,
+  destination text,
+  start_date date,
+  end_date date,
+  budget numeric,
+  preferences jsonb,
+  status text, -- pending / success / failed
+  created_at timestamptz
+)
+
+itinerary_days (
+  id uuid primary key,
+  trip_plan_id uuid,
+  day_index int,
+  title text,
+  activities jsonb,
+  day_budget numeric
+)
+
+generation_logs (
+  id uuid primary key,
+  trip_plan_id uuid,
+  model_name text,
+  prompt_snapshot text,
+  latency_ms int,
+  status text,
+  created_at timestamptz
+)
+```
+
+### 第三步：实现规划接口
+
+```text
+请帮我实现 /api/trips/plan 接口。
+
+目标：
+1. 接收用户输入（目的地、日期、预算、偏好）
+2. 调用 LLM 生成结构化 JSON 行程
+3. 校验 JSON 字段完整性
+4. 保存到 trip_plans 和 itinerary_days 表
+5. 返回给前端展示
+
+要求：
+- 明确 DTO 和校验规则
+- 返回统一错误码
+- 记录模型调用耗时与失败日志
+```
+
+### 第四步：实现再生成与优化
+
+```text
+请帮我实现“微调行程”接口 /api/trips/:id/regenerate。
+
+用户可输入：
+- “预算再低 20%”
+- “减少步行”
+- “多加亲子场景”
+
+要求：
+- 保留旧版本行程
+- 生成新版本并对比差异
+- 前端支持一键切换版本
+```
+
+## 4. 上线与交付
+
+### 交付物
+
+- 完整项目仓库（前后端或单体）
+- 可访问演示链接
+- README（安装、配置、启动、部署、排障）
+- 60 秒左右演示视频
+- 至少 4 张截图：首页、规划页、结果页、管理页
+
+### 验收标准
+
+| 维度 | 最低达标 | 加分项 |
+|------|------|------|
+| 功能闭环 | 可创建计划、查看结果、保存历史 | 可做二次优化并保留版本 |
+| 智能质量 | 输出结构化、基本可执行 | 有预算校验和冲突提示 |
+| 工程质量 | 接口清晰、错误可追踪 | 有缓存与性能优化 |
+| 产品体验 | loading/空态/错误态完整 | 支持导出分享 |
+| 运维交付 | 可部署、文档可复现 | 有后台统计看板 |
+
+## 提交前最后检查
+
+<el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
+  <template #header>
+    <div style="font-weight: bold; font-size: 16px;">提交前最后看一眼</div>
+  </template>
+
+  <ul style="list-style-type: none; padding-left: 0;">
+    <li><label><input type="checkbox" disabled /> 用户可以创建并成功生成一份行程</label></li>
+    <li><label><input type="checkbox" disabled /> 行程结果按天展示且可读</label></li>
+    <li><label><input type="checkbox" disabled /> 生成记录已写入数据库并可回看</label></li>
+    <li><label><input type="checkbox" disabled /> 接口失败时有可理解错误提示</label></li>
+    <li><label><input type="checkbox" disabled /> 管理后台可查看基础统计</label></li>
+    <li><label><input type="checkbox" disabled /> 项目可部署且 README 可复现</label></li>
+  </ul>
+</el-card>
@@ -90,7 +90,34 @@

 ### 大作业

-通过实战项目巩固你的全栈开发技能：
+前面的章节是在学“零件”，大作业才是在学“怎么把零件装成一个能跑、能演示、能上线的产品”。
+
+建议你按 **大作业 1 -> 大作业 2** 的顺序来做：
+
+- **大作业 1** 先带你跑通现代 SaaS 最常见的主链路：登录、生成、数据库、支付、管理后台。
+- **大作业 2** 再带你进入更像业务系统的场景：角色权限、题库、考试、提交记录、管理台。
+
+```mermaid
+flowchart LR
+  A["前端页面与组件"] --> B["数据库与接口"]
+  B --> C["大作业 1<br/>文案生成 SaaS"]
+  C --> D["支付 / 部署 / 后台管理"]
+  D --> E["大作业 2<br/>在线考试系统"]
+  E --> F["完整全栈作品集"]
+```
+
+如果你不知道先做哪个，可以直接参考下面这张对比表：
+
+| 项目 | 你会重点练到什么 | 最适合谁 | 最终交付物 |
+|------|------|------|------|
+| 大作业 1：文案生成网站 | SaaS 页面结构、用户登录、AI 生成、Stripe 支付、后台管理 | 第一次做完整商业化网站的人 | 一个可注册、可生成、可付费、可管理的 SaaS 雏形 |
+| 大作业 2：在线考试与管理系统 | 角色权限、题库建模、考试流程、提交记录、批改与统计 | 想把“业务系统”真正做完整的人 | 一个有学生端和管理端的考试平台 |
+
+无论做哪一个，大作业都建议至少准备这 3 个交付物：
+
+- 一个可运行的项目仓库
+- 一个可访问的演示链接
+- 一份 README 和一段演示视频

 <NavGrid>
  <NavCard
@@ -105,6 +132,41 @@
  />
 </NavGrid>

+如果你已经完成了上面两个主线项目，或者想按自己的技术方向做作品集，可以继续从下面这些扩展选题里选一题深入：
+
+<NavGrid>
+  <NavCard
+    href="/zh-cn/stage-2/assignments/modern-landing-page/"
+    title="扩展作业：现代网页落地页"
+    description="练习价值表达、转化路径、CTA 设计与基础埋点，做一个真正能承接流量的页面"
+  />
+  <NavCard
+    href="/zh-cn/stage-2/assignments/custom-dify-agent-platform/"
+    title="扩展作业：自制 Dify 智能体平台"
+    description="实现智能体管理、对话、日志与权限控制，做一个最小可用的 AI 平台"
+  />
+  <NavCard
+    href="/zh-cn/stage-2/assignments/travel-planning-agent-platform/"
+    title="扩展作业：智能旅游规划 Agent 平台"
+    description="围绕结构化输入、Agent 编排和历史计划管理，做一个可执行的 AI 旅行规划产品"
+  />
+  <NavCard
+    href="/zh-cn/stage-2/assignments/movie-recommendation-springboot/"
+    title="扩展作业：电影推荐网（Spring Boot）"
+    description="结合 Spring Boot、评分收藏与可解释推荐，完成一个完整推荐系统原型"
+  />
+  <NavCard
+    href="/zh-cn/stage-2/assignments/simple-grocery-microservices/"
+    title="扩展作业：简单买菜微服务网站"
+    description="练习服务拆分、网关转发、库存与订单协作，体验从单体到微服务的工程思路"
+  />
+  <NavCard
+    href="/zh-cn/stage-2/assignments/traffic-data-visualization-go/"
+    title="扩展作业：交通大数据可视化分析（Go）"
+    description="从数据接入、窗口聚合到趋势看板与告警，做一个完整的数据产品原型"
+  />
+</NavGrid>
+
 ### AI 能力扩展

 <NavGrid>