/**
 * LookupFieldDriver —— 引用字段驱动
 *
 * 功能参考钉表格的查找引用字段：
 * 通过引用其他数据表的字段，根据查找条件匹配记录，回填目标字段值。
 *
 * 设计要点：
 * 1. panelKind = 'inline'，用户选择后弹出配置面板。
 * 2. MaterializeMode = 'passive'，数据由后端查找引用服务填充。
 * 3. 配置包含：引用数据表、引用字段、字段描述与可检索能力（canSearch/model）。
 * 4. 配置持久化到 DataModel.customFields.lookupConfig，由视图保存链路统一落远端。
 * 5. `lookupFieldConfig.hiddenSubTable === true` 且配置了业务回调时，先回调再写本地/魔方；
 *    未开启 hiddenSubTable 时不走业务回调，保持原引用字段逻辑。
 */
import type { FieldDriver, FieldMeta, FieldUiContribution, FieldRecord, FieldContext } from '../types';
/** 查找引用字段配置接口 */
export interface LookupFieldConfig {
    /** 字段名称，用于列头展示 */
    fieldName: string;
    /** 引用的数据表 ID，指向被引用的源数据表 */
    sourceTableId: string;
    /** 引用的数据表名称，仅用于 UI 展示 */
    sourceTableName?: string;
    /** 引用的目标字段 code，标识源表中具体被引用的字段 */
    targetFieldCode: string;
    /** 引用的目标字段名称，仅用于 UI 展示 */
    targetFieldName?: string;
    /** 列 code，作为字段的唯一持久化标识，格式为 sourceTableId_targetFieldCode */
    columnCode: string;
    /** 字段描述信息，用于 tooltip 或帮助面板展示 */
    description?: string;
    /** 是否支持在 CnAiFilter 组件中作为检索条件 */
    canSearch?: boolean;
    /** 引用字段对应的表单 DSL 配置，用于转换为 Formily schema 进行渲染 */
    model?: {
        /** 表单控件类型 */
        type?: string;
        /** 表单控件属性 */
        props?: Record<string, unknown>;
        [key: string]: unknown;
    };
}
/**
 * 引用字段驱动类
 *
 * 实现 FieldDriver 接口，提供引用字段的完整生命周期管理，包括：
 * 创建、编辑、删除、数据水合、视图挂载等能力。
 */
