# elm

**Repository Path**: HRJ_666/elm

## Basic Information

- **Project Name**: elm
- **Description**: 软件工程综合实践饿了么项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-10-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 轻量级外卖服务平台（仿饿了么）

一个前后端分离的轻量级外卖服务平台，覆盖「客户点餐 → 商家接单 → 平台运营」的完整业务闭环，全程 TDD（测试优先）开发。

- **三类角色**：客户（Customer）、商家（Merchant）、平台管理员（Admin）
- **三端**：客户 H5 端、商家管理端、平台管理端
- **核心考核点**：TDD 流程落地、前后端分离架构、架构应对需求变更的扩展性

---

## 技术栈

| 层 | 技术 |
| --- | --- |
| 后端 | Spring Boot 3.3.5 + Java 17 + MyBatis-Plus 3.5.7 |
| 数据库 | MySQL 8.0（**远端云服务器** `192.144.154.249:3306`，库 `elm`） |
| 前端 | Vue 3 + Vue Router + Pinia + Element Plus |
| 鉴权 | JWT（`Authorization: Bearer <token>`） |
| 对象存储 | MinIO（**远端图床** `192.144.154.249:9000`，Bucket `elm-uploads`，图片上传返回公网 URL） |
| 测试 | JUnit5 + MockMvc（后端）、Vitest（前端） |
| 接口文档 | springdoc-openapi（Swagger UI） |

---

## 角色与端

| 角色 | 英文标识 | 使用端 | 入口端口 |
| --- | --- | --- | --- |
| 客户 | `CUSTOMER` | 客户 H5（`frontend/customer-h5`） | `http://localhost:5174` |
| 商家 | `MERCHANT` | 商家后台（`frontend/admin` 内 `/merchant/*`） | `http://localhost:5173` |
| 平台管理员 | `ADMIN` | 平台后台（`frontend/admin` 内 `/platform/*`） | `http://localhost:5173` |

> 商家端与平台端共用同一个 `admin` 前端工程，登录后按角色路由到各自页面。

---

## 功能概览

- **客户端**：注册登录、地址管理、余额充值、商家/菜品搜索浏览、多规格加购、下单支付、订单进度、取消/退款、三维度评价、优惠券、消息中心、热力地图、榜单、AI 对话推荐与个性化推荐
- **商家端**：入驻申请与资质审核、开店与营业状态、菜品分类/规格/库存、订单处理（接单/出餐/配送/送达）、售后处理、店铺券、评价回复与申诉、经营数据、提现
- **平台端**：资质审核、商家/客户管理、订单治理、内容运营（轮播/分类/推荐位/公告）、平台券、财务（佣金/对账/流水/提现审核）、数据看板、系统配置、操作日志

完整用例清单见 [docs/需求规格说明书.md](docs/需求规格说明书.md) §5。

---

## 项目结构

```
elm/
├── backend/                # Spring Boot 后端（四层架构）
│   └── src/main/resources/sql/   # 建表脚本：account.sql / trade.sql / operation.sql
├── frontend/
│   ├── customer-h5/        # 客户 H5 端（Vite 8 / Pinia 4）
│   └── admin/              # 商家端 + 平台端（Vite 6 / Pinia 3）
└── docs/                   # 项目文档（需求 / 接口 / 数据库 / 规范 / 验收）
```

后端按业务域分包：

| 域 | 包路径 | 负责范围 |
| --- | --- | --- |
| account（账号域） | `com.elm.account` | 三角色注册登录、改密、头像昵称、地址、余额 |
| trade（交易域） | `com.elm.trade` | 商家入驻/店铺/菜品、购物车、订单、支付、售后、评价、优惠券 |
| operation（运营域） | `com.elm.operation` | 审核、内容运营、财务、数据看板、系统配置、消息 |

数据库共 **29 张表**，采用统一 `user` 表 + `role` 字段建模三角色，详见 [docs/数据库设计文档.md](docs/数据库设计文档.md)。

---

## 快速开始

### 环境要求

| 端 | 依赖 | 版本要求 |
| --- | --- | --- |
| 后端 | JDK | 17 |
| 后端 | Maven | 3.9+ |
| 前端 | Node.js | 20.19+ 或 22.12+ |

### 启动后端

**数据库与对象存储使用远端云服务器**（无需本机安装 MySQL / MinIO）：

| 依赖 | 地址 | 说明 |
| --- | --- | --- |
| MySQL | `192.144.154.249:3306` | 数据库 `elm`，账号/密码 `elm` / `elm` |
| MinIO 图床 | `http://192.144.154.249:9000` | Bucket `elm-uploads`（公开读），图片上传走这里 |

一键启动（`run-remote.sh` 已封装上述远端连接环境变量）：

```bash
cd backend
bash run-remote.sh          # 启动后监听 http://localhost:8080
```

