diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index e3e0eb2..5540f3b 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -1528,35 +1528,35 @@ Sitemap: ${siteUrl}/sitemap.xml link: '/zh-cn/stage-2/frontend/2.5-hogwarts-portraits/' }, { - text: '大作业 1：第一个 SaaS 全栈应用——文案生成网站', + text: '大作业 1：AI 营销文案 SaaS 开发实战', link: '/zh-cn/stage-2/assignments/copywriting-platform-supabase/' }, { - text: '大作业 2：在线考试与管理系统', + text: '大作业 2：在线考试与管理系统开发实战', link: '/zh-cn/stage-2/assignments/exam-management-express/' }, { - text: '扩展作业：现代网页落地页', + text: '扩展作业：现代 AI 生图 SaaS 开发实战', link: '/zh-cn/stage-2/assignments/modern-landing-page/' }, { - text: '扩展作业：自制 Dify 智能体平台', + text: '扩展作业：类 Dify 智能体平台开发实战', link: '/zh-cn/stage-2/assignments/custom-dify-agent-platform/' }, { - text: '扩展作业：智能旅游规划 Agent 平台', + text: '扩展作业：智能旅游规划 Agent 平台开发实战', link: '/zh-cn/stage-2/assignments/travel-planning-agent-platform/' }, { - text: '扩展作业：电影推荐网（Spring Boot）', + text: '扩展作业：Spring Boot 电影推荐系统开发实战', link: '/zh-cn/stage-2/assignments/movie-recommendation-springboot/' }, { - text: '扩展作业：简单买菜微服务网站', + text: '扩展作业：生鲜电商微服务系统开发实战', link: '/zh-cn/stage-2/assignments/simple-grocery-microservices/' }, { - text: '扩展作业：交通大数据可视化分析（Go）', + text: '扩展作业：Go 交通数据分析平台开发实战', link: '/zh-cn/stage-2/assignments/traffic-data-visualization-go/' } ] diff --git a/docs/public/sitemap.xml b/docs/public/sitemap.xml index b2ba6f2..ed1f46a 100644 --- a/docs/public/sitemap.xml +++ b/docs/public/sitemap.xml @@ -938,58 +938,114 @@ + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/copywriting-platform-supabase/PRD/ + 2026-03-31T04:14:27.746Z + weekly + 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/copywriting-platform-supabase/ - 2026-03-26T11:20:31+08:00 + 2026-03-29T19:37:03+08:00 weekly 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/custom-dify-agent-platform/PRD/ + 2026-03-31T04:14:27.747Z + weekly + 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/custom-dify-agent-platform/ - 2026-03-26T11:20:31+08:00 + 2026-03-29T19:37:03+08:00 weekly 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/exam-management-express/PRD/ + 2026-03-31T04:14:27.748Z + weekly + 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/exam-management-express/ - 2026-03-26T11:20:31+08:00 + 2026-03-29T19:37:03+08:00 weekly 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/modern-landing-page/PRD/ + 2026-03-30T09:59:56.848Z + weekly + 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/modern-landing-page/ - 2026-03-26T11:20:31+08:00 + 2026-03-29T19:37:03+08:00 weekly 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/movie-recommendation-springboot/PRD/ + 2026-03-31T04:15:20.951Z + weekly + 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/movie-recommendation-springboot/ - 2026-03-26T11:20:31+08:00 + 2026-03-29T19:37:03+08:00 weekly 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/simple-grocery-microservices/PRD/ + 2026-03-31T04:15:20.951Z + weekly + 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/simple-grocery-microservices/ - 2026-03-26T11:20:31+08:00 + 2026-03-29T19:37:03+08:00 weekly 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/traffic-data-visualization-go/PRD/ + 2026-03-31T04:15:20.951Z + weekly + 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/traffic-data-visualization-go/ - 2026-03-26T11:20:31+08:00 + 2026-03-29T19:37:03+08:00 weekly 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/travel-planning-agent-platform/PRD/ + 2026-03-31T04:15:20.950Z + weekly + 0.8 + + https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/assignments/travel-planning-agent-platform/ - 2026-03-26T11:20:31+08:00 + 2026-03-29T19:37:03+08:00 weekly 0.8 @@ -1108,7 +1164,7 @@ https://datawhalechina.github.io/easy-vibe/zh-cn/stage-2/ - 2026-03-29T15:16:07+08:00 + 2026-03-29T19:37:03+08:00 weekly 0.8 diff --git a/docs/zh-cn/stage-2/assignments/copywriting-platform-supabase/PRD.md b/docs/zh-cn/stage-2/assignments/copywriting-platform-supabase/PRD.md new file mode 100644 index 0000000..246e23a --- /dev/null +++ b/docs/zh-cn/stage-2/assignments/copywriting-platform-supabase/PRD.md @@ -0,0 +1,361 @@ +# PRD：AI 营销文案 SaaS 平台 + +状态：Draft v0.1 +目标：先明确产品边界、页面结构、数据模型与支付闭环，再进入开发。 + +## 1. 项目定位 + +这是一个面向独立开发者、小团队和内容运营者的 AI 营销文案 SaaS。它不是单次调用模型的 Demo，而是一套带登录、生成、历史、套餐、后台管理的完整产品。 + +一句话定义： +做一个支持注册登录、文案生成、历史管理、套餐付费和后台运营的 AI 营销文案工作台。 + +系统总览： + +```mermaid +flowchart LR + WWW["www.xxx.com
官网前台"] --> API["应用 API / 管理 API"] + APP["app.xxx.com
用户工作台"] --> API + ADMIN["admin.xxx.com
后台管理台"] --> API + API --> AUTH["Supabase Auth"] + API --> DB["Supabase Postgres"] + API --> PAY["Stripe"] + API --> LLM["第三方大模型 API"] +``` + +## 1.1 技术选型建议 + +- 前端框架：`Next.js App Router` +- 用户鉴权：`Supabase Auth` +- 数据库：`Supabase Postgres` +- 支付：`Stripe` +- AI 能力：统一后端适配层对接第三方大模型 API + +站点入口约定： + +- 官网前台：`www.xxx.com` +- 用户工作台：`app.xxx.com` +- 后台管理台：`admin.xxx.com` + +## 1.2 竞品参考（官方） + +- [Jasper](https://www.jasper.ai/) +- [Copy.ai](https://www.copy.ai/) + +## 1.3 产品借鉴点 + +本项目的产品设计建议参考这些真实产品的做法： + +- 借鉴 `Jasper` 的官网表达方式：强调营销团队场景、价值主张、平台能力和 CTA 转化 +- 借鉴 `Jasper` 的工作台思路：让“生成”不是一个孤立按钮，而是一个带上下文和多种产出类型的工作空间 +- 借鉴 `Copy.ai` 的产品形态：把不同输出场景拆成清晰工作流，而不是把所有功能堆在一个输入框里 +- 因此本项目的首页、工作台、套餐页和后台运营页，都应该更像一个真实营销 SaaS，而不是单页工具 + +## 1.4 竞品页面拆解 + +建议重点参考的竞品页面结构： + +- `Jasper` 官网首页 + - 重点看：Hero、品牌价值表达、工作流/Agent 介绍、演示 CTA、企业化信任背书 +- `Jasper` 的 Agent / Workflow 类页面 + - 重点看：不是单纯展示一个文本框，而是强调“场景 -> 输入上下文 -> 输出结果”的完整工作流 +- `Copy.ai` 的 Workflow / GTM 类页面 + - 重点看：不同营销任务如何拆成不同工作区和模板入口 + +因此本项目建议页面设计不是“一个输入框 + 一个结果框”，而是： + +- 首页负责转化 +- 工作台负责结构化输入与输出管理 +- 历史页负责内容复用 +- 套餐页负责商业化 +- 后台负责运营视角 + +## 2. 目标用户与核心目标 + +目标用户： + +- 想快速生成营销文案的独立开发者 +- 需要批量产出广告、落地页、社媒文案的小团队 +- 管理套餐、用户和生成记录的管理员 + +核心目标： + +- 用户能在 5 分钟内注册并完成第一次文案生成 +- 用户能查看历史生成结果并二次编辑 +- 产品能完成从生成到支付升级的基本闭环 + +## 3. MVP 范围 + +第一版必须包含： + +- 官网首页 +- 注册/登录 +- 文案生成工作台 +- 历史记录页 +- 套餐页 +- 支付/订阅能力 +- 后台查看用户、生成记录和支付数据 + +第一版不做： + +- 团队协作 +- 多语言翻译链路 +- 复杂工作流编排 +- 模板市场 + +## 4. 角色与权限 + +| 角色 | 权限 | +|------|------| +| 游客 | 浏览官网、注册登录 | +| 注册用户 | 生成文案、查看历史、管理套餐 | +| 管理员 | 查看用户、生成数据、支付和运营数据 | + +## 5. 页面架构 + +当前 PRD 定义为 `3 套入口，10 个大页面`： + +- 官网前台 `1` 个大页面 +- 用户工作台 `5` 个大页面 +- 后台管理台 `4` 个大页面 + +### 官网前台 + +#### 1. 官网首页 `www:/` + +核心功能： + +- Hero 与 CTA +- 场景介绍 +- 输出示例 +- 套餐预览 +- FAQ + +### 用户工作台 + +#### 2. 登录页 `app:/login` + +核心功能： + +- 邮箱密码登录 +- 第三方登录 +- 跳转注册 + +#### 3. 注册页 `app:/register` + +核心功能： + +- 新用户注册 +- 同意条款 +- 注册完成跳转工作台 + +#### 4. 生成工作台 `app:/generate` + +核心功能： + +- 输入产品信息、受众、渠道、卖点 +- 选择输出类型和语气 +- 发起生成 +- 查看生成结果 +- 保存和再次编辑 + +#### 5. 历史记录页 `app:/history` + +核心功能： + +- 查看历史文案 +- 按时间/类型筛选 +- 再次打开、复制、删除 + +#### 6. 套餐页 `app:/billing` + +核心功能： + +- 查看 Free / Pro / Team 套餐 +- 月付/年付切换 +- 发起支付 +- 查看当前套餐权益 + +### 后台管理台 + +#### 7. 后台首页 `admin:/` + +核心功能： + +- 用户总数 +- 生成次数 +- 付费收入 +- 转化概览 + +#### 8. 用户管理 `admin:/users` + +核心功能： + +- 查看用户列表 +- 查看套餐状态 +- 查看最近活跃 +- 封禁/恢复 + +#### 9. 生成记录 `admin:/generations` + +核心功能： + +- 查看生成内容与次数 +- 查看失败记录 +- 查看高频模板和渠道分布 + +#### 10. 支付与订阅 `admin:/billing` + +核心功能： + +- 查看支付订单 +- 查看订阅状态 +- 查看退款与失败订单 + +## 5.1 关键用户链路 + +```mermaid +flowchart TD + visitor["访客"] --> home["官网首页"] + home --> register["注册 / 登录"] + register --> workspace["文案工作台"] + workspace --> generate["提交生成任务"] + generate --> result["查看生成结果"] + result --> history["保存到历史记录"] + workspace --> billing["升级套餐"] + billing --> pay["Stripe 支付"] + pay --> plan["套餐状态更新"] + plan --> workspace + plan --> admin["后台查看用户/生成/支付数据"] +``` + +关键状态流： + +- 游客 -> 注册用户 +- 免费用户 -> 付费用户 +- 生成中 -> 生成成功 / 生成失败 +- 订单处理中 -> 支付成功 / 支付失败 + +## 6. 后端实现 + +后端模块： + +- `auth` +- `generation` +- `history` +- `billing` +- `analytics` +- `admin` + +建议数据表： + +```sql +profiles ( + id uuid primary key, + email text, + role text, + plan text, + created_at timestamptz +) + +generation_records ( + id uuid primary key, + user_id uuid, + input_payload jsonb, + output_payload jsonb, + channel text, + tone text, + status text, + created_at timestamptz +) + +billing_records ( + id uuid primary key, + user_id uuid, + plan_code text, + billing_cycle text, + amount_cents int, + status text, + created_at timestamptz +) +``` + +## 6.1 后台指标与监控 + +后台建议至少查看这些指标： + +- 新增注册用户数 +- 日活跃生成用户数 +- 文案生成总次数 +- 生成成功率 / 失败率 +- 套餐转化率 +- 付费收入与退款率 +- 高峰时段生成请求量 + +基础监控建议： + +- 模型调用成功率 +- 接口平均耗时 +- 支付回调成功率 +- 数据库连接与慢查询 +- 关键任务错误日志 + +## 7. 功能清单 + +必须完成： + +- 官网价值展示 +- 注册/登录 +- 结构化文案输入 +- 文案生成结果展示 +- 历史记录管理 +- 套餐与支付 +- 后台用户与生成数据查看 + +可选增强： + +- 文案模板库 +- 不同语气/渠道预设 +- 结果二次编辑 +- 复制和导出 +- 团队共享工作区 + +## 8. 接口草案 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/auth/register` | 注册 | +| `POST` | `/api/auth/login` | 登录 | +| `POST` | `/api/generations` | 创建文案生成任务 | +| `GET` | `/api/generations/:id` | 获取生成结果 | +| `GET` | `/api/history` | 获取历史记录 | +| `DELETE` | `/api/history/:id` | 删除历史记录 | +| `GET` | `/api/billing/plans` | 获取套餐 | +| `POST` | `/api/billing/checkout` | 创建支付会话 | +| `GET` | `/api/admin/overview` | 获取后台总览 | +| `GET` | `/api/admin/users` | 获取用户列表 | +| `GET` | `/api/admin/generations` | 获取生成记录列表 | + +## 9. 非功能要求 + +- 生成过程要有清晰加载和失败反馈 +- 用户历史记录只能自己可见 +- 支付状态和套餐状态要一致 +- 后台能按日查看生成量和付费数据 +- 首页和工作台都需要移动端可用 + +## 10. 开发顺序建议 + +1. 搭官网和登录注册页 +2. 实现生成工作台 +3. 接入鉴权和数据库 +4. 接入模型生成接口 +5. 实现历史记录 +6. 接入支付与套餐 +7. 实现后台运营页 + +## 11. 待确认项 + +- 是否默认只做单次生成，不做批量生成 +- 支付是先做月付，还是月付和年付都做 +- 是否需要在第一版加入模板库 diff --git a/docs/zh-cn/stage-2/assignments/copywriting-platform-supabase/index.md b/docs/zh-cn/stage-2/assignments/copywriting-platform-supabase/index.md index e56d0e9..e277426 100644 --- a/docs/zh-cn/stage-2/assignments/copywriting-platform-supabase/index.md +++ b/docs/zh-cn/stage-2/assignments/copywriting-platform-supabase/index.md @@ -1,222 +1,158 @@ -# 大作业 1：第一个 SaaS 全栈应用——文案生成网站 +# AI 营销文案 SaaS 开发实战 -第一次做全栈网站，最容易卡住的地方往往不是代码，而是**不知道该做什么**。 +这个项目不再只是“写一个生成按钮”，而是围绕一份真实 PRD，把一个 AI 营销文案 SaaS 从想法推进到可上线产品。 -题目太大，功能太散，做到一半发现根本收不住。 +你会同时看到三件事： -所以这次换个思路：不给开放题，直接给你一个明确的方向——做一件完整但不复杂的事。 +- 项目要做成什么 +- 如何基于 PRD 拆解并推进开发 +- 最后应该交付出什么样的效果 -::: tip 🎯 这次做什么？ -打造一个 **AI 营销文案工作台**。用户登录后填写产品信息，一键生成营销文案，自动保存历史记录。需要更多生成次数？升级套餐即可。管理员可在后台查看所有用户、生成记录和支付情况。 +::: tip PRD 入口 +本项目的需求文档在同级页面： [查看 PRD](./PRD.md) :::
-## 先看全景：你最终要做出来的不是“一个页面”，而是一条完整业务链路 +## 这个项目到底在做什么？ -很多人第一次做全栈项目，最容易犯的错不是不会写代码，而是只盯着某一个页面，结果首页挺好看，后端没接上；生成按钮能点，历史记录没保存；支付能跳转，但数据库根本没更新。 +这是一个面向独立开发者和内容团队的 AI 营销文案 SaaS： -这个项目真正要交付的，是下面这条完整链路： +- 官网前台：负责产品介绍、定价、FAQ、注册转化 +- 用户工作台：负责输入产品信息、生成文案、查看历史、升级套餐 +- 后台管理台：负责用户、生成记录、支付数据和运营概览 + +后端需要接住这些关键能力： + +- 用户鉴权 +- 文案生成任务 +- 历史记录持久化 +- Stripe 支付 +- 后台用户和生成数据管理 + +## 开发过程怎么走？ + +### 1. 先看 PRD，不要上来就写代码 + +先确认： + +- 有几个入口：`www / app / admin` +- 页面清单是否完整 +- 后端模块和数据表是否合理 +- 套餐、支付和后台范围是否收住 + +如果 PRD 没拍板，就先不要写代码。 + +### 2. 先让 AI 生成“骨架版” + +第一轮目标不是做完整闭环，而是先生成： + +- 官网首页 +- 登录注册 +- 文案生成工作台 +- 历史记录页 +- 套餐页 +- 后台首页与管理页骨架 + +这一步要先把页面结构、路由和信息架构搭出来。 + +### 3. 再进入“监工模式” + +你需要重点盯这几件事： + +- 页面结构是不是和 PRD 一致 +- 登录态和匿名态有没有分清 +- 生成结果有没有稳定落库 +- 支付之后套餐状态有没有更新 +- 后台是不是能看到真实用户、生成和支付数据 + +可以把 AI 当执行者，但你自己要做项目经理和验收人。 + +### 4. 最后做联调和上线 ```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["查看用户 / 生成记录 / 支付状态"] + prd["PRD"] --> web["官网前台"] + prd --> app["用户工作台"] + prd --> admin["后台管理台"] + app --> auth["鉴权"] + app --> gen["文案生成任务"] + gen --> db["数据库"] + billing["支付与套餐"] --> db + admin --> analytics["用户 / 生成 / 支付看板"] ``` -只要上面这张图能跑通，你做的就不是课堂 Demo，而是一个真正像产品的最小 SaaS。 +只要这条链路能跑通，这个项目就不是单点 Demo，而是一个完整 SaaS 原型。 -## 为什么选这个题目？ +## 怎么让 AI 帮你生成？ -因为它恰到好处——**涵盖了现代网站该有的所有要素，又不会复杂到失控**。 - -- **前台有实际用途**：不是摆设，用户真的来解决问题 -- **用户系统有登录权限**：区分访客与注册用户 -- **核心功能是"生成"**：调用 AI 动态产出内容，而非展示静态页面 -- **数据持久化**：生成结果存入数据库，随时可查 -- **付费机制**：看起来像正经 SaaS，而非玩具项目 -- **管理后台**：体验管理员视角，掌控全局 - -难度适中：不会简单到只有一个表单，也不会复杂到做一周还找不着北。 - -### 先锁定项目边界，别一上来就做“大而全” - -为了让你真的能按时做完，这个项目建议你先只做 **最小可用版本**： - -- 只做 **邮箱注册 / 登录**，先不要接第三方 OAuth -- 支付只做 **免费版 + Pro 版** 两档，先不要做优惠券、年付月付切换 -- AI 生成功能只做 **单次文案生成**，先不要做批量任务队列 -- 管理后台先做 **查看**，暂时不要求复杂运营操作 -- 权限只区分 **user / admin** 两种角色 - -你会发现，真正难的不是“还能不能继续加功能”，而是“能不能先把主流程稳定交付”。 - -## 1. 定主题：先搞清楚要做什么 - -网站名称：**LaunchKit** - -定位：AI 营销文案工作台 - -目标用户：独立开发者、小商家、内容运营者，以及想快速搞定 Landing Page 的人。 - -他们来这里不是为了闲聊——就是想**快速拿到能用的营销文案**。 - -### 核心功能 - -别想太复杂，核心就一件事： - -**用户输入**：产品名、一句话介绍、目标用户、3 个卖点、投放渠道 - -**系统输出**：主标题、副标题、CTA 按钮文案、3 版短文案、1 版长文案 - -生成结果自动存入账户，下次登录随时查看。 - -### 页面规划 - -按这 6 个页面来做： - -| 页面 | 路径 | 说明 | -|------|------|------| -| 首页 | `/` | 清晰传达产品价值，放置注册/登录入口 | -| 登录页 | `/login` | 简洁的登录表单 | -| 注册页 | `/register` | 简洁的注册表单 | -| 工作台 | `/dashboard` | 填写信息、生成文案、查看结果 | -| 套餐页 | `/billing` | 展示免费版与 Pro 版，跳转 Stripe 付款 | -| 管理后台 | `/admin` | 管理员查看用户、生成记录、支付状态 | - -### 数据模型 - -三张核心表足够： - -```sql -profiles ( - id uuid primary key, - email text, - role text, -- user / admin - plan text, -- free / pro - created_at timestamptz -) - -generations ( - id uuid primary key, - user_id uuid, - product_name text, - target_channel text, - input_payload jsonb, - result_payload jsonb, - created_at timestamptz -) - -subscriptions ( - id uuid primary key, - user_id uuid, - stripe_customer_id text, - stripe_subscription_id text, - plan text, - status text, - created_at timestamptz -) -``` - -到这一步，整个网站的骨架已经清晰。 - -### 推荐开发顺序 - -不要按“想到什么做什么”，而要按依赖关系推进： - -```mermaid -flowchart LR - A["首页 / 登录 / Dashboard 骨架"] --> B["Supabase Auth"] - B --> C["profiles / generations / subscriptions"] - C --> D["生成接口 + 历史记录"] - D --> E["Stripe 支付 + 套餐限制"] - E --> F["Admin 后台"] - F --> G["部署 / README / 演示视频"] -``` - -这个顺序的好处是：每一步都能看到阶段性成果，也更容易排查问题。 - -
- - - -
- -## 2. 搭前台：先把页面做出来 - -这一步先别碰数据库，也别急着接支付——**先把前台骨架搭起来**。 - -### 技术栈 - -- **Next.js App Router** —— 现代 React 框架 -- **TypeScript** —— 类型安全 -- **Tailwind CSS** —— 原子化样式 -- **shadcn/ui** —— 精致组件库 -- **Supabase** —— 后端服务 -- **Stripe** —— 支付处理 - -这套组合是目前 AI IDE 最擅长的技术栈，也最符合现代 SaaS 的审美。 - -### 第一步：搭建项目骨架 - -把下面这段提示词丢给 Trae / Cursor / Claude Code： +推荐按模块逐步下指令，而不是一句“帮我做完”。 ```text -请帮我创建一个现代 SaaS 网站，名字叫 LaunchKit。 - -技术栈要求： -- Next.js App Router -- TypeScript -- Tailwind CSS -- shadcn/ui - -页面清单： -1. 首页 / -2. 登录页 /login -3. 注册页 /register -4. 用户工作台 /dashboard -5. 套餐页 /billing -6. 管理后台 /admin - -请先只做前端结构，不接数据库。 +请基于当前 PRD，帮我生成一个 AI 营销文案 SaaS 的前端骨架。 要求： -- 首页要有现代 AI SaaS 落地页的气质 -- 登录和注册页保持简洁 -- Dashboard 左侧表单，右侧结果展示 -- Billing 页面展示 free 和 pro 两个套餐 -- Admin 页面先做后台框架：侧边栏、顶部栏、表格区域 -- 使用 shadcn/ui 组件 -- 页面风格要像真实产品，不要像课堂 demo +1. 分成三个入口：www、app、admin +2. 官网包括：首页、定价、FAQ +3. app 包括：登录、注册、生成工作台、历史记录、套餐页 +4. admin 包括：后台首页、用户管理、生成记录、支付订单 +5. 先只生成页面结构和假数据，不接真实接口 +6. 风格要像现代 SaaS，不像课堂 demo ``` -### 第二步：完善工作台细节 +然后再一块一块补： + +- 鉴权 +- 生成接口 +- 数据库 +- 支付 +- 后台管理 + +## 怎么“监工”才有效？ + +每做完一个模块，至少检查这 5 件事： + +| 检查项 | 要看什么 | +|------|------| +| 页面是否对 | 页面数量、入口、功能是否符合 PRD | +| 接口是否对 | 输入参数、返回结构、状态处理是否合理 | +| 权限是否对 | 游客、用户、管理员是否隔离 | +| 数据是否对 | 生成、历史、支付和套餐状态是否一致 | +| 演示是否对 | 是否真的能完整跑通注册、生成、升级这条链路 | + +## 最后的预期效果 + +做完后，你应该拿到这些交付物： + +- 一套可运行的 AI 文案 SaaS 项目 +- 一份同级 PRD 文档 +- 三套入口：`www / app / admin` +- 基础鉴权、生成、历史、支付、后台管理 +- 一份 README +- 一个可以演示的线上版本或本地完整运行方案 + +## 验收标准 + +| 维度 | 最低达标 | +|------|------| +| PRD 对齐 | 页面、功能、数据结构基本符合 PRD | +| 产品闭环 | 注册、生成、历史、支付升级可以跑通 | +| 后台能力 | 用户、生成、支付数据可以查看 | +| 工程完整度 | 前端、后端、数据库、支付链路已接通 | +| 展示能力 | 可以清楚演示“从 PRD 到成品”的过程 | + +::: tip 🚀 完成后你会得到什么？ +你得到的不只是一个生成页面，而是一套完整的 AI SaaS 开发过程样例。后面再做别的产品型项目，也可以继续沿用这套“先 PRD、再生成、再监工、再联调上线”的方法。 +::: 第一版页面完成后，继续补充： diff --git a/docs/zh-cn/stage-2/assignments/custom-dify-agent-platform/PRD.md b/docs/zh-cn/stage-2/assignments/custom-dify-agent-platform/PRD.md new file mode 100644 index 0000000..6073d47 --- /dev/null +++ b/docs/zh-cn/stage-2/assignments/custom-dify-agent-platform/PRD.md @@ -0,0 +1,442 @@ +# PRD：类 Dify 智能体编排平台 + +状态：Draft v0.1 +目标：先把平台的 MVP 产品定义和实现边界写清楚，待 review 后再开发。 + +## 1. 项目定位 + +这是一个模仿 Dify 核心体验的精简版智能体平台，重点不是复刻全部能力，而是跑通下面这条主链路： + +- 创建智能体 +- 配置 Prompt 与模型参数 +- 发起对话 +- 查看调用日志 +- 可选接入知识库 + +一句话定义： +做一个类 Dify 的最小可用智能体编排平台。 + +系统总览： + +```mermaid +flowchart LR + WWW["www.xxx.com
官网前台"] --> API["应用 API / 管理 API"] + APP["app.xxx.com
用户控制台"] --> API + ADMIN["admin.xxx.com
后台管理台"] --> API + API --> AUTH["Supabase Auth"] + API --> DB["Supabase Postgres"] + API --> LLM["LLM Provider"] + API --> KB["知识库 / 文档处理"] +``` + +## 1.0 技术选型建议 + +- 前端框架：`Next.js App Router` +- 用户鉴权：`Supabase Auth` +- 数据库：`Supabase Postgres` +- 文件存储：`Supabase Storage` +- 模型层：统一后端适配层对接第三方 LLM + +站点入口约定： + +- 官网前台：`www.xxx.com` +- 用户控制台：`app.xxx.com` +- 后台管理台：`admin.xxx.com` + +## 1.1 竞品参考（官方） + +- [Dify](https://dify.ai/) +- [Dify Docs](https://docs.dify.ai/) + +## 1.2 产品借鉴点 + +本项目的产品设计建议参考 Dify 的真实产品形态： + +- 智能体管理、知识库、对话、日志应该是清晰分区，而不是混在一个页面里 +- 配置页应该突出 Prompt、模型、参数和发布状态，而不是只给一个表单 +- 对话页应该强调“当前正在使用哪个 agent”和“当前会话属于哪个 agent” +- 日志页应该能快速定位失败调用、耗时、token 消耗和错误原因 +- 整体设计应更像 AI 平台控制台，而不是普通聊天网站 + +## 1.3 竞品页面拆解 + +建议重点参考的竞品页面结构： + +- `Dify` 控制台首页 + - 重点看：应用列表、创建入口、最近活动、平台感导航 +- `Dify` 应用配置页 + - 重点看：Prompt、模型、参数、发布状态的组织方式 +- `Dify` 知识库页 + - 重点看：文档上传、状态、处理结果的管理方式 +- `Dify` 调试 / 预览页 + - 重点看：左侧配置、右侧运行结果的双栏思路 + +因此本项目的页面建议应更像平台控制台： + +- 智能体列表页像应用市场/应用管理 +- 配置页像控制台配置中心 +- 对话页像调试与预览台 +- 日志页像开发者运维页 + +## 2. 目标用户与核心目标 + +目标用户： + +- 想快速配置并测试多个智能体的开发者 +- 想搭建内部知识助手的学生或独立开发者 +- 需要查看模型调用记录的管理员 + +核心目标： + +- 用户 5 分钟内创建第一个智能体 +- 用户能在同一个平台里完成配置与对话 +- 平台可以追踪每次调用的输入、输出、耗时与状态 + +## 3. MVP 范围 + +第一版必须包含： + +- 注册/登录 +- 智能体 CRUD +- 对话页 +- 会话历史 +- 调用日志页 +- 可选知识库：仅支持文本文件上传与基础检索 + +第一版不做： + +- 复杂工作流节点编排 UI +- 多租户企业权限体系 +- 工具调用沙箱 +- 支付与计费 +- 多模型路由策略 + +## 4. 角色与权限 + +| 角色 | 权限 | +|------|------| +| 普通用户 | 管理自己的智能体、发起对话、看自己的日志 | +| 管理员 | 查看全平台用户和调用概览 | + +## 5. 前端实现 + +## 5.1 页面架构总览 + +当前 PRD 定义为 `3 套入口，10 个大页面`： + +- 官网前台 `1` 个大页面 +- 用户控制台 `7` 个大页面 +- 后台管理台 `2` 个大页面 + +### A. 官网前台 `www.xxx.com` + +#### 1. 官网首页 `www:/` + +核心功能： + +- 产品介绍 +- 能力说明 +- 使用场景 +- 注册/登录 CTA + +### B. 用户控制台 `app.xxx.com` + +#### 2. 登录页 `app:/login` + +核心功能： + +- 登录 +- 注册入口 +- 第三方登录 + +#### 3. 智能体列表页 `app:/agents` + +核心功能： + +- 查看所有智能体 +- 新建智能体 +- 编辑入口 +- 状态筛选 + +#### 4. 智能体配置页 `app:/agents/:id` + +核心功能： + +- 配置名称和描述 +- 配置 Prompt、模型、参数 +- 启停和发布状态 + +#### 5. 对话页 `app:/chat` + +核心功能： + +- 选择智能体 +- 新建会话 +- 聊天消息展示 +- 问答发送与结果展示 + +#### 6. 会话详情页 `app:/chat/:id` + +核心功能： + +- 查看完整消息历史 +- 重命名会话 +- 继续提问 + +#### 7. 知识库页 `app:/knowledge` + +核心功能： + +- 上传文档 +- 查看处理状态 +- 关联到智能体 + +#### 8. 日志页 `app:/logs` + +核心功能： + +- 查看调用日志 +- 按状态/模型筛选 +- 查看错误详情 + +### C. 后台管理台 `admin.xxx.com` + +#### 9. 后台首页 `admin:/` + +核心功能： + +- 用户数 +- 调用次数 +- 失败率 +- 平台资源概览 + +#### 10. 用户与调用概览页 `admin:/usage` + +核心功能： + +- 查看用户使用情况 +- 查看模型调用消耗 +- 查看异常用户和高成本调用 + +## 5.2 关键用户链路 + +```mermaid +flowchart TD + user["用户"] --> login["登录"] + login --> agents["智能体列表页"] + agents --> config["配置智能体"] + config --> publish["保存配置"] + publish --> chat["对话页"] + chat --> logs["调用日志页"] + config --> kb["知识库页"] + kb --> chat + logs --> admin["后台调用概览"] +``` + +关键状态流： + +- 智能体：草稿 -> 已配置 -> 可用 / 停用 +- 会话：新建 -> 进行中 -> 归档 +- 文档：上传中 -> 处理中 -> 可检索 / 失败 +- 调用：成功 / 错误 / 超时 + +推荐技术栈： + +- Next.js App Router +- TypeScript +- Tailwind CSS +- shadcn/ui + +建议页面： + +| 页面 | 路径 | 说明 | +|------|------|------| +| 登录页 | `/login` | 登录与注册 | +| 智能体列表 | `/agents` | 查看和管理智能体 | +| 智能体配置页 | `/agents/:id` | 编辑名称、Prompt、模型、温度等 | +| 对话页 | `/chat` | 左侧会话列表，右侧消息区 | +| 知识库页 | `/knowledge` | 上传资料、查看文档状态 | +| 日志页 | `/logs` | 查看模型调用日志 | +| 管理后台 | `/admin` | 用户数、调用数、失败数概览 | + +前端核心组件： + +- 智能体卡片列表 +- Agent 配置表单 +- 对话消息列表 +- Prompt 调试面板 +- 日志筛选表格 +- 文件上传组件 + +## 6. 后端实现 + +推荐技术栈： + +- Node.js + NestJS 或 Express +- PostgreSQL / Supabase +- OpenAI 兼容接口 + +后端模块： + +- `auth` +- `agents` +- `chat` +- `knowledge` +- `logs` +- `admin` + +建议数据表： + +```sql +profiles ( + id uuid primary key, + email text, + role text, + created_at timestamptz +) + +agents ( + id uuid primary key, + user_id uuid, + name text, + description text, + system_prompt text, + model text, + temperature numeric, + status text, + created_at timestamptz +) + +chat_sessions ( + id uuid primary key, + user_id uuid, + agent_id uuid, + title text, + created_at timestamptz +) + +chat_messages ( + id uuid primary key, + session_id uuid, + role text, + content text, + token_usage int, + created_at timestamptz +) + +knowledge_documents ( + id uuid primary key, + user_id uuid, + agent_id uuid, + filename text, + status text, + chunk_count int, + created_at timestamptz +) + +run_logs ( + id uuid primary key, + user_id uuid, + agent_id uuid, + session_id uuid, + model text, + latency_ms int, + prompt_tokens int, + completion_tokens int, + status text, + error_message text, + created_at timestamptz +) +``` + +## 6.1 后台指标与监控 + +后台建议至少查看这些指标： + +- 智能体总数 +- 活跃用户数 +- 日调用次数 +- 平均响应耗时 +- 模型调用失败率 +- 知识库文档处理成功率 +- 高消耗用户与高成本智能体 + +基础监控建议： + +- `/api/chat` 平均耗时与错误率 +- 模型供应商调用成功率 +- 知识库文档处理队列状态 +- 数据库连接和日志写入健康状态 + +## 7. 功能清单 + +必须完成： + +- 用户鉴权 +- 创建/编辑/删除智能体 +- 选择智能体发起会话 +- 会话消息持久化 +- 调用日志记录 + +第二优先级： + +- 文档上传 +- 基础检索增强 +- 平台概览统计 + +## 8. 接口草案 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/auth/register` | 注册 | +| `POST` | `/api/auth/login` | 登录 | +| `GET` | `/api/agents` | 获取当前用户的智能体列表 | +| `POST` | `/api/agents` | 创建智能体 | +| `PATCH` | `/api/agents/:id` | 更新智能体配置 | +| `DELETE` | `/api/agents/:id` | 删除智能体 | +| `POST` | `/api/chat/sessions` | 创建新会话 | +| `POST` | `/api/chat/sessions/:id/messages` | 向某个会话发送消息 | +| `GET` | `/api/chat/sessions/:id/messages` | 获取会话消息 | +| `POST` | `/api/knowledge/documents` | 上传知识库文档 | +| `GET` | `/api/logs` | 获取调用日志 | +| `GET` | `/api/admin/overview` | 平台总览 | + +`POST /api/chat/sessions/:id/messages` 请求示例： + +```json +{ + "agentId": "agent_123", + "message": "帮我总结一下这个功能的定位" +} +``` + +## 9. 关键业务规则 + +- 用户只能访问自己的智能体和会话 +- 删除智能体前需要检查是否有活跃会话 +- 日志中必须记录失败原因 +- 知识库文档处理失败要可见 + +## 10. 非功能要求 + +- 用户只能访问自己的智能体、文档和会话 +- 调用日志需要可追踪、可筛选 +- 文档处理状态要有明确反馈 +- 对话页在移动端至少可查看 +- 智能体配置修改后要有变更提示 + +## 11. 开发顺序建议 + +1. 登录与基础鉴权 +2. 智能体 CRUD +3. 对话页和会话存储 +4. 日志记录 +5. 文档上传与基础检索 +6. 管理后台概览 + +## 12. 待确认项 + +- 第一版是否必须带知识库 +- 模型供应商先只接 1 家还是预留多家 +- 平台是否需要 Workspace 概念 +- 日志是否保留完整 prompt 快照 diff --git a/docs/zh-cn/stage-2/assignments/custom-dify-agent-platform/index.md b/docs/zh-cn/stage-2/assignments/custom-dify-agent-platform/index.md index 751b10e..90c57b7 100644 --- a/docs/zh-cn/stage-2/assignments/custom-dify-agent-platform/index.md +++ b/docs/zh-cn/stage-2/assignments/custom-dify-agent-platform/index.md @@ -1,223 +1,128 @@ -# 自制 Dify 智能体平台 +# 类 Dify 智能体平台开发实战 -如果你已经会用 Dify，下一步最值得挑战的不是“再配一个工作流”，而是自己做一个“类 Dify 平台”。 +这个项目不是“再配一个聊天页”，而是围绕一份真实 PRD，把一个类 Dify 智能体平台从想法推进到可上线产品。 -这个大作业会带你完成一个简化但完整的智能体平台：支持创建智能体、配置 Prompt、接知识库、发起对话、查看日志和调用统计。 +你会同时看到三件事： -::: tip 🎯 这次做什么？ -打造一个 **最小可用的智能体平台（Mini Dify）**。平台至少包含：智能体管理、会话问答、知识库接入（可选第一版简化）、调用记录与基础权限控制。目标是让用户能“创建一个智能体并真实对话”。 +- 项目要做成什么 +- 如何基于 PRD 拆解并推进开发 +- 最后应该交付出什么样的效果 + +::: tip PRD 入口 +本项目的需求文档在同级页面： [查看 PRD](./PRD.md) :::
-## 为什么这个题目值得做？ +## 这个项目到底在做什么？ -因为它几乎覆盖了 AI 应用工程化的核心能力： +这是一个模仿 Dify 核心体验的智能体平台： -- 从“调用一个模型”升级到“管理多个智能体” -- 从“单页 Demo”升级到“有后台、有数据、有权限的平台” -- 从“能回答”升级到“可配置、可追踪、可维护” +- 用户控制台：创建智能体、配置 Prompt、发起对话、查看日志 +- 平台后端：管理智能体、会话、消息、知识库和模型调用 +- 管理后台：查看用户和平台资源使用情况 -如果你未来想做 Agent 产品、企业知识助手或 AI SaaS，这个项目会是非常有含金量的一次训练。 +## 开发过程怎么走？ -## 先看全景：平台核心模块 +### 1. 先看 PRD，不要上来就写代码 + +先确认： + +- 智能体、会话、日志、知识库哪些要进 MVP +- 页面和路由清单是否拍板 +- 模型调用和日志记录边界是否清楚 +- 多租户和复杂工作流是不是先不做 + +### 2. 先让 AI 生成“骨架版” + +第一轮先生成： + +- 登录页 +- 智能体列表页 +- 智能体配置页 +- 对话页 +- 日志页 +- 知识库页 +- 管理后台首页 + +### 3. 再进入“监工模式” + +你要重点盯这几件事： + +- 智能体是不是能被正确创建和编辑 +- 对话是不是使用了正确的 agent 配置 +- 会话和消息有没有稳定落库 +- 日志是不是记录了耗时、token、错误 +- 知识库和模型调用有没有串权限 + +### 4. 最后做联调和上线 ```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["日志/成本统计"] +flowchart TD + prd["PRD"] --> app["用户控制台"] + prd --> admin["管理后台"] + app --> auth["鉴权"] + app --> agent["智能体配置"] + app --> chat["会话对话"] + chat --> llm["模型调用"] + chat --> db["数据库"] + app --> kb["知识库接入"] + admin --> logs["调用日志与平台概览"] + logs --> db ``` -核心目标只有一个：用户能在后台创建智能体，然后在对话页选择该智能体并得到可追踪的回答。 - -## 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 先搭骨架 +## 怎么让 AI 帮你生成？ ```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 +请基于当前 PRD，帮我生成一个类 Dify 智能体平台的前端骨架。 要求： -- 说明每步修改了哪些文件 -- 明确需要在数据库后台操作的 SQL -- 完成后给我一份验证清单 +1. 用户侧包括：登录、智能体列表、智能体配置、对话页、日志页、知识库页 +2. 后台侧包括：后台首页、用户概览、资源使用概览 +3. 先只生成页面结构和假数据，不接真实接口 +4. 风格要像现代 AI 平台 ``` -## 3. 接智能体主链路：从“创建”到“回答” +## 怎么“监工”才有效？ -### 智能体调用时序图 +| 检查项 | 要看什么 | +|------|------| +| 页面是否对 | 页面数量、功能是否符合 PRD | +| 接口是否对 | agents、chat、logs、knowledge 是否闭环 | +| 权限是否对 | 用户是否只能管理自己的 agent 和会话 | +| 数据是否对 | messages、logs、documents 是否一致 | +| 演示是否对 | 是否能演示“创建 agent -> 对话 -> 查看日志”完整链路 | -```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: 渲染回复 -``` +- 一套可运行的类 Dify 平台 +- 一份同级 PRD 文档 +- 用户侧控制台 + 管理后台 +- 智能体、对话、日志、知识库基础能力 +- README 和演示方案 -### 第三步：实现聊天接口（最小版本） +## 验收标准 -第一版聊天接口建议做到： +| 维度 | 最低达标 | +|------|------| +| PRD 对齐 | 页面、功能、数据结构基本符合 PRD | +| 产品闭环 | 创建 agent、发起对话、查看日志可以跑通 | +| 后台能力 | 用户与平台使用概览可查看 | +| 工程完整度 | 前端、后端、数据库、模型调用链路已接通 | +| 展示能力 | 可以清楚演示“从 PRD 到成品”的过程 | -- 接收 `agentId` 和用户输入 -- 根据 `agentId` 加载对应系统提示词 -- 调用模型并返回结果 -- 将问答落库到 `messages` -- 将耗时/状态写入 `llm_logs` - -提示词示例： - -```text -请帮我实现 /api/chat 接口。 - -业务规则： -1. 必须校验用户是否已登录 -2. 必须校验 agent 属于当前用户 -3. 请求体包含 agentId 和 message +::: tip 🚀 完成后你会得到什么？ +你得到的不只是一个聊天页，而是一套 AI 平台型产品的开发样例。后面做知识助手、企业 Agent、AI 控制台时，都可以继续复用这套方法。 +::: 4. 调用 LLM 前拼接系统提示词和最近 10 条上下文 5. 返回 assistant 内容并写入消息表 6. 无论成功失败都写一条 llm_logs diff --git a/docs/zh-cn/stage-2/assignments/exam-management-express/PRD.md b/docs/zh-cn/stage-2/assignments/exam-management-express/PRD.md new file mode 100644 index 0000000..41a987d --- /dev/null +++ b/docs/zh-cn/stage-2/assignments/exam-management-express/PRD.md @@ -0,0 +1,356 @@ +# PRD：在线考试与管理系统 + +状态：Draft v0.1 +目标：先明确角色、考试链路、后台管理和核心数据模型，再进入开发。 + +## 1. 项目定位 + +这是一个典型的多角色业务系统。它不只是答题页面，而是一整套包含学生端、管理端、题库、考试、提交记录和成绩处理的产品。 + +一句话定义： +做一个支持学生答题、管理员出卷、题库维护、成绩统计和后台管理的在线考试系统。 + +系统总览： + +```mermaid +flowchart LR + HOME["www.xxx.com
官网前台"] --> API["应用 API / 管理 API"] + STUDENT["app.xxx.com
学生端"] --> API + ADMIN["admin.xxx.com
管理后台"] --> API + API --> AUTH["JWT / Session Auth"] + API --> DB["PostgreSQL"] +``` + +## 1.1 技术选型建议 + +- 前端框架：`Next.js` 或 `React + Vite` +- 后端框架：`Node.js + Express` +- 数据库：`PostgreSQL` +- 鉴权：`JWT + Role-based Access Control` + +站点入口约定： + +- 官网前台：`www.xxx.com` +- 学生端：`app.xxx.com` +- 管理后台：`admin.xxx.com` + +## 1.2 竞品参考（官方） + +- [Canvas by Instructure](https://www.instructure.com/canvas) +- [Moodle LMS](https://moodle.com/products/lms/) + +## 1.3 产品借鉴点 + +本项目的产品设计建议参考这些真实教学产品： + +- 借鉴 `Canvas` 的信息分层：学生端和管理端职责清晰，不把所有功能放在同一个视图 +- 借鉴 `Moodle` 的题库与考试管理思路：题目、考试、提交、成绩应是独立模块 +- 学生侧页面应强调“考试状态、剩余时间、提交反馈” +- 管理端页面应强调“题库维护、考试发布、提交记录、统计面板” +- 设计上应更像真实 LMS/考试平台，而不是单一答题表单 + +## 1.4 竞品页面拆解 + +建议重点参考的竞品页面结构： + +- `Canvas` 的课程/作业/测验组织方式 + - 重点看：学生如何看到待完成事项、任务状态和结果反馈 +- `Moodle` 的题库与测验页 + - 重点看：题目、测验、提交记录这些模块如何拆开 +- `Moodle` 的后台管理体验 + - 重点看：题库管理、测验配置、成绩查看如何层次化呈现 + +因此本项目建议页面遵循： + +- 学生端强调“流程感” +- 管理端强调“配置感” +- 成绩页强调“结果感” +- 后台首页强调“概览感” + +## 2. 目标用户与核心目标 + +目标用户： + +- 参加考试和查看成绩的学生 +- 维护考试、题目、成绩和统计的管理员 + +核心目标： + +- 学生能顺利完成考试流程 +- 管理员能完成题库、考试和提交记录管理 +- 系统能稳定保存提交结果和成绩统计 + +## 3. MVP 范围 + +第一版必须包含： + +- 登录 +- 学生考试列表 +- 学生答题页 +- 提交结果与历史成绩 +- 管理后台 +- 题库管理 +- 考试管理 +- 提交记录与成绩查看 + +第一版不做： + +- 随机组卷 +- 复杂防作弊 +- 多校区多租户 +- 监考视频 + +## 4. 角色与权限 + +| 角色 | 权限 | +|------|------| +| 学生 | 查看考试、开始答题、提交试卷、查看成绩 | +| 管理员 | 管理题库、考试、提交记录和成绩统计 | + +## 5. 页面架构 + +当前 PRD 定义为 `3 套入口，10 个大页面`： + +- 官网前台 `1` 个大页面 +- 学生端 `4` 个大页面 +- 管理后台 `5` 个大页面 + +### 官网前台 + +#### 1. 官网首页 `www:/` + +核心功能： + +- 平台介绍 +- 登录入口 +- 考试说明 + +### 学生端 + +#### 2. 登录页 `app:/login` + +核心功能： + +- 账号密码登录 +- 找回密码入口 + +#### 3. 考试列表页 `app:/student/exams` + +核心功能： + +- 查看可参加考试 +- 查看考试状态与时间 +- 进入考试 + +#### 4. 答题页 `app:/student/exams/:id` + +核心功能： + +- 展示题目 +- 作答 +- 倒计时 +- 提交试卷 + +#### 5. 历史成绩页 `app:/student/history` + +核心功能： + +- 查看历史考试 +- 查看成绩与状态 +- 查看待复核情况 + +### 管理后台 + +#### 6. 后台首页 `admin:/` + +核心功能： + +- 考试总数 +- 学生提交数 +- 待批改数 +- 成绩概览 + +#### 7. 题库管理 `admin:/questions` + +核心功能： + +- 新增题目 +- 编辑题目 +- 分类筛选 +- 批量导入 + +#### 8. 考试管理 `admin:/exams` + +核心功能： + +- 创建考试 +- 绑定题目 +- 设置开始时间和时长 +- 发布/关闭考试 + +#### 9. 提交记录 `admin:/submissions` + +核心功能： + +- 查看学生提交 +- 查看答案详情 +- 人工复核 + +#### 10. 成绩统计 `admin:/scores` + +核心功能： + +- 查看考试平均分 +- 查看通过率 +- 查看题目错误率 + +## 5.1 关键用户链路 + +```mermaid +flowchart TD + student["学生"] --> login["登录"] + login --> list["考试列表"] + list --> start["开始考试"] + start --> answer["答题页"] + answer --> submit["提交试卷"] + submit --> score["成绩结果 / 待复核"] + admin["管理员"] --> bank["题库管理"] + bank --> exam["考试管理"] + exam --> publish["发布考试"] + publish --> list + submit --> review["提交记录"] + review --> scoreAdmin["成绩统计"] +``` + +关键状态流： + +- 考试：草稿 -> 已发布 -> 已关闭 +- 提交：进行中 -> 已提交 -> 已评阅 / 待复核 +- 学生成绩：未出分 -> 已出分 + +## 6. 后端实现 + +后端模块： + +- `auth` +- `exams` +- `questions` +- `submissions` +- `scores` +- `admin` + +建议数据表： + +```sql +profiles ( + id uuid primary key, + email text, + role text, + created_at timestamptz +) + +exams ( + id uuid primary key, + title text, + description text, + duration_minutes int, + status text, + created_at timestamptz +) + +questions ( + id uuid primary key, + type text, + stem text, + options jsonb, + correct_answer text, + score int, + created_at timestamptz +) + +submissions ( + id uuid primary key, + exam_id uuid, + student_id uuid, + status text, + total_score numeric, + submitted_at timestamptz +) +``` + +## 6.1 后台指标与监控 + +后台建议至少查看这些指标： + +- 已发布考试数 +- 已参加人数 +- 提交率 +- 平均分 / 通过率 +- 待复核题目数 +- 题目错误率 Top10 + +基础监控建议： + +- 登录成功率 +- 提交流程错误率 +- 自动判分耗时 +- 数据库写入失败率 + +## 7. 功能清单 + +必须完成： + +- 登录与角色鉴权 +- 学生考试列表 +- 学生答题与提交 +- 历史成绩查看 +- 题库管理 +- 考试管理 +- 提交记录查看 +- 成绩统计查看 + +可选增强： + +- 随机组卷 +- 批量导题 +- 班级维度统计 +- 成绩导出 + +## 8. 接口草案 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/auth/login` | 登录 | +| `GET` | `/api/exams` | 获取学生可见考试列表 | +| `GET` | `/api/exams/:id` | 获取考试详情 | +| `POST` | `/api/submissions/start` | 开始考试 | +| `POST` | `/api/submissions/:id/submit` | 提交试卷 | +| `GET` | `/api/student/history` | 获取历史成绩 | +| `GET` | `/api/admin/questions` | 获取题库 | +| `POST` | `/api/admin/questions` | 新增题目 | +| `GET` | `/api/admin/exams` | 获取考试列表 | +| `POST` | `/api/admin/exams` | 创建考试 | +| `GET` | `/api/admin/submissions` | 获取提交记录 | +| `GET` | `/api/admin/scores` | 获取成绩统计 | + +## 9. 非功能要求 + +- 学生端和管理员端权限必须严格隔离 +- 交卷后成绩和答题记录需稳定落库 +- 自动判分与人工复核状态要清晰 +- 后台统计口径要保持一致 +- 答题页在倒计时和断网提示上要有明确反馈 + +## 10. 开发顺序建议 + +1. 登录与角色鉴权 +2. 学生端考试列表和答题页 +3. 提交与成绩链路 +4. 管理后台题库和考试管理 +5. 提交记录和统计页 + +## 11. 待确认项 + +- 第一版是否只支持单选/判断/简答 +- 简答题是否只做人工复核 +- 是否要限制考试只能提交一次 diff --git a/docs/zh-cn/stage-2/assignments/exam-management-express/index.md b/docs/zh-cn/stage-2/assignments/exam-management-express/index.md index f83cf1f..ebcb297 100644 --- a/docs/zh-cn/stage-2/assignments/exam-management-express/index.md +++ b/docs/zh-cn/stage-2/assignments/exam-management-express/index.md @@ -1,222 +1,161 @@ -# 大作业 2：在线考试与管理系统 +# 在线考试与管理系统开发实战 -做完第一个 SaaS 项目后，下一步不只是“再做一个网站”，而是要进入更接近真实业务系统的场景。 +这个项目不是单纯的答题页面，而是围绕一份真实 PRD，把一个多角色业务系统从想法推进到可上线产品。 -在线考试系统就是一个很典型的练手题： +你会同时看到三件事： -- 前台不再只有一个工作台，而是有 **学生端完整考试流程** -- 后台不再只是看数据，而是要有 **题库管理、考试管理、成绩管理** -- 权限不再只是“登录/未登录”，而是要处理 **学生 / 管理员** 两种角色 -- 数据也不再是一张结果表，而是会涉及 **考试、题目、答卷、成绩、用户** 多种实体 +- 项目要做成什么 +- 如何基于 PRD 拆解并推进开发 +- 最后应该交付出什么样的效果 -::: tip 🎯 这次做什么？ -打造一个 **在线考试与管理系统**。学生登录后可查看考试列表、开始答题、提交试卷、查看历史成绩；管理员可以创建考试、维护题库、查看提交记录，并根据题目规则完成自动判分或人工复核。 +::: tip PRD 入口 +本项目的需求文档在同级页面： [查看 PRD](./PRD.md) :::
-## 为什么这个题目值得做？ +## 这个项目到底在做什么？ -因为它特别适合练“业务系统思维”。 +这是一个典型的在线考试与管理系统： -你会发现，考试系统不是把几个页面摆在一起就结束了，它必须处理很多真实约束： +- 官网前台：负责平台介绍和登录入口 +- 学生端：负责考试列表、答题、提交和成绩查看 +- 管理后台：负责题库、考试、提交记录和成绩统计 -- 学生只能看到自己该看的考试和成绩 -- 管理员要能发布考试、维护题目、查看提交情况 -- 一场考试通常会有开始时间、结束时间、作答时长、是否允许重复提交等规则 -- 题目可能有单选、多选、判断、简答，不同题型的判分方式也不一样 +后端需要接住这些关键能力： -这些问题会逼着你第一次认真面对： +- 登录鉴权 +- 角色权限 +- 考试和题库管理 +- 提交流程与自动判分 +- 成绩和统计管理 -- **角色权限** -- **数据建模** -- **接口设计** -- **提交流程与状态流转** +## 开发过程怎么走？ -这正是从“会写页面”到“会做系统”的关键一步。 +### 1. 先看 PRD，不要上来就写代码 -## 先看全景：这个系统到底由哪些部分组成？ +先确认： + +- 角色是不是只收敛到 `student / admin` +- 页面清单是否完整 +- 题型、提交流程和批改范围是否拍板 +- 接口与数据表是否合理 + +如果 PRD 没拍板，就先不要写代码。 + +### 2. 先让 AI 生成“骨架版” + +第一轮先生成： + +- 登录页 +- 学生考试列表 +- 学生答题页 +- 学生成绩页 +- 后台首页 +- 题库管理页 +- 考试管理页 +- 提交记录页 +- 成绩统计页 + +先把页面结构、导航和信息架构搭出来。 + +### 3. 再进入“监工模式” + +你要重点盯这几件事： + +- 学生和管理员入口有没有分清 +- 登录后权限是不是隔离 +- 开始考试、作答、提交链路是不是闭环 +- 自动判分和人工复核边界是不是清楚 +- 管理端能不能看到真实提交记录和成绩统计 + +### 4. 最后做联调和上线 ```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 + prd["PRD"] --> web["官网前台"] + prd --> student["学生端"] + prd --> admin["管理后台"] + student --> auth["鉴权"] + student --> exam["考试与作答"] + exam --> db["数据库"] + admin --> question["题库管理"] + admin --> submission["提交记录与成绩统计"] + question --> db + submission --> db ``` -你最终要交付的，不是一套静态页面，而是一套能让两类角色都跑通核心业务的系统。 +只要这条链路能跑通，这个项目就不是课堂作业，而是一套完整的业务系统原型。 -## 1. 定角色与范围：先把“做什么”说清楚 +## 怎么让 AI 帮你生成？ -### 角色设计 - -这次只保留两种角色，先把范围收住： - -| 角色 | 核心动作 | -|------|------| -| 学生 | 登录、查看考试列表、开始答题、提交试卷、查看历史成绩 | -| 管理员 | 登录、创建考试、维护题库、查看提交记录、查看成绩统计 | - -### 核心页面规划 - -按下面这些页面来做，已经足够覆盖主要能力： - -| 页面 | 路径 | 说明 | -|------|------|------| -| 首页 | `/` | 说明平台用途，提供登录入口 | -| 登录页 | `/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: 返回提交结果 -``` - -到这一步，你应该已经能看清这个作业的真正重点了：不是“页面多”，而是“状态和数据流更多”。 - -
- - - -
- -## 2. 搭前台：先让学生端和管理端“看得见、点得动” - -这一步先不要急着把所有后端写完，先把页面骨架搭出来。 - -### 推荐技术栈 - -- **Next.js / React**：负责前端页面 -- **TypeScript**：保证类型清晰 -- **Tailwind CSS + shadcn/ui**：快速搭建专业界面 -- **Express**：编写 REST API -- **PostgreSQL / Supabase Postgres**：存业务数据 - -### 第一步：让 AI IDE 先帮你起出页面骨架 +推荐按模块逐步下指令，而不是一句“帮我做完”。 ```text -请帮我创建一个在线考试与管理系统的前端页面骨架。 +请基于当前 PRD，帮我生成一个在线考试与管理系统的前端骨架。 + +要求： +1. 分成三个入口：www、app、admin +2. 官网包括：首页、登录入口 +3. 学生端包括：登录、考试列表、答题页、历史成绩 +4. 后台包括：后台首页、题库管理、考试管理、提交记录、成绩统计 +5. 先只生成页面结构和假数据，不接真实接口 +6. 风格要像真实业务系统，不像课堂 demo +``` + +然后再一块一块补： + +- 登录鉴权 +- 考试接口 +- 提交与判分 +- 题库管理 +- 成绩统计 + +## 怎么“监工”才有效？ + +每做完一个模块，至少检查这 5 件事： + +| 检查项 | 要看什么 | +|------|------| +| 页面是否对 | 页面数量、入口、功能是否符合 PRD | +| 接口是否对 | 请求参数、返回结构、状态处理是否合理 | +| 权限是否对 | 学生和管理员权限是否隔离 | +| 数据是否对 | 题目、提交、成绩、统计是否一致 | +| 演示是否对 | 是否真的能演示完整考试闭环 | + +## 最后的预期效果 + +做完后，你应该拿到这些交付物： + +- 一套可运行的在线考试系统项目 +- 一份同级 PRD 文档 +- 三套入口：`www / app / admin` +- 登录、题库、考试、提交、成绩、后台管理 +- 一份 README +- 一个可以演示的线上版本或本地完整运行方案 + +## 验收标准 + +| 维度 | 最低达标 | +|------|------| +| PRD 对齐 | 页面、功能、数据结构基本符合 PRD | +| 产品闭环 | 登录、考试、提交、成绩查看可以跑通 | +| 后台能力 | 题库、考试、提交、成绩统计可以查看 | +| 工程完整度 | 前端、后端、数据库、判分链路已接通 | +| 展示能力 | 可以清楚演示“从 PRD 到成品”的过程 | + +::: tip 🚀 完成后你会得到什么？ +你得到的不只是几个业务页面，而是一套完整的多角色系统开发样例。后面做教培、后台管理、内容平台项目时，都可以继续复用这套方法。 +::: 技术栈要求： - Next.js App Router diff --git a/docs/zh-cn/stage-2/assignments/modern-landing-page/PRD.md b/docs/zh-cn/stage-2/assignments/modern-landing-page/PRD.md new file mode 100644 index 0000000..2485268 --- /dev/null +++ b/docs/zh-cn/stage-2/assignments/modern-landing-page/PRD.md @@ -0,0 +1,758 @@ +# PRD：现代 AI 生图 SaaS 平台 + +状态：Draft v0.2 +目标：先完成可 review 的产品与实现方案，不进入开发。 + +## 1. 项目定位 + +这是一个现代化 AI 生图 SaaS 网站，产品体验参考 Midjourney、Leonardo、Playground 这类平台，但后端不训练自己的模型，而是对接第三方图像生成模型服务。 + +第一版要做的不是“一个展示页”，而是一套最小可用的产品闭环： + +- 官网落地页 +- 用户注册登录 +- Prompt 输入与图片生成 +- 图片历史记录与结果管理 +- 套餐/额度体系 +- 积分体系 +- 图片分享与公开展示 +- 点赞、评论、转发等互动能力 +- 管理后台 + +一句话定义： +做一个面向普通创作者和独立开发者的现代 AI 生图 SaaS 平台，前端提供官网、生成工作台和分享社区，后端对接第三方生图模型，支持注册登录、按套餐购买积分、图片分享与互动。 + +站点入口约定： + +- 官网前台：`www.xxx.com` +- 用户工作台：`app.xxx.com` +- 后台管理台：`admin.xxx.com` + +## 1.1 技术选型建议 + +当前默认技术方案： + +- 前端框架：`Next.js App Router` +- 用户鉴权：`Supabase Auth` +- 数据库：`Supabase Postgres` +- 文件存储：`Supabase Storage` +- 支付：`Stripe` +- 图像生成模型：通过统一后端适配层对接第三方模型 API + +默认原因： + +- `Supabase Auth + Supabase Postgres` 适合第一版 SaaS 快速落地 +- 用户系统、数据库、对象存储可以一起解决 +- 对 `app.xxx.com` 和 `admin.xxx.com` 两套前端都友好 +- 后续如果要拆独立服务，也保留扩展空间 + +默认鉴权设计： + +- 普通用户支持邮箱密码登录和第三方登录 +- 管理员使用同一套登录系统，但在用户表中标记 `role=admin` +- 后台管理台必须校验管理员权限 +- 用户前台与后台管理台接口分开鉴权 + +默认数据库设计： + +- 主业务库使用 `PostgreSQL` +- 用户、任务、支付、积分、社区内容、监控日志先放一套主库 +- 分析型查询先基于主库聚合，后续如数据量变大再拆分析库 + +系统总览： + +```mermaid +flowchart LR + WWW["www.xxx.com
官网前台"] --> API["应用 API / 管理 API"] + APP["app.xxx.com
用户工作台"] --> API + ADMIN["admin.xxx.com
后台管理台"] --> API + API --> AUTH["Supabase Auth"] + API --> DB["Supabase Postgres"] + API --> OSS["OSS 对象存储"] + API --> PAY["Stripe"] + API --> MODEL["第三方生图模型"] +``` + +## 2. 目标用户与核心目标 + +目标用户： + +- 想快速生成营销图、封面图、海报图的普通用户 +- 需要批量试 Prompt 的设计师或内容创作者 +- 喜欢浏览他人作品并进行互动的社区用户 +- 管理用户、任务和额度消耗的管理员 + +核心目标： + +- 用户可以在 3 分钟内完成注册并生成第一张图 +- 用户能清晰看到每次生成结果、积分消耗和历史记录 +- 用户可以把满意作品分享出来并获得互动反馈 +- 平台能支持积分购买、积分消耗、失败重试、内容互动和后台管理 + +建议北极星指标： + +- 新用户首图生成成功率 +- 日活跃生成用户数 +- 人均生成次数 +- 生成任务成功率 +- 付费转化率 +- 分享图片数 +- 点赞/评论互动率 +- 日活跃积分用户数 + +## 3. MVP 范围 + +第一版必须包含： + +- 官网首页 +- 注册/登录 +- 生图工作台 +- 图片历史页 +- 套餐/积分页 +- 积分页 +- 支付/订阅能力 +- 图片公开分享页 +- 点赞、评论、转发 +- 图片生成接口 +- 生成任务状态查询 +- 后台查看用户、生成任务、积分使用和内容互动情况 + +第一版不做： + +- 自训练模型 +- 多模型工作流编排 +- 图片编辑器 +- 团队协作 +- 多语言 + +## 4. 角色与权限 + +| 角色 | 权限 | +|------|------| +| 游客 | 浏览官网、查看产品介绍、注册登录 | +| 注册用户 | 创建生成任务、查看历史图片、管理自己的积分和结果、查看积分明细、分享作品、点赞评论转发 | +| 管理员 | 查看用户、任务状态、失败日志、套餐与积分消耗情况，管理积分规则、公开内容与互动数据 | + +## 5. 前端实现 + +推荐技术栈： + +- Next.js App Router +- TypeScript +- Tailwind CSS +- shadcn/ui + +前端形态说明： + +- 官网前台和用户工作台都属于“前端产品” +- 后台管理系统本质上也是前端页面，只是面向内部运营和管理员使用 +- 因此本项目会有两套前端界面： + - 面向用户的产品前台 + - 面向运营/管理员的后台管理台 +- 同时后台管理台需要配套独立的管理员接口与权限校验 + +入口建议： + +| 站点类型 | 建议入口 | 说明 | +|------|------|------| +| 官网前台 | `www.xxx.com` | 产品介绍、定价、FAQ、注册入口 | +| 用户工作台 | `app.xxx.com` | 登录后生成图片、看图库、看积分、发动态 | +| 后台管理台 | `admin.xxx.com` | 管理用户、套餐、任务、内容、风控 | + +## 5.1 页面架构总览 + +当前 PRD 定义为 `3 套入口，19 个大页面`： + +- 官网前台 `1` 个大页面 +- 用户工作台 `9` 个大页面 +- 后台管理台 `9` 个大页面 + +### A. 官网前台 `www.xxx.com` + +#### 1. 官网首页 `www:/` + +核心功能： + +- Hero 区与主 CTA +- 产品能力介绍 +- 作品展示 +- 套餐预览 +- FAQ +- 注册/登录/进入工作台入口 + +### B. 用户工作台 `app.xxx.com` + +#### 2. 登录页 `app:/login` + +核心功能： + +- 邮箱/密码登录 +- 第三方登录入口 +- 找回密码入口 +- 跳转注册页 + +#### 3. 注册页 `app:/register` + +核心功能： + +- 新用户注册 +- 同意协议与隐私政策 +- 第三方登录注册 +- 注册成功后进入工作台 + +#### 4. 生成工作台 `app:/generate` + +核心功能： + +- 输入 Prompt 与 Negative Prompt +- 选择模型、比例、数量、质量参数 +- 提交生图任务 +- 查看生成中/成功/失败状态 +- 对结果进行再次生成、收藏、发布 + +#### 5. 历史图库 `app:/gallery` + +核心功能： + +- 查看个人历史生成记录 +- 按时间/模型/状态筛选 +- 删除图片 +- 收藏图片 +- 从历史记录再次进入详情或复用 Prompt + +#### 6. 套餐页 `app:/billing` + +核心功能： + +- 查看 Basic / Standard / Pro / Mega 套餐 +- 月付/年付切换 +- 查看每档套餐包含的积分和权益 +- 发起购买套餐 +- 购买额外积分包 +- FAQ 与账号关联说明 + +#### 7. 积分页 `app:/points` + +核心功能： + +- 查看当前积分余额 +- 查看积分获取记录 +- 查看积分消耗记录 +- 每日签到 +- 积分兑换权益或生成次数 + +#### 8. 社区广场 `app:/explore` + +核心功能： + +- 浏览公开作品流 +- 按热门/最新排序 +- 点赞作品 +- 评论作品 +- 转发作品 +- 进入作品详情页 + +#### 9. 作品详情页 `app:/posts/:id` + +核心功能： + +- 查看单个作品大图 +- 查看作者信息与发布时间 +- 查看完整 Prompt 与参数 +- 查看点赞、评论、转发数据 +- 复制 Prompt / 再次生成 / 点赞 / 评论 / 转发 + +#### 10. 个人中心 `app:/settings` + +核心功能： + +- 查看个人资料 +- 绑定/关联账号 +- 查看当前套餐 +- 查看登录方式与安全设置 +- 管理公开分享偏好 + +### C. 后台管理台 `admin.xxx.com` + +#### 11. 后台首页 `admin:/` + +核心功能： + +- 用户总数 +- 生成任务总量 +- 支付收入概览 +- 内容分享与互动概览 +- 异常任务提醒 + +#### 12. 用户管理 `admin:/users` + +核心功能： + +- 查看用户列表 +- 搜索和筛选用户 +- 查看用户套餐、积分、活跃情况 +- 封禁/解封账号 +- 手动调整积分 + +#### 13. 任务管理 `admin:/tasks` + +核心功能： + +- 查看全部生成任务 +- 按状态筛选成功/失败/处理中任务 +- 查看失败原因 +- 手动重试或标记异常任务 + +#### 14. 内容管理 `admin:/posts` + +核心功能： + +- 查看公开作品列表 +- 审核作品是否可展示 +- 下架违规内容 +- 查看评论与互动记录 +- 审核或删除评论 + +#### 15. 套餐管理 `admin:/plans` + +核心功能： + +- 配置套餐价格 +- 配置月付/年付优惠 +- 配置套餐积分数 +- 配置积分包 top-up +- 配置并发和高级权益 + +#### 16. 支付订单 `admin:/billing` + +核心功能： + +- 查看支付订单列表 +- 查看订阅状态 +- 查看退款/失败订单 +- 搜索异常支付记录 + +#### 17. 运营配置 `admin:/operations` + +核心功能： + +- 配置签到积分规则 +- 配置分享/互动奖励规则 +- 配置活动公告 +- 配置风控和审核开关 + +#### 18. SaaS 指标看板 `admin:/analytics` + +核心功能： + +- 查看新增用户、DAU、WAU、MAU +- 查看注册转化率、付费转化率 +- 查看次日/7日/30日留存 +- 查看套餐分布和订阅续费情况 +- 查看积分发放、积分消耗、积分结余情况 +- 查看社区分享数、点赞率、评论率、转发率 + +#### 19. 系统监控页 `admin:/observability` + +核心功能： + +- 查看 API 调用量、成功率、错误率、平均耗时 +- 查看第三方生图模型调用情况 +- 查看数据库连接状态、慢查询和失败率 +- 查看支付接口回调状态 +- 查看任务队列积压和重试情况 +- 查看系统告警与异常日志 + +建议页面明细： + +| 页面 | 路径 | 说明 | +|------|------|------| +| 官网首页 | `www:/` | Hero、作品展示、功能介绍、价格方案、FAQ、CTA | +| 登录页 | `app:/login` | 登录表单 | +| 注册页 | `app:/register` | 注册表单 | +| 生成工作台 | `app:/generate` | Prompt、参数设置、任务提交、结果查看 | +| 历史图库 | `app:/gallery` | 查看历史图片、筛选、删除、收藏 | +| 套餐页 | `app:/billing` | 展示套餐档位、月付/年付、积分权益 | +| 积分页 | `app:/points` | 查看积分余额、获取记录、兑换规则 | +| 社区广场 | `app:/explore` | 浏览公开作品、点赞、评论、转发 | +| 作品详情页 | `app:/posts/:id` | 查看单张公开作品的详情与互动信息 | +| 个人中心 | `app:/settings` | 用户资料、积分、绑定信息 | +| 后台首页 | `admin:/` | 后台概览看板 | +| 用户管理 | `admin:/users` | 查看用户、封禁、积分与套餐状态 | +| 任务管理 | `admin:/tasks` | 查看生图任务、失败任务、重试情况 | +| 内容管理 | `admin:/posts` | 审核公开作品、评论、转发数据 | +| 套餐管理 | `admin:/plans` | 配置套餐、积分包、价格与权益 | +| 支付订单 | `admin:/billing` | 查看支付记录、退款状态、异常订单 | +| 运营配置 | `admin:/operations` | 配置签到规则、积分规则、公告与活动 | +| SaaS 指标看板 | `admin:/analytics` | 查看留存、转化、积分、订阅与社区活跃指标 | +| 系统监控页 | `admin:/observability` | 查看 API、模型调用、数据库、支付、队列状态 | + +前端核心组件： + +- Hero 区与 CTA +- Prompt 输入面板 +- 模型参数配置区 +- 图片结果卡片 +- 任务状态轮询组件 +- 图库列表/瀑布流 +- 套餐卡片组件 +- 月付/年付切换组件 +- 积分概览卡片 +- 积分明细列表 +- FAQ 折叠区 +- 公开作品卡片 +- 评论列表与评论输入框 +- 点赞/转发操作栏 +- 套餐价格卡片 +- 空态、加载、失败重试组件 +- 管理后台表格、筛选器、统计卡片、审核面板 +- 监控图表、趋势图、健康状态卡片、告警列表 + +前端状态与数据流： + +- 游客从首页进入注册或登录 +- 登录后进入 `/generate` +- 用户输入 Prompt 和参数后提交生成任务 +- 前端轮询或订阅任务状态 +- 成功后展示图片并写入历史记录 +- 用户完成签到、生成、分享、互动后可获得积分 +- 用户可将图片发布到公开广场 +- 其他用户可点赞、评论、转发该作品 +- 套餐页展示剩余积分、套餐差异与升级入口 +- 积分页展示积分来源、消费记录和兑换入口 +- 管理员从独立后台入口进入运营看板和管理模块 +- 管理员可在后台查看业务指标和系统健康状态 + +## 6. 后端实现 + +推荐技术栈： + +- Next.js Route Handlers 或 Node.js/Express +- PostgreSQL / Supabase +- 对接第三方图像生成模型 API + +后端模块： + +- `auth`：注册、登录、鉴权 +- `generation`：创建生图任务、查询任务状态、失败重试 +- `images`：图片历史、删除、收藏、详情 +- `points`：积分购买、累计、扣减、任务奖励、兑换记录 +- `billing`：套餐、支付记录、升级状态 +- `social`：公开发布、点赞、评论、转发 +- `analytics`：留存、转化、订阅、积分、社区活跃统计 +- `observability`：API 调用、模型调用、数据库状态、告警日志 +- `admin`：后台查看用户、任务、错误日志、审核内容、运营配置 + +核心数据流： + +```mermaid +flowchart TD + user["用户"] --> gen["提交生成任务"] + gen --> payCheck["检查套餐/积分"] + payCheck --> model["调用第三方生图模型"] + model --> oss["上传结果到 OSS"] + oss --> db["写入 Postgres: tasks / images / points"] + db --> gallery["历史图库 / 社区发布"] + gallery --> social["点赞 / 评论 / 转发"] + social --> db + db --> analytics["SaaS 指标看板"] + db --> observability["API / DB / Provider 监控"] +``` + +建议数据表： + +```sql +profiles ( + id uuid primary key, + email text, + role text, + plan text, + points int, + created_at timestamptz +) + +generation_tasks ( + id uuid primary key, + user_id uuid, + prompt text, + negative_prompt text, + model text, + aspect_ratio text, + image_count int, + status text, + error_message text, + provider_task_id text, + points_cost int, + created_at timestamptz +) + +generated_images ( + id uuid primary key, + task_id uuid, + user_id uuid, + image_url text, + width int, + height int, + is_favorite boolean, + created_at timestamptz +) + +billing_records ( + id uuid primary key, + user_id uuid, + plan_code text, + billing_cycle text, + type text, + amount_cents int, + points_delta int, + status text, + created_at timestamptz +) + +point_records ( + id uuid primary key, + user_id uuid, + type text, + points_delta int, + source text, + created_at timestamptz +) + +api_call_logs ( + id uuid primary key, + route text, + method text, + user_id uuid, + status_code int, + duration_ms int, + request_id text, + created_at timestamptz +) + +provider_call_logs ( + id uuid primary key, + provider_name text, + task_id uuid, + status text, + duration_ms int, + error_message text, + created_at timestamptz +) + +system_health_checks ( + id uuid primary key, + service_name text, + check_type text, + status text, + detail jsonb, + created_at timestamptz +) + +subscription_plans ( + id uuid primary key, + code text, + name text, + monthly_price_cents int, + yearly_price_cents int, + monthly_points int, + concurrent_image_jobs int, + concurrent_video_jobs int, + supports_hd_video boolean, + supports_stealth boolean, + created_at timestamptz +) + +shared_posts ( + id uuid primary key, + image_id uuid, + user_id uuid, + caption text, + visibility text, + repost_from_post_id uuid, + created_at timestamptz +) + +post_likes ( + id uuid primary key, + post_id uuid, + user_id uuid, + created_at timestamptz +) + +post_comments ( + id uuid primary key, + post_id uuid, + user_id uuid, + content text, + created_at timestamptz +) +``` + +## 7. 功能清单 + +必须完成： + +- 官网价值展示 +- 注册/登录 +- Prompt 输入与参数选择 +- 图片生成任务提交 +- 图片结果展示 +- 历史记录查看 +- 套餐/积分展示 +- 积分展示与明细 +- 支付/订阅 +- 图片公开分享 +- 点赞、评论、转发 +- 后台独立入口 +- 管理员查看任务、用户、支付和社区内容 +- 管理员审核公开内容与评论 +- 管理员配置积分规则与套餐规则 +- 后台查看 SaaS 留存、转化、积分与订阅指标 +- 后台查看 API 调用、模型调用和数据库健康状态 + +可选增强： + +- 图片收藏 +- 再次生成同款 +- Prompt 模板 +- 水印与下载规格选择 +- 任务失败自动重试 +- 评论通知 +- 个人主页与作品墙 +- 积分兑换生成次数或高级功能 + +## 8.1 套餐设计草案 + +套餐逻辑： + +- 用户购买的是 `积分型订阅套餐` +- 月付和年付两种计费方式 +- 年付默认比月付优惠 `20%` +- 套餐按月发放积分 +- 生成图片、生成视频、高清能力、并发能力由套餐共同决定 + +建议档位： + +| 套餐 | 月付 | 年付折后 | 每月积分 | 图片并发 | 视频并发 | 其他权益 | +|------|------|------|------|------|------|------| +| Basic | `$10` | `$8` | 2000 | 3 | 1 | 基础生图、可补充购买积分 | +| Standard | `$30` | `$24` | 8000 | 3 | 3 | 支持高清视频、无限慢速图像生成 | +| Pro | `$60` | `$48` | 18000 | 12 | 6 | 隐身生成、更多并发 | +| Mega | `$120` | `$96` | 40000 | 12 | 12 | 更高上限、适合高频创作用户 | + +补充说明： + +- 套餐价格和积分数值是第一版草案，后续可调整 +- 不同模型与分辨率对应不同积分消耗 +- 视频生成会比图片生成消耗更多积分 +- 支持额外购买积分包作为 top-up + +建议 FAQ 内容： + +- 我买了套餐但没生效怎么办？ +- 月付和年付有什么差别？ +- 积分用完了怎么办？ +- 积分会不会过期？ +- 账号能不能绑定多个登录方式？ +- 哪些内容支持公开分享？ + +## 9. 接口草案 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/auth/register` | 用户注册 | +| `POST` | `/api/auth/login` | 用户登录 | +| `POST` | `/api/auth/link-account` | 关联不同登录账号 | +| `GET` | `/api/me` | 获取当前用户资料与积分 | +| `GET` | `/api/points` | 获取积分余额和明细 | +| `POST` | `/api/points/check-in` | 每日签到获取积分 | +| `POST` | `/api/points/redeem` | 积分兑换权益或生成次数 | +| `POST` | `/api/generations` | 创建生图任务 | +| `GET` | `/api/generations/:id` | 获取任务状态和结果 | +| `GET` | `/api/gallery` | 获取当前用户历史图片 | +| `DELETE` | `/api/gallery/:id` | 删除某张图片 | +| `PATCH` | `/api/gallery/:id/favorite` | 收藏/取消收藏图片 | +| `GET` | `/api/billing/plans` | 获取套餐列表 | +| `POST` | `/api/billing/checkout` | 创建支付订单或订阅会话 | +| `POST` | `/api/billing/top-up` | 购买额外积分包 | +| `GET` | `/api/billing/records` | 获取消费与充值记录 | +| `POST` | `/api/posts` | 将一张图片发布为公开作品 | +| `GET` | `/api/posts` | 获取公开作品流 | +| `GET` | `/api/posts/:id` | 获取作品详情 | +| `POST` | `/api/posts/:id/likes` | 点赞作品 | +| `DELETE` | `/api/posts/:id/likes` | 取消点赞 | +| `POST` | `/api/posts/:id/comments` | 评论作品 | +| `POST` | `/api/posts/:id/repost` | 转发作品 | +| `GET` | `/api/admin/overview` | 获取后台总览 | +| `GET` | `/api/admin/users` | 获取用户列表与账户状态 | +| `GET` | `/api/admin/tasks` | 获取生成任务列表 | +| `GET` | `/api/admin/posts` | 获取公开作品与互动列表 | +| `GET` | `/api/admin/analytics/overview` | 获取新增、活跃、付费转化等核心 SaaS 指标 | +| `GET` | `/api/admin/analytics/retention` | 获取次日/7日/30日留存数据 | +| `GET` | `/api/admin/analytics/points` | 获取积分发放、消耗、结余数据 | +| `GET` | `/api/admin/analytics/subscriptions` | 获取订阅与套餐分布数据 | +| `PATCH` | `/api/admin/posts/:id/moderate` | 审核或下架公开作品 | +| `PATCH` | `/api/admin/comments/:id/moderate` | 审核或删除评论 | +| `GET` | `/api/admin/billing` | 获取支付订单与订阅记录 | +| `GET` | `/api/admin/plans` | 获取套餐与积分包配置 | +| `PATCH` | `/api/admin/plans/:id` | 更新套餐配置 | +| `GET` | `/api/admin/point-rules` | 获取积分规则 | +| `PATCH` | `/api/admin/point-rules` | 更新积分规则 | +| `GET` | `/api/admin/observability/apis` | 获取 API 调用量、错误率、耗时等监控数据 | +| `GET` | `/api/admin/observability/providers` | 获取第三方模型调用情况 | +| `GET` | `/api/admin/observability/database` | 获取数据库连接、慢查询、失败率 | +| `GET` | `/api/admin/observability/health` | 获取系统健康检查结果 | + +`POST /api/generations` 请求示例： + +```json +{ + "prompt": "a cinematic futuristic city at sunset, ultra detailed", + "negativePrompt": "blurry, low quality", + "model": "flux-dev", + "aspectRatio": "1:1", + "imageCount": 4 +} +``` + +## 10. 非功能要求 + +- 生成过程有明确状态反馈 +- 失败任务能提示原因 +- 移动端至少可查看和浏览历史结果 +- 首页具备现代 SaaS 视觉质量 +- 用户只能访问自己的图片和任务 +- 积分扣减逻辑要稳定可追踪 +- 积分发放与扣减逻辑要可审计 +- 公开内容需要有最小审核或风控预留能力 +- 互动接口需要防刷和限流预留 +- 管理后台关键指标需支持日/周/月维度查看 +- API 日志、数据库状态、第三方模型调用结果需可追踪 + +## 11. 开发顺序建议 + +1. 搭官网首页与登录注册页 +2. 实现用户鉴权 +3. 实现生成工作台 UI +4. 接入生图任务接口 +5. 实现历史图库 +6. 实现支付、套餐、积分与 FAQ 页 +7. 实现分享、点赞、评论、转发 +8. 实现独立后台入口与后台任务、用户、积分、支付、内容管理页 +9. 实现 SaaS 指标看板与系统监控页 + +## 12. 待确认项 + +- 第三方模型服务优先接哪一家 +- 图片是否允许公开分享 +- 后台是否必须使用独立二级域名，还是允许先用独立路由入口 +- 积分获取规则是签到 + 分享 + 互动，还是还要包含邀请奖励 +- 积分是否只用于生成消耗，还是还要兑换会员权益 +- 年付优惠是否固定为 `20%` +- 是否需要单独的积分包 top-up +- 鉴权是否接受默认方案：`Supabase Auth` +- 数据库是否接受默认方案：`Supabase Postgres` +- 留存与系统监控是否先做基础后台报表，后续再接专业监控平台 +- 评论是否允许二级回复 +- 转发是站内转发，还是还要带外链分享 +- 第一版是否需要人工审核公开作品 diff --git a/docs/zh-cn/stage-2/assignments/modern-landing-page/index.md b/docs/zh-cn/stage-2/assignments/modern-landing-page/index.md index ad7d0ed..013cfdb 100644 --- a/docs/zh-cn/stage-2/assignments/modern-landing-page/index.md +++ b/docs/zh-cn/stage-2/assignments/modern-landing-page/index.md @@ -1,228 +1,174 @@ -# 现代网页落地页 +# 现代 AI 生图 SaaS 开发实战 -很多同学会写功能页，但一到“让用户第一次看到就愿意注册”的落地页就卡住了。 +这个项目不再只是“做一个页面”，而是围绕一份真实 PRD，把一个 AI 生图 SaaS 从想法推进到可上线产品。 -这份大作业就是专门练这件事：你要做一个真正能承接流量、讲清价值、引导转化的现代落地页，而不是“看起来像作业”的静态展示页。 +你会同时看到三件事： -::: tip 🎯 这次做什么？ -打造一个 **可上线的现代产品落地页**。页面需要包含价值主张、核心功能展示、用户证言、价格方案、FAQ、明确 CTA（注册/预约演示）以及基础数据埋点，最终可以用于真实投放或作品集展示。 +- 项目要做成什么 +- 如何基于 PRD 拆解并推进开发 +- 最后应该交付出什么样的效果 + +::: tip PRD 入口 +本项目的需求文档在同级页面： [查看 PRD](./PRD.md) :::
-## 为什么这个题目值得做？ +## 这个项目到底在做什么？ -因为落地页不是“前端练习题”，而是产品和增长的交叉点。 +这是一个参考 Midjourney 产品体验的现代 AI 生图 SaaS： -- 你会练到结构化表达：30 秒内让用户知道你是谁、你解决什么问题 -- 你会练到工程能力：组件化、响应式、性能优化、SEO 基础 -- 你会练到转化意识：CTA 设计、表单路径、埋点事件、A/B 迭代 +- 官网前台：负责产品介绍、定价、FAQ、注册转化 +- 用户工作台：负责 Prompt 输入、图片生成、图库、积分、套餐、社区互动 +- 后台管理台：负责用户、任务、支付、积分、内容审核、SaaS 指标和系统监控 -做完这个项目，你不仅能做“页面”，还能做“会转化的页面”。 +同时，后端需要接住这些关键能力： -## 先看全景：一张图看懂这个作业 +- 用户鉴权 +- 图片生成任务 +- OSS 对象存储 +- 积分与套餐支付 +- 图片分享、点赞、评论、转发 +- 留存、转化、API 调用、数据库状态监控 + +## 开发过程怎么走？ + +### 1. 先看 PRD，不要上来就写代码 + +先把这几个问题看清楚： + +- 有几个入口：`www / app / admin` +- 有几个大页面 +- 每个页面的核心功能是什么 +- 后端模块和数据库表有哪些 +- 第一版哪些做，哪些不做 + +如果 PRD 没拍板，就不要开始开发。 + +### 2. 先让 AI 生成“骨架版” + +第一轮不是要它一次性写完，而是先生成： + +- 官网首页 +- 登录注册 +- 生图工作台 +- 历史图库 +- 套餐/积分页 +- 社区广场 +- 后台首页与管理页骨架 + +这一步的目标是：把信息架构、路由、页面分工先搭出来。 + +### 3. 再进入“监工模式” + +真正难的不是生成第一版，而是持续监工。 + +你要盯的重点包括： + +- 页面结构是不是和 PRD 一致 +- 前台、工作台、后台入口有没有分清 +- 鉴权是不是做对了 +- 普通用户和管理员权限有没有串 +- 积分、支付、生成任务的状态流是不是闭环 +- OSS 上传、数据库写入、任务状态更新是不是一致 +- 后台有没有 SaaS 指标和系统监控 + +可以把 AI 当成执行者，但你自己要做“产品经理 + 技术负责人 + QA”。 + +### 4. 最后做联调和上线 + +最后一轮不是补页面，而是把完整链路跑通： ```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["埋点事件上报"] + prd["PRD"] --> web["官网前台"] + prd --> app["用户工作台"] + prd --> admin["后台管理台"] + app --> auth["鉴权"] + app --> gen["图片生成任务"] + gen --> oss["OSS 对象存储"] + gen --> db["数据库"] + billing["支付与套餐"] --> db + social["分享 / 点赞 / 评论 / 转发"] --> db + admin --> analytics["SaaS 指标看板"] + admin --> observability["API / DB / Provider 监控"] ``` -这张图表达的核心是：你的目标不是把每个模块都写出来，而是让用户自然走到 CTA 并完成动作。 +只要这条链路能跑通，这个项目就不是“Demo 页面”，而是一个完整产品原型。 -## 1. 定定位：先把“做给谁看”讲清楚 +## 怎么让 AI 帮你生成？ -### 建议你先写出这 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. 页脚 +请基于当前 PRD，帮我生成一个现代 AI 生图 SaaS 的前端骨架。 要求： -- 风格现代、简洁，不要像课堂作业 -- 先实现响应式布局 -- 所有 CTA 有 hover/active 状态 -- 预留事件埋点函数 +1. 分成三个入口：www、app、admin +2. 官网包括：首页、定价、FAQ +3. app 包括：登录、注册、生成工作台、图库、套餐、积分、社区、作品详情、个人中心 +4. admin 包括：后台首页、用户管理、任务管理、内容管理、套餐管理、支付订单、运营配置、SaaS 指标、系统监控 +5. 先只生成页面结构和假数据，不接真实接口 +6. 风格参考 Midjourney，简洁、现代、带产品感 ``` -### 第二步：补齐文案与信息层级 +然后再一块一块补： -很多页面做不出转化，根因是信息顺序错了。你可以继续给 AI IDE： +- 鉴权 +- 数据库 +- OSS 上传 +- 支付 +- 积分系统 +- 社区互动 +- 后台统计和监控 -```text -请优化我的落地页文案结构，目标是提高注册转化率。 +## 怎么“监工”才有效？ -背景： -- 目标用户：独立开发者和小团队 -- 核心价值：用 AI 自动生成营销内容 -- 主转化动作：点击“免费开始” +每做完一个模块，至少检查这 5 件事： -请输出： -1. Hero 标题 5 个备选 -2. 副标题 5 个备选 -3. CTA 按钮文案 5 个备选 -4. 每个功能卡片的一句话价值描述 -5. FAQ 建议问题列表 -``` +| 检查项 | 要看什么 | +|------|------| +| 页面是否对 | 页面数量、入口、功能是否符合 PRD | +| 接口是否对 | 请求参数、返回结构、状态处理是否合理 | +| 权限是否对 | 普通用户和管理员是否隔离 | +| 数据是否对 | 数据库、OSS、支付、积分是否一致 | +| 演示是否对 | 是否真的能给别人完整演示一条链路 | -### 第三步：加关键交互与状态 +如果发现 AI 写偏了，不要整页推翻，直接让它改具体模块。 -至少补齐这几项： +## 最后的预期效果 -- 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（启动方式、技术栈、埋点说明） +- 一套可运行的 AI 生图 SaaS 项目 +- 一份同级 PRD 文档 +- 三套入口：`www / app / admin` +- 基础鉴权、支付、积分、OSS、社区互动、后台管理 +- SaaS 指标看板和系统监控页 +- 一份 README +- 一个可以演示的线上版本或本地完整运行方案 ## 验收标准 -| 维度 | 最低达标 | 加分项 | -|------|------|------| -| 页面完整度 | Hero/功能/价格/FAQ/页脚完整 | 信息密度与视觉层级优秀 | -| 转化设计 | 有明确主 CTA 和提交流程 | CTA 文案与位置经过对比优化 | -| 工程质量 | 响应式正常、交互状态完整 | 组件拆分清晰、复用性高 | -| 数据意识 | 关键事件埋点可用 | 有初步转化漏斗分析 | -| 交付能力 | 可访问链接 + README + 演示视频 | Lighthouse、SEO、无障碍基础优化 | +| 维度 | 最低达标 | +|------|------| +| PRD 对齐 | 页面、功能、数据结构基本符合 PRD | +| 产品闭环 | 注册、购买积分、生成图片、查看历史、分享互动可以跑通 | +| 后台能力 | 用户、任务、支付、内容、积分、监控可以查看 | +| 工程完整度 | 前端、后端、数据库、OSS、支付链路都已接通 | +| 展示能力 | 可以清楚演示“从 PRD 到成品”的完整过程 | -## 提交前最后检查 - - - - -
    -
    • -
    • -
    • -
    • -
    • -
