“# 渠道分组过滤业务流程说明
文档生成时间：2025-05-29
最后更新：2025-05-29
概述
本文档详细描述了AI Hub平台的渠道分组过滤业务流程，包括渠道选择逻辑、优先级规则、配置解析顺序以及各层级渠道配置的处理机制。
业务背景
在AI Hub平台中，用户使用AI服务时需要通过渠道进行请求转发。为了满足不同用户、组织和分销商的渠道使用需求，系统实现了多层次的渠道分组过滤机制。
核心概念
1. 渠道组 (Channel Groups)
- 预定义的渠道分组，如
default、premium、enterprise等 - 每个渠道组包含一组具体的渠道实例
2. 配置字段
- UseChannels: 渠道白名单，逗号分隔的渠道组名称
- ExcludeChannels: 渠道黑名单，逗号分隔的渠道组名称
3. 配置层级
- 组织层级: 组织级别的渠道配置
- 用户层级: 用户个人的渠道配置
- 分销商层级: 分销商相关的渠道配置
业务流程总览
主流程：GetChannelGroupsHandler
详细处理逻辑
1. 缓存读取与降级处理
入口函数: GetChannelGroupsHandler(userId int, autoChannels []string) []string
- 输入: 用户ID + 系统自动筛选的基础渠道组
- 第一步: 尝试读取用户缓存信息
- 降级策略: 如果缓存读取失败，直接返回
autoChannels，不做额外过滤 - 目的: 确保系统在异常情况下仍能正常工作
2. 组织链渠道配置解析
函数: getChannelGroupsOrgHandle(orgId int, autoChannels []string) ([]string, bool)
处理逻辑：
- 当前组织检查: 检查当前组织是否配置了
UseChannels - 递归向上查找: 如果当前组织无配置，递归向上级组织查找
- 顶级组织处理: 到达顶级组织后，查找组织类型分销商配置
- 返回值:
- 过滤后的渠道组列表
- 布尔值表示是否在组织链中找到有效配置
递归查找示例：
组织层级: 公司总部 → 事业部 → 部门 → 团队
查找顺序: 团队 → 部门 → 事业部 → 公司总部3. 用户层级配置解析
函数: getChannelGroupsUserHandle(cache *model.UserBase, autoChannels []string) []string
处理逻辑：
- 用户配置优先: 如果用户自身配置了
UseChannels，按用户配置过滤 - 分销商备选: 否则查找个人类型分销商的渠道配置
- 默认返回: 如果都无配置，返回原始
autoChannels
4. 分销商渠道配置
函数: GetChannelGroupsByResellerByTargetIdAndType(targetType string, targetId int, autoChannels []string) ([]string, bool)
分销商类型：
- 个人分销商 (
ResellerTypePersonal): 针对单个用户 - 组织分销商 (
ResellerTypeOrganization): 针对整个组织
处理逻辑：
- 根据目标类型和ID查找对应的分销商
- 获取分销商父级用户的渠道配置
- 应用分销商配置到渠道组过滤
5. 渠道组过滤算法
核心函数: AppendAndRemoveChannelGroups(channels []string, useChannels string, excludeChannels string) []string
两步过滤策略：
白名单追加 (
AppendChannelGroups)- 将
UseChannels中的渠道组追加到基础渠道组 - 跳过已存在的渠道组，避免重复
- 忽略空字符串和空白项
- 将
黑名单移除 (
RemoveChannelGroups)- 从结果中移除
ExcludeChannels指定的渠道组 - 同样忽略空字符串和空白项
- 从结果中移除
示例：
// 输入
channels = [\"default\", \"premium\"]
useChannels = \"enterprise,vip\"
excludeChannels = \"premium\"
// 处理过程
1. 追加白名单: [\"default\", \"premium\", \"enterprise\", \"vip\"]
2. 移除黑名单: [\"default\", \"enterprise\", \"vip\"]配置优先级规则
优先级顺序（从高到低）
- 组织链配置 ← 最高优先级
- 用户个人配置
- 分销商配置 ← 最低优先级
规则说明
- 组织配置优先: 只要组织链中任意级别配置了
UseChannels，就以其为准 - 用户配置次之: 仅当组织无配置时，才检查用户个人配置
- 分销商兜底: 前两者都无配置时，才使用分销商配置
- 黑名单覆盖: 黑名单在所有情况下都会生效
异常处理与容错
1. 缓存读取失败
- 场景: 用户缓存信息无法获取
- 处理: 直接返回基础
autoChannels，保障服务可用性
2. 配置解析异常
- 空配置处理: 空字符串或空白项自动忽略
- 无效渠道组: 不存在的渠道组名称会被过滤算法自然排除
3. 递归保护
- 终止条件: 到达顶级组织（ParentId=0）时停止递归
- 循环检测: 依赖数据库约束防止组织链循环引用
性能考虑
1. 缓存优化
- 用户信息缓存减少数据库查询
- 渠道组配置缓存提升过滤性能
2. 递归深度控制
- 组织层级通常不会过深（一般3-5级）
- 递归查找在合理范围内
3. 算法效率
- 使用map进行存在性检查，O(1)时间复杂度
- 避免不必要的数组操作
使用场景示例
场景1：企业统一渠道管理
组织配置:
UseChannels: "enterprise,stable"
ExcludeChannels: "experimental"
效果: 该组织下所有用户只能使用enterprise和stable渠道组场景2：VIP用户特殊渠道
用户配置:
UseChannels: "vip,premium"
ExcludeChannels: ""
效果: 该用户可以使用vip和premium渠道组，覆盖组织配置场景3：分销商渠道限制
分销商配置:
UseChannels: "partner"
ExcludeChannels: "internal"
效果: 该分销商下的用户/组织只能使用partner渠道组相关配置接口
参考其他文档中的相关接口：
- 组织渠道配置更新接口
- 用户渠道配置更新接口
- 分销商管理接口
注意事项
- 配置生效时间: 渠道配置修改后需要等待缓存刷新
- 权限控制: 渠道配置修改需要相应权限
- 监控告警: 建议监控渠道过滤异常情况
- 日志记录: 关键操作需要记录审计日志
文档版本: v1.0”
