企业官网建设流程全解析

easy-vibe 生鲜电商微服务系统实战：从 PRD 需求拆分到网关联调上线的完整开发指南

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe

导读

本指南是 easy-vibe 课程 Stage 2（初中级开发）综合实战环节的核心作业文档，要求你围绕一份真实的 PRD（产品需求文档），从零构建一个生鲜电商微服务系统。与前面单服务项目不同，该项目的后端按业务拆分为鉴权、商品、库存、订单等多个独立服务，并通过 API 网关统一对外。读完本指南，你将掌握服务边界的拆分方法、API 网关路由与 JWT 鉴权的实现思路，以及如何通过"预扣—确认/回滚"机制解决跨服务的数据一致性问题，最终交付一个可演示、可部署的微服务原型。

项目概述与定位

本项目要求你围绕真实 PRD 从零完成生鲜电商微服务系统。它是 Stage 2 的综合实战环节——微服务架构在实际工作中非常常见，掌握服务拆分和网关路由的基本思路后，你能应对更复杂的后端系统设计。

整个产品由两个子系统构成：

后端按业务拆分为以下五个独立服务：

项目的一句话定义：做一个由网关、鉴权、商品、库存、订单协作完成交易闭环的生鲜电商微服务系统。本项目重点不在复杂运营功能，而是跑通商品浏览、下单、扣库存、查订单、管理端调库存这条完整链路。

前置知识

开始本项目之前，你应该已经掌握以下内容：

• 前端页面设计与组件库使用（UI 设计、现代组件库）
• 后端接口设计与开发（接口代码编写）
• 数据库基础与 Supabase（从数据库到 Supabase）
• Git 工作流与部署（Git 和 GitHub、部署 Web 应用）

学习目标

完成本实战后，你将能够：

1. 阅读 PRD 并提取微服务系统的开发任务清单
2. 按业务领域拆分服务边界（鉴权、商品、库存、订单）
3. 设计和实现 API 网关路由
4. 处理库存扣减和订单一致性等跨服务问题
5. 完成端到端联调，交付可演示的微服务原型

第一部分：需求分析

1.1 阅读 PRD

本项目对应的需求文档见 PRD（中文版）。打开 PRD 后，重点回答以下问题：

• 服务如何拆分？每个服务的职责边界是什么？
• 前台和管理端分别有哪些页面？
• 下单后库存扣减的策略是什么？成功 / 失败 / 超时各怎么处理？
• 第一版哪些复杂能力（如分布式事务、消息队列）先不做？

::: warning 如果以上问题没有明确答案，不要开始写代码。需求理解不清楚是导致返工的最常见原因。 :::

1.2 明确 MVP 范围与技术选型

根据 PRD，第一版必须包含：API Gateway、Auth 服务、Catalog 服务、Inventory 服务、Order 服务、用户端商品列表/详情/下单、管理端商品与库存管理。

第一版明确不做：真实支付、优惠券和促销、秒杀、消息队列集群、分布式事务框架。也就是说，跨服务一致性先通过"调用链补偿"这类轻量手段解决，而不是引入重型的分布式事务中间件。

PRD 给出的技术选型建议：

• 前端框架：Next.js（搭配 TypeScript、Tailwind CSS）
• 网关：Node.js + Express/Fastify
• 服务层：Node.js + Express/Fastify
• 数据库：PostgreSQL
• 鉴权：JWT
• 编排：Docker Compose

站点入口约定为三套域名：官网前台www.xxx.com、用户前台app.xxx.com、后台管理台admin.xxx.com。

1.3 确认系统架构

PRD 定义了三套入口、九个页面的总体结构（官网前台 1 个、用户前台 4 个、后台管理台 4 个），整体请求链路如下：

从架构图中可以看到两个关键设计决策：前端永不直连业务服务，一切请求统一走网关；Order Service 与 Inventory Service 之间存在直接的跨服务调用（下单时扣库存），这是本项目要重点解决的一致性难点所在。

1.4 页面结构与关键用户链路

九个页面的核心功能如下：

关键用户链路：

PRD 建议借鉴 Instacart 的用户购物路径：从商品浏览到购物车、订单查看都应足够直接；用户端强调"快速下单"，管理端强调"状态管理"，前端体验尽量像统一产品而非几个接口的拼凑。关键状态流为：订单：待创建 → 已创建 → 已完成 / 已取消；库存：可用 → 预扣 → 确认扣减 / 回滚。

