# coffee_shop

**Repository Path**: Yuxon/coffee_shop

## Basic Information

- **Project Name**: coffee_shop
- **Description**: 基于微信小程序咖啡商城项目
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-15
- **Last Updated**: 2025-12-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 瑞幸咖啡微信小程序商城项目

## 项目简介

这是一个完整的校园咖啡商城微信小程序项目，实现了从用户注册登录、商品浏览、购物结算到订单管理的完整电商流程。项目采用前后端分离架构，前端基于微信小程序原生框架开发，后端使用Node.js + Express.js + MySQL提供API服务（由教师提供文件夹资料）。

项目特色：
- 🛒 **完整购物流程**：支持商品浏览、购物袋管理、订单结算等完整电商功能
- 📱 **现代化UI设计**：基于Vant Weapp组件库，界面美观但仍有优化空间
- 🔧 **完善的技术架构**：包含环境配置、错误处理、图片处理等实用功能
- ⚠️ **功能完善中**：部分高级功能（如AI推荐、个人资料管理、密码找回等）暂未实现

## 一、项目概述

### 1.1 项目架构

- **前端**：微信小程序端（学生核心开发）
- **后端**：Node.js + Express.js + MySQL（教师提供API服务）
- **AI服务**：DeepSeek API（个性化推荐，暂未实现）
- **辅助工具**：豆包AI（页面布局生成+代码优化）

### 1.2 当前项目状态

**✅ 已完成功能：**
- 完整的购物流程（浏览商品 → 加入购物袋 → 提交订单）
- 用户注册登录功能
- 商品展示、分类筛选
- 购物袋管理、订单处理
- 地址管理和订单管理

**⚠️ 待优化功能：**
- UI界面美化优化
- 收藏商品图片显示问题修复

**🔄 未实现功能：**
- AI个性化推荐（已接入大模型但未成功实现个性化推荐功能）
- 个人资料管理（头像、昵称、简介等）
- 密码找回功能
- 修改密码功能
- 账号注销功能

### 1.2 技术栈

|端别|技术选型|
|---|---|
|前端|微信小程序原生框架（WXML/WXSS/JS）、Vant Weapp组件库|
|后端|Node.js + Express.js、Sequelize ORM、MySQL（mysql2驱动）|
|认证|JWT (jsonwebtoken)|
|邮件服务|Nodemailer|
|AI服务|DeepSeek API|
|开发工具|微信开发者工具、Apipost、Gitee、AI辅助工具|

### 1.3 项目特色

- ✅ **完整电商流程**：注册→浏览→收藏→购物→结算→订单管理
- ✅ **购物功能完整**：商品展示、购物袋管理、订单处理等核心功能已实现
- ⚠️ **UI界面优化**：界面功能完整，但仍需进一步美化优化
- 🔄 **功能完善中**：部分高级功能正在开发中
- ✅ **健壮的架构**：完善的错误处理、图片处理、缓存机制
- ✅ **模块化设计**：组件化开发，可维护性强
## 二、快速开始

### 2.1 环境要求

- **微信开发者工具**：最新稳定版
- **Node.js**：v22.18.0
- **后端服务**：Node.js + Express.js + MySQL（教师提供serverapi文件夹和manage文件夹等后端资料）

### 2.2 项目配置

#### 1. 克隆项目
```bash
git clone <repository-url>
cd coffee_shop
```

#### 2. 安装依赖
```bash
# 微信小程序项目无需额外安装依赖
# 确保微信开发者工具已安装
```

#### 3. 配置API接口

编辑 `utils/config.js`：
```javascript
const config = {
  // API基础配置
  API_BASE_URL: 'http://127.0.0.1:7001', // 修改为实际后端地址
  TOKEN_KEY: 'token34'
};
```

#### 4. 配置AI推荐服务

编辑 `api/api.js` 中的 `getAIRecommendation` 函数：
```javascript
const DEEPSEEK_API_KEY = 'sk-b904eece25d44eab812a88cd4b281498'; 
```

#### 5. 导入数据库

