BPOS-TMP-REPO/packages/contracts/src/ledger.ts

/**
 * 数据与台账(编码规范 §8.1 / §7.2;语义出处 OS 04 / 09,AM 10.3 / 11.1)。
 *
 * 三级寻址「数据域.数据对象.字段」+ 通用事务性接口 + 写三分(系统写 / 草稿写 / 放行写)。
 * 写三分是 `ledger` 出口上的**三个不同方法**,不是一个带 flag 的方法 —— 调用方拿不到「绕门」的形态。
 */
import { z } from 'zod';
import { taskIdSchema } from './id.ts';

/* ── 三级寻址 ─────────────────────────────────────────────────────────── */

const identifier = z
  .string()
  .min(1)
  .max(63)
  .regex(/^[a-z][a-z0-9_]*$/, '标识符只准小写字母开头、字母数字下划线');

/**
 * 数据域:活动自持域用活动名,共享域固定为 `shared`(AM 11.3 暗耦合禁令)。
 * 活动间不得共享自持域的数据表;跨活动的事实只有两条路 —— 输出口载荷,或共享域。
 */
export const SHARED_DOMAIN = 'shared';

export const ledgerAddressSchema = z.object({
  domain: identifier,
  object: identifier,
  field: identifier.optional(),
});
export type LedgerAddress = z.infer<typeof ledgerAddressSchema>;

export function formatAddress(address: LedgerAddress): string {
  return address.field === undefined
    ? `${address.domain}.${address.object}`
    : `${address.domain}.${address.object}.${address.field}`;
}

export function parseAddress(text: string): LedgerAddress {
  const parts = text.split('.');
  if (parts.length < 2 || parts.length > 3) throw new Error(`非法台账地址:${text}`);
  const [domain, object, field] = parts;
  return ledgerAddressSchema.parse(field === undefined ? { domain, object } : { domain, object, field });
}

export function isSharedDomain(address: LedgerAddress): boolean {
  return address.domain === SHARED_DOMAIN;
}

/* ── 字段声明与自生长 ────────────────────────────────────────────────── */

/**
 * 字段类型 —— 台账自生长的类型格。
 * 「同名异型取能兼容双方的最宽类型」(放宽即增,不破坏);语义互斥才拦下(OS 04)。
 */
export const LEDGER_FIELD_TYPES = ['text', 'number', 'integer', 'boolean', 'date', 'timestamp', 'json'] as const;
export const ledgerFieldTypeSchema = z.enum(LEDGER_FIELD_TYPES);
export type LedgerFieldType = z.infer<typeof ledgerFieldTypeSchema>;

