授权机制全链路架构

授权从「载体 → 内存 → 业务校验 / 缓存 / 前端」是一条完整的单向链路。

common/auth/enums/FeatureEnum.java。每个枚举值 = 一个可独立授权的功能模块。

• featureId < 100 为模块/主授权；100 ≤ featureId ≤ 201 为点位授权档位。
• show=false 的模块（61/53）不出现在授权信息列表（FeatureEnum.isShow() 过滤），但仍参与权限判断。
• 前端判断权限统一用枚举常量名 name（如 "MODULE_ZHIWEN_SERVICE"），而非中文 featureName（文案可能变动）。FeatureEnum.getName() 返回该常量名。

common/auth/enums/BitFeatureEnum.java。授权码密文末尾的「授权组合数字」用二进制位编码各模块：

• getFeatureIdsByAuthNum(authNumber)：把十进制授权数按位拆解，返回 FeatureEnum ID 集合。
• getAllAuthNum()：反向枚举所有组合，用于硬狗初始化（SuperDog.init() 按每个组合调用 DLL Init）。

common/auth/domain/Certification.java。@Data @Builder。

common/auth/domain/DogEncryptionStorage.java。静态类，两个 ConcurrentHashMap：

public static final Map<String, Certification> hardSortCertMap = new ConcurrentHashMap<>(); // 硬件狗
public static final Map<String, Certification> softSortCertMap = new ConcurrentHashMap<>(); // 软授权

• hasAuth(featureId) / hasAuth(FeatureEnum)：是否拥有某模块授权
• hasAuthFeatureIdList()：合并 hard+soft 两个 Map，经 auth() 时间过滤，返回当前有效 featureId 集合
• auth(certification, now)：点位授权（featureId≥100）直接放行不参与时间判定；模块授权校验 begin/endTime 有效期
• authPoint()：计算允许点位数（详见 §5）

系统启动入口：SuperDog.execute()（common/auth/dog/SuperDog.java:141），由 InitializationManager 在 Spring 启动阶段调用，顺序执行三件事：

public void execute(ApplicationArguments args) {
    sysCertificationBiz.refreshSoftCertification();  // 1. 软授权
    init();                                          // 2. 硬狗（try-catch 不阻塞启动）
    TimeTamperDetector.init();                       // 3. 时间防篡改
}

• 平台限制：仅 Windows 加载 SuperDog.dll（JNA），Linux 不加载。
• 初始化（SuperDog.init()）：用 BitFeatureEnum.getAllAuthNum() 枚举所有授权组合，对每个组合调 DLL.Init(featureId, vendor) 拿到 dogID，再 SetInterval(dogID, 20*1000) + SetCallBack(dogID, callback)。
• 轮询周期：20 秒（注释写"5 分钟"但代码是 20*1000）。DLL 内部按此周期轮询硬件狗，仅在状态码变化时回调。
• 回调：CallbackImpl.invoke(featureNum, code, type, datetime)
  1. BitFeatureEnum.getFeatureIdsByAuthNum(featureNum) 按位拆出 featureId 集合
  2. 按 code 分支：code=0/45（成功）→ 按 type（1=永久，2/3=限期）构造 Certification 写入 hardSortCertMap；异常码 → remove 对应 key（拔狗即移除授权）
  3. 末尾发布 ModuleAuthActivatedEvent("hard")
• 要点：硬件狗不经 RSA 解密，狗本身就是授权载体，DLL 直接返回 (code, type, datetime)。

SysCertificationBizImpl.refreshSoftCertification()（modules/system/biz/impl/SysCertificationBizImpl.java:117）：

1. softSortCertMap.clear() 清空
2. 从 DB 读主授权记录（featureId=99 且 type=software_cert）的 cipherText
3. RsaUtil.rsaDecToBean(cipherText) —— RSA 公钥解密（授权工具用私钥加密，后台用公钥解密）
4. 解密明文格式：机器码#cloud#开始时间#结束时间#授权组合数字
5. 解析出主授权 + 各模块/点位，逐条写入 softSortCertMap
6. finally 块发布 ModuleAuthActivatedEvent("soft")

common/auth/time/TimeTamperDetector.java：

• 启动一个名为 "time-check" 的虚拟线程，每 5 秒校验一次系统时间
• 用 AES 加密的时间戳日志文件 log.bin 记录上次时间；若发现时间回退超过 1 小时 → 判定篡改 → timeCheckEnabled.set(false)
• 每个请求由 WatchDogInterceptor 先查 isTimeCheckEnabled()，被判定篡改后所有请求被拦截（抛 code 452）

授权状态写入 DogEncryptionStorage 后，通过以下四层作用于业务运行时：

