# eshop-class2-group8

**Repository Path**: grade24-fullstack-class2/eshop-class2-group8

## Basic Information

- **Project Name**: eshop-class2-group8
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📦 电子商城（B2C）— 8 组

> B2C 电子商城教学项目，前后端分离架构。
> 分工方式：**按业务模块垂直分工**（每人独立完成所负责模块的库表+接口+页面全链路）。
> 周期：4 周（20 个工作日）。

## 团队分工

| 角色 | 姓名 | 分工 |
|------|------|------|
| A · 组长/架构员 | 胡晨辉 | 公共基建（脚手架/鉴权/统一响应/DB）+ 后台操作日志；挑战 **C09** 或 **C10** |
| B | 江禹辰 | 商品包（分类/列表/搜索/详情 + 后台商品）+ 评价晒图；挑战 **C04** |
| C | 陈杨文 | 订单支付包（订单/支付/取消 + 后台订单）；挑战 **C03** 订单超时取消 |
| D | 余泽 | 用户购物车包（注册登录/地址/购物车 + 后台用户）+ 收藏/浏览历史；测试主笔 |

## 技术栈

- 前端：**Vue 3** + Vite + Vue Router + Pinia + **Element Plus**
- 后端：**Node.js 20 + Express 4** + Sequelize 6 + mysql2 + Joi + bcryptjs + jsonwebtoken
- 数据库：**MySQL 8.0**
- 缓存：**Redis 7**
- 部署：**Docker Compose**（MySQL + Redis，可扩展 backend / 前端 / Nginx）

详细选型理由见 [`docs/02-设计文档/系统架构设计.md`](docs/02-设计文档/系统架构设计.md)。

## 项目结构