/** 字段使用声明 —— 声明的是**活动要用什么字段**,不是对象该定义什么字段 */
export const fieldDeclarationSchema = z.object({
  name: identifier,
  type: ledgerFieldTypeSchema,
  label: z.string().optional(),
  /** 主键参与:对象的主键由声明的最大化合并决定 */
  primaryKey: z.boolean().default(false),
  /** 治理:脱敏 / 保留期 / 可学习标记(OS 8.1 治理先行) */
  masked: z.boolean().default(false),
  /**
   * **这一列缺了就是活没干完** —— 于是基座数得出「本单这张表缺必填的有几行」。
   *
   * 不建 NOT NULL:草稿层的本分就是「过程中允许缺」,缺口要摆给人看、由人补,
   * 而不是让写入当场炸掉。这一维只служ两件事:
   *   · 读数 `域_对象_missing` / `_missing_keys` —— 基座数出来的数,判据可以放心读;
   *   · 报告模版按它标红胶囊(A1 那张清单的「必填 / 选填」两色就是它)。
   *
   * 为什么要有它(2026-08-01,连跑十轮里三轮死在这):A1 的
   * 「必填齐(PN / 年用量)」是 L1 机检,读的却是**活动自己写的** `missing_key_total` ——
   * 人在卡上补了年用量、基座写回了草稿层,而那个汇总列要模型自己重算;
   * 它算漏一次,这条判据就永远绿不了,连拒五拍熔断。
   * **机检判据只许读基座数得出来的数** —— 这一维就是让基座数得出来的那把尺。
   *
   * 用 `optional` 不用 `default(false)`:后者会把它变成出参必填,
   * 六个活动两百来行字段声明都得补一个 `required: false` —— 那是给纪律收噪音税。
   * 不写就是不必填,读的那一侧一律 `=== true` 才当真。
   */
  required: z.boolean().optional(),
  /**
   * **这一列是分类列** —— 给出它的取值域,基座就按值现数本单每一类几行。
   *
   * 出的读数是 `域_对象_<列>_<值>`(值消毒成小写标识符),例如
   * `quote_intake_record_type_tag_a`。**没出现的值也铺 0** —— 取值域是声明给的,
   * 所以数得全;零条也是一个数,判据才算得下去。
   *
   * 为什么非要基座来数(2026-08-01 用户当场指出):三分类的条数从前是活动自己写的
   * `type_a_total / type_b_total / type_c_total`,而分布条、放行时的去向谓词、验收判据
   * 读的全是它们。于是**人在放行页把九条料全改成 A,类徽变了,分布条还是 5/3/1、
   * 去向还是「去选型」** —— 逐行数据变了,汇总数没人重算。
   * 而**手工修改的全部意义就是纠正 AI 的判断**:改了类标而流向不跟着变,
   * 这个兜底功能就是假的。能由数据算出来的,一律别让活动自报。
   */
  tally: z.array(z.string().min(1)).optional(),
  /**
   * **这一列缺了不拦单,但那一问不能省** —— 基座据此数「还有几行缺选填」。
   *
   * 与 `required` 的分工:必填缺一条都不许放行(它是验收标准);
   * 选填缺照样往下走,只是**必须经过人**——问过客户、或放行时确认可以先受理。
   *
   * 为什么也得基座数(2026-08-02 用户实测:「我这次补了目标价,为啥 L4 还在那乱判」):
   * 那条 L4 裁的依据是活动自己写的 `missing_minor_total`。人在件上补了目标价、
   * 基座已经写回草稿层,而那个数要模型自己重算 —— 它没算,于是照旧裁「不满足」,
   * 人明明补齐了却被告知还缺。**裁量项可以由人来判,但它判的事实必须是真的。**
   */
  expect: z.boolean().optional(),
  /**
   * **这一列由基座生成,既不问人也不让模型编**(2026-08-02 用户:「联系人ID自增啊,不用填」)。
   *
   * 用在**内部流水号**那一类主键上:联系人编码、行号 —— 它们不承载业务含义,
   * 只是「同一位客户下的第几位」。让人填是白占一格他答不上来的表单
   * (他哪知道这家客户已经有几位联系人);让模型编更糟,编重了就是覆盖别人那一行。
   *
   * 生成规则是**声明出来的一条**,不是每处各写一套:
   * 取同组其余主键的值作前缀,后面跟两位序号 —— `CU-9001` + `-01`、`-02`……
   * 序号数的是**同组已有的行**(正式版 + 本单草稿),所以同一单里加两位联系人也不撞。
   * 没有其余主键(它自己就是唯一那把键)时退回纯序号 `01`。
   *
   * 落在哪一层:人按下确认那一刻由基座补上 —— 与「该由人亲手落下的别经 AI 转述」
   * 同一条规矩的另一半:**人答不上来的,也别摆到他面前假装他该答**。
   */
  auto: z.boolean().optional(),
  /**
   * **行级必填:同行某列等于某值时,这一列才算必填**(2026-08-02 用户:
   * 「工作区的 HTML 必填项必须填写了才能提交啊,不填写能算任务完成了吗?」)。
   *
   * 逐颗按序派单(A2 的 sel_stage 队列)撞上表级 `required` 的死结:
   * 定案三格若整列必填,第一颗的卡会被**第二颗**(还没轮到、在件上根本不可见)
   * 的空格拦死 —— 人无处可填,闸成了死路;整列不标,闸又没牙,
   * 空手就能交卷(用户实测点名)。
   * 这一维把「必填」钉在**该轮到的那一行**上:`{ column: 'sel_stage', value: 'NOW' }`
   * 即「排到 NOW 的那一行,这一格必填」。`_missing` / `_missing_keys` /
   * 提交闸 / 件上红带全部同源生效;`required` 不带它照旧整列必填。
   */
  requiredWhen: z.object({ column: z.string().min(1), value: z.string().min(1) }).optional(),
});
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 const LEDGER_OBJECT_KINDS = ['record', 'master', 'derived'] as const;
export const ledgerObjectKindSchema = z.enum(LEDGER_OBJECT_KINDS);
export type LedgerObjectKind = z.infer<typeof ledgerObjectKindSchema>;

