docs: 更新项目文档，完善需求和技术细节

2025-09-01 02:35:41 +08:00
parent e1647902e2
commit ad20888cd4
57 changed files with 961 additions and 156 deletions
--- a/docs/API接口文档.md
+++ b/docs/API接口文档.md
@@ -0,0 +1,454 @@
+# 爱鉴花小程序后端API接口文档
+
+## 概述
+
+本文档详细描述了爱鉴花小程序后端RESTful API接口规范，基于OpenAPI 3.0标准。
+
+## 基础信息
+
+- **Base URL**: `http://localhost:3200/api/v1`
+- **认证方式**: Bearer Token (JWT)
+- **响应格式**: JSON
+
+## 认证接口
+
+### 用户注册
+
+**POST** `/auth/register`
+
+**请求参数**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| username | string | 是 | 用户名 |
+| password | string | 是 | 密码（最少6位） |
+| phone | string | 是 | 手机号 |
+| email | string | 否 | 邮箱 |
+| user_type | string | 否 | 用户类型（farmer/buyer/admin） |
+
+**响应示例**:
+
+```json
+{
+  "code": 201,
+  "message": "注册成功",
+  "data": {
+    "user_id": 1,
+    "username": "testuser",
+    "phone": "13800138000",
+    "email": "user@example.com",
+    "user_type": "farmer",
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+}
+```
+
+### 用户登录
+
+**POST** `/auth/login`
+
+**请求参数**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| login | string | 是 | 用户名/手机号/邮箱 |
+| password | string | 是 | 密码 |
+
+**响应示例**:
+
+```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..."
+  }
+}
+```
+
+## 用户接口
+
+### 获取用户信息
+
+**GET** `/users/me`
+
+**请求头**:
+```
+Authorization: Bearer <token>
+```
+
+**响应示例**:
+
+```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"
+  }
+}
+```
+
+### 更新用户信息
+
+**PUT** `/users/{id}`
+
+**请求参数**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| email | string | 否 | 邮箱 |
+| real_name | string | 否 | 真实姓名 |
+| avatar_url | string | 否 | 头像URL |
+
+## 商品接口
+
+### 获取商品列表
+
+**GET** `/products`
+
+**查询参数**:
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| page | integer | 页码（默认1） |
+| limit | integer | 每页数量（默认12） |
+| category_id | integer | 分类ID |
+| keyword | string | 搜索关键词 |
+| min_price | number | 最低价格 |
+| max_price | number | 最高价格 |
+| sort_by | string | 排序字段（name/price/created_at/stock） |
+| sort_order | string | 排序方向（asc/desc） |
+
+**响应示例**:
+
+```json
+{
+  "code": 200,
+  "message": "获取成功",
+  "data": {
+    "products": [
+      {
+        "id": 1,
+        "name": "玫瑰花",
+        "category_id": 1,
+        "price": 29.9,
+        "stock": 100,
+        "image": "/uploads/products/rose.jpg",
+        "description": "新鲜玫瑰花，香气浓郁",
+        "category_name": "鲜花"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "limit": 12,
+      "total": 50,
+      "pages": 5
+    }
+  }
+}
+```
+
+### 获取商品详情
+
+**GET** `/products/{id}`
+
+## 订单接口
+
+### 创建订单
+
+**POST** `/orders`
+
+**请求参数**:
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| items | array | 是 | 商品列表 |
+| shipping_address | string | 是 | 收货地址 |
+
+**items数组结构**:
+```json
+[
+  {
+    "product_id": 1,
+    "quantity": 2
+  }
+]
+```
+
+## 花卉识别接口
+
+### 花卉识别
+
+**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,
+    "care_tips": "喜阳光，需要充足水分",
+    "related_products": [
+      {
+        "id": 1,
+        "name": "玫瑰花束",
+        "price": 29.9,
+        "image": "/uploads/products/rose.jpg"
+      }
+    ],
+    "created_at": "2024-01-15T10:30:00Z"
+  }
+}
+```
+
+### 获取识别历史
+
+**GET** `/identifications/history`
+
+**查询参数**:
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| user_id | integer | 用户ID |
+| 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": "2024-01-15T10:30:00Z"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "limit": 10,
+      "total": 15,
+      "pages": 2
+    }
+  }
+}
+```
+
+## 推广奖励接口
+
+### 生成推广链接
+
+**POST** `/promotions/generate-link`
+
+**请求头**:
+```
+Authorization: Bearer <token>
+```
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "生成成功",
+  "data": {
+    "promotion_link": "https://aijianhua.com/register?ref=ABC123",
+    "qr_code_url": "/uploads/qrcodes/ABC123.png",
+    "expires_at": "2024-02-15T10:30:00Z"
+  }
+}
+```
+
+### 获取推广数据
+
+**GET** `/promotions/stats`
+
+**查询参数**:
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| start_date | string | 开始日期（YYYY-MM-DD） |
+| end_date | string | 结束日期（YYYY-MM-DD） |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "获取成功",
+  "data": {
+    "total_referrals": 50,
+    "successful_orders": 25,
+    "pending_rewards": 250.00,
+    "withdrawn_rewards": 500.00,
+    "available_balance": 250.00,
+    "daily_stats": [
+      {
+        "date": "2024-01-15",
+        "referrals": 5,
+        "orders": 3,
+        "rewards": 30.00
+      }
+    ]
+  }
+}
+```
+
+### 申请提现
+
+**POST** `/promotions/withdraw`
+
+**请求参数**:
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| amount | number | 是 | 提现金额（≥50元） |
+| bank_account | string | 是 | 银行账号 |
+| bank_name | string | 是 | 银行名称 |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "提现申请已提交",
+  "data": {
+    "withdrawal_id": 1,
+    "amount": 100.00,
+    "status": "pending",
+    "estimated_arrival": "2024-01-16T10:30:00Z"
+  }
+}
+```
+
+### 获取提现记录
+
+**GET** `/promotions/withdrawals`
+
+**查询参数**:
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| page | integer | 页码（默认1） |
+| limit | integer | 每页数量（默认10） |
+| status | string | 状态（pending/completed/rejected） |
+
+**响应示例**:
+```json
+{
+  "code": 200,
+  "message": "获取成功",
+  "data": {
+    "withdrawals": [
+      {
+        "id": 1,
+        "amount": 100.00,
+        "status": "completed",
+        "bank_account": "****1234",
+        "bank_name": "中国银行",
+        "created_at": "2024-01-15T10:30:00Z",
+        "completed_at": "2024-01-16T10:30:00Z"
+      }
+    ],
+    "pagination": {
+      "page": 1,
+      "limit": 10,
+      "total": 5,
+      "pages": 1
+    }
+  }
+}
+```
+
+## 错误码规范
+
+| 错误码 | 错误信息 | 说明 |
+|--------|----------|------|
+| 200 | 成功 | 请求成功 |
+| 201 | 创建成功 | 资源创建成功 |
+| 400 | 参数错误 | 请求参数验证失败 |
+| 401 | 未授权 | 需要登录认证 |
+| 403 | 禁止访问 | 权限不足 |
+| 404 | 资源不存在 | 请求的资源不存在 |
+| 409 | 资源冲突 | 资源已存在或状态冲突 |
+| 500 | 服务器内部错误 | 服务器内部处理错误 |
+| 1001 | 识别失败 | 植物识别处理失败 |
+| 1002 | 图片格式不支持 | 上传的图片格式不支持 |
+| 2001 | 推广奖励不足 | 可提现余额不足50元 |
+| 2002 | 提现频率限制 | 24小时内只能提现一次 |
+| 3001 | 库存不足 | 商品库存不足 |
+| 3002 | 订单状态异常 | 订单状态不允许此操作 |
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| image | file | 是 | 花卉图片文件 |
+
+**响应示例**:
+
+```json
+{
+  "code": 200,
+  "message": "识别成功",
+  "data": {
+    "identification_id": 1,
+    "image_url": "/uploads/identifications/identify-123.jpg",
+    "results": [
+      {
+        "name": "玫瑰",
+        "confidence": 0.95,
+        "scientificName": "Rosa rugosa",
+        "description": "玫瑰是蔷薇科蔷薇属的植物，具有浓郁的芳香和美丽的花朵。"
+      }
+    ],
+    "best_result": {
+      "name": "玫瑰",
+      "confidence": 0.95,
+      "scientificName": "Rosa rugosa",
+      "description": "玫瑰是蔷薇科蔷薇属的植物，具有浓郁的芳香和美丽的花朵。"
+    }
+  }
+}
+```
+
+### 获取识别历史
+
+**GET** `/identifications`
+
+
+
+## 安全要求
+
+1. 所有敏感接口必须使用HTTPS
+2. JWT token有效期7天
+3. 密码使用bcrypt加密存储
+4. 文件上传限制10MB
+5. 支持CORS跨域访问
+
+## 版本历史
+
+- v1.0.0 (2024-03-15): 初始版本发布
+- 包含用户认证、商品管理、订单管理、花卉识别等核心功能