# 软件工程实践

**Repository Path**: decade9/sep

## Basic Information

- **Project Name**: 软件工程实践
- **Description**: Software Engineering Practice for Tianjin University
- **Primary Language**: Java
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 28
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 轻量级外卖服务平台(仿饿了么)

> 天津大学《26271学期-软件工程综合实践》课程项目(2026-08-31 ~ 2026-09-20)
> 项目代号:`elm-v2.0` | 前后端分离 | TDD 测试驱动开发 | RESTful API

一个功能完整、架构清晰、易于扩展的轻量级外卖服务平台:消费者可浏览店铺、选购商品、下单并跟踪订单;商家可通过**入驻申请**开店并管理商品/订单/营业状态;管理员负责开店、审核入驻申请与平台管理。

---

## 一、技术栈

| 层 | 技术 |
|----|------|
| 后端 | Java 17、Spring Boot 3.5.4、Spring Data JPA(Hibernate)、Spring Security + JWT、SpringDoc OpenAPI、Maven |
| 前端 | Vue 3、Vite、Element Plus、Pinia、Vue Router、Axios |
| 数据库 | H2(开发/测试,文件模式)、MySQL/MariaDB(生产,已验证 MariaDB 11.4) |
| 测试 | JUnit 5、Mockito、MockMvc、AssertJ、Hamcrest(后端);Vitest(前端) |

## 二、快速开始

### 环境要求

- JDK ≥ 17、Maven ≥ 3.8
- Node.js ≥ 22.18

### 1. 启动后端

```bash
cd elm-v2.0
mvn spring-boot:run        # http://localhost:8080
```

- Swagger 文档:http://localhost:8080/swagger-ui/index.html
- H2 控制台:http://localhost:8080/h2-console(JDBC URL `jdbc:h2:file:./data/testdb`,用户 `sa`,密码空)
- 生产库切换 MySQL/MariaDB:

```bash
docker compose up -d mysql   # 一键拉起 MariaDB
mvn spring-boot:run -Dspring-boot.run.profiles=mysql
```

详见 [docs/MySQL部署指南.md](docs/MySQL部署指南.md)。

### 2. 启动前端

```bash
npm install
npm run dev                 # http://localhost:5173(已代理 /api → 8080)
```

### 3. 种子账号

| 账号 | 密码 | 角色 |
|------|------|------|
| admin | admin | ADMIN + BUSINESS + USER(管理员/商家) |
| user | user | USER(普通消费者) |

> 种子数据由 `elm-v2.0/src/main/resources/data.sql` 自动播种(含 5 个商品分类)。首次启动后端即就绪。

### 4. 运行测试

```bash
cd elm-v2.0 && mvn test    # 315/315 通过(TDD 报告见 docs/testing/)
npm run test:unit          # 前端 Vitest
```

## 三、功能清单

### 阶段1:基础功能

| 模块 | 功能 |
|------|------|
| 用户 | 注册(username 4-20 / password 6-20 / login 唯一)、登录(错误码 1104/1103)、个人信息查询/修改、修改密码(验旧密码) |
| 商家 | **入驻申请 → 管理员审核(通过授予 BUSINESS 角色 / 拒绝删除)**、开店(ADMIN)、关店、临时闭店(营业状态) |
| 店铺 | 列表(分页/关键词搜索)、详情、营业状态展示(营业中/休息中/已打烊/暂停/待审核) |
| 商品 | CRUD、分类、列表(分页/搜索/分类筛选)、价格/库存展示、上架/下架 |
| 购物车 | 加购(重复 1402 / 数量校验)、增删改查、越权隔离 |
| 订单 | 创建(空车/跨店/他人地址拦截)、状态查询、列表(分页/状态筛选)、支付/取消/发货/收货状态机 |
| 地址 | CRUD、格式校验(手机号 11 位 / 称呼 0-1)、默认地址、越权隔离 |

### 阶段2:需求变更迭代(REQ-001 ~ REQ-006)

1. **订单状态机**:待支付→待配送→配送中→已完成 / 待支付→已取消;非法流转 1502;取消幂等;支付/取消时间戳
2. **商品库存管理**:下单扣减、取消回滚、库存不足 2001、乐观锁防超卖
3. **分页**:`page/size/sort`(size 1~100 截断、sort 字段白名单)
4. **统一优惠折扣**:满 50 减 5 / 满 100 减 15,配送费不参与
5. **店铺营业状态**:OPEN/REST/CLOSED/SUSPENDED/PENDING,非营业状态拒单 2004
6. **商品分类**:分类查询、按分类筛选、`categoryId=-1` 查未分类、分类不存在 2005

