跳转至

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 必须不大于 max
  • kind: "unit" unit_price、quantity:十进制字符串与正整数

共同字段:currency(三位大写代码,必须)、note(可选,如「含税」「含安装」「不含运费」)。

金额一律用字符串,不用浮点数。币种不做换算,混币就是两个 Deal 或进附注。

1.5 attachments 附件哈希

数组,可为空。每项:

  • name 必须,文件名
  • sha256 必须,64 位十六进制小写
  • size 必须,字节数
  • media_type 可选,MIME
  • where 可选,取件方式(链接或「随消息口头约定」)

附件内容不进 Deal 本体,只留指纹与取件方式。取件走别的渠道,见 §W。


2. 附注 notes

字符串数组,必须字段,可为空数组。凡五件装不下的东西都放这里,一条一句:

  • 报价单里的十二行明细、品牌型号、工艺说明
  • 付款节点与比例
  • 口头答应过的事、双方默认的行业惯例
  • 「他说下周三之前给我看样品,不算正式时间」

附注不参与任何判断,不进状态机,不影响回执。它的作用只有一个:不丢信息。


3. 版本链

一个 Deal 由一串只追加的版本组成,v0001.json、v0002.json……每个文件自洽、含完整五项(不存「差异」,存全量),外加元信息:

  • deal_id ULID,创建时生成,此后不变
  • version 整数,从 1 起
  • created_at RFC 3339 UTC
  • prev_sha256 上一版文件的 SHA-256;第一版为 null
  • fields 上述五项
  • notes 附注

规则:

  1. 版本文件写一次即不可变:创建时若文件已存在,必须失败,不得覆盖。
  2. 读到的历史版本字节永不重写;要改就追加新版本。
  3. prev_sha256 构成哈希链,任何一版被改动都能被发现。校验命令见 §5。
  4. 版本只增不减。删除一个 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 必填。

五条硬规则

  1. 每个动词必须带 deal_id 与目标 version;目标版本不是当前版即 conflict(防止照着旧版回复)。
  2. accept/decline 只对对方发出的版本有效。对自己的版本只能 counter/change_request,或 cancel/close。
  3. 议定之后仍可改:agreed 下收到 change_request 即回 negotiating,对方 accept 后回 agreed。加项、改期都走这条,不新建 Deal。
  4. closed 之后任何动词一律 illegal_transition,remind 也不例外。
  5. 同一版本自动催办不超过两次。次数由 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→ closed
  • negotiating —counter/change_request/decline→ negotiating;—accept→ agreed;—cancel/close→ closed
  • agreed —deliver→ awaiting_acceptance;—change_request→ negotiating;—cancel/close→ closed
  • awaiting_acceptance —accept_delivery(accepted、accepted_with_defects)→ accepted;—accept_delivery(rejected)→ agreed;—cancel/close→ closed
  • accepted —close→ closed
  • closed 无

不在表内的组合一律 illegal_transition。

比原设少一个状态、并改一处定义:

  • 删「执行中」这一态:没有任何动词能把 agreed 推进它,它永远进不去;议定即在办,日程由 timing 表达,不需要第二个状态重复同一件事。
  • 「已归档」不是状态而是视图。收档回答「还看不看」,不回答「成没成」。成败记在 closed.outcome,是否归档记 archived_at;任何终态都可归档,归档不改状态。

9. 回执

close 时生成,双方各存一份:

  • deal_id、本端 agent_id、对方 agent_id
  • subject 标的原文,不摘要
  • price、timing 结案当版的值
  • versions 版本总数与首末两版指纹
  • messages 消息条数与首末 message_id
  • outcome、reason、closed_at

回执不含正文、附注、附件内容,也不含签名——签名是可选增强。它的用途只有一个:事后能说清这件事成没成、按什么条件成交。不作债权凭证。


10. 本版明确不做

  • 不做交付物与验收标准的封闭枚举(自由附注+版本对比足够)
  • 不做变更规则引擎(谁在什么条件下能改什么,交给 Policy 与人的判断)
  • 不做多币种换算与汇率
  • 不做金额合计、税率、发票字段
  • 不做附件内容托管
  • 不做跨 Deal 的合并、拆分、关联

这些都不缺道理,缺的是「少了它,主人每天多处理几件事」的证据。没有证据就不加。