128 lines
4.4 KiB
Markdown
128 lines
4.4 KiB
Markdown
# 一、文档结构层级规范
|
||
|
||
|
||
## 1.1 标题层级定义
|
||
|
||
- 一级标题 ：核心业务模块，对应MES一级标题和文档核心业务文件夹名称
|
||
- 二级标题 ：功能模块标题，对应MES二级标题和文档功能文件名称
|
||
- 三级标题 ：功能节点页面，用于细分功能内的具体内容，格式为 #### X.X.X 详细内容
|
||
- 特殊加强 : 针对特殊加强部分，可以使用 **功能标题：** 进行特殊加强
|
||
|
||
|
||
|
||
> 标题层级定义中，一级标题对应MES一级标题和文档核心业务文件夹名称，二级标题对应MES二级标题和文档功能文件名称，三级标题对应MES三级标题和文档功能节点页面名称。
|
||
|
||
> 英文翻译 、 代码模块命名 、文档目录和命名 必须一致，不能有差异。
|
||
|
||
# 二、标题块书写标准
|
||
|
||
## 2.1 功能概述块标准格式
|
||
|
||
每个功能模块的开篇应包含功能概述块，采用以下标准格式：
|
||
|
||
```text
|
||
**核心功能：**
|
||
|
||
- 功能点一
|
||
- 功能点二
|
||
- 功能点三
|
||
```
|
||
|
||
概述内容应简洁明了，通常列出3至6个核心功能点，使用无序列表呈现。概述块放置于功能节标题之后、正文内容之前。
|
||
|
||
## 2.2 术语说明块标准格式
|
||
|
||
涉及专业术语的章节应包含术语说明块，采用表格形式呈现：
|
||
|
||
```text
|
||
#### X.X.X 术语说明
|
||
|
||
| 术语 | 定义 | 说明 |
|
||
|------|------|------|
|
||
| 术语一 | 术语一定义 | 补充说明 |
|
||
| 术语二 | 术语二定义 | 补充说明 |
|
||
```
|
||
表格应包含术语、定义、说明三列，定义列应简洁准确，说明列提供必要的上下文信息。
|
||
|
||
# 三、操作说明块书写标准
|
||
|
||
## 3.1 操作步骤标准格式
|
||
|
||
操作说明应采用编号列表形式，基本格式如下：
|
||
|
||
```text
|
||
**操作步骤：**
|
||
|
||
1. 进入【菜单路径】→【子菜单】
|
||
2. 点击【操作按钮】
|
||
3. 填写表单信息
|
||
4. 点击【确认】完成操作
|
||
```
|
||
操作步骤应遵循以下规范：每个步骤以动词开头（如进入、点击、填写、选择、确认等）；菜单路径使用【】包裹；按钮名称使用【】包裹；操作说明使用祈使句式；步骤编号连续不间断。
|
||
|
||
## 3.2 字段说明表格标准格式
|
||
|
||
操作中涉及的表单字段应使用标准表格进行说明：
|
||
|
||
```text
|
||
| 字段 | 说明 | 必填 |
|
||
|------|------|------|
|
||
| 字段一 | 字段一的含义和填写要求 | 是 |
|
||
| 字段二 | 字段二的含义和填写要求 | 否 |
|
||
```
|
||
|
||
表格必须包含字段、说明、必填三列。必填列使用“是”或“否”标识。说明列应详细描述字段的用途、格式要求、取值范围等信息。对于需要自动生成的字段，在必填列标注“-”或说明“系统自动生成”。
|
||
|
||
## 3.3 提示与注意事项标注规范
|
||
|
||
文档中应使用统一的标注符号系统来提示不同类型的信息：
|
||
|
||
- 【重要】 ：用于标识关键操作点或不可逆操作，如“【重要】删除操作不可恢复，请谨慎操作”
|
||
- 【注意】 ：用于标识常见的操作误区或需要特别关注的事项，如“【注意】修改BOM版本会影响新的工单”
|
||
- 【提示】 ：用于提供便于操作的技巧或建议，如“【提示】建议使用移动端进行扫码操作”
|
||
|
||
这些标注应放置于相关操作说明的末尾或独立成段，使用加粗格式以突出显示。
|
||
|
||
## 3.4 查询条件与结果说明规范
|
||
|
||
涉及查询功能的操作应包含查询条件说明：
|
||
|
||
```text
|
||
**查询条件：**
|
||
|
||
| 查询条件 | 说明 |
|
||
|---------|------|
|
||
| 条件一 | 条件一的含义 |
|
||
| 条件二 | 条件二的选择方式 |
|
||
|
||
```
|
||
查询结果应描述系统的返回内容和展示方式，必要时使用表格或图示说明结果字段的含义。
|
||
|
||
# 四、截图说明块书写标准
|
||
|
||
## 4.1 界面示意图绘制规范
|
||
|
||
图片名称或说明用 **图片说明** 放置在图片插入点上方
|
||
|
||
```text
|
||
**操作示意图：**
|
||
|
||
xxxxxx[图片]
|
||
```
|
||
|
||
|
||
|
||
图片命名格式：
|
||
图片描述.png/svg ....
|
||
|
||
# 五、流程说明块书写标准
|
||
|
||
5.1 流程图规范
|
||
|
||
所有文档中的流程图，均使用mermaid语法绘制。
|
||
|
||
如果涉及到mermaid无法表述的复杂图表，使用SVG方式进行嵌入，并确保SVG来源于Draw.IO绘制导出的标准SVG格式。
|
||
|
||
# 六、文档样例
|
||
|
||
> 查阅 basic/factory_model.md 文件 |