export const LEDGER_KIND_LABEL: Readonly<Record<LedgerObjectKind, string>> = {
  record: '单据',
  master: '主数据',
  derived: '派生',
};

export const LEDGER_KIND_DESC: Readonly<Record<LedgerObjectKind, string>> = {
  record: '一单一份的过程与结论 —— 放行即定稿,只增不改;查得到、回放得出就够了',
  master: '跨单积累的经营资产 —— 会被反复更新,下一单读它做判断;治理都在这一类上',
  derived: '能由单据与主数据算出来的指标 —— 不该手写,手写的派生值会和来源打架',
};

export const objectDeclarationSchema = z.object({
  domain: identifier,
  object: identifier,
  label: z.string().optional(),
  /**
   * 这张表是什么性质 —— 缺省 `record`,因为活动写下的绝大多数是单据。
   * 缺省不是「随便」:安装静态审会按 kind 各自核一遍(见 `ledgerKindFindings`)。
   */
  kind: ledgerObjectKindSchema.default('record'),
  /**
   * 单标识字段名 —— **只有 `record` 需要**,且必须是它主键的一部分。
   *
   * 为什么要显式声明而不去猜:猜的规则(比如「主键里得有个 `_ref` 结尾的列」)
   * 迟早猜错,而错的那一次是**静默覆盖数据**。让活动自己说清哪一列是「单」,
   * 安装期就能核:它在不在 fields 里、是不是主键的一部分。
   */
  caseKey: identifier.optional(),
  /**
   * **这张表的每一行还是一份资料文件** —— 哪几列合起来是那份文件(2026-08-23 加)。
   *
   * 起因:I01 要「真实产出资料文件」(word/excel/md/html,人点开就能看)。文件的
   * 正身是**内容**,而内容本来就该落在台账里 —— 再单独存一份文件字节,同一份事实
   * 两处各存一份,改一处就分叉。所以这里只声明「这一行的哪一列是标题、哪一列是正文、
   * 哪一列说要出哪种格式」,字节由基座按声明**现造**(`composeFile`):
   * 下载拿到的是真 .docx/.xlsx(能用 Word/Excel 打开),而它与台账永远一致。
   *
   * 它同时是**授权面**:没声明这一段的表,谁也点不出文件来 —— 与「写的授权面是
   * 台账声明」「立监听的授权面是清单声明」同款。
   */
  file: z
    .object({
      /** 文件名取哪一列(空了退主键) */
      titleColumn: identifier,
      /** 正文取哪一列 —— 一律 Markdown 原文,四种格式都由它现造 */
      bodyColumn: identifier,
      /** 出哪种格式取哪一列(值:md / html / docx / xlsx) */
      formatColumn: identifier,
    })
    .optional(),
  fields: z.array(fieldDeclarationSchema).min(1),
});
export type ObjectDeclaration = z.infer<typeof objectDeclarationSchema>;

/* ── 通用事务接口 DTO ────────────────────────────────────────────────── */

export const ledgerRowSchema = z.record(z.string(), z.unknown());
export type LedgerRow = z.infer<typeof ledgerRowSchema>;

export const ledgerKeySchema = z.record(z.string(), z.union([z.string(), z.number()]));
export type LedgerKey = z.infer<typeof ledgerKeySchema>;

export const LEDGER_OPERATIONS = ['insert', 'update', 'upsert', 'delete'] as const;
export const ledgerOperationSchema = z.enum(LEDGER_OPERATIONS);
export type LedgerOperation = z.infer<typeof ledgerOperationSchema>;

export const ledgerMutationSchema = z.object({
  address: ledgerAddressSchema.omit({ field: true }),
  operation: ledgerOperationSchema,
  key: ledgerKeySchema,
  values: ledgerRowSchema.default({}),
});
export type LedgerMutation = z.infer<typeof ledgerMutationSchema>;

