fastadmin_tailored/ORDER_STATISTICS_README.md

订单统计功能使用说明

功能概述

该功能为验货端用户提供订单统计服务，支持按日、月、年维度统计订单数据，包括验收订单、退回订单和售后订单的统计。

接口列表

1. 订单统计接口

接口地址： /api/inspection/order/statistics

请求方式： GET

参数说明：

• type: 统计类型，可选值：day（按日）、month（按月）、year（按年）
• date: 统计日期，格式：YYYY-MM-DD

响应示例：

{
    "code": 1,
    "msg": "统计数据获取成功",
    "data": {
        "date": "07-14",
        "type": "day",
        "current_period": {
            "inspection_count": 158,
            "return_count": 12,
            "aftersale_count": 2
        },
        "previous_period": {
            "inspection_count": 145,
            "return_count": 10,
            "aftersale_count": 3
        },
        "growth_rate": {
            "inspection_rate": 8.97,
            "return_rate": 20.00,
            "aftersale_rate": -33.33
        },
        "statistics": {
            "inspection_count": 158,
            "return_count": 12,
            "aftersale_count": 2
        }
    }
}

2. 日期范围接口

接口地址： /api/inspection/order/getStatisticsDateRange

请求方式： GET

响应示例：

{
    "code": 1,
    "msg": "日期范围获取成功",
    "data": {
        "earliest_date": "2024-01-01",
        "latest_date": "2025-01-14",
        "current_date": "2025-01-14",
        "current_month": "2025-01",
        "current_year": "2025"
    }
}

3. 趋势数据接口

接口地址： /api/inspection/order/getTrendData

请求方式： GET

参数说明：

• type: 统计类型（目前支持day）
• days: 统计天数，默认7天，范围1-365

响应示例：

{
    "code": 1,
    "msg": "趋势数据获取成功",
    "data": [
        {
            "date": "2025-01-08",
            "display_date": "01-08",
            "inspection_count": 120,
            "return_count": 8,
            "aftersale_count": 1
        },
        {
            "date": "2025-01-09",
            "display_date": "01-09",
            "inspection_count": 135,
            "return_count": 10,
            "aftersale_count": 2
        }
    ]
}

统计类型说明

订单状态映射

• 验收订单：ORDER_STATUS = 211（验货通过）
• 退回订单：ORDER_STATUS = 212（验货不通过）
• 售后订单：ORDER_STATUS IN (202, 203)（退款、退款确认）

时间维度

• day：按日统计，显示格式：MM-DD
• month：按月统计，显示格式：YYYY-MM
• year：按年统计，显示格式：YYYY年

使用示例

获取今日订单统计

// 获取今日统计数据
fetch('/api/inspection/order/statistics?type=day&date=2025-01-14')
    .then(response => response.json())
    .then(data => {
        console.log('今日验收订单：', data.data.statistics.inspection_count);
        console.log('今日退回订单：', data.data.statistics.return_count);
        console.log('今日售后订单：', data.data.statistics.aftersale_count);
    });

获取本月统计数据

// 获取本月统计数据
fetch('/api/inspection/order/statistics?type=month&date=2025-01-14')
    .then(response => response.json())
    .then(data => {
        console.log('本月统计：', data.data.statistics);
        console.log('环比增长：', data.data.growth_rate);
    });

获取最近7天趋势

// 获取最近7天趋势数据
fetch('/api/inspection/order/getTrendData?type=day&days=7')
    .then(response => response.json())
    .then(data => {
        data.data.forEach(item => {
            console.log(`${item.display_date}: 验收${item.inspection_count}，退回${item.return_count}，售后${item.aftersale_count}`);
        });
    });

注意事项

1. 所有接口都需要用户登录认证
2. 统计数据基于当前登录用户的订单数据
3. 日期参数格式必须为 YYYY-MM-DD
4. 趋势数据最多支持查询365天
5. 增长率计算：当上期数据为0时，增长率为100%或0%
6. 所有时间均基于服务器时区

错误处理

常见错误码：

• 400: 参数验证失败
• 401: 未登录或登录已过期
• 403: 权限不足
• 500: 服务器内部错误

错误响应示例：

{
    "code": 0,
    "msg": "统计类型只能是day、month、year",
    "data": null
}