- - -::: tip 🚀 完成后你会得到什么？ -这会是你作品集中最“有商业味道”的页面之一。它证明你不只会做界面，还能围绕目标用户和转化结果来做产品页面。 +::: tip 🚀 做完这个项目，你会得到什么？ +你得到的不只是一个页面，也不只是一个小功能，而是一套完整的 AI SaaS 产品开发过程样例。后面再做别的项目，你可以继续沿用这套“先 PRD、再生成、再监工、再联调上线”的方法。 ::: diff --git a/docs/zh-cn/stage-2/assignments/movie-recommendation-springboot/PRD.md b/docs/zh-cn/stage-2/assignments/movie-recommendation-springboot/PRD.md new file mode 100644 index 0000000..cbfee32 --- /dev/null +++ b/docs/zh-cn/stage-2/assignments/movie-recommendation-springboot/PRD.md @@ -0,0 +1,408 @@ +# PRD：Spring Boot 电影推荐系统 + +状态：Draft v0.1 +目标：明确推荐系统项目的最小可用边界和前后端分工。 + +## 1. 项目定位 + +这是一个“带推荐能力的电影站点”，不是纯展示页面。它需要把用户行为沉淀下来，并给出可解释推荐。 + +一句话定义： +做一个包含电影浏览、评分收藏、推荐结果与后台管理的电影推荐系统。 + +系统总览： + +```mermaid +flowchart LR + WWW["www.xxx.com
官网前台"] --> API["应用 API / 管理 API"] + APP["app.xxx.com
用户前台"] --> API + ADMIN["admin.xxx.com
后台管理台"] --> API + API --> AUTH["JWT Auth"] + API --> DB["MySQL"] + API --> REC["Recommendation Service"] +``` + +## 1.0 技术选型建议 + +- 前端框架：`React` 或 `Vue` +- 后端框架：`Spring Boot 3` +- 数据库：`MySQL` +- 鉴权：`JWT` +- 缓存：`Redis`（可选） + +站点入口约定： + +- 官网前台：`www.xxx.com` +- 用户前台：`app.xxx.com` +- 后台管理台：`admin.xxx.com` + +## 1.1 竞品参考（官方） + +- [Letterboxd](https://letterboxd.com/) +- [IMDb](https://www.imdb.com/) + +## 1.2 产品借鉴点 + +本项目的产品设计建议参考真实电影产品的做法： + +- 借鉴 `Letterboxd` 的社区化电影浏览体验：电影卡片、评分、收藏、个人记录要自然串起来 +- 借鉴 `IMDb` 的详情页信息组织：海报、简介、标签、评分、演员和关联内容分层展示 +- 推荐页不能只是一个列表，应当同时展示推荐理由 +- 个人中心要强调“我的评分 / 我的收藏 / 我的推荐偏好” +- 后台管理应像内容后台，而不是简单 CRUD 页面 + +## 1.3 竞品页面拆解 + +建议重点参考的竞品页面结构： + +- `Letterboxd` 首页与个人页 + - 重点看：电影浏览、评分记录、收藏和个人偏好的组织方式 +- `IMDb` 电影详情页 + - 重点看：海报、简介、标签、评分、演员与相关内容的层次 +- `IMDb` 排行榜和推荐内容区域 + - 重点看：卡片式展示和浏览路径设计 + +因此本项目建议： + +- 列表页更像内容浏览页 +- 详情页更像内容详情页 +- 推荐页更像“为你推荐” +- 后台页更像内容运营后台 + +## 2. 目标用户与核心目标 + +目标用户： + +- 浏览和筛选电影的普通用户 +- 愿意通过评分与收藏改善推荐结果的注册用户 +- 维护影片信息和推荐质量的管理员 + +核心目标： + +- 用户可以完成浏览、评分、收藏闭环 +- 系统可给出 TopN 推荐结果 +- 推荐结果要有基础可解释性 + +## 3. MVP 范围 + +第一版必须包含： + +- 注册/登录 +- 电影列表和详情 +- 搜索、分类、分页 +- 用户评分 +- 收藏电影 +- 推荐页 +- 管理后台维护电影数据 + +第一版不做： + +- 复杂协同过滤算法 +- 视频播放 +- 评论社区 +- 多维画像系统 +- 实时推荐流计算 + +## 4. 角色与权限 + +| 角色 | 权限 | +|------|------| +| 游客 | 浏览电影列表与详情 | +| 注册用户 | 评分、收藏、查看推荐 | +| 管理员 | 管理电影数据、查看推荐概览 | + +## 5. 前端实现 + +## 5.1 页面架构总览 + +当前 PRD 定义为 `3 套入口，9 个大页面`： + +- 官网前台 `1` 个大页面 +- 用户前台 `5` 个大页面 +- 后台管理台 `3` 个大页面 + +### A. 官网前台 `www.xxx.com` + +#### 1. 官网首页 `www:/` + +核心功能： + +- 产品介绍 +- 热门电影 +- 注册入口 + +### B. 用户前台 `app.xxx.com` + +#### 2. 登录页 `app:/login` + +核心功能： + +- 登录 +- 注册入口 + +#### 3. 电影列表页 `app:/movies` + +核心功能： + +- 浏览电影 +- 搜索和筛选 +- 分页 + +#### 4. 电影详情页 `app:/movies/:id` + +核心功能： + +- 查看海报和简介 +- 评分 +- 收藏 +- 查看标签和推荐理由 + +#### 5. 推荐页 `app:/recommendations` + +核心功能： + +- 查看个性化推荐 +- 查看推荐理由 + +#### 6. 个人中心 `app:/me` + +核心功能： + +- 查看评分历史 +- 查看收藏 +- 查看个人偏好 + +### C. 后台管理台 `admin.xxx.com` + +#### 7. 后台首页 `admin:/` + +核心功能： + +- 电影总数 +- 用户行为概览 +- 推荐效果概览 + +#### 8. 电影管理页 `admin:/movies` + +核心功能： + +- 新增电影 +- 编辑电影 +- 管理标签 + +#### 9. 推荐概览页 `admin:/recommendations` + +核心功能： + +- 查看推荐结果 +- 查看热门标签 +- 查看用户行为统计 + +## 5.2 关键用户链路 + +```mermaid +flowchart TD + visitor["访客"] --> list["电影列表页"] + list --> detail["电影详情页"] + visitor --> login["登录 / 注册"] + login --> rate["评分 / 收藏"] + rate --> reco["推荐页"] + reco --> me["个人中心"] + admin["管理员"] --> movies["电影管理页"] + movies --> recoAdmin["推荐概览页"] +``` + +关键状态流： + +- 用户：游客 -> 注册用户 +- 电影交互：未评分 -> 已评分 +- 推荐：冷启动 -> 有偏好推荐 + +推荐技术栈： + +- React 或 Vue +- TypeScript +- Ant Design / shadcn/ui + +建议页面： + +| 页面 | 路径 | 说明 | +|------|------|------| +| 首页 | `/` | 热门电影、推荐入口 | +| 电影列表页 | `/movies` | 搜索、筛选、分页 | +| 电影详情页 | `/movies/:id` | 简介、标签、评分、收藏 | +| 推荐页 | `/recommendations` | 个性化推荐列表 | +| 个人中心 | `/me` | 评分与收藏记录 | +| 管理后台 | `/admin/movies` | 电影维护 | + +前端关键组件： + +- 电影卡片 +- 搜索筛选栏 +- 评分组件 +- 收藏按钮 +- 推荐理由展示卡片 +- 后台表格和编辑弹窗 + +## 6. 后端实现 + +推荐技术栈： + +- Java 17 +- Spring Boot 3 +- Spring Web +- Spring Data JPA +- MySQL 8 +- JWT 鉴权 + +后端模块： + +- `auth` +- `movies` +- `ratings` +- `favorites` +- `recommendations` +- `admin` + +建议数据表： + +```sql +users ( + id bigint primary key auto_increment, + email varchar(120), + password_hash varchar(255), + role varchar(20), + 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, + created_at datetime +) + +favorites ( + id bigint primary key auto_increment, + user_id bigint, + movie_id bigint, + created_at datetime +) + +recommendation_logs ( + id bigint primary key auto_increment, + user_id bigint, + strategy varchar(50), + result_count int, + created_at datetime +) +``` + +## 6.1 后台指标与监控 + +后台建议至少查看这些指标： + +- 电影总数 +- 日评分数 +- 收藏率 +- 推荐点击率 +- 热门标签分布 +- 冷启动用户占比 + +基础监控建议： + +- 推荐接口响应耗时 +- 评分写入成功率 +- 数据库慢查询 +- 缓存命中率（如果用了 Redis） + +## 7. 推荐策略 + +第一版推荐策略建议： + +- 基于标签偏好 +- 结合用户评分权重 +- 冷启动时叠加热门电影 +- 过滤已评分/已收藏电影 + +推荐结果应展示： + +- 推荐分值 +- 推荐理由 +- 对应标签 + +## 8. 接口草案 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/auth/register` | 注册 | +| `POST` | `/api/auth/login` | 登录 | +| `GET` | `/api/movies` | 电影列表，支持搜索与分页 | +| `GET` | `/api/movies/:id` | 电影详情 | +| `POST` | `/api/movies/:id/ratings` | 提交评分 | +| `POST` | `/api/movies/:id/favorite` | 收藏电影 | +| `DELETE` | `/api/movies/:id/favorite` | 取消收藏 | +| `GET` | `/api/recommendations` | 获取推荐结果 | +| `GET` | `/api/me/profile` | 获取用户资料和行为摘要 | +| `POST` | `/api/admin/movies` | 新增电影 | +| `PATCH` | `/api/admin/movies/:id` | 编辑电影 | + +`GET /api/recommendations` 返回示例： + +```json +{ + "items": [ + { + "movieId": 12, + "title": "Interstellar", + "score": 0.91, + "reason": "你近期给高分的科幻与冒险标签影片较多" + } + ] +} +``` + +## 9. 关键业务规则 + +- 每个用户对同一电影只保留一条评分 +- 收藏与评分都能影响推荐 +- 管理员接口必须单独鉴权 +- 推荐结果至少返回 10 条或当前可用最大值 + +## 10. 非功能要求 + +- 推荐结果应可解释 +- 列表与详情页加载要可接受 +- 管理员接口与普通用户接口权限严格分离 +- 推荐缓存和行为数据允许后续扩展 + +## 11. 开发顺序建议 + +1. 登录与用户体系 +2. 电影列表与详情 +3. 评分与收藏 +4. 推荐接口 +5. 后台管理页 + +## 12. 待确认项 + +- 前端选 React 还是 Vue +- 推荐解释文案是后端拼接还是前端渲染 +- 是否需要影片导入脚本 +- 后台是否要包含标签管理 diff --git a/docs/zh-cn/stage-2/assignments/movie-recommendation-springboot/index.md b/docs/zh-cn/stage-2/assignments/movie-recommendation-springboot/index.md index 1769a1f..87b3f95 100644 --- a/docs/zh-cn/stage-2/assignments/movie-recommendation-springboot/index.md +++ b/docs/zh-cn/stage-2/assignments/movie-recommendation-springboot/index.md @@ -1,294 +1,119 @@ -# 电影推荐网 (Spring Boot) +# Spring Boot 电影推荐系统开发实战 -推荐系统是最典型的“看起来简单，做起来很像真实业务系统”的题目。 +这个项目不是“做一个电影列表页”，而是围绕一份真实 PRD，把一个带推荐能力的内容产品从想法推进到可上线原型。 -这次大作业你会从“电影列表网站”升级到“可登录、可评分、可推荐、可管理”的完整产品原型。 +你会同时看到三件事： -::: tip 🎯 这次做什么？ -打造一个 **电影推荐网站（Spring Boot）**。用户登录后可浏览电影、搜索筛选、评分收藏，并获得个性化推荐；管理员可维护电影数据、查看用户行为统计与推荐效果。 +- 项目要做成什么 +- 如何基于 PRD 拆解并推进开发 +- 最后应该交付出什么样的效果 + +::: tip PRD 入口 +本项目的需求文档在同级页面： [查看 PRD](./PRD.md) :::
-## 为什么这个题目适合 Stage 2？ +## 这个项目到底在做什么？ -因为它能一次性把你带过 5 个关键能力： +这是一个带推荐能力的电影网站： -- **后端工程化**：Controller / Service / Repository 分层 -- **数据建模**：用户、电影、标签、评分、推荐结果 -- **业务逻辑**：搜索筛选、评分行为、收藏与历史 -- **推荐算法入门**：规则推荐或协同过滤 -- **管理能力**：后台维护数据与查看指标 +- 用户可以浏览、搜索、评分、收藏电影 +- 系统根据用户行为给出推荐结果 +- 管理员可以维护电影数据和查看推荐效果 -做完后你不仅能讲“我写了个网站”，还能讲清楚“推荐是怎么跑起来的”。 +## 开发过程怎么走？ -## 先看系统全景 +### 1. 先看 PRD，不要上来就写代码 -```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: 返回电影卡片数据 -``` +### 2. 先让 AI 生成“骨架版” -## 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 -``` +### 3. 再进入“监工模式” -
- - - -
+你要重点盯这几件事： -## 3. 做推荐：先做“可解释推荐”，再做“更聪明推荐” +- 列表、详情、评分、收藏是不是闭环 +- 推荐结果是不是和行为数据联动 +- 推荐理由是不是可解释 +- 后台电影数据和用户行为是不是能查看 -### 推荐模块拆分建议 - -| 模块 | 职责 | -|------|------| -| CandidateService | 召回候选电影（未看、同标签、热门） | -| RankingService | 按偏好分数排序并截断 TopN | -| ExplainService | 生成“为什么推荐这部电影”文案 | -| RecommendationController | 对外提供推荐接口 | - -### 推荐流程图 +### 4. 最后做联调和上线 ```mermaid flowchart TD - A["读取用户评分历史"] --> B["统计用户标签偏好"] - B --> C["召回候选电影"] - C --> D["计算综合分数"] - D --> E["过滤已看电影"] - E --> F["生成 Top N 推荐"] - F --> G["返回推荐原因与标签命中"] + prd["PRD"] --> web["前端页面"] + web --> auth["用户鉴权"] + web --> movie["电影列表 / 详情"] + web --> behavior["评分 / 收藏"] + behavior --> reco["推荐逻辑"] + reco --> db["数据库"] + admin["后台管理"] --> db ``` -### 第三步：让 AI IDE 帮你实现推荐接口 +## 怎么让 AI 帮你生成？ ```text -请帮我实现 Spring Boot 推荐接口 GET /api/recommendations。 - -业务规则： -1. 根据用户最近评分记录统计偏好标签权重 -2. 从同标签电影中召回候选 -3. 结合全站热门度做加权 -4. 去掉用户已经评分过的电影 -5. 返回前 12 条推荐，并附带推荐理由 +请基于当前 PRD，帮我生成一个 Spring Boot 电影推荐系统的前端骨架。 要求： -- Service 层拆分清晰 -- SQL 或 JPA 查询可读 -- 返回结构包含 movieId、title、score、reason -- 给出最小可跑通的单元测试示例 +1. 页面包括：首页、电影列表、电影详情、推荐页、个人中心、后台管理 +2. 先只生成页面结构和假数据，不接真实接口 +3. 风格要像真实内容产品，而不是课堂 demo ``` -### 第四步：补管理员统计页 +## 怎么“监工”才有效？ -第一版至少展示这些指标： +| 检查项 | 要看什么 | +|------|------| +| 页面是否对 | 页面数量、功能是否符合 PRD | +| 接口是否对 | movies、ratings、favorites、recommendations 是否闭环 | +| 数据是否对 | 用户行为是否影响推荐结果 | +| 推荐是否对 | 推荐理由是否清晰、结果是否可解释 | +| 演示是否对 | 是否能演示“浏览 -> 评分 -> 推荐变化” | -- 总用户数 -- 总电影数 -- 最近 7 天评分次数 -- 推荐接口成功率与平均耗时 +## 最后的预期效果 -这样你可以快速发现系统是否健康，而不是“看起来能用但实际经常失败”。 +- 一套可运行的电影推荐系统 +- 一份同级 PRD 文档 +- 浏览、评分、收藏、推荐、后台管理 +- Spring Boot 后端与推荐逻辑 +- README 和演示方案 -## 4. 上线与交付 +## 验收标准 -### 交付物 +| 维度 | 最低达标 | +|------|------| +| PRD 对齐 | 页面、功能、数据结构基本符合 PRD | +| 产品闭环 | 浏览、评分、收藏、推荐可以跑通 | +| 后台能力 | 电影数据和推荐效果可查看 | +| 工程完整度 | 前端、后端、数据库、推荐接口已接通 | +| 展示能力 | 可以清楚演示“从 PRD 到成品”的过程 | -- Spring Boot 后端仓库（含数据库初始化脚本） -- 前端项目仓库（或单仓 monorepo） -- 可访问演示地址 -- README（本地启动、环境变量、部署方式） -- 60 秒演示视频 - -### 验收标准 - -| 维度 | 最低达标 | 加分项 | -|------|------|------| -| 基础功能 | 注册登录、电影浏览、评分收藏都可用 | 评论、观看历史等拓展功能 | -| 推荐质量 | 推荐列表可生成且有理由 | 支持冷启动策略与个性化解释 | -| 工程质量 | 接口分层清晰，错误可追踪 | 有单测与缓存优化 | -| 管理能力 | 管理员可维护电影和标签 | 有统计看板和告警阈值 | -| 交付能力 | 可部署、文档完整、可复现 | CI/CD 或自动化脚本 | - -## 提交前最后检查 - - - - -
    -
    • -
    • -
    • -
    • -
    • -
    • -
