升级商城逻辑
This commit is contained in:
79
docs/README.md
Normal file
79
docs/README.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# API 文档结构说明
|
||||
|
||||
本项目已将 Swagger API 文档从路由文件中分离出来，采用模块化的文档管理方式。
|
||||
|
||||
## 文件夹结构
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README.md # 本说明文件
|
||||
├── schemas/ # 数据模型定义
|
||||
│ ├── product.js # 商品相关数据模型
|
||||
│ ├── order.js # 订单相关数据模型
|
||||
│ ├── user.js # 用户相关数据模型
|
||||
│ └── cart.js # 购物车相关数据模型
|
||||
└── apis/ # API 接口定义
|
||||
├── products.js # 商品相关 API
|
||||
└── orders.js # 订单相关 API
|
||||
```
|
||||
|
||||
## 优势
|
||||
|
||||
1. **模块化管理**: 按功能模块分离文档，便于维护和查找
|
||||
2. **代码分离**: 路由文件专注于业务逻辑，文档定义独立管理
|
||||
3. **复用性**: Schema 定义可以在多个 API 中复用
|
||||
4. **可维护性**: 文档修改不会影响业务代码，降低出错风险
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 添加新的 Schema
|
||||
|
||||
在 `schemas/` 文件夹中创建新的 `.js` 文件，使用 `@swagger` 注释定义数据模型：
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* @swagger
|
||||
* components:
|
||||
* schemas:
|
||||
* YourModel:
|
||||
* type: object
|
||||
* properties:
|
||||
* id:
|
||||
* type: integer
|
||||
* description: ID
|
||||
*/
|
||||
```
|
||||
|
||||
### 添加新的 API 文档
|
||||
|
||||
在 `apis/` 文件夹中创建新的 `.js` 文件，使用 `@swagger` 注释定义 API 接口：
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* @swagger
|
||||
* tags:
|
||||
* name: YourModule
|
||||
* description: 模块描述
|
||||
*/
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /your-endpoint:
|
||||
* get:
|
||||
* summary: 接口描述
|
||||
* tags: [YourModule]
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 成功响应
|
||||
*/
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
Swagger 配置文件 `swagger.js` 已更新扫描路径：
|
||||
|
||||
```javascript
|
||||
apis: ['./docs/schemas/*.js', './docs/apis/*.js', './routes/*.js', './admin/routes/*.js']
|
||||
```
|
||||
|
||||
这样既保持了对现有路由文件中文档的兼容性，又支持新的模块化文档结构。
|
||||
236
docs/apis/orders.js
Normal file
236
docs/apis/orders.js
Normal file
@@ -0,0 +1,236 @@
|
||||
/**
|
||||
* @swagger
|
||||
* tags:
|
||||
* name: Orders
|
||||
* description: 订单管理API
|
||||
*/
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /orders/create-from-cart:
|
||||
* post:
|
||||
* summary: 从购物车创建预订单
|
||||
* tags: [Orders]
|
||||
* requestBody:
|
||||
* required: true
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* required:
|
||||
* - cartIds
|
||||
* properties:
|
||||
* cartIds:
|
||||
* type: array
|
||||
* items:
|
||||
* type: integer
|
||||
* description: 购物车商品ID数组
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 成功创建预订单
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* data:
|
||||
* $ref: '#/components/schemas/PreOrder'
|
||||
* 400:
|
||||
* description: 请求参数错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* message:
|
||||
* type: string
|
||||
*/
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /orders/pre-order/{id}:
|
||||
* get:
|
||||
* summary: 获取预订单详情
|
||||
* tags: [Orders]
|
||||
* parameters:
|
||||
* - in: path
|
||||
* name: id
|
||||
* required: true
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: 预订单ID
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 成功获取预订单详情
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* data:
|
||||
* type: object
|
||||
* properties:
|
||||
* preOrder:
|
||||
* $ref: '#/components/schemas/PreOrder'
|
||||
* items:
|
||||
* type: array
|
||||
* items:
|
||||
* type: object
|
||||
* properties:
|
||||
* product_id:
|
||||
* type: integer
|
||||
* product_name:
|
||||
* type: string
|
||||
* quantity:
|
||||
* type: integer
|
||||
* points_price:
|
||||
* type: integer
|
||||
* rongdou_price:
|
||||
* type: number
|
||||
* image_url:
|
||||
* type: string
|
||||
* 404:
|
||||
* description: 预订单不存在
|
||||
*/
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /orders/confirm:
|
||||
* post:
|
||||
* summary: 确认下单
|
||||
* tags: [Orders]
|
||||
* requestBody:
|
||||
* required: true
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* required:
|
||||
* - preOrderId
|
||||
* - shippingAddress
|
||||
* properties:
|
||||
* preOrderId:
|
||||
* type: integer
|
||||
* description: 预订单ID
|
||||
* shippingAddress:
|
||||
* type: string
|
||||
* description: 收货地址
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 订单确认成功
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* data:
|
||||
* type: object
|
||||
* properties:
|
||||
* orderId:
|
||||
* type: integer
|
||||
* orderNumber:
|
||||
* type: string
|
||||
* 400:
|
||||
* description: 请求参数错误或余额不足
|
||||
* 404:
|
||||
* description: 预订单不存在
|
||||
*/
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /orders:
|
||||
* get:
|
||||
* summary: 获取用户订单列表
|
||||
* tags: [Orders]
|
||||
* parameters:
|
||||
* - in: query
|
||||
* name: page
|
||||
* schema:
|
||||
* type: integer
|
||||
* default: 1
|
||||
* description: 页码
|
||||
* - in: query
|
||||
* name: limit
|
||||
* schema:
|
||||
* type: integer
|
||||
* default: 10
|
||||
* description: 每页数量
|
||||
* - in: query
|
||||
* name: status
|
||||
* schema:
|
||||
* type: string
|
||||
* enum: [pending, confirmed, shipped, delivered, cancelled]
|
||||
* description: 订单状态筛选
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 成功获取订单列表
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* data:
|
||||
* type: object
|
||||
* properties:
|
||||
* orders:
|
||||
* type: array
|
||||
* items:
|
||||
* $ref: '#/components/schemas/Order'
|
||||
* pagination:
|
||||
* type: object
|
||||
* properties:
|
||||
* page:
|
||||
* type: integer
|
||||
* limit:
|
||||
* type: integer
|
||||
* total:
|
||||
* type: integer
|
||||
* pages:
|
||||
* type: integer
|
||||
*/
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /orders/{id}:
|
||||
* get:
|
||||
* summary: 获取订单详情
|
||||
* tags: [Orders]
|
||||
* parameters:
|
||||
* - in: path
|
||||
* name: id
|
||||
* required: true
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: 订单ID
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 成功获取订单详情
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* data:
|
||||
* type: object
|
||||
* properties:
|
||||
* order:
|
||||
* $ref: '#/components/schemas/Order'
|
||||
* items:
|
||||
* type: array
|
||||
* items:
|
||||
* $ref: '#/components/schemas/OrderItem'
|
||||
* 404:
|
||||
* description: 订单不存在
|
||||
*/
|
||||
154
docs/apis/products.js
Normal file
154
docs/apis/products.js
Normal file
@@ -0,0 +1,154 @@
|
||||
/**
|
||||
* @swagger
|
||||
* tags:
|
||||
* name: Products
|
||||
* description: 商品管理API
|
||||
*/
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /products:
|
||||
* get:
|
||||
* summary: 获取商品列表
|
||||
* tags: [Products]
|
||||
* parameters:
|
||||
* - in: query
|
||||
* name: page
|
||||
* schema:
|
||||
* type: integer
|
||||
* default: 1
|
||||
* description: 页码
|
||||
* - in: query
|
||||
* name: limit
|
||||
* schema:
|
||||
* type: integer
|
||||
* default: 10
|
||||
* description: 每页数量
|
||||
* - in: query
|
||||
* name: search
|
||||
* schema:
|
||||
* type: string
|
||||
* description: 搜索关键词
|
||||
* - in: query
|
||||
* name: category
|
||||
* schema:
|
||||
* type: string
|
||||
* description: 商品分类
|
||||
* - in: query
|
||||
* name: status
|
||||
* schema:
|
||||
* type: string
|
||||
* enum: [active, inactive]
|
||||
* description: 商品状态
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 成功获取商品列表
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* data:
|
||||
* type: object
|
||||
* properties:
|
||||
* products:
|
||||
* type: array
|
||||
* items:
|
||||
* $ref: '#/components/schemas/Product'
|
||||
* pagination:
|
||||
* type: object
|
||||
* properties:
|
||||
* page:
|
||||
* type: integer
|
||||
* limit:
|
||||
* type: integer
|
||||
* total:
|
||||
* type: integer
|
||||
* pages:
|
||||
* type: integer
|
||||
*/
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /products/categories:
|
||||
* get:
|
||||
* summary: 获取商品分类列表
|
||||
* tags: [Products]
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 成功获取分类列表
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* data:
|
||||
* type: array
|
||||
* items:
|
||||
* type: string
|
||||
*/
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /products/hot:
|
||||
* get:
|
||||
* summary: 获取热门商品
|
||||
* tags: [Products]
|
||||
* parameters:
|
||||
* - in: query
|
||||
* name: limit
|
||||
* schema:
|
||||
* type: integer
|
||||
* default: 10
|
||||
* description: 返回数量
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 成功获取热门商品
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* data:
|
||||
* type: object
|
||||
* properties:
|
||||
* products:
|
||||
* type: array
|
||||
* items:
|
||||
* $ref: '#/components/schemas/Product'
|
||||
*/
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /products/{id}:
|
||||
* get:
|
||||
* summary: 获取商品详情
|
||||
* tags: [Products]
|
||||
* parameters:
|
||||
* - in: path
|
||||
* name: id
|
||||
* required: true
|
||||
* schema:
|
||||
* type: integer
|
||||
* description: 商品ID
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 成功获取商品详情
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* data:
|
||||
* $ref: '#/components/schemas/Product'
|
||||
* 404:
|
||||
* description: 商品不存在
|
||||
*/
|
||||
93
docs/schemas/cart.js
Normal file
93
docs/schemas/cart.js
Normal file
@@ -0,0 +1,93 @@
|
||||
/**
|
||||
* @swagger
|
||||
* components:
|
||||
* schemas:
|
||||
* CartItem:
|
||||
* type: object
|
||||
* required:
|
||||
* - user_id
|
||||
* - product_id
|
||||
* - quantity
|
||||
* properties:
|
||||
* id:
|
||||
* type: integer
|
||||
* description: 购物车商品ID
|
||||
* user_id:
|
||||
* type: integer
|
||||
* description: 用户ID
|
||||
* product_id:
|
||||
* type: integer
|
||||
* description: 商品ID
|
||||
* quantity:
|
||||
* type: integer
|
||||
* description: 商品数量
|
||||
* created_at:
|
||||
* type: string
|
||||
* format: date-time
|
||||
* description: 创建时间
|
||||
* updated_at:
|
||||
* type: string
|
||||
* format: date-time
|
||||
* description: 更新时间
|
||||
*
|
||||
* CartItemWithProduct:
|
||||
* type: object
|
||||
* properties:
|
||||
* id:
|
||||
* type: integer
|
||||
* description: 购物车商品ID
|
||||
* product_id:
|
||||
* type: integer
|
||||
* description: 商品ID
|
||||
* product_name:
|
||||
* type: string
|
||||
* description: 商品名称
|
||||
* quantity:
|
||||
* type: integer
|
||||
* description: 商品数量
|
||||
* points_price:
|
||||
* type: integer
|
||||
* description: 积分价格
|
||||
* rongdou_price:
|
||||
* type: number
|
||||
* description: 融豆价格
|
||||
* image_url:
|
||||
* type: string
|
||||
* description: 商品图片URL
|
||||
* stock:
|
||||
* type: integer
|
||||
* description: 库存数量
|
||||
* payment_methods:
|
||||
* type: array
|
||||
* items:
|
||||
* type: string
|
||||
* description: 支付方式列表
|
||||
* created_at:
|
||||
* type: string
|
||||
* format: date-time
|
||||
* description: 创建时间
|
||||
*
|
||||
* AddToCartRequest:
|
||||
* type: object
|
||||
* required:
|
||||
* - product_id
|
||||
* - quantity
|
||||
* properties:
|
||||
* product_id:
|
||||
* type: integer
|
||||
* description: 商品ID
|
||||
* quantity:
|
||||
* type: integer
|
||||
* minimum: 1
|
||||
* description: 商品数量
|
||||
*
|
||||
* UpdateCartRequest:
|
||||
* type: object
|
||||
* required:
|
||||
* - quantity
|
||||
* properties:
|
||||
* quantity:
|
||||
* type: integer
|
||||
* minimum: 1
|
||||
* description: 商品数量
|
||||
*/
|
||||
102
docs/schemas/order.js
Normal file
102
docs/schemas/order.js
Normal file
@@ -0,0 +1,102 @@
|
||||
/**
|
||||
* @swagger
|
||||
* components:
|
||||
* schemas:
|
||||
* Order:
|
||||
* type: object
|
||||
* required:
|
||||
* - user_id
|
||||
* - total_amount
|
||||
* - status
|
||||
* properties:
|
||||
* id:
|
||||
* type: integer
|
||||
* description: 订单ID
|
||||
* order_number:
|
||||
* type: string
|
||||
* description: 订单号
|
||||
* user_id:
|
||||
* type: integer
|
||||
* description: 用户ID
|
||||
* total_amount:
|
||||
* type: number
|
||||
* description: 订单总金额
|
||||
* total_points:
|
||||
* type: integer
|
||||
* description: 订单总积分
|
||||
* total_rongdou:
|
||||
* type: number
|
||||
* description: 订单总融豆
|
||||
* status:
|
||||
* type: string
|
||||
* description: 订单状态
|
||||
* enum: [pending, confirmed, shipped, delivered, cancelled]
|
||||
* payment_status:
|
||||
* type: string
|
||||
* description: 支付状态
|
||||
* enum: [pending, paid, failed, refunded]
|
||||
* shipping_address:
|
||||
* type: string
|
||||
* description: 收货地址
|
||||
* created_at:
|
||||
* type: string
|
||||
* format: date-time
|
||||
* description: 创建时间
|
||||
* updated_at:
|
||||
* type: string
|
||||
* format: date-time
|
||||
* description: 更新时间
|
||||
*
|
||||
* OrderItem:
|
||||
* type: object
|
||||
* properties:
|
||||
* id:
|
||||
* type: integer
|
||||
* description: 订单商品ID
|
||||
* order_id:
|
||||
* type: integer
|
||||
* description: 订单ID
|
||||
* product_id:
|
||||
* type: integer
|
||||
* description: 商品ID
|
||||
* quantity:
|
||||
* type: integer
|
||||
* description: 商品数量
|
||||
* price:
|
||||
* type: number
|
||||
* description: 商品价格
|
||||
* points_price:
|
||||
* type: integer
|
||||
* description: 积分价格
|
||||
* rongdou_price:
|
||||
* type: number
|
||||
* description: 融豆价格
|
||||
* created_at:
|
||||
* type: string
|
||||
* format: date-time
|
||||
* description: 创建时间
|
||||
*
|
||||
* PreOrder:
|
||||
* type: object
|
||||
* properties:
|
||||
* preOrderId:
|
||||
* type: integer
|
||||
* description: 预订单ID
|
||||
* orderNumber:
|
||||
* type: string
|
||||
* description: 订单号
|
||||
* totalAmount:
|
||||
* type: number
|
||||
* description: 总金额
|
||||
* totalPoints:
|
||||
* type: integer
|
||||
* description: 所需积分总数
|
||||
* totalRongdou:
|
||||
* type: number
|
||||
* description: 所需融豆总数
|
||||
* paymentMethods:
|
||||
* type: array
|
||||
* items:
|
||||
* type: string
|
||||
* description: 去重后的支付方式列表
|
||||
*/
|
||||
53
docs/schemas/product.js
Normal file
53
docs/schemas/product.js
Normal file
@@ -0,0 +1,53 @@
|
||||
/**
|
||||
* @swagger
|
||||
* components:
|
||||
* schemas:
|
||||
* Product:
|
||||
* type: object
|
||||
* required:
|
||||
* - name
|
||||
* - points_price
|
||||
* - stock
|
||||
* properties:
|
||||
* id:
|
||||
* type: integer
|
||||
* description: 商品ID
|
||||
* name:
|
||||
* type: string
|
||||
* description: 商品名称
|
||||
* category:
|
||||
* type: string
|
||||
* description: 商品分类
|
||||
* points_price:
|
||||
* type: integer
|
||||
* description: 积分价格
|
||||
* rongdou_price:
|
||||
* type: number
|
||||
* description: 融豆价格
|
||||
* stock:
|
||||
* type: integer
|
||||
* description: 库存数量
|
||||
* image_url:
|
||||
* type: string
|
||||
* description: 商品图片URL
|
||||
* description:
|
||||
* type: string
|
||||
* description: 商品描述
|
||||
* status:
|
||||
* type: string
|
||||
* description: 商品状态
|
||||
* enum: [active, inactive]
|
||||
* payment_methods:
|
||||
* type: array
|
||||
* items:
|
||||
* type: string
|
||||
* description: 支付方式列表
|
||||
* created_at:
|
||||
* type: string
|
||||
* format: date-time
|
||||
* description: 创建时间
|
||||
* updated_at:
|
||||
* type: string
|
||||
* format: date-time
|
||||
* description: 更新时间
|
||||
*/
|
||||
104
docs/schemas/user.js
Normal file
104
docs/schemas/user.js
Normal file
@@ -0,0 +1,104 @@
|
||||
/**
|
||||
* @swagger
|
||||
* components:
|
||||
* schemas:
|
||||
* User:
|
||||
* type: object
|
||||
* required:
|
||||
* - username
|
||||
* - email
|
||||
* properties:
|
||||
* id:
|
||||
* type: integer
|
||||
* description: 用户ID
|
||||
* username:
|
||||
* type: string
|
||||
* description: 用户名
|
||||
* email:
|
||||
* type: string
|
||||
* format: email
|
||||
* description: 邮箱地址
|
||||
* phone:
|
||||
* type: string
|
||||
* description: 手机号码
|
||||
* points:
|
||||
* type: integer
|
||||
* description: 积分余额
|
||||
* rongdou:
|
||||
* type: number
|
||||
* description: 融豆余额
|
||||
* avatar:
|
||||
* type: string
|
||||
* description: 头像URL
|
||||
* status:
|
||||
* type: string
|
||||
* description: 用户状态
|
||||
* enum: [active, inactive, banned]
|
||||
* created_at:
|
||||
* type: string
|
||||
* format: date-time
|
||||
* description: 创建时间
|
||||
* updated_at:
|
||||
* type: string
|
||||
* format: date-time
|
||||
* description: 更新时间
|
||||
*
|
||||
* UserProfile:
|
||||
* type: object
|
||||
* properties:
|
||||
* id:
|
||||
* type: integer
|
||||
* description: 用户ID
|
||||
* username:
|
||||
* type: string
|
||||
* description: 用户名
|
||||
* email:
|
||||
* type: string
|
||||
* description: 邮箱地址
|
||||
* phone:
|
||||
* type: string
|
||||
* description: 手机号码
|
||||
* points:
|
||||
* type: integer
|
||||
* description: 积分余额
|
||||
* rongdou:
|
||||
* type: number
|
||||
* description: 融豆余额
|
||||
* avatar:
|
||||
* type: string
|
||||
* description: 头像URL
|
||||
*
|
||||
* LoginRequest:
|
||||
* type: object
|
||||
* required:
|
||||
* - username
|
||||
* - password
|
||||
* properties:
|
||||
* username:
|
||||
* type: string
|
||||
* description: 用户名或邮箱
|
||||
* password:
|
||||
* type: string
|
||||
* description: 密码
|
||||
*
|
||||
* RegisterRequest:
|
||||
* type: object
|
||||
* required:
|
||||
* - username
|
||||
* - email
|
||||
* - password
|
||||
* properties:
|
||||
* username:
|
||||
* type: string
|
||||
* description: 用户名
|
||||
* email:
|
||||
* type: string
|
||||
* format: email
|
||||
* description: 邮箱地址
|
||||
* password:
|
||||
* type: string
|
||||
* description: 密码
|
||||
* phone:
|
||||
* type: string
|
||||
* description: 手机号码
|
||||
*/
|
||||
Reference in New Issue
Block a user