Archived
xcsandClaude Fable 5
7b85a79323
human-tool / ledger / loop-engine / release / task / interaction 六模块与 app 层(desk 路由、engines、consumers、 data-order-landing、case-stamp、reset-runs、seed-activities、容器与 server 装配),web 的 desk-task (ViewRegion / chat-bubbles / review-face)与 app.css、ui-kit 图标;契约 card / manifest; 迁移 0034_task_seq 与迁移日志;api-report 快照;CLAUDE.md 快照、debt、活动开发规范、HTML 报告规范同步。 逐条口径见 CLAUDE.md 快照(2026-08-27 下午至晚)。另一会话做的,一直留在工作树没入库;与同批另两条提交互相依赖。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0167qWjeyBwvfdGovd7FWbCu
83 lines
4.5 KiB
TypeScript
83 lines
4.5 KiB
TypeScript
/**
|
|
* module: ledger —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
|
|
*/
|
|
import type { EnvelopeDraft, LedgerKey, LedgerQuery, LedgerRow, LedgerObjectKind } from '@contracts';
|
|
import type { MaterializedObject, SchemaChange } from './internal/domain/schema-merge.ts';
|
|
import type { DraftEntry } from './internal/domain/task-view.ts';
|
|
|
|
export type Clock = { now(): Date };
|
|
export type IdGenerator = { next(): string };
|
|
|
|
/** 数据事件的发射口 —— app 注入 `event` 模块的出口(§5.2) */
|
|
export type EventPublisher = { publish(envelope: EnvelopeDraft): Promise<void> };
|
|
|
|
/**
|
|
* 这一单是不是**试跑** —— app 注入(设计台的两条试跑路径都算,见 `container.ts`)。
|
|
*
|
|
* 台账在 L1,认不出「谁起的单」;而放行写要不要落主数据,取决的恰恰是这件事。
|
|
* 所以由 app 把这一个布尔判断喂进来 —— 与 `EventPublisher` 同一个套路:
|
|
* 模块只声明「我需要知道什么」,不声明「去哪儿问」。
|
|
*
|
|
* 为什么只挡主数据、不挡单据:单据按单标识分行,一次试跑写一行自己的,
|
|
* 清运行数据就没了;主数据是**按业务实体**分行的档案,试跑往里建一位客户,
|
|
* 「新客户」那条样例就此再也试不出来 —— 它成了老客户。
|
|
*/
|
|
export type SimulationProbe = { isSimulated(taskId: string): Promise<boolean> };
|
|
|
|
export type ObjectRef = { readonly domain: string; readonly object: string };
|
|
|
|
/**
|
|
* 台账存储 —— 运行时 DDL / DML 由声明生成,ORM 静态 schema 不适用,
|
|
* 一律 node-postgres 直写(§1 / ADR-002)。
|
|
*/
|
|
export type LedgerStore = {
|
|
/** 已物化对象的列与主键;未物化返回 undefined */
|
|
describe(ref: ObjectRef): Promise<MaterializedObject | undefined>;
|
|
/** 出参带人读名(表注释);没登记就没有 label,呈现退回对象键 */
|
|
/** 记下对象性质(单据/主数据/派生)与单标识 —— 随声明走,不随建表走 */
|
|
setObjectMeta(ref: ObjectRef, kind: LedgerObjectKind, caseKey: string | undefined): Promise<void>;
|
|
listObjects(): Promise<Array<ObjectRef & { label?: string | undefined }>>;
|
|
/**
|
|
* 哪些对象是**主数据** —— 放行写要据此把试跑单的主数据挡在正式表外。
|
|
*
|
|
* 单独一个方法而不是让调用方 `listObjects` 自己筛:性质记在 `__object_meta` 里,
|
|
* 一次 where 就够;`describe` 读的是 information_schema,那里没有性质这一维。
|
|
*/
|
|
masterRefs(): Promise<ReadonlyArray<ObjectRef>>;
|
|
/** 执行「只增不破坏」的变更计划 */
|
|
applyChanges(ref: ObjectRef, changes: readonly SchemaChange[]): Promise<void>;
|
|
|
|
select(query: LedgerQuery): Promise<{ rows: LedgerRow[]; total: number }>;
|
|
selectByKeys(ref: ObjectRef, keys: readonly LedgerKey[]): Promise<LedgerRow[]>;
|
|
upsert(ref: ObjectRef, key: LedgerKey, values: LedgerRow): Promise<void>;
|
|
deleteRow(ref: ObjectRef, key: LedgerKey): Promise<void>;
|
|
|
|
/** 放行写的原子性:草稿合并与事件登记同一事务 */
|
|
transaction<T>(fn: (store: LedgerStore, drafts: DraftStore) => Promise<T>): Promise<T>;
|
|
};
|
|
|
|
/** 任务级草稿层 —— 推荐形态 ledger.__draft;物理形态可换,功能约束不可变(§7.2) */
|
|
export type DraftStore = {
|
|
list(taskId: string): Promise<Array<DraftEntry & ObjectRef>>;
|
|
listForObject(taskId: string, ref: ObjectRef): Promise<DraftEntry[]>;
|
|
put(taskId: string, ref: ObjectRef, entry: DraftEntry): Promise<void>;
|
|
/**
|
|
* 撤掉本单草稿层的**一行** —— 写错了得有退路(2026-08-01 加)。
|
|
*
|
|
* 只动 `taskId` 那一份,正式版碰不到。没有它的后果实测过:客户说本轮跳过的那颗料
|
|
* 被写进了有效清单,条目数报 9 而表里躺着 10 —— 判据正确地拦住,而模型改不动
|
|
* (唯一能改的是那个数,改了别的判据又不对),13 次拒回、23 拍、234k token 才熔断。
|
|
*/
|
|
drop(taskId: string, ref: ObjectRef, key: LedgerKey): Promise<void>;
|
|
/**
|
|
* 给本单草稿层的一行打上「已落地」记号(2026-08-27,数据工单确认即入库)。
|
|
*
|
|
* 那一行刚经一道更早的门并进了正式表:条目**留着**(它仍是本单写下的行,
|
|
* 任务视图 / `mine:` / `_rows` 照旧认它),只是放行时不再写它。
|
|
* `baseline` 换成落地后正式表里的值 —— 之后再往这一行写一笔(记号随之擦掉),
|
|
* 冲突检查比的才是「我改之前表里是什么」,而不是落地前那份早已过时的基线。
|
|
*/
|
|
markLanded(taskId: string, ref: ObjectRef, key: LedgerKey, baseline: LedgerRow): Promise<void>;
|
|
clear(taskId: string): Promise<void>;
|
|
};
|