diff --git a/backend/routes/auth.js b/backend/routes/auth.js index a7d7ec6..33555e8 100644 --- a/backend/routes/auth.js +++ b/backend/routes/auth.js @@ -127,7 +127,7 @@ router.post('/login', async (req, res, next) => { const userData = user[0]; // 验证密码 - const isValidPassword = await bcrypt.compare(password, userData.password); + const isValidPassword = await bcrypt.compare(password, userData.password_hash); if (!isValidPassword) { return res.status(401).json({ code: 401, diff --git a/docs/小程序API接口文档.md b/docs/小程序API接口文档.md new file mode 100644 index 0000000..e6c78f7 --- /dev/null +++ b/docs/小程序API接口文档.md @@ -0,0 +1,975 @@ +# 爱鉴花小程序API接口文档 + +## 概述 + +本文档详细描述爱鉴花微信小程序后端RESTful API接口规范，基于OpenAPI 3.0标准。 + +## 基础信息 + +- **Base URL**: `http://localhost:3200/api/v1` +- **认证方式**: Bearer Token (JWT) +- **响应格式**: JSON +- **字符编码**: UTF-8 + +## 通用响应格式 + +### 成功响应 +```json +{ + "code": 200, + "message": "操作成功", + "data": {} +} +``` + +### 错误响应 +```json +{ + "code": 400, + "message": "参数错误", + "error": "详细错误信息" +} +``` + +## 错误码说明 + +| 错误码 | 说明 | +|--------|------| +| 200 | 成功 | +| 400 | 参数错误 | +| 401 | 未授权 | +| 403 | 禁止访问 | +| 404 | 资源不存在 | +| 500 | 服务器内部错误 | + +## 认证接口 + +### 1. 用户注册 + +**POST** `/auth/register` + +**请求参数**: + +| 参数名 | 类型 | 必填 | 说明 | 示例 | +|--------|------|------|------|------| +| username | string | 是 | 用户名（3-20字符） | "testuser" | +| password | string | 是 | 密码（最少6位） | "123456" | +| phone | string | 是 | 手机号 | "13800138000" | +| email | string | 否 | 邮箱 | "user@example.com" | +| user_type | string | 否 | 用户类型 | "farmer" | + +**响应示例**: +```json +{ + "code": 201, + "message": "注册成功", + "data": { + "user_id": 1, + "username": "testuser", + "phone": "13800138000", + "email": "user@example.com", + "user_type": "farmer", + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + } +} +``` + +### 2. 用户登录 + +**POST** `/auth/login` + +**请求参数**: + +| 参数名 | 类型 | 必填 | 说明 | 示例 | +|--------|------|------|------|------| +| login | string | 是 | 用户名/手机号/邮箱 | "testuser" | +| password | string | 是 | 密码 | "123456" | + +**响应示例**: +```json +{ + "code": 200, + "message": "登录成功", + "data": { + "user_id": 1, + "username": "testuser", + "phone": "13800138000", + "email": "user@example.com", + "user_type": "farmer", + "avatar_url": "/uploads/avatars/avatar.jpg", + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + } +} +``` + +### 3. 获取当前用户信息 + +**GET** `/users/me` + +**请求头**: +``` +Authorization: Bearer +``` + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": { + "id": 1, + "username": "testuser", + "phone": "13800138000", + "email": "user@example.com", + "user_type": "farmer", + "avatar_url": "/uploads/avatars/avatar.jpg", + "created_at": "2023-01-01T00:00:00Z", + "last_login": "2023-01-01T00:00:00Z" + } +} +``` + +## 植物识别接口 + +### 1. 植物识别 + +**POST** `/identifications/identify` + +**请求格式**: `multipart/form-data` + +**请求参数**: + +| 参数名 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| image | file | 是 | 植物图片文件 | +| user_id | integer | 否 | 用户ID（已登录用户） | + +**响应示例**: +```json +{ + "code": 200, + "message": "识别成功", + "data": { + "identification_id": 1, + "plant_name": "玫瑰花", + "scientific_name": "Rosa rugosa", + "family": "蔷薇科", + "confidence": 0.92, + "description": "玫瑰花，蔷薇科蔷薇属植物，具有浓郁的香气...", + "care_tips": "喜阳光，需要充足的水分和肥料...", + "related_products": [ + { + "id": 1, + "name": "玫瑰花束", + "price": 29.9, + "image": "/uploads/products/rose_bouquet.jpg" + } + ] + } +} +``` + +### 2. 获取识别历史 + +**GET** `/identifications/history` + +**请求头**: +``` +Authorization: Bearer +``` + +**查询参数**: + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| page | integer | 页码（默认1） | +| limit | integer | 每页数量（默认10） | + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": { + "identifications": [ + { + "id": 1, + "plant_name": "玫瑰花", + "image_url": "/uploads/identifications/rose_123.jpg", + "confidence": 0.92, + "created_at": "2023-01-01T10:00:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 10, + "total": 15, + "pages": 2 + } + } +} +``` + +## 商品接口 + +### 1. 获取商品列表 + +**GET** `/products` + +**查询参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| page | integer | 页码（默认1） | 1 | +| limit | integer | 每页数量（默认12） | 12 | +| category_id | integer | 分类ID | 1 | +| keyword | string | 搜索关键词 | "玫瑰" | +| min_price | number | 最低价格 | 10 | +| max_price | number | 最高价格 | 100 | +| sort_by | string | 排序字段 | "price" | +| sort_order | string | 排序方向 | "asc" | + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": { + "products": [ + { + "id": 1, + "name": "玫瑰花束", + "category_id": 1, + "price": 29.9, + "original_price": 39.9, + "stock": 100, + "image": "/uploads/products/rose_bouquet.jpg", + "description": "新鲜玫瑰花束，香气浓郁，适合送礼", + "category_name": "鲜花", + "sales_count": 150, + "rating": 4.8, + "review_count": 45 + } + ], + "pagination": { + "page": 1, + "limit": 12, + "total": 50, + "pages": 5 + } + } +} +``` + +### 2. 获取商品详情 + +**GET** `/products/{id}` + +**路径参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| id | integer | 商品ID | 1 | + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": { + "id": 1, + "name": "玫瑰花束", + "category_id": 1, + "price": 29.9, + "original_price": 39.9, + "stock": 100, + "images": [ + "/uploads/products/rose_bouquet_1.jpg", + "/uploads/products/rose_bouquet_2.jpg" + ], + "description": "新鲜玫瑰花束，包含12朵红玫瑰...", + "details": "花材：红玫瑰12朵\n包装：精美礼盒包装\n配送：同城2小时配送", + "care_instructions": "放置在阴凉处，定期换水...", + "category_name": "鲜花", + "sales_count": 150, + "rating": 4.8, + "review_count": 45, + "reviews": [ + { + "user_name": "张*", + "rating": 5, + "content": "花很新鲜，包装精美", + "created_at": "2023-01-01T10:00:00Z" + } + ] + } +} +``` + +### 3. 获取商品分类 + +**GET** `/categories` + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": [ + { + "id": 1, + "name": "鲜花", + "icon": "/icons/flowers.png", + "product_count": 25 + }, + { + "id": 2, + "name": "盆栽", + "icon": "/icons/potted_plants.png", + "product_count": 18 + } + ] +} +``` + +## 购物车接口 + +### 1. 获取购物车 + +**GET** `/cart` + +**请求头**: +``` +Authorization: Bearer +``` + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": { + "items": [ + { + "id": 1, + "product_id": 1, + "product_name": "玫瑰花束", + "product_image": "/uploads/products/rose_bouquet.jpg", + "price": 29.9, + "quantity": 2, + "subtotal": 59.8, + "stock": 100 + } + ], + "total_amount": 59.8, + "total_quantity": 2 + } +} +``` + +### 2. 添加商品到购物车 + +**POST** `/cart/items` + +**请求头**: +``` +Authorization: Bearer +``` + +**请求参数**: + +| 参数名 | 类型 | 必填 | 说明 | 示例 | +|--------|------|------|------|------| +| product_id | integer | 是 | 商品ID | 1 | +| quantity | integer | 是 | 数量 | 2 | + +**响应示例**: +```json +{ + "code": 200, + "message": "添加成功", + "data": { + "cart_item_id": 1 + } +} +``` + +### 3. 更新购物车商品数量 + +**PUT** `/cart/items/{id}` + +**请求头**: +``` +Authorization: Bearer +``` + +**路径参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| id | integer | 购物车项ID | 1 | + +**请求参数**: + +| 参数名 | 类型 | 必填 | 说明 | 示例 | +|--------|------|------|------|------| +| quantity | integer | 是 | 数量 | 3 | + +**响应示例**: +```json +{ + "code": 200, + "message": "更新成功" +} +``` + +### 4. 删除购物车商品 + +**DELETE** `/cart/items/{id}` + +**请求头**: +``` +Authorization: Bearer +``` + +**路径参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| id | integer | 购物车项ID | 1 | + +**响应示例**: +```json +{ + "code": 200, + "message": "删除成功" +} +``` + +## 订单接口 + +### 1. 创建订单 + +**POST** `/orders` + +**请求头**: +``` +Authorization: Bearer +``` + +**请求参数**: + +| 参数名 | 类型 | 必填 | 说明 | 示例 | +|--------|------|------|------|------| +| items | array | 是 | 商品列表 | - | +| address_id | integer | 是 | 收货地址ID | 1 | +| coupon_code | string | 否 | 优惠券代码 | "WELCOME10" | +| remark | string | 否 | 订单备注 | "请下午配送" | + +**items数组结构**: +```json +[ + { + "product_id": 1, + "quantity": 2 + } +] +``` + +**响应示例**: +```json +{ + "code": 201, + "message": "订单创建成功", + "data": { + "order_id": 1, + "order_no": "ORDER202301010001", + "total_amount": 59.8, + "payment_amount": 59.8, + "pay_url": "/pay/order/ORDER202301010001" + } +} +``` + +### 2. 获取订单列表 + +**GET** `/orders` + +**请求头**: +``` +Authorization: Bearer +``` + +**查询参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| page | integer | 页码（默认1） | 1 | +| limit | integer | 每页数量（默认10） | 10 | +| status | string | 订单状态 | "pending" | + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": { + "orders": [ + { + "id": 1, + "order_no": "ORDER202301010001", + "total_amount": 59.8, + "status": "pending", + "status_text": "待支付", + "created_at": "2023-01-01T10:00:00Z", + "items": [ + { + "product_name": "玫瑰花束", + "product_image": "/uploads/products/rose_bouquet.jpg", + "quantity": 2, + "price": 29.9 + } + ] + } + ], + "pagination": { + "page": 1, + "limit": 10, + "total": 5, + "pages": 1 + } + } +} +``` + +### 3. 获取订单详情 + +**GET** `/orders/{id}` + +**请求头**: +``` +Authorization: Bearer +``` + +**路径参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| id | integer | 订单ID | 1 | + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": { + "id": 1, + "order_no": "ORDER202301010001", + "total_amount": 59.8, + "payment_amount": 59.8, + "status": "paid", + "status_text": "已支付", + "shipping_address": { + "recipient": "张三", + "phone": "13800138000", + "address": "北京市海淀区中关村大街1号" + }, + "items": [ + { + "product_id": 1, + "product_name": "玫瑰花束", + "product_image": "/uploads/products/rose_bouquet.jpg", + "quantity": 2, + "price": 29.9, + "subtotal": 59.8 + } + ], + "payment_info": { + "payment_method": "wechat", + "payment_time": "2023-01-01T10:05:00Z", + "transaction_id": "4200001234567890" + }, + "shipping_info": { + "shipping_method": "express", + "tracking_number": "SF1234567890", + "estimated_delivery": "2023-01-01T14:00:00Z" + }, + "created_at": "2023-01-01T10:00:00Z", + "paid_at": "2023-01-01T10:05:00Z" + } +} +``` + +## 收货地址接口 + +### 1. 获取收货地址列表 + +**GET** `/addresses` + +**请求头**: +``` +Authorization: Bearer +``` + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": [ + { + "id": 1, + "recipient": "张三", + "phone": "13800138000", + "province": "北京市", + "city": "北京市", + "district": "海淀区", + "detail": "中关村大街1号", + "is_default": true, + "created_at": "2023-01-01T00:00:00Z" + } + ] +} +``` + +### 2. 添加收货地址 + +**POST** `/addresses` + +**请求头**: +``` +Authorization: Bearer +``` + +**请求参数**: + +| 参数名 | 类型 | 必填 | 说明 | 示例 | +|--------|------|------|------|------| +| recipient | string | 是 | 收货人 | "张三" | +| phone | string | 是 | 手机号 | "13800138000" | +| province | string | 是 | 省份 | "北京市" | +| city | string | 是 | 城市 | "北京市" | +| district | string | 是 | 区县 | "海淀区" | +| detail | string | 是 | 详细地址 | "中关村大街1号" | +| is_default | boolean | 否 | 是否默认 | true | + +**响应示例**: +```json +{ + "code": 201, + "message": "添加成功", + "data": { + "address_id": 1 + } +} +``` + +### 3. 更新收货地址 + +**PUT** `/addresses/{id}` + +**请求头**: +``` +Authorization: Bearer +``` + +**路径参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| id | integer | 地址ID | 1 | + +**请求参数**: + +| 参数名 | 类型 | 必填 | 说明 | 示例 | +|--------|------|------|------|------| +| recipient | string | 否 | 收货人 | "张三" | +| phone | string | 否 | 手机号 | "13800138000" | +| province | string | 否 | 省份 | "北京市" | +| city | string | 否 | 城市 | "北京市" | +| district | string | 否 | 区县 | "海淀区" | +| detail | string | 否 | 详细地址 | "中关村大街1号" | +| is_default | boolean | 否 | 是否默认 | true | + +**响应示例**: +```json +{ + "code": 200, + "message": "更新成功" +} +``` + +### 4. 删除收货地址 + +**DELETE** `/addresses/{id}` + +**请求头**: +``` +Authorization: Bearer +``` + +**路径参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| id | integer | 地址ID | 1 | + +**响应示例**: +```json +{ + "code": 200, + "message": "删除成功" +} +``` + +## 推广奖励接口 + +### 1. 获取推广信息 + +**GET** `/promotion/info` + +**请求头**: +``` +Authorization: Bearer +``` + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": { + "promotion_code": "PROMO123456", + "qr_code_url": "/uploads/qrcodes/promo_123456.png", + "promotion_url": "https://aijianhua.com/promo/PROMO123456", + "total_invites": 15, + "successful_orders": 8, + "total_earnings": 120.5, + "available_balance": 85.3, + "withdrawn_amount": 35.2 + } +} +``` + +### 2. 获取推广记录 + +**GET** `/promotion/records` + +**请求头**: +``` +Authorization: Bearer +``` + +**查询参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| page | integer | 页码（默认1） | 1 | +| limit | integer | 每页数量（默认10） | 10 | +| type | string | 记录类型 | "invite" | + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": { + "records": [ + { + "id": 1, + "type": "invite", + "user_name": "李*", + "phone": "138****0000", + "amount": 10.0, + "status": "completed", + "created_at": "2023-01-01T10:00:00Z" + }, + { + "id": 2, + "type": "order_commission", + "user_name": "王*", + "order_amount": 299.0, + "amount": 29.9, + "status": "pending", + "created_at": "2023-01-02T14:30:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 10, + "total": 25, + "pages": 3 + } + } +} +``` + +### 3. 申请提现 + +**POST** `/promotion/withdraw` + +**请求头**: +``` +Authorization: Bearer +``` + +**请求参数**: + +| 参数名 | 类型 | 必填 | 说明 | 示例 | +|--------|------|------|------|------| +| amount | number | 是 | 提现金额 | 50.0 | +| payment_method | string | 是 | 支付方式 | "wechat" | +| account_info | string | 是 | 账户信息 | "wx_1234567890" | + +**响应示例**: +```json +{ + "code": 200, + "message": "提现申请已提交", + "data": { + "withdraw_id": 1, + "amount": 50.0, + "status": "processing", + "estimated_arrival": "2023-01-03T10:00:00Z" + } +} +``` + +### 4. 获取提现记录 + +**GET** `/promotion/withdrawals` + +**请求头**: +``` +Authorization: Bearer +``` + +**查询参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| page | integer | 页码（默认1） | 1 | +| limit | integer | 每页数量（默认10） | 10 | + +**响应示例**: +```json +{ + "code": 200, + "message": "获取成功", + "data": { + "withdrawals": [ + { + "id": 1, + "amount": 50.0, + "payment_method": "wechat", + "status": "completed", + "completed_at": "2023-01-03T10:00:00Z", + "created_at": "2023-01-01T10:00:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 10, + "total": 5, + "pages": 1 + } + } +} +``` + +## 支付接口 + +### 1. 发起支付 + +**POST** `/pay/orders/{order_no}` + +**请求头**: +``` +Authorization: Bearer +``` + +**路径参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| order_no | string | 订单编号 | "ORDER202301010001" | + +**响应示例**: +```json +{ + "code": 200, + "message": "支付参数生成成功", + "data": { + "payment_params": { + "timeStamp": "1672531200", + "nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS", + "package": "prepay_id=wx201410272009395522fsd8f8f8f8f8f8", + "signType": "MD5", + "paySign": "C380BEC2BFD727A4B6845133519F3AD6" + } + } +} +``` + +### 2. 查询支付结果 + +**GET** `/pay/orders/{order_no}/status` + +**请求头**: +``` +Authorization: Bearer +``` + +**路径参数**: + +| 参数名 | 类型 | 说明 | 示例 | +|--------|------|------|------| +| order_no | string | 订单编号 | "ORDER202301010001" | + +**响应示例**: +```json +{ + "code": 200, + "message": "查询成功", + "data": { + "order_no": "ORDER202301010001", + "payment_status": "paid", + "paid_amount": 59.8, + "paid_at": "2023-01-01T10:05:00Z" + } +} +``` + +## 文件上传接口 + +### 1. 上传文件 + +**POST** `/upload` + +**请求格式**: `multipart/form-data` + +**请求参数**: + +| 参数名 | 类型 | 必填 | 说明 | 示例 | +|--------|------|------|------|------| +| file | file | 是 | 上传文件 | - | +| type | string | 否 | 文件类型 | "avatar" | + +**响应示例**: +```json +{ + "code": 200, + "message": "上传成功", + "data": { + "url": "/uploads/avatars/avatar_123.jpg", + "filename": "avatar_123.jpg", + "size": 102400, + "mime_type": "image/jpeg" + } +} +``` + +--- + +*本文档最后更新: 2024-01-15* +*API版本: v1.0* \ No newline at end of file