#AI.注释

zhou zhou

10 小时以前 80a6d9236ade191a5de0975abe4de5a6e7e63915

 rsf-server/src/main/java/com/vincent/rsf/server/ai/tool/RsfWmsBaseTools.java

@@ -27,18 +27,25 @@
    private final BasStationService basStationService;
    private final DictDataService dictDataService;

    @Tool(name = "rsf_query_warehouses", description = "按仓库编码或名称查询仓库基础信息。")
    /**
     * 查询仓库基础信息。
     * 该工具面向“按编码/名称定位仓库”的问答场景，不负责提供全量仓库主数据导出能力。
     */
    @Tool(name = "rsf_query_warehouses", description = "只读查询工具。按仓库编码或名称查询仓库基础信息。")
    public List<Map<String, Object>> queryWarehouses(
            @ToolParam(description = "仓库编码，可选") String code,
            @ToolParam(description = "仓库名称，可选") String name,
            @ToolParam(description = "返回条数，默认 10，最大 50") Integer limit) {
        String normalizedCode = BuiltinToolGovernanceSupport.sanitizeQueryText(code, "仓库编码", 64);
        String normalizedName = BuiltinToolGovernanceSupport.sanitizeQueryText(name, "仓库名称", 100);
        BuiltinToolGovernanceSupport.requireAnyFilter("仓库查询至少需要提供仓库编码或名称", normalizedCode, normalizedName);
        LambdaQueryWrapper<Warehouse> queryWrapper = new LambdaQueryWrapper<>();
        int finalLimit = normalizeLimit(limit, 10, 50);
        if (StringUtils.hasText(code)) {
            queryWrapper.like(Warehouse::getCode, code);
        int finalLimit = BuiltinToolGovernanceSupport.normalizeLimit(limit, 10, 50);
        if (StringUtils.hasText(normalizedCode)) {
            queryWrapper.like(Warehouse::getCode, normalizedCode);
        }
        if (StringUtils.hasText(name)) {
            queryWrapper.like(Warehouse::getName, name);
        if (StringUtils.hasText(normalizedName)) {
            queryWrapper.like(Warehouse::getName, normalizedName);
        }
        queryWrapper.orderByAsc(Warehouse::getCode).last("LIMIT " + finalLimit);
        List<Warehouse> warehouses = warehouseService.list(queryWrapper);
@@ -58,22 +65,31 @@
        return result;
    }

    @Tool(name = "rsf_query_bas_stations", description = "按站点编号、站点名称或使用状态查询基础站点。")
    /**
     * 查询基础站点信息。
     * 查询条件允许按站点名称、编号或使用状态组合过滤，返回值只保留 AI 对话需要的字段。
     */
    @Tool(name = "rsf_query_bas_stations", description = "只读查询工具。按站点编号、站点名称或使用状态查询基础站点。")
    public List<Map<String, Object>> queryBasStations(
            @ToolParam(description = "站点编号，可选") String stationName,
            @ToolParam(description = "站点名称，可选") String stationId,
            @ToolParam(description = "站点名称，可选") String stationName,
            @ToolParam(description = "站点编号，可选") String stationId,
            @ToolParam(description = "使用状态，可选") String useStatus,
            @ToolParam(description = "返回条数，默认 10，最大 50") Integer limit) {
        String normalizedStationName = BuiltinToolGovernanceSupport.sanitizeQueryText(stationName, "站点名称", 100);
        String normalizedStationId = BuiltinToolGovernanceSupport.sanitizeQueryText(stationId, "站点编号", 64);
        String normalizedUseStatus = BuiltinToolGovernanceSupport.sanitizeQueryText(useStatus, "使用状态", 32);
        BuiltinToolGovernanceSupport.requireAnyFilter("基础站点查询至少需要提供站点名称、站点编号或使用状态",
                normalizedStationName, normalizedStationId, normalizedUseStatus);
        LambdaQueryWrapper<BasStation> queryWrapper = new LambdaQueryWrapper<>();
        int finalLimit = normalizeLimit(limit, 10, 50);
        if (StringUtils.hasText(stationName)) {
            queryWrapper.like(BasStation::getStationName, stationName);
        int finalLimit = BuiltinToolGovernanceSupport.normalizeLimit(limit, 10, 50);
        if (StringUtils.hasText(normalizedStationName)) {
            queryWrapper.like(BasStation::getStationName, normalizedStationName);
        }
        if (StringUtils.hasText(stationId)) {
            queryWrapper.like(BasStation::getStationId, stationId);
        if (StringUtils.hasText(normalizedStationId)) {
            queryWrapper.like(BasStation::getStationId, normalizedStationId);
        }
        if (StringUtils.hasText(useStatus)) {
            queryWrapper.eq(BasStation::getUseStatus, useStatus);
        if (StringUtils.hasText(normalizedUseStatus)) {
            queryWrapper.eq(BasStation::getUseStatus, normalizedUseStatus);
        }
        queryWrapper.orderByAsc(BasStation::getStationName).last("LIMIT " + finalLimit);
        List<BasStation> stations = basStationService.list(queryWrapper);
@@ -98,23 +114,30 @@
        return result;
    }

    @Tool(name = "rsf_query_dict_data", description = "根据字典类型编码查询字典数据，可按值或标签进一步过滤。")
    /**
     * 查询字典数据。
     * 字典类型编码是强制条件，用来确保模型不会越过业务边界直接遍历整张字典表。
     */
    @Tool(name = "rsf_query_dict_data", description = "只读查询工具。根据字典类型编码查询字典数据，可按值或标签进一步过滤。")
    public List<Map<String, Object>> queryDictData(
            @ToolParam(required = true, description = "字典类型编码") String dictTypeCode,
            @ToolParam(description = "字典值，可选") String value,
            @ToolParam(description = "字典标签，可选") String label,
            @ToolParam(description = "返回条数，默认 20，最大 100") Integer limit) {
        if (!StringUtils.hasText(dictTypeCode)) {
        String normalizedDictTypeCode = BuiltinToolGovernanceSupport.sanitizeQueryText(dictTypeCode, "字典类型编码", 64);
        String normalizedValue = BuiltinToolGovernanceSupport.sanitizeQueryText(value, "字典值", 64);
        String normalizedLabel = BuiltinToolGovernanceSupport.sanitizeQueryText(label, "字典标签", 100);
        if (!StringUtils.hasText(normalizedDictTypeCode)) {
            throw new CoolException("字典类型编码不能为空");
        }
        int finalLimit = normalizeLimit(limit, 20, 100);
        int finalLimit = BuiltinToolGovernanceSupport.normalizeLimit(limit, 20, 100);
        LambdaQueryWrapper<DictData> queryWrapper = new LambdaQueryWrapper<DictData>()
                .eq(DictData::getDictTypeCode, dictTypeCode);
        if (StringUtils.hasText(value)) {
            queryWrapper.like(DictData::getValue, value);
                .eq(DictData::getDictTypeCode, normalizedDictTypeCode);
        if (StringUtils.hasText(normalizedValue)) {
            queryWrapper.like(DictData::getValue, normalizedValue);
        }
        if (StringUtils.hasText(label)) {
            queryWrapper.like(DictData::getLabel, label);
        if (StringUtils.hasText(normalizedLabel)) {
            queryWrapper.like(DictData::getLabel, normalizedLabel);
        }
        queryWrapper.orderByAsc(DictData::getSort).last("LIMIT " + finalLimit);
        List<DictData> dictDataList = dictDataService.list(queryWrapper);
@@ -135,13 +158,4 @@
        return result;
    }

    private int normalizeLimit(Integer limit, int defaultValue, int maxValue) {
        if (limit == null) {
            return defaultValue;
        }
        if (limit < 1 || limit > maxValue) {
            throw new CoolException("limit 必须在 1 到 " + maxValue + " 之间");
        }
        return limit;
    }
}