两个拦截器的 isHasAuth() 逻辑一致：endTime="infinite" 或 now<endTime 有效；过期会把软授权 DB 记录置为 EXPIRED；status="no" 强制无效。

注册位置：AuthInterceptorConfig.addInterceptors()。排除路径含登录、swagger、/system/certification/**、/energy/calc/**、apk 下载等（getExcludePatterns()）。

注解 @ModuleAuth(FeatureEnum.XXX) + 切面 CheckModuleAuth：

@Around("@annotation(moduleAuth)")
public Object around(ProceedingJoinPoint joinPoint, ModuleAuth moduleAuth) {
    if (!DogEncryptionStorage.hasAuth(moduleAuth.value())) {
        throw new AuthException(NOT_HAS_THIS_FUNCTION_ACCESS);  // code 467
    }
    return joinPoint.proceed();
}

• 能耗计费(51)：modules/bill/** 下所有 Controller
• 监控系统(26)：modules/optiview/controller/AppsController.java:76
• 大屏设计(52)：modules/view/controller/YcviewScreenController.java:345

• modules/energy/task/EnergyCalculateTask.java:103 —— 无 EMS 权限则不执行能耗计算
• modules/energy/task/ScheduleTask.java:60 —— 无 EMS 权限则跳过阈值告警

SysMenu 实体有 authorizeFeatureId 字段（菜单/按钮绑定的 featureId）和 menuSource（菜单类型）。

getMenuListForCurUser()（SysMenuBizImpl.java:86）两个过滤维度：

• 显式匹配：菜单 authorizeFeatureId 必须在当前激活集合内
• 间接匹配（isHasPermission，按 menuSource）：APP 类型需 26、SCREEN 需 52、SYSTEM 需 53

getCurUserPermissions()（行 1480）同理过滤按钮，返回 perms 权限标识串供前端做按钮级控制。

这是「授权变化 → 业务 / 前端感知」的核心机制。

定义在 event/auth/ModuleAuthEventListener.java 内部：

• A. 软授权：SysCertificationBizImpl.refreshSoftCertification() 的 finally（行 176）—— 无论成功 / 清空 / 失败都发一次
• B. 硬狗：CallbackImpl.invoke() 末尾（行 137）—— 每次硬狗状态回调解析完都发

• C. 失效差集：ModuleAuthEventListener.onModuleAuthActivated() 内部（行 119）—— 对比 lastActiveFeatureIds 求差集，差集非空才发。失效事件不会被业务方直接发布，统一由 Listener 计算后转发。

@EventListener
public synchronized void onModuleAuthActivated(ModuleAuthActivatedEvent event) {
    handleModuleAuthActivated(...);              // → activeFeatureHolder.refresh()
    Set<Integer> expiredIds = new HashSet<>(lastActiveFeatureIds);
    expiredIds.removeAll(currentIds);            // 差集 = 上次有、本次无
    if (!expiredIds.isEmpty()) {
        publisher.publishEvent(new ModuleAuthExpiredEvent(expiredFeatures));
    }
    lastActiveFeatureIds = currentIds;           // 更新基准
}

• lastActiveFeatureIds：上次激活快照，失效差集计算的唯一基准；初始为空，故首次激活不产生失效事件。
• synchronized 保证并发安全。

common/auth/holder/ActiveFeatureHolder.java：

• private volatile List<FeatureEnum> activeFeatures —— volatile 引用 + 不可变 List，读无锁、写 synchronized
• @PostConstruct init() —— 启动预热一次（幂等）
• refresh() —— 从 hasAuthFeatureIdList() 重算并整体替换引用
• 触发方：ModuleAuthEventListener.handleModuleAuthActivated/Expired() 两处

FeatureController（GET /system/feature/active）直接读 ActiveFeatureHolder 缓存返回 List<FeatureEnum>（序列化为对象数组，含 name/url/featureId/featureName/show）。不实时计算，返回事件刷新后的快照。

本节说明授权激活 / 失效事件在当前实现中如何传播，以及前端如何感知。

授权事件是纯进程内 Spring 事件，完整传播路径如下：

• 事件的唯一副作用是刷新 ActiveFeatureHolder 本地缓存（ModuleAuthEventListener.java:141-154）。
• 前端不会被实时通知，需等到下一次路由切换（路由守卫调 getFeatureList()）或用户主动操作（如授权成功回调里立即调 getFeatureList()，见 §6.4）才会拉取最新状态。
• 事件不跨进程 / 实例传播（授权状态本身存于 JVM 静态 DogEncryptionStorage，是单进程模型）。

授权事件基于 Spring 的 ApplicationEvent 机制。两个事件类型定义在 ModuleAuthEventListener 内部：

授权事件最常见的实战用途是：某个模块被激活 / 失效时，自动启停该模块的后台任务。以下示例取自 carbon 分支的账单模块（MODULE_ENERGY_BILL_SERVICE 被激活时启动自动账单 / 归档 / 关单 / 欠费告警定时任务，失效时移除）。

在 ModuleAuthEventListener 的两个 handle* 方法里，按 FeatureEnum 判断并联动业务：

@Resource
private BillAutoBillTaskManager billAutoBillTaskManager;  // 注入被联动的业务管理器

/**
 * 处理激活的模块授权
 */