- +::: tip 🚀 完成后你会得到什么？ +你得到的不只是一个电影站，而是一套“内容 + 行为 + 推荐”型产品的开发样例。 +::: diff --git a/docs/zh-cn/stage-2/assignments/simple-grocery-microservices/PRD.md b/docs/zh-cn/stage-2/assignments/simple-grocery-microservices/PRD.md new file mode 100644 index 0000000..e8a1523 --- /dev/null +++ b/docs/zh-cn/stage-2/assignments/simple-grocery-microservices/PRD.md @@ -0,0 +1,393 @@ +# PRD：生鲜电商微服务系统 + +状态：Draft v0.1 +目标：先明确服务拆分、数据边界和交易主链路，再进入开发。 + +## 1. 项目定位 + +这是一个用来练微服务拆分和服务协作的电商系统。重点不是做复杂运营功能，而是跑通： + +- 商品浏览 +- 下单 +- 扣库存 +- 查订单 +- 管理端调库存 + +一句话定义： +做一个由网关、鉴权、商品、库存、订单协作完成交易闭环的生鲜电商微服务系统。 + +系统总览： + +```mermaid +flowchart LR + WWW["www.xxx.com
官网前台"] --> GW["API Gateway"] + APP["app.xxx.com
用户前台"] --> GW + ADMIN["admin.xxx.com
后台管理台"] --> GW + GW --> AUTH["Auth Service"] + GW --> CATALOG["Catalog Service"] + GW --> INVENTORY["Inventory Service"] + GW --> ORDER["Order Service"] +``` + +## 1.0 技术选型建议 + +- 前端框架：`Next.js` +- 网关：`Node.js + Express/Fastify` +- 服务层：`Node.js + Express/Fastify` +- 数据库：`PostgreSQL` +- 鉴权：`JWT` +- 编排：`Docker Compose` + +站点入口约定： + +- 官网前台：`www.xxx.com` +- 用户前台：`app.xxx.com` +- 后台管理台：`admin.xxx.com` + +## 1.1 竞品参考（官方） + +- [Instacart](https://www.instacart.com/) + +## 1.2 产品借鉴点 + +本项目的产品设计建议参考真实生鲜电商产品： + +- 借鉴 `Instacart` 的用户购物路径：从商品浏览到购物车、订单查看都应足够直接 +- 商品页和购物车页应强调价格、库存状态和操作反馈 +- 管理端页面应更像运营后台，突出商品、库存、订单状态管理 +- 前台页面不需要做得很复杂，但一定要把“下单链路”做顺 +- 微服务拆分服务于业务边界，前端体验要尽量像统一产品，而不是几个接口拼起来 + +## 1.3 竞品页面拆解 + +建议重点参考的竞品页面结构： + +- `Instacart` 首页与商品分类页 + - 重点看：分类、商品卡片、购物入口的清晰程度 +- `Instacart` 购物车与结算体验 + - 重点看：从商品到下单的路径是否顺畅 +- 电商后台常见商品/订单管理思路 + - 重点看：列表、状态筛选、库存调整这些基础运营动作 + +因此本项目建议： + +- 用户端更强调“快速下单” +- 管理端更强调“状态管理” +- 微服务架构隐藏在后台，前台体验仍应统一 + +## 2. 目标用户与核心目标 + +目标用户： + +- 浏览商品并下单的普通用户 +- 调整商品与库存的管理员 + +核心目标： + +- 用户下单链路完整可追踪 +- 库存与订单状态一致 +- 每个服务边界清晰，可独立维护 + +## 3. MVP 范围 + +第一版必须包含： + +- API Gateway +- Auth 服务 +- Catalog 服务 +- Inventory 服务 +- Order 服务 +- 用户端商品列表/详情/下单 +- 管理端商品与库存管理 + +第一版不做： + +- 真实支付 +- 优惠券和促销 +- 秒杀 +- 消息队列集群 +- 分布式事务框架 + +## 4. 角色与权限 + +| 角色 | 权限 | +|------|------| +| 普通用户 | 浏览商品、下单、查看自己的订单 | +| 管理员 | 商品上下架、库存调整、查看订单 | + +## 5. 前端实现 + +## 5.1 页面架构总览 + +当前 PRD 定义为 `3 套入口，9 个大页面`： + +- 官网前台 `1` 个大页面 +- 用户前台 `4` 个大页面 +- 后台管理台 `4` 个大页面 + +### A. 官网前台 `www.xxx.com` + +#### 1. 官网首页 `www:/` + +核心功能： + +- 品类入口 +- 活动区 +- 登录入口 + +### B. 用户前台 `app.xxx.com` + +#### 2. 商品列表页 `app:/products` + +核心功能： + +- 浏览分类 +- 查看商品卡片 +- 加入购物车 + +#### 3. 商品详情页 `app:/products/:id` + +核心功能： + +- 查看商品详情 +- 查看库存状态 +- 加入购物车 + +#### 4. 购物车页 `app:/cart` + +核心功能： + +- 查看购物车 +- 修改数量 +- 提交订单 + +#### 5. 订单页 `app:/orders` + +核心功能： + +- 查看我的订单 +- 查看订单状态 + +### C. 后台管理台 `admin.xxx.com` + +#### 6. 后台首页 `admin:/` + +核心功能： + +- 商品数 +- 库存预警 +- 订单概览 + +#### 7. 商品管理页 `admin:/products` + +核心功能： + +- 上下架商品 +- 编辑价格与分类 + +#### 8. 库存管理页 `admin:/inventory` + +核心功能： + +- 查看库存 +- 调整库存 + +#### 9. 订单管理页 `admin:/orders` + +核心功能： + +- 查看订单 +- 筛选状态 + +## 5.2 关键用户链路 + +```mermaid +flowchart TD + user["用户"] --> products["商品列表"] + products --> detail["商品详情"] + detail --> cart["购物车"] + cart --> order["提交订单"] + order --> inventory["库存扣减"] + inventory --> orders["我的订单"] + admin["管理员"] --> inventoryAdmin["库存管理"] + admin --> orderAdmin["订单管理"] +``` + +关键状态流： + +- 订单：待创建 -> 已创建 -> 已完成 / 已取消 +- 库存：可用 -> 预扣 -> 确认扣减 / 回滚 + +推荐技术栈： + +- Next.js +- TypeScript +- Tailwind CSS + +建议页面： + +| 页面 | 路径 | 说明 | +|------|------|------| +| 首页 | `/` | 商品列表与分类 | +| 商品详情 | `/products/:id` | 商品信息与加入购物车 | +| 购物车 | `/cart` | 确认下单 | +| 我的订单 | `/orders` | 查看订单历史 | +| 管理后台商品页 | `/admin/products` | 商品维护 | +| 管理后台库存页 | `/admin/inventory` | 库存调整 | +| 管理后台订单页 | `/admin/orders` | 订单列表与状态 | + +前端关键组件： + +- 商品卡片 +- 购物车抽屉/页面 +- 订单状态标签 +- 管理后台表格 +- 库存调整弹窗 + +## 6. 后端实现 + +推荐技术栈： + +- Node.js + Express/Fastify +- PostgreSQL +- Docker Compose + +服务拆分： + +| 服务 | 职责 | +|------|------| +| `api-gateway` | 统一路由、鉴权、聚合返回 | +| `auth-service` | 注册、登录、JWT 校验 | +| `catalog-service` | 商品信息、分类、上下架 | +| `inventory-service` | 库存查询、预扣、回滚 | +| `order-service` | 订单创建、状态流转、查询 | + +建议数据模型： + +```sql +users ( + id uuid primary key, + email text, + password_hash text, + role text, + created_at timestamptz +) + +products ( + id uuid primary key, + name text, + category text, + price_cents int, + status text, + created_at timestamptz +) + +inventory_items ( + id uuid primary key, + product_id uuid, + available_quantity int, + reserved_quantity int, + updated_at timestamptz +) + +orders ( + id uuid primary key, + user_id uuid, + total_amount_cents int, + status text, + created_at timestamptz +) + +order_items ( + id uuid primary key, + order_id uuid, + product_id uuid, + quantity int, + price_cents int +) +``` + +## 6.1 后台指标与监控 + +后台建议至少查看这些指标： + +- 下单成功率 +- 库存回滚次数 +- 热销商品排行 +- 订单状态分布 +- 库存预警数 + +基础监控建议： + +- 网关错误率 +- 鉴权服务成功率 +- 库存服务超时率 +- 订单创建失败率 + +## 7. 下单主链路 + +主流程： + +1. 用户提交订单 +2. Gateway 完成鉴权 +3. Order 服务校验商品 +4. Inventory 服务预扣库存 +5. Order 服务创建订单 +6. 成功则确认库存，失败则补偿回滚 + +关键规则： + +- 库存不足直接失败 +- 同一个订单只允许一次成功创建 +- 所有状态变化要可追踪 + +## 8. 接口草案 + +外部接口统一走 Gateway： + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/auth/register` | 注册 | +| `POST` | `/api/auth/login` | 登录 | +| `GET` | `/api/catalog/products` | 商品列表 | +| `GET` | `/api/catalog/products/:id` | 商品详情 | +| `POST` | `/api/orders` | 创建订单 | +| `GET` | `/api/orders/my` | 当前用户订单列表 | +| `GET` | `/api/orders/:id` | 订单详情 | +| `PATCH` | `/api/inventory/:productId` | 管理员调整库存 | +| `POST` | `/api/admin/products` | 管理员新增商品 | +| `PATCH` | `/api/admin/products/:id` | 管理员编辑商品 | + +`POST /api/orders` 请求示例： + +```json +{ + "items": [ + { "productId": "p1", "quantity": 2 }, + { "productId": "p2", "quantity": 1 } + ] +} +``` + +## 9. 非功能要求 + +- 本地一键启动 +- 服务之间日志可追踪 +- 接口返回结构统一 +- 关键链路有错误处理和补偿逻辑 + +## 10. 开发顺序建议 + +1. Monorepo/Workspaces 与 Gateway +2. Auth 服务 +3. Catalog 与 Inventory +4. Order 下单闭环 +5. 前端用户端与管理端 +6. Docker Compose 与文档 + +## 11. 待确认项 + +- 前端是否做购物车持久化 +- 服务间通信先用 HTTP 还是预留消息机制 +- 商品与库存是否拆独立数据库 +- 管理端是否允许直接修改订单状态 diff --git a/docs/zh-cn/stage-2/assignments/simple-grocery-microservices/index.md b/docs/zh-cn/stage-2/assignments/simple-grocery-microservices/index.md index 656020c..ba5f256 100644 --- a/docs/zh-cn/stage-2/assignments/simple-grocery-microservices/index.md +++ b/docs/zh-cn/stage-2/assignments/simple-grocery-microservices/index.md @@ -1,253 +1,119 @@ -# 简单买菜微服务网站 +# 生鲜电商微服务系统开发实战 -做完单体应用后，很多同学会进入一个新困惑：功能越来越多，代码还能写，但项目越来越难维护。 +这个项目不是“做一个买菜网站”，而是围绕一份真实 PRD，把一个微服务电商系统从想法推进到可运行原型。 -这个大作业的目标，就是让你在一个可控规模里，体验一次“从单体到微服务”的完整过程。 +你会同时看到三件事： -::: tip 🎯 这次做什么？ -打造一个 **简单买菜微服务网站**。用户可以浏览商品、下单、查看订单；管理员可以管理商品与库存。后端拆成多个服务，通过 API 网关统一对外提供接口。 +- 项目要做成什么 +- 如何基于 PRD 拆解并推进开发 +- 最后应该交付出什么样的效果 + +::: tip PRD 入口 +本项目的需求文档在同级页面： [查看 PRD](./PRD.md) :::
-## 为什么这个项目值得做？ +## 这个项目到底在做什么？ -这个题目看起来是“买菜网站”，本质上练的是三个能力： +这是一个生鲜电商微服务系统： -- **拆服务**：学会按业务边界拆分，而不是按技术层硬拆 -- **控复杂度**：在多服务协作下保持清晰的接口和数据流 -- **做稳定链路**：让“下单 -> 扣库存 -> 查订单”能够稳定可追踪 +- 用户端负责浏览商品、下单、查看订单 +- 管理端负责商品、库存和订单管理 +- 后端按业务拆成网关、鉴权、商品、库存、订单服务 -这会直接影响你后续做电商、SaaS 后台、内容平台等多模块项目的上限。 +## 开发过程怎么走？ -## 先看全景：系统由哪些模块组成？ +### 1. 先看 PRD，不要上来就写代码 -```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. 定边界：先把范围控制住 +### 2. 先让 AI 生成“骨架版” -### 建议服务拆分 +第一轮先生成： -第一版只保留 4 个核心服务： +- 用户端首页、商品页、购物车、订单页 +- 管理端商品、库存、订单管理页 +- API Gateway +- auth、catalog、inventory、order 四个服务骨架 -| 服务 | 职责 | -|------|------| -| `auth-service` | 登录、注册、令牌校验、角色识别 | -| `catalog-service` | 商品列表、商品详情、分类查询 | -| `inventory-service` | 库存查询、库存扣减、库存回滚 | -| `order-service` | 创建订单、查询订单、订单状态管理 | +### 3. 再进入“监工模式” -### 建议角色与页面 +你要重点盯这几件事： -| 角色 | 页面 | 关键动作 | -|------|------|------| -| 用户 | 首页、商品页、购物车、订单页 | 浏览商品、下单、看订单 | -| 管理员 | 商品管理、库存管理、订单管理 | 上下架商品、调库存、查看异常订单 | +- 网关路由是否正确 +- JWT 和角色权限是否正确 +- 商品和库存数据是否一致 +- 下单后库存和订单状态是否闭环 +- 失败补偿是否真的能回滚 -### 范围控制（一定要先做“能交付”的版本） - -- 只做最小支付模拟，不接真实支付网关 -- 不做复杂促销（满减、优惠券、拼团） -- 不做推荐算法，商品排序先按上架时间或销量 -- 不做分布式事务框架，先用“本地事务 + 失败补偿”思路 -- 不做消息中间件集群，第一版可同步调用 - -## 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: 返回订单号和状态 -``` - -### 失败补偿思路（避免“扣了库存却没订单”） +### 4. 最后做联调和上线 ```mermaid flowchart TD - A["创建订单请求"] --> B["校验库存是否足够"] - B -->|不足| C["返回失败"] - B -->|充足| D["预扣库存"] - D --> E["写入订单记录"] - E -->|成功| F["确认扣减完成"] - E -->|失败| G["回滚库存"] - G --> H["记录补偿日志"] - F --> I["返回下单成功"] + prd["PRD"] --> fe["前端页面"] + fe --> gw["API Gateway"] + gw --> auth["Auth Service"] + gw --> catalog["Catalog Service"] + gw --> inventory["Inventory Service"] + gw --> order["Order Service"] + order --> inventory ``` -## 3. 推荐技术栈 - -- **前端**：Next.js + TypeScript + Tailwind CSS + shadcn/ui -- **服务端**：Node.js + Express / Fastify -- **网关**：Express Gateway 或自建 BFF 网关 -- **数据库**：PostgreSQL（每个服务独立库或独立 schema） -- **缓存（可选）**：Redis（热商品列表、会话短缓存） -- **部署**：Docker Compose（本地）+ Zeabur / Railway（云端） - -## 4. 分步实现路径（可直接照做） - -
- - - -
- -### 第一步：起项目骨架与网关 +## 怎么让 AI 帮你生成？ ```text -请帮我搭建一个买菜微服务项目骨架。 +请基于当前 PRD，帮我生成一个生鲜电商微服务系统的项目骨架。 要求： -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） +1. 生成前端用户端和管理端骨架 +2. 生成 api-gateway、auth-service、catalog-service、inventory-service、order-service 五个目录 +3. 每个服务先只做最小可运行入口 +4. 先不接真实数据库和支付 ``` -### 第二步：先做鉴权，再做业务接口 +## 怎么“监工”才有效？ -先完成： +| 检查项 | 要看什么 | +|------|------| +| 页面是否对 | 页面数量、入口、功能是否符合 PRD | +| 接口是否对 | catalog、inventory、orders 是否闭环 | +| 权限是否对 | 用户与管理员权限是否隔离 | +| 数据是否对 | 商品、库存、订单状态是否一致 | +| 演示是否对 | 是否能演示“浏览 -> 下单 -> 查单 -> 管理库存” | -- 用户注册 / 登录 -- JWT 发放和校验中间件 -- 网关统一鉴权（白名单接口可放行） +## 最后的预期效果 -```text -请帮我实现 auth-service 的最小鉴权链路。 +- 一套可运行的生鲜电商微服务系统 +- 一份同级 PRD 文档 +- 用户端、管理端、网关和 4 个核心服务 +- JWT 鉴权、库存扣减、订单管理 +- README 和演示方案 -目标： -1. POST /register -2. POST /login -3. 输出 access token -4. gateway 中间件可以验证 token 并把 userId、role 注入请求上下文 -5. 提供一个受保护示例接口用于测试 -``` +## 验收标准 -### 第三步：商品与库存服务 +| 维度 | 最低达标 | +|------|------| +| PRD 对齐 | 页面、功能、数据结构基本符合 PRD | +| 产品闭环 | 浏览、下单、库存、查单可以跑通 | +| 后台能力 | 商品、库存、订单管理可以查看 | +| 工程完整度 | 前端、网关、服务、数据库链路已接通 | +| 展示能力 | 可以清楚演示“从 PRD 到成品”的过程 | -优先做这几个接口： - -- `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. 提交前最后检查 - - - - -
    -
    • -
    • -
    • -
    • -
    • -
    • -