第二部分：搭建项目骨架

2.1 生成项目结构

进入开发后，第一步是让 AI 编程工具帮你生成骨架。提示词参考：

请基于当前 PRD，帮我生成一个生鲜电商微服务系统的项目骨架。 要求： 1. 生成前端用户端和管理端骨架 2. 生成 api-gateway、auth-service、catalog-service、inventory-service、order-service 五个目录 3. 每个服务先只做最小可运行入口 4. 先不接真实数据库和支付

这里的关键约束是"最小可运行"：骨架阶段不接数据库、不接支付，只为每个服务生成一个能启动、能响应健康检查的入口，从而先把工程边界和调用链立起来。

2.2 验证项目结构

逐项检查：

• 五个服务目录结构清晰
• API Gateway 可以启动并转发请求
• 各服务健康检查接口可用
• 前端用户端和管理端页面可访问

第三部分：迭代开发

3.1 按模块推进

骨架验证通过后，按以下顺序逐模块补齐接口：

1. API Gateway：路由配置、JWT 校验中间件
2. Auth Service：注册、登录、JWT 颁发
3. Catalog Service：商品 CRUD、列表查询
4. Inventory Service：库存查询、库存扣减
5. Order Service：订单创建、状态流转、库存联动
6. 管理端：商品管理、库存管理、订单管理

PRD 给出的推荐开发顺序与此一致：Monorepo/Workspaces 与 Gateway → Auth 服务 → Catalog 与 Inventory → Order 下单闭环 → 前端用户端与管理端 → Docker Compose 与文档。先打通后端主链路，再接前端，最后做编排。

3.2 设计数据模型

按 PRD 建议，各服务的数据模型可以这样建（使用 PostgreSQL）：

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 )

注意inventory_items中available_quantity（可用库存）与reserved_quantity（预扣库存）两个字段的区分——这正是"预扣—确认/回滚"机制的数据基础：下单先预扣，成功后把预扣转为确认扣减，失败或超时则回滚预扣。

3.3 下单主链路与一致性处理

PRD 定义的下单主流程如下：

1. 用户提交订单
2. Gateway 完成鉴权
3. Order 服务校验商品
4. Inventory 服务预扣库存
5. Order 服务创建订单
6. 成功则确认库存，失败则补偿回滚

关键规则：

• 库存不足直接失败
• 同一个订单只允许一次成功创建
• 所有状态变化要可追踪

3.4 外部接口草案

所有外部接口统一走 Gateway，接口草案如下：

POST /api/orders请求体示例：

{ "items": [ { "productId": "p1", "quantity": 2 }, { "productId": "p2", "quantity": 1 } ] }

3.5 模块自检

每个模块完成后，按下面的检查项逐项验证：

此外，PRD 还提出了非功能要求，也应纳入自检范围：本地一键启动、服务之间日志可追踪、接口返回结构统一、关键链路有错误处理和补偿逻辑。角色权限上，普通用户只能浏览商品、下单、查看自己的订单；管理员才有商品上下架、库存调整、查看订单的权限。

第四部分：联调与上线

4.1 端到端测试

所有模块打通后，至少验证以下场景：

• 浏览商品 → 加入购物车 → 下单 → 查看订单
• 管理员 → 添加商品 → 更新库存 → 查看订单

4.2 后台指标与监控

PRD 建议管理后台至少展示这些指标：下单成功率、库存回滚次数、热销商品排行、订单状态分布、库存预警数；基础监控建议关注网关错误率、鉴权服务成功率、库存服务超时率、订单创建失败率。

交付物

完成本项目后，你需要提交以下内容：

• 可访问的线上演示链接
• 源码仓库链接（含 README）
• PRD 文档
• 核心页面截图（商品列表、下单页、订单页、管理后台）
• 60 秒演示视频

评分标准

参考资料

• UI 设计
• 使用现代组件库更新你的界面
• 从数据库到 Supabase
• 大模型辅助编写接口代码与接口文档
• Git 和 GitHub 工作流
• 如何部署 Web 应用
• 生鲜电商微服务系统 PRD

【免费下载链接】easy-vibe💻 vibe coding 101｜The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe