查询单条组件
查询单条组件（DbQuerySingle）用于按主键查询单条实体记录。
概述
查询单条组件从目标实体中取出指定主键的一条记录，并返回所选的查询字段。相比查询集合，它只返回一条数据，适合「取详情」「取唯一配置项」等场景。
记录主键由上游传入（例如上一条记录的 ID），组件本身只需选择操作对象与需要返回的字段。
配置项
| 配置项 | 说明 |
|---|---|
| 操作对象 | 要查询的实体对象，必填 |
| 查询字段 | 需要返回的字段，必填，可多选，支持关联（lookup）字段 |
| 输出到最终结果 | 开启后该组件结果作为接口返回值 |
主键来源
组件不单独配置主键，而是按以下顺序自动解析：
- 上游数据操作组件写入的
BizDataIds（取逗号分隔的第一个）。 - 请求 query 参数
dataId。 - 请求 query 参数
id。 - 请求体
request.list中唯一一条数据的Id。
若以上均未取到，组件执行时抛出「未找到 ID 参数」异常。
查询字段
「查询字段」决定返回记录包含哪些字段，支持关联字段（含 ~）。执行时会与对象字段集合取交集，并在有配置查询字段时自动附加 organization 字段。
使用场景
- 根据主键获取详情
- 读取唯一配置项
- 查询关联对象数据
下一步
属性明细
以下内容面向技术实现与 AI 检索，说明查询单条组件的节点元数据。
节点元数据
查询单条组件由 FlowCmpType.DbQuerySingle 标识。所有节点 meta 值均以字符串存储（布尔、数字、数组等在元数据中同样以字符串形式保存）。
| 属性名 | 类型 | 含义 | 取值/存储值 |
|---|---|---|---|
type | string | 组件类型 | 固定为 "DbQuerySingle" |
MetaObjectId | string(GUID) | 目标实体对象 | 缺省取当前接口所属对象 |
QueryFields | string | 查询字段编码列表 | 逗号分隔，例 "Name,Code" |
IsFinalResult | string(bool) | 是否输出到最终结果 | "true" / "false" |
IsDisabled | string(bool) | 是否禁用该节点 | "true" / "false" |
order | string | 同级排序 | 例："8" |
元数据存储示例
{
"ID": "single1",
"type": "DbQuerySingle",
"MetaObjectId": "3f9c0b2e-2d3a-4e6f-9c11-0f7a5b8d2e10",
"QueryFields": "Name,Code,Status",
"IsFinalResult": "true",
"order": "8"
}
字段数据源
「查询字段」下拉通过 POST /api/DataSource/GetMetaFieldDataSource 获取（带 extend.IncludeLookup = "true"），切换操作对象后重新请求。
服务端执行逻辑
本节说明 DbQuerySingleComponentManager 在服务端的真实执行过程。组件继承自 TriggerComponentManagerBase，接口链路与实体触发器链路均会执行。
执行时机与场景
- 执行入口为
_ExecuteAsync，按主键精确查询一条记录，执行后调用ExecuteNextAsync继续下游。 - 基类执行前读取
IsDisabled，为"true"时跳过本组件。
主键解析
按「上游 BizDataIds → query dataId → query id → 请求体唯一数据 Id」的顺序解析；BizDataIds 取逗号分隔后的第一个非空项，请求体分支要求 list 恰好一条且 Id 非空。全部落空时抛出 IdParameterNotFound。
查询字段解析
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | 节点 QueryFields | 非空即用 |
| 2 | query 参数 queryFields | 节点未配置时读取 |
| 3 | query 参数 metaFormId | 读取对象表单 Layout，取其中表单项的 Code 作为字段（优先级高于节点配置的查询字段） |
随后对含 ~ 的 lookup 字段补上其前缀基础字段；若最终有字段集合，则与对象字段集取交集并追加 organization；未配置查询字段时取对象全部字段。
权限过滤
- 查询操作权限：除非
SkipOperationPermission生效，否则调用VerifyPermissionAsync(Query)校验MetaObjectDataOperationType.Query，无权限直接抛出NoPermissionAccess。 - MOU（数据）权限：查询到结果后，若未开启
SkipMouPermission，以FilterBuilder.Eq(_id, result._id)为基底，调用CombineDataPermissionFilterAsync(context, metaObject, filter, MouPermissionStageEnum.QuerySingle)得到带 MOU 的过滤条件，再用GetListAsync(code, filter, ["_id"])复核；若结果 ID 不在返回集合中，抛出NoPermissionAccessData。SkipOperationPermission取自节点meta或context.DicParam；SkipMouPermission仅取自context.DicParam。
执行与 SQL 形态
单条查询直接按主键读取：
var result = await chameleonDbContext.GetByIdAsync(metaObject.Code, Guid.Parse(id), columns);
即 IChameleonDbContext.GetByIdAsync(集合名称, id, columns)，对应底层按 _id 的单行查询，无需构造 DynamicFilter，也不涉及排序与分页。
数据翻译
结果非空时依次执行：
dataSourceApp.TranslateAsync(resultList, metaObject._id, metaFields)：存储值 → 展示值。dataSourceApp.TranslateLookupAsync(resultList, metaFields, queryFields 数组)：按查询字段填充 lookup 关联字段。
输出与上下文
| 输出项 | 内容 |
|---|---|
context.CmpResult | List<ObjectData>（0 或 1 条） |
context.DicParam["BizDataIds"] | 结果记录的 _id |
context.DicParam["MetaObjectCode"] | 对象编码 |
context.DicParam["MetaObjectId"] | 对象 ID |
当 IsFinalResult="true" 时，写入 context.TransferResult.List / .Total，并赋值 context.Result = ResponseResult<List<ObjectData>>.Success(resultList).Total(resultList.Count)。
性能与限制
- 单条按主键查询，无分页与排序开销；结果最多一条。
- 组件递归深度上限 100，超过抛出异常。
异常与校验
校验阶段 （_VerifyAsync）：
| 场景 | 异常 |
|---|---|
MetaObjectId 为空 | OperationObjectNotFound |
| 对象不存在 | MetaObjectNotFoundById |
执行阶段：
| 场景 | 异常 |
|---|---|
| 未解析到主键 | IdParameterNotFound |
| 无查询操作权限 | NoPermissionAccess |
| 记录未通过 MOU 权限复核 | NoPermissionAccessData |