通过git bash命令node index.js初始化数据库：
-- 1. user.sql - 用户表
-- 2. b_user.sql - 商家用户表
-- 3. type.sql - 商品类型表
-- 4. product.sql - 商品表
-- 5. address.sql - 地址表
-- 6. shopcart.sql - 购物袋表
-- 7. like.sql - 收藏表
-- 8. order.sql - 订单表
-- 9. validcode.sql - 验证码表

### 2.3 运行项目

1. 使用微信开发者工具打开项目
2. 填写正确的 AppID（已在 `project.config.json` 中配置：`wx50fa3967499fdfd1`）
3. 点击"编译"运行项目

### 2.4 项目结构

```
coffee_shop/
├── api/                    # API接口封装
│   └── api.js             # 统一API接口管理
├── components/            # 自定义组件
│   ├── Product/          # 商品组件
│   └── Stepper/          # 数量选择器组件
├── database/             # 数据库结构文件
├── images/               # 图片资源
├── pages/                # 页面文件
│   ├── home/            # 首页
│   ├── menu/            # 菜单分类
│   ├── shopbag/         # 购物袋
│   ├── my/              # 个人中心
│   └── ...               # 其他页面
├── utils/                # 工具函数
│   ├── config.js        # 配置文件
│   └── util.js          # 通用工具函数
├── app.js               # 小程序入口文件
├── app.json             # 小程序配置
└── app.wxss            # 全局样式
```

## 三、模块核心功能与API接口明细

### 2.1 用户认证模块

#### 核心功能

- ✅ 注册、登录功能已完成
- ⚠️ 找回密码功能暂未实现
- ✅ 登录状态持久化与全局校验

#### 细化需求

- ✅ 表单验证：手机号格式正则校验、密码长度≥6位、必填项校验
- ✅ 登录状态：token存入Storage（key: token34），封装全局登录校验函数
- ⚠️ 找回密码：验证码60秒倒计时、新密码二次确认（暂未实现）
- ✅ 错误提示：统一使用Toast组件展示错误信息

#### API接口信息

|接口名称|请求方式|参数格式|状态码说明|备注|
|---|---|---|---|---|
|用户注册|POST|`{phone: string, password: string, nickName: string}`|成功：500；失败：501/401等|教师提供接口路径：`/register`|
|用户登录|POST|`{phone: string, password: string}`|成功：500；失败：501/700等|失败码700需跳转登录页，路径：`/login`|
|发送验证码|GET/POST|`{phone: string}`（需确认接口）|成功：500；失败：501|用于找回密码，路径：`/sendCode`（示例）|
|密码重置|POST|`{phone: string, newPassword: string, code: string}`|成功：500；失败：501|路径：`/resetPassword`（示例）|
### 2.2 首页模块

#### 核心功能

- 轮播图展示、热卖商品推荐、搜索功能

- 搜索历史缓存与管理

#### 细化需求

- 轮播图：自动切换（interval=5000）、指示器显示、点击跳转商品详情

- 商品卡片：自适应布局、显示名称/价格/小图、点击跳转详情

- 搜索框：防抖（300ms延迟）、搜索历史本地缓存（Storage）、支持单个删除/清空

- 图片处理：HTTP地址转HTTPS（小程序安全协议要求）

#### API接口信息

|接口名称|请求方式|参数格式|状态码说明|备注|
|---|---|---|---|---|
|热卖商品查询|GET|`flags: JSON字符串数组`（如：`["热销"]`）|成功：500；失败：501|路径：`/flagProducts`，参数必须为JSON字符串|
|轮播图商品查询|GET|`flags: JSON字符串数组`（如：`["新品","时令"]`）|成功：500；失败：501|复用`flagProducts`接口，筛选对应标志商品|
|关键词搜索|GET|`keyword: string`（需确认参数名）|成功：500；失败：501|路径：`/searchProduct`（示例）|
### 2.3 菜单分类模块

#### 核心功能

- 商品分类筛选（左侧导航+右侧列表联动）

- 分类商品查询

#### 细化需求

- 左侧分类：纵向ScrollView滚动，点击高亮当前分类

- 右侧商品：横向滚动，切换分类时刷新对应商品列表

- 商品列表：支持下拉刷新、上拉加载（可选）

- 图片处理：小图HTTP转HTTPS

#### API接口信息

