# 功能模块文档撰写说明

适用文件：`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. 时序图：参与者使用主文档里的类名，箭头文字使用方法名。图下用中文按顺序说明这次事件。

方法表留在主文档的核心业务层。业务文档点名本事件调用的方法。