M1: 底座 —— @contracts 首版 + event / ledger / org / llm
@contracts 首版(§8.1 九个文件): - id 品牌 ID / terminal 终态五名与归侧四标签 / envelope 信封六字段与四类事件 - card 工单两模式 + 对话卡族(形状对齐 2026-07-26 原型定稿) - contract7 契约七件 / ledger 三级寻址与写三分 / process-package 流程包 DSL 与触发器三类 - manifest 活动包清单六区(含 CMMN·DMN·步序声明的资产形状)/ org / api 路由契约 模块(L1): - event 信封存储、归属解析三级短路、投递五诺、监听注册表、三级消费裁定 - ledger schema 自生长(最大化合并/最宽类型/只增不破坏)、任务视图叠加、写三分、冲突检查 - org 岗位授权(客体三类×动作三种)、停用前置检查、会话、种子播种 - llm 四元绑定、ModelGateway 三模式(live/record/replay)—— 两缝之一 app 装配:Hono 服务 + 鉴权中间件 + 治理台/工作台路由;drizzle 迁移;AES-256-GCM 凭证密封 ADR-007 工具链与门禁 · ADR-008 投递队列 · ADR-009 凭证加密 (ADR 编号自 007 续:编码规范 §14 已用到 006,README 写「从 005 续」是笔误) 门禁五道全绿;96 个测试通过,含对真实 PG 的 ledger 集成测试 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m
This commit is contained in:
JCAI Main Agent
co-authored by
Claude Opus 5
Claude Opus 5
parent
7cd664af3a
commit
14d4fa046a
@@ -0,0 +1,37 @@
|
||||
# module: ledger
|
||||
|
||||
职责: 台账:三级寻址、通用事务接口、schema 自生长(最大化合并 / 最宽类型 / 只增不破坏)、
|
||||
任务级草稿层与任务视图、写三分、数据冲突检查
|
||||
不负责: 放行时机与落地预检的编排(见 release)、数据事件的投递与三级消费(见 event)、
|
||||
动作意向的执行(见 toolbox / release)
|
||||
|
||||
公开出口: index.ts
|
||||
- 类型:`LedgerService` `SystemWrite` `DraftWrite` `ReleaseWriteResult` `SchemaApplyResult`
|
||||
`ObjectAddress` `MergedObject` `MergeNotice` `MergeConflict` `ConflictFinding`
|
||||
- 错误:`DraftConflictError` `SchemaConflictError` `ObjectNotMaterializedError`
|
||||
- 端口类型:`LedgerStore` `DraftStore` `EventPublisher` `Clock` `IdGenerator` `ObjectRef`
|
||||
- 用例工厂:`createLedgerService(deps: LedgerServiceDeps): LedgerService`
|
||||
- 纯函数(供 activity-registry 静态审复用):`mergeDeclarations` `planSchemaChanges`
|
||||
`planIsNonDestructive` `widen` `overlay` `detectConflicts` `keyOf` `pickKey`
|
||||
- adapter 工厂:`createLedgerStore(pool)` `createDraftStore(runner)` `tableNameOf`
|
||||
`DRAFT_DDL` `DRAFT_TABLE`
|
||||
|
||||
层级: L1(编码规范 §4)
|
||||
依赖: @contracts;@shared/db(LEDGER_SCHEMA)
|
||||
port:`EventPublisher`(app 注入 event)、`Clock`、`IdGenerator`、`LedgerStore`、`DraftStore`
|
||||
被依赖: channel, release, activity-registry, loop-engine, flow-engine, task, trigger,
|
||||
app(治理台 · 数据管理路由)
|
||||
|
||||
不变量:
|
||||
- **写三分是三个方法**:`systemWrite` / `draftWrite` / `releaseWrite` —— 无第四条写入路径,
|
||||
调用方拿不到带 flag 的「绕门」形态(§12.5#9)
|
||||
- 正式版写入(system / release)**必**产生数据事件;草稿写**必不**产生
|
||||
- `releaseWrite` 先过数据冲突检查:任一冲突即抛 `DraftConflictError`,不做部分合并
|
||||
- 合并只增不破坏:`planSchemaChanges` 永不产出删列 / 缩窄;主键一经建立不得由声明变更
|
||||
- 同名异型取能兼容双方的最宽类型(integer→number→text;date→timestamp→text);
|
||||
`json` 与标量语义互斥 —— 拦下,交数据管理裁决
|
||||
- 脱敏取或:任一声明要求脱敏即脱敏(安全方向单调)
|
||||
- `ledger` schema 的唯一写者是本模块 adapter;SQL 拼接只在 `ledger-store.ts`,
|
||||
标识符过 `IDENT` 正则 + `quoteIdent`
|
||||
|
||||
影响半径: index/contract/port 未变 → 对外零影响
|
||||
@@ -0,0 +1,205 @@
|
||||
/**
|
||||
* ledger 集成测试 —— 对真实 PG 断言 schema 自生长与写三分(编码规范 §1 / §7.2)。
|
||||
* 系统内部机制不得 mock:这里跑的是真 DDL、真 DML、真事务。
|
||||
*/
|
||||
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
|
||||
import { Pool } from 'pg';
|
||||
import type { EnvelopeDraft, ObjectDeclaration, TaskId } from '@contracts';
|
||||
import { startItDatabase } from '@testing';
|
||||
import type { ItDatabase } from '@testing';
|
||||
import { createDraftStore, createLedgerStore, DRAFT_DDL } from '../internal/adapter/ledger-store.ts';
|
||||
import { createLedgerService } from '../internal/usecase/ledger-service.ts';
|
||||
import { DraftConflictError } from '../contract.ts';
|
||||
import type { LedgerService } from '../contract.ts';
|
||||
|
||||
// 顶层 await:可用性必须在**收集期**就定下来,否则 it.skip 的判定早于 beforeAll
|
||||
const database: ItDatabase | undefined = await startItDatabase();
|
||||
let pool: Pool | undefined;
|
||||
let ledger: LedgerService;
|
||||
let published: EnvelopeDraft[] = [];
|
||||
|
||||
const DOMAIN = 'it_quote';
|
||||
const OBJECT = 'intake';
|
||||
const T1 = 't-it-1' as TaskId;
|
||||
const T2 = 't-it-2' as TaskId;
|
||||
|
||||
const declaration = (fields: ObjectDeclaration['fields']): ObjectDeclaration => ({
|
||||
domain: DOMAIN,
|
||||
object: OBJECT,
|
||||
fields,
|
||||
});
|
||||
|
||||
beforeAll(async () => {
|
||||
if (database === undefined) return;
|
||||
pool = new Pool({ connectionString: database.url, max: 4 });
|
||||
await pool.query(`drop table if exists ledger."${DOMAIN}__${OBJECT}"`);
|
||||
await pool.query(DRAFT_DDL);
|
||||
await pool.query(`delete from ledger.__draft where task_id in ($1, $2)`, [T1, T2]);
|
||||
|
||||
let counter = 0;
|
||||
ledger = createLedgerService({
|
||||
store: createLedgerStore(pool),
|
||||
drafts: createDraftStore(pool),
|
||||
events: {
|
||||
publish: async (envelope) => {
|
||||
published.push(envelope);
|
||||
},
|
||||
},
|
||||
clock: { now: () => new Date('2026-07-27T12:00:00Z') },
|
||||
ids: { next: () => `it-${(counter += 1)}` },
|
||||
});
|
||||
}, 120_000);
|
||||
|
||||
afterAll(async () => {
|
||||
if (pool !== undefined) {
|
||||
await pool.query(`drop table if exists ledger."${DOMAIN}__${OBJECT}"`).catch(() => undefined);
|
||||
await pool.query(`delete from ledger.__draft where task_id in ($1, $2)`, [T1, T2]).catch(() => undefined);
|
||||
await pool.end();
|
||||
}
|
||||
await database?.stop();
|
||||
});
|
||||
|
||||
const itDb = () => (database === undefined ? it.skip : it);
|
||||
|
||||
|
||||
describe('ledger · 真实 PG', () => {
|
||||
itDb()('声明 → 建表;再声明 → 加列与加宽,只增不破坏', async () => {
|
||||
const first = await ledger.applyDeclarations([
|
||||
declaration([
|
||||
{ name: 'pn', type: 'text', primaryKey: true, masked: false },
|
||||
{ name: 'eau', type: 'integer', primaryKey: false, masked: false },
|
||||
]),
|
||||
]);
|
||||
expect(first[0]?.applied).toBe(true);
|
||||
|
||||
const described = await ledger.describe({ domain: DOMAIN, object: OBJECT });
|
||||
expect(described?.primaryKey).toEqual(['pn']);
|
||||
expect(described?.columns.map((c) => c.name).sort()).toEqual(['eau', 'pn']);
|
||||
|
||||
// 第二个活动声明:多一个字段,且 eau 用更宽的 number
|
||||
const second = await ledger.applyDeclarations([
|
||||
declaration([
|
||||
{ name: 'pn', type: 'text', primaryKey: true, masked: false },
|
||||
{ name: 'eau', type: 'number', primaryKey: false, masked: false },
|
||||
{ name: 'grade', type: 'text', primaryKey: false, masked: false },
|
||||
]),
|
||||
]);
|
||||
expect(second[0]?.applied).toBe(true);
|
||||
expect(second[0]?.notices.some((n) => n.kind === 'type-widened')).toBe(true);
|
||||
|
||||
const after = await ledger.describe({ domain: DOMAIN, object: OBJECT });
|
||||
expect(after?.columns.map((c) => c.name).sort()).toEqual(['eau', 'grade', 'pn']);
|
||||
expect(after?.columns.find((c) => c.name === 'eau')?.type).toBe('number');
|
||||
}, 60_000);
|
||||
|
||||
itDb()('系统写:落正式版并即时抛数据事件', async () => {
|
||||
published = [];
|
||||
await ledger.systemWrite({
|
||||
address: { domain: DOMAIN, object: OBJECT },
|
||||
key: { pn: 'LM358' },
|
||||
values: { eau: 1000, grade: 'A' },
|
||||
cause: { kind: 'inbound', ref: 'mail-1' },
|
||||
});
|
||||
expect(published).toHaveLength(1);
|
||||
expect(published[0]?.type).toBe('data');
|
||||
|
||||
const page = await ledger.query({
|
||||
address: { domain: DOMAIN, object: OBJECT },
|
||||
where: {},
|
||||
orderBy: [],
|
||||
limit: 50,
|
||||
offset: 0,
|
||||
});
|
||||
expect(page.rows).toHaveLength(1);
|
||||
expect(page.rows[0]).toMatchObject({ pn: 'LM358', grade: 'A' });
|
||||
}, 60_000);
|
||||
|
||||
itDb()('草稿写:读己之写,正式版不可见,零事件', async () => {
|
||||
published = [];
|
||||
await ledger.draftWrite({
|
||||
taskId: T1,
|
||||
address: { domain: DOMAIN, object: OBJECT },
|
||||
key: { pn: 'LM358' },
|
||||
patch: { grade: 'C' },
|
||||
});
|
||||
expect(published).toHaveLength(0);
|
||||
|
||||
const view = await ledger.taskView(T1, {
|
||||
address: { domain: DOMAIN, object: OBJECT },
|
||||
where: {},
|
||||
orderBy: [],
|
||||
limit: 50,
|
||||
offset: 0,
|
||||
});
|
||||
expect(view.rows[0]).toMatchObject({ pn: 'LM358', grade: 'C' });
|
||||
|
||||
// 正式版仍是 A —— 别的任务只见过门的事实
|
||||
const official = await ledger.query({
|
||||
address: { domain: DOMAIN, object: OBJECT },
|
||||
where: {},
|
||||
orderBy: [],
|
||||
limit: 50,
|
||||
offset: 0,
|
||||
});
|
||||
expect(official.rows[0]).toMatchObject({ grade: 'A' });
|
||||
|
||||
// 另一任务的任务视图也看不见 T1 的草稿
|
||||
const otherView = await ledger.taskView(T2, {
|
||||
address: { domain: DOMAIN, object: OBJECT },
|
||||
where: {},
|
||||
orderBy: [],
|
||||
limit: 50,
|
||||
offset: 0,
|
||||
});
|
||||
expect(otherView.rows[0]).toMatchObject({ grade: 'A' });
|
||||
}, 60_000);
|
||||
|
||||
itDb()('放行写:原子合并入正式版,此刻才抛事件,草稿清空', async () => {
|
||||
published = [];
|
||||
const result = await ledger.releaseWrite(T1);
|
||||
expect(result.mergedRows).toBe(1);
|
||||
expect(published).toHaveLength(1);
|
||||
|
||||
const official = await ledger.query({
|
||||
address: { domain: DOMAIN, object: OBJECT },
|
||||
where: {},
|
||||
orderBy: [],
|
||||
limit: 50,
|
||||
offset: 0,
|
||||
});
|
||||
expect(official.rows[0]).toMatchObject({ grade: 'C' });
|
||||
|
||||
// 草稿已清空:再放行是空操作
|
||||
expect(await ledger.releaseWrite(T1)).toEqual({ mergedRows: 0, emittedEvents: 0 });
|
||||
}, 60_000);
|
||||
|
||||
itDb()('数据冲突检查:他单已改同一字段 → 放行写打回,不做部分合并', async () => {
|
||||
await ledger.draftWrite({
|
||||
taskId: T2,
|
||||
address: { domain: DOMAIN, object: OBJECT },
|
||||
key: { pn: 'LM358' },
|
||||
patch: { grade: 'B' },
|
||||
});
|
||||
|
||||
// 他单(系统写)抢先改了同一字段
|
||||
await ledger.systemWrite({
|
||||
address: { domain: DOMAIN, object: OBJECT },
|
||||
key: { pn: 'LM358' },
|
||||
values: { grade: 'D' },
|
||||
cause: { kind: 'engine', ref: 'other-task' },
|
||||
});
|
||||
|
||||
expect(await ledger.checkConflicts(T2)).toHaveLength(1);
|
||||
await expect(ledger.releaseWrite(T2)).rejects.toBeInstanceOf(DraftConflictError);
|
||||
|
||||
// 正式版没被部分改动
|
||||
const official = await ledger.query({
|
||||
address: { domain: DOMAIN, object: OBJECT },
|
||||
where: {},
|
||||
orderBy: [],
|
||||
limit: 50,
|
||||
offset: 0,
|
||||
});
|
||||
expect(official.rows[0]).toMatchObject({ grade: 'D' });
|
||||
}, 60_000);
|
||||
});
|
||||
@@ -0,0 +1,219 @@
|
||||
/**
|
||||
* schema 自生长 —— 零 mock 全覆盖(编码规范 §7.2 明令)。
|
||||
*/
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import type { LedgerFieldType, ObjectDeclaration } from '@contracts';
|
||||
import {
|
||||
mergeDeclarations,
|
||||
planIsNonDestructive,
|
||||
planSchemaChanges,
|
||||
widen,
|
||||
} from '../internal/domain/schema-merge.ts';
|
||||
import type { MaterializedObject } from '../internal/domain/schema-merge.ts';
|
||||
|
||||
const f = (
|
||||
name: string,
|
||||
type: LedgerFieldType,
|
||||
extra: Partial<{ primaryKey: boolean; masked: boolean; label: string }> = {},
|
||||
) => ({
|
||||
name,
|
||||
type,
|
||||
primaryKey: extra.primaryKey ?? false,
|
||||
masked: extra.masked ?? false,
|
||||
...(extra.label === undefined ? {} : { label: extra.label }),
|
||||
});
|
||||
|
||||
const decl = (fields: ReturnType<typeof f>[]): ObjectDeclaration => ({
|
||||
domain: 'quote',
|
||||
object: 'intake',
|
||||
fields,
|
||||
});
|
||||
|
||||
describe('widen —— 类型格', () => {
|
||||
it('同型不加宽', () => {
|
||||
expect(widen('text', 'text')).toEqual({ ok: true, type: 'text', widened: false });
|
||||
});
|
||||
|
||||
it('integer + number → number', () => {
|
||||
expect(widen('integer', 'number')).toEqual({ ok: true, type: 'number', widened: true });
|
||||
expect(widen('number', 'integer')).toEqual({ ok: true, type: 'number', widened: true });
|
||||
});
|
||||
|
||||
it('date + timestamp → timestamp', () => {
|
||||
expect(widen('date', 'timestamp')).toEqual({ ok: true, type: 'timestamp', widened: true });
|
||||
});
|
||||
|
||||
it('跨链落到 text', () => {
|
||||
expect(widen('number', 'boolean')).toEqual({ ok: true, type: 'text', widened: true });
|
||||
expect(widen('date', 'integer')).toEqual({ ok: true, type: 'text', widened: true });
|
||||
});
|
||||
|
||||
it('json 与标量语义互斥,拦下', () => {
|
||||
expect(widen('json', 'text').ok).toBe(false);
|
||||
expect(widen('number', 'json').ok).toBe(false);
|
||||
});
|
||||
|
||||
it('json + json 可合', () => {
|
||||
expect(widen('json', 'json')).toEqual({ ok: true, type: 'json', widened: false });
|
||||
});
|
||||
|
||||
it('加宽可交换', () => {
|
||||
const types: LedgerFieldType[] = ['text', 'number', 'integer', 'boolean', 'date', 'timestamp'];
|
||||
for (const a of types)
|
||||
for (const b of types) {
|
||||
expect(widen(a, b)).toEqual(widen(b, a));
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('mergeDeclarations —— 最大化合并', () => {
|
||||
it('空声明集返回 undefined', () => {
|
||||
expect(mergeDeclarations([]).merged).toBeUndefined();
|
||||
});
|
||||
|
||||
it('并集取全部字段,首个声明定顺序', () => {
|
||||
const r = mergeDeclarations([
|
||||
decl([f('pn', 'text', { primaryKey: true }), f('eau', 'integer')]),
|
||||
decl([f('pn', 'text', { primaryKey: true }), f('target_price', 'number')]),
|
||||
]);
|
||||
expect(r.merged?.fields.map((x) => x.name)).toEqual(['pn', 'eau', 'target_price']);
|
||||
expect(r.conflicts).toEqual([]);
|
||||
});
|
||||
|
||||
it('同名异型取最宽类型,并留静态审提示', () => {
|
||||
const r = mergeDeclarations([decl([f('eau', 'integer')]), decl([f('eau', 'number')])]);
|
||||
expect(r.merged?.fields[0]?.type).toBe('number');
|
||||
expect(r.notices).toHaveLength(1);
|
||||
expect(r.notices[0]?.kind).toBe('type-widened');
|
||||
expect(r.conflicts).toEqual([]);
|
||||
});
|
||||
|
||||
it('互斥类型拦下报错', () => {
|
||||
const r = mergeDeclarations([decl([f('spec', 'json')]), decl([f('spec', 'text')])]);
|
||||
expect(r.conflicts).toHaveLength(1);
|
||||
expect(r.conflicts[0]?.kind).toBe('type-incompatible');
|
||||
});
|
||||
|
||||
it('主键取或', () => {
|
||||
const r = mergeDeclarations([decl([f('pn', 'text')]), decl([f('pn', 'text', { primaryKey: true })])]);
|
||||
expect(r.merged?.primaryKey).toEqual(['pn']);
|
||||
});
|
||||
|
||||
it('脱敏取或,方向单调', () => {
|
||||
const r = mergeDeclarations([decl([f('phone', 'text')]), decl([f('phone', 'text', { masked: true })])]);
|
||||
expect(r.merged?.fields[0]?.masked).toBe(true);
|
||||
expect(r.notices.some((n) => n.kind === 'masked-propagated')).toBe(true);
|
||||
});
|
||||
|
||||
it('名称冲突保留首个声明并提示', () => {
|
||||
const r = mergeDeclarations([
|
||||
decl([f('pn', 'text', { label: '料号' })]),
|
||||
decl([f('pn', 'text', { label: '型号' })]),
|
||||
]);
|
||||
expect(r.merged?.fields[0]?.label).toBe('料号');
|
||||
expect(r.notices.some((n) => n.kind === 'label-kept-first')).toBe(true);
|
||||
});
|
||||
|
||||
it('合并结果与声明顺序无关(类型与主键部分)', () => {
|
||||
const a = decl([f('x', 'integer'), f('y', 'date')]);
|
||||
const b = decl([f('x', 'number', { primaryKey: true }), f('y', 'timestamp')]);
|
||||
const ab = mergeDeclarations([a, b]).merged;
|
||||
const ba = mergeDeclarations([b, a]).merged;
|
||||
expect(ab?.fields.find((v) => v.name === 'x')?.type).toBe(ba?.fields.find((v) => v.name === 'x')?.type);
|
||||
expect(ab?.primaryKey).toEqual(ba?.primaryKey);
|
||||
});
|
||||
|
||||
it('拒绝混入别的对象', () => {
|
||||
expect(() =>
|
||||
mergeDeclarations([decl([f('a', 'text')]), { domain: 'quote', object: 'other', fields: [f('a', 'text')] }]),
|
||||
).toThrow(/只接受同一对象/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('planSchemaChanges —— 只增不破坏', () => {
|
||||
const target = mergeDeclarations([
|
||||
decl([f('pn', 'text', { primaryKey: true }), f('eau', 'number'), f('grade', 'text')]),
|
||||
]).merged!;
|
||||
|
||||
it('未物化 → 建表', () => {
|
||||
const plan = planSchemaChanges(target, undefined);
|
||||
expect(plan.changes).toHaveLength(1);
|
||||
expect(plan.changes[0]?.kind).toBe('create-table');
|
||||
expect(planIsNonDestructive(plan)).toBe(true);
|
||||
});
|
||||
|
||||
it('已物化缺列 → 加列', () => {
|
||||
const current: MaterializedObject = {
|
||||
domain: 'quote',
|
||||
object: 'intake',
|
||||
columns: [
|
||||
{ name: 'pn', type: 'text' },
|
||||
{ name: 'eau', type: 'number' },
|
||||
],
|
||||
primaryKey: ['pn'],
|
||||
};
|
||||
const plan = planSchemaChanges(target, current);
|
||||
expect(plan.changes).toEqual([
|
||||
{ kind: 'add-column', field: expect.objectContaining({ name: 'grade' }) },
|
||||
]);
|
||||
});
|
||||
|
||||
it('已物化窄类型 → 加宽,不缩窄', () => {
|
||||
const current: MaterializedObject = {
|
||||
domain: 'quote',
|
||||
object: 'intake',
|
||||
columns: [
|
||||
{ name: 'pn', type: 'text' },
|
||||
{ name: 'eau', type: 'integer' },
|
||||
{ name: 'grade', type: 'text' },
|
||||
],
|
||||
primaryKey: ['pn'],
|
||||
};
|
||||
const plan = planSchemaChanges(target, current);
|
||||
expect(plan.changes).toHaveLength(1);
|
||||
expect(plan.changes[0]).toMatchObject({ kind: 'widen-column', from: 'integer' });
|
||||
expect(planIsNonDestructive(plan)).toBe(true);
|
||||
});
|
||||
|
||||
it('已物化更宽 → 不产出任何变更(声明永不缩表)', () => {
|
||||
const current: MaterializedObject = {
|
||||
domain: 'quote',
|
||||
object: 'intake',
|
||||
columns: [
|
||||
{ name: 'pn', type: 'text' },
|
||||
{ name: 'eau', type: 'text' },
|
||||
{ name: 'grade', type: 'text' },
|
||||
],
|
||||
primaryKey: ['pn'],
|
||||
};
|
||||
expect(planSchemaChanges(target, current).changes).toEqual([]);
|
||||
});
|
||||
|
||||
it('声明试图新增主键字段 → 拦下', () => {
|
||||
const twoKeys = mergeDeclarations([
|
||||
decl([f('pn', 'text', { primaryKey: true }), f('rev', 'text', { primaryKey: true })]),
|
||||
]).merged!;
|
||||
const current: MaterializedObject = {
|
||||
domain: 'quote',
|
||||
object: 'intake',
|
||||
columns: [
|
||||
{ name: 'pn', type: 'text' },
|
||||
{ name: 'rev', type: 'text' },
|
||||
],
|
||||
primaryKey: ['pn'],
|
||||
};
|
||||
const plan = planSchemaChanges(twoKeys, current);
|
||||
expect(plan.conflicts[0]?.kind).toBe('primary-key-divergent');
|
||||
});
|
||||
|
||||
it('互斥类型在差分阶段也拦下', () => {
|
||||
const jsonTarget = mergeDeclarations([decl([f('spec', 'json')])]).merged!;
|
||||
const current: MaterializedObject = {
|
||||
domain: 'quote',
|
||||
object: 'intake',
|
||||
columns: [{ name: 'spec', type: 'text' }],
|
||||
primaryKey: [],
|
||||
};
|
||||
expect(planSchemaChanges(jsonTarget, current).conflicts[0]?.kind).toBe('type-incompatible');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,94 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import type { LedgerRow } from '@contracts';
|
||||
import { detectConflicts, keyOf, overlay, pickKey } from '../internal/domain/task-view.ts';
|
||||
import type { DraftEntry } from '../internal/domain/task-view.ts';
|
||||
|
||||
const PK = ['pn'];
|
||||
|
||||
const draft = (pn: string, patch: LedgerRow, baseline: LedgerRow = {}, tombstone = false): DraftEntry => ({
|
||||
key: { pn },
|
||||
patch,
|
||||
baseline,
|
||||
tombstone,
|
||||
});
|
||||
|
||||
describe('keyOf —— 主键规范化', () => {
|
||||
it('字段顺序不影响键', () => {
|
||||
expect(keyOf({ a: 1, b: 'x' })).toBe(keyOf({ b: 'x', a: 1 }));
|
||||
});
|
||||
});
|
||||
|
||||
describe('pickKey', () => {
|
||||
it('只取主键字段', () => {
|
||||
expect(pickKey({ pn: 'LM358', eau: 1000 }, PK)).toEqual({ pn: 'LM358' });
|
||||
});
|
||||
it('缺主键字段时跳过', () => {
|
||||
expect(pickKey({ eau: 1000 }, PK)).toEqual({});
|
||||
});
|
||||
});
|
||||
|
||||
describe('overlay —— 任务视图 = 正式版 + 本任务草稿层', () => {
|
||||
const official: LedgerRow[] = [
|
||||
{ pn: 'LM358', eau: 1000, grade: 'A' },
|
||||
{ pn: 'NE555', eau: 500, grade: 'B' },
|
||||
];
|
||||
|
||||
it('无草稿时视图 = 正式版', () => {
|
||||
expect(overlay(official, [], PK)).toEqual(official);
|
||||
});
|
||||
|
||||
it('读己之写:草稿字段覆盖正式版', () => {
|
||||
const rows = overlay(official, [draft('LM358', { grade: 'C' })], PK);
|
||||
expect(rows[0]).toEqual({ pn: 'LM358', eau: 1000, grade: 'C' });
|
||||
expect(rows[1]).toEqual(official[1]);
|
||||
});
|
||||
|
||||
it('草稿新增的行出现在视图里', () => {
|
||||
const rows = overlay(official, [draft('TL072', { eau: 200, grade: 'B' })], PK);
|
||||
expect(rows).toHaveLength(3);
|
||||
expect(rows[2]).toEqual({ pn: 'TL072', eau: 200, grade: 'B' });
|
||||
});
|
||||
|
||||
it('tombstone 的行从视图中消失', () => {
|
||||
const rows = overlay(official, [draft('NE555', {}, {}, true)], PK);
|
||||
expect(rows.map((r) => r['pn'])).toEqual(['LM358']);
|
||||
});
|
||||
|
||||
it('tombstone 的新增行不出现', () => {
|
||||
const rows = overlay(official, [draft('XX', { eau: 1 }, {}, true)], PK);
|
||||
expect(rows).toHaveLength(2);
|
||||
});
|
||||
});
|
||||
|
||||
describe('detectConflicts —— 落地预检第五项', () => {
|
||||
it('基线与正式版一致 → 无冲突', () => {
|
||||
const officialByKey = new Map([[keyOf({ pn: 'LM358' }), { pn: 'LM358', grade: 'A' }]]);
|
||||
expect(detectConflicts([draft('LM358', { grade: 'C' }, { grade: 'A' })], officialByKey)).toEqual([]);
|
||||
});
|
||||
|
||||
it('他单已改同一字段 → 冲突', () => {
|
||||
const officialByKey = new Map([[keyOf({ pn: 'LM358' }), { pn: 'LM358', grade: 'B' }]]);
|
||||
const findings = detectConflicts([draft('LM358', { grade: 'C' }, { grade: 'A' })], officialByKey);
|
||||
expect(findings).toHaveLength(1);
|
||||
expect(findings[0]).toMatchObject({ field: 'grade', baseline: 'A', official: 'B', draft: 'C' });
|
||||
});
|
||||
|
||||
it('没碰的字段被别人改了不算冲突', () => {
|
||||
const officialByKey = new Map([[keyOf({ pn: 'LM358' }), { pn: 'LM358', grade: 'A', eau: 2000 }]]);
|
||||
expect(detectConflicts([draft('LM358', { grade: 'C' }, { grade: 'A' })], officialByKey)).toEqual([]);
|
||||
});
|
||||
|
||||
it('草稿新增的行无从冲突', () => {
|
||||
expect(detectConflicts([draft('NEW', { grade: 'C' }, {})], new Map())).toEqual([]);
|
||||
});
|
||||
|
||||
it('null 与 undefined 视为同值', () => {
|
||||
const officialByKey = new Map([[keyOf({ pn: 'LM358' }), { pn: 'LM358', grade: null }]]);
|
||||
expect(detectConflicts([draft('LM358', { grade: 'C' }, { grade: undefined })], officialByKey)).toEqual([]);
|
||||
});
|
||||
|
||||
it('数字与其字符串形态视为同值(PG 回读的宽容口径)', () => {
|
||||
const officialByKey = new Map([[keyOf({ pn: 'LM358' }), { pn: 'LM358', eau: '1000' }]]);
|
||||
expect(detectConflicts([draft('LM358', { eau: 2000 }, { eau: 1000 })], officialByKey)).toEqual([]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,96 @@
|
||||
/**
|
||||
* module: ledger —— 对外类型(编码规范 §10.1)。只有类型和常量,没有实现。
|
||||
*/
|
||||
import type {
|
||||
LedgerAddress,
|
||||
LedgerKey,
|
||||
LedgerPage,
|
||||
LedgerQuery,
|
||||
LedgerRow,
|
||||
ObjectDeclaration,
|
||||
TaskId,
|
||||
WriteKind,
|
||||
} from '@contracts';
|
||||
import type { MaterializedObject, MergeConflict, MergeNotice, MergedObject } from './internal/domain/schema-merge.ts';
|
||||
import type { ConflictFinding } from './internal/domain/task-view.ts';
|
||||
|
||||
export type { LedgerAddress, LedgerKey, LedgerPage, LedgerQuery, LedgerRow, ObjectDeclaration, WriteKind };
|
||||
export type { MaterializedObject, MergeConflict, MergeNotice, MergedObject, ConflictFinding };
|
||||
|
||||
export class DraftConflictError extends Error {
|
||||
constructor(readonly findings: readonly ConflictFinding[]) {
|
||||
super(`草稿与正式版并发冲突:${findings.length} 处字段已被他单改动`);
|
||||
this.name = 'DraftConflictError';
|
||||
}
|
||||
}
|
||||
|
||||
export class SchemaConflictError extends Error {
|
||||
constructor(readonly conflicts: readonly MergeConflict[]) {
|
||||
super(`台账声明语义互斥,交数据管理裁决:${conflicts.map((c) => `${c.field}(${c.message})`).join('; ')}`);
|
||||
this.name = 'SchemaConflictError';
|
||||
}
|
||||
}
|
||||
|
||||
export class ObjectNotMaterializedError extends Error {
|
||||
constructor(readonly address: string) {
|
||||
super(`台账对象未物化:${address}`);
|
||||
this.name = 'ObjectNotMaterializedError';
|
||||
}
|
||||
}
|
||||
|
||||
/** 声明合并与物化的结果 —— 安装静态审读它:conflicts 非空即不上架 */
|
||||
export type SchemaApplyResult = {
|
||||
readonly merged: MergedObject | undefined;
|
||||
readonly notices: readonly MergeNotice[];
|
||||
readonly conflicts: readonly MergeConflict[];
|
||||
readonly applied: boolean;
|
||||
};
|
||||
|
||||
export type ObjectAddress = { readonly domain: string; readonly object: string };
|
||||
|
||||
export type SystemWrite = {
|
||||
readonly address: ObjectAddress;
|
||||
readonly key: LedgerKey;
|
||||
readonly values: LedgerRow;
|
||||
/** 归因:哪条入站 / 哪次流转产生了这次系统写 */
|
||||
readonly cause: { readonly kind: 'inbound' | 'engine' | 'governance'; readonly ref: string };
|
||||
/** 系统写也可挂到任务上(入站归一到某任务),数据事件的目标即它 */
|
||||
readonly taskId?: TaskId;
|
||||
};
|
||||
|
||||
export type DraftWrite = {
|
||||
readonly taskId: TaskId;
|
||||
readonly address: ObjectAddress;
|
||||
readonly key: LedgerKey;
|
||||
readonly patch: LedgerRow;
|
||||
readonly tombstone?: boolean;
|
||||
};
|
||||
|
||||
export type ReleaseWriteResult = {
|
||||
readonly mergedRows: number;
|
||||
readonly emittedEvents: number;
|
||||
};
|
||||
|
||||
/**
|
||||
* 写三分是**三个不同方法**,不是一个带 flag 的方法 —— 调用方拿不到「绕门」的形态(§7.2)。
|
||||
* systemWrite —— 登记世界已发生的事实,不过放行门,写正式版并**即时**抛数据事件
|
||||
* draftWrite —— 任务级草稿层,读己之写,**不抛**事件
|
||||
* releaseWrite —— 放行通过,草稿合并入正式版,**此刻**抛数据事件;原子且过冲突检查
|
||||
*/
|
||||
export type LedgerService = {
|
||||
applyDeclarations(declarations: readonly ObjectDeclaration[]): Promise<SchemaApplyResult[]>;
|
||||
describe(address: ObjectAddress): Promise<MaterializedObject | undefined>;
|
||||
listObjects(): Promise<ObjectAddress[]>;
|
||||
|
||||
systemWrite(write: SystemWrite): Promise<void>;
|
||||
draftWrite(write: DraftWrite): Promise<void>;
|
||||
releaseWrite(taskId: TaskId): Promise<ReleaseWriteResult>;
|
||||
|
||||
/** 正式版查询 —— 跨任务只见过门的事实 */
|
||||
query(query: LedgerQuery): Promise<LedgerPage>;
|
||||
/** 任务视图 = 正式版 + 本任务草稿层 */
|
||||
taskView(taskId: TaskId, query: LedgerQuery): Promise<LedgerPage>;
|
||||
/** 落地预检第五项:数据冲突检查 */
|
||||
checkConflicts(taskId: TaskId): Promise<ConflictFinding[]>;
|
||||
discardDrafts(taskId: TaskId): Promise<void>;
|
||||
};
|
||||
@@ -0,0 +1,47 @@
|
||||
/**
|
||||
* module: ledger —— 唯一出口。只做 re-export,不写逻辑(编码规范 §10.1)。
|
||||
*/
|
||||
export type {
|
||||
ConflictFinding,
|
||||
DraftWrite,
|
||||
LedgerAddress,
|
||||
LedgerKey,
|
||||
LedgerPage,
|
||||
LedgerQuery,
|
||||
LedgerRow,
|
||||
LedgerService,
|
||||
MaterializedObject,
|
||||
MergeConflict,
|
||||
MergeNotice,
|
||||
MergedObject,
|
||||
ObjectAddress,
|
||||
ObjectDeclaration,
|
||||
ReleaseWriteResult,
|
||||
SchemaApplyResult,
|
||||
SystemWrite,
|
||||
WriteKind,
|
||||
} from './contract.ts';
|
||||
export { DraftConflictError, ObjectNotMaterializedError, SchemaConflictError } from './contract.ts';
|
||||
|
||||
export type { Clock, DraftStore, EventPublisher, IdGenerator, LedgerStore, ObjectRef } from './port.ts';
|
||||
|
||||
export type { LedgerServiceDeps } from './internal/usecase/ledger-service.ts';
|
||||
export { createLedgerService } from './internal/usecase/ledger-service.ts';
|
||||
|
||||
export type {
|
||||
MergedField,
|
||||
SchemaChange,
|
||||
SchemaPlan,
|
||||
WidenResult,
|
||||
} from './internal/domain/schema-merge.ts';
|
||||
export {
|
||||
mergeDeclarations,
|
||||
planIsNonDestructive,
|
||||
planSchemaChanges,
|
||||
widen,
|
||||
} from './internal/domain/schema-merge.ts';
|
||||
|
||||
export type { DraftEntry } from './internal/domain/task-view.ts';
|
||||
export { detectConflicts, keyOf, overlay, pickKey } from './internal/domain/task-view.ts';
|
||||
|
||||
export { createDraftStore, createLedgerStore, DRAFT_DDL, DRAFT_TABLE, tableNameOf } from './internal/adapter/ledger-store.ts';
|
||||
@@ -0,0 +1,303 @@
|
||||
/**
|
||||
* 台账存储 adapter —— node-postgres 直写(编码规范 §1 / ADR-002)。
|
||||
*
|
||||
* 运行时 DDL/DML 由声明生成,ORM 静态 schema 不适用;`ledger` schema 的**唯一写者**就是本文件。
|
||||
* 标识符全部来自 @contracts 的 identifier 正则(小写字母开头、字母数字下划线),
|
||||
* 落库前再过一道 `quoteIdent` —— 拼接 SQL 的地方只有这里。
|
||||
*/
|
||||
import type { Pool, PoolClient } from 'pg';
|
||||
import type { LedgerKey, LedgerQuery, LedgerRow } from '@contracts';
|
||||
import { LEDGER_SCHEMA } from '@shared/db.ts';
|
||||
import type { DraftStore, LedgerStore, ObjectRef } from '../../port.ts';
|
||||
import type { MaterializedObject, MergedField } from '../domain/schema-merge.ts';
|
||||
import type { DraftEntry } from '../domain/task-view.ts';
|
||||
import { keyOf } from '../domain/task-view.ts';
|
||||
|
||||
const IDENT = /^[a-z][a-z0-9_]*$/;
|
||||
|
||||
function quoteIdent(name: string): string {
|
||||
if (!IDENT.test(name)) throw new Error(`非法标识符:${name}`);
|
||||
return `"${name}"`;
|
||||
}
|
||||
|
||||
/** 物理表名:<域>__<对象>;域与对象都过 IDENT,拼接安全 */
|
||||
export function tableNameOf(ref: ObjectRef): string {
|
||||
if (!IDENT.test(ref.domain) || !IDENT.test(ref.object)) {
|
||||
throw new Error(`非法台账地址:${ref.domain}.${ref.object}`);
|
||||
}
|
||||
return `${ref.domain}__${ref.object}`;
|
||||
}
|
||||
|
||||
const PG_TYPE: Readonly<Record<MergedField['type'], string>> = {
|
||||
text: 'text',
|
||||
number: 'double precision',
|
||||
integer: 'bigint',
|
||||
boolean: 'boolean',
|
||||
date: 'date',
|
||||
timestamp: 'timestamptz',
|
||||
json: 'jsonb',
|
||||
};
|
||||
|
||||
const FROM_PG: Readonly<Record<string, MergedField['type']>> = {
|
||||
text: 'text',
|
||||
'character varying': 'text',
|
||||
'double precision': 'number',
|
||||
numeric: 'number',
|
||||
bigint: 'integer',
|
||||
integer: 'integer',
|
||||
boolean: 'boolean',
|
||||
date: 'date',
|
||||
'timestamp with time zone': 'timestamp',
|
||||
'timestamp without time zone': 'timestamp',
|
||||
jsonb: 'json',
|
||||
json: 'json',
|
||||
};
|
||||
|
||||
type Queryable = Pick<Pool | PoolClient, 'query'>;
|
||||
|
||||
export function createLedgerStore(pool: Pool): LedgerStore {
|
||||
return buildStore(pool, pool);
|
||||
}
|
||||
|
||||
function buildStore(runner: Queryable, pool: Pool): LedgerStore {
|
||||
const store: LedgerStore = {
|
||||
async describe(ref) {
|
||||
const table = tableNameOf(ref);
|
||||
const cols = await runner.query<{ column_name: string; data_type: string }>(
|
||||
`select column_name, data_type from information_schema.columns
|
||||
where table_schema = $1 and table_name = $2 order by ordinal_position`,
|
||||
[LEDGER_SCHEMA, table],
|
||||
);
|
||||
if (cols.rows.length === 0) return undefined;
|
||||
|
||||
const pk = await runner.query<{ attname: string }>(
|
||||
`select a.attname from pg_index i
|
||||
join pg_attribute a on a.attrelid = i.indrelid and a.attnum = any(i.indkey)
|
||||
where i.indrelid = $1::regclass and i.indisprimary`,
|
||||
[`${LEDGER_SCHEMA}.${quoteIdent(table)}`],
|
||||
);
|
||||
|
||||
const materialized: MaterializedObject = {
|
||||
domain: ref.domain,
|
||||
object: ref.object,
|
||||
columns: cols.rows.map((c) => ({ name: c.column_name, type: FROM_PG[c.data_type] ?? 'text' })),
|
||||
primaryKey: pk.rows.map((p) => p.attname),
|
||||
};
|
||||
return materialized;
|
||||
},
|
||||
|
||||
async listObjects() {
|
||||
const res = await runner.query<{ table_name: string }>(
|
||||
`select table_name from information_schema.tables
|
||||
where table_schema = $1 and table_name not like '\\_\\_%' order by table_name`,
|
||||
[LEDGER_SCHEMA],
|
||||
);
|
||||
return res.rows.flatMap((r) => {
|
||||
const idx = r.table_name.indexOf('__');
|
||||
if (idx <= 0) return [];
|
||||
return [{ domain: r.table_name.slice(0, idx), object: r.table_name.slice(idx + 2) }];
|
||||
});
|
||||
},
|
||||
|
||||
async applyChanges(ref, changes) {
|
||||
const table = `${LEDGER_SCHEMA}.${quoteIdent(tableNameOf(ref))}`;
|
||||
for (const change of changes) {
|
||||
switch (change.kind) {
|
||||
case 'create-table': {
|
||||
const cols = change.object.fields.map((f) => `${quoteIdent(f.name)} ${PG_TYPE[f.type]}`);
|
||||
const pk =
|
||||
change.object.primaryKey.length > 0
|
||||
? `, primary key (${change.object.primaryKey.map(quoteIdent).join(', ')})`
|
||||
: '';
|
||||
await runner.query(`create table if not exists ${table} (${cols.join(', ')}${pk})`);
|
||||
break;
|
||||
}
|
||||
case 'add-column':
|
||||
await runner.query(
|
||||
`alter table ${table} add column if not exists ${quoteIdent(change.field.name)} ${PG_TYPE[change.field.type]}`,
|
||||
);
|
||||
break;
|
||||
case 'widen-column':
|
||||
await runner.query(
|
||||
`alter table ${table} alter column ${quoteIdent(change.field.name)} type ${PG_TYPE[change.field.type]} ` +
|
||||
`using ${quoteIdent(change.field.name)}::${PG_TYPE[change.field.type]}`,
|
||||
);
|
||||
break;
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
async select(query: LedgerQuery) {
|
||||
const table = `${LEDGER_SCHEMA}.${quoteIdent(tableNameOf(query.address))}`;
|
||||
const params: unknown[] = [];
|
||||
const clauses = Object.entries(query.where).map(([field, value]) => {
|
||||
params.push(value);
|
||||
return `${quoteIdent(field)} = $${params.length}`;
|
||||
});
|
||||
const where = clauses.length > 0 ? ` where ${clauses.join(' and ')}` : '';
|
||||
const order =
|
||||
query.orderBy.length > 0
|
||||
? ` order by ${query.orderBy.map((o) => `${quoteIdent(o.field)} ${o.dir === 'desc' ? 'desc' : 'asc'}`).join(', ')}`
|
||||
: '';
|
||||
|
||||
const countRes = await runner.query<{ n: string }>(`select count(*)::text as n from ${table}${where}`, params);
|
||||
params.push(query.limit, query.offset);
|
||||
const rows = await runner.query<LedgerRow>(
|
||||
`select * from ${table}${where}${order} limit $${params.length - 1} offset $${params.length}`,
|
||||
params,
|
||||
);
|
||||
return { rows: rows.rows, total: Number(countRes.rows[0]?.n ?? '0') };
|
||||
},
|
||||
|
||||
async selectByKeys(ref, keys) {
|
||||
if (keys.length === 0) return [];
|
||||
const table = `${LEDGER_SCHEMA}.${quoteIdent(tableNameOf(ref))}`;
|
||||
const out: LedgerRow[] = [];
|
||||
for (const key of keys) {
|
||||
const params: unknown[] = [];
|
||||
const clauses = Object.entries(key).map(([field, value]) => {
|
||||
params.push(value);
|
||||
return `${quoteIdent(field)} = $${params.length}`;
|
||||
});
|
||||
if (clauses.length === 0) continue;
|
||||
const res = await runner.query<LedgerRow>(
|
||||
`select * from ${table} where ${clauses.join(' and ')} limit 1`,
|
||||
params,
|
||||
);
|
||||
out.push(...res.rows);
|
||||
}
|
||||
return out;
|
||||
},
|
||||
|
||||
async upsert(ref, key, values) {
|
||||
const table = `${LEDGER_SCHEMA}.${quoteIdent(tableNameOf(ref))}`;
|
||||
const merged: LedgerRow = { ...key, ...values };
|
||||
const fields = Object.keys(merged);
|
||||
if (fields.length === 0) return;
|
||||
const params = fields.map((f) => merged[f]);
|
||||
const placeholders = fields.map((_, i) => `$${i + 1}`);
|
||||
const keyFields = Object.keys(key);
|
||||
const updatable = fields.filter((f) => !keyFields.includes(f));
|
||||
const onConflict =
|
||||
keyFields.length === 0
|
||||
? ''
|
||||
: updatable.length === 0
|
||||
? ` on conflict (${keyFields.map(quoteIdent).join(', ')}) do nothing`
|
||||
: ` on conflict (${keyFields.map(quoteIdent).join(', ')}) do update set ` +
|
||||
updatable.map((f) => `${quoteIdent(f)} = excluded.${quoteIdent(f)}`).join(', ');
|
||||
await runner.query(
|
||||
`insert into ${table} (${fields.map(quoteIdent).join(', ')}) values (${placeholders.join(', ')})${onConflict}`,
|
||||
params,
|
||||
);
|
||||
},
|
||||
|
||||
async deleteRow(ref, key) {
|
||||
const table = `${LEDGER_SCHEMA}.${quoteIdent(tableNameOf(ref))}`;
|
||||
const params: unknown[] = [];
|
||||
const clauses = Object.entries(key).map(([field, value]) => {
|
||||
params.push(value);
|
||||
return `${quoteIdent(field)} = $${params.length}`;
|
||||
});
|
||||
if (clauses.length === 0) return;
|
||||
await runner.query(`delete from ${table} where ${clauses.join(' and ')}`, params);
|
||||
},
|
||||
|
||||
async transaction(fn) {
|
||||
const client = await pool.connect();
|
||||
try {
|
||||
await client.query('begin');
|
||||
const scoped = buildStore(client, pool);
|
||||
const result = await fn(scoped, createDraftStore(client));
|
||||
await client.query('commit');
|
||||
return result;
|
||||
} catch (error) {
|
||||
await client.query('rollback');
|
||||
throw error;
|
||||
} finally {
|
||||
client.release();
|
||||
}
|
||||
},
|
||||
};
|
||||
return store;
|
||||
}
|
||||
|
||||
/* ── 任务级草稿层:ledger.__draft ─────────────────────────────────────── */
|
||||
|
||||
export const DRAFT_TABLE = `${LEDGER_SCHEMA}.__draft`;
|
||||
|
||||
export const DRAFT_DDL = `
|
||||
create table if not exists ${DRAFT_TABLE} (
|
||||
task_id text not null,
|
||||
domain text not null,
|
||||
object text not null,
|
||||
key_hash text not null,
|
||||
key jsonb not null,
|
||||
patch jsonb not null,
|
||||
baseline jsonb not null,
|
||||
tombstone boolean not null default false,
|
||||
updated_at timestamptz not null default now(),
|
||||
primary key (task_id, domain, object, key_hash)
|
||||
);`;
|
||||
|
||||
type DraftRow = {
|
||||
task_id: string;
|
||||
domain: string;
|
||||
object: string;
|
||||
key: Record<string, string | number>;
|
||||
patch: LedgerRow;
|
||||
baseline: LedgerRow;
|
||||
tombstone: boolean;
|
||||
};
|
||||
|
||||
function toEntry(row: DraftRow): DraftEntry & ObjectRef {
|
||||
return {
|
||||
domain: row.domain,
|
||||
object: row.object,
|
||||
key: row.key,
|
||||
patch: row.patch,
|
||||
baseline: row.baseline,
|
||||
tombstone: row.tombstone,
|
||||
};
|
||||
}
|
||||
|
||||
export function createDraftStore(runner: Queryable): DraftStore {
|
||||
return {
|
||||
async list(taskId) {
|
||||
const res = await runner.query<DraftRow>(
|
||||
`select * from ${DRAFT_TABLE} where task_id = $1 order by updated_at`,
|
||||
[taskId],
|
||||
);
|
||||
return res.rows.map(toEntry);
|
||||
},
|
||||
async listForObject(taskId, ref) {
|
||||
const res = await runner.query<DraftRow>(
|
||||
`select * from ${DRAFT_TABLE} where task_id = $1 and domain = $2 and object = $3 order by updated_at`,
|
||||
[taskId, ref.domain, ref.object],
|
||||
);
|
||||
return res.rows.map(toEntry);
|
||||
},
|
||||
async put(taskId, ref, entry) {
|
||||
await runner.query(
|
||||
`insert into ${DRAFT_TABLE} (task_id, domain, object, key_hash, key, patch, baseline, tombstone)
|
||||
values ($1,$2,$3,$4,$5,$6,$7,$8)
|
||||
on conflict (task_id, domain, object, key_hash) do update
|
||||
set patch = ${DRAFT_TABLE}.patch || excluded.patch,
|
||||
tombstone = excluded.tombstone,
|
||||
updated_at = now()`,
|
||||
[
|
||||
taskId,
|
||||
ref.domain,
|
||||
ref.object,
|
||||
keyOf(entry.key as LedgerKey),
|
||||
JSON.stringify(entry.key),
|
||||
JSON.stringify(entry.patch),
|
||||
JSON.stringify(entry.baseline),
|
||||
entry.tombstone,
|
||||
],
|
||||
);
|
||||
},
|
||||
async clear(taskId) {
|
||||
await runner.query(`delete from ${DRAFT_TABLE} where task_id = $1`, [taskId]);
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,267 @@
|
||||
/**
|
||||
* 台账 schema 自生长 —— 纯算法,零 IO(编码规范 §7.2:落此文件,零 mock 全覆盖测试)。
|
||||
*
|
||||
* 语义出处 OS 04 / AM 11.1:
|
||||
* 声明的是**活动要用什么字段**,不是对象该定义什么字段;
|
||||
* 对象的实际 schema = 全部使用声明的**最大化合并**(并集);
|
||||
* 定义**只增不破坏**:声明永不缩表、不删改已有字段;
|
||||
* 同名字段类型不一致时,以**能兼容双方的最宽类型**落地(放宽即增,不破坏),静态审提示、不阻塞;
|
||||
* **语义互斥**不可兼容的极端情形才拦下,交数据管理裁决。
|
||||
*/
|
||||
import type { FieldDeclaration, LedgerFieldType, ObjectDeclaration } from '@contracts';
|
||||
|
||||
/* ── 类型格:widen(a, b) = 能同时容纳 a 与 b 的最窄类型 ────────────────── */
|
||||
|
||||
/**
|
||||
* 标量的加宽链:
|
||||
* integer → number → text
|
||||
* date → timestamp → text
|
||||
* boolean → text
|
||||
* `json` 是容器类型,与任何标量**语义互斥** —— 不加宽,直接拦下。
|
||||
*/
|
||||
const SCALAR_CHAIN: Readonly<Record<LedgerFieldType, readonly LedgerFieldType[]>> = {
|
||||
integer: ['integer', 'number', 'text'],
|
||||
number: ['number', 'text'],
|
||||
date: ['date', 'timestamp', 'text'],
|
||||
timestamp: ['timestamp', 'text'],
|
||||
boolean: ['boolean', 'text'],
|
||||
text: ['text'],
|
||||
json: ['json'],
|
||||
};
|
||||
|
||||
export type WidenResult =
|
||||
| { readonly ok: true; readonly type: LedgerFieldType; readonly widened: boolean }
|
||||
| { readonly ok: false; readonly reason: string };
|
||||
|
||||
export function widen(a: LedgerFieldType, b: LedgerFieldType): WidenResult {
|
||||
if (a === b) return { ok: true, type: a, widened: false };
|
||||
if (a === 'json' || b === 'json') {
|
||||
return { ok: false, reason: `json 与 ${a === 'json' ? b : a} 语义互斥,不可兼容` };
|
||||
}
|
||||
// 取两条链的最靠前的公共上界
|
||||
for (const candidate of SCALAR_CHAIN[a]) {
|
||||
if (SCALAR_CHAIN[b].includes(candidate)) {
|
||||
return { ok: true, type: candidate, widened: true };
|
||||
}
|
||||
}
|
||||
/* istanbul ignore next —— text 是标量的公共顶,理论不可达 */
|
||||
return { ok: false, reason: `${a} 与 ${b} 无公共上界` };
|
||||
}
|
||||
|
||||
/* ── 合并结果 ───────────────────────────────────────────────────────── */
|
||||
|
||||
export type MergedField = {
|
||||
readonly name: string;
|
||||
readonly type: LedgerFieldType;
|
||||
readonly label: string | undefined;
|
||||
readonly primaryKey: boolean;
|
||||
readonly masked: boolean;
|
||||
};
|
||||
|
||||
export type MergeNotice = {
|
||||
readonly kind: 'type-widened' | 'masked-propagated' | 'label-kept-first';
|
||||
readonly field: string;
|
||||
readonly message: string;
|
||||
};
|
||||
|
||||
export type MergeConflict = {
|
||||
readonly kind: 'type-incompatible' | 'primary-key-divergent';
|
||||
readonly field: string;
|
||||
readonly message: string;
|
||||
};
|
||||
|
||||
export type MergedObject = {
|
||||
readonly domain: string;
|
||||
readonly object: string;
|
||||
readonly label: string | undefined;
|
||||
readonly fields: readonly MergedField[];
|
||||
readonly primaryKey: readonly string[];
|
||||
};
|
||||
|
||||
export type MergeResult = {
|
||||
readonly merged: MergedObject | undefined;
|
||||
/** 静态审提示,不阻塞 */
|
||||
readonly notices: readonly MergeNotice[];
|
||||
/** 语义互斥 —— 拦下,交数据管理裁决 */
|
||||
readonly conflicts: readonly MergeConflict[];
|
||||
};
|
||||
|
||||
function mergeField(
|
||||
acc: MergedField,
|
||||
next: FieldDeclaration,
|
||||
notices: MergeNotice[],
|
||||
conflicts: MergeConflict[],
|
||||
): MergedField {
|
||||
const w = widen(acc.type, next.type);
|
||||
if (!w.ok) {
|
||||
conflicts.push({ kind: 'type-incompatible', field: acc.name, message: w.reason });
|
||||
return acc;
|
||||
}
|
||||
if (w.widened) {
|
||||
notices.push({
|
||||
kind: 'type-widened',
|
||||
field: acc.name,
|
||||
message: `同名异型 ${acc.type} + ${next.type} → 取最宽类型 ${w.type}(放宽即增,不破坏)`,
|
||||
});
|
||||
}
|
||||
// 脱敏取或:任一声明要求脱敏即脱敏(安全方向单调)
|
||||
const masked = acc.masked || next.masked;
|
||||
if (masked && !acc.masked) {
|
||||
notices.push({ kind: 'masked-propagated', field: acc.name, message: '任一声明要求脱敏即脱敏' });
|
||||
}
|
||||
if (next.label !== undefined && acc.label !== undefined && next.label !== acc.label) {
|
||||
notices.push({
|
||||
kind: 'label-kept-first',
|
||||
field: acc.name,
|
||||
message: `字段名称冲突(${acc.label} / ${next.label}),保留首个声明`,
|
||||
});
|
||||
}
|
||||
return {
|
||||
name: acc.name,
|
||||
type: w.type,
|
||||
label: acc.label ?? next.label,
|
||||
// 主键参与取或:任一声明视其为主键即入主键集
|
||||
primaryKey: acc.primaryKey || next.primaryKey,
|
||||
masked,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 最大化合并:把同一个「域.对象」的**全部**使用声明合成一份对象 schema。
|
||||
* 声明顺序不影响结果(合并是可交换、可结合的)——除标签保留首个声明外。
|
||||
*/
|
||||
export function mergeDeclarations(declarations: readonly ObjectDeclaration[]): MergeResult {
|
||||
const notices: MergeNotice[] = [];
|
||||
const conflicts: MergeConflict[] = [];
|
||||
|
||||
const first = declarations[0];
|
||||
if (first === undefined) return { merged: undefined, notices, conflicts };
|
||||
|
||||
for (const d of declarations) {
|
||||
if (d.domain !== first.domain || d.object !== first.object) {
|
||||
throw new Error(`mergeDeclarations 只接受同一对象的声明:${d.domain}.${d.object} ≠ ${first.domain}.${first.object}`);
|
||||
}
|
||||
}
|
||||
|
||||
const byName = new Map<string, MergedField>();
|
||||
const order: string[] = [];
|
||||
|
||||
for (const declaration of declarations) {
|
||||
for (const field of declaration.fields) {
|
||||
const existing = byName.get(field.name);
|
||||
if (existing === undefined) {
|
||||
order.push(field.name);
|
||||
byName.set(field.name, {
|
||||
name: field.name,
|
||||
type: field.type,
|
||||
label: field.label,
|
||||
primaryKey: field.primaryKey,
|
||||
masked: field.masked,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
byName.set(field.name, mergeField(existing, field, notices, conflicts));
|
||||
}
|
||||
}
|
||||
|
||||
const fields = order.map((name) => byName.get(name)!);
|
||||
const primaryKey = fields.filter((f) => f.primaryKey).map((f) => f.name);
|
||||
|
||||
return {
|
||||
merged: {
|
||||
domain: first.domain,
|
||||
object: first.object,
|
||||
label: declarations.find((d) => d.label !== undefined)?.label,
|
||||
fields,
|
||||
primaryKey,
|
||||
},
|
||||
notices,
|
||||
conflicts,
|
||||
};
|
||||
}
|
||||
|
||||
/* ── 与已物化 schema 的差分:生成「只增不破坏」的变更计划 ─────────────── */
|
||||
|
||||
export type MaterializedColumn = {
|
||||
readonly name: string;
|
||||
readonly type: LedgerFieldType;
|
||||
};
|
||||
|
||||
export type MaterializedObject = {
|
||||
readonly domain: string;
|
||||
readonly object: string;
|
||||
readonly columns: readonly MaterializedColumn[];
|
||||
readonly primaryKey: readonly string[];
|
||||
};
|
||||
|
||||
export type SchemaChange =
|
||||
| { readonly kind: 'create-table'; readonly object: MergedObject }
|
||||
| { readonly kind: 'add-column'; readonly field: MergedField }
|
||||
| { readonly kind: 'widen-column'; readonly field: MergedField; readonly from: LedgerFieldType };
|
||||
|
||||
export type SchemaPlan = {
|
||||
readonly changes: readonly SchemaChange[];
|
||||
readonly notices: readonly MergeNotice[];
|
||||
readonly conflicts: readonly MergeConflict[];
|
||||
};
|
||||
|
||||
/**
|
||||
* 差分:目标 schema(合并结果)相对已物化 schema 的增量。
|
||||
* **永不产出删列、缩窄或改主键的变更** —— 那三样是破坏,由数据管理的治理动作承担,不经声明发生。
|
||||
*/
|
||||
export function planSchemaChanges(
|
||||
target: MergedObject,
|
||||
current: MaterializedObject | undefined,
|
||||
): SchemaPlan {
|
||||
const notices: MergeNotice[] = [];
|
||||
const conflicts: MergeConflict[] = [];
|
||||
|
||||
if (current === undefined) {
|
||||
return { changes: [{ kind: 'create-table', object: target }], notices, conflicts };
|
||||
}
|
||||
|
||||
// 主键一经建立不得由声明变更 —— 新增主键字段是破坏性变更
|
||||
const currentPk = [...current.primaryKey].sort();
|
||||
const targetPk = [...target.primaryKey].sort();
|
||||
const addedPk = targetPk.filter((k) => !currentPk.includes(k));
|
||||
if (addedPk.length > 0) {
|
||||
conflicts.push({
|
||||
kind: 'primary-key-divergent',
|
||||
field: addedPk.join(','),
|
||||
message: `主键已建立为 (${currentPk.join(', ')}),声明试图新增主键字段 ${addedPk.join(', ')} —— 只增不破坏,交数据管理裁决`,
|
||||
});
|
||||
}
|
||||
|
||||
const columns = new Map(current.columns.map((c) => [c.name, c]));
|
||||
const changes: SchemaChange[] = [];
|
||||
|
||||
for (const field of target.fields) {
|
||||
const existing = columns.get(field.name);
|
||||
if (existing === undefined) {
|
||||
changes.push({ kind: 'add-column', field });
|
||||
continue;
|
||||
}
|
||||
const w = widen(existing.type, field.type);
|
||||
if (!w.ok) {
|
||||
conflicts.push({ kind: 'type-incompatible', field: field.name, message: w.reason });
|
||||
continue;
|
||||
}
|
||||
if (w.type !== existing.type) {
|
||||
notices.push({
|
||||
kind: 'type-widened',
|
||||
field: field.name,
|
||||
message: `已物化 ${existing.type},声明需要 ${field.type} → 加宽为 ${w.type}`,
|
||||
});
|
||||
changes.push({ kind: 'widen-column', field: { ...field, type: w.type }, from: existing.type });
|
||||
}
|
||||
}
|
||||
|
||||
return { changes, notices, conflicts };
|
||||
}
|
||||
|
||||
/** 声明只增不破坏的机检:计划里不得出现任何缩表动作 */
|
||||
export function planIsNonDestructive(plan: SchemaPlan): boolean {
|
||||
return plan.changes.every(
|
||||
(c) => c.kind === 'create-table' || c.kind === 'add-column' || c.kind === 'widen-column',
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,119 @@
|
||||
/**
|
||||
* 任务视图与草稿层叠加 —— 纯逻辑,零 IO(编码规范 §7.2 / §5.3)。
|
||||
*
|
||||
* 语义出处 OS 09 / AM 10.3:
|
||||
* 任务视图 = 正式版 + 本任务草稿层(**读己之写**:本任务可见、正式版不可见、不产生数据事件);
|
||||
* 环内推进读任务视图,不依赖事件;跨任务监听只认正式版事件。
|
||||
*/
|
||||
import type { LedgerKey, LedgerRow } from '@contracts';
|
||||
|
||||
export type DraftEntry = {
|
||||
readonly key: LedgerKey;
|
||||
readonly patch: LedgerRow;
|
||||
readonly tombstone: boolean;
|
||||
/** 草稿建立时读到的基线值 —— 放行前的数据冲突检查用 */
|
||||
readonly baseline: LedgerRow;
|
||||
};
|
||||
|
||||
/** 主键的规范化串:字段名排序后拼接,保证同一行的键恒等 */
|
||||
export function keyOf(key: LedgerKey): string {
|
||||
return Object.keys(key)
|
||||
.sort()
|
||||
.map((k) => `${k}=${String(key[k])}`)
|
||||
.join('|');
|
||||
}
|
||||
|
||||
/**
|
||||
* 叠加:正式版行 + 本任务草稿 patch → 任务视图行。
|
||||
* 草稿新增的行(正式版没有)也出现在视图里;tombstone 的行从视图中消失。
|
||||
*/
|
||||
export function overlay(
|
||||
official: readonly LedgerRow[],
|
||||
drafts: readonly DraftEntry[],
|
||||
primaryKey: readonly string[],
|
||||
): LedgerRow[] {
|
||||
const draftByKey = new Map(drafts.map((d) => [keyOf(d.key), d]));
|
||||
const seen = new Set<string>();
|
||||
const out: LedgerRow[] = [];
|
||||
|
||||
for (const row of official) {
|
||||
const k = keyOf(pickKey(row, primaryKey));
|
||||
seen.add(k);
|
||||
const draft = draftByKey.get(k);
|
||||
if (draft === undefined) {
|
||||
out.push(row);
|
||||
continue;
|
||||
}
|
||||
if (draft.tombstone) continue;
|
||||
out.push({ ...row, ...draft.patch });
|
||||
}
|
||||
|
||||
for (const draft of drafts) {
|
||||
const k = keyOf(draft.key);
|
||||
if (seen.has(k) || draft.tombstone) continue;
|
||||
out.push({ ...draft.key, ...draft.patch });
|
||||
}
|
||||
|
||||
return out;
|
||||
}
|
||||
|
||||
export function pickKey(row: LedgerRow, primaryKey: readonly string[]): LedgerKey {
|
||||
const key: Record<string, string | number> = {};
|
||||
for (const field of primaryKey) {
|
||||
const value = row[field];
|
||||
if (typeof value === 'string' || typeof value === 'number') key[field] = value;
|
||||
else if (value !== undefined && value !== null) key[field] = String(value);
|
||||
}
|
||||
return key;
|
||||
}
|
||||
|
||||
/* ── 数据冲突检查(落地预检第五项,OS 7.3) ────────────────────────── */
|
||||
|
||||
export type ConflictFinding = {
|
||||
readonly key: LedgerKey;
|
||||
readonly field: string;
|
||||
readonly baseline: unknown;
|
||||
readonly official: unknown;
|
||||
readonly draft: unknown;
|
||||
};
|
||||
|
||||
/**
|
||||
* 草稿层所改字段与正式版的并发冲突:**他单已改同一字段即预检不过**,
|
||||
* 打回环内基于新正式版重拟。
|
||||
*
|
||||
* 判据:草稿建立时读到的基线值 ≠ 当前正式版值 ⇒ 冲突。
|
||||
* 只检查草稿实际修改过的字段 —— 没碰的字段被别人改了不算冲突。
|
||||
*/
|
||||
export function detectConflicts(
|
||||
drafts: readonly DraftEntry[],
|
||||
officialByKey: ReadonlyMap<string, LedgerRow>,
|
||||
): ConflictFinding[] {
|
||||
const findings: ConflictFinding[] = [];
|
||||
for (const draft of drafts) {
|
||||
const official = officialByKey.get(keyOf(draft.key));
|
||||
if (official === undefined) continue; // 草稿新增的行,无从冲突
|
||||
for (const field of Object.keys(draft.patch)) {
|
||||
const baseline = draft.baseline[field];
|
||||
const current = official[field];
|
||||
if (!sameValue(baseline, current)) {
|
||||
findings.push({
|
||||
key: draft.key,
|
||||
field,
|
||||
baseline,
|
||||
official: current,
|
||||
draft: draft.patch[field],
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
return findings;
|
||||
}
|
||||
|
||||
function sameValue(a: unknown, b: unknown): boolean {
|
||||
if (a === b) return true;
|
||||
if (a === null || a === undefined) return b === null || b === undefined;
|
||||
if (b === null || b === undefined) return false;
|
||||
if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
|
||||
if (typeof a === 'object' || typeof b === 'object') return JSON.stringify(a) === JSON.stringify(b);
|
||||
return String(a) === String(b);
|
||||
}
|
||||
@@ -0,0 +1,236 @@
|
||||
/**
|
||||
* ledger 用例 —— 编排 domain,依赖 port.ts,不 import 任何 adapter(编码规范 §5.3)。
|
||||
*
|
||||
* 写三分的不变量在此落实(OS 09):
|
||||
* systemWrite → 正式版 + **即时**数据事件
|
||||
* draftWrite → 草稿层,**零**事件
|
||||
* releaseWrite → 冲突检查 → 原子合并 → **此刻**抛事件
|
||||
*/
|
||||
import type { EnvelopeDraft, LedgerPage, LedgerQuery, ObjectDeclaration, TaskId } from '@contracts';
|
||||
import { eventIdSchema } from '@contracts';
|
||||
import type {
|
||||
DraftWrite,
|
||||
LedgerService,
|
||||
ObjectAddress,
|
||||
ReleaseWriteResult,
|
||||
SchemaApplyResult,
|
||||
SystemWrite,
|
||||
} from '../../contract.ts';
|
||||
import { DraftConflictError, ObjectNotMaterializedError } from '../../contract.ts';
|
||||
import type { Clock, DraftStore, EventPublisher, IdGenerator, LedgerStore, ObjectRef } from '../../port.ts';
|
||||
import { mergeDeclarations, planIsNonDestructive, planSchemaChanges } from '../domain/schema-merge.ts';
|
||||
import { detectConflicts, keyOf, overlay, pickKey } from '../domain/task-view.ts';
|
||||
|
||||
export type LedgerServiceDeps = {
|
||||
readonly store: LedgerStore;
|
||||
readonly drafts: DraftStore;
|
||||
readonly events: EventPublisher;
|
||||
readonly clock: Clock;
|
||||
readonly ids: IdGenerator;
|
||||
};
|
||||
|
||||
function groupDeclarations(declarations: readonly ObjectDeclaration[]): Map<string, ObjectDeclaration[]> {
|
||||
const groups = new Map<string, ObjectDeclaration[]>();
|
||||
for (const d of declarations) {
|
||||
const key = `${d.domain}.${d.object}`;
|
||||
const bucket = groups.get(key);
|
||||
if (bucket === undefined) groups.set(key, [d]);
|
||||
else bucket.push(d);
|
||||
}
|
||||
return groups;
|
||||
}
|
||||
|
||||
export function createLedgerService(deps: LedgerServiceDeps): LedgerService {
|
||||
function dataEvent(
|
||||
ref: ObjectRef,
|
||||
key: Record<string, string | number>,
|
||||
changed: readonly string[],
|
||||
operation: 'insert' | 'update' | 'delete',
|
||||
taskId: TaskId | undefined,
|
||||
cause: { kind: 'ledger-write'; ref: string },
|
||||
): EnvelopeDraft {
|
||||
return {
|
||||
id: eventIdSchema.parse(deps.ids.next()),
|
||||
type: 'data',
|
||||
correlation: {
|
||||
// 未绑任务的系统写不指定消费目标 —— 三级消费由 `event` 判定(OS 6.3)
|
||||
...(taskId === undefined ? {} : { target: { kind: 'task' as const, id: taskId } }),
|
||||
cause,
|
||||
keys: Object.fromEntries(Object.entries(key).map(([k, v]) => [k, String(v)])),
|
||||
},
|
||||
payload: {
|
||||
data: {
|
||||
domain: ref.domain,
|
||||
object: ref.object,
|
||||
primaryKey: key,
|
||||
changed: [...changed],
|
||||
operation,
|
||||
},
|
||||
},
|
||||
occurredAt: deps.clock.now().toISOString(),
|
||||
source: { kind: 'engine', detail: 'ledger' },
|
||||
};
|
||||
}
|
||||
|
||||
async function requireSchema(address: ObjectAddress) {
|
||||
const described = await deps.store.describe(address);
|
||||
if (described === undefined) throw new ObjectNotMaterializedError(`${address.domain}.${address.object}`);
|
||||
return described;
|
||||
}
|
||||
|
||||
return {
|
||||
async applyDeclarations(declarations) {
|
||||
const results: SchemaApplyResult[] = [];
|
||||
for (const [, group] of groupDeclarations(declarations)) {
|
||||
const first = group[0]!;
|
||||
const ref: ObjectRef = { domain: first.domain, object: first.object };
|
||||
const merge = mergeDeclarations(group);
|
||||
if (merge.merged === undefined || merge.conflicts.length > 0) {
|
||||
results.push({ merged: merge.merged, notices: merge.notices, conflicts: merge.conflicts, applied: false });
|
||||
continue;
|
||||
}
|
||||
const current = await deps.store.describe(ref);
|
||||
const plan = planSchemaChanges(merge.merged, current);
|
||||
const conflicts = [...merge.conflicts, ...plan.conflicts];
|
||||
if (conflicts.length > 0 || !planIsNonDestructive(plan)) {
|
||||
results.push({ merged: merge.merged, notices: [...merge.notices, ...plan.notices], conflicts, applied: false });
|
||||
continue;
|
||||
}
|
||||
if (plan.changes.length > 0) await deps.store.applyChanges(ref, plan.changes);
|
||||
results.push({
|
||||
merged: merge.merged,
|
||||
notices: [...merge.notices, ...plan.notices],
|
||||
conflicts: [],
|
||||
applied: true,
|
||||
});
|
||||
}
|
||||
return results;
|
||||
},
|
||||
|
||||
async describe(address) {
|
||||
return deps.store.describe(address);
|
||||
},
|
||||
|
||||
async listObjects() {
|
||||
return deps.store.listObjects();
|
||||
},
|
||||
|
||||
/** ① 系统写:世界已发生的事实,免门,即时抛事件 */
|
||||
async systemWrite(write: SystemWrite) {
|
||||
await requireSchema(write.address);
|
||||
await deps.store.upsert(write.address, write.key, write.values);
|
||||
await deps.events.publish(
|
||||
dataEvent(
|
||||
write.address,
|
||||
write.key,
|
||||
Object.keys(write.values),
|
||||
'update',
|
||||
write.taskId,
|
||||
{ kind: 'ledger-write', ref: `${write.cause.kind}:${write.cause.ref}` },
|
||||
),
|
||||
);
|
||||
},
|
||||
|
||||
/** ② 草稿写:读己之写,正式版不可见,**不产生数据事件** */
|
||||
async draftWrite(write: DraftWrite) {
|
||||
const schema = await requireSchema(write.address);
|
||||
const existing = await deps.store.selectByKeys(write.address, [write.key]);
|
||||
const baseline: Record<string, unknown> = {};
|
||||
const row = existing[0];
|
||||
if (row !== undefined) {
|
||||
for (const field of Object.keys(write.patch)) baseline[field] = row[field];
|
||||
}
|
||||
await deps.drafts.put(write.taskId, write.address, {
|
||||
key: pickKey({ ...write.key }, schema.primaryKey.length > 0 ? schema.primaryKey : Object.keys(write.key)),
|
||||
patch: write.patch,
|
||||
tombstone: write.tombstone ?? false,
|
||||
baseline,
|
||||
});
|
||||
},
|
||||
|
||||
/** ③ 放行写:冲突检查 → 原子合并 → 此刻抛事件 */
|
||||
async releaseWrite(taskId): Promise<ReleaseWriteResult> {
|
||||
const conflicts = await this.checkConflicts(taskId);
|
||||
if (conflicts.length > 0) throw new DraftConflictError(conflicts);
|
||||
|
||||
const drafts = await deps.drafts.list(taskId);
|
||||
if (drafts.length === 0) return { mergedRows: 0, emittedEvents: 0 };
|
||||
|
||||
const pending: EnvelopeDraft[] = [];
|
||||
|
||||
await deps.store.transaction(async (store, draftStore) => {
|
||||
for (const draft of drafts) {
|
||||
const ref: ObjectRef = { domain: draft.domain, object: draft.object };
|
||||
if (draft.tombstone) {
|
||||
await store.deleteRow(ref, draft.key);
|
||||
pending.push(
|
||||
dataEvent(ref, draft.key, [], 'delete', taskId, { kind: 'ledger-write', ref: `release:${taskId}` }),
|
||||
);
|
||||
continue;
|
||||
}
|
||||
const existing = await store.selectByKeys(ref, [draft.key]);
|
||||
await store.upsert(ref, draft.key, draft.patch);
|
||||
pending.push(
|
||||
dataEvent(
|
||||
ref,
|
||||
draft.key,
|
||||
Object.keys(draft.patch),
|
||||
existing.length === 0 ? 'insert' : 'update',
|
||||
taskId,
|
||||
{ kind: 'ledger-write', ref: `release:${taskId}` },
|
||||
),
|
||||
);
|
||||
}
|
||||
await draftStore.clear(taskId);
|
||||
});
|
||||
|
||||
for (const envelope of pending) await deps.events.publish(envelope);
|
||||
return { mergedRows: drafts.length, emittedEvents: pending.length };
|
||||
},
|
||||
|
||||
async query(query: LedgerQuery): Promise<LedgerPage> {
|
||||
const { rows, total } = await deps.store.select(query);
|
||||
return { rows, total };
|
||||
},
|
||||
|
||||
async taskView(taskId, query): Promise<LedgerPage> {
|
||||
const ref: ObjectRef = { domain: query.address.domain, object: query.address.object };
|
||||
const schema = await requireSchema(ref);
|
||||
const [official, drafts] = await Promise.all([
|
||||
deps.store.select(query),
|
||||
deps.drafts.listForObject(taskId, ref),
|
||||
]);
|
||||
const rows = overlay(official.rows, drafts, schema.primaryKey);
|
||||
return { rows, total: rows.length };
|
||||
},
|
||||
|
||||
async checkConflicts(taskId) {
|
||||
const drafts = await deps.drafts.list(taskId);
|
||||
if (drafts.length === 0) return [];
|
||||
const byObject = new Map<string, Array<(typeof drafts)[number]>>();
|
||||
for (const d of drafts) {
|
||||
const k = `${d.domain}.${d.object}`;
|
||||
const bucket = byObject.get(k);
|
||||
if (bucket === undefined) byObject.set(k, [d]);
|
||||
else bucket.push(d);
|
||||
}
|
||||
const findings = [];
|
||||
for (const [, group] of byObject) {
|
||||
const first = group[0]!;
|
||||
const ref: ObjectRef = { domain: first.domain, object: first.object };
|
||||
const schema = await requireSchema(ref);
|
||||
const rows = await deps.store.selectByKeys(
|
||||
ref,
|
||||
group.map((g) => g.key),
|
||||
);
|
||||
const officialByKey = new Map(rows.map((r) => [keyOf(pickKey(r, schema.primaryKey)), r]));
|
||||
findings.push(...detectConflicts(group, officialByKey));
|
||||
}
|
||||
return findings;
|
||||
},
|
||||
|
||||
async discardDrafts(taskId) {
|
||||
await deps.drafts.clear(taskId);
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"name": "@modules/ledger",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"exports": { ".": "./index.ts" }
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
/**
|
||||
* module: ledger —— 本模块要外界提供的能力(编码规范 §10.1 / §5.3)。
|
||||
*/
|
||||
import type { EnvelopeDraft, LedgerKey, LedgerQuery, LedgerRow } 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> };
|
||||
|
||||
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>;
|
||||
listObjects(): Promise<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>;
|
||||
clear(taskId: string): Promise<void>;
|
||||
};
|
||||
Reference in New Issue
Block a user