diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 0bb552e..20eec8f 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -1499,12 +1499,12 @@ Sitemap: ${siteUrl}/sitemap.xml link: '/zh-cn/stage-2/frontend/2.5-hogwarts-portraits/' }, { - text: '构建第一个现代应用程序 - 全栈应用', - link: '/zh-cn/stage-2/assignments/2.1-fullstack-app/' + text: '大作业 1：第一个 SaaS 全栈应用——文案生成网站', + link: '/zh-cn/stage-2/assignments/copywriting-platform-supabase/' }, { - text: '现代前端组件库 + Trae 实战', - link: '/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/' + text: '大作业 2：在线考试与管理系统', + link: '/zh-cn/stage-2/assignments/exam-management-express/' } ] } diff --git a/docs/zh-cn/stage-2/assignments/2.1-fullstack-app/index.md b/docs/zh-cn/stage-2/assignments/2.1-fullstack-app/index.md deleted file mode 100644 index ff64f11..0000000 --- a/docs/zh-cn/stage-2/assignments/2.1-fullstack-app/index.md +++ /dev/null @@ -1,207 +0,0 @@ -# 构建第一个现代应用程序：全栈应用 - -::: tip 目标 -将一个原型想法变成一个小而完整的 Web 应用，具备真正的前端、后端逻辑、持久化数据和公开部署链接。 -::: - -此时，目标不再只是"让页面看起来正确"。目标是让核心产品循环真正运作起来：用户打开应用，做一些有意义的事情，触发后端逻辑，存储或读取数据，并在下次回来时结果仍然存在。 - -你不需要构建一个巨大的平台。一个范围清晰、流程完整的小产品，比一个充满未完成功能的大项目要好得多。 - -这个作业旨在连接第二阶段的学习路径： - -- [UI 设计](../../frontend/2.2-ui-design/) -- [从设计原型到项目代码](../../frontend/2.6-design-to-code/) -- [现代组件库](../../frontend/2.7-modern-component-library/) -- [从数据库到 Supabase](../../backend/2.2-database-supabase/) -- [使用 LLM 编写 API 代码](../../backend/2.3-ai-interface-code/) -- [Git 和 GitHub 工作流](../../backend/2.4-git-workflow/) -- [如何部署 Web 应用](../../backend/2.5-zeabur-deployment/) - -## 1. 作业目标 - -构建一个**可工作、可演示、可公开访问**的全栈 Web 应用。 - -你的项目应该具备： - -1. **清晰的用户和使用场景** - - 你应该能够解释产品是为谁服务的，解决什么问题。 -2. **完整的产品循环** - - 关键操作必须超越前端模拟数据，触发真正的后端或数据库行为。 -3. **真正的工程交付** - - 代码应该存放在仓库中，密钥应该正确处理，其他人应该能够理解项目如何运作。 - -好的项目方向包括： - -- 将第一阶段的原型升级为真正的应用 -- 将[霍格沃茨画像](../../frontend/2.5-hogwarts-portraits/)扩展为更完整的产品 -- 构建一个小型 AI 工具，如写作工具、摘要器或研究工作区 -- 构建一个轻量级垂直工具，如 CRM、排程工具或学习助手 - -## 2. 最低要求 - -| 领域 | 最低要求 | 备注 | -| --- | --- | --- | -| 产品范围 | 一个清晰的核心工作流 | 例如：创建并保存内容、上传并处理输入、创建角色并聊天 | -| 前端 | 至少 2 个页面，或 1 个复杂主页面加 1 个辅助页面 | 需要支持桌面端 | -| 状态 | 处理加载、空和错误状态 | 不要只构建快乐路径 | -| 数据 | 至少 1 个核心表，理想情况下 2 个相关实体 | 例如：`users` + `projects`，`characters` + `messages` | -| 后端 | 至少 3 个真正的 API 端点或等效的服务器端能力 | Express、Next.js 路由处理器或边缘函数都可以接受 | -| 持久化 | 核心用户操作必须可保存和检索 | 不仅仅是模拟数据 | -| 交付 | GitHub 仓库和公开在线链接 | 推荐使用 Vercel 或 Zeabur | -| 文档 | 可读的 `README.md` | 包括目的、技术栈、设置和环境变量 | - -## 3. 推荐技术栈 - -你可以使用任何合理的技术栈，但如果你想要最稳妥的路径，这个组合效果很好： - -| 层 | 推荐选项 | -| --- | --- | -| 前端 | React / Next.js 或 Vue | -| 组件库 | shadcn/ui、Ant Design、HeroUI 或 Element Plus | -| 数据和认证 | Supabase | -| 后端 | Next.js 路由处理器、Express 或 Supabase Edge Functions | -| 部署 | Vercel 或 Zeabur | - -对于第一个全栈项目，"前端 + Supabase + 少量服务器逻辑"通常是成功提交的最快方式。 - -## 4. 建议工作流程 - -### 4.1 用一句话写出核心任务 - -在编码之前，回答： - -> 用户在这个应用中应该能够做的最重要的一件事是什么？ - -例如： - -- 上传文本，生成摘要，并保存到历史记录 -- 创建角色档案并继续与它聊天 -- 添加客户线索并稍后查看其状态 - -如果这句话仍然模糊，范围可能太宽了。 - -### 4.2 先规划结构 - -草拟： - -- 你需要哪些页面 -- 每个页面上最重要的模块 -- 哪些操作读取数据 -- 哪些操作写入数据 - -这将使 AI 辅助实现更加稳定。 - -### 4.3 从模拟数据开始 - -一个实用的顺序是： - -1. 用模拟数据构建前端结构 -2. 连接真正的后端逻辑 -3. 用真正的持久化替换模拟数据 - -这样可以大大减少调试范围。 - -### 4.4 AI IDE 起始提示词 - -```text -帮我构建一个可部署的全栈 Web 应用，用于[你的使用场景]。 - -不要一次生成所有内容。首先将项目分解为： -1. 页面结构和路由 -2. 数据模型设计 -3. API 或服务器端能力设计 -4. 前端组件拆分 -5. 环境变量和部署设置 - -要求： -- 使用 [React/Next.js/Vue + 你的组件库 + Supabase/Express] -- 优先考虑可工作的 MVP，而不是过度工程化 -- 告诉我要创建哪些文件 -- 包括加载、空、错误和验证状态 -``` - -## 5. 交付物 - -请提交： - -1. **GitHub 仓库链接** -2. **公开在线链接** -3. **`README.md`** - - 项目名称和一句话描述 - - 目标用户和使用场景 - - 技术栈 - - 主要功能 - - 本地设置步骤 - - 环境变量说明 -4. **简短的演示素材** - - 理想情况下是 60 到 90 秒的视频，或几张关键截图/GIF - -有用的可选补充： - -- 数据库模式或 ER 图 -- API 说明或端点列表 -- 设计/架构解释 -- 简短的迭代日志 - -## 6. 评估清单 - -如果你的项目满足以下条件，那就很好了： - -- 用户可以完成真正的端到端流程 -- 关键操作在系统中产生可见的变化 -- 刷新后数据仍然存在 -- 后端故障不会导致 UI 崩溃 -- 你可以在大约一分钟内清楚地解释产品 - -## 7. 进阶想法 - -你可以通过以下方式更进一步： - -- 认证和多用户支持 -- 真正的 AI 能力，包括流式传输或重试 -- 使用现代组件库提高 UI 质量 -- 监控、日志或分析 -- 基本测试 -- 支付或订阅流程 -- 移动端适配 - -## 8. 常见错误 - -### 8.1 范围太大 - -如果你的第一个版本需要同时具备认证、管理工具、支付、工作流构建器、知识库和多用户协作，那么项目可能太大了。 - -### 8.2 前端看起来不错，但什么都不是真的 - -这可能仍然是一个有用的前端练习，但不是一个强有力的全栈作业。这个项目应该包括真正的持久化和服务器端行为。 - -### 8.3 密钥被提交到仓库 - -API 密钥和数据库密钥应该放在环境变量中，而不是前端源代码中。 - -### 8.4 只测试快乐路径 - -手动测试： - -- 空输入 -- 重复操作 -- 网络故障 -- 缺失数据 -- 权限错误 - -这是最有用的产品修复通常出现的地方。 - -## 9. 最后的建议 - -把这个作业当作你第一次真正的产品交付练习，而不是功能数量竞赛。 - -最重要的不是你使用了多少工具，而是你是否能够： - -- 定义清晰的产品目标 -- 使用 AI 工具从想法到实现 -- 交付一个其他人可以理解、尝试和重现的东西 - -::: tip 下一步 -完成这个作业后，继续[作业 2：现代前端组件库 + Trae 实战](../2.2-modern-frontend-trae/)，将界面质量推向更高水平。 -::: diff --git a/docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/index.md b/docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/index.md deleted file mode 100644 index e120e0e..0000000 --- a/docs/zh-cn/stage-2/assignments/2.2-modern-frontend-trae/index.md +++ /dev/null @@ -1,282 +0,0 @@ -# 作业 2：现代前端组件库 + Trae 实战 - -::: tip 目标 -使用 Trae 或其他 AI IDE 结合现代组件库，构建一个感觉像真正产品而不是课堂演示的前端。 -::: - -上一个作业关注全栈完整性。这个作业关注前端质量：结构、一致性、交互、响应式和迭代。 - -许多第一次前端项目可以"工作"但仍然感觉未完成： - -- 布局可用，但视觉不一致 -- 按钮、表单、抽屉和表格感觉不像一个系统 -- 桌面版本可以接受，但窄屏幕会崩溃 -- AI 可以快速生成第一版，但结果仍然看起来很通用 - -这个作业就是要突破第一稿。 - -建议复习章节： - -- [从设计原型到项目代码](../../frontend/2.6-design-to-code/) -- [使用现代组件库升级你的界面](../../frontend/2.7-modern-component-library/) -- [用 LLM 和技能让界面变美](../../frontend/2.4-llm-skills-beautiful/) -- [参考 UI 设计规范和多产品 UI 设计](../../frontend/2.3-multi-product-ui/) - -## 1. 作业目标 - -构建一个前端项目，具备： - -- 清晰的使用场景 -- 结构化的布局 -- 一致的设计语言 -- 真正的交互模式 -- 组织成可复用组件的代码 - -可能的项目类型： - -- 落地页 -- 登录后的产品工作区 -- 仪表盘或管理界面 -- AI 工具界面 -- 多模块内容管理页面 - -## 2. 必备工具 - -你应该使用： - -- **Trae** 或其他 AI 编码 IDE -- **至少一个现代组件库** - -例如： - -- React：`shadcn/ui`、`Ant Design`、`HeroUI`、`Material UI` -- Vue：`Element Plus`、`Naive UI`、`Ant Design Vue` - -重要的部分不仅仅是命名一个库。该库应该有意义地改善项目的结构和精致度。 - -## 3. 最低要求 - -| 领域 | 最低要求 | 备注 | -| --- | --- | --- | -| 页面范围 | 至少 2 个页面，或 1 个复杂主页面加 1 个辅助页面 | 例如：仪表盘 + 详情页 | -| 组件库 | 至少使用 1 个真正的组件库 | 它应该出现在实际实现中 | -| 组件拆分 | 至少 5 个可复用组件或清晰分离的模块 | 导航、过滤器、表格区域、模态框、摘要卡片等 | -| 交互 | 至少 3 种交互类型 | 表单验证、模态框/抽屉、标签页、菜单、过滤器、分页、图表切换等 | -| 状态 | 至少包含以下 3 种：加载、空、错误、成功反馈 | 对产品真实性很重要 | -| 响应式 | 桌面就绪，有合理的窄屏幕处理 | 完整移动端支持是加分项 | -| 数据 | 真正的 API 或结构化的模拟数据 | 即使是模拟数据也应该组织良好 | -| 交付 | 仓库链接 + 公开部署 | 推荐 GitHub + Vercel/Zeabur | - -## 4. 建议的项目方向 - -### 4.1 产品落地页 - -适合练习视觉层次和展示。 - -建议的部分： - -- 英雄区 -- 功能卡片 -- 工作流程 -- 用户评价 -- 定价 -- 常见问题 -- 页脚 - -好的库选项：`HeroUI`、`Material UI` - -### 4.2 AI 工具工作区 - -适合布局、状态设计和交互。 - -建议的部分： - -- 侧边栏 -- 顶部工具栏 -- 输入区域 -- 结果区域 -- 历史面板 -- 设置模态框 - -好的库选项：`shadcn/ui`、`Element Plus` - -### 4.3 仪表盘 / 管理界面 - -适合密集信息布局和组件组合。 - -建议的部分： - -- 摘要卡片 -- 图表 -- 过滤器 -- 数据表格 -- 详情抽屉或模态框 -- 分页和状态标签 - -好的库选项：`Ant Design`、`Element Plus` - -## 5. 建议工作流程 - -### 5.1 先决定三件事 - -在打开 Trae 之前，写下： - -1. 你在构建什么样的产品 -2. 为什么选择这个组件库 -3. 页面上哪 3 个模块最重要 - -这种清晰度会让 AI 生成的输出好得多。 - -### 5.2 生成第一个结构版本 - -在第一轮中，关注布局、组件结构、数据形状和核心交互，而不是视觉完美。 - -示例提示词： - -```text -帮我使用 [组件库] 构建一个 [产品类型] 的前端项目。 - -第一版关注： -1. 页面结构 -2. 组件拆分 -3. 模拟数据结构 -4. 核心交互 -5. 响应式布局基础 - -请将代码拆分为合理的页面和组件文件。 -``` - -### 5.3 后续轮次用于润色 - -第一版工作后，迭代： - -- 间距和布局节奏 -- 视觉层次 -- 按钮优先级 -- 悬停/聚焦/禁用状态 -- 状态颜色、图标和标签 -- 窄屏幕适配 - -这通常是项目开始感觉像真正产品的地方。 - -### 5.4 添加缺失的产品细节 - -不要跳过： - -- 提交时的加载按钮 -- 空状态消息 -- 失败请求的回退 UI -- 保存/删除/导出流程的确认和反馈 -- 密集布局中的滚动和溢出行为 - -这些细节通常会创造最大的质量飞跃。 - -## 6. 起始提示词模板 - -```text -帮我使用 [组件库] 构建 [项目名称] 的前端界面。 -风格应该感觉 [现代 / 专业 / 轻量 / 消费级 / 企业级]。 - -目标用户： -- [谁使用这个] - -页面目标： -- [这个页面上最重要的任务] - -布局： -- 左侧：... -- 顶部区域：... -- 主要内容：... -- 右侧/底部：... - -交互要求： -- 包括以下几种：模态框、抽屉、过滤器、表单验证、图表、分页 -- 包括加载、空和错误状态 -- 桌面优先，有窄屏幕处理 - -实现要求： -- 清晰的组件拆分 -- 模拟数据放在单独的文件或模块中 -- 不要生成一个巨大的页面文件 -- 先构建结构，然后迭代改进视觉效果 -``` - -## 7. 交付物 - -请提交： - -1. **GitHub 仓库链接** -2. **公开在线链接** -3. **`README.md`** - - 页面或产品是什么 - - 你使用了哪个组件库以及为什么 - - 包含的主要模块 - - 如何在本地运行 -4. **截图或简短演示** - - 至少展示主桌面视图 - - 如果你处理了响应式，也包括窄屏幕视图 - -有用的可选补充： - -- 第一稿和最终结果之间的前后对比 -- 帮助你最多的提示词 -- 一个你特别自豪的 UI 细节 - -## 8. 评估清单 - -如果你的项目满足以下条件，那就很强： - -- 第一个屏幕清楚地传达了产品是什么 -- 即使页面包含很多信息，布局也感觉有组织 -- 控件在整个页面中感觉一致 -- 代码被分解成可理解的部分 -- 交互感觉有意为之，而不是装饰性的 -- 结果感觉像一个产品，而不是截图拼贴 - -## 9. 进阶想法 - -你可以通过以下方式更进一步： - -- 真正的 API 集成 -- 主题令牌或深色/浅色主题切换 -- 可复用的布局原语 -- 图表、骨架加载器或更丰富的数据状态 -- 无障碍改进，如聚焦状态和语义结构 -- 简短的设计理念 - -## 10. 常见错误 - -### 10.1 只关注"看起来更好" - -现代前端质量不仅仅是视觉。它还包括清晰度、可用性、状态处理和结构。 - -### 10.2 过于接近默认组件库示例 - -组件库是基础，而不是产品的最终身份。 - -### 10.3 一次生成所有内容 - -复杂界面通常分阶段构建更好： - -1. 结构 -2. 模块 -3. 润色 -4. 细节 - -## 11. 最后的建议 - -不要把 AI 当作一次性页面生成器。把它当作协作前端伙伴。 - -最有用的模式通常是： - -- 你定义方向 -- AI 创建第一版 -- 你批评结果 -- AI 优化它 -- 你继续做产品决策 - -这就是如何从"一个存在的页面"到"一个值得发布的前端"。 - -::: tip 下一步 -如果这个作业进展顺利，重新访问[全栈作业](../2.1-fullstack-app/)，用你在这里构建的前端质量升级那个产品。 -::: diff --git a/docs/zh-cn/stage-2/index.md b/docs/zh-cn/stage-2/index.md index 2b7f398..932ab84 100644 --- a/docs/zh-cn/stage-2/index.md +++ b/docs/zh-cn/stage-2/index.md @@ -94,14 +94,14 @@