```
eshop-class2-group8/
├── backend/
│   ├── package.json
│   ├── .env.example
│   ├── sql/
│   │   ├── schema.sql                # A 负责（建表全部由 A 汇总，但表结构由各人设计后合并）
│   │   └── data.sql                  # 各人准备自己模块的演示数据，A 汇总
│   ├── src/
│   │   ├── app.js                    # A 负责（入口，挂载路由、中间件）
│   │   ├── common/                   # ===== A 公共基建 =====
│   │   │   ├── response.js           # 统一响应格式
│   │   │   ├── exception.js          # 全局异常处理
│   │   │   ├── auth.js  、             # 鉴权中间件（JWT 验证）
│   │   │   ├── pagination.js         # 分页封装
│   │   │   ├── validator.js          # 参数校验中间件
│   │   │   ├── logger.js             # 操作日志（A 可挑战后台操作日志）
│   │   │   └── error-handler.js      # Express 4 参全局异常中间件（与 exception.js 职责分离：exception.js 是异常类定义，error-handler.js 是把异常转成 {code,message,data} HTTP 响应）
│   │   ├── config/
│   │   │   ├── db.js                 # A 负责（数据库连接）
│   │   │   └── redis.js              # A 负责（Redis 连接，供缓存/超时使用）
│   │   ├── models/                   # Sequelize 模型注册中心（A 负责统一加载关联）
│   │   │   ├── index.js              # A 负责（导入所有模块模型并建立关联）
│   │   │   └── (各模块模型由各人定义，放置于 modules/模块名/models/ 下)
│   │   ├── routes/
│   │   │   └── index.js              # A 负责（聚合所有模块路由）
│   │   └── modules/                  # ===== 业务模块 =====
│   │       ├── user/                 # ===== D 负责 =====
│   │       │   ├── models/
│   │       │   │   ├── User.js
│   │       │   │   ├── Address.js
│   │       │   │   └── CartItem.js   # 购物车项
│   │       │   ├── routes/
│   │       │   │   └── index.js      # 路由：/api/user/*
│   │       │   ├── controllers/
│   │       │   │   ├── authController.js     # 注册/登录/退出
│   │       │   │   ├── profileController.js  # 个人信息维护
│   │       │   │   ├── addressController.js  # 地址 CRUD
│   │       │   │   ├── cartController.js     # 购物车 CRUD
│   │       │   │   └── adminUserController.js # 后台用户管理（禁用/启用）
│   │       │   └── services/
│   │       │       ├── authService.js
│   │       │       ├── userService.js
│   │       │       └── cartService.js
│   │       │
│   │       ├── product/              # ===== B 负责 =====
│   │       │   ├── models/
│   │       │   │   ├── Category.js
│   │       │   │   └── Product.js
│   │       │   ├── routes/
│   │       │   │   └── index.js      # 路由：/api/product/*
│   │       │   ├── controllers/
│   │       │   │   ├── categoryController.js # 分类列表（前台+后台）
│   │       │   │   ├── productController.js  # 商品列表/详情/搜索
│   │       │   │   └── adminProductController.js # 后台增删改查/上下架
│   │       │   └── services/
│   │       │       ├── categoryService.js
│   │       │       └── productService.js
│   │       │
│   │       ├── order/                # ===== C 负责 =====
│   │       │   ├── models/
│   │       │   │   ├── Order.js
│   │       │   │   ├── OrderItem.js
│   │       │   │   └── Payment.js
│   │       │   ├── routes/
│   │       │   │   └── index.js      # 路由：/api/order/*
│   │       │   ├── controllers/
│   │       │   │   ├── orderController.js    # 提交订单/列表/详情/取消
│   │       │   │   ├── paymentController.js  # 模拟支付（状态流转）
│   │       │   │   └── adminOrderController.js # 后台订单管理/发货
│   │       │   └── services/
│   │       │       ├── orderService.js
│   │       │       └── paymentService.js
│   │       │
│   │       └── admin/                # ===== A 负责（管理后台专属） =====
│   │           ├── log.routes.js     # 操作日志查询路由（GET /api/admin/operation-logs）
│   │           └── operation-log.model.js  # operation_log 表 Sequelize 模型
│   │
│   └── (tests/ 按模块分，各自写单元/集成测试，D 汇总测试计划)  # ⚠️ 暂未创建
│
└── frontend/
    ├── package.json
    ├── src/
    │   ├── main.js                   # A 负责（全局配置）
    │   ├── App.vue                   # A 负责
    │   ├── api/                      # Axios 封装（A 负责基础，各模块自己扩展）
    │   │   ├── index.js              # A 负责（axios 实例/拦截器）
    │   │   ├── user.js               # D 负责
    │   │   ├── product.js            # B 负责
    │   │   ├── order.js              # C 负责
    │   │   └── admin.js              # A 负责（管理后台专属 API：操作日志 M09）
    │   ├── stores/                   # Pinia 状态管理（按模块分）
    │   │   ├── index.js              # A 负责（组合 store）
    │   │   ├── userStore.js          # D 负责（登录态、用户信息）
    │   │   ├── cartStore.js          # D 负责（购物车本地状态+同步）
    │   │   ├── productStore.js       # B 负责（商品列表/分类）
    │   │   └── orderStore.js         # C 负责（订单列表/支付状态）
    │   ├── router/
    │   │   └── index.js              # A 负责（路由守卫，鉴权）
    │   ├── layouts/
    │   │   ├── FrontLayout.vue       # A 负责（前台布局，header/footer）
    │   │   └── AdminLayout.vue       # A 负责（后台布局，侧边栏）
    │   ├── components/               # 公共组件（A 负责）
    │   │   ├── Pagination.vue
    │   │   ├── Loading.vue
    │   │   └── ...
    │   └── views/                    # ===== 业务页面（按模块划分） =====
    │       ├── user/                 # D 负责
    │       │   ├── Login.vue
    │       │   ├── Register.vue
    │       │   ├── Profile.vue
    │       │   ├── AddressList.vue
    │       │   ├── AddressEdit.vue
    │       │   ├── Cart.vue
    │       │   └── admin/
    │       │       └── UserManage.vue   # 后台用户管理
    │       ├── product/              # B 负责
    │       │   ├── ProductList.vue
    │       │   ├── ProductDetail.vue
    │       │   ├── SearchResult.vue
    │       │   ├── CategoryBrowse.vue
    │       │   └── admin/
    │       │       ├── ProductManage.vue   # 商品列表/增删改
    │       │       └── CategoryManage.vue  # 分类管理
    │       ├── order/                # C 负责
    │       │   ├── Checkout.vue          # 提交订单（结算页）
    │       │   ├── OrderList.vue
    │       │   ├── OrderDetail.vue
    │       │   ├── Payment.vue           # 模拟支付页
    │       │   └── admin/
    │       │       └── OrderManage.vue   # 后台订单管理
    │       └── admin/                 # ===== A 负责（管理后台专属页面） =====
    │           ├── Dashboard.vue     # 后台首页（统计看板）
    │           └── Logs.vue           # 操作日志查看页（M09）
    │       # ⚠️ 备注：图中原写为 "（可选）dashboard/"，实际项目中归入 admin/ 目录下
    └── public/ ...
```

> ⚠️ 完整结构图见根目录 `项目结构图.txt`（含文件职责说明 + 责任人 A/B/C/D）。

## 🚀 一键启动（开发环境）