|接口名称|请求方式|参数格式|状态码说明|备注|
|---|---|---|---|---|
|分类列表查询|GET|无参数（或固定参数）|成功：500；失败：501|路径：`/type`，返回所有商品类型|
|分类商品查询|GET|`typeId: string`（商品类型ID）|成功：500；失败：501|路径：`/typeProducts`，按类型筛选商品|
### 2.4 商品详情模块

#### 核心功能

- 商品详情展示、收藏/取消收藏、加入购物袋

- 购物袋数量实时更新

#### 细化需求

- 详情展示：多图预览、商品名称/英文名称/价格/描述（分行显示）

- 收藏功能：图标状态切换（变色动画）、进入页面初始化收藏状态

- 数量选择：使用Stepper组件（最小1），支持增减

- 加入购物袋：成功提示、实时更新购物袋数量（本地+接口同步）

#### API接口信息

|接口名称|请求方式|参数格式|状态码说明|备注|
|---|---|---|---|---|
|商品详情查询|GET|`pid: string`（商品ID）|成功：500；失败：501|路径：`/productDetail`，返回单个商品全量信息|
|收藏状态查询|GET|`{pid: string, token: string}`|成功：1000（有收藏）/500；失败：501|路径：`/findlike`，返回收藏记录数组|
|商品收藏|POST|`{pid: string, token: string}`|成功：500；失败：501|路径：`/like`|
|取消收藏|POST|`{pid: string, token: string}`|成功：500；失败：501|路径：`/notlike`|
|加入购物袋|POST|`{pid: string, token: string, count: number}`|成功：3000；失败：501/700|路径：`/addShopcart`，失败码700需跳转登录|
|购物袋数量查询|GET|`token: string`|成功：4000；失败：501|路径：`/shopcartCount`，返回商品总数量|
### 2.5 购物袋模块

#### 核心功能

- 商品列表展示、数量修改、全选/反选、批量删除、订单提交

- 总价实时计算

#### 细化需求

- 列表展示：商品复选框、图片、名称/英文名称、单价、数量选择器、选中状态

- 数量修改：Stepper组件（最小1），本地更新+接口同步

- 选中逻辑：单个选中联动全选状态、全选切换所有商品状态

- 删除功能：批量删除（选中后点击按钮）、确认弹窗、删除后刷新列表

- 总价计算：实时累加选中商品（数量×单价），保留2位小数

- 订单提交：携带选中商品ID和总价跳转支付页

#### API接口信息

|接口名称|请求方式|参数格式|状态码说明|备注|
|---|---|---|---|---|
|购物袋列表查询|GET|`token: string`|成功：500；失败：501/700|路径：`/findAllShopcart`，失败码700跳转登录|
|数量修改|POST|`{sid: string, token: string, count: number}`|成功：500；失败：501|路径：`/modifyShopcartCount`，sid为购物袋商品ID|
|商品删除|POST|`{sids: JSON字符串, token: string}`（如：`["sid1","sid2"]`）|成功：7000；失败：501|路径：`/deleteShopcart`，sids为选中商品ID数组JSON字符串|
### 2.6 地址管理模块

#### 核心功能

- 地址增删改查、默认地址设置

- 地址选择联动订单结算页

#### 细化需求

- 列表展示：地址卡片（收货人、手机号、详细地址、默认标签）、新增按钮

- 新增地址：表单验证（手机号、必填项）、省市区选择（可选三级联动）

- 编辑地址：回显原有数据、修改后同步接口

- 默认地址：单选设置，接口同步默认状态

#### API接口信息

|接口名称|请求方式|参数格式|状态码说明|备注|
|---|---|---|---|---|
|地址列表查询|GET|`token: string`|成功：500；失败：501|路径：`/getAddressList`（示例）|
|新增地址|POST|`{token: string, receiver: string, phone: string, addressDetail: string, isDefault: boolean}`|成功：500；失败：501|路径：`/addAddress`|
|地址详情查询|GET|`{token: string, addressId: string}`|成功：500；失败：501|路径：`/getAddressDetail`（示例），用于编辑回显|
|地址修改|POST|`{token: string, addressId: string, receiver: string, phone: string, addressDetail: string, isDefault: boolean}`|成功：500；失败：501|路径：`/updateAddress`（示例）|
|设置默认地址|POST|`{token: string, addressId: string}`|成功：500；失败：501|路径：`/setDefaultAddress`（示例）|
### 2.7 订单结算模块