## 四、接口规范

- 统一前缀 `/api/v1`,资源名词 URI,标准 HTTP 方法与状态码
- 统一响应体:`{ success, code, data, message }`
- JWT 无状态认证(`Authorization: Bearer <token>`),RBAC 角色控制(USER/BUSINESS/ADMIN)
- 错误码分段:1000 通用 / 1100 用户认证 / 1200 店铺 / 1300 商品 / 1400 购物车 / 1500 订单 / 1600 地址 / 2000 迭代需求

完整契约见 [docs/api/接口契约表v1.0.md](docs/api/接口契约表v1.0.md)(v1.4),需求规格见 [docs/软件需求规格说明书.md](docs/软件需求规格说明书.md)(v1.2)。

## 五、目录结构

```
sep/
├── src/                    # 前端源码(Vue 3)
│   ├── api/                # 接口统一封装
│   ├── views/              # 页面
│   ├── components/         # 公共组件(分页、入驻审核等)
│   ├── router/             # 路由与守卫(公开浏览/角色控制)
│   ├── stores/             # Pinia 状态
│   └── utils/              # axios 拦截器、auth 工具
├── elm-v2.0/               # 后端源码(Spring Boot)
│   ├── src/main/java/cn/edu/tju/
│   │   ├── core/           # 统一返回/异常/安全(JWT)/分页工具
│   │   └── elm/            # 业务分层:model/repository/service/controller
│   ├── src/test/java/      # 315 个测试(Controller 集成 + Service 单元)
│   └── data/               # H2 文件数据库(本地,不入 git)
├── docs/                   # 项目文档(见下方文档索引)
├── docker-compose.yml      # MariaDB 一键部署
└── vite.config.js          # 前端构建/代理配置
```

## 六、文档索引

| 文档 | 位置 |
|------|------|
| 软件需求规格说明书(SRS v1.2) | [docs/软件需求规格说明书.md](docs/软件需求规格说明书.md) |
| 接口契约表(v1.3) | [docs/api/接口契约表v1.0.md](docs/api/接口契约表v1.0.md) |
| 第二周需求规格(REQ-001~006) | [docs/week2/第二周需求规格说明书.md](docs/week2/第二周需求规格说明书.md) |
| 需求变更记录(CR-001~008 含 SHA) | [docs/week2/需求变更记录.md](docs/week2/需求变更记录.md) |
| 数据库设计/数据字典 | [docs/database/](docs/database/) |
| TDD 测试报告(v1.0/v2.0) | [docs/testing/](docs/testing/) |
| 交叉验收自检清单 | [docs/验收/交叉验收自检清单.md](docs/验收/交叉验收自检清单.md) |
| Bug 清单与修复记录 | [docs/bug-reports/](docs/bug-reports/) |
| AI 辅助使用记录 | [docs/项目文档/AI辅助使用记录.md](docs/项目文档/AI辅助使用记录.md) |
| 项目进度与注意事项 | [docs/week2/项目进度.md](docs/week2/项目进度.md) |

## 七、团队分工

| 成员 | 角色 | 负责 |
|------|------|------|
| 成员A | 测试&验收文档负责人 | TDD 用例编写、测试执行、验收文档 |
| 成员B | 后端&数据库负责人 | 架构分层、业务逻辑、数据库设计、接口契约 |
| 成员C | 前端&验收文档负责人 | 页面开发、前后端联调、交互实现 |

## 八、常见问题(踩坑记录)

1. **登录接口是 `/api/auth`**,不是 `/api/authenticate`(历史写错过)。
2. **不要提交 `target/`、`node_modules/`**,已在 .gitignore。
3. **H2 文件模式**必须配 `spring.sql.init.mode=always`,否则 data.sql 不执行、种子账号/分类缺失。
4. **清库流程**:停后端 → H2 Shell 按外键顺序删表并 `ALTER TABLE <表> ALTER COLUMN ID RESTART WITH 1` → 重启自动播种(详见 [docs/week2/项目进度.md](docs/week2/项目进度.md) 注意事项第 7 条)。
5. **商家审核通过后需重新登录**,JWT 角色是签发时快照(前端工作台已加"请重新登录"提示)。
6. **数据库文件 `data/testdb.mv.db` 是本地的**——如遇 `business_status` 列报 "Value not permitted … 'PENDING'",说明本机文件库还是旧 ENUM 列,执行 `ALTER TABLE BUSINESS ALTER COLUMN BUSINESS_STATUS VARCHAR(20)` 或删除 db 文件重建。

---

**许可证**:GPL-2.0 | 课程项目,仅供教学实践使用