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