ChaiHaoandClaude Opus 5
ade0fa5a94
活动:A2 选型 / A3 寻源 / A4 定价 / A6 议价 / A7 归档五件各补成真活动包 —— 契约宽进(input.required 空,归一在活动内)、台账必填声明(含行级 requiredWhen)、 入场哨兵与 L1/L2 判据一律读基座数、两份件(在办可编辑 + 办结静态快照)、 三案例常备、包内自测。e2e 各三案例 released、行动被拒 0、发口正确、提交闸每单真拦。 基座(共享面,改一处影响所有活动,故每处都带回归): · 重发判断走在站上场之前 —— 人答完那步常已收掉,readyToWork 先抛「不能再往它上面挂活」, 于是「重发已答过的卡 = 无事发生」这条唯一活路在最需要时够不着,A1 基线当场熔断; · 决策卡补幂等兜底(与执行工单同一把尺):头两次无事发生,第三次起才算被拒; · 输出没成形先就地重问一次,原话进工作日志、不再摆上卡面; · 工具调用读数 tool_<名>_calls —— 「机检只读基座数」这条纪律第一次覆盖到工具; · 执行卡 steps/standard 补进出参 schema(从前能到卡面全靠厂商 JSON 模式宽松); · 件的就地更新改逐节点 morph,保存先把新值镜像进只读那份 —— 不闪、不等回声。 A1(基线,全程守住):措辞三档对齐(必填/建议/选填)、禁止拿历史价当客户目标价、 卡骨架从步骤剧本搬进说明书(压成一拍连做时剧本没摊开,会发出没有指导书的裸卡)。 契约两处**新增可选字段**(非破坏):FieldDeclaration.requiredWhen、工单 finalHtml; api-report 同批更新。docs/adr 与 docs/archive 的 13 份文件在工作树里不见了, 本次予以恢复而非提交删除。 门禁:typecheck / lint / depcruise / test(1366)全绿。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
317 lines
16 KiB
TypeScript
317 lines
16 KiB
TypeScript
/**
|
|
* 数据与台账(编码规范 §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(),
|
|
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>;
|