package cn.iocoder.yudao.module.qcreport.controller.admin.aiimport.vo;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

import java.util.List;

/**
 * 组件积木清单的一项：前端注册表的**派生视图**，喂给大模型当「可用积木」。
 * <p>
 * 由前端从活注册表生成（剥掉 icon / buildContent / validate 这些不可序列化的成员）后随请求上传。
 * <b>后端刻意不硬编码这份清单</b>：注册表在前端是唯一真相来源，后端抄一份就是第二个真相来源，
 * 前端加了组件、改了必填字段时后端副本会静默过期，大模型随即会编出注册表里根本不存在的 type。
 * <p>
 * 积木清单只用于拼 prompt。后端**不据此做任何渲染或合法性推断**——
 * 真正把关的是前端装配器查询活注册表；未注册的 type 在那里会被直接跳过，产不出任意 HTML。
 */
@Schema(description = "管理后台 - 智能质检报告 AI 积木清单项")
@Data
public class QcReportComponentSpecVO {

    @Schema(description = "组件类型，如 ReportHeader / QualityTable", requiredMode = Schema.RequiredMode.REQUIRED,
            example = "QualityTable")
    private String type;

    @Schema(description = "组件显示名，供模型理解语义", example = "检验项目表格")
    private String label;

    @Schema(description = "组件分类，如 basic / data / result", example = "data")
    private String category;

    @Schema(description = "选型说明：这个组件用来放什么、不要用来放什么",
            example = "文档最顶部的抬头块：公司名称、报告标题、报告编号")
    private String hint;

    @Schema(description = "该组件允许填写的属性字段；未在此声明的 key 一律会被丢弃")
    private List<Field> fields;

    /**
     * 一个可填属性。只保留模型需要知道的部分，字段类型同样由前端注册表给出。
     */
    @Schema(description = "管理后台 - AI 积木清单的字段项")
    @Data
    public static class Field {

        @Schema(description = "属性 key，如 itemsPath / title", requiredMode = Schema.RequiredMode.REQUIRED,
                example = "itemsPath")
        private String key;

        @Schema(description = "字段显示名", example = "检验项数据源")
        private String label;

        @Schema(description = "字段类型，如 text / number / boolean / enum / dataPath", example = "dataPath")
        private String type;

        @Schema(description = "是否必填；必填未给时后端会在 warnings 里提示")
        private Boolean required;

        @Schema(description = "是否支持数据绑定", example = "true")
        private Boolean bindable;

        @Schema(description = "枚举可选值，仅在 type=enum 时有意义")
        private List<Object> enumOptions;

    }

}