本科软件工程课程项目：一套支持「客户下单 / 自提点团长分单 / 管理员运营」三种角色的社区生鲜团购系统。 仓库为多进程单体仓库，包含前端、Node API、Spring Boot 服务与 PostgreSQL 数据库脚本。
浏览器
│
▼
client/ React 19 + Vite 7 + Tailwind CSS 4 ──HTTP──▶ server/ Express 5 + pg
(客户 / 团长 / 管理员三种界面) │ JWT 鉴权 + 角色守卫
▼
PostgreSQL（database/ 中的 schema、存储过程、触发器、视图）
backend/ Spring Boot 2.5（Java 17，MySQL + Redis）：并行的 Java 端服务骨架，当前提供 /api/hello
- 业务主链路走
server/+ PostgreSQL：下单、扣库存、成团、分单等逻辑都在这里，库存扣减放在database/procedures.sql的place_order存储过程里做并发控制。 backend/是 Spring Boot 技术栈的对照实现骨架（若依风格目录结构 + Docker/CI），目前只有示例接口。- 三种角色的权限由
server/middleware/auth.js（校验 JWT）与server/middleware/authorizeRole.js（校验角色）共同完成， 角色取值：customer/leader/admin。
.
├── client/ # React 19 + Vite 7 前端（Tailwind CSS 4）
│ ├── src/pages/ # 按角色划分的页面：首页、团购详情、购物车、我的订单、团长工作台、管理后台
│ ├── src/components/ # Navbar、Footer、ProtectedRoute、倒计时、骨架屏等
│ └── src/context/ # AuthContext（JWT 登录态）、CartContext（购物车）
├── server/ # Express 5 API（PostgreSQL）
│ ├── index.js # 路由挂载与启动入口
│ ├── routes/ # auth / products / orders / leader / admin
│ ├── middleware/ # JWT 鉴权、角色守卫
│ ├── test/ # node:test 冒烟测试（无需数据库）
│ └── scripts/init-db.sql # 建库脚本
├── backend/ # Spring Boot 2.5（Java 17，MySQL + Redis）服务骨架
│ ├── src/main/java/com/example/backend/
│ ├── src/main/resources/application.yml
│ └── docker/ # Dockerfile 与 docker-compose（MySQL + Redis + 应用）
├── database/ # PostgreSQL：schema.sql / procedures.sql / triggers.sql / views.sql / seeds.sql
├── tests/ # Playwright 端到端用例（根目录 playwright.config.js）
└── .github/workflows/ # ci.yml（三端构建+测试）、cd.yml（SSH 部署）、e2e.yml（手动触发）
| 组件 | 版本 | 必需 |
|---|---|---|
| Node.js | ≥ 20（Vite 7 要求） | 是 |
| PostgreSQL | 14+ | 是 |
| JDK | 17 | 仅 backend/ 需要 |
| Maven | 3.8+ | 仅 backend/ 需要 |
| MySQL 8 / Redis | — | 仅 backend/ 需要 |
createdb community_db
psql -d community_db -f database/schema.sql # 建表
psql -d community_db -f database/procedures.sql # place_order 存储过程（下单并发控制）
psql -d community_db -f database/triggers.sql
psql -d community_db -f database/views.sql
psql -d community_db -f database/seeds.sql # 演示数据cd server
cp .env.example .env # 修改 DATABASE_URL 与 JWT_SECRET
npm install
PORT=3001 npm run dev # 前端默认访问 3001 端口前端
client/src/config.js默认请求http://<当前主机>:3001/api。server/.env.example里的PORT默认是 3000，本地联调请设为PORT=3001， 或用VITE_API_BASE_URL覆盖前端地址。
cd client
npm install
npm run dev # http://localhost:5173先编辑 backend/src/main/resources/application.yml 中的 MySQL 连接（你的数据库名 / 你的MySQL密码），然后：
cd backend
mvn spring-boot:run # http://localhost:8080/api/hello或使用 Docker 一键起 MySQL + Redis + 应用：
cd backend/docker
DB_MYSQL_ROOT_PASSWORD=yourpassword docker-compose up -d| 方法 & 路径 | 鉴权 | 说明 |
|---|---|---|
POST /api/auth/register |
— | 注册（customer / leader / admin） |
POST /api/auth/login |
— | 登录，返回 JWT |
GET /api/products、GET /api/group-buys、GET /api/group-buys/:id/items |
— | 商品与团购活动 |
GET /api/orders、GET /api/orders/mine、POST /api/orders、GET /api/orders/:orderId |
JWT | 下单与订单查询（下单调用 place_order 存储过程） |
GET /api/leader/* |
JWT + leader |
自提点维度的一键分单、收货确认、配送轨迹 |
GET /api/admin/orders/to-ship、POST /api/admin/orders/:id/ship、/admin/stats/today-summary 等 |
JWT + admin |
发货、商品管理、运营看板 |
GET /api/protected |
JWT | 调试用的受保护示例接口 |
| 类型 | 命令 | 依赖 |
|---|---|---|
API 冒烟测试（server/test/） |
cd server && npm test |
无需数据库 |
| 前端静态检查 / 构建 | cd client && npm run lint && npm run build |
Node |
| 后端单元/集成测试 | cd backend && mvn test |
JDK 17 + Maven |
端到端测试（tests/） |
npm install && npx playwright install chromium && npm run test:e2e |
需要前端 + API 已启动 |
端到端测试默认打到 http://localhost:5173，可用环境变量切换目标：
E2E_BASE_URL=http://192.168.1.10:5173 npm run test:e2eci.yml：三个并行任务——后端（Maven 构建 + 测试 + 产物上传）、API（npm ci && npm test）、前端（npm ci && lint && build）。cd.yml：CI 在main成功后自动部署，通过 SSH 在服务器上执行docker-compose pull && docker-compose up -d； 未配置HOST/USERNAME/SSH_KEY时自动跳过，也可手动触发。e2e.yml：手动触发，需要先配置仓库变量E2E_BASE_URL指向一套可访问的测试环境。
- 数据库变更一律以
database/*.sql为准（幂等写法，CREATE OR REPLACE/DROP ... IF EXISTS），并在 README 的初始化步骤中同步。 - 新增接口需同时更新第 5 节的接口表；涉及金额的字段统一使用
DECIMAL(10,2)，不使用浮点。 - 下单必须走
place_order存储过程，保证并发下的库存一致性，不要在应用层拼接「查询-判断-更新」。 - 新增页面按角色放入
client/src/pages/，并在App.jsx中通过<ProtectedRoute roles={[...]}>声明可见角色。 - 提交前应至少通过：
cd server && npm test、cd client && npm run lint && npm run build。