分组聚合查询组件

分组聚合查询组件（DbQueryGroup）用于按字段分组并做聚合统计，返回分组后的聚合结果。

概述

分组聚合查询按一个分组字段（GroupField）对记录分组，再对聚合字段（AggregateField）执行聚合运算，例如按「部门」分组统计「金额」之和。它常用于统计报表、图表数据源与看板指标。

组件先按统一的「基础 / 高级」条件筛选数据（详见 全局属性），默认条件过滤已删除数据。

配置项

配置项	说明
操作对象	要统计的实体对象，必填
默认条件	筛选条件，支持基础模式与高级模式
分组字段	分组依据的字段，必填
聚合方式	聚合运算方式，必填，缺省为「计数」
聚合字段	参与聚合的字段，聚合方式非「计数」时使用
排序	聚合结果的排序方向，必填，缺省为「顺序」
输出到最终结果	开启后该组件结果作为接口返回值

聚合方式取值

界面名称	值（AggregateMethod）	说明
计数	count	统计记录条数（缺省）
求和	sum	数值字段求和
平均值	avg	数值字段求平均
最大值	max	取最大值
最小值	min	取最小值

排序取值

界面名称	值（SortType）	说明
顺序	1	升序（缺省）
倒序	-1	降序

使用场景

• 统计报表
• 图表数据源
• 按维度汇总业务数据

下一步

• 查询集合 - 查询记录列表
• 查询数量 - 统计记录数量
• 数据源 - 生成下拉选项数据

属性明细

以下内容面向技术实现与 AI 检索，说明分组聚合查询组件的节点元数据。

节点元数据

分组聚合查询组件由 FlowCmpType.DbQueryGroup 标识。所有节点 meta 值均以字符串存储（布尔、数字、数组等在元数据中同样以字符串形式保存）。

属性名	类型	含义	取值/存储值
type	string	组件类型	固定为 "DbQueryGroup"
MetaObjectId	string(GUID)	目标实体对象	缺省取当前接口所属对象
DefaultFilter	string(JSON)	高级模式的条件	条件 JSON，缺省为 isdeleted = false 模板
BasicFilter	string(JSON)	基础模式的条件	条件 JSON
ConditionMode	string	条件编辑模式	"basic"（缺省）/ "advanced"
GroupField	string	分组字段编码	字段的 Code
AggregateMethod	string	聚合方式	"count"（缺省）/ "sum" / "avg" / "max" / "min"
AggregateField	string	聚合字段编码	非计数时使用
SortType	string	排序方向	"1"（升序，缺省）/ "-1"（降序）
IsFinalResult	string(bool)	是否输出到最终结果	"true" / "false"
IsDisabled	string(bool)	是否禁用该节点	"true" / "false"
order	string	同级排序	例："11"

元数据存储示例

{
  "ID": "group1",
  "type": "DbQueryGroup",
  "MetaObjectId": "3f9c0b2e-2d3a-4e6f-9c11-0f7a5b8d2e10",
  "ConditionMode": "basic",
  "GroupField": "DepartmentId",
  "AggregateMethod": "sum",
  "AggregateField": "Amount",
  "SortType": "-1",
  "IsFinalResult": "true",
  "order": "11"
}

服务端执行逻辑

本节说明 DbQueryGroupComponentManager 在服务端的真实执行过程。组件继承自 TriggerComponentManagerBase，接口链路与实体触发器链路均会执行。

执行时机与场景

• 执行入口为 _ExecuteAsync，先生成聚合 SQL，再执行并组装为图表数据；执行后调用 ExecuteNextAsync 继续下游。
• 基类执行前读取 IsDisabled，为 "true" 时跳过本组件。

查询条件组装

条件组装优先级自高到低：

1. context.FilterOverride（最高优先）：一旦赋值，覆盖其他所有条件。
2. 否则拼接默认条件，并追加密链路条件：
   • 默认条件：由 ConditionFilterResolver.ResolveAsync(ConditionMode, DefaultFilter, BasicFilter, ctx) 解析。ConditionMode="basic" 时读取 BasicFilter 并按值类型解析；其他情况按「高级模式」反序列化 DefaultFilter。
   • context.AndFilter：链路按需插入的额外 AND 条件。
3. 最终若仍为空，则使用 FilterBuilder.Empty 作为条件。

与查询集合不同，分组聚合组件不读取 request.Condition，也不执行默认值占位符替换。

权限过滤

1. 查询操作权限：除非 SkipOperationPermission 生效，否则调用 VerifyPermissionAsync(Query) 校验 MetaObjectDataOperationType.Query，无权限直接抛出 NoPermissionAccess。
2. 组件不拼接 MOU 数据权限过滤，即不调用 CombineDataPermissionFilterAsync；因此本组件的聚合结果不受 MOU 行级权限约束。
   • SkipOperationPermission 取自节点 meta 或 context.DicParam。

分组字段与聚合字段校验

• 分组字段：执行时要求 GroupField 存在于对象字段集合，否则抛出 GroupFieldNotFound。
• 聚合字段：AggregateField 为空时缺省为 _id；非空时必须存在于对象字段集合，否则抛出 AggregateFieldNotExist。

执行与 SQL 形态

组件通过数据访问层生成聚合 SQL 并执行：

var listSql = sqlManager.GetLookupQueryGroupSql(
    metaObject.Code, metaFields, filter, listParam,
    sort, groupField.ToLowerInvariant(), aggregateMethod, aggregateField.ToLowerInvariant());
var result = await chameleonDbContext.GetListBySqlAsync(listSql, listParam);

• 排序字典以 groupField（小写）为唯一键，方向取排序配置。
• 分组字段、聚合字段均转为小写传入 SQL 生成器。
• 结果行包含分组列与聚合列（聚合列键名为 value）。

数据翻译

聚合结果的分组维度值会做数据源翻译（TranslateXField）：对每个分组值构造临时 ObjectData，调用 dataSourceApp.TranslateAsync(objectDatas, metaObjectId, metaFields)，再读取该字段的 .Text 展示文本。翻译不到的取值回退为原始值；聚合数值（value）不做翻译。

输出与上下文

结果组装为 EChartsData<string, string, long>：

输出项	内容
XAxis.Data	各分组的展示值（经翻译）
Series.Data	各分组的聚合值（Convert.ToInt64，空值记 0）
context.CmpResult	上述 EChartsData 对象
context.DicParam["MetaObjectCode"]	对象编码
context.DicParam["MetaObjectId"]	对象 ID

当 IsFinalResult="true" 时，写入 context.TransferResult.EChartsData 与 .Total = 1，并赋值 context.Result = ResponseResult<EChartsData<string, string, long>>.Success(res).Total(1)。

性能与限制

• 聚合在数据库侧完成，仅返回「分组数」条结果，无分页参数。
• 组件递归深度上限 100，超过抛出异常。

异常与校验

校验阶段（_VerifyAsync）：

场景	异常
MetaObjectId 为空	OperationObjectNotFound
对象不存在	MetaObjectNotFoundById
GroupField 为空	GroupFieldNotSet
AggregateMethod 为空	AggregateMethodNotSet
SortType 不为 "1" / "-1"	SortModeConfigError

执行阶段：

场景	异常
无查询操作权限	NoPermissionAccess
分组字段不存在于对象	GroupFieldNotFound
聚合字段不存在于对象	AggregateFieldNotExist