export declare class LookupFieldDriver implements FieldDriver<LookupFieldConfig> {
    /**
     * 获取引用字段的元数据信息
     * 用于字段类型注册、选择面板展示等场景
     * @returns 包含字段类型标识、展示名称、分类、排序权重、图标等元信息
     */
    getMeta(): FieldMeta;
    /**
     * 获取引用字段的 UI 贡献配置
     * 定义字段在选择器面板中的展示项、创建/编辑面板组件及面板交互模式
     * @returns UI 贡献配置对象，包含 selectorItem、面板组件和面板类型
     */
    getUiContribution(): FieldUiContribution;
    /**
     * 创建引用字段的默认配置
     * 用于新建字段时初始化空白表单状态
     * @returns 所有字段为空/默认值的配置对象
     */
    createDefaultConfig(): LookupFieldConfig;
    /**
     * 校验引用字段配置的完整性
     * 依次检查字段名称、数据表选择、引用字段选择是否已填写
     * @param config - 待校验的引用字段配置
     * @returns 校验结果对象，valid 为 false 时包含 error 提示信息
     */
    validateConfig(config: LookupFieldConfig): {
        valid: boolean;
        error?: string;
    };
    /**
     * 持久化引用字段元数据（创建流程）
     *
     * 执行顺序：
     * 1. 生成或复用 columnCode 作为字段唯一标识
     * 2. 校验是否有重复引用
     * 3. 若处于 hiddenSubTable 模式，调用业务方 addFieldCallback
     * 4. 写入 DataModel 的 lookupConfig
     * 5. 发出搜索配置更新事件通知 CnAiFilter
     * 6. 记录埋点日志
     *
     * @param config - 用户在面板中填写的引用字段配置
     * @param ctx - 字段操作上下文，包含 dataModel、eventBus、services 等
     * @returns 创建成功后的字段记录，包含 id、类型、名称、配置及运行时信息
     */
    persistMeta(config: LookupFieldConfig, ctx: FieldContext): Promise<FieldRecord>;
    /**
     * 构建表格列定义并注册到 DataModel
     * 将字段记录转化为表格组件可消费的列配置对象
     * @param record - 字段记录，包含 id 和 name 等信息
     * @param ctx - 字段操作上下文，用于访问 dataModel.addColumn
     * @returns 表格列定义对象，包含 dataIndex、title、header、accessorKey、format
     */
    buildColumnDef(record: FieldRecord, ctx: FieldContext): any;
    /**
     * 将字段挂载到指定视图的列顺序中
     * 如果字段已存在于 columnOrder 则跳过，避免重复添加
     * @param record - 字段记录，record.id 用于加入列顺序数组
     * @param ctx - 字段操作上下文，ctx.viewId 指定目标视图
     */
    attachToView(record: FieldRecord, ctx: FieldContext): void;
    /**
     * 物化数据（空实现）
     * 引用字段为 passive 模式，数据由后端查找引用服务异步填充，前端无需主动物化
     */
    materializeData(): Promise<void>;
    /**
     * 更新引用字段元数据（编辑流程）
     *
     * 仅允许修改 fieldName 和 description，sourceTableId / targetFieldCode 不可变更。
     * 执行顺序：
     * 1. 获取已有配置作为不可变基准
     * 2. 校验重复引用
     * 3. 合并可编辑字段并写入 DataModel
     * 4. 发出搜索配置更新事件
     * 5. 同步更新列定义中的 title/header
     * 6. 触发远端视图同步
     * 7. 记录埋点日志
     *
     * @param columnId - 要更新的字段 columnCode 标识
     * @param config - 用户修改后的配置（仅 fieldName/description 生效）
     * @param ctx - 字段操作上下文
     * @returns 更新后的字段记录
     */
    updateMeta(columnId: string, config: LookupFieldConfig, ctx: FieldContext): Promise<FieldRecord>;
    /**
     * 删除引用字段
     *
     * 执行顺序：
     * 1. 获取已有配置用于回调参数构建
     * 2. 若处于 hiddenSubTable 模式，调用业务方 deleteFieldCallback
     * 3. 从 DataModel 中彻底移除字段（列定义、视图配置、自定义字段）
     * 4. 发出搜索配置更新事件
     * 5. 记录埋点日志
     *
     * @param columnId - 要删除的字段 columnCode 标识
     * @param ctx - 字段操作上下文
     */
    remove(columnId: string, ctx: FieldContext): Promise<void>;
    /**
     * 从持久化配置中水合（恢复）字段记录
     * 用于页面加载时从 DataModel 中读取已保存的 lookupConfig 并重建 FieldRecord
     * @param columnId - 字段的 columnCode 标识
     * @param ctx - 字段操作上下文
     * @returns 水合后的字段记录；若配置不存在则返回 undefined
     */
    hydrate(columnId: string, ctx: FieldContext): FieldRecord | undefined;
    /**
     * 判断是否应调用业务方的 add/deleteFieldCallback 回调
     * 仅在 hiddenSubTable 模式下才触发业务回调，避免非隐藏子表场景下产生副作用
     * @param ctx - 字段操作上下文，包含 lookupFieldConfig 等全局配置
     * @returns true 表示需要调用业务回调
     */
    private shouldInvokeLookupBizCallbacks;
    /**
     * 校验引用字段是否存在重复配置
     * 同一数据表的同一字段不允许被重复引用（排除自身编辑场景）
     * @param ctx - 字段操作上下文
     * @param sourceTableId - 引用的源数据表 ID
     * @param targetFieldCode - 引用的目标字段 code
     * @param selfColumnCode - 当前字段自身的 columnCode，编辑时排除自身
     * @throws 如果检测到重复引用，抛出错误提示用户
     */
    private ensureNoDuplicateLookup;
    /**
     * 从 DataModel 中彻底移除指定字段的所有痕迹
     *
     * 清理范围：
     * - 列定义（columnDefinitions）
     * - 自定义字段配置（customFields）
     * - 所有视图配置中的引用：columnOrder、hiddenColumns、filter、sort、group、colorFill
     * - 触发远端视图同步
     *
     * @param columnId - 要移除的字段 columnCode 标识
     * @param ctx - 字段操作上下文
     */
    private removeFieldFromDataModel;
}
