跳到主要内容

黑名单状态控制

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件围绕黑名单状态控制进行全面技术与实践说明，涵盖黑名单生命周期管理（状态定义、状态转换、状态同步）、启用/禁用操作（权限控制、业务验证、数据更新）、生效时间控制（定时/立即/延迟策略）、版本管理（版本号生成、版本比较、回滚）、以及配置选项与使用指南。目标是帮助管理员与开发者高效、安全地管理黑名单状态。

项目结构​

黑名单状态控制主要位于黑名单模块的业务实现层，配合 BPM 流程、规则引擎、Redis 缓存与字典数据，形成“配置-审批-同步-生效”的闭环。

Mermaid Diagram Code:

graph TB
subgraph "黑名单模块"
A["AppBlacklistedDO<br/>主表实体"]
B["IAppBlackListedBpmService<br/>接口"]
C["AppBlackListedBpmServiceImpl<br/>审批流服务实现"]
D["BlacklistUtil<br/>工具类"]
E["RuleBlacklistStatusListener<br/>规则变更监听"]
F["BlacklistedScopeVO<br/>范围变更载体"]
G["BlacklistConfig<br/>配置开关"]
end
subgraph "外部依赖"
H["BpmProcessInstanceApi<br/>流程实例API"]
I["DictDataApi<br/>字典数据API"]
J["RuleBusinessApi<br/>规则业务API"]
K["AppBlacklistedRedisDAO<br/>Redis缓存"]
end
B --> C
C --> A
C --> D
C --> E
C --> F
C --> G
C --> H
C --> I
C --> J
C --> K

图表来源

章节来源

核心组件​

  • 主数据对象：AppBlacklistedDO，承载黑名单的基础信息、草稿、流程状态、生效状态等字段。
  • 审批流服务：IAppBlackListedBpmService 与 AppBlackListedBpmServiceImpl，负责创建/取消审批流、处理审批结果、同步业务与关联表、更新 Redis。
  • 工具类：BlacklistUtil，提供可编辑性校验、草稿状态更新等辅助方法。
  • 规则监听：RuleBlacklistStatusListener，响应规则变更事件，将黑名单流程状态置为“未开始”。
  • 配置开关：BlacklistConfig，控制是否启用规则引擎模式。
  • 枚举：BpmBusinessValid、GlobalBpmBusinessValid，统一业务生效状态语义。

章节来源

架构总览​

黑名单状态控制贯穿“配置-审批-同步-生效”全流程，关键节点包括：

  • 配置变更：管理员或普通用户发起变更，系统根据权限与配置决定是否进入审批流。
  • 审批流：创建流程实例，传递业务变量；监听流程状态变化，执行业务数据与关联表的同步。
  • 生效同步：审批通过后，更新主表与关联表的生效状态，同步至 Redis，供设备侧查询使用。
  • 规则联动：规则引擎变更时，触发黑名单流程状态调整，避免脏数据。

Mermaid Diagram Code:

sequenceDiagram
participant Admin as "管理员/普通用户"
participant Ctrl as "控制器/服务"
participant BPM as "BPM流程实例API"
participant Svc as "AppBlackListedBpmServiceImpl"
participant DB as "数据库/Redis"
Admin->>Ctrl : "提交变更(含权限/业务校验)"
Ctrl->>Svc : "createBpm(userId, blackListedId)"
Svc->>BPM : "创建流程实例(携带业务变量)"
BPM-->>Svc : "返回流程实例ID"
Svc->>DB : "更新bpmStatus=审批中"
Note over Svc,DB : "等待流程结束"
BPM-->>Svc : "推送流程结果事件(APPROVE/DENY/CANCEL)"
Svc->>DB : "审批通过 : valid=已生效, 清理草稿"
Svc->>DB : "同步关联表(渠道/区域/MAC)生效状态"
Svc->>DB : "更新Redis(设备维度范围)"

