Add a scaffold script that replaces the bq prefix with the new project name.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
75
doc/项目文档/功能模块/*功能模块文档撰写说明.md
Normal file
75
doc/项目文档/功能模块/*功能模块文档撰写说明.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# 功能模块文档撰写说明
|
||||
|
||||
适用文件:`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. 时序图:参与者使用主文档里的类名,箭头文字使用方法名。图下用中文按顺序说明这次事件。
|
||||
|
||||
方法表留在主文档的核心业务层。业务文档点名本事件调用的方法。
|
||||
Reference in New Issue
Block a user