Merge remote-tracking branch 'origin/main'

2025-09-12 13:15:03 +08:00
parent f0f57fec7d bbc7abd69c
commit e340bf3b34
28 changed files with 10237 additions and 1945 deletions
--- a/backend/config/swagger.js
+++ b/backend/config/swagger.js
@@ -0,0 +1,248 @@
+const swaggerJsdoc = require('swagger-jsdoc')
+const swaggerUi = require('swagger-ui-express')
+
+// Swagger 配置选项
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: '活牛采购智能数字化系统 API文档',
+      description: '活牛采购智能数字化系统的后端API接口文档',
+      version: '1.0.0',
+      contact: {
+        name: 'NiuMall Team',
+        email: 'contact@niumall.com'
+      },
+      license: {
+        name: 'MIT',
+        url: 'https://opensource.org/licenses/MIT'
+      }
+    },
+    servers: [
+      {
+        url: 'http://localhost:4330',
+        description: '本地开发环境'
+      }
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT'
+        }
+      },
+      schemas: {
+        // 通用响应格式
+        ApiResponse: {
+          type: 'object',
+          properties: {
+            success: {
+              type: 'boolean',
+              description: '请求是否成功'
+            },
+            message: {
+              type: 'string',
+              description: '返回消息'
+            },
+            data: {
+              type: 'object',
+              description: '返回数据',
+              nullable: true
+            }
+          }
+        },
+        // 分页数据格式
+        PagedResponse: {
+          type: 'object',
+          properties: {
+            items: {
+              type: 'array',
+              items: {
+                type: 'object'
+              },
+              description: '数据列表'
+            },
+            total: {
+              type: 'integer',
+              description: '总条数'
+            },
+            page: {
+              type: 'integer',
+              description: '当前页码'
+            },
+            pageSize: {
+              type: 'integer',
+              description: '每页条数'
+            },
+            totalPages: {
+              type: 'integer',
+              description: '总页数'
+            }
+          }
+        },
+        // 订单相关模型
+        Order: {
+          type: 'object',
+          properties: {
+            id: {
+              type: 'integer',
+              description: '订单ID'
+            },
+            orderNo: {
+              type: 'string',
+              description: '订单编号'
+            },
+            buyerId: {
+              type: 'integer',
+              description: '买方ID'
+            },
+            buyerName: {
+              type: 'string',
+              description: '买方名称'
+            },
+            supplierId: {
+              type: 'integer',
+              description: '供应商ID'
+            },
+            supplierName: {
+              type: 'string',
+              description: '供应商名称'
+            },
+            traderId: {
+              type: 'integer',
+              nullable: true,
+              description: '贸易商ID'
+            },
+            traderName: {
+              type: 'string',
+              nullable: true,
+              description: '贸易商名称'
+            },
+            cattleBreed: {
+              type: 'string',
+              description: '牛品种'
+            },
+            cattleCount: {
+              type: 'integer',
+              description: '牛数量'
+            },
+            expectedWeight: {
+              type: 'number',
+              description: '预计重量'
+            },
+            actualWeight: {
+              type: 'number',
+              nullable: true,
+              description: '实际重量'
+            },
+            unitPrice: {
+              type: 'number',
+              description: '单价'
+            },
+            totalAmount: {
+              type: 'number',
+              description: '总金额'
+            },
+            paidAmount: {
+              type: 'number',
+              description: '已支付金额'
+            },
+            remainingAmount: {
+              type: 'number',
+              description: '剩余金额'
+            },
+            status: {
+              type: 'string',
+              enum: ['pending', 'confirmed', 'preparing', 'shipping', 'delivered', 'accepted', 'completed', 'cancelled', 'refunded'],
+              description: '订单状态'
+            },
+            deliveryAddress: {
+              type: 'string',
+              description: '送货地址'
+            },
+            expectedDeliveryDate: {
+              type: 'string',
+              format: 'date',
+              description: '预计送达日期'
+            },
+            actualDeliveryDate: {
+              type: 'string',
+              format: 'date',
+              nullable: true,
+              description: '实际送达日期'
+            },
+            notes: {
+              type: 'string',
+              nullable: true,
+              description: '备注'
+            },
+            createdAt: {
+              type: 'string',
+              format: 'date-time',
+              description: '创建时间'
+            },
+            updatedAt: {
+              type: 'string',
+              format: 'date-time',
+              description: '更新时间'
+            }
+          }
+        },
+        // 用户相关模型
+        User: {
+          type: 'object',
+          properties: {
+            id: {
+              type: 'integer',
+              description: '用户ID'
+            },
+            username: {
+              type: 'string',
+              description: '用户名'
+            },
+            email: {
+              type: 'string',
+              format: 'email',
+              description: '邮箱'
+            },
+            phone: {
+              type: 'string',
+              description: '手机号'
+            },
+            user_type: {
+              type: 'string',
+              enum: ['admin', 'buyer', 'supplier', 'trader'],
+              description: '用户类型'
+            },
+            status: {
+              type: 'string',
+              enum: ['active', 'inactive', 'suspended'],
+              description: '用户状态'
+            },
+            createdAt: {
+              type: 'string',
+              format: 'date-time',
+              description: '创建时间'
+            },
+            updatedAt: {
+              type: 'string',
+              format: 'date-time',
+              description: '更新时间'
+            }
+          }
+        }
+      }
+    }
+  },
+  // 指定API文档的路径
+  apis: ['../routes/*.js']
+}
+
+// 初始化Swagger-jsdoc
+const specs = swaggerJsdoc(options)
+
+module.exports = {
+  specs,
+  swaggerUi
+}