@sparqjs/schema-protocol 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,1678 @@
+/**
+ * 当前协议版本。正式发布前不保留旧协议兼容逻辑。
+ */
+export type SchemaVersion = '1.0';
+/**
+ * 资源的基础描述信息。
+ *
+ * 这部分主要用于页面标题、调试信息和资源定位，不参与字段或布局推导。
+ */
+export interface ResourceDescriptor {
+    /** 资源编码，例如 customer。 */
+    name: string;
+    /** 资源展示名称。 */
+    title?: string;
+    /** 资源说明。 */
+    description?: string;
+    /** 资源来源，例如 playground、database、remote。 */
+    source_type?: string;
+    /** 资源归属类型，例如 app、tenant。 */
+    owner_type?: string;
+    /** 资源归属编码。 */
+    owner_code?: string;
+}
+/**
+ * 后端下发给前端的资源协议载体。
+ */
+export interface SchemaResource {
+    /** 资源元信息。 */
+    resource?: ResourceDescriptor;
+    /** 资源字段、视图和动作协议。 */
+    schema: ResourceSchema;
+}
+/**
+ * 资源协议主体。
+ *
+ * fields 是前后端共享的基础字段协议。views 是前端布局协议，后端可以按 JSON 透传。
+ */
+export interface ResourceSchema {
+    /** 协议版本。 */
+    version: SchemaVersion;
+    /** 资源编码，应与 resource.name 保持一致。 */
+    name: string;
+    /** 资源展示名称。 */
+    title?: string;
+    /** 资源补充说明。 */
+    description?: string;
+    /** 资源记录主键字段名。缺失时 runtime 使用 id，删除、编辑、详情等动作会复用该字段取值。 */
+    primaryKey?: string;
+    /** 资源级能力开关，例如 allow_export。 */
+    capabilities?: Record<string, unknown>;
+    /** 业务状态字段和值语义配置。 */
+    state?: ResourceStateConfig;
+    /** 树形资源配置。存在该配置时，资源可使用 TreeService 管理父子结构。 */
+    tree?: ResourceTreeConfig;
+    /** 资源级索引和唯一约束契约。 */
+    constraints?: SchemaConstraints;
+    /** 资源字段定义。前端只能复用，不应写入布局语义。 */
+    fields: ResourceField[];
+    /** 前端视图配置。缺失时 runtime 可按字段能力推导默认视图。 */
+    views?: ResourceViews;
+    /** 顶层动作定义。按钮位置通过 ActionRef 引用这里的定义。 */
+    actions?: Record<string, ActionDefinition>;
+}
+/**
+ * 资源状态语义配置。
+ */
+export interface ResourceStateConfig {
+    /** 保存业务状态的字段名。 */
+    field?: string;
+    /** 普通提交时使用的默认状态值。 */
+    default_value?: unknown;
+    /** 状态值到系统语义的映射，键为实际落库值。 */
+    values?: Record<string, ResourceStateValue>;
+}
+export type ResourceStateKind = 'draft' | 'workflow_pending' | 'workflow_rejected' | 'active' | 'inactive' | 'archived' | string;
+/**
+ * 单个状态值的系统语义。
+ */
+export interface ResourceStateValue {
+    /** 系统状态语义。 */
+    kind?: ResourceStateKind;
+    /** 展示文本。 */
+    label?: string;
+}
+/**
+ * 树形资源配置。
+ */
+export interface ResourceTreeConfig {
+    /** 是否启用树形资源能力。 */
+    enabled?: boolean;
+    /** 父节点字段名。默认由后端约定为 parent_id。 */
+    parent_field?: string;
+    /** 同级排序字段名。 */
+    order_field?: string;
+    /** 树形模式。 */
+    mode?: string;
+}
+/**
+ * 资源级约束契约。
+ */
+export interface SchemaConstraints {
+    /** 普通索引契约。 */
+    indexes?: SchemaIndex[];
+    /** 唯一约束契约。 */
+    uniques?: SchemaUnique[];
+}
+/**
+ * 普通索引契约。
+ */
+export interface SchemaIndex {
+    /** 索引名。 */
+    name?: string;
+    /** 参与索引的字段名集合。 */
+    fields: string[];
+}
+/**
+ * 唯一约束契约。
+ */
+export interface SchemaUnique {
+    /** 唯一约束名。 */
+    name?: string;
+    /** 参与唯一约束的字段名集合。 */
+    fields: string[];
+}
+/**
+ * 树形资源节点。
+ */
+export interface SchemaTreeNode {
+    /** 节点主键。 */
+    id: number;
+    /** 父节点主键。 */
+    parent_id?: number;
+    /** 所属根节点主键。 */
+    root_id?: number;
+    /** 相对查询起点的深度。 */
+    depth: number;
+    /** 是否仍有直接子节点。 */
+    has_children?: boolean;
+    /** 直接子节点数量。 */
+    children_count?: number;
+    /** 从根到父节点的祖先主键路径。 */
+    ancestor_ids?: number[];
+    /** 节点业务记录。 */
+    item?: Record<string, unknown>;
+}
+/**
+ * 嵌套树形资源节点。
+ */
+export interface SchemaTreeBranch extends SchemaTreeNode {
+    /** 子节点集合。 */
+    children?: SchemaTreeBranch[];
+}
+/**
+ * 树形节点列表结果。
+ */
+export interface SchemaTreeListResult {
+    /** 命中的树节点。 */
+    items: SchemaTreeNode[];
+}
+/**
+ * 嵌套树查询结果。
+ */
+export interface SchemaTreeResult {
+    /** 命中的树分支。 */
+    items: SchemaTreeBranch[];
+}
+/**
+ * 树形祖先路径结果。
+ */
+export interface SchemaTreeAncestorsResult {
+    /** 从根到当前节点的路径。 */
+    items: SchemaTreeNode[];
+}
+/**
+ * 树形移动结果。
+ */
+export interface SchemaTreeMoveResult {
+    /** 移动后的节点。 */
+    node: SchemaTreeNode;
+}
+/**
+ * 树形索引重建结果。
+ */
+export interface SchemaTreeRebuildResult {
+    /** 资源编码。 */
+    resource: string;
+    /** 参与重建的节点数量。 */
+    count: number;
+}
+/**
+ * 审计记录操作人。
+ */
+export interface AuditActor {
+    /** 操作人主键。 */
+    id?: string | number;
+    /** 操作人展示名称。 */
+    name?: string;
+    /** 操作人头像。 */
+    avatar?: string;
+}
+/**
+ * 审计字段变更项。
+ */
+export interface AuditChange {
+    /** 字段名。 */
+    field: string;
+    /** 字段展示标题。 */
+    label?: string;
+    /** 修改前的值。 */
+    before?: unknown;
+    /** 修改后的值。 */
+    after?: unknown;
+}
+/**
+ * 单条审计事件。
+ *
+ * 审计是资源运行时内置能力，不需要写入 ResourceSchema；该结构只约定前后端审计接口的返回载荷。
+ */
+export interface AuditEntry {
+    /** 审计事件主键。 */
+    id: string | number;
+    /** 审计类型，例如 create、update、delete、restore。 */
+    type: 'create' | 'update' | 'delete' | 'restore' | string;
+    /** 审计标题。 */
+    title?: string;
+    /** 审计摘要。 */
+    summary?: string;
+    /** 操作人。 */
+    actor?: AuditActor;
+    /** 发生时间。 */
+    occurred_at: string;
+    /** 字段变更明细。 */
+    changes?: AuditChange[];
+    /** 附加信息。 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 审计列表结果。
+ */
+export interface AuditListResult {
+    /** 当前页审计事件。 */
+    results: AuditEntry[];
+    /** 总数。 */
+    total?: number;
+    /** 页码。 */
+    page?: number;
+    /** 每页数量。 */
+    pageSize?: number;
+    /** 是否还有更多。 */
+    hasMore?: boolean;
+}
+/**
+ * 字段动态值表达式类型。
+ */
+export type FieldValueExpressionType = 'literal' | 'now' | 'today' | 'start_of_day' | 'end_of_day' | 'start_of_month' | 'end_of_month' | string;
+/**
+ * 时间类动态值表达式偏移量。
+ */
+export interface FieldValueExpressionOffset {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+/**
+ * 字段动态值表达式。
+ *
+ * 当前用于 default_expr 和 validation.value_expr。后端可以透传，前端只执行受支持的表达式类型。
+ */
+export interface FieldValueExpression {
+    /** 表达式类型，例如 now、today、literal。 */
+    type: FieldValueExpressionType;
+    /** literal 等表达式使用的静态值。 */
+    value?: unknown;
+    /** 时间类表达式的偏移量。 */
+    offset?: FieldValueExpressionOffset;
+    /** 输出格式，缺失时由字段类型推导。 */
+    format?: 'date' | 'datetime' | 'time' | 'timestamp' | string;
+    /** 时间类表达式使用的时区。第一阶段由消费端决定支持范围。 */
+    timezone?: string;
+}
+/**
+ * 字段级校验规则类型。
+ */
+export type FieldValidationRuleType = 'required' | 'max_length' | 'min_length' | 'min' | 'max' | 'pattern' | 'format' | 'complexity' | 'range' | string;
+/** range 校验使用的固定跨度单位。日期范围使用 day，时间范围使用 minute。 */
+export type RangeValidationSpanUnit = 'day' | 'minute';
+/** JSON 二元范围值的边界、顺序和最大跨度参数。 */
+export interface RangeValidationParams {
+    /** 两个端点共同使用的最小边界。 */
+    min?: string;
+    /** 两个端点共同使用的最大边界。 */
+    max?: string;
+    /** 起点不得晚于终点；当前协议固定为 true。 */
+    ordered: true;
+    /** 允许的最大实际跨度，相同端点的跨度为 0。 */
+    max_span?: number;
+    /** 日期范围固定为 day，时间范围固定为 minute。 */
+    span_unit: RangeValidationSpanUnit;
+}
+/**
+ * 字段级校验规则。
+ *
+ * value 是规则主参数，params 用于后续承载扩展参数；动态表达式后续单独扩展，不复用静态 value。
+ */
+export interface FieldValidationRule {
+    /** 校验规则类型。 */
+    type: FieldValidationRuleType;
+    /** 校验规则静态主参数。 */
+    value?: unknown;
+    /** 校验规则动态主参数表达式。 */
+    value_expr?: FieldValueExpression;
+    /** 命中规则时的提示信息。 */
+    message?: string;
+    /** 规则启用条件。缺失时始终启用。 */
+    when?: Condition;
+    /** 校验规则附加参数。 */
+    params?: Record<string, unknown>;
+}
+/**
+ * 资源字段投影。
+ *
+ * 这是后端主要消费的共享字段协议。前端根据这些信息推导表单项、表格列、搜索项和详情展示。
+ */
+export interface ResourceField {
+    /** 字段投影唯一标识。 */
+    id?: number;
+    /** 所属资源主体标识。 */
+    resource_id?: number;
+    /** 来源版本标识。 */
+    version_id?: number;
+    /** 字段名，也是表单值和接口数据中的默认 key。 */
+    name: string;
+    /** 字段排序值。默认视图推导时按该值升序排列。 */
+    sort?: number;
+    /** 字段类型，例如 text、number、select、relation。 */
+    type: string;
+    /** 字段展示标题。 */
+    label: string;
+    /** 创建记录时的静态默认值。只在新增表单初始化时使用，编辑表单以记录数据为准。 */
+    default?: unknown;
+    /** 创建记录时的动态默认值表达式。静态 default 优先于 default_expr。 */
+    default_expr?: FieldValueExpression;
+    /** 字段值计算表达式。用于由其他字段、上下文或受限函数派生当前字段值。 */
+    computed_expr?: ValueExpression;
+    /** 计算触发源。缺失时消费端可从 computed_expr 依赖推导；第一阶段建议显式声明字段名。 */
+    computed_triggers?: string[];
+    /** 字段级校验规则。前端可用于基础表单校验和控件限制推导，后端仍是最终校验边界。 */
+    validation?: FieldValidationRule[];
+    /**
+     * 预留的物理列名映射。
+     *
+     * 当前阶段持久化字段默认等于 name，前端渲染、表单数据和查询条件都应使用 name。
+     * 后续接入遗留表或字段改名迁移时，该字段才可能与 name 不同。
+     */
+    column_name?: string;
+    /** 是否持久化。 */
+    persisted?: boolean;
+    /** 是否支持多值。多选、标签、附件等字段会用到。 */
+    multiple?: boolean;
+    /** 是否必填。表单校验会复用该值。 */
+    required?: boolean;
+    /** 是否只读。表单字段默认进入只读状态。 */
+    readonly?: boolean;
+    /** 是否禁用。表单字段默认进入禁用状态。 */
+    disabled?: boolean;
+    /** 是否默认出现在列表中。 */
+    listable?: boolean;
+    /** 是否默认出现在表单中。 */
+    formable?: boolean;
+    /** 是否默认出现在搜索区域中。 */
+    searchable?: boolean;
+    /** 是否支持列表排序。 */
+    sortable?: boolean;
+    /** 字段值引用的目标资源；候选查询配置不应重复声明这些稳定语义。 */
+    reference?: FieldReferenceConfig;
+    /** 字段候选项来源和取值策略。 */
+    options?: FieldOptionsConfig;
+    /** 字段扩展信息，例如生成器、关联资源、密文字段等后端字段能力扩展。 */
+    extensions?: Record<string, unknown>;
+    /** 创建时间。 */
+    created_at?: string;
+    /** 最后更新时间。 */
+    updated_at?: string;
+}
+/** 字段值对另一个资源字段的稳定引用。 */
+export interface FieldReferenceConfig {
+    /** 目标资源编码。 */
+    resource: string;
+    /** 目标资源中作为当前字段值的字段名。 */
+    value_field: string;
+    /** 目标资源中用于回显的字段名。 */
+    label_field: string;
+}
+/**
+ * 资源视图集合。
+ *
+ * group 缺失表示需要时可自动推导 default；group=false 表示整类视图禁用。
+ */
+export interface ResourceViews {
+    /** 默认资源页简写，等价于 pages.default。 */
+    page?: false | PageView;
+    /** 资源页组合配置。 */
+    pages?: false | Record<string, PageView>;
+    /** 默认表单视图简写，等价于 forms.default。 */
+    form?: false | FormView;
+    /** 表单视图集合。 */
+    forms?: false | Record<string, false | FormView>;
+    /** 默认表格视图简写，等价于 tables.default。 */
+    table?: false | TableView;
+    /** 表格视图集合。 */
+    tables?: false | Record<string, false | TableView>;
+    /** 默认搜索视图简写，等价于 searches.default。 */
+    search?: false | SearchView;
+    /** 搜索视图集合。 */
+    searches?: false | Record<string, false | SearchView>;
+    /** 默认详情视图简写，等价于 details.default。 */
+    detail?: false | DetailView;
+    /** 详情视图集合。 */
+    details?: false | Record<string, false | DetailView>;
+}
+/**
+ * 资源页组合配置。
+ *
+ * mode=page 时，runtime 根据该配置组合 search、table、form 和 detail。
+ */
+export interface PageView {
+    /** 使用的搜索视图名，默认可取 default。 */
+    search?: string;
+    /** 使用的表格视图名，默认可取 default。 */
+    table?: string;
+    /** 新增动作使用的表单视图名。 */
+    createForm?: string;
+    /** 编辑动作使用的表单视图名。 */
+    updateForm?: string;
+    /** 查看动作使用的详情视图名。 */
+    detail?: string;
+    /** 页面级附加属性，由 renderer 或业务适配层解释。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 外层包装器类型。
+ */
+export type WrapperType = 'default' | 'card' | 'dialog' | 'drawer' | 'panel' | string;
+/**
+ * 表单或详情的外层包装配置。
+ *
+ * 独立渲染时通常使用 default/card/panel；从列表动作打开时通常使用 dialog/drawer。
+ */
+export interface WrapperConfig {
+    /** 包装器类型。 */
+    type?: WrapperType;
+    /** 包装器属性，例如宽度、标题对齐、遮罩行为。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 底部操作区配置。
+ *
+ * false 表示明确隐藏 footer；未设置时由 runtime 根据上下文生成默认按钮。
+ */
+export type FooterConfig = false | {
+    /** footer 容器属性。 */
+    props?: Record<string, unknown>;
+    /** 显式按钮列表。缺失时 runtime 生成 submit/reset 或 submit/cancel。 */
+    actions?: ActionRef[];
+};
+/**
+ * 表单打开前的数据加载方式。
+ *
+ * create 场景通常不加载数据；edit 场景默认通过 detail 接口取得完整编辑数据。
+ */
+export interface FormLoadConfig {
+    /** 数据来源。none 不填充，record 使用当前行，detail 请求详情接口。 */
+    type: 'none' | 'record' | 'detail';
+    /** 请求 detail 时使用的 view 名称，缺失时使用当前 form view 名称。 */
+    view?: string;
+    /** 请求 detail 时携带的附加参数。 */
+    params?: Record<string, unknown>;
+}
+/**
+ * 表单视图。
+ *
+ * Form 只描述布局和默认展示配置。创建、编辑、关闭和刷新由 action 与渲染上下文决定。
+ */
+export interface FormView {
+    /** 表单标题。 */
+    title?: string;
+    /** 表单说明。 */
+    help?: string;
+    /** 表单外层包装配置。 */
+    wrapper?: WrapperConfig;
+    /** 表单底部操作区。false 表示隐藏。 */
+    footer?: FooterConfig;
+    /** 打开表单前的数据加载配置。 */
+    load?: FormLoadConfig;
+    span?: number;
+    gap?: number;
+    /** 字段名简写。后端导出轻量 views 时可用该字段表达字段顺序。 */
+    fields?: string[];
+    /** 表单布局节点。 */
+    children?: ViewNode[];
+    /** 表单级附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 详情视图。
+ *
+ * Detail 是独立展示协议，不等同于 readonly form。
+ */
+export interface DetailView {
+    /** 详情标题。 */
+    title?: string;
+    /** 详情说明。 */
+    help?: string;
+    /** 详情外层包装配置。 */
+    wrapper?: WrapperConfig;
+    span?: number;
+    gap?: number;
+    /** 字段名简写。后端导出轻量 views 时可用该字段表达字段顺序。 */
+    fields?: string[];
+    /** 详情布局节点。 */
+    children?: ViewNode[];
+    /** 详情级附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 字段可选值来源模式。
+ */
+export type FieldOptionsMode = 'static' | 'dictionary' | 'reference' | 'remote';
+/** 候选值约束策略。closed 只接受候选来源中的值，open 允许自定义值。 */
+export type FieldOptionValuePolicy = 'closed' | 'open';
+/**
+ * 字段可选值配置。
+ *
+ * `mode=static` 时使用 `items`；`mode=dictionary` 时由数据字典服务按 code 加载；
+ * `mode=reference` 时根据字段 reference 加载目标资源候选项。
+ */
+export interface FieldOptionsConfig {
+    /** 选项来源模式。 */
+    mode: FieldOptionsMode;
+    /** 候选值约束策略；缺失时按 closed 处理。 */
+    value_policy?: FieldOptionValuePolicy;
+    /** 静态选项列表，通常在 mode=static 时使用。 */
+    items?: OptionItem[];
+    /** 数据字典来源，通常在 mode=dictionary 时使用。 */
+    dictionary?: DictionaryOptionSourceConfig;
+    /** 资源引用候选查询配置，通常在 mode=reference 时使用。 */
+    reference?: ReferenceOptionQueryConfig;
+    /** 远程选项配置，通常在 mode=remote 时交给 DataAdapter 或 hooks 解析。 */
+    remote?: RemoteDataSourceConfig;
+}
+/** 数据字典候选项来源。 */
+export interface DictionaryOptionSourceConfig {
+    /** 数据字典模块中的稳定字典编码。 */
+    code: string;
+}
+/**
+ * 候选项过滤规则。
+ */
+export interface FieldOptionFilterConfig {
+    /** 过滤字段名。 */
+    field: string;
+    /** 过滤操作符。 */
+    operator?: string;
+    /** 固定过滤值。 */
+    value?: unknown;
+    /** 过滤值来源字段或上下文键，例如 form.category_id。 */
+    from?: string;
+}
+/**
+ * 候选项排序规则。
+ */
+export interface FieldOptionSortConfig {
+    /** 排序字段名。 */
+    field: string;
+    /** 排序方向。 */
+    order?: 'asc' | 'desc' | string;
+}
+/**
+ * 资源引用候选项查询配置。
+ */
+export interface ReferenceOptionQueryConfig {
+    /** 搜索字段。 */
+    search_field?: string;
+    /** 禁用状态字段。 */
+    disabled_field?: string;
+    /** 父级字段。树形关联选项会用到。 */
+    parent_field?: string;
+    /** 候选项分组稳定值字段。 */
+    group_field?: string;
+    /** 候选项分组展示名称字段。 */
+    group_label_field?: string;
+    /** 候选项补充说明字段。 */
+    description_field?: string;
+    /** 需要随选项一并返回的元信息字段。 */
+    meta_fields?: string[];
+    /** 固定过滤条件。 */
+    filters?: FieldOptionFilterConfig[];
+    /** 固定排序配置。 */
+    sorts?: FieldOptionSortConfig[];
+    /** 单次查询数量。 */
+    limit?: number;
+    /** 加载模式。paged 表示搜索分页，tree 表示树形懒加载，all 表示显式全量。 */
+    load_mode?: 'paged' | 'tree' | 'all';
+    /** 附加参数。 */
+    params?: Record<string, unknown>;
+}
+/**
+ * 远程选项来源配置。
+ */
+export interface RemoteDataSourceConfig {
+    /** 远程候选项来源。provider 表示后端托管，client 表示前端直连 URL。 */
+    target?: 'provider' | 'client' | string;
+    /** 前端直连候选项接口地址，仅 target=client 时使用。 */
+    url?: string;
+    /** 远程能力提供者。 */
+    provider?: string;
+    /** 远程能力键。保留给前端适配层组合 provider/key。 */
+    key?: string;
+    /** 远程请求方法。 */
+    method?: string;
+    /** 选项值字段。 */
+    value_field?: string;
+    /** 选项标签字段。 */
+    label_field?: string;
+    /** 禁用状态字段。 */
+    disabled_field?: string;
+    /** 父级字段。树形远程选项会用到。 */
+    parent_field?: string;
+    /** 候选项分组稳定值字段。 */
+    group_field?: string;
+    /** 候选项分组展示名称字段。 */
+    group_label_field?: string;
+    /** 候选项补充说明字段。 */
+    description_field?: string;
+    /** 需要随选项一并返回的元信息字段。 */
+    meta_fields?: string[];
+    /** 远程关键字查询参数名。 */
+    keyword_param?: string;
+    /** 固定过滤条件。 */
+    filters?: FieldOptionFilterConfig[];
+    /** 固定排序配置。 */
+    sorts?: FieldOptionSortConfig[];
+    /** 单次查询数量。 */
+    limit?: number;
+    /** 加载模式。paged 表示搜索分页，tree 表示树形懒加载，all 表示显式全量。 */
+    load_mode?: 'paged' | 'tree' | 'all';
+    /** 请求参数。 */
+    params?: Record<string, unknown>;
+}
+/**
+ * 字段组件回写策略。
+ *
+ * always 表示每次命中事件都覆盖目标字段；empty 表示仅在目标字段为空时写入。
+ * 当前空值由消费端按 undefined、null、空字符串和空数组判断。
+ */
+export type WriteBackStrategy = 'always' | 'empty';
+/**
+ * 字段组件联动回写规则。
+ *
+ * 该规则属于前端 UI 层协议，只在组件主动提供变更上下文时生效。
+ * 第一阶段 from 仅约定为简单路径，例如 value、asset.id、asset.metadata.duration、assets.0.id。
+ * 第一阶段 to 仅约定为当前表单内顶层字段名，不支持跨资源、跨表单或嵌套路径写入。
+ */
+export interface WriteBackRule {
+    /** 从组件变更上下文读取值的路径。 */
+    from: string;
+    /** 写入当前表单的目标字段名。 */
+    to: string;
+    /** 写入策略。缺失时按 always 处理。 */
+    strategy?: WriteBackStrategy;
+    /** 触发事件列表。缺失或空数组表示不限制事件。 */
+    events?: string[];
+}
+/**
+ * 组件变更上下文。
+ *
+ * 不同组件暴露的上下文不同。基础组件通常只暴露 value；资源组件会额外暴露 asset、assets 和资源事件。
+ */
+export interface ComponentChangeContext {
+    /** 当前组件写入主字段的最终值。 */
+    value?: unknown;
+    /** 组件变更事件，例如 upload、pick、change。 */
+    event?: string;
+    /** 组件自定义上下文。 */
+    [key: string]: unknown;
+}
+/**
+ * 通用节点 props。
+ *
+ * props 允许组件透传 UI 库差异化配置，因此协议仅固定跨组件稳定字段。
+ */
+export interface ViewNodeProps {
+    /** 字段联动回写规则。仅支持提供变更上下文的组件。 */
+    writeBack?: WriteBackRule[];
+    /** 允许组件继续扩展自身 props。 */
+    [key: string]: unknown;
+}
+/**
+ * 资源类型。
+ */
+export type AssetType = 'image' | 'video' | 'audio' | 'file' | string;
+/**
+ * 资源组件值模式。
+ *
+ * url 表示提交资源 URL；id 表示提交资源 ID；asset 表示提交完整资源对象。
+ */
+export type AssetValueMode = 'url' | 'id' | 'asset';
+/**
+ * 资源元信息。
+ *
+ * 媒体解析结果、转码信息和业务扩展信息都放在 metadata 中。后端返回值是最终可信来源。
+ */
+export interface AssetMetadata {
+    /** 音视频时长，单位秒。 */
+    duration?: number;
+    /** 封面资源 ID。 */
+    coverAssetId?: string | number;
+    /** 封面 URL。 */
+    coverUrl?: string;
+    /** 媒体宽度。 */
+    width?: number;
+    /** 媒体高度。 */
+    height?: number;
+    /** 编码格式。 */
+    codec?: string;
+    /** 码率。 */
+    bitrate?: number;
+    /** 业务扩展元信息。 */
+    [key: string]: unknown;
+}
+/**
+ * 资源对象。
+ */
+export interface AssetDescriptor {
+    /** 资源 ID。valueMode=id 时必须存在，否则消费端应忽略该资源并输出错误日志。 */
+    id?: string | number;
+    /** 资源可访问 URL。 */
+    url: string;
+    /** 文件名。 */
+    name?: string;
+    /** 展示标题。 */
+    title?: string;
+    /** MIME 类型。 */
+    mime?: string;
+    /** 文件大小，单位字节。 */
+    size?: number;
+    /** 资源类型。 */
+    type?: AssetType;
+    /** 资源元信息。 */
+    metadata?: AssetMetadata;
+}
+/**
+ * 资源上传/选择组件 props。
+ */
+export interface AssetComponentProps extends ViewNodeProps {
+    /** 输出值模式，默认 url。 */
+    valueMode?: AssetValueMode;
+    /** 文件 accept 限制，例如 image/*、video/*、.pdf。 */
+    accept?: string;
+    /** 是否允许多选。 */
+    multiple?: boolean;
+    /** 数量限制。0 表示不限制。 */
+    limit?: number;
+    /** 单个文件最大字节数。0 或缺失表示不增加前端大小限制。 */
+    maxSize?: number;
+    /** 是否允许编辑资源标题。该配置只影响 UI，不决定输出值模式。 */
+    editableTitle?: boolean;
+    /** editableTitle 的兼容别名。 */
+    editable?: boolean;
+    /** 上传按钮文案。 */
+    uploadText?: string;
+    /** 当前字段使用的专用上传地址；配置后不经过资源中心，也不开放已有资源选择。 */
+    uploadEndpoint?: string;
+    /** 资源选择按钮文案。 */
+    pickText?: string;
+}
+/**
+ * 富文本工具栏模式。
+ */
+export type RichTextToolbarMode = 'simple' | 'default' | 'full' | 'custom';
+/**
+ * 富文本工具栏吸顶边界。
+ */
+export type RichTextToolbarBoundary = 'field' | 'form' | 'page' | string;
+/**
+ * 富文本工具栏配置。
+ *
+ * 不同编辑器可以将该通用配置映射到自身工具栏能力；无法识别的工具项由具体编辑器适配器忽略。
+ */
+export interface RichTextToolbarConfig {
+    /** 工具栏预设模式。 */
+    mode?: RichTextToolbarMode;
+    /** 是否启用工具栏吸顶。 */
+    sticky?: boolean;
+    /** 吸顶偏移量。 */
+    stickyOffset?: number | string;
+    /** 吸顶边界。第一阶段主要由具体编辑器适配器解释。 */
+    stickyBoundary?: RichTextToolbarBoundary;
+    /** 显式工具项。 */
+    items?: string[];
+    /** 从预设或显式工具项中排除的工具项。 */
+    exclude?: string[];
+}
+/**
+ * 富文本组件 props。
+ */
+export interface RichTextComponentProps extends ViewNodeProps {
+    /** 编辑器实现标识，例如 markdown、tinymce、wang、editorjs。 */
+    editor?: string;
+    /** 占位提示。 */
+    placeholder?: string;
+    /** 编辑器高度。 */
+    height?: number | string;
+    /** 加载提示。 */
+    loadingText?: string;
+    /** 工具栏配置。 */
+    toolbar?: RichTextToolbarConfig;
+    /** 透传给具体编辑器适配器的配置。 */
+    editorProps?: Record<string, unknown>;
+}
+/**
+ * 节点静态插槽内容。
+ *
+ * 第一阶段只支持纯文本和图标，不支持任意组件、按钮或事件处理。复杂组合输入应使用自定义组件实现。
+ */
+export type ViewNodeSlotContent = {
+    /** 纯文本插槽。 */
+    type: 'text';
+    /** 插槽文本。 */
+    text: string;
+} | {
+    /** 图标插槽。 */
+    type: 'icon';
+    /** 图标 key，由具体 UI adapter 解析。 */
+    icon: string;
+};
+/**
+ * 节点静态插槽。
+ *
+ * 当前主要面向单行输入类组件。组件或 UI adapter 不支持时应忽略。
+ */
+export interface ViewNodeSlots {
+    /** 输入框内部前缀。 */
+    prefix?: ViewNodeSlotContent;
+    /** 输入框内部后缀。 */
+    suffix?: ViewNodeSlotContent;
+    /** 输入框外部前置内容。 */
+    prepend?: ViewNodeSlotContent;
+    /** 输入框外部后置内容。 */
+    append?: ViewNodeSlotContent;
+}
+/**
+ * 嵌入视图数据绑定。
+ *
+ * form-array 表示父表单 values 中的数组字段；relation-list 表示父资源关联的完整子资源列表。
+ */
+export type ViewNodeBinding = FormArrayBinding | RelationListBinding;
+/**
+ * 父表单数组绑定。
+ *
+ * 适合 JSON 字段随父表单一起保存的轻量明细配置。
+ */
+export interface FormArrayBinding {
+    /** 绑定类型。 */
+    type: 'form-array';
+    /** 父表单 values 中的数组字段名。 */
+    field: string;
+}
+/**
+ * 子资源关联列表绑定。
+ *
+ * 适合订单明细、活动商品、角色权限等完整资源或中间表关系。
+ */
+export interface RelationListBinding {
+    /** 绑定类型。 */
+    type: 'relation-list';
+    /** 父资源上的关系名，例如 items、products、permissions。 */
+    relation: string;
+    /** 子资源或目标资源编码。也可由 ViewNode.resource 提供，二者存在时应保持一致。 */
+    resource?: string;
+    /** 父资源主键字段。缺失时使用父资源 primaryKey。 */
+    parentKey?: string;
+    /** 关系类型。缺失时按 has-many 处理。 */
+    relationType?: 'has-many' | 'many-to-many' | string;
+    /** has-many 关系下子资源指向父资源的外键字段。 */
+    foreignKey?: string;
+    /** many-to-many 或 through 关系配置。 */
+    through?: RelationThroughBinding;
+    /** 是否要求父记录已存在。完整资源模式建议默认 true。 */
+    requireParent?: boolean;
+    /** 父记录不存在时的展示策略。 */
+    whenParentMissing?: 'disabled' | 'hidden' | 'readonly';
+    /** 子列表查询配置。 */
+    query?: RelationListQueryConfig;
+    /** 子列表分页配置。 */
+    pagination?: RelationListPaginationConfig;
+    /** 子资源操作后的默认刷新策略。 */
+    refresh?: RelationListRefreshConfig;
+    /** 子资源操作配置。 */
+    operations?: RelationListOperationsConfig;
+}
+/**
+ * 中间表关系配置。
+ */
+export interface RelationThroughBinding {
+    /** 中间资源编码，例如 campaign_product。 */
+    resource: string;
+    /** 中间资源指向父资源的字段，例如 campaign_id。 */
+    parentForeignKey: string;
+    /** 中间资源指向目标资源的字段，例如 product_id。 */
+    targetForeignKey: string;
+    /** 目标资源主键字段，缺失时使用目标资源 primaryKey。 */
+    targetKey?: string;
+    /** 是否展示或编辑中间表字段。 */
+    exposeThroughFields?: boolean;
+    /** 需要展示或编辑的中间表字段。 */
+    throughFields?: string[];
+}
+/**
+ * 子资源列表查询配置。
+ */
+export interface RelationListQueryConfig {
+    /** 是否自动附加 foreignKey = parent[parentKey] 过滤。默认 true。 */
+    inheritParentFilter?: boolean;
+    /** 固定请求参数。 */
+    params?: Record<string, unknown>;
+    /** 固定过滤条件。 */
+    filters?: FieldOptionFilterConfig[];
+    /** 默认排序。 */
+    sorts?: FieldOptionSortConfig[];
+}
+/**
+ * 子资源列表分页配置。
+ */
+export interface RelationListPaginationConfig {
+    /** 是否启用分页。 */
+    enabled?: boolean;
+    /** 默认每页条数。 */
+    pageSize?: number;
+}
+/**
+ * 子资源列表刷新策略。
+ */
+export interface RelationListRefreshConfig {
+    /** 新增后刷新策略。 */
+    afterCreate?: RelationListRefreshMode;
+    /** 更新后刷新策略。 */
+    afterUpdate?: RelationListRefreshMode;
+    /** 删除后刷新策略。 */
+    afterDelete?: RelationListRefreshMode;
+    /** 操作成功后是否刷新父详情，用于父资源汇总字段。 */
+    parent?: boolean;
+}
+/**
+ * 子资源列表刷新模式。
+ */
+export type RelationListRefreshMode = 'reload-current' | 'reload-first' | 'none';
+/**
+ * 子资源列表操作集合。
+ */
+export interface RelationListOperationsConfig {
+    /** 创建新的目标资源并建立关系。 */
+    create?: RelationListOperationConfig;
+    /** 选择已有目标资源并建立关系。 */
+    attach?: RelationListOperationConfig;
+    /** 编辑目标资源或关系字段。 */
+    update?: RelationListOperationConfig;
+    /** 只解除关系，不删除目标资源。 */
+    detach?: RelationListOperationConfig;
+    /** 删除目标资源。 */
+    delete?: RelationListOperationConfig;
+}
+/**
+ * 子资源列表操作配置。
+ */
+export interface RelationListOperationConfig {
+    /** 是否启用该操作。操作配置存在时默认 true；未配置该操作时不开放。 */
+    enabled?: boolean;
+    /** 关系操作按钮文案。缺失时使用内置动作文案。 */
+    title?: string;
+    /** 关系操作按钮图标。 */
+    icon?: string;
+    /** 关系操作按钮类型。 */
+    type?: string;
+    /** 关系操作执行前确认。delete/detach 缺失时使用内置确认配置。 */
+    confirm?: ConfirmConfig;
+    /** 关系操作按钮附加属性。 */
+    props?: Record<string, unknown>;
+    /** 按钮位置。缺失时 create/attach 使用 toolbar，其余操作使用 row。 */
+    placement?: RelationListOperationPlacement;
+    /** 点击按钮后的输入收集方式。缺失时按关系操作语义推导。 */
+    interaction?: RelationListOperationInteraction;
+    /** 输入准备完成后的数据执行方式。缺失时使用资源 CRUD。 */
+    execution?: RelationListOperationExecution;
+    /** 操作成功后的刷新策略，优先级高于 binding.refresh。 */
+    refresh?: RelationListRefreshMode;
+    /** 操作成功后是否刷新父详情。 */
+    refreshParent?: boolean;
+}
+/** 关系操作按钮位置。 */
+export type RelationListOperationPlacement = 'toolbar' | 'row';
+/** 关系操作交互方式。 */
+export type RelationListOperationInteraction = RelationListFormInteraction | RelationListSelectionInteraction | RelationListDirectInteraction | RelationListHandlerInteraction;
+/** 通过目标资源表单收集操作输入。 */
+export interface RelationListFormInteraction {
+    type: 'form';
+    /** 目标资源 Form View。 */
+    form?: string;
+    /** 表单初始状态。create 使用默认值，edit 使用当前行记录。 */
+    mode?: 'create' | 'edit';
+}
+/** 通过目标资源表格选择操作对象。 */
+export interface RelationListSelectionInteraction {
+    type: 'selection';
+    /** 目标资源 Table View。 */
+    table?: string;
+    /** 是否允许一次选择多条资源。默认 true。 */
+    multiple?: boolean;
+    /** 候选数据范围。attach 默认 unassigned，其余操作默认 related。 */
+    source?: 'related' | 'unassigned' | 'all';
+}
+/** 点击按钮后不再收集输入，直接执行操作。 */
+export interface RelationListDirectInteraction {
+    type: 'direct';
+}
+/** 将完整前端交互委托给宿主 onAction 或已注册的 session action handler。 */
+export interface RelationListHandlerInteraction {
+    type: 'handler';
+    /** 前端交互处理标识。 */
+    handler: string;
+}
+/** 关系操作最终执行方式。 */
+export type RelationListOperationExecution = RelationListResourceExecution | RelationListActionExecution;
+/** 使用关系语义对应的资源 CRUD。 */
+export interface RelationListResourceExecution {
+    type: 'resource';
+}
+/** 使用 DataAdapter.executeAction 执行业务动作。 */
+export interface RelationListActionExecution {
+    type: 'action';
+    /** 业务 action key，例如 order_item.attachExisting。 */
+    action: string;
+}
+/**
+ * 布局节点类型。
+ */
+export type ViewNodeType = 'field' | 'group' | 'section' | 'card' | 'collapse' | 'collapse-item' | 'grid' | 'row' | 'col' | 'tabs' | 'tab' | 'divider' | 'custom' | 'view';
+/**
+ * 表单和详情共用的布局节点。
+ *
+ * field 节点通过 field 引用 ResourceField；view 节点用于在当前布局中嵌入 table/form/detail/search。
+ */
+export interface ViewNode {
+    /** 节点唯一标识。设计器和嵌套 scope 会用到。 */
+    id?: string;
+    /** 节点运行名称。tab 等需要稳定组件 name 的节点优先使用该值；缺失时可退回 id。 */
+    name?: string;
+    /** 节点类型。 */
+    type: ViewNodeType;
+    /** 字段名。仅 field 节点使用。 */
+    field?: string;
+    /** 当前节点展示标题。不会修改 ResourceField.label。 */
+    title?: string;
+    /** 字段节点标题旁的补充提示。由 UI adapter 通过可聚焦的提示入口展示。 */
+    tip?: string;
+    /** 当前节点辅助说明。常用于字段说明或区域说明。 */
+    help?: string;
+    /** 逻辑组件 key，例如 rich-text、status-tag、custom-card。 */
+    component?: string;
+    /** 嵌入视图的渲染模式。仅 view 节点使用。 */
+    mode?: RenderMode;
+    /** 嵌入视图名，例如 contacts。仅 view 节点使用。 */
+    view?: string;
+    /** 嵌入外部资源编码。第一阶段可先不实现。 */
+    resource?: string;
+    /** 栅格跨度。默认由 renderer 决定。 */
+    span?: number;
+    /** 子节点间距。 */
+    gap?: number;
+    /** 节点附加属性。组件协议固定字段见 ViewNodeProps，具体组件仍可扩展自身 props。 */
+    props?: ViewNodeProps;
+    /** 节点静态插槽。第一阶段主要由 text/password 等单行输入类组件消费。 */
+    slots?: ViewNodeSlots;
+    /** 嵌入视图数据绑定。主要用于 form-array 和 relation-list 这类表单内嵌列表。 */
+    binding?: ViewNodeBinding;
+    /** 节点 CSS class。 */
+    className?: string;
+    /** 节点内联样式。只建议放少量静态样式。 */
+    style?: Record<string, string | number>;
+    /** 节点专属数据源。常用于覆盖字段默认选项来源。 */
+    dataSource?: DataSourceConfig;
+    /** 子节点。布局容器、card、tab 和 custom 容器会使用。 */
+    children?: ViewNode[];
+    /** 显示条件。条件不满足时节点不渲染。 */
+    show_when?: Condition;
+    /** 禁用条件。主要用于 field 节点。 */
+    disabled_when?: Condition;
+    /** 只读条件。主要用于 field 节点。 */
+    readonly_when?: Condition;
+}
+/**
+ * 表格视图。
+ */
+export interface TableView {
+    /** 表格标题。 */
+    title?: string;
+    /** 表格说明。 */
+    help?: string;
+    /** 表格数据模式。tree 表示使用资源树接口加载根节点和子节点。 */
+    mode?: 'list' | 'tree' | string;
+    /** 树形表格展示配置，仅 mode=tree 时生效。 */
+    tree?: TableTreeConfig;
+    /** 序号列配置。true 使用默认序号列，false 不显示。 */
+    index?: boolean | TableIndexConfig;
+    /** 选择列配置。false 表示不显示选择列。 */
+    selection?: false | TableSelectionConfig;
+    /** 顶部工具栏。false 表示不显示工具栏。 */
+    toolbar?: false | TableToolbarConfig;
+    /** 字段名简写。后端导出轻量 views 时可用该字段表达列顺序。 */
+    fields?: string[];
+    /** 表格列。缺失时按 listable 字段推导。 */
+    columns?: TableColumn[];
+    /** 行操作列。false 表示不显示操作列。数组表示只配置 actions。 */
+    operate?: false | ActionRef[] | TableOperateConfig;
+    /** 分页配置。true 使用默认分页，false 不显示分页。 */
+    pagination?: boolean | TablePaginationConfig;
+    /** 表格编辑配置。第一阶段主要用于 relation-list 的行内编辑声明。 */
+    editing?: TableEditingConfig;
+    /** 表格级附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 树形表格展示配置。
+ */
+export interface TableTreeConfig {
+    /** 默认展开策略。all 表示一次性加载完整树；level/keys 表示在懒加载模式下展开指定范围。 */
+    default_expand?: 'none' | 'level' | 'keys' | 'all' | string;
+    /** default_expand=level 时默认展开到的层级。 */
+    expand_level?: number;
+    /** default_expand=keys 时默认展开的节点主键。 */
+    expanded_keys?: Array<string | number>;
+    /** 承载层级缩进和展开控件的列 id 或字段名。缺失时使用第一数据列。 */
+    expand_column?: string;
+}
+/**
+ * 表格序号列配置。
+ */
+export interface TableIndexConfig {
+    /** 序号列表头。 */
+    title?: string;
+    /** 序号列宽度。 */
+    width?: number;
+    /** 固定方向。 */
+    fixed?: 'left' | 'right';
+}
+/**
+ * 表格选择列配置。
+ */
+export interface TableSelectionConfig {
+    /** checkbox 表示多选，radio 表示单选。 */
+    type: 'checkbox' | 'radio';
+    /** 禁用某一行选择的条件。 */
+    disabled_when?: Condition;
+    /** 选择列附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 表格工具栏配置。
+ */
+export interface TableToolbarConfig {
+    /** 左侧动作。 */
+    left?: ActionRef[];
+    /** 右侧动作。 */
+    right?: ActionRef[];
+    /** 批量动作。scope 默认是 batch，选中项为空时默认禁用。 */
+    batch?: ActionRef[];
+    /** 动作简写，等价于 left。 */
+    actions?: ActionRef[];
+    /** 工具栏快捷筛选项。 */
+    filters?: TableFilterConfig[];
+    /** 工具栏容器属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 表格工具栏快捷筛选项。
+ *
+ * 完整搜索表单使用 SearchView；toolbar filters 用于状态、快捷视图等轻量筛选。
+ */
+export interface TableFilterConfig {
+    /** 字段名。通常引用 ResourceField.name。 */
+    field?: string;
+    /** 筛选项标题。 */
+    title?: string;
+    /** 查询操作符。缺失时可按字段类型推导。 */
+    operator?: string;
+    /** 筛选组件 key，例如 segmented、select。 */
+    component?: string;
+    /** 默认值。 */
+    defaultValue?: unknown;
+    /** 静态选项。 */
+    options?: OptionItem[];
+    /** 异步数据源。 */
+    dataSource?: DataSourceConfig;
+    /** 筛选组件附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 表格行操作列配置。
+ */
+export interface TableOperateConfig {
+    /** 操作列表头。 */
+    title?: string;
+    /** 操作列宽度。 */
+    width?: number;
+    /** 最小列宽。 */
+    minWidth?: number;
+    /** 固定方向。 */
+    fixed?: 'left' | 'right';
+    /** 对齐方式。 */
+    align?: 'left' | 'center' | 'right';
+    /** 是否将过多操作自动折叠为更多操作。只有显式设为 true 时才启用。 */
+    collapse?: boolean;
+    /** 是否使用按钮组包裹行操作。默认 true。 */
+    group?: boolean;
+    /** 行操作动作。 */
+    actions?: ActionRef[];
+    /** 操作列附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 表格分页配置。
+ */
+export interface TablePaginationConfig {
+    /** 默认每页条数。 */
+    pageSize?: number;
+    /** 可选每页条数。 */
+    pageSizes?: number[];
+    /** 分页组件附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 表格编辑配置。
+ *
+ * 该配置是表格视图能力，普通列表和嵌套关系列表都可以消费。第一阶段建议只实现 saveMode=row。
+ */
+export interface TableEditingConfig {
+    /** 编辑模式。none/default 表示不启用行内编辑。 */
+    mode?: 'none' | 'inline' | string;
+    /** 新增记录展示方式。inline 表示插入行编辑；dialog/drawer 表示复用表单视图。 */
+    createMode?: 'inline' | 'dialog' | 'drawer' | string;
+    /** 更新记录展示方式。 */
+    updateMode?: 'inline' | 'dialog' | 'drawer' | string;
+    /** 保存粒度。第一阶段建议只实现 row。 */
+    saveMode?: 'row' | 'batch' | string;
+    /** 允许行内编辑的字段。缺失时按 columns 中可编辑字段推导。 */
+    fields?: string[];
+}
+/**
+ * 表格列。
+ *
+ * 字段列使用 field；非字段列使用 type=custom 并提供 id。
+ */
+export interface TableColumn {
+    /** 自定义列标识。非字段列必填。 */
+    id?: string;
+    /** 列类型。缺失且存在 field 时按字段列处理。 */
+    type?: 'field' | 'custom';
+    /** 字段名。字段列必须引用 ResourceField.name。 */
+    field?: string;
+    /** 当前列标题。缺失时使用 ResourceField.label。 */
+    title?: string;
+    /** 逻辑展示组件 key。缺失时根据字段类型推导。 */
+    component?: string;
+    /** 字符串模板，例如 "${amount}-单价：${price}/元"。 */
+    template?: string;
+    /** 计算表达式。由受限表达式执行器求值。 */
+    value?: ValueExpression;
+    /** 展示格式化配置。 */
+    format?: FormatConfig;
+    /** 固定列宽。 */
+    width?: number;
+    /** 最小列宽。 */
+    minWidth?: number;
+    /** 固定方向。 */
+    fixed?: 'left' | 'right';
+    /** 对齐方式。 */
+    align?: 'left' | 'center' | 'right';
+    /** 是否允许排序。缺失时使用 ResourceField.sortable。 */
+    sortable?: boolean;
+    /** 列组件附加属性。 */
+    props?: Record<string, unknown>;
+    /** 显示条件。 */
+    show_when?: Condition;
+}
+/**
+ * 搜索视图。
+ */
+export interface SearchView {
+    /** 搜索区标题。通常不展示。 */
+    title?: string;
+    /** 搜索展示模式。inline 表示轻量内联搜索区。 */
+    mode?: 'inline' | 'advanced' | string;
+    /** 字段名简写。后端导出轻量 views 时可用该字段表达搜索项顺序。 */
+    fields?: string[];
+    /** 搜索项。缺失时按 searchable 字段推导。 */
+    items?: SearchItem[];
+    /** 搜索按钮。false 表示不显示按钮；缺失时生成查询和重置。 */
+    actions?: false | ActionRef[];
+    /** 搜索区布局配置。 */
+    layout?: SearchLayoutConfig;
+    span?: number;
+    gap?: number;
+    /** 是否默认收起。 */
+    collapsed?: boolean;
+    /** 搜索区附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 搜索区布局配置。
+ */
+export interface SearchLayoutConfig {
+    /** 每行列数。 */
+    columns?: number;
+    /** 搜索项间距。 */
+    gap?: number;
+    /** 收起时保留的行数。 */
+    collapsedRows?: number;
+}
+/**
+ * 搜索项。
+ *
+ * 默认不显示 label，placeholder 使用 title 或 ResourceField.label。
+ */
+export interface SearchItem {
+    /** 字段名，必须引用 ResourceField.name。 */
+    field: string;
+    /** 当前搜索项标题。可作为 placeholder 来源。 */
+    title?: string;
+    /** 查询操作符。缺失时根据字段类型推导。 */
+    operator?: string;
+    /** 可选查询操作符集合。存在时搜索项通常需要展示操作符选择。 */
+    operators?: string[];
+    /** 搜索组件 key。缺失时根据搜索场景推导。 */
+    component?: string;
+    /** 搜索组件附加属性。 */
+    props?: Record<string, unknown>;
+    /** 搜索项专属数据源。常用于 select、relation 等搜索组件。 */
+    dataSource?: DataSourceConfig;
+    /** 栅格跨度。 */
+    span?: number;
+    gap?: number;
+    /** 是否显示 label。默认 false。 */
+    show_label?: boolean;
+    /** 显示条件。 */
+    show_when?: Condition;
+}
+/** 动作作用域。 */
+export type ActionScope = 'collection' | 'resource' | 'record' | 'batch' | 'form' | 'self' | string;
+/** 动作类型。 */
+export type ActionKind = 'builtin' | 'custom' | 'request' | 'navigate' | string;
+/**
+ * 动作引用。
+ *
+ * 出现在 toolbar、operate、batchActions、footer.actions 等 UI 位置。
+ */
+export interface ActionRef {
+    /** 动作标识。可指向内置动作，也可引用 schema.actions。 */
+    action: string;
+    /** 当前按钮文案。缺失时可使用 ActionDefinition.title。 */
+    title?: string;
+    /** 图标 key。具体图标由 UI adapter 解析。 */
+    icon?: string;
+    /** 按钮类型或动作展示类型。type=dropdown 时表示下拉动作组。 */
+    type?: string;
+    /** 动作作用域。缺失时由所在位置推导。 */
+    scope?: ActionScope;
+    /** 子动作。用于下拉按钮或更多操作。 */
+    children?: ActionRef[];
+    /** 自定义按钮组件 key。 */
+    component?: string;
+    /** 按钮组件附加属性。 */
+    props?: Record<string, unknown>;
+    /** 执行前确认配置。 */
+    confirm?: ConfirmConfig;
+    /** 显示条件。 */
+    show_when?: Condition;
+    /** 禁用条件。scope=batch 时选中项为空会默认禁用。 */
+    disabled_when?: Condition;
+    /** 成功后的前端效果。局部配置优先于 ActionDefinition。 */
+    afterSuccess?: ActionAfterEffect;
+    /** 失败后的前端效果。局部配置优先于 ActionDefinition。 */
+    afterError?: ActionAfterEffect;
+}
+/**
+ * 顶层动作定义。
+ *
+ * 用于集中定义自定义动作或覆盖内置动作的默认行为。
+ */
+export interface ActionDefinition {
+    /** 动作默认标题。 */
+    title?: string;
+    /** 默认图标 key。 */
+    icon?: string;
+    /** 默认按钮类型。 */
+    type?: string;
+    /** 动作类型。custom 通常交给 DataAdapter.executeAction。 */
+    kind?: ActionKind;
+    /** 默认作用域。 */
+    scope?: ActionScope;
+    /** 业务处理标识，例如 customer.archive。 */
+    handler?: string;
+    /** 是否启用。false 时引用该动作的位置应禁用或隐藏。 */
+    enabled?: boolean;
+    /** 动作打开表单、详情或页面时的展示方式。 */
+    presentation?: ActionPresentation;
+    /** 执行前确认配置。 */
+    confirm?: ConfirmConfig;
+    /** 显示条件。 */
+    show_when?: Condition;
+    /** 禁用条件。 */
+    disabled_when?: Condition;
+    /** 成功后的默认前端效果。 */
+    afterSuccess?: ActionAfterEffect;
+    /** 失败后的默认前端效果。 */
+    afterError?: ActionAfterEffect;
+    /** 动作附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 动作展示方式。
+ */
+export interface ActionPresentation {
+    /** 展示类型，例如 dialog、drawer、page。 */
+    type?: 'default' | 'dialog' | 'drawer' | 'page' | string;
+    /** 嵌套场景中的挂载位置。默认 self。 */
+    mount?: 'self' | 'parent' | 'root' | string;
+    /** 展示组件附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 动作确认框配置。
+ */
+export interface ConfirmConfig {
+    /** 确认框标题。 */
+    title?: string;
+    /** 确认框内容。 */
+    content?: string;
+    /** 确认组件附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * 动作完成后的前端效果。
+ */
+export interface ActionAfterEffect {
+    /** 关闭目标。true 表示关闭当前动作打开的 wrapper。 */
+    close?: boolean | string;
+    /** 刷新目标，例如 source、table:default、root.table:default。 */
+    refresh?: string[];
+    /** 成功或失败提示文案。 */
+    message?: string;
+    /** 跳转地址或路由标识。 */
+    navigate?: string;
+    /** 重置目标，例如 form:default。 */
+    reset?: string[];
+    /** 额外触发的事件名。 */
+    emit?: string;
+}
+/**
+ * 数据源配置。
+ *
+ * 字段默认数据源优先来自 ResourceField.options。节点级 dataSource 用于覆盖当前 UI 场景。
+ */
+export type DataSourceConfig = StaticOptionsDataSource | RemoteOptionsDataSource | DictionaryOptionsDataSource | ReferenceDataSource;
+/**
+ * 静态选项数据源。
+ */
+export interface StaticOptionsDataSource {
+    /** 数据源类型。 */
+    type: 'static-options';
+    /** 静态选项列表。 */
+    options: OptionItem[];
+}
+/**
+ * 远程选项数据源。
+ *
+ * source 是业务数据源标识，由 DataAdapter 或 hooks.resolveOptions 解释。
+ */
+export interface RemoteOptionsDataSource {
+    /** 数据源类型。 */
+    type: 'remote-options';
+    /** 业务数据源标识，例如 category.options。 */
+    source: string;
+    /** 请求参数。 */
+    params?: Record<string, unknown>;
+}
+/** 数据字典数据源。 */
+export interface DictionaryOptionsDataSource {
+    type: 'dictionary';
+    /** 数据字典模块中的稳定字典编码。 */
+    code: string;
+}
+/**
+ * 资源引用候选项数据源。
+ */
+export interface ReferenceDataSource {
+    /** 数据源类型。 */
+    type: 'reference';
+    /** 关联资源编码。 */
+    resource: string;
+    /** 选项值字段。 */
+    value_field: string;
+    /** 选项标签字段。 */
+    label_field: string;
+    /** 搜索字段。 */
+    search_field?: string;
+    /** 禁用状态字段。 */
+    disabled_field?: string;
+    /** 父级字段。树形关联选项会用到。 */
+    parent_field?: string;
+    /** 候选项分组稳定值字段。 */
+    group_field?: string;
+    /** 候选项分组展示名称字段。 */
+    group_label_field?: string;
+    /** 候选项补充说明字段。 */
+    description_field?: string;
+    /** 需要随选项一并返回的元信息字段。 */
+    meta_fields?: string[];
+    /** 固定过滤条件。 */
+    filters?: FieldOptionFilterConfig[];
+    /** 固定排序配置。 */
+    sorts?: FieldOptionSortConfig[];
+    /** 单次查询数量。 */
+    limit?: number;
+    /** 加载模式。paged 表示搜索分页，tree 表示树形懒加载，all 表示显式全量。 */
+    load_mode?: 'paged' | 'tree' | 'all';
+    /** 附加参数。 */
+    params?: Record<string, unknown>;
+}
+/** 普通候选项允许保存的 JSON 标量值。 */
+export type OptionValue = string | number | boolean;
+/** 候选项分组。 */
+export interface OptionGroup {
+    /** 分组稳定值。 */
+    value: OptionValue;
+    /** 分组展示名称。 */
+    label: string;
+}
+/**
+ * 选项项。
+ */
+export interface OptionItem {
+    /** 选项标签。 */
+    label: string;
+    /** 选项值。 */
+    value: OptionValue;
+    /** 是否禁用。 */
+    disabled?: boolean;
+    /** 下拉列表中的补充说明。 */
+    description?: string;
+    /** 所属分组；不支持分组的 UI adapter 可以忽略。 */
+    group?: OptionGroup;
+    /** 子选项。树形选择会用到。 */
+    children?: OptionItem[];
+    /** 父级值。树形选择会用到。 */
+    parent_value?: unknown;
+    /** 是否仍有子节点。树形懒加载会用到。 */
+    has_children?: boolean;
+    /** 搜索结果路径标签。树形搜索会用到。 */
+    path_labels?: string[];
+    /** 选项附加属性。 */
+    meta?: Record<string, unknown>;
+}
+/**
+ * relation 候选项结果。
+ */
+export interface RelationOptionsResult {
+    /** 当前候选项。 */
+    results: OptionItem[];
+    /** 已选值回显候选项。 */
+    selected?: OptionItem[];
+    /** 符合条件的总数量。 */
+    total?: number;
+    /** 当前页码。 */
+    page?: number;
+    /** 当前分页大小。 */
+    limit?: number;
+    /** 是否还有更多候选项。 */
+    has_more?: boolean;
+    /** 附加信息。 */
+    meta?: Record<string, unknown>;
+}
+/**
+ * 稳定条件协议支持的字段操作符。
+ */
+export type ConditionOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'in' | 'not_in' | 'empty' | 'not_empty';
+/**
+ * 条件表达式。
+ *
+ * 简单条件使用 field/op/value；组合条件使用 all/any/not。
+ * expr 是预留的受限表达式字段，运行时实现前应通过 diagnostics 明确提示不支持。
+ */
+export interface Condition {
+    /** 全部子条件成立。 */
+    all?: Condition[];
+    /** 任一子条件成立。 */
+    any?: Condition[];
+    /** 子条件不成立。 */
+    not?: Condition;
+    /** 字段名。 */
+    field?: string;
+    /** 操作符，例如 eq、neq、contains、in。缺失时按 eq 处理。 */
+    op?: ConditionOperator;
+    /** 比较值。 */
+    value?: unknown;
+    /** selection 为空。常用于批量按钮禁用。 */
+    selection_empty?: boolean;
+    /** 受限表达式。 */
+    expr?: string;
+}
+/**
+ * 值计算表达式类型。
+ *
+ * literal 返回静态值；field/path 从表达式上下文读取值；template 做字符串插值；
+ * concat/sum 聚合子表达式或字段；now/today 等时间函数复用 FieldValueExpression 的时间输出约定。
+ */
+export type ValueExpressionType = 'literal' | 'field' | 'path' | 'template' | 'concat' | 'sum' | 'now' | 'today' | 'start_of_day' | 'end_of_day' | 'start_of_month' | 'end_of_month' | string;
+/**
+ * 值计算表达式。
+ *
+ * 该协议是受限结构化表达式，不执行任意 JavaScript。消费端只能解释明确支持的 type。
+ */
+export interface ValueExpression {
+    /** 表达式类型，例如 field、template、sum。 */
+    type: ValueExpressionType;
+    /** literal 使用的静态值。 */
+    value?: unknown;
+    /** field 表达式读取当前表单字段值。 */
+    field?: string;
+    /** path 表达式读取表达式上下文路径，例如 form.amount、row.price、payload.parentValue。 */
+    path?: string;
+    /** template 表达式使用的字符串模板，例如 "${form.first_name} ${form.last_name}"。 */
+    template?: string;
+    /** concat 等组合表达式使用的子表达式。 */
+    items?: ValueExpression[];
+    /** sum 等字段聚合表达式使用的当前表单字段集合。 */
+    fields?: string[];
+    /** concat 输出时使用的分隔符。 */
+    separator?: string;
+    /** 时间类表达式的偏移量。 */
+    offset?: FieldValueExpressionOffset;
+    /** 时间类表达式输出格式。 */
+    format?: 'date' | 'datetime' | 'time' | 'timestamp' | string;
+    /** 时间类表达式使用的时区。 */
+    timezone?: string;
+}
+/**
+ * 展示格式化配置。
+ */
+export interface FormatConfig {
+    /** 格式化类型。 */
+    type: 'datetime' | 'date' | 'time' | 'number' | 'currency' | 'percent' | 'enum' | 'custom' | string;
+    /** 日期时间格式或自定义格式模板。 */
+    pattern?: string;
+    /** 货币代码，例如 CNY。 */
+    currency?: string;
+    /** 格式化器附加属性。 */
+    props?: Record<string, unknown>;
+}
+/**
+ * SparqView 支持的渲染模式。
+ */
+export type RenderMode = 'page' | 'form' | 'table' | 'search' | 'detail';
+//# sourceMappingURL=types.d.ts.map