init：代码初始化
This commit is contained in:
bai
532
src/routes/api.js
Normal file
532
src/routes/api.js
Normal file
@@ -0,0 +1,532 @@
|
||||
const express = require('express');
|
||||
const PriceController = require('../controllers/priceController');
|
||||
const { validatePriceQuery, validateSearch, validateStats } = require('../middlewares/validator');
|
||||
|
||||
const router = express.Router();
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/health:
|
||||
* get:
|
||||
* tags:
|
||||
* - Health
|
||||
* summary: 健康检查
|
||||
* description: 检查服务是否正常运行
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 服务正常
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* example: true
|
||||
* message:
|
||||
* type: string
|
||||
* example: Steel Prices Service is running
|
||||
* timestamp:
|
||||
* type: string
|
||||
* format: date-time
|
||||
*/
|
||||
router.get('/health', (req, res) => {
|
||||
res.json({
|
||||
success: true,
|
||||
message: 'Steel Prices Service is running',
|
||||
timestamp: new Date().toISOString()
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/prices/region:
|
||||
* get:
|
||||
* tags:
|
||||
* - Prices
|
||||
* summary: 按地区查询价格
|
||||
* description: 根据地区和日期查询钢材价格数据，支持按日期筛选或查询该地区所有价格数据
|
||||
* parameters:
|
||||
* - $ref: '#/components/parameters/RegionParam'
|
||||
* - $ref: '#/components/parameters/DateParam'
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 查询成功
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* allOf:
|
||||
* - $ref: '#/components/schemas/SuccessResponse'
|
||||
* - type: object
|
||||
* properties:
|
||||
* data:
|
||||
* type: array
|
||||
* items:
|
||||
* $ref: '#/components/schemas/Price'
|
||||
* total:
|
||||
* type: integer
|
||||
* description: 返回的记录数量
|
||||
* example: 50
|
||||
* 400:
|
||||
* description: 参数错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* 500:
|
||||
* description: 服务器错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* examples:
|
||||
* query_by_region_and_date:
|
||||
* summary: 查询昆明地区 2026-01-05 的价格
|
||||
* value:
|
||||
* region: 昆明
|
||||
* date: 2026-01-05
|
||||
* query_by_region_only:
|
||||
* summary: 查询昆明地区所有价格数据
|
||||
* value:
|
||||
* region: 昆明
|
||||
*/
|
||||
router.get('/prices/region', validatePriceQuery, PriceController.getByRegion);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/prices/search:
|
||||
* get:
|
||||
* tags:
|
||||
* - Prices
|
||||
* summary: 搜索价格数据
|
||||
* description: |
|
||||
* 根据多个条件组合搜索钢材价格数据，支持分页返回结果。
|
||||
|
||||
* **搜索条件：**
|
||||
* - material: 材质（支持模糊搜索）
|
||||
* - specification: 规格型号（支持模糊搜索）
|
||||
* - startDate: 开始日期
|
||||
* - endDate: 结束日期
|
||||
* - region: 地区
|
||||
*
|
||||
* **分页参数：**
|
||||
* - page: 页码（默认 1）
|
||||
* - pageSize: 每页数量（默认 20，最大 1000）
|
||||
* parameters:
|
||||
* - name: material
|
||||
* in: query
|
||||
* description: 材质（支持模糊搜索，如：HPB300、HRB400、HRB500E）
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* example: HPB300
|
||||
* - name: specification
|
||||
* in: query
|
||||
* description: 规格型号（支持模糊搜索，如：Φ8、Φ16、HRB400）
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* example: Φ8
|
||||
* - name: startDate
|
||||
* in: query
|
||||
* description: 开始日期（格式：YYYY-MM-DD）
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* format: date
|
||||
* example: 2026-01-01
|
||||
* - name: endDate
|
||||
* in: query
|
||||
* description: 结束日期（格式：YYYY-MM-DD）
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* format: date
|
||||
* example: 2026-01-05
|
||||
* - name: region
|
||||
* in: query
|
||||
* description: 地区
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* example: 昆明
|
||||
* - $ref: '#/components/parameters/PageParam'
|
||||
* - $ref: '#/components/parameters/PageSizeParam'
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 搜索成功
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* allOf:
|
||||
* - $ref: '#/components/schemas/SuccessResponse'
|
||||
* - type: object
|
||||
* properties:
|
||||
* data:
|
||||
* type: array
|
||||
* items:
|
||||
* $ref: '#/components/schemas/Price'
|
||||
* pagination:
|
||||
* $ref: '#/components/schemas/Pagination'
|
||||
* 400:
|
||||
* description: 参数错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* 500:
|
||||
* description: 服务器错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* examples:
|
||||
* search_by_material:
|
||||
* summary: 按材质搜索
|
||||
* value:
|
||||
* material: HPB300
|
||||
* page: 1
|
||||
* pageSize: 20
|
||||
* search_by_date_range:
|
||||
* summary: 按日期范围搜索
|
||||
* value:
|
||||
* material: HRB400
|
||||
* startDate: 2026-01-01
|
||||
* endDate: 2026-01-05
|
||||
* page: 1
|
||||
* pageSize: 50
|
||||
*/
|
||||
router.get('/prices/search', validateSearch, PriceController.search);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/prices/stats:
|
||||
* get:
|
||||
* tags:
|
||||
* - Prices
|
||||
* summary: 获取价格统计
|
||||
* description: |
|
||||
* 获取钢材价格的统计数据，包括平均值、最大值、最小值、标准差等。
|
||||
*
|
||||
* **筛选条件：**
|
||||
* - region: 指定地区
|
||||
* - material: 指定材质
|
||||
* - days: 统计最近 N 天的数据
|
||||
* - startDate/endDate: 指定日期范围
|
||||
*
|
||||
* **统计指标：**
|
||||
* - count: 记录数量
|
||||
* - avgPrice: 平均价格
|
||||
* - minPrice: 最低价格
|
||||
* - maxPrice: 最高价格
|
||||
* - stdDev: 标准差
|
||||
* - trend: 价格趋势（up/down/stable）
|
||||
* - changeRate: 变化率（相对于上一周期）
|
||||
* parameters:
|
||||
* - name: region
|
||||
* in: query
|
||||
* description: 地区（可选）
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* example: 昆明
|
||||
* - name: material
|
||||
* in: query
|
||||
* description: 材质（可选，支持模糊搜索）
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* example: HPB300
|
||||
* - $ref: '#/components/parameters/DaysParam'
|
||||
* - name: startDate
|
||||
* in: query
|
||||
* description: 开始日期（格式：YYYY-MM-DD）
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* format: date
|
||||
* example: 2026-01-01
|
||||
* - name: endDate
|
||||
* in: query
|
||||
* description: 结束日期（格式：YYYY-MM-DD）
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* format: date
|
||||
* example: 2026-01-05
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 统计成功
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* allOf:
|
||||
* - $ref: '#/components/schemas/SuccessResponse'
|
||||
* - type: object
|
||||
* properties:
|
||||
* data:
|
||||
* $ref: '#/components/schemas/PriceStats'
|
||||
* 400:
|
||||
* description: 参数错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* 500:
|
||||
* description: 服务器错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* examples:
|
||||
* stats_by_region_and_days:
|
||||
* summary: 统计昆明地区最近 30 天的 HPB300 价格
|
||||
* value:
|
||||
* region: 昆明
|
||||
* material: HPB300
|
||||
* days: 30
|
||||
* stats_by_date_range:
|
||||
* summary: 统计指定日期范围内的价格
|
||||
* value:
|
||||
* startDate: 2026-01-01
|
||||
* endDate: 2026-01-05
|
||||
*/
|
||||
router.get('/prices/stats', validateStats, PriceController.getStats);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/prices/trend:
|
||||
* get:
|
||||
* tags:
|
||||
* - Prices
|
||||
* summary: 获取价格趋势
|
||||
* description: |
|
||||
* 获取钢材价格的时间序列趋势数据，按日期分组统计。
|
||||
*
|
||||
* **筛选条件：**
|
||||
* - region: 指定地区
|
||||
* - material: 指定材质
|
||||
* - days: 统计最近 N 天的数据
|
||||
*
|
||||
* **返回数据：**
|
||||
* - date: 日期
|
||||
* - avgPrice: 当日平均价格
|
||||
* - minPrice: 当日最低价格
|
||||
* - maxPrice: 当日最高价格
|
||||
*
|
||||
* **适用场景：**
|
||||
* - 绘制价格走势图
|
||||
* - 分析价格波动规律
|
||||
* - 预测价格趋势
|
||||
* parameters:
|
||||
* - name: region
|
||||
* in: query
|
||||
* description: 地区（可选）
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* example: 昆明
|
||||
* - name: material
|
||||
* in: query
|
||||
* description: 材质（可选，支持模糊搜索）
|
||||
* required: false
|
||||
* schema:
|
||||
* type: string
|
||||
* example: HPB300
|
||||
* - $ref: '#/components/parameters/DaysParam'
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 查询成功
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* allOf:
|
||||
* - $ref: '#/components/schemas/SuccessResponse'
|
||||
* - type: object
|
||||
* properties:
|
||||
* data:
|
||||
* type: array
|
||||
* items:
|
||||
* $ref: '#/components/schemas/TrendData'
|
||||
* 400:
|
||||
* description: 参数错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* 500:
|
||||
* description: 服务器错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* examples:
|
||||
* trend_by_region:
|
||||
* summary: 获取昆明地区最近 30 天的价格趋势
|
||||
* value:
|
||||
* region: 昆明
|
||||
* days: 30
|
||||
* trend_by_material:
|
||||
* summary: 获取 HPB300 最近 60 天的价格趋势
|
||||
* value:
|
||||
* material: HPB300
|
||||
* days: 60
|
||||
*/
|
||||
router.get('/prices/trend', validateStats, PriceController.getTrend);
|
||||
|
||||
/**
|
||||
* @swagger
|
||||
* /api/prices/import:
|
||||
* post:
|
||||
* tags:
|
||||
* - Data
|
||||
* summary: 导入价格数据
|
||||
* description: |
|
||||
* 批量导入钢材价格数据到数据库。
|
||||
*
|
||||
* **请求体格式：**
|
||||
* ```json
|
||||
* {
|
||||
* "prices": [
|
||||
* {
|
||||
* "region": "昆明",
|
||||
* "city": "昆明",
|
||||
* "material": "HPB300",
|
||||
* "specification": "Φ8",
|
||||
* "price": 3840.00,
|
||||
* "unit": "元/吨",
|
||||
* "date": "2026-01-05",
|
||||
* "source": "云南钢协",
|
||||
* "warehouse": "玉昆"
|
||||
* }
|
||||
* ]
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* **注意事项：**
|
||||
* - 必填字段：region, material, price, date
|
||||
* - price 必须为数字类型
|
||||
* - date 格式必须为 YYYY-MM-DD
|
||||
* - 重复数据会自动更新
|
||||
* requestBody:
|
||||
* required: true
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* required:
|
||||
* - prices
|
||||
* properties:
|
||||
* prices:
|
||||
* type: array
|
||||
* description: 价格数据数组
|
||||
* items:
|
||||
* type: object
|
||||
* required:
|
||||
* - region
|
||||
* - material
|
||||
* - price
|
||||
* - date
|
||||
* properties:
|
||||
* region:
|
||||
* type: string
|
||||
* description: 地区
|
||||
* example: 昆明
|
||||
* city:
|
||||
* type: string
|
||||
* description: 城市
|
||||
* example: 昆明
|
||||
* material:
|
||||
* type: string
|
||||
* description: 材质
|
||||
* example: HPB300
|
||||
* specification:
|
||||
* type: string
|
||||
* description: 规格型号
|
||||
* example: Φ8
|
||||
* price:
|
||||
* type: number
|
||||
* format: decimal
|
||||
* description: 价格
|
||||
* example: 3840.00
|
||||
* unit:
|
||||
* type: string
|
||||
* description: 单位
|
||||
* example: 元/吨
|
||||
* date:
|
||||
* type: string
|
||||
* format: date
|
||||
* description: 日期
|
||||
* example: 2026-01-05
|
||||
* source:
|
||||
* type: string
|
||||
* description: 数据来源
|
||||
* example: 云南钢协
|
||||
* warehouse:
|
||||
* type: string
|
||||
* description: 仓库/厂家
|
||||
* example: 玉昆
|
||||
* examples:
|
||||
* single_record:
|
||||
* summary: 单条记录
|
||||
* value:
|
||||
* prices:
|
||||
* - region: 昆明
|
||||
* city: 昆明
|
||||
* material: HPB300
|
||||
* specification: Φ8
|
||||
* price: 3840
|
||||
* unit: 元/吨
|
||||
* date: 2026-01-05
|
||||
* source: 云南钢协
|
||||
* warehouse: 玉昆
|
||||
* multiple_records:
|
||||
* summary: 多条记录
|
||||
* value:
|
||||
* prices:
|
||||
* - region: 昆明
|
||||
* material: HPB300
|
||||
* price: 3840
|
||||
* date: 2026-01-05
|
||||
* source: 云南钢协
|
||||
* - region: 玉溪
|
||||
* material: HRB400
|
||||
* price: 3750
|
||||
* date: 2026-01-05
|
||||
* source: 德钢指导价
|
||||
* responses:
|
||||
* 200:
|
||||
* description: 导入成功
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* allOf:
|
||||
* - $ref: '#/components/schemas/SuccessResponse'
|
||||
* - type: object
|
||||
* properties:
|
||||
* message:
|
||||
* type: string
|
||||
* example: 成功导入 100 条数据
|
||||
* data:
|
||||
* type: object
|
||||
* properties:
|
||||
* imported:
|
||||
* type: integer
|
||||
* description: 实际导入的记录数
|
||||
* example: 100
|
||||
* 400:
|
||||
* description: 参数错误或数据格式错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* 500:
|
||||
* description: 服务器错误
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
*/
|
||||
router.post('/prices/import', PriceController.importData);
|
||||
|
||||
module.exports = router;
|
||||
Reference in New Issue
Block a user