BPOS-TMP-REPO/api-report/packages/contracts/src/ledger.d.ts

/**
 * 数据与台账(编码规范 §8.1 / §7.2;语义出处 OS 04 / 09,AM 10.3 / 11.1)。
 *
 * 三级寻址「数据域.数据对象.字段」+ 通用事务性接口 + 写三分(系统写 / 草稿写 / 放行写)。
 * 写三分是 `ledger` 出口上的**三个不同方法**,不是一个带 flag 的方法 —— 调用方拿不到「绕门」的形态。
 */
import { z } from 'zod';
/**
 * 数据域:活动自持域用活动名,共享域固定为 `shared`(AM 11.3 暗耦合禁令)。
 * 活动间不得共享自持域的数据表;跨活动的事实只有两条路 —— 输出口载荷,或共享域。
 */
export declare const SHARED_DOMAIN = "shared";
export declare const ledgerAddressSchema: z.ZodObject<{
    domain: z.ZodString;
    object: z.ZodString;
    field: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
export type LedgerAddress = z.infer<typeof ledgerAddressSchema>;
export declare function formatAddress(address: LedgerAddress): string;
export declare function parseAddress(text: string): LedgerAddress;
export declare function isSharedDomain(address: LedgerAddress): boolean;
/**
 * 字段类型 —— 台账自生长的类型格。
 * 「同名异型取能兼容双方的最宽类型」(放宽即增,不破坏);语义互斥才拦下(OS 04)。
 */
export declare const LEDGER_FIELD_TYPES: readonly ["text", "number", "integer", "boolean", "date", "timestamp", "json"];
export declare const ledgerFieldTypeSchema: z.ZodEnum<{
    number: "number";
    boolean: "boolean";
    json: "json";
    text: "text";
    date: "date";
    integer: "integer";
    timestamp: "timestamp";
}>;
export type LedgerFieldType = z.infer<typeof ledgerFieldTypeSchema>;
/** 字段使用声明 —— 声明的是**活动要用什么字段**,不是对象该定义什么字段 */
export declare const fieldDeclarationSchema: z.ZodObject<{
    name: z.ZodString;
    type: z.ZodEnum<{
        number: "number";
        boolean: "boolean";
        json: "json";
        text: "text";
        date: "date";
        integer: "integer";
        timestamp: "timestamp";
    }>;
    label: z.ZodOptional<z.ZodString>;
    primaryKey: z.ZodDefault<z.ZodBoolean>;
    masked: z.ZodDefault<z.ZodBoolean>;
    required: z.ZodOptional<z.ZodBoolean>;
    tally: z.ZodOptional<z.ZodArray<z.ZodString>>;
    expect: z.ZodOptional<z.ZodBoolean>;
    auto: z.ZodOptional<z.ZodBoolean>;
    requiredWhen: z.ZodOptional<z.ZodObject<{
        column: z.ZodString;
        value: z.ZodString;
    }, z.core.$strip>>;
    distinct: z.ZodOptional<z.ZodBoolean>;
    refersTo: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
export type FieldDeclaration = z.infer<typeof fieldDeclarationSchema>;
/**
 * 台账对象的**性质** —— 这条数据归谁管、活多久、谁有权改它。
 *
 * 从前台账只有「地址 + 列」,没有这一维,于是**没人需要回答「这张表是什么」**——
 * 后果不是不好看,是主键写歪了还没人发现:A4 的报价草案本该一单一份,
 * 主键却只有 `pn`,第二单报同一个料号直接 upsert 覆盖上一单
 * (实测:跑了四轮 A4,`quote_pricing.draft` 只剩最后一轮的 3 行;
 * 而主键带了单号的 `quote_intake.record` 是 61 行 / 20 单,一单不少)。
 *
 * 分三类,判据是**机械的**,不靠感觉:
 *
 * · `record` 单据 —— 一单一份的过程与结论。主键**必含单标识**(`caseKey`),
 *   放行即定稿、只增不改。它不需要「管理」,需要的是查得到、回放得出。
 * · `master` 主数据 —— 跨单积累的经营资产(客户、供应商、料号规格、历史价)。
 *   主键是**业务实体**,会被反复更新,下一单读它做判断。治理都在这一类上:
 *   谁能改、依据是什么、怎么去重、多久算过期。
 * · `derived` 派生 —— 能由前两类算出来的指标(落地率、命中率)。
 *   **本不该手写**:手写的派生值能和它的来源打架,而没人会发现。
 *   标出来至少让它可被重算校验。
 */
export declare const LEDGER_OBJECT_KINDS: readonly ["record", "master", "derived"];
export declare const ledgerObjectKindSchema: z.ZodEnum<{
    record: "record";
    master: "master";
    derived: "derived";
}>;
export type LedgerObjectKind = z.infer<typeof ledgerObjectKindSchema>;
export declare const LEDGER_KIND_LABEL: Readonly<Record<LedgerObjectKind, string>>;
export declare const LEDGER_KIND_DESC: Readonly<Record<LedgerObjectKind, string>>;
export declare const objectDeclarationSchema: z.ZodObject<{
    domain: z.ZodString;
    object: z.ZodString;
    label: z.ZodOptional<z.ZodString>;
    kind: z.ZodDefault<z.ZodEnum<{
        record: "record";
        master: "master";
        derived: "derived";
    }>>;
    caseKey: z.ZodOptional<z.ZodString>;
    createOnly: z.ZodOptional<z.ZodBoolean>;
    file: z.ZodOptional<z.ZodObject<{
        titleColumn: z.ZodString;
        bodyColumn: z.ZodString;
        formatColumn: z.ZodString;
    }, z.core.$strip>>;
    fields: z.ZodArray<z.ZodObject<{
        name: z.ZodString;
        type: z.ZodEnum<{
            number: "number";
            boolean: "boolean";
            json: "json";
            text: "text";
            date: "date";
            integer: "integer";
            timestamp: "timestamp";
        }>;
        label: z.ZodOptional<z.ZodString>;
        primaryKey: z.ZodDefault<z.ZodBoolean>;
        masked: z.ZodDefault<z.ZodBoolean>;
        required: z.ZodOptional<z.ZodBoolean>;
        tally: z.ZodOptional<z.ZodArray<z.ZodString>>;
        expect: z.ZodOptional<z.ZodBoolean>;
        auto: z.ZodOptional<z.ZodBoolean>;
        requiredWhen: z.ZodOptional<z.ZodObject<{
            column: z.ZodString;
            value: z.ZodString;
        }, z.core.$strip>>;
        distinct: z.ZodOptional<z.ZodBoolean>;
        refersTo: z.ZodOptional<z.ZodString>;
    }, z.core.$strip>>;
}, z.core.$strip>;
export type ObjectDeclaration = z.infer<typeof objectDeclarationSchema>;
export declare const ledgerRowSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
export type LedgerRow = z.infer<typeof ledgerRowSchema>;
export declare const ledgerKeySchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
export type LedgerKey = z.infer<typeof ledgerKeySchema>;
export declare const LEDGER_OPERATIONS: readonly ["insert", "update", "upsert", "delete"];
export declare const ledgerOperationSchema: z.ZodEnum<{
    insert: "insert";
    update: "update";
    delete: "delete";
    upsert: "upsert";
}>;
export type LedgerOperation = z.infer<typeof ledgerOperationSchema>;
export declare const ledgerMutationSchema: z.ZodObject<{
    address: z.ZodObject<{
        object: z.ZodString;
        domain: z.ZodString;
    }, z.core.$strip>;
    operation: z.ZodEnum<{
        insert: "insert";
        update: "update";
        delete: "delete";
        upsert: "upsert";
    }>;
    key: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
    values: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
}, z.core.$strip>;
export type LedgerMutation = z.infer<typeof ledgerMutationSchema>;
/** 查询:简单等值过滤 + 排序 + 分页(治理台数据管理的记录浏览也走这里) */
export declare const ledgerQuerySchema: z.ZodObject<{
    address: z.ZodObject<{
        object: z.ZodString;
        domain: z.ZodString;
    }, z.core.$strip>;
    where: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
    orderBy: z.ZodDefault<z.ZodArray<z.ZodObject<{
        field: z.ZodString;
        dir: z.ZodEnum<{
            desc: "desc";
            asc: "asc";
        }>;
    }, z.core.$strip>>>;
    limit: z.ZodDefault<z.ZodNumber>;
    offset: z.ZodDefault<z.ZodNumber>;
}, z.core.$strip>;
export type LedgerQuery = z.infer<typeof ledgerQuerySchema>;
export declare const ledgerPageSchema: z.ZodObject<{
    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
    total: z.ZodNumber;
}, z.core.$strip>;
export type LedgerPage = z.infer<typeof ledgerPageSchema>;
/**
 * ① system —— 系统写:入站归一、流转记录、留痕。登记世界已发生的事实,不过放行门,
 *              写入正式版并**即时产生数据事件**。
 * ② draft  —— 草稿写:任务级草稿层(读己之写:本任务可见、正式版不可见、**不产生数据事件**)。
 * ③ release —— 放行写:草稿层合并入正式版,**此刻才产生数据事件**。
 */
export declare const WRITE_KINDS: readonly ["system", "draft", "release"];
export declare const writeKindSchema: z.ZodEnum<{
    draft: "draft";
    system: "system";
    release: "release";
}>;
export type WriteKind = z.infer<typeof writeKindSchema>;
export declare const WRITE_KIND_LABEL: Readonly<Record<WriteKind, string>>;
/** 三分的不变量,机检用:只有 draft 不抛数据事件 */
export declare function emitsDataEvent(kind: WriteKind): boolean;
/** 任务视图 = 正式版 + 本任务草稿层;环内推进读它,不依赖事件(OS 09) */
export declare const taskViewRequestSchema: z.ZodObject<{
    taskId: z.core.$ZodBranded<z.ZodString, "TaskId", "out">;
    query: z.ZodObject<{
        address: z.ZodObject<{
            object: z.ZodString;
            domain: z.ZodString;
        }, z.core.$strip>;
        where: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
        orderBy: z.ZodDefault<z.ZodArray<z.ZodObject<{
            field: z.ZodString;
            dir: z.ZodEnum<{
                desc: "desc";
                asc: "asc";
            }>;
        }, z.core.$strip>>>;
        limit: z.ZodDefault<z.ZodNumber>;
        offset: z.ZodDefault<z.ZodNumber>;
    }, z.core.$strip>;
}, z.core.$strip>;
export type TaskViewRequest = z.infer<typeof taskViewRequestSchema>;
export declare const draftPatchSchema: z.ZodObject<{
    taskId: z.core.$ZodBranded<z.ZodString, "TaskId", "out">;
    address: z.ZodObject<{
        object: z.ZodString;
        domain: z.ZodString;
    }, z.core.$strip>;
    key: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
    patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
    tombstone: z.ZodDefault<z.ZodBoolean>;
}, z.core.$strip>;
export type DraftPatch = z.infer<typeof draftPatchSchema>;
/** 数据冲突检查(落地预检第五项):他单已改同一字段即预检不过(OS 7.3) */
export declare const draftConflictSchema: z.ZodObject<{
    address: z.ZodObject<{
        domain: z.ZodString;
        object: z.ZodString;
        field: z.ZodOptional<z.ZodString>;
    }, z.core.$strip>;
    key: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
    field: z.ZodString;
    draftValue: z.ZodUnknown;
    officialValue: z.ZodUnknown;
    baselineValue: z.ZodUnknown;
}, z.core.$strip>;
export type DraftConflict = z.infer<typeof draftConflictSchema>;
export declare const ACTION_INTENT_STATES: readonly ["drafted", "prechecked", "landed", "failed", "abandoned"];
export declare const actionIntentStateSchema: z.ZodEnum<{
    failed: "failed";
    drafted: "drafted";
    prechecked: "prechecked";
    landed: "landed";
    abandoned: "abandoned";
}>;
export type ActionIntentState = z.infer<typeof actionIntentStateSchema>;
export declare const actionIntentSchema: z.ZodObject<{
    id: z.ZodString;
    taskId: z.core.$ZodBranded<z.ZodString, "TaskId", "out">;
    tool: z.ZodString;
    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
    idempotencyKey: z.ZodString;
    state: z.ZodEnum<{
        failed: "failed";
        drafted: "drafted";
        prechecked: "prechecked";
        landed: "landed";
        abandoned: "abandoned";
    }>;
    label: z.ZodString;
    detail: z.ZodOptional<z.ZodString>;
    error: z.ZodOptional<z.ZodString>;
}, z.core.$strip>;
export type ActionIntent = z.infer<typeof actionIntentSchema>;