### 前置依赖
- **Node.js 20+**
- **本地 MySQL 8.0+**（推荐 [MySQL Installer](https://dev.mysql.com/downloads/installer/) 或解压版，默认端口 3306）
- **本地 Redis 7+**（推荐 [Memurai](https://www.memurai.com/) Windows 版 或 [WSL 装 Redis](https://learn.microsoft.com/en-us/windows/wsl/install)，默认端口 6379）
- **pnpm**（前端包管理）：`npm i -g pnpm`

### 步骤

```bash
# 1. 准备本地 MySQL + Redis
#    - 启动 MySQL，用 root 登录后执行：
mysql -u root -p < backend/sql/schema.sql
mysql -u root -p < backend/sql/data.sql
#    - 启动 Redis（默认端口 6379，无密码）：
redis-server

# 2. 安装并启动后端
cd backend
cp .env.example .env       # 然后按需修改（默认连接 localhost:3306 / localhost:6379）
npm install
npm run dev                # 监听 http://localhost:3000

# 3. 另开终端：安装并启动前端
cd frontend
cp .env.example .env
pnpm install
pnpm dev                   # 访问 http://localhost:5173
```

### 健康检查

- 后端：[http://localhost:3000/health](http://localhost:3000/health) — 应返回 `{"code":0,...}`
- 前端：[http://localhost:5173](http://localhost:5173)
- 数据库：[localhost:3306](localhost:3306)，账号 `eshop / eshop123`（自行在 MySQL 里建）
- Redis：[localhost:6379](localhost:6379)

### 默认账号

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | admin123 | 管理员（后台 `/admin`）|
| tester | buyer123 | 测试买家 |

> ✅ 真实 bcrypt 哈希已写入 `backend/sql/data.sql`（commit `ba6c314`），导入 SQL 后即可直接登录。
> ⚠️ 本项目**不使用 Docker**（团队统一约定）。如需容器化请自行扩展。

## 协作硬规则（来自《项目要求》3.3）

1. **接口文档先行**：跨人接缝接口变更必须先 PR 到 `docs/02-设计文档/接口设计.md`，A 审核通过方可改代码。
2. **交叉 Code Review**：B 审 C、C 审 D、D 审 B；A 兜底审查所有接缝接口 PR。
3. **交叉答辩**：除讲解自己模块外，每人被抽问 1 个其他成员模块的基础问题。

## Git 分支与提交规范

```
main        ← 受保护，仅通过 PR 合并
dev         ← 集成分支
feature/<姓名>-<模块>   ← 个人开发分支
hotfix/...  ← 紧急修复
```

提交信息前缀：
- `feat:` 新功能
- `fix:` 修复
- `docs:` 文档
- `test:` 测试
- `refactor:` 重构
- `chore:` 杂项（构建/依赖）

## 4 条跨人接缝接口（必须先改文档再写代码）

| # | 接口 | 提供 | 调用 |
|---|---|---|---|
| S01 | `POST /api/products/batch` 批量查商品 | B | D、C |
| S02 | `POST /api/products/:id/stock/decrement` 扣减库存（幂等）| B | C |
| S03 | `POST /api/products/:id/stock/increment` 回补库存（幂等）| B | C |
| S04 | `GET /api/cart/checkout` 购物车结算快照 | D | C |

## 文档索引

| 文档 | 位置 |
|------|------|
| 需求规格说明书 | `docs/01-需求文档/需求规格说明书.md` |
| 系统架构设计 | `docs/02-设计文档/系统架构设计.md` |
| 数据库设计 | `docs/02-设计文档/数据库设计.md` |
| 接口设计 | `docs/02-设计文档/接口设计.md` |
| ER 与接口调用图 | `docs/02-设计文档/ER与接口调用图.drawio.png` |
| 第 1 周周报 | `reports/weekly/第1周-周报.md` |

## 验收标准摘录

- 必做 ≥13 项 + 选做 ≥2 项 + 挑战 ≥1 项
- 系统部署在可访问环境
- 密码加密、登录态、参数校验（N04 安全）
- ≥30 商品 + ≥3 分类演示数据（N03）

## 常见问题

**Q: 启动报 "ECONNREFUSED 3306"？**
A: 本地 MySQL 没起来。在 Windows 服务里启动 MySQL 服务，或用 MySQL Installer 启动 Workbench 连一下确认。

**Q: 登录 admin/admin123 报"用户名或密码错误"？**
A: 确认 `data.sql` 已导入（commit `ba6c314` 已写入真实 bcrypt 哈希）。若仍报错，先 `mysql -u root -p eshop < backend/sql/schema.sql` 重建表结构，再 `mysql ... < backend/sql/data.sql` 重置数据。

**Q: 接缝接口签名要改怎么办？**
A: 先 PR 到 `docs/02-设计文档/接口设计.md`，A 审核通过后再改代码。

---

> 历史模板信息可参考原版 `git log -p HEAD~ README.md`，本版是基于分工与实际工程化落地的版本。