#### 核心功能

- 地址选择、商品清单展示、总价计算、订单提交

- 异常处理（无地址/无选中商品）

#### 细化需求

- 地址选择：点击跳转地址列表页，选择后回显

- 商品清单：展示从购物袋携带的选中商品（名称、数量、单价、小计）

- 总价计算：自动累加商品金额，禁用支付按钮（无地址/无商品时）

- 订单提交：成功后跳转结果页，提供"查看订单"和"继续购物"入口

#### API接口信息

|接口名称|请求方式|参数格式|状态码说明|备注|
|---|---|---|---|---|
|创建订单|POST|`{token: string, addressId: string, productList: Array, totalPrice: number}`|成功：500；失败：501|路径：`/createOrder`（示例），productList含sid、count等|
### 2.8 我的订单模块

#### 核心功能

- 订单列表展示、状态筛选、订单操作（确认收货/删除）

- 订单详情查看

#### 细化需求

- 状态筛选：全部/待付款/待收货/已完成，点击切换筛选条件

- 订单展示：订单号、创建时间、商品缩略、总金额、状态标签

- 订单操作：待收货→确认收货；所有状态→删除（需确认弹窗）

- 详情跳转：点击订单卡片进入详情页，展示全量订单信息

#### API接口信息

|接口名称|请求方式|参数格式|状态码说明|备注|
|---|---|---|---|---|
|订单列表查询|GET|`{token: string, status: string}`（status：all/paid/received/completed）|成功：500；失败：501|路径：`/getOrderList`（示例）|
|确认收货|POST|`{token: string, orderId: string}`|成功：500；失败：501|路径：`/confirmReceipt`（示例）|
|订单删除|POST|`{token: string, orderId: string}`|成功：500；失败：501|路径：`/deleteOrder`（示例）|
|订单详情查询|GET|`{token: string, orderId: string}`|成功：500；失败：501|路径：`/getOrderDetail`（示例）|
### 2.9 个人中心模块

#### 核心功能

- ⚠️ 个人资料展示与修改（暂未实现）
- ✅ 收藏列表（功能完整，但图片显示异常）
- ⚠️ 安全中心（修改密码、注销账号暂未实现）
- ⚠️ 背景图/头像上传（暂未实现）

#### 细化需求

- ⚠️ 资料展示：头像、昵称、背景图、功能入口（我的收藏/订单/安全中心）（暂未实现）
- ⚠️ 资料修改：头像裁剪上传、昵称修改、简介编辑（暂未实现）
- ⚠️ 安全中心：更改密码（旧密码验证）、退出登录（清除Storage）、注销账号（暂未实现）
- ⚠️ 收藏列表：展示用户收藏商品，点击跳转详情页（图片显示异常）

#### API接口信息

|接口名称|请求方式|参数格式|状态码说明|备注|
|---|---|---|---|---|
|用户信息查询|GET|`token: string`|成功：500；失败：501|路径：`/getUserInfo`（示例）|
|资料更新|POST|`{token: string, nickName: string, avatar: string, intro: string}`|成功：500；失败：501|路径：`/updateUserInfo`（示例）|
|密码修改|POST|`{token: string, oldPassword: string, newPassword: string}`|成功：500；失败：501|路径：`/changePassword`（示例）|
|收藏列表查询|GET|`token: string`|成功：500；失败：501|路径：`/getLikeList`（示例）|
|图片上传|POST|`{token: string, file: File}`|成功：500；失败：501|路径：`/uploadImage`（示例），用于头像/背景图|
### 2.10 AI个性化推荐模块

#### 核心功能

- ⚠️ **智能推荐**：基于用户历史订单和收藏偏好的AI个性化推荐（暂未接入AI大模型）
- ⚠️ **精准匹配**：DeepSeek大模型分析用户偏好，生成精准推荐（未实现）
- ⚠️ **数据分析**：自动解析订单数据，提取商品类型和购买频次（未实现）
- ⚠️ **异常处理**：多层fallback机制，确保功能稳定性（未实现）

