package com.ruoyi.common.core.service;
|
|
import java.util.List;
|
|
/**
|
* 「AI 选项匹配」的对外契约。
|
*
|
* <h3>它是什么</h3>
|
* 原 {@code IServiceSubtaskService#matchOptionIndex}（smartor）：
|
* 把「用户问题 + 语音识别结果 + 候选选项」序列化成 JSON，<b>POST 到一个外部 AI 服务</b>，
|
* 把返回的数字解析为命中的选项下标（解析失败或 url 为空返回 {@code -1}）。
|
*
|
* <h3>为什么要下沉成契约</h3>
|
* 模板模块的 {@code IvrLibaTargetServiceImpl} 需要调它，但它是 smartor 的方法。
|
* 模板模块**绝不能依赖 smartor**（smartor 已依赖模板模块 → 会成环，Maven 直接构建失败）。
|
* 所以按既有手法（{@link VisitTaskCreateApi} / {@link ServiceTaskMatchApi} 等）：
|
* 接口放 ruoyi-common，smartor 侧提供过渡实现。
|
*
|
* <h3>⚠️ 入参为什么用<b>泛型</b> {@code List<T>} 而不是模板实体</h3>
|
* 原方法签名是 {@code List<IvrTaskTemplateTargetoption>}，而那个类型已搬进
|
* {@code ruoyi-template}。若契约直接写具体类型，ruoyi-common 就得依赖 ruoyi-template ——
|
* 方向不对。
|
* <p>
|
* 也不能简单写成 {@code List<Object>}：调用方拿到返回值后要
|
* {@code options.get(matched).getOptiondesc()} —— 参数若是 {@code List<Object>}，
|
* {@code get()} 返回 {@code Object}，那行就编译不过。用泛型 {@code <T>} 可以让
|
* 调用点的类型保持原样，而 ruoyi-common 无需知道 {@code T} 是什么。
|
* <p>
|
* 语义上也安全：原方法对 options **只做一件事 —— {@code jsonObject.put("options", options)}**
|
* 然后整体序列化，从不读它的字段，所以 {@code T} 具体是什么都不影响结果。
|
*
|
* <h3>实现方必须保持的行为</h3>
|
* <ul>
|
* <li>{@code url} 为空 → 不发请求，返回 {@code -1}；</li>
|
* <li>请求抛异常 → 打日志后返回 {@code -1}（<b>吞异常</b>，原实现如此）；</li>
|
* <li>响应非纯整数（允许前导负号）→ 返回 {@code -1}。</li>
|
* </ul>
|
*/
|
public interface SubtaskOptionMatchApi {
|
|
/**
|
* 调外部 AI 服务做选项匹配。
|
*
|
* @param url AI 服务地址（原 {@code ivrTaskTemplate.url}）；为空则直接返回 -1
|
* @param questionText 用户问题
|
* @param voiceText 语音识别结果
|
* @param options 候选选项（原为 {@code List<IvrTaskTemplateTargetoption>}）；
|
* 仅用于 JSON 序列化，故用泛型承载
|
* @param uuid 本次会话 uuid
|
* @param <T> 选项元素类型（调用方决定，实现方不需要知道）
|
* @return 命中的下标；无法匹配返回 {@code -1}
|
*/
|
<T> Integer matchOptionIndex(String url, String questionText, String voiceText,
|
List<T> options, String uuid);
|
}
|
