package com.ruoyi.satisfaction.api;

import java.util.List;
import java.util.Map;

/**
 * 满意度模块<b>对外接口</b>（唯一允许其它模块依赖的入口）。
 * <p>
 * 设计约定：
 * <ul>
 *   <li>只暴露 DTO / 基本类型，<b>不暴露</b>满意度模块内部的实体与 Mapper；</li>
 *   <li>本接口由 {@link SatisfactionFacade} 统一转出，门面<b>永远存在</b>，
 *       即使满意度模块被关闭（{@code sys_config} 参数 {@code satisfaction.enabled=false}）
 *       也不会导致调用方启动失败；</li>
 *   <li>关闭时各方法返回 {@code false} / 空集合 / {@code null}，并打 WARN 日志，
 *       <b>不抛异常</b>，以免影响调用方主流程（如随访导出、登录）。</li>
 * </ul>
 */
public interface SatisfactionApi {

    /**
     * 满意度模块是否已启用
     */
    boolean isEnabled();

    /**
     * 获取满意度问题分类（语音 + 问卷），带缓存。
     * <p>
     * 供登录链路使用（原 {@code IUserExtInfoService.getSatisfactionCategories}）。
     * <p>
     * 返回结构（与迁移前完全一致）：
     * <pre>
     * {
     *   "voiceCategories":        [ {categoryid, categoryName}, ... ],
     *   "questionnaireCategorys": [ {categoryid, categoryName}, ... ]
     * }
     * </pre>
     *
     * @param orgid 机构 id
     * @return 分类结构；模块关闭时返回空 Map
     */
    Map<String, Object> getSatisfactionCategories(String orgid);

    /**
     * 问题详情占比导出包（供随访导出使用）。
     * <p>
     * 对应原 {@code IServiceSubtaskService.statMydQuestionOptionForExport}。
     * <p>
     * 返回 {@link SatisfactionExportBundle}：行列表 + 行类型 + 图表构建器一次给齐，
     * 调用方（随访导出）因此<b>只需 import api 包</b>即可把结果交给
     * {@code ExcelUtil.exportExcelTwoSheetWithChart}，
     * 不需要接触本模块的 {@code domain} / {@code support} 包。
     *
     * @param subtaskIds   本次导出的子任务 id
     * @param questiontext 题目内容（可选，模糊匹配）
     * @return 导出包；模块关闭时返回 {@link SatisfactionExportBundle#empty()}（导出照常完成，只是没有占比 Sheet）
     */
    SatisfactionExportBundle getQuestionOptionRatioExport(List<Long> subtaskIds, String questiontext);

    /**
     * 判断该机构是否存在满意度配置（可选能力，供调用方做前置校验）
     *
     * @param orgid 机构 id
     * @return 有语音或问卷满意度分类时返回 true
     */
    boolean hasSatisfactionCategory(String orgid);

    /**
     * 随访统计页的「满意度指数」：满意度题目总量 / 填报量 / 完成比例。
     * <p>
     * 对应原 {@code IServiceSubtaskService#getSfStatisticsJoy} 内部私有的
     * {@code getSatisfactionIndex}（现已搬入本模块）。
     * <p>
     * ⚠️ 出于"不改行为"的要求，被迁移实现里的原缺陷<b>原样保留</b>：
     * 本方法恒定返回 {@code {mydtmzl: 0, mydtbl: 0, wcbl: 0.0}}。
     * 因此模块关闭时返回同样的全零 Map，调用方得到的显示结果与开启时一致。
     *
     * @param type          "1"=按科室，"2"=按病区
     * @param code          科室/病区编码
     * @param orgid         机构 id
     * @param ivrCategoryid 语音满意度分类 id（可为 null）
     * @param svyCategoryid 问卷满意度分类 id（可为 null）
     * @return {@code mydtmzl}(Integer) / {@code mydtbl}(Integer) / {@code wcbl}(Double)
     */
    Map<String, Object> getSatisfactionIndex(String type, String code, String orgid,
                                            Long ivrCategoryid, Long svyCategoryid);
}