D 事项(Deal)¶
DWP v0.1 草案 2026-11-22
Deal(事项) 是就某件事达成的一次往复,从开口到结案。确认一个会议时间、追一笔尾款、改一次交付内容,都是 Deal。本章只定义结构与版本,动词与状态转换见下一节(同章 §D.7 起)。
本章的取舍只有一句:能塞进五件就塞,塞不进去就进附注,绝不为了整齐而把真实信息挤掉。
1. 五个结构化字段¶
一个 Deal 的每次变更都是一个版本,每个版本只含这五项加附注。
1.1 counterparty 对手方¶
name必须,对方的名字或称呼,自由文本agent_id可选,对方的代理域名;没有代理的对端不填contact可选,人类可读的联络方式描述(如「王工,微信」);不得存口令、验证码、身份证号
1.2 timing 时间点或时间窗¶
二选一,kind 决定其余字段:
kind: "point"at:RFC 3339 UTC,秒精度kind: "window"from、to:同上,to必须不早于from;flex可选,自由文本描述可浮动范围(如「前后两天」)
时间只表达「什么时候」,不表达「谁定的」。谁定的看动词(§D.7)。
1.3 subject 标的¶
text必须,这件事到底是什么,自由文本。一句话说不完就写长句,不截断category可选,自由文本标签(如「装修」「会议」「交付」)。本版不设封闭枚举——枚举一定会漏,漏了就逼人撒谎
1.4 price 价格¶
kind 二选一:
kind: "range"min、max:十进制字符串,min必须不大于maxkind: "unit"unit_price、quantity:十进制字符串与正整数
共同字段:currency(三位大写代码,必须)、note(可选,如「含税」「含安装」「不含运费」)。
金额一律用字符串,不用浮点数。币种不做换算,混币就是两个 Deal 或进附注。
1.5 attachments 附件哈希¶
数组,可为空。每项:
name必须,文件名sha256必须,64 位十六进制小写size必须,字节数media_type可选,MIMEwhere可选,取件方式(链接或「随消息口头约定」)
附件内容不进 Deal 本体,只留指纹与取件方式。取件走别的渠道,见 §W。
2. 附注 notes¶
字符串数组,必须字段,可为空数组。凡五件装不下的东西都放这里,一条一句:
- 报价单里的十二行明细、品牌型号、工艺说明
- 付款节点与比例
- 口头答应过的事、双方默认的行业惯例
- 「他说下周三之前给我看样品,不算正式时间」
附注不参与任何判断,不进状态机,不影响回执。它的作用只有一个:不丢信息。
3. 版本链¶
一个 Deal 由一串只追加的版本组成,v0001.json、v0002.json……每个文件自洽、含完整五项(不存「差异」,存全量),外加元信息:
deal_idULID,创建时生成,此后不变version整数,从 1 起created_atRFC 3339 UTCprev_sha256上一版文件的 SHA-256;第一版为nullfields上述五项notes附注
规则:
- 版本文件写一次即不可变:创建时若文件已存在,必须失败,不得覆盖。
- 读到的历史版本字节永不重写;要改就追加新版本。
prev_sha256构成哈希链,任何一版被改动都能被发现。校验命令见 §5。- 版本只增不减。删除一个 Deal 属数据主权操作,走整体导出后归档,不在版本链里留空洞。
4. 导出人类可读件¶
一条命令把任意版本或整条链导出为 Markdown:标题取 subject.text,依次列出对手方、时间、价格、附件、附注,末尾标注「第 N 版 / 共 M 版,生成时间」与每版的时间戳。
导出件是只读快照,不是新版本,不写回版本链。
5. 校验¶
dwp deal verify <deal_id> 从头重算每条 prev_sha256 并逐版比对文件指纹,任一处不符即报错并指出断在第几版。校验不修改任何文件。
被拒绝的输入一律以错误码 invalid_request 返回,指出字段路径(如 fields.price.min)。接受的形状只有上面写的这些,未知字段必须拒绝——静默忽略会让人以为写了就算数。
6. 与消息的关系¶
Deal 版本是状态,消息是过程。每条消息的 payload 可以携带新版本(完整五项加附注);对端接受后自己落一版。两侧版本号不要求一致,同一个 prev_sha256 链只在各自一侧成立。
结案时生成回执:双方、类型、金额区间、时间、消息链哈希,不含正文与附注。回执随 close 动词产生,见 §9。
7. 动词¶
本版十一个,分五类,每个只回答一个问题。
起事(draft → negotiating)
ask我要什么,尚未给价。最少只需subject.text。offer我给条件,price必含。
改条件(留在 negotiating,产生新版本)
counter只改价格(金额或区间),其余照旧。change_request改价格以外的条件:时间、标的、附件、交付要求。价格可不变。
定夺
accept接受当前版本的全部条件(negotiating→agreed)。decline拒绝当前版本。不结束事项:事项仍在商议中,等下一版。
办事
deliver声明已交付(agreed→awaiting_acceptance)。须带delivery:交付内容自由文本、完成时间、附件哈希。accept_delivery对交付的判定,result取accepted、accepted_with_defects、rejected。rejected退回agreed,并在附注里写明不合格之处。
催办(不改状态)
remind催一次。不改字段、不产生新版本、不改变状态,只留痕并计入打扰次数。
收尾(→ closed)
cancel取消事项,reason必填。对方反悔、条件崩了、自己叫停,都走这里。close收档。outcome取completed、abandoned、lost、declined_final,reason必填。
五条硬规则
- 每个动词必须带
deal_id与目标version;目标版本不是当前版即conflict(防止照着旧版回复)。 accept/decline只对对方发出的版本有效。对自己的版本只能counter/change_request,或cancel/close。- 议定之后仍可改:
agreed下收到change_request即回negotiating,对方accept后回agreed。加项、改期都走这条,不新建 Deal。 closed之后任何动词一律illegal_transition,remind也不例外。- 同一版本自动催办不超过两次。次数由 Policy 数,Deal 只记账。
为什么是十一个
iTIP 用八个方法覆盖会议邀约,含 COUNTER/DECLINECOUNTER、CANCEL、REFRESH;EDI 用 850/855/860/865 覆盖下单、回执、变更、变更回执。两套体系都没有「打招呼」「同步信息」「付款」这类动词。FIPA 当年列了二十二个通信行为,实际实现普遍只用四五个——动词一多,各家各选一半,互通就崩。
所以本版不加这几个:
comment/inform:纯信息同步写附注,或走主人自己的聊天工具。加了就等于把事项流做成聊天工具。withdraw:撤回一条对方还没看到的提议,等价于cancel后重发,代价小于多一个动词。pay/invoice:不碰钱。sign:不在本版范围,签约是外部动作。
8. 状态机¶
六个状态,一个终态:
draft草拟:已建立,尚未发出。negotiating商议中:至少一版已发出,尚未被接受。agreed议定:条件双方一致,事在办。awaiting_acceptance待验收:对方声明已交付。accepted已验收:交付合格。closed已收档(终态),带outcome。
转移:
draft—ask/offer→negotiating;—cancel/close→closednegotiating—counter/change_request/decline→negotiating;—accept→agreed;—cancel/close→closedagreed—deliver→awaiting_acceptance;—change_request→negotiating;—cancel/close→closedawaiting_acceptance—accept_delivery(accepted、accepted_with_defects)→accepted;—accept_delivery(rejected)→agreed;—cancel/close→closedaccepted—close→closedclosed无
不在表内的组合一律 illegal_transition。
比原设少一个状态、并改一处定义:
- 删「执行中」这一态:没有任何动词能把
agreed推进它,它永远进不去;议定即在办,日程由timing表达,不需要第二个状态重复同一件事。 - 「已归档」不是状态而是视图。收档回答「还看不看」,不回答「成没成」。成败记在
closed.outcome,是否归档记archived_at;任何终态都可归档,归档不改状态。
9. 回执¶
close 时生成,双方各存一份:
deal_id、本端agent_id、对方agent_idsubject标的原文,不摘要price、timing结案当版的值versions版本总数与首末两版指纹messages消息条数与首末message_idoutcome、reason、closed_at
回执不含正文、附注、附件内容,也不含签名——签名是可选增强。它的用途只有一个:事后能说清这件事成没成、按什么条件成交。不作债权凭证。
10. 本版明确不做¶
- 不做交付物与验收标准的封闭枚举(自由附注+版本对比足够)
- 不做变更规则引擎(谁在什么条件下能改什么,交给 Policy 与人的判断)
- 不做多币种换算与汇率
- 不做金额合计、税率、发票字段
- 不做附件内容托管
- 不做跨 Deal 的合并、拆分、关联
这些都不缺道理,缺的是「少了它,主人每天多处理几件事」的证据。没有证据就不加。