#### 细化需求

- **数据流程**：历史订单 → 数据解析 → 生成Prompt → 调用DeepSeek API → 解析推荐结果 → 商品匹配 → 界面展示

- **推荐逻辑**：
  - 提取用户购买的商品类型及频次
  - 分析商品名称和分类信息
  - 生成结构化的推荐prompt
  - AI生成个性化推荐建议
  - 在现有商品库中查找匹配商品

- **界面展示**：
  - 首页专属"🤖 为您推荐"区域
  - 展示推荐商品卡片（最多4个）
  - 显示推荐理由和匹配度
  - 支持点击跳转商品详情

- **异常处理**：
  - 无历史订单：显示"暂无个性化推荐"提示
  - API调用失败：自动fallback到热销商品
  - 商品匹配失败：使用随机商品作为推荐

#### 配置步骤

⚠️ **注意**：AI个性化推荐功能暂未实现，以下为预期的配置步骤：

1. **获取DeepSeek API Key**
   - 访问 [DeepSeek平台](https://platform.deepseek.com)
   - 注册账号并完成实名认证
   - 创建API Key并复制

2. **配置API Key**
   ```javascript
   // 编辑 api/api.js 中的 getAIRecommendation 函数
   const DEEPSEEK_API_KEY = 'sk-xxxxxxxxxxxxxxxx'; // 替换为实际API Key
   ```

3. **测试验证**
   - 确保用户已登录且有历史订单
   - 访问首页查看推荐区域
   - 检查控制台API调用日志

#### API接口信息

|接口名称|请求方式|参数格式|状态码说明|备注|
|---|---|---|---|---|
|历史订单查询|GET|`token: string`|成功：500；失败：501|路径：`/getOrderHistory`，用于生成推荐prompt|
|DeepSeek推荐|POST|`{prompt: string}`|成功：200；失败：500|直接调用DeepSeek API，需配置API Key|
|商品匹配查询|GET|`keyword: string`|成功：500；失败：501|在商品库中匹配AI推荐结果|

#### 技术特性

- **智能解析**：支持JSON和文本格式的AI回复解析
- **性能优化**：API调用结果缓存，避免重复请求
- **用户体验**：加载状态提示，错误友好提示
- **扩展性**：支持多种推荐策略和算法调整
## 三、通用接口规范

### 3.1 数据格式要求

- 请求参数：JSON格式（POST）或URL参数（GET）

- 数组参数：需转为JSON字符串（如`flags`、`sids`），后端用`JSON.parse()`解析

- 图片地址：后端返回HTTP格式，前端需转为HTTPS（`replace('http://', 'https://')`）

### 3.2 状态码说明

- 业务成功：500（特殊设计，与常规HTTP状态码区分）

- 业务失败：501、401（权限不足）、700（未登录）等

- HTTP状态码：始终返回200（即使业务失败）

### 3.3 登录状态校验

- 所有需用户权限的接口（如购物袋、订单、地址）需携带`token`参数

- `token`存储在微信小程序`Storage`中，key为`token34`

- 接口返回`code:700`时，需跳转至登录页（`../login/login`）

## 四、数据库设计

### 4.1 数据库表结构

项目使用MySQL数据库，包含以下核心表：

#### 用户相关表
- **`user`**：用户基础信息（手机号、昵称、头像等）
- **`b_user`**：商家用户表（扩展用户类型）
- **`validcode`**：短信验证码表

#### 商品相关表
- **`product`**：商品信息（名称、价格、图片、描述等）
- **`type`**：商品分类表
- **`like`**：用户收藏表

#### 交易相关表
- **`shopcart`**：购物袋表
- **`order`**：订单表
- **`address`**：收货地址表

### 4.2 核心字段说明

#### Product表结构
```sql
CREATE TABLE `product` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键id',
  `pid` varchar(20) NOT NULL COMMENT '商品唯一标识',
  `type_id` varchar(18) NOT NULL COMMENT '商品类型id',
  `name` varchar(120) NOT NULL COMMENT '商品名称',
  `price` decimal(10,2) NOT NULL COMMENT '商品价格',
  `desc` varchar(255) NOT NULL COMMENT '商品描述',
  `small_img` varchar(255) NOT NULL COMMENT '商品小图片',
  `large_img` varchar(255) NOT NULL COMMENT '商品大图片',
  `flag` varchar(255) NOT NULL COMMENT '商品标志(热销、新品等)',
  `enname` varchar(255) NOT NULL COMMENT '英文名称',
  `created_at` datetime NOT NULL,
  `updated_at` datetime NOT NULL,
  PRIMARY KEY (`id`)
);
```

#### Order表结构
```sql
-- 订单表包含订单状态、总价、地址等完整信息
-- 支持订单状态：待付款、待收货、已完成等
```

## 五、部署指南

### 5.1 开发环境部署

1. **后端服务**
   ```bash
   # 启动Node.js + Express服务（由教师提供）
   ```

2. **数据库**
   ```bash
   # 导入数据库文件
   ```

3. **小程序端**
   - 使用微信开发者工具创建项目
   - 修改API基础地址为实际后端地址
   - 编译运行

### 5.2 生产环境部署

**配置生产环境**
   - 修改 `api/api.js` 中的环境配置为生产地址
   - 配置生产数据库连接
   - 设置生产环境的DeepSeek API Key


## 六、开发规范

### 6.1 代码规范

- **命名规范**：使用驼峰命名法，文件使用kebab-case
- **注释规范**：重要函数和复杂逻辑需要添加注释
- **错误处理**：统一的错误处理机制，使用Toast提示用户

### 6.2 接口规范

- **请求格式**：POST使用JSON格式，GET使用URL参数
- **响应格式**：统一的响应结构 `{code, message, result}`
- **状态码**：业务成功500，业务失败501，登录过期700

### 6.3 图片处理规范

- **URL处理**：自动识别HTTP/HTTPS，小程序环境保持HTTP
- **本地回退**：网络图片加载失败时使用本地默认图片
- **性能优化**：支持图片懒加载和缓存机制

## 七、常见问题

### 7.1 图片显示问题

**问题**：商品图片不显示或显示默认图片
**解决**：
1. 检查图片URL是否正确
2. 确认后端图片服务是否正常
3. 查看控制台是否有图片处理相关的错误日志

**问题**：收藏商品无法展示图片
**解决**：
1. 检查收藏列表页面的图片URL处理逻辑
2. 确认图片地址是否正确转换为HTTPS格式
3. 可能是图片URL格式问题，需检查后端返回的数据结构

### 7.2 AI推荐不显示

**问题**：首页不显示个性化推荐区域
**解决**：
1. AI个性化推荐功能暂未实现，这是正常现象
2. 待后续版本接入DeepSeek大模型后，将提供个性化推荐功能
3. 当前版本暂不支持此功能

### 7.3 个人资料功能异常

**问题**：个人资料、修改密码、注销账号等功能无法使用
**解决**：
1. 这些功能暂未实现，为后续版本规划功能
2. 当前版本仅支持基本的用户登录和注册
3. 安全中心相关功能将在后续版本中完善

### 7.4 找回密码功能

**问题**：忘记密码无法找回
**解决**：
1. 找回密码功能暂未实现
2. 当前版本不支持密码找回，请妥善保管密码
3. 建议使用易记的密码或定期修改

### 7.3 登录状态异常

**问题**：用户登录后仍显示未登录状态
**解决**：
1. 检查token存储是否正常
2. 确认API接口返回的token格式
3. 验证登录状态检查函数逻辑

### 7.4 支付功能异常

**问题**：微信支付无法正常调用
**解决**：
1. 检查微信支付相关配置
2. 确认商户号和支付密钥设置
3. 验证支付回调地址配置

## 八、贡献指南

### 8.1 开发流程

1. Fork项目到个人仓库
2. 创建功能分支：`git checkout -b master`
3. 提交代码：`git commit -m "Add new master"`
4. 推送分支：`git push origin master`
5. 创建Pull Request

### 8.2 代码审查标准

- 代码功能完整，符合需求
- 遵循项目代码规范
- 添加必要的注释和文档
- 通过所有测试用例