图表来源

详细组件分析​

状态定义与生命周期​

  • 主表字段
    • status：开启状态（启用/禁用）
    • type：删除状态（如卸载/杀死）
    • version：版本号（可空，空表示对所有版本生效）
    • draft：未审批通过的草稿数据
    • bpmStatus：流程状态（未开始/审批中/审批通过/审批不通过/已取消）
    • valid：生效状态（未生效/已生效/已生效且做移除标记/已生效且做修改标记）
  • 生命周期阶段
    • 草稿阶段：bpmStatus=-1，valid=未生效
    • 审批中：bpmStatus=审批中，valid=未生效
    • 已生效：bpmStatus=审批通过，valid=已生效
    • 已取消/未通过：bpmStatus=已取消/审批不通过，valid=未生效

Mermaid Diagram Code:

stateDiagram-v2
[*] --> 草稿
草稿 --> 审批中 : "创建流程"
审批中 --> 已生效 : "审批通过"
审批中 --> 未开始 : "取消/未通过"
已生效 --> 已生效 : "修改(草稿->审批->生效)"
已生效 --> 未开始 : "删除(草稿->审批->删除)"

图表来源

章节来源

状态转换与同步机制​

  • 创建审批流
    • 校验是否存在运行中的流程实例，若存在则取消后提示“系统正在处理”
    • 构建业务变量，包含基础信息与关联范围变更摘要
    • 调用流程实例 API 创建流程，写入 processInstanceId 与 bpmStatus=审批中
  • 处理审批结果
    • 仅当流程状态为“审批通过”时，更新 valid=已生效，清理草稿
    • 同步主表与关联表（渠道/区域/MAC）的生效状态
    • 更新 Redis 中设备维度的范围缓存（新增/删除范围分别处理）

Mermaid Diagram Code:

flowchart TD
Start(["进入 handleBpmResult"]) --> CheckKey["校验业务Key是否存在"]
CheckKey --> |否| End(["退出"])
CheckKey --> |是| LoadData["加载业务数据(带草稿)并加锁"]
LoadData --> SetBpmStatus["更新bpmStatus为流程最终状态"]
SetBpmStatus --> IsApprove{"审批通过?"}
IsApprove --> |否| UpdateOnly["仅更新流程状态"] --> End
IsApprove --> |是| SetValid["valid=已生效, 清理草稿"]
SetValid --> ParentOp{"父级操作类型"}
ParentOp --> |删除| DeleteMain["删除主表记录"]
ParentOp --> |新增| NoopMain["无需更新主表(已生效)"]
ParentOp --> |修改| ApplyDraft["应用草稿到主表"]
DeleteMain --> SyncRel["同步关联表(渠道/区域/MAC)生效状态"]
NoopMain --> SyncRel
ApplyDraft --> SyncRel
SyncRel --> UpdateRedis["更新Redis设备范围缓存"]
UpdateRedis --> End

图表来源

章节来源

启用/禁用操作与权限控制​

  • 权限与生效策略
    • 非管理员修改：进入审批流，审批通过后生效
    • 管理员修改：直接生效，不触发审批流
  • 业务验证
    • 校验是否存在运行中的流程实例，避免并发覆盖
    • 校验草稿内容是否为空，避免无意义提交
    • 校验主表是否已完全审批通过，避免重复提交
  • 数据更新
    • 审批通过后，更新主表与关联表的生效状态
    • 更新 Redis，确保设备侧查询即时生效

章节来源

生效时间控制策略​

  • 立即生效
    • 管理员直接修改时，系统直接更新主表与关联表生效状态，并同步 Redis
  • 审批生效
    • 非管理员修改时，通过审批流控制生效时机；审批通过后统一同步
  • 延迟生效
    • 代码中未见显式的“延迟生效”策略实现；可通过流程变量扩展实现（如在流程变量中携带生效时间戳，服务端在指定时间点再执行生效动作）