- - -::: tip -这个作业最重要的不是“服务越多越好”，而是你能不能把边界、协作和失败处理讲清楚并做扎实。 +::: tip 🚀 完成后你会得到什么？ +你得到的不只是一个电商练习题，而是一套微服务项目的开发样例。后面再做复杂后端系统时，这会非常有用。 ::: diff --git a/docs/zh-cn/stage-2/assignments/traffic-data-visualization-go/PRD.md b/docs/zh-cn/stage-2/assignments/traffic-data-visualization-go/PRD.md new file mode 100644 index 0000000..6e533b7 --- /dev/null +++ b/docs/zh-cn/stage-2/assignments/traffic-data-visualization-go/PRD.md @@ -0,0 +1,361 @@ +# PRD：Go 交通数据分析与可视化平台 + +状态：Draft v0.1 +目标：先明确数据产品的口径、模块和接口，再进入实现。 + +## 1. 项目定位 + +这是一个“数据接入 + 聚合分析 + 看板展示”的完整型项目。重点是把原始交通数据转换成可读的分析结果和告警。 + +一句话定义： +做一个支持事件接入、窗口聚合、异常检测和大屏展示的 Go 数据分析平台。 + +系统总览： + +```mermaid +flowchart LR + SOURCE["数据源 / 模拟器"] --> API["Go API"] + API --> RAW["原始数据表"] + RAW --> AGG["聚合任务"] + AGG --> ALERT["告警规则"] + AGG --> DASH["Dashboard API"] + ALERT --> DASH + ADMIN["admin.xxx.com
管理后台"] --> DASH +``` + +## 1.0 技术选型建议 + +- 后端框架：`Go + Gin/Fiber` +- 数据库：`PostgreSQL` +- 聚合任务：`robfig/cron` +- 前端：`React / Next.js` +- 图表：`ECharts` 或 `AntV` + +站点入口约定： + +- 分析看板：`app.xxx.com` +- 后台管理台：`admin.xxx.com` + +## 1.1 竞品参考（官方） + +- [TomTom Traffic Index](https://www.tomtom.com/traffic-index/) + +## 1.2 产品借鉴点 + +本项目的产品设计建议参考真实交通分析产品： + +- 借鉴 `TomTom Traffic Index` 的指标表达方式：趋势、拥堵程度、城市/路口排行应直观可读 +- 看板首页应优先展示关键指标和异常信息，而不是堆很多图 +- 趋势页、排行页、告警页要有清晰的分工 +- 管理端应强调数据导入、任务状态和告警处理，而不是只看静态图表 +- 整体设计要更像数据产品和运营看板，而不是普通后台列表 + +## 1.3 竞品页面拆解 + +建议重点参考的竞品页面结构： + +- `TomTom Traffic Index` 的总览页 + - 重点看：如何用少量关键指标快速建立全局认知 +- `TomTom Traffic Index` 的趋势和排名表达 + - 重点看：图表和排行如何帮助用户快速理解问题 +- 数据产品常见监控页 + - 重点看：告警、数据状态和任务状态如何分区展示 + +因此本项目建议： + +- 总览页强调关键指标 +- 趋势页强调时间变化 +- 告警页强调异常定位 +- 管理端强调数据导入和任务健康状态 + +## 2. 目标用户与核心目标 + +目标用户： + +- 关注交通趋势和拥堵状态的分析人员 +- 查看异常告警与处理结果的管理员 + +核心目标： + +- 原始数据可稳定接入 +- 聚合指标可查询 +- 告警可见、可处理 +- 可视化页面可支撑汇报和演示 + +## 3. MVP 范围 + +第一版必须包含： + +- 数据接入接口 +- 原始数据落库 +- 定时聚合任务 +- 异常检测规则 +- 趋势图、Top 路口、告警面板 +- 管理端数据导入或模拟数据入口 + +第一版不做： + +- Kafka/Flink 级流处理 +- 复杂 GIS 地图引擎 +- 机器学习预测模型 +- 多租户平台权限 + +## 4. 角色与权限 + +| 角色 | 权限 | +|------|------| +| 分析用户 | 查看看板、趋势、排行榜 | +| 管理员 | 导入数据、处理告警、查看任务状态 | + +## 5. 前端实现 + +## 5.1 页面架构总览 + +当前 PRD 定义为 `2 套入口，6 个大页面`： + +- 用户看板 `4` 个大页面 +- 后台管理台 `2` 个大页面 + +### A. 分析看板 `app.xxx.com` + +#### 1. 总览页 `app:/dashboard` + +核心功能： + +- 总车流 +- 当前告警数 +- 最拥堵路口 + +#### 2. 趋势页 `app:/dashboard/trend` + +核心功能： + +- 车流趋势图 +- 时间范围切换 + +#### 3. 路口排行页 `app:/dashboard/intersections` + +核心功能： + +- 拥堵排行 +- 关键路口指标 + +#### 4. 告警页 `app:/alerts` + +核心功能： + +- 查看告警 +- 筛选级别 +- 标记处理状态 + +### B. 后台管理台 `admin.xxx.com` + +#### 5. 数据导入页 `admin:/imports` + +核心功能： + +- 导入 CSV +- 查看导入任务状态 + +#### 6. 任务与告警管理页 `admin:/operations` + +核心功能： + +- 查看聚合任务状态 +- 查看告警处理记录 + +## 5.2 关键用户链路 + +```mermaid +flowchart TD + source["数据源"] --> ingest["接入接口"] + ingest --> raw["原始数据表"] + raw --> agg["聚合任务"] + agg --> trend["趋势页"] + agg --> rank["排行页"] + agg --> alerts["告警页"] + admin["管理员"] --> imports["数据导入页"] + imports --> ingest + admin --> ops["任务与告警管理页"] +``` + +关键状态流： + +- 数据事件：接收成功 / 校验失败 +- 聚合任务：待执行 -> 执行中 -> 成功 / 失败 +- 告警：新建 -> 已确认 -> 已处理 + +推荐技术栈： + +- React / Next.js +- ECharts / AntV +- TypeScript + +建议页面： + +| 页面 | 路径 | 说明 | +|------|------|------| +| 总览看板 | `/dashboard` | 今日流量、拥堵指数、告警数 | +| 趋势页 | `/dashboard/trend` | 分时趋势图 | +| 路口分析页 | `/dashboard/intersections` | Top 路口排行 | +| 告警页 | `/alerts` | 告警列表与处理状态 | +| 数据管理页 | `/admin/imports` | 导入数据、查看任务日志 | + +前端关键组件： + +- 指标卡片 +- 折线图/柱状图 +- 排行榜表格 +- 告警列表 +- 时间范围筛选器 + +## 6. 后端实现 + +推荐技术栈： + +- Go +- Gin 或 Fiber +- PostgreSQL +- robfig/cron + +后端模块： + +- `ingest` +- `aggregation` +- `alerts` +- `dashboard` +- `imports` +- `admin` + +建议数据表： + +```sql +raw_traffic_events ( + id bigserial primary key, + intersection_id text, + event_time timestamptz, + vehicle_count int, + avg_speed numeric, + source text, + created_at timestamptz +) + +traffic_agg_1m ( + id bigserial primary key, + intersection_id text, + window_start timestamptz, + total_vehicles int, + avg_speed numeric, + congestion_index numeric +) + +traffic_agg_5m ( + id bigserial primary key, + intersection_id text, + window_start timestamptz, + total_vehicles int, + avg_speed numeric, + congestion_index numeric +) + +alerts ( + id bigserial primary key, + intersection_id text, + level text, + rule_code text, + status text, + message text, + created_at timestamptz, + resolved_at timestamptz +) + +import_jobs ( + id bigserial primary key, + filename text, + status text, + total_rows int, + success_rows int, + failed_rows int, + created_at timestamptz +) +``` + +## 6.1 后台指标与监控 + +后台建议至少查看这些指标： + +- 接入事件总数 +- 聚合任务成功率 +- 告警总数与处理率 +- 热点路口排行 +- 导入任务成功率 + +基础监控建议： + +- 接入接口错误率 +- 聚合任务耗时 +- 数据库写入失败率 +- 看板查询接口耗时 + +## 7. 指标与规则 + +第一版指标： + +- 每分钟车流量 +- 每 5 分钟聚合车流量 +- 平均车速 +- 拥堵指数 +- Top10 拥堵路口 + +第一版告警规则： + +- 当前流量高于近 5 分钟均值阈值 +- 当前速度连续低于阈值 + +## 8. 接口草案 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/traffic/events` | 写入单条交通事件 | +| `POST` | `/api/traffic/import` | 上传 CSV 或批量导入 | +| `GET` | `/api/dashboard/overview` | 获取概览卡片数据 | +| `GET` | `/api/dashboard/trend` | 获取趋势图数据 | +| `GET` | `/api/dashboard/intersections/top` | 获取拥堵路口排行 | +| `GET` | `/api/alerts` | 获取告警列表 | +| `PATCH` | `/api/alerts/:id/resolve` | 处理告警 | +| `GET` | `/api/admin/import-jobs` | 获取导入任务状态 | + +`POST /api/traffic/events` 请求示例： + +```json +{ + "intersectionId": "A-101", + "timestamp": "2026-04-01T08:30:00+08:00", + "vehicleCount": 42, + "avgSpeed": 18.6, + "source": "simulator" +} +``` + +## 9. 非功能要求 + +- 聚合任务可重复执行且结果稳定 +- API 返回结构统一 +- 导入失败要能定位原因 +- 看板查询响应时间可接受 + +## 10. 开发顺序建议 + +1. Go API 骨架与数据表 +2. 事件接入接口 +3. 聚合任务 +4. 告警规则 +5. Dashboard 查询接口 +6. 前端图表页 + +## 11. 待确认项 + +- 是否提供 CSV 导入作为主要演示入口 +- 是否需要地图视图 +- 告警阈值是否写死还是后台可配 +- 前端图表库选 ECharts 还是 AntV diff --git a/docs/zh-cn/stage-2/assignments/traffic-data-visualization-go/index.md b/docs/zh-cn/stage-2/assignments/traffic-data-visualization-go/index.md index 5b14dc2..2d51f34 100644 --- a/docs/zh-cn/stage-2/assignments/traffic-data-visualization-go/index.md +++ b/docs/zh-cn/stage-2/assignments/traffic-data-visualization-go/index.md @@ -1,239 +1,120 @@ -# 交通大数据可视化分析 (Go项目) +# Go 交通数据分析平台开发实战 -很多同学学 Go 时会卡在一个问题：会写接口，但不知道怎么把“数据处理能力”和“业务展示能力”组合成一个完整项目。 +这个项目不是“写几个 Go 接口”，而是围绕一份真实 PRD，把一个数据接入、聚合、告警、可视化的产品原型推进出来。 -这个大作业就是为了解这个问题。你会做一个可运行的交通数据平台，从数据接入、清洗、聚合，到可视化展示和告警，一条链路走完。 +你会同时看到三件事： -::: tip 🎯 这次做什么？ -打造一个 **交通大数据可视化分析平台（Go 后端）**。系统可以接收交通流量数据，完成时间窗口聚合与异常检测，并在可视化页面展示趋势、拥堵热力、路口排名和告警记录。 +- 项目要做成什么 +- 如何基于 PRD 拆解并推进开发 +- 最后应该交付出什么样的效果 + +::: tip PRD 入口 +本项目的需求文档在同级页面： [查看 PRD](./PRD.md) :::
-## 为什么这个项目值得做？ +## 这个项目到底在做什么？ -这个题目同时练了三种在真实项目里非常关键的能力： +这是一个 Go 交通数据分析平台： -- **工程能力**：Go 接口设计、并发处理、任务调度 -- **数据能力**：时间序列聚合、指标建模、异常检测 -- **产品能力**：把分析结果变成可读、可操作的可视化页面 +- 接收原始交通事件 +- 做窗口聚合 +- 计算趋势和拥堵指标 +- 生成告警 +- 在前端看板中展示结果 -做完后，你不只是“写了个后端”，而是能说清一个数据产品如何从输入走到决策。 +## 开发过程怎么走？ -## 1. 项目全景与范围控制 +### 1. 先看 PRD，不要上来就写代码 -### 系统模块图 +先确认： -```mermaid -flowchart LR - source["数据源
路口设备 / CSV / 模拟器"] --> ingest["Go Ingest API"] - ingest --> clean["数据清洗与标准化"] - clean --> rawdb["原始数据表"] - clean --> agg["聚合任务（1m/5m/1h）"] - agg --> aggdb["聚合结果表"] - agg --> detect["异常检测任务"] - detect --> alertdb["告警表"] - aggdb --> dashboard["可视化看板"] - alertdb --> dashboard -``` +- 数据来源和字段是否拍板 +- 指标口径是否清楚 +- 告警规则是否先收敛到简单版本 +- 看板页面范围是否合理 -### 建议分析维度 +### 2. 先让 AI 生成“骨架版” -第一版只聚焦这些核心指标： +第一轮先生成： -- 时间窗口车流量（每分钟 / 每 5 分钟 / 每小时） -- 路口拥堵指数（可用速度反比或排队长度估算） -- TOP 拥堵路口排名 -- 异常突增告警（同比前 5 分钟或滑动均值） +- Go API 服务骨架 +- 数据接入接口 +- 聚合任务骨架 +- 总览看板、趋势页、告警页 -### 范围控制（防止项目失控） +### 3. 再进入“监工模式” -- 第一版不做实时流处理平台（如 Kafka/Flink 集群） -- 第一版不做复杂地图引擎，热力可先用网格或散点替代 -- 第一版不做机器学习预测，先用规则阈值异常检测 -- 第一版不做多租户权限系统，只保留普通用户 + 管理员 +你要重点盯这几件事： -## 2. 数据链路与时序 +- 原始数据是否正确入库 +- 聚合口径是否一致 +- 告警规则是否符合预期 +- 看板展示和后端数据是否一致 +- API 是否有统一返回结构和错误处理 -### 数据从接入到看板的主流程 - -```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: 返回图表数据 -``` - -### 异常检测逻辑（简版） +### 4. 最后做联调和上线 ```mermaid flowchart TD - A["读取最近 10 分钟聚合值"] --> B["计算近 5 分钟均值"] - B --> C["当前值 > 均值 * 阈值?"] - C -->|否| D["正常，无告警"] - C -->|是| E["生成告警记录"] - E --> F["标记级别（低/中/高）"] - F --> G["写入 alerts 表"] + prd["PRD"] --> ingest["数据接入 API"] + ingest --> raw["原始数据表"] + raw --> agg["聚合任务"] + agg --> alert["告警规则"] + agg --> dashboard["看板接口"] + alert --> dashboard ``` -## 3. 推荐技术栈 - -- **后端**：Go + Gin / Fiber -- **数据处理**：Go `cron` / `robfig/cron`（定时聚合） -- **数据库**：PostgreSQL（可选 TimescaleDB） -- **缓存（可选）**：Redis（热点看板数据） -- **前端**：React / Next.js + ECharts / AntV -- **部署**：Docker Compose + Zeabur / Railway / 自托管 - -## 4. 分步实现路径 - -
- - - -
- -### 第一步：搭 Go 项目骨架和数据模型 +## 怎么让 AI 帮你生成？ ```text -请帮我创建一个 Go 交通数据分析项目骨架。 +请基于当前 PRD，帮我生成一个 Go 交通数据分析平台骨架。 要求： -1. 使用 Gin（或 Fiber）创建 API 服务 -2. 按 handler / service / repository / model 分层 -3. 设计并创建数据表： - - raw_traffic_events - - traffic_agg_1m - - traffic_agg_5m - - alerts -4. 提供一个健康检查接口 /health -5. 给出本地启动步骤（含数据库连接配置） +1. 使用 Gin 或 Fiber +2. 提供数据接入接口 +3. 提供聚合任务骨架 +4. 提供 dashboard 和 alerts 接口骨架 +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` | +| 接口是否对 | ingest、dashboard、alerts 是否闭环 | +| 数据是否对 | 原始表、聚合表、告警表是否一致 | +| 指标是否对 | 趋势、排名、告警口径是否合理 | +| 页面是否对 | 看板展示和后端结果是否对齐 | +| 演示是否对 | 是否能演示“接入 -> 聚合 -> 告警 -> 展示” | -## 6. 交付物要求 +## 最后的预期效果 -- 可运行项目代码（Go API + 可视化前端） -- 数据库表结构与初始化脚本 -- README（架构图、运行说明、指标解释） -- 关键页面截图（趋势图、排名、告警） -- 60 秒到 120 秒演示视频 +- 一套可运行的 Go 数据分析平台 +- 一份同级 PRD 文档 +- 数据接入、聚合、告警、看板展示 +- README 和演示方案 -## 7. 验收标准 +## 验收标准 -| 维度 | 最低达标 | 加分项 | -|------|------|------| -| 数据链路 | 接入、存储、聚合、展示完整跑通 | 支持重放历史数据和批量导入 | -| 分析能力 | 有趋势、排名、告警三个核心模块 | 告警支持分级与处理状态流转 | -| Go 工程质量 | 代码分层清晰，错误处理明确 | 有结构化日志与基础性能优化 | -| 可视化质量 | 关键图表可读，指标口径一致 | 增加地图层或交互筛选能力 | -| 交付完整度 | README、截图、演示视频齐全 | 有线上演示地址和压测说明 | +| 维度 | 最低达标 | +|------|------| +| PRD 对齐 | 页面、功能、数据结构基本符合 PRD | +| 产品闭环 | 接入、聚合、告警、看板可以跑通 | +| 分析能力 | 趋势、排行、告警三个核心模块可用 | +| 工程完整度 | Go API、数据库、前端看板链路已接通 | +| 展示能力 | 可以清楚演示“从 PRD 到成品”的过程 | -## 8. 提交前最后检查 - - - - -
    -
    • -
    • -
    • -
    • -
    • -
    • -
