package com.yunhai.acasyllabu.service;

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

/**
 * 用户中心门面服务（对齐 UserBase {@code UserCenterService} 模式）。
 * <p>封装 {@code YschBaseOpenApi} / {@code OpenApiUserClient} 静态门面调用，
 * 把原本散落在 Controller 的组树组装、教师挂组、成员解析等业务逻辑下沉到 Service 层，
 * Controller 只保留"取参 → 调 Service → 返回"的薄壳。</p>
 */
public interface IUserCenterService {

    /**
     * 获取当前用户学校组及用户（树形结构）。
     * <p>组装规则（从原 BaseApiController.getSchoolAll 下沉）：</p>
     * <ol>
     *   <li>userbase 读取当前学校整棵组树（getGroupById(schId, withSub=true)），剔除学生组（type=8）及其子组；</li>
     *   <li>bschclass 获取该校全部教师（/oapi/DbClass/GetSchteaList?Group=schId），按 GroupIds 挂到对应组下，
     *       无有效组（如所属组全被剔除）的教师兜底挂学校根节点；</li>
     *   <li>扁平节点按 pid 递归组装为树（空组剔除，同 C# FormatUserTree）。</li>
     * </ol>
     *
     * @param schId 学校ID（用户当前角色所属学校）
     * @return 用户树形结构（组节点 type=1 / 教师节点 type=2）
     */
    List<Map<String, Object>> getSchoolAllTree(Integer schId);

    /**
     * 获取指定组内用户（教师 + 管理员）。
     * <p>对应前端 base/GetGroupUser。原实现为空桩返回空列表，现按 C# 语义
     * （ITeainfoBLL.GetGroupTeainfo + IAdminfoBLL.GetGroupAdminfo）接入用户中心。
     * 若用户中心不可用或未配置对应开放接口，则抛出带语义的异常（显式报错而非静默失能）。</p>
     *
     * @param gid  组ID
     * @param role 角色（默认 2=教师；1=管理员等）
     * @return 组内用户列表
     */
    List<Map<String, Object>> getGroupUser(Integer gid, Integer role);

    /**
     * 获取当前用户可访问的模块树（左侧菜单）。
     * <p>从基础平台拉取当前用户模块列表（含学校上下文），组装为前端 layout 期望的树结构
     * （{@code modId/page/children}），对应前端 GetUserMod 接口。</p>
     *
     * @param userId 用户ID
     * @param schId  学校ID（可为 null）
     * @return 模块树（顶层 List，含 children 嵌套）
     */
    List<Map<String, Object>> getUserModuleTree(Integer userId, Integer schId);
}