private void handleModuleAuthActivated(List<FeatureEnum> activeFeatures) {
    activeFeatureHolder.refresh();   // 当前 2.1.1：刷新激活功能缓存
    // 业务联动：账单授权被激活 → 重启账单自动任务
    if (activeFeatures.contains(FeatureEnum.MODULE_ENERGY_BILL_SERVICE)) {
        billAutoBillTaskManager.reStartAutoTask();
    }
}

/**
 * 处理失效的模块授权
 */
private void handleModuleAuthExpired(List<FeatureEnum> expiredFeatures) {
    activeFeatureHolder.refresh();   // 当前 2.1.1：刷新激活功能缓存
    // 业务联动：账单授权失效 → 移除账单自动任务
    if (expiredFeatures.contains(FeatureEnum.MODULE_ENERGY_BILL_SERVICE)) {
        billAutoBillTaskManager.removeAutoTask();
    }
}

被联动的业务管理器内部用 FeatureEnum.contains 守卫，确保只在对应模块授权变化时才动作。carbon 分支的 BillAutoBillTaskManager（modules/bill/business/task/BillAutoBillTaskManager.java）完整实现如下，可作为「授权驱动定时任务生命周期」的范本：

@Component
@Slf4j
public class BillAutoBillTaskManager implements InitTask {
    @Resource private BillAutoBillJob autoBillJob;
    @Resource private IScheduleHelper scheduleHelper;
    private final RedisService redisService = RedisKit.bill();

    // 平台启动时：无账单授权则不启动任何账单任务
    @Override
    public void execute(ApplicationArguments args) {
        if (!DogEncryptionStorage.hasAuth(FeatureEnum.MODULE_ENERGY_BILL_SERVICE)) return;
        startAutoTask();
    }

    // 授权激活事件调用：重启全部账单自动任务
    public void reStartAutoTask() {
        startAutoBillTask(true);      // checkExist=true：已存在则跳过
        startAutoArchiveTask(true);
        startAutoCloseOrderTask(true);
        startArrearsAlertTask(true);
    }

    // 授权失效事件调用：移除全部账单自动任务
    public void removeAutoTask() {
        removeAutoBillTask();
        removeArrearsAlertTask();
        removeAutoArchiveTask();
        removeAutoCloseOrderTask();
    }
    // ... 每个 start*Task 内部用 scheduleHelper 注册 Quartz 定时任务，id 存 Redis
}

• 判断依据是 List<FeatureEnum>.contains(目标模块)，激活事件拿到的是全集（判断「是否包含」即可），失效事件拿到的是差集（列表里的就是要处理的）。
• 平台启动时（InitTask.execute）也用 DogEncryptionStorage.hasAuth() 做一次同样的守卫，保证重启后状态与授权一致。
• 业务管理器自身要做好幂等（carbon 用 Redis 存任务 ID，checkExist=true 时已存在则跳过），因为授权事件可能多次触发。

DogEncryptionStorage.authPoint()（行 105）：

• 分别从 hard/soft Map 取点位授权，按 featureId 降序取最大档位
• 换算：允许点数 = (featureId - 100) * 500（每档 500 点）
• 任一档位 featureId ≥ 201 → 返回 -1（无限制）

• 新增点位上限校验：drivers/access/PlatformApiImpl.java、modules/iot/biz/impl/DriverBizImpl.java
• 80% 容量预警（同上）
• 前端展示：SysCertificationBizImpl.getPointCapacity() 返回 {curPointNum, pointCapacity, percentage}

即 featureId=100（0 点位档位）在硬狗下会进 superDogPoint&& 检索范围、在软授权下不会。实践中 100 档位（0 点）极少单独出现，影响有限，但排查点位计数异常时需留意此差异。

font_end/src/store/modules/authStore/authStore.ts：

font_end/src/router/index.ts:168，已有 router.beforeEach 守卫登录态校验通过后：

if (Cookies.get(multipleTabsKey) && userInfo) {
  useAuthStore().getFeatureList();  // 每次切页面刷新激活功能授权
  ...
}