- - -::: tip -这个作业的关键，不是图表多炫，而是你能不能保证“口径一致、链路闭环、告警可信”。 +::: tip 🚀 完成后你会得到什么？ +你得到的不只是一个接口项目，而是一套“数据接入 + 数据产品”型项目的开发样例。 ::: diff --git a/docs/zh-cn/stage-2/assignments/travel-planning-agent-platform/PRD.md b/docs/zh-cn/stage-2/assignments/travel-planning-agent-platform/PRD.md new file mode 100644 index 0000000..6434d27 --- /dev/null +++ b/docs/zh-cn/stage-2/assignments/travel-planning-agent-platform/PRD.md @@ -0,0 +1,405 @@ +# PRD：智能旅游规划 Agent 编排平台 + +状态：Draft v0.1 +目标：先确认这个 Agent 产品的最小可用范围，再进入开发。 + +## 1. 项目定位 + +这是一个面向真实旅行规划场景的 AI 产品，不只是聊天，而是把结构化输入转成可执行行程。 + +一句话定义： +做一个可以生成、保存、调整与导出旅行计划的 Agent 编排平台。 + +系统总览： + +```mermaid +flowchart LR + WWW["www.xxx.com
官网前台"] --> API["应用 API / 管理 API"] + APP["app.xxx.com
用户工作台"] --> API + ADMIN["admin.xxx.com
后台管理台"] --> API + API --> AUTH["Supabase Auth"] + API --> DB["Supabase Postgres"] + API --> MODEL["LLM / Agent 编排层"] + API --> EXT["天气 / 地图 / POI 外部信息源"] +``` + +## 1.0 技术选型建议 + +- 前端框架：`Next.js App Router` +- 用户鉴权：`Supabase Auth` +- 数据库：`Supabase Postgres` +- 模型层：统一后端服务调用大模型 +- 可选缓存：`Redis` + +站点入口约定： + +- 官网前台：`www.xxx.com` +- 用户工作台：`app.xxx.com` +- 后台管理台：`admin.xxx.com` + +## 1.1 竞品参考（官方） + +- [Wanderlog](https://wanderlog.com/) + +## 1.2 产品借鉴点 + +本项目的产品设计建议参考真实旅行规划产品的做法： + +- 借鉴 `Wanderlog` 的路线规划表达方式：输入后直接看到可编辑的每日行程，而不是只返回一大段文本 +- 行程详情应突出日期、地点、预算、移动顺序和注意事项 +- 历史记录页应像“我的行程库”，支持再次打开和二次生成 +- 后台页应强调热门目的地、失败任务和用户反馈，而不是只看系统日志 +- 整体设计要体现“行程产品”感，而不是“聊天回答”感 + +## 1.3 竞品页面拆解 + +建议重点参考的竞品页面结构： + +- `Wanderlog` 首页 + - 重点看：如何同时讲清楚 itinerary、map、budget、collaboration 这些核心价值 +- `Wanderlog` 行程页 + - 重点看：一天一天的安排、地图与列表并存、预算与预订信息并列 +- `Wanderlog` Pro 页面 + - 重点看：如何把高级功能做成清晰权益，而不是一长串技术描述 + +因此本项目建议： + +- 规划页更像“行程编辑台” +- 详情页更像“可执行 itinerary” +- 历史页更像“我的旅行库” +- 后台页更像“运营与任务中心” + +## 2. 目标用户与核心目标 + +目标用户： + +- 想快速获得 3 到 7 天行程安排的普通用户 +- 需要预算与节奏建议的自由行用户 +- 维护平台质量和任务健康状态的管理员 + +核心目标： + +- 用户能在一次表单提交后得到结构化行程 +- 用户能保存历史计划并再次编辑/重生成 +- 平台能记录失败任务和生成质量反馈 + +## 3. MVP 范围 + +第一版必须包含： + +- 规划表单页 +- 行程详情页 +- 历史计划页 +- 计划保存与重生成 +- 预算拆分 +- 导出文本/PDF 占位能力 +- 后台查看任务与失败日志 + +第一版不做： + +- 真正的机票/酒店预订 +- 多城市复杂路线联排 +- 实时票价与库存同步 +- 多人协同编辑 +- 多语言输出 + +## 4. 角色与权限 + +| 角色 | 权限 | +|------|------| +| 普通用户 | 创建计划、查看历史、导出、反馈 | +| 管理员 | 查看热门目的地、失败任务、用户反馈 | + +## 5. 前端实现 + +## 5.1 页面架构总览 + +当前 PRD 定义为 `3 套入口，8 个大页面`： + +- 官网前台 `1` 个大页面 +- 用户工作台 `5` 个大页面 +- 后台管理台 `2` 个大页面 + +### A. 官网前台 `www.xxx.com` + +#### 1. 官网首页 `www:/` + +核心功能： + +- 产品介绍 +- 典型使用场景 +- Demo 行程展示 +- CTA + +### B. 用户工作台 `app.xxx.com` + +#### 2. 登录页 `app:/login` + +核心功能： + +- 登录 +- 注册入口 + +#### 3. 规划页 `app:/planner` + +核心功能： + +- 输入旅行需求 +- 选择偏好与预算 +- 发起规划任务 + +#### 4. 行程详情页 `app:/trips/:id` + +核心功能： + +- 查看每日行程 +- 查看预算拆分 +- 再次生成和导出 + +#### 5. 历史计划页 `app:/history` + +核心功能： + +- 查看历史计划 +- 重新打开 +- 重新生成 + +#### 6. 反馈与导出页 `app:/exports` + +核心功能： + +- 导出计划 +- 提交反馈 + +### C. 后台管理台 `admin.xxx.com` + +#### 7. 后台首页 `admin:/` + +核心功能： + +- 热门目的地 +- 任务成功率 +- 失败任务数 + +#### 8. 任务与反馈页 `admin:/runs` + +核心功能： + +- 查看失败任务 +- 查看用户反馈 +- 排查异常计划 + +## 5.2 关键用户链路 + +```mermaid +flowchart TD + user["用户"] --> login["登录"] + login --> planner["规划页"] + planner --> submit["提交旅行需求"] + submit --> agent["Agent 编排层"] + agent --> result["生成结构化行程"] + result --> detail["行程详情页"] + detail --> history["保存到历史计划"] + detail --> export["导出 / 分享"] + admin["管理员"] --> runs["任务与反馈页"] + runs --> optimize["排查失败任务"] +``` + +关键状态流： + +- 规划任务：待生成 -> 生成中 -> 成功 / 失败 +- 行程：草稿 -> 已保存 -> 已导出 +- 反馈：未处理 -> 已查看 -> 已关闭 + +推荐技术栈： + +- Next.js App Router +- TypeScript +- Tailwind CSS + +建议页面： + +| 页面 | 路径 | 说明 | +|------|------|------| +| 首页 | `/` | 产品介绍与创建入口 | +| 规划页 | `/planner` | 输入需求并提交 | +| 行程详情页 | `/trips/:id` | 查看每日计划、预算和注意事项 | +| 历史记录页 | `/history` | 查看历史计划 | +| 管理后台 | `/admin` | 查看任务状态和平台统计 | + +前端关键组件： + +- 旅行需求表单 +- 任务进度状态条 +- Day by Day 行程卡片 +- 预算拆分卡片 +- 历史记录列表 +- 错误重试与反馈组件 + +## 6. 后端实现 + +推荐技术栈： + +- Node.js + NestJS/Express +- PostgreSQL / Supabase +- LLM API +- 可选 Redis 做短缓存 + +后端模块： + +- `auth` +- `trip-plans` +- `planner` +- `exports` +- `admin` +- `feedback` + +建议数据表： + +```sql +trip_plans ( + id uuid primary key, + user_id uuid, + origin text, + destination text, + start_date date, + end_date date, + budget numeric, + preferences jsonb, + pace text, + status text, + created_at timestamptz +) + +itinerary_days ( + id uuid primary key, + trip_plan_id uuid, + day_index int, + title text, + summary text, + day_budget numeric +) + +itinerary_items ( + id uuid primary key, + itinerary_day_id uuid, + start_time text, + end_time text, + place_name text, + category text, + notes text, + estimated_cost numeric +) + +planner_runs ( + id uuid primary key, + trip_plan_id uuid, + provider text, + latency_ms int, + status text, + error_message text, + created_at timestamptz +) + +trip_feedback ( + id uuid primary key, + trip_plan_id uuid, + user_id uuid, + score int, + comment text, + created_at timestamptz +) +``` + +## 6.1 后台指标与监控 + +后台建议至少查看这些指标： + +- 日规划任务数 +- 规划成功率 +- 平均生成耗时 +- 热门目的地排行 +- 用户反馈评分分布 +- 导出次数 + +基础监控建议： + +- 模型调用成功率 +- 外部信息源失败率 +- 任务重试次数 +- 数据库存取耗时 + +## 7. 功能清单 + +必须完成： + +- 创建旅行计划 +- 返回结构化每日行程 +- 查看历史计划 +- 重生成计划 +- 预算拆分 +- 管理端查看失败任务 + +可选增强： + +- 热门目的地榜单 +- POI 数据二次校验 +- 导出为分享图 + +## 8. 接口草案 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/trips/plan` | 创建新的规划任务 | +| `GET` | `/api/trips/:id` | 获取计划详情 | +| `POST` | `/api/trips/:id/regenerate` | 按原条件重新生成 | +| `PATCH` | `/api/trips/:id/preferences` | 更新偏好后重算 | +| `GET` | `/api/history` | 获取历史计划列表 | +| `POST` | `/api/trips/:id/export` | 导出行程 | +| `POST` | `/api/trips/:id/feedback` | 提交用户反馈 | +| `GET` | `/api/admin/planner-runs` | 获取生成日志 | + +`POST /api/trips/plan` 请求示例： + +```json +{ + "origin": "上海", + "destination": "成都", + "startDate": "2026-05-01", + "endDate": "2026-05-04", + "budget": 3500, + "preferences": ["美食", "历史文化"], + "pace": "standard" +} +``` + +## 9. 关键业务规则 + +- 第一版限制单目的地 +- 只支持 3 到 7 天 +- 预算必须返回总预算与每日预算 +- 失败任务必须可重试 +- 生成结果需要有结构化 JSON，不能只返回自由文本 + +## 10. 非功能要求 + +- 规划结果要有稳定的结构化 JSON +- 长任务必须有状态反馈 +- 外部信息源失败时要优雅降级 +- 导出失败可重试 +- 移动端至少可查看详情和历史计划 + +## 11. 开发顺序建议 + +1. 规划页表单与 mock 结果 +2. 创建计划与详情接口 +3. 历史记录与重生成 +4. 导出与反馈 +5. 管理后台日志页 + +## 12. 待确认项 + +- 第一版是否需要接外部天气/地图数据 +- 导出先做 PDF 还是纯文本下载 +- 行程生成是否需要“省钱/均衡/深度游”预设模板 +- 管理端是否需要查看用户反馈详情 diff --git a/docs/zh-cn/stage-2/assignments/travel-planning-agent-platform/index.md b/docs/zh-cn/stage-2/assignments/travel-planning-agent-platform/index.md index 00de111..4845fc6 100644 --- a/docs/zh-cn/stage-2/assignments/travel-planning-agent-platform/index.md +++ b/docs/zh-cn/stage-2/assignments/travel-planning-agent-platform/index.md @@ -1,282 +1,120 @@ -# 智能旅游规划 Agent 平台 +# 智能旅游规划 Agent 平台开发实战 -很多人做 AI 项目时，常见问题不是模型不会调，而是应用链路不完整：能聊天，但不能真正“规划一趟旅行”。 +这个项目不是“做一个会聊天的旅行助手”，而是围绕一份真实 PRD，把一个可执行的旅行规划产品从想法推进到可上线原型。 -这个大作业的目标，就是把一个“会说话的 Demo”做成“可执行的产品原型”。 +你会同时看到三件事： -::: tip 🎯 这次做什么？ -打造一个 **智能旅游规划 Agent 平台**。用户输入出发地、目的地、日期、预算和偏好后，系统自动生成每日行程、预算拆分、景点与餐饮建议，并支持导出或保存计划。管理员可查看热门目的地、生成成功率和用户反馈。 +- 项目要做成什么 +- 如何基于 PRD 拆解并推进开发 +- 最后应该交付出什么样的效果 + +::: tip PRD 入口 +本项目的需求文档在同级页面： [查看 PRD](./PRD.md) :::
-## 为什么这个题目值得做？ +## 这个项目到底在做什么？ -因为它同时覆盖了现代 AI 应用最关键的 4 类能力： +这是一个旅行规划 Agent 平台： -- **结构化输入**：把用户偏好转成可计算参数 -- **Agent 编排**：任务拆解、信息收集、行程生成与校验 -- **真实业务约束**：预算、时长、交通可行性、营业时间 -- **产品化交付**：保存历史、查看详情、导出分享 +- 用户输入出发地、目的地、日期、预算和偏好 +- 系统生成每日行程、预算拆分和建议 +- 用户可以保存历史计划、再次生成、导出 +- 管理员可以查看热门目的地、失败任务和反馈 -做完这个项目，你学到的不只是“会调用 LLM”，而是“会做一个可落地的 AI 产品”。 +## 开发过程怎么走？ -## 先看全景：系统主链路是什么？ +### 1. 先看 PRD，不要上来就写代码 + +先确认： + +- 第一版是否只做单目的地 +- 行程输出是否必须结构化 +- 导出能力做多深 +- 后台统计和任务日志范围是否清楚 + +### 2. 先让 AI 生成“骨架版” + +第一轮先生成： + +- 首页 +- 规划页 +- 行程详情页 +- 历史记录页 +- 管理后台页 + +### 3. 再进入“监工模式” + +你要重点盯这几件事： + +- 输入表单字段是否和 PRD 一致 +- 行程输出是否真的结构化 +- 预算、节奏和每日活动是否合理 +- 历史计划和重生成是否闭环 +- 失败任务有没有被记录 + +### 4. 最后做联调和上线 ```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 / 图片 / 文本"] + prd["PRD"] --> planner["规划页"] + planner --> agent["Agent 编排层"] + agent --> model["模型调用"] + agent --> db["数据库"] + db --> history["历史计划"] + db --> admin["后台统计与日志"] ``` -```mermaid -sequenceDiagram - autonumber - actor U as 用户 - participant FE as 前端页面 - participant API as 后端 API - participant AG as Agent 服务 - participant DB as 数据库 +## 怎么让 AI 帮你生成？ - 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 +```text +请基于当前 PRD，帮我生成一个智能旅游规划 Agent 平台的前端骨架。 + +要求： +1. 页面包括：首页、规划页、行程详情页、历史记录页、管理页 +2. 规划页左侧是表单，右侧是结果预览 +3. 先只生成页面结构和假数据，不接真实接口 +4. 风格要像现代 AI 产品 ``` -## 1. 定范围：先把题目收住，避免“越做越大” +## 怎么“监工”才有效？ -### 角色设计 - -| 角色 | 核心动作 | +| 检查项 | 要看什么 | |------|------| -| 普通用户 | 创建旅行计划、查看每日行程、调整偏好、保存与导出 | -| 管理员 | 查看使用统计、热门城市、失败任务日志、用户反馈 | +| 页面是否对 | 页面数量、功能是否符合 PRD | +| 接口是否对 | 规划、详情、历史、重生成是否闭环 | +| 输出是否对 | 行程结果是不是结构化且可读 | +| 数据是否对 | trip、itinerary、logs 是否一致 | +| 演示是否对 | 是否能演示“输入 -> 生成 -> 保存 -> 再次生成” | -### 核心页面 +## 最后的预期效果 -| 页面 | 路径 | 说明 | -|------|------|------| -| 首页 | `/` | 介绍产品价值与创建入口 | -| 规划页 | `/planner` | 填写需求并发起生成 | -| 行程详情页 | `/trips/:id` | 查看每日计划与预算拆分 | -| 历史记录页 | `/history` | 查看过去的规划任务 | -| 管理后台 | `/admin` | 查看统计数据与任务健康状态 | +- 一套可运行的旅行规划 Agent 平台 +- 一份同级 PRD 文档 +- 首页、规划、详情、历史、后台五类页面 +- Agent 编排、结构化输出、历史管理、后台统计 +- README 和演示方案 -### 第一版边界（强烈建议） +## 验收标准 -- 只做单人行程，不做多人协同编辑 -- 只支持 1 个目的地，不做多城市跳转 -- 只做 3-7 天行程，不做超长旅行计划 -- 先使用一种语言输出，不做多语言切换 -- 先接一个外部信息源，避免数据接入过多导致失控 +| 维度 | 最低达标 | +|------|------| +| PRD 对齐 | 页面、功能、数据结构基本符合 PRD | +| 产品闭环 | 规划、保存、历史、重生成可以跑通 | +| 后台能力 | 任务统计和失败日志可以查看 | +| 工程完整度 | 前端、后端、数据库、模型调用链路已接通 | +| 展示能力 | 可以清楚演示“从 PRD 到成品”的过程 | -## 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 页面。 - -输入字段： -- 出发地 -- 目的地 -- 出行日期（开始/结束） -- 总预算 -- 旅行偏好（自然风光/历史文化/亲子/美食） -- 每日节奏（轻松/标准/高强度） - -输出区域： -- 每日行程卡片 -- 预算拆分 -- 交通建议 -- 注意事项 - -要求： -- 点击“生成行程”后显示任务进度 -- 失败时显示可重试按钮 -- 首屏有示例数据引导 -``` - -
- - - -
- -## 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/空态/错误态完整 | 支持导出分享 | -| 运维交付 | 可部署、文档可复现 | 有后台统计看板 | - -## 提交前最后检查 - - - - -
    -
    • -
    • -
    • -
    • -
    • -
    • -
- +::: tip 🚀 完成后你会得到什么？ +你得到的不只是一个旅游聊天 Demo，而是一套带结构化输入、Agent 编排和任务管理的 AI 产品开发样例。 +::: diff --git a/docs/zh-cn/stage-2/index.md b/docs/zh-cn/stage-2/index.md index 29653e1..0577fa3 100644 --- a/docs/zh-cn/stage-2/index.md +++ b/docs/zh-cn/stage-2/index.md @@ -137,32 +137,32 @@ flowchart LR