3.0 KiB
功能模块文档撰写说明
适用文件：doc/功能模块/<模块名>/<模块名>(目录名).md。
目录
单文档形态见本节「一条主业务」。拆分形态的示例是 编辑器主文档 和 绘制。
主文档写什么
1. 模块目录结构
写出该 src/features/[feature] 内部的目录和承担业务的文件。空目录按仓库现状保留。
2. 功能定义
一段话定义这个模块做什么。下面列出它包含的业务。每条业务一句话。
3. 核心业务层与核心模型
分两节，不合并成「核心类」。
核心业务层是 ViewModel。每个 ViewModel 写定义、文件路径和方法。公开方法必写，承担业务的私有方法一并列出。方法写签名和这个方法做什么。页面组件不列入。
核心模型写聚合根、它包含的实体，以及不变条件。每个类型写定义、文件路径和领域方法。包含关系用类图。外部只能调用聚合根的方法。存储位置、接口报文字段不写进实体。
需要画出页面怎样向聚合提交动作时，另用用例图：参与者写 ViewModel，用例写聚合根的方法名。类图和用例图不要重复同一件事。
一条主业务
模块只有一条要讲述的主业务时，不另建文件。主文档增加第 4 节「核心业务」，放一张时序图。图中只用类名和方法名，图下用中文按调用顺序写清这条业务。
只有一条主业务的模块，目录是：
## 目录
- [模块目录结构](#模块目录结构)
- [功能定义](#功能定义)
- [核心业务层](#核心业务层)
- [核心模型](#核心模型)
- [核心业务](#核心业务)
「核心业务」里直接放时序图。例如项目模块的保存：调用方 → ProjectApplication.save → IProjectRepository。应用层先按 store 选定实现，领域端口本身不区分本地和远程。list、get、save、create 写在功能定义。落笔、撤销和重做写在聚合根。
多条事件业务
同一模块有多条事件业务时，主文档不放时序图。第 4 节改为「业务文档」，作为索引链到同目录下的各篇。
编辑器按事件拆开，例如：
doc/功能模块/编辑器模块/
├── 编辑器模块(editor).md
├── 打开项目.md
├── 绘制.md
└── 撤销与重做.md
主文档目录里列出这些文件。
业务文档写什么
每篇业务文档包含目录，以及：
- 业务定义：这个事件做什么，从哪个操作开始。
- 时序图：参与者使用主文档里的类名，箭头文字使用方法名。图下用中文按顺序说明这次事件。
方法表留在主文档的核心业务层。业务文档点名本事件调用的方法。