datahub/backend/app/OpenApiSpec.php

<?php

declare(strict_types=1);

namespace App;

use OpenApi\Attributes as OA;

#[OA\Info(
    version: '1.0.0',
    title: 'Datahub API',
    description: 'Datahub API documentation'
)]
#[OA\Server(url: '/api/v1', description: 'API v1')]
#[OA\SecurityScheme(
    securityScheme: 'bearerAuth',
    type: 'http',
    scheme: 'bearer',
    bearerFormat: 'JWT'
)]
#[OA\SecurityScheme(
    securityScheme: 'apiKeyAuth',
    type: 'apiKey',
    in: 'header',
    name: 'X-API-Key'
)]
#[OA\Schema(
    schema: 'ApiResponse',
    type: 'object',
    properties: [
        new OA\Property(property: 'code', type: 'integer', example: 0),
        new OA\Property(property: 'message', type: 'string', example: 'success'),
        new OA\Property(property: 'data', type: 'object', nullable: true),
    ]
)]
#[OA\Schema(
    schema: 'PaginatedData',
    type: 'object',
    properties: [
        new OA\Property(property: 'items', type: 'array', items: new OA\Items()),
        new OA\Property(property: 'total', type: 'integer', example: 0),
        new OA\Property(property: 'page', type: 'integer', example: 1),
        new OA\Property(property: 'per_page', type: 'integer', example: 15),
    ]
)]
#[OA\Schema(
    schema: 'ErrorResponse',
    type: 'object',
    properties: [
        new OA\Property(property: 'code', type: 'integer', example: 400),
        new OA\Property(property: 'message', type: 'string', example: 'Bad request'),
        new OA\Property(property: 'data', type: 'object', nullable: true),
    ]
)]
#[OA\Schema(
    schema: 'MqQueueInfo',
    type: 'object',
    description: '单个队列的状态信息',
    properties: [
        new OA\Property(property: 'queue', type: 'string', example: 'orders.queue', description: '队列名称'),
        new OA\Property(property: 'messages', description: '消息数量（异常时为 N/A）', oneOf: [new OA\Schema(type: 'integer'), new OA\Schema(type: 'string')], example: 5),
        new OA\Property(property: 'consumers', description: '消费者数量（异常时为 N/A）', oneOf: [new OA\Schema(type: 'integer'), new OA\Schema(type: 'string')], example: 1),
        new OA\Property(property: 'status', type: 'string', enum: ['high_load', 'processing', 'active', 'empty', 'error'], example: 'active', description: '队列状态'),
    ]
)]
#[OA\Schema(
    schema: 'MqQueueStatus',
    type: 'object',
    description: '消息队列全量状态',
    properties: [
        new OA\Property(property: 'business_queues', type: 'array', items: new OA\Items(ref: '#/components/schemas/MqQueueInfo'), description: '业务队列列表'),
        new OA\Property(property: 'retry_queues', type: 'array', items: new OA\Items(ref: '#/components/schemas/MqQueueInfo'), description: '重试队列列表'),
        new OA\Property(property: 'error_queue', ref: '#/components/schemas/MqQueueInfo', description: '错误队列（筛选时为空数组）'),
        new OA\Property(property: 'summary', properties: [
            new OA\Property(property: 'total_messages', type: 'integer', example: 7, description: '消息总数'),
            new OA\Property(property: 'total_consumers', type: 'integer', example: 1, description: '消费者总数'),
        ], type: 'object', description: '汇总统计'),
        new OA\Property(property: 'fetched_at', type: 'string', format: 'date-time', example: '2026-03-13 12:00:00', description: '数据获取时间'),
    ]
)]
#[OA\Schema(
    schema: 'FailedMessageList',
    type: 'object',
    description: '失败消息列表项',
    properties: [
        new OA\Property(property: 'id', type: 'integer', example: 1),
        new OA\Property(property: 'error_id', type: 'string', example: 'err_67890abc'),
        new OA\Property(property: 'data_type', type: 'string', enum: ['order', 'product', 'refund'], example: 'order'),
        new OA\Property(property: 'platform', type: 'string', example: 'Tmall', nullable: true),
        new OA\Property(property: 'platform_id', type: 'integer', example: 1, nullable: true),
        new OA\Property(property: 'company_id', type: 'integer', example: 1, nullable: true),
        new OA\Property(property: 'store_id', type: 'integer', example: 1, nullable: true),
        new OA\Property(property: 'error_type', type: 'string', example: 'RuntimeException'),
        new OA\Property(property: 'error_message', type: 'string', example: 'Connection refused'),
        new OA\Property(property: 'retry_count', type: 'integer', example: 3),
        new OA\Property(property: 'message_id', type: 'string', example: 'msg_12345', nullable: true),
        new OA\Property(property: 'failed_at', type: 'string', format: 'date-time'),
        new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
    ]
)]
#[OA\Schema(
    schema: 'FailedMessageDetail',
    type: 'object',
    description: '失败消息详情（含完整错误堆栈和原始消息体）',
    properties: [
        new OA\Property(property: 'id', type: 'integer', example: 1),
        new OA\Property(property: 'error_id', type: 'string', example: 'err_67890abc'),
        new OA\Property(property: 'data_type', type: 'string', enum: ['order', 'product', 'refund'], example: 'order'),
        new OA\Property(property: 'platform', type: 'string', example: 'Tmall', nullable: true),
        new OA\Property(property: 'platform_id', type: 'integer', example: 1, nullable: true),
        new OA\Property(property: 'company_id', type: 'integer', example: 1, nullable: true),
        new OA\Property(property: 'store_id', type: 'integer', example: 1, nullable: true),
        new OA\Property(property: 'error_type', type: 'string', example: 'RuntimeException'),
        new OA\Property(property: 'error_message', type: 'string', example: 'Connection refused'),
        new OA\Property(property: 'error_code', type: 'integer', example: 0),
        new OA\Property(property: 'error_trace', type: 'string', description: '完整异常堆栈'),
        new OA\Property(property: 'original_message', type: 'object', description: '原始消息体 JSON'),
        new OA\Property(property: 'retry_count', type: 'integer', example: 3),
        new OA\Property(property: 'message_id', type: 'string', example: 'msg_12345', nullable: true),
        new OA\Property(property: 'failed_at', type: 'string', format: 'date-time'),
        new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
    ]
)]
#[OA\Schema(
    schema: 'DashboardOverview',
    type: 'object',
    description: 'Dashboard 概览统计',
    properties: [
        new OA\Property(property: 'today', properties: [
            new OA\Property(property: 'success', type: 'integer', example: 120),
            new OA\Property(property: 'failed', type: 'integer', example: 3),
        ], type: 'object', description: '今日统计'),
        new OA\Property(property: 'this_week', properties: [
            new OA\Property(property: 'success', type: 'integer', example: 850),
            new OA\Property(property: 'failed', type: 'integer', example: 15),
        ], type: 'object', description: '本周统计'),
        new OA\Property(property: 'this_month', properties: [
            new OA\Property(property: 'success', type: 'integer', example: 3200),
            new OA\Property(property: 'failed', type: 'integer', example: 42),
        ], type: 'object', description: '本月统计'),
        new OA\Property(property: 'by_type', type: 'array', items: new OA\Items(properties: [
            new OA\Property(property: 'data_type', type: 'string', enum: ['order', 'product', 'refund', 'inventory'], example: 'order'),
            new OA\Property(property: 'success', type: 'integer', example: 1000),
            new OA\Property(property: 'failed', type: 'integer', example: 10),
        ], type: 'object'), description: '按数据类型分组统计（本月窗口）'),
    ]
)]
#[OA\Schema(
    schema: 'DashboardTrendItem',
    type: 'object',
    description: '趋势数据点',
    properties: [
        new OA\Property(property: 'date', type: 'string', format: 'date', example: '2026-03-17'),
        new OA\Property(property: 'success', type: 'integer', example: 120),
        new OA\Property(property: 'failed', type: 'integer', example: 3),
    ]
)]
#[OA\Schema(
    schema: 'DashboardBreakdownItem',
    type: 'object',
    description: '分组统计项',
    properties: [
        new OA\Property(property: 'id', type: 'integer', example: 1, description: '维度 ID（公司/平台/店铺）'),
        new OA\Property(property: 'name', type: 'string', example: 'Tmall', description: '维度名称'),
        new OA\Property(property: 'success', type: 'integer', example: 500),
        new OA\Property(property: 'failed', type: 'integer', example: 8),
    ]
)]
#[OA\Schema(
    schema: 'ApiRequestLogList',
    type: 'object',
    description: 'API 请求日志列表项',
    properties: [
        new OA\Property(property: 'id', type: 'integer', example: 1),
        new OA\Property(property: 'user_id', type: 'integer', example: 1, nullable: true),
        new OA\Property(property: 'method', type: 'string', example: 'GET'),
        new OA\Property(property: 'path', type: 'string', example: '/api/v1/users'),
        new OA\Property(property: 'status_code', type: 'integer', example: 200),
        new OA\Property(property: 'ip', type: 'string', example: '127.0.0.1', nullable: true),
        new OA\Property(property: 'response_code', type: 'integer', example: 0, nullable: true),
        new OA\Property(property: 'duration_ms', type: 'integer', example: 42),
        new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
    ]
)]
#[OA\Schema(
    schema: 'ApiRequestLogDetail',
    type: 'object',
    description: 'API 请求日志详情（含完整请求体和 User-Agent）',
    properties: [
        new OA\Property(property: 'id', type: 'integer', example: 1),
        new OA\Property(property: 'user_id', type: 'integer', example: 1, nullable: true),
        new OA\Property(property: 'method', type: 'string', example: 'POST'),
        new OA\Property(property: 'path', type: 'string', example: '/api/v1/users'),
        new OA\Property(property: 'status_code', type: 'integer', example: 200),
        new OA\Property(property: 'ip', type: 'string', example: '127.0.0.1', nullable: true),
        new OA\Property(property: 'user_agent', type: 'string', example: 'Mozilla/5.0', nullable: true),
        new OA\Property(property: 'request_body', type: 'object', description: '请求体（脱敏后）', nullable: true),
        new OA\Property(property: 'response_code', type: 'integer', example: 0, nullable: true),
        new OA\Property(property: 'duration_ms', type: 'integer', example: 42),
        new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
    ]
)]
#[OA\Schema(
    schema: 'OperationLogList',
    type: 'object',
    description: '操作日志列表项',
    properties: [
        new OA\Property(property: 'id', type: 'integer', example: 1),
        new OA\Property(property: 'user_id', type: 'integer', example: 1),
        new OA\Property(property: 'action', type: 'string', example: 'user.create'),
        new OA\Property(property: 'target_type', type: 'string', example: 'user'),
        new OA\Property(property: 'target_id', type: 'integer', example: 5, nullable: true),
        new OA\Property(property: 'description', type: 'string', example: '创建用户 test_user'),
        new OA\Property(property: 'ip', type: 'string', example: '127.0.0.1', nullable: true),
        new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
    ]
)]
#[OA\Schema(
    schema: 'OperationLogDetail',
    type: 'object',
    description: '操作日志详情（含完整操作详情 JSON）',
    properties: [
        new OA\Property(property: 'id', type: 'integer', example: 1),
        new OA\Property(property: 'user_id', type: 'integer', example: 1),
        new OA\Property(property: 'action', type: 'string', example: 'user.create'),
        new OA\Property(property: 'target_type', type: 'string', example: 'user'),
        new OA\Property(property: 'target_id', type: 'integer', example: 5, nullable: true),
        new OA\Property(property: 'description', type: 'string', example: '创建用户 test_user'),
        new OA\Property(property: 'detail', type: 'object', description: '操作详情 JSON', nullable: true),
        new OA\Property(property: 'ip', type: 'string', example: '127.0.0.1', nullable: true),
        new OA\Property(property: 'created_at', type: 'string', format: 'date-time'),
    ]
)]
class OpenApiSpec
{
}