> ⚠️ **AI 助手（UC-C30）依赖 DeepSeek 密钥，`run-remote.sh` 不会自动加载。**
> 若直接 `bash run-remote.sh` 启动，后端能正常起，但客户 H5 的「AI 助手」会返回 `50000 暂时不可用`（后端日志出现 `AI chat failed type=IllegalStateException`）。密钥在 `backend/.env.ai.local`（团队共享、已入库），启用 AI 助手请先加载再启动：
>
> ```bash
> cd backend
> set -a && source .env.ai.local && set +a
> bash run-remote.sh
> ```
>
> 或从仓库根目录运行 `bash backend/scripts/ai.sh run`（自动加载密钥）。未配置密钥不影响其他业务，仅 AI 对话不可用。

如需连本机库，可覆盖环境变量后手动启动（默认 `localhost:3306` / `root` / `root`）：

```bash
cd backend
mvn spring-boot:run
```

> 启动时 `DataInitializer` 自动保证默认管理员存在：`admin / 123456`（角色 ADMIN）。

### 启动前端

两个前端为独立 npm 工程，需分别安装、分别启动：

```bash
# 客户 H5 端（默认 :5174）
cd frontend/customer-h5
npm install                # 网络慢可加 --registry=https://registry.npmmirror.com
npm run dev

# 商家端 + 平台端（默认 :5173）
cd frontend/admin
npm install
npm run dev
```

两个前端 Vite 均已配置代理，将 `/api`、`/uploads` 转发到 `http://localhost:8080`；前端 axios `baseURL` 均为 `/api/v1`，无需修改。

### 运行测试

```bash
cd backend
mvn test        # 后端自动化测试使用隔离 H2 内存库，不依赖 MySQL
```

---

## 核心约定

### RESTful 接口

- 版本隔离：统一前缀 `/api/v1`
- 资源名词 URI，拒绝动词型路径（登录、取消、支付等业界惯例动作除外，如 `POST /api/v1/orders/{id}/cancel`）
- HTTP 方法语义：GET 查询、POST 新建、PUT/PATCH 更新、DELETE 删除
- 分页/过滤/排序统一 Query 参数：`page` / `size` / `sort`

### 统一响应体

```json
{ "code": 0, "msg": "success", "data": { } }
```

- `code = 0` 表示成功；非 0 见错误码表（`40000` 参数错误、`40100` 未登录、`40300` 无权限、`40400` 不存在、`40900` 状态冲突等）
- 标准 HTTP 状态码配合业务码，异常统一走全局异常处理器

### 鉴权

登录返回 JWT Token，前端请求头携带 `Authorization: Bearer <token>`，后端按角色做权限校验，角色不符返回 `40300`。

### TDD 开发流程

严格遵循「先测试后编码」：梳理需求 → 写测试（正常/异常/边界）→ 测试失败 → 写业务 → 测试通过 → 提交。核心接口测试覆盖率 100%，关键业务方法覆盖率 ≥ 90%。详见 [docs/TDD流程与测试规范.md](docs/TDD流程与测试规范.md)。

---

## 文档索引

| 文档 | 说明 |
| --- | --- |
| [需求规格说明书](docs/需求规格说明书.md) | 项目详细需求与用例 |
| [接口契约文档](docs/接口契约文档.md) | 前后端接口唯一契约 |
| [数据库设计文档](docs/数据库设计文档.md) | 29 张表结构、ER 图、状态机设计 |
| [数据库设计注意事项](docs/数据库设计注意事项.md) | 建表与字段使用注意点 |
| [统计口径说明](docs/统计口径说明.md) | 财务/经营数据统计口径 |
| [团队分工方案](docs/团队分工方案.md) | 5 名成员角色与职责 |
| [TDD 流程与测试规范](docs/TDD流程与测试规范.md) | 测试分层、命名、覆盖率要求 |
| [Git 分支与提交规范](docs/Git分支与提交规范.md) | 分支模型与提交节奏 |
| [项目基本要求](docs/项目基本要求.md) | 课程项目要求与验收标准 |
| [依赖清单](docs/依赖清单.md) | 后端/前端依赖与环境 |
| [给验收小组的部署文档](docs/给验收小组的部署文档.md) | 本机部署与联调步骤 |
| [给验收小组的需求文档](docs/给验收小组的需求文档.md) | 交叉验收范围与评分表 |
| [联调阶段必读](docs/联调阶段必读.md) | 前后端联调注意事项 |
| [AI 对话功能实现文档](docs/AI对话功能实现文档.md) | AI 对话（UC-C30）实现说明 |
| [AI 推荐系统实现文档](docs/AI推荐系统实现文档.md) | AI 个性化推荐（UC-C31）实现说明 |

---

## 团队分工

| 成员 | 角色 | 负责域 |
| --- | --- | --- |
| 成员 1 | 技术负责人 / 架构师 | 后端公共层 + 数据库 + 账号域 + AI 对话 |
| 成员 2 | 后端 · 交易域 | 商品/购物车/订单/支付/售后/优惠券/评价/AI 推荐 |
| 成员 3 | 后端 · 平台运营域 | 管理员/内容/财务/数据/系统/消息 |
| 成员 4 | 前端 · 客户 H5 端 | 前端工程、公共层、客户全部页面 |
| 成员 5 | 前端 · 商家端 + 平台端 | 两个后台 Web + 文档与验收材料 |

详见 [docs/团队分工方案.md](docs/团队分工方案.md)。