package com.nanri.aiimage.config;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("AI Image Backend API")
                        .description("""
                                数富 AI Java 后端接口文档，包含文件处理、任务调度、店铺匹配、紫鸟接入和管理后台接口。

                                任务型模块通常按以下链路联调：
                                1. 前端或 Python 桌面端调用 /api/files/upload 上传源文件；
                                2. 调用模块的解析或创建任务接口，由 Java 解析数据并持久化任务；
                                3. 前端激活任务并派发给 Python，Python 按分页接口拉取任务明细；
                                4. 执行期间调用 /api/tasks/{taskId}/heartbeat 上报心跳和处理进度；
                                5. Python 将处理结果回传模块接口，Java 异步生成 XLSX/ZIP 并上传 OSS；
                                6. 任务详情或历史接口返回公开 OSS 下载直链。

                                跨语言请求中的 user_id、task_ids 等字段使用 snake_case；响应字段默认使用 camelCase。

                                上架模块的 Python 分页、结果回传和任务级进度接口优先使用 taskId/fileId 定位，user_id 仅作为可选的旧客户端归属校验；创建批次、总览和历史接口仍按用户维度调用。

                                本地启动说明：
                                - 默认配置读取 application.yml；
                                - 建议复制 application-local.example.yml 为本地配置，并在 IDE 中通过环境变量覆盖数据库与 OSS 参数；
                                - Knife4j 地址：/doc.html
                                """)
                        .version("v0.0.1")
                        .contact(new Contact().name("Nanri AI"))
                        .license(new License().name("Internal Use")))
                .externalDocs(new ExternalDocumentation()
                        .description("Knife4j 文档")
                        .url("/doc.html"));
    }

}