/** 查询:简单等值过滤 + 排序 + 分页(治理台数据管理的记录浏览也走这里) */
export const ledgerQuerySchema = z.object({
  address: ledgerAddressSchema.omit({ field: true }),
  where: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])).default({}),
  orderBy: z.array(z.object({ field: identifier, dir: z.enum(['asc', 'desc']) })).default([]),
  limit: z.number().int().min(1).max(500).default(50),
  offset: z.number().int().min(0).default(0),
});
export type LedgerQuery = z.infer<typeof ledgerQuerySchema>;

export const ledgerPageSchema = z.object({
  rows: z.array(ledgerRowSchema),
  total: z.number().int().min(0),
});
export type LedgerPage = z.infer<typeof ledgerPageSchema>;

/* ── 写三分(OS 09) ────────────────────────────────────────────────── */

/**
 * ① system —— 系统写:入站归一、流转记录、留痕。登记世界已发生的事实,不过放行门,
 *              写入正式版并**即时产生数据事件**。
 * ② draft  —— 草稿写:任务级草稿层(读己之写:本任务可见、正式版不可见、**不产生数据事件**)。
 * ③ release —— 放行写:草稿层合并入正式版,**此刻才产生数据事件**。
 */
export const WRITE_KINDS = ['system', 'draft', 'release'] as const;
export const writeKindSchema = z.enum(WRITE_KINDS);
export type WriteKind = z.infer<typeof writeKindSchema>;

export const WRITE_KIND_LABEL: Readonly<Record<WriteKind, string>> = {
  system: '系统写',
  draft: '草稿写',
  release: '放行写',
};

/** 三分的不变量,机检用:只有 draft 不抛数据事件 */
export function emitsDataEvent(kind: WriteKind): boolean {
  return kind !== 'draft';
}

/* ── 任务视图与草稿层 ────────────────────────────────────────────────── */

/** 任务视图 = 正式版 + 本任务草稿层;环内推进读它,不依赖事件(OS 09) */
export const taskViewRequestSchema = z.object({
  taskId: taskIdSchema,
  query: ledgerQuerySchema,
});
export type TaskViewRequest = z.infer<typeof taskViewRequestSchema>;

export const draftPatchSchema = z.object({
  taskId: taskIdSchema,
  address: ledgerAddressSchema.omit({ field: true }),
  key: ledgerKeySchema,
  patch: ledgerRowSchema,
  /** 草稿删除:合并时物理删除正式版行 */
  tombstone: z.boolean().default(false),
});
export type DraftPatch = z.infer<typeof draftPatchSchema>;

/** 数据冲突检查(落地预检第五项):他单已改同一字段即预检不过(OS 7.3) */
export const draftConflictSchema = z.object({
  address: ledgerAddressSchema,
  key: ledgerKeySchema,
  field: z.string(),
  draftValue: z.unknown(),
  officialValue: z.unknown(),
  /** 草稿建立时读到的基线值 —— 与当前正式版不同即冲突 */
  baselineValue: z.unknown(),
});
export type DraftConflict = z.infer<typeof draftConflictSchema>;

/* ── 动作意向(写类工具调用,登记后集中在放行时落地,OS 7.3) ───────── */

export const ACTION_INTENT_STATES = [
  'drafted',
  'prechecked',
  'landed',
  'failed',
  'abandoned',
] as const;
export const actionIntentStateSchema = z.enum(ACTION_INTENT_STATES);
export type ActionIntentState = z.infer<typeof actionIntentStateSchema>;

export const actionIntentSchema = z.object({
  id: z.string().min(1),
  taskId: taskIdSchema,
  tool: z.string().min(1),
  /** 入参冻结 —— 登记时即定,放行时按幂等键执行 */
  input: z.record(z.string(), z.unknown()),
  idempotencyKey: z.string().min(1),
  state: actionIntentStateSchema,
  label: z.string(),
  detail: z.string().optional(),
  error: z.string().optional(),
});
export type ActionIntent = z.infer<typeof actionIntentSchema>;