章节来源

版本管理机制​

  • 版本号字段
    • 主表包含 version 字段，用于限定生效的 APP 版本
    • 空值表示对所有版本生效
  • 版本比较与回滚
    • 代码中未见专门的“版本比较/回滚”逻辑；版本字段主要用于匹配与展示
    • 回滚可通过新增一条更高优先级的黑名单记录实现（在规则引擎或查询侧具备更高优先级时）

章节来源

配置选项与使用指南​

  • 配置项
    • blacklist.rule.enable：是否启用规则引擎模式
  • 使用指南
    • 新增/编辑黑名单：填写应用名称、包名、开启状态、删除状态、版本号等
    • 关联范围：可配置渠道、地区、MAC 等范围
    • 审批流程：非管理员修改需提交审批，管理员修改直接生效
    • 导出与查询：支持批量导出与按状态/流程状态筛选

章节来源

依赖分析​

  • 组件耦合
    • AppBlackListedBpmServiceImpl 依赖 BPM、字典、规则引擎、RedisDAO、Mapper 等，职责集中于审批流与状态同步
    • BlacklistUtil 提供可编辑性校验与草稿状态更新，降低重复逻辑
    • RuleBlacklistStatusListener 作为事件监听器，解耦规则变更与黑名单状态
  • 外部依赖
    • BPM 流程实例 API：创建/取消/查询流程实例
    • 字典数据 API：流程变量与状态标签映射
    • 规则业务 API：审批变更信息获取
    • RedisDAO：设备维度范围缓存更新

Mermaid Diagram Code:

graph LR
Svc["AppBlackListedBpmServiceImpl"] --> BPM["BpmProcessInstanceApi"]
Svc --> Dict["DictDataApi"]
Svc --> Rule["RuleBusinessApi"]
Svc --> Redis["AppBlacklistedRedisDAO"]
Svc --> Mapper["AppBlacklistedMapper"]
Util["BlacklistUtil"] --> Mapper
Listener["RuleBlacklistStatusListener"] --> Util

图表来源

章节来源

性能考虑​

  • Redis 同步优化
    • 关联表范围变更采用批量写入/删除，减少多次网络往返
    • 对删除场景采用增量删除策略，避免全量扫描
  • 并发控制
    • 通过“正在运行的流程实例”检测与数据库行级锁，避免并发覆盖
  • 流程变量与规则联动
    • 审批流程变量中携带规则变更摘要，便于审计与回溯

章节来源

故障排查指南​

  • 常见错误
    • “存在正在运行的流程实例，请稍后刷新查看最新状态”：系统自动取消旧流程后提示
    • “该黑名单配置的修改没有修改任何内容，无需提交审批”：草稿为空或无变更
    • “该黑名单配置的修改已完全审批通过，请勿重复提交”：重复提交审批
  • 排查步骤
    • 检查 bpmStatus 与 processInstanceId 是否一致
    • 校验 draft 是否为空，确认是否需要重新编辑
    • 若规则引擎变更导致流程状态异常，检查 RuleBlacklistStatusListener 是否正确处理

章节来源

结论​

黑名单状态控制通过“审批流+生效状态+Redis同步”的组合，实现了对黑名单配置的精细化管理。管理员可借助规则引擎与审批流，确保变更的安全与可追溯；设备侧通过 Redis 缓存获得低延迟的黑名单查询结果。未来可在流程变量中扩展“延迟生效”能力，并完善版本回滚策略，进一步提升系统的灵活性与可运维性。

附录​

  • 相关文档入口
    • 黑名单管理模块概览与功能入口
    • APP 卸载配置管理与审批流程说明
  • 关键字段说明
    • status：开启状态（启用/禁用）
    • type：删除状态（卸载/杀死）
    • version：版本号（空表示全部版本）
    • draft：未审批草稿
    • bpmStatus：流程状态
    • valid：生效状态

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答