johanhaleby/domain-storytelling

领域故事讲述

领域故事是讲述业务流程的画面，以句子形式呈现：参与者对工作对象做某事，有时涉及另一个参与者。箭头上的数字表示顺序，其他信息不表示顺序。

此技能对故事进行建模，然后渲染。在建模任何非平凡内容之前，请在一次调用中阅读 references/notation.md 和 references/spec.md。规范文件列出了每个图标名称。

步骤

1. 对故事建模。 默认是草稿：根据用户描述对典型情况建模，选择图标，渲染，并说明你做了哪些假设。只有当选择会改变模型而非仅仅装饰时才提问。
2. 回读句子一次，询问哪些句子是可选的，或者有时以不同方式发生。这些将成为注释。这是最容易跳过的环节，跳过它的代价最大，因为记法中没有分支。仅在某些时候发生的步骤要么带有注释，要么静默地加入正常路径。
3. 改为运行工作坊，当用户要求时（/domain-storytelling workshop、“运行工作坊”、“就此采访我”）或者当计划依赖于一个从未被记录的过程时。现在阅读 references/workshop.md。绝不同时采访和绘图。
4. 编写规范并渲染，如下面的“渲染”部分所述。
5. 处理警告。 当生成器向 stderr 写入任何内容时，立即阅读 references/warnings.md。生成器以命名该文件的行结束，因此跳过的阅读会在输出中显示。
6. 检查图片，通过阅读渲染器写入的预览 PNG，并命名每个写入的文件。当没有警告且图片轨迹清晰时，渲染完成。

不可协商的规则

这些规则源自该方法，违反它们会产生看似领域故事但并非如此的东西。

• 每个参与者恰好出现一次。 每个参与者一个形状，无论它出现在多少个句子中。
• 不同角色中的两个人是两个参与者，即使领域称他们为同一事物。 上述规则是关于一个参与者绘制一次，而不是关于一个单词绘制一次。在合并同一名词的两次提及之前，询问一个人是否能够完成两个步骤。如果不能，则他们是不同的参与者，需要不同的形状和名称，说明每个在此扮演的角色。序列号才是使这一点错误而非仅仅模糊的原因，因为它们断言执行句子 5 的参与者就是执行句子 2 的那个人。一个加入分类队列、释放停车位然后认领释放位置的司机，暗示一个司机放弃了一个停车位并又被提供回来，而离开的持有者和排队者是共享一个职位的两个角色。注释中提及可能执行该步骤的其他人，“管理员可以改为释放停车位”，表明该步骤的参与者从未确定。
• 每个活动绘制自己的工作对象。 三个句子中的同一个订单是三个形状。这不是重复，而是记法显示事物移动的方式。
• 没有条件、分支或循环。 没有网关、没有菱形、没有虚线的“如果”。将重要的替代方案建模为独立的故事。将小的变化保留为注释。
• 句子以参与者开头，序列号放在第一个箭头上。指向第二个参与者的箭头上带有介词，而非数字。
• 同时发生的句子共享一个编号，任意数量都可以。在规范中跨它们重复 n 值。这是记号表示“同时”的唯一方式，因为它没有分支和汇合，因此当一个步骤不等待另一个步骤时请使用它。当一个步骤真正跟随另一个步骤时，请保持编号分开，因为共享的编号声称的不仅仅是“这两个是相关的”。
• 使用领域自己的词语。 箭头上的动词是领域专家所说的词语。如果你发现自己写“处理”或“处置”，说明你尚未理解该步骤，请提问。在从代码提取的故事中，领域的词语是人们触发的动作名称，即按钮、节点或命令，因此 cancel-reservation 节点生成“取消预订”。每个动词命名一个动作，一个故事中的两个不同动作使用两个不同的动词。在命名参与者之前，跟随节点到调用它的屏幕，并根据该屏幕的用户命名参与者，因为后台用户和管理员编辑器中的专家服务是可以做不同事情的不同角色。当相邻动作有类似效果时，取消停车位预订与从队列中移除排队者不同，注释中应标明屏幕和按钮，以及它不是哪个相邻动作。
• 工作对象是领域已经使用的名词。 “发票”、“停车位认领”。名称中的 and 表明它实际上是两个，修复方法是选择活动真正移动的那个，或者写两个共享一个编号的句子。长度是症状而非错误，因此缩短复合名称以适配只会掩盖问题。
• 明确说出范围。 粒度、时间点、领域纯度。没有这些的故事含糊不清，无法明确它声称什么。范围在规范和 Egon 描述中传递，而非画面上，因为这三个术语是方法对建模者说的，而读者无法从图像中解码它们。

显示变更的位置

当故事的重点是变更对过程的影响时，用 "changed": true 标记受影响的句子，并在描述中说明。一张带有变更标记的图片通常优于两张需要肉眼比较的图片。当过程的形状发生变化时（即步骤在参与者之间移动或消失），请绘制 AS-IS 和 TO-BE 故事，而不是步骤位置不变仅内容变化的情况。

当变更决定谁获得某物（报价、优先级或轮次）时，绘制对比：失去的人和获得的人，作为同一角色中的两个参与者，以其位置命名（“第一个排队者”、“第二个排队者”）。以命名谁获得了某物的句子结束。如果该角色只有一个参与者，跳过某人的规则绘制起来与无作为的规则完全一样。

从代码而非人绘制的故事是对代码的解读。请在图片旁边说明，以便读者知道它未经任何实际操作者验证。在绘制变更的句子之前，阅读决定新行为何时适用的守卫：它所需的状态和触发它的事件。将该事件绘制为变更之前的句子，并将整个故事所处的状态（例如“离开的司机仍然停在那里”）放入描述中。像“下次询问队列时”这样的注释没有命名任何参与者，这是触发器从未找到的迹象。

多少个故事

• 每个重要替代方案一个故事。首先是正常路径。
• AS-IS 和 TO-BE 始终是独立的故事，从不是一张图片。
• 粗略概览加上对关键步骤的精细故事，当过程庞大时。
• 大约每十五个句子就拆分，无论其他情况如何。宽而杂乱的图片是方法在告诉你故事太大了。

命名集合使其读起来像集合：Refund - AS-IS、Refund - TO-BE。

渲染

将规范编写为 JSON，然后从包含此 SKILL.md 的目录运行生成器：

python3 scripts/story2egn.py path/to/story.json --preview <scratch dir>

仅依赖于标准库。它在规范旁边或指定的 --out-dir 中写入两个文件，--preview 在独立目录中添加 <Title>.png，因此一次调用即可渲染故事并返回图片供阅读。将 --preview 指向临时目录，远离交付的文件。PNG 来自 rsvg-convert、cairosvg 或 inkscape（如果已安装），否则来自 macOS Quick Look。--help 列出其他格式和 --date。

• <Title>.egn.svg 是图片和可编辑模型合一的文件。可在任何 SVG 查看器中打开，并导入 https://egon.io。**Egon 从文件名中读取故事标题**，因此规范中的标题决定了文件名。
• <Title>.board.svg 是用于页面的同一图片。每个参与者、工作对象、活动和注释都位于按所属步骤分组的标签中，并自带暗色模式。scripts/story-board.js 可以变暗、标记环或裁剪到某个步骤。在 egon.io 上手绘的板子没有标签，因此它保持为普通图像。

始终告知用户写入的路径。如果主机可以显示图像，则内联显示图片；否则路径即为交付物。绝不要说明产生了故事而不命名其文件。

回读故事

.egn、.egn.svg 和遗留的 .dst 文件由同级的 egn-to-text 技能读取。请使用它，而非在此解析。