不阻塞导航，保证后端缓存变化后前端下一次切页面即可同步。

font_end/src/layout/components/lay-navbar/index.vue：

• 智问按钮 v-show="showZhiwen"，APP 按钮 v-show="showApp"
• showZhiwen/showApp 为 computed，基于 authStore.hasFeature(...)
• 用 v-show 不用 v-if：navbar 是常驻布局组件，v-show 保持 DOM 骨架稳定，避免导航时虚拟 DOM 锚点失效（曾因 v-if 导致 parentNode null 报错，已修复）

font_end/src/layout/components/lay-navbar/components/AuthInfo.vue：

• 「大模型配置」Tab：v-if="showZhiwen"（无智问授权则不显示该 Tab）
• 软件 / 硬件授权卡片列表：无智问授权时过滤掉 name 含"智问"的卡片
• 授权成功回调（submit()）：除 getAuthInfo() 外立即调用 getFeatureList()，使按钮 / Tab 即时按新权限显隐，无需等下次切页面

硬件狗插拔：CallbackImpl 回调 → 发 ModuleAuthActivatedEvent("hard") → 缓存刷新 → 前端下次切页面 getFeatureList() 同步。

在 Controller 方法 / 类上加注解 @ModuleAuth(FeatureEnum.XXX)，由切面 CheckModuleAuth 拦截：进入方法前先查 DogEncryptionStorage.hasAuth()，无授权直接抛异常，业务方法不会执行。

@ModuleAuth(FeatureEnum.MODULE_ENERGY_BILL_SERVICE)   // 进入前校验计费授权
@PostMapping("/save")
public Result save(@RequestBody BillDTO dto) {
    // 能走到这里，说明已拥有计费模块授权(51)
    return Result.success(billBiz.save(dto));
}

• 有授权：正常进入方法执行。
• 无授权：抛 AuthException(NOT_HAS_THIS_FUNCTION_ACCESS)，经 AuthExceptionHandler 统一转成 Result.error(467, "用户无此功能权限") 返回前端。

需要在方法内部按权限决定「要不要执行某段逻辑」时，直接调静态方法 DogEncryptionStorage.hasAuth(FeatureEnum.XXX)。不会抛异常，由调用方自行决定处理方式（通常用于定时任务、降级逻辑、点位容量校验）。

// 场景一：定时任务——无 EMS 授权则跳过执行
if (!DogEncryptionStorage.hasAuth(FeatureEnum.MODULE_ENERGY_SERVICE)) {
    return;   // 静默跳过，不抛异常
}
energyCalculateBiz.calculate();

// 场景二：启动时——无授权则不初始化该模块任务
if (!DogEncryptionStorage.hasAuth(FeatureEnum.MODULE_ENERGY_BILL_SERVICE)) return;
startAutoTask();

当某模块从无授权变为有授权（或软授权重新刷新）时发布。典型用途：模块被激活 → 自动启动该模块的后台任务 / 缓存。

订阅写法（在 ModuleAuthEventListener.handleModuleAuthActivated 内联动，或在任意 @Component 用 @EventListener 独立订阅）：

// 方式一：在 ModuleAuthEventListener.handleModuleAuthActivated 里联动（与缓存刷新同处）
private void handleModuleAuthActivated(List<FeatureEnum> activeFeatures) {
    activeFeatureHolder.refresh();
    if (activeFeatures.contains(FeatureEnum.MODULE_ENERGY_BILL_SERVICE)) {
        billAutoBillTaskManager.reStartAutoTask();   // 启动账单定时任务
    }
}

// 方式二：独立 @EventListener（与 handle* 并行执行，互不影响）
@EventListener
public void onAuthActivated(ModuleAuthEventListener.ModuleAuthActivatedEvent event) {
    if (event.getActiveFeatures().contains(FeatureEnum.MODULE_ZHIWEN_SERVICE)) {
        // 智问授权被激活 → 初始化 AI 配置缓存
    }
}

当某模块从有授权变为无授权时发布（如拔狗、导入新授权码后旧模块消失、过期）。典型用途：模块失效 → 自动停止该模块的后台任务 / 释放资源。

订阅写法：

// 在 ModuleAuthEventListener.handleModuleAuthExpired 里联动
private void handleModuleAuthExpired(List<FeatureEnum> expiredFeatures) {
    activeFeatureHolder.refresh();
    if (expiredFeatures.contains(FeatureEnum.MODULE_ENERGY_BILL_SERVICE)) {
        billAutoBillTaskManager.removeAutoTask();   // 移除账单定时任务
    }
}

异常经 AuthExceptionHandler（@RestControllerAdvice）统一转成 Result.error。