添加Cursor Rules配置指南文档，详细说明文档编写规范、基础规则、语言规范、业务领域规则等内容，以提高文档质量和协作效率。
This commit is contained in:
parent
60a217da4f
commit
c48b61c4ac
296
cursor_rules.md
Normal file
296
cursor_rules.md
Normal file
@ -0,0 +1,296 @@
|
||||
# Cursor Rules 配置指南
|
||||
|
||||
## 一、Cursor Rules 概述
|
||||
|
||||
Cursor Rules 是一套文档编写规范检查工具，用于确保福建水务营收系统概要设计文档的一致性、规范性和可读性。通过配置适当的规则，可以帮助文档编写者遵循统一的格式和风格，提高文档质量和协作效率。
|
||||
|
||||
## 二、基础规则配置
|
||||
|
||||
### 1. 文档格式规则
|
||||
|
||||
#### 1.1 文档结构规则
|
||||
|
||||
- **文件命名规则**：所有文档文件名应使用英文小写，单词之间使用下划线连接，以`.md`为扩展名，例如：`water_biz_system_architecture.md`
|
||||
- **标题层级规则**：最多使用四级标题，使用数字编号（如：一、1、1.1、1.1.1）
|
||||
- **标题格式规则**：一级标题使用`#`，二级标题使用`##`，以此类推
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: document-file-naming
|
||||
pattern: "^[a-z]+(_[a-z]+)*\\.md$"
|
||||
message: "文件名应使用英文小写，单词之间使用下划线连接，以.md为扩展名"
|
||||
|
||||
- name: heading-hierarchy
|
||||
pattern: "^#{1,4} [一二三四五六七八九十]、|^#{2,5} \\d+(\\.\\d+){0,2}、"
|
||||
message: "标题层级应遵循规定的编号格式"
|
||||
```
|
||||
|
||||
#### 1.2 段落格式规则
|
||||
|
||||
- **段落长度**：每个段落不应超过500个字符
|
||||
- **行间距**：段落之间保留一个空行
|
||||
- **缩进**：不使用Tab缩进，使用空格对齐
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: paragraph-length
|
||||
pattern: ".{500,}"
|
||||
message: "段落长度不应超过500个字符"
|
||||
|
||||
- name: paragraph-spacing
|
||||
pattern: "\n\n"
|
||||
message: "段落之间应保留一个空行"
|
||||
```
|
||||
|
||||
### 2. 语言规范
|
||||
|
||||
#### 2.1 术语一致性
|
||||
|
||||
- **专业术语**：保持专业术语的一致性，遵循术语表中的定义
|
||||
- **缩写规则**：首次出现的缩写应给出全称解释，例如：RBAC（基于角色的访问控制）
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: abbreviation-explanation
|
||||
pattern: "[A-Z]{2,}(?!（.*）|\\(.*\\))"
|
||||
message: "首次出现的缩写应给出全称解释"
|
||||
```
|
||||
|
||||
#### 2.2 标点符号
|
||||
|
||||
- **使用全角标点**：中文内容中使用全角标点（如：，。；：""）
|
||||
- **使用半角标点**：英文内容中使用半角标点（如: , . ; : ""）
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: chinese-punctuation
|
||||
pattern: "[，。；：""！？]"
|
||||
scope: "chinese-content"
|
||||
message: "中文内容应使用全角标点"
|
||||
|
||||
- name: english-punctuation
|
||||
pattern: "[,.;:\"\"!?]"
|
||||
scope: "english-content"
|
||||
message: "英文内容应使用半角标点"
|
||||
```
|
||||
|
||||
## 三、业务领域规则
|
||||
|
||||
### 1. 水务营收术语规范
|
||||
|
||||
- **统一术语**：使用统一的水务营收领域术语，如：抄表、水价、阶梯水价、远传水表等
|
||||
- **术语解释**：关键业务术语首次出现时应提供简要解释
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: water-business-terms
|
||||
pattern: "(抄表|水价|阶梯水价|远传水表|客户编号|水表编号|账务|账单周期)"
|
||||
message: "请检查水务营收术语使用是否规范"
|
||||
```
|
||||
|
||||
### 2. 技术术语规范
|
||||
|
||||
- **统一框架术语**：使用RuoYi-Vue-Pro和yudao-ui-admin-vue3框架的官方术语
|
||||
- **版本一致性**：技术组件版本号应保持一致，如：Spring Boot 2.7.x
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: framework-terms
|
||||
pattern: "(RuoYi-Vue-Pro|yudao-ui-admin-vue3)"
|
||||
message: "框架名称应使用官方正确拼写"
|
||||
|
||||
- name: version-consistency
|
||||
pattern: "(Spring Boot|MySQL|Redis|JDK)\\s+\\d+(\\.\\d+)*"
|
||||
message: "技术组件版本号应保持一致"
|
||||
```
|
||||
|
||||
## 四、图表规范
|
||||
|
||||
### 1. 流程图规范
|
||||
|
||||
- **使用Mermaid**：流程图应使用Mermaid语法编写
|
||||
- **图表标题**：每个图表应有明确的标题
|
||||
- **流程方向**：流程图应从上到下或从左到右展示
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: mermaid-flow-chart
|
||||
pattern: "```mermaid\\s+graph (TD|LR)"
|
||||
message: "流程图应使用Mermaid语法，并明确方向(TD或LR)"
|
||||
```
|
||||
|
||||
### 2. ER图规范
|
||||
|
||||
- **使用Mermaid**：ER图应使用Mermaid语法的erDiagram编写
|
||||
- **关系表示**：实体间关系应使用标准符号表示，如：||--o{
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: mermaid-er-diagram
|
||||
pattern: "```mermaid\\s+erDiagram"
|
||||
message: "ER图应使用Mermaid语法的erDiagram"
|
||||
```
|
||||
|
||||
### 3. 架构图规范
|
||||
|
||||
- **使用Mermaid**：架构图应使用Mermaid语法编写
|
||||
- **分层清晰**：架构图应清晰显示系统分层
|
||||
- **组件关系**：组件间关系应明确标示
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: mermaid-architecture-diagram
|
||||
pattern: "```mermaid\\s+graph (TD|LR)\\s+subgraph"
|
||||
message: "架构图应使用Mermaid语法，并使用subgraph表示分层"
|
||||
```
|
||||
|
||||
## 五、代码示例规范
|
||||
|
||||
### 1. 代码块规范
|
||||
|
||||
- **语言标记**：代码块应标明语言类型，如：```java
|
||||
- **代码缩进**：代码应使用统一的缩进风格
|
||||
- **注释规范**：关键代码处应添加注释
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: code-block-language
|
||||
pattern: "```(java|xml|yaml|json|sql|html|css|javascript)"
|
||||
message: "代码块应标明语言类型"
|
||||
```
|
||||
|
||||
### 2. 配置示例规范
|
||||
|
||||
- **格式一致**：配置示例应使用统一的格式
|
||||
- **关键参数**：关键配置参数应有注释说明
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: config-example-format
|
||||
pattern: "```(yaml|properties|json)\\s+"
|
||||
message: "配置示例应使用统一的格式并标明语言类型"
|
||||
```
|
||||
|
||||
## 六、引用链接规范
|
||||
|
||||
### 1. 内部链接规范
|
||||
|
||||
- **相对路径**：文档间链接应使用相对路径
|
||||
- **锚点链接**：同一文档内的跳转应使用锚点链接
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: relative-path-link
|
||||
pattern: "\\[.*?\\]\\((?!http|https|ftp).*?\\)"
|
||||
message: "文档间链接应使用相对路径"
|
||||
```
|
||||
|
||||
### 2. 外部链接规范
|
||||
|
||||
- **完整URL**：外部链接应使用完整URL，包含协议头
|
||||
- **链接描述**：链接文本应描述链接目标内容
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: external-link-format
|
||||
pattern: "\\[.*?\\]\\((http|https|ftp)://.*?\\)"
|
||||
message: "外部链接应使用完整URL，包含协议头"
|
||||
```
|
||||
|
||||
## 七、表格规范
|
||||
|
||||
### 1. 表格格式规则
|
||||
|
||||
- **表头行**：每个表格应有表头行
|
||||
- **对齐方式**：表格列应根据内容类型设置对齐方式（左对齐、居中、右对齐）
|
||||
- **单元格内容**：单元格内容应简洁明了
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: table-header
|
||||
pattern: "\\|.*?\\|.*?\\|\\s*\\n\\|\\s*[-:]+\\s*\\|"
|
||||
message: "表格应有表头行和分隔行"
|
||||
|
||||
- name: table-alignment
|
||||
pattern: "\\|\\s*:?-+:?\\s*\\|"
|
||||
message: "表格列应设置对齐方式"
|
||||
```
|
||||
|
||||
### 2. 表格内容规则
|
||||
|
||||
- **字段描述**：数据库表字段应包含字段名、类型、长度、是否必填、说明等内容
|
||||
- **接口描述**：接口表格应包含参数名、类型、是否必填、说明等内容
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: database-field-table
|
||||
pattern: "\\|\\s*字段名\\s*\\|\\s*数据类型\\s*\\|\\s*长度\\s*\\|\\s*是否必填\\s*\\|"
|
||||
message: "数据库表字段表格应包含规定的列"
|
||||
|
||||
- name: api-parameter-table
|
||||
pattern: "\\|\\s*参数名\\s*\\|\\s*类型\\s*\\|\\s*是否必填\\s*\\|\\s*说明\\s*\\|"
|
||||
message: "接口参数表格应包含规定的列"
|
||||
```
|
||||
|
||||
## 八、自定义规则配置方法
|
||||
|
||||
### 1. 规则定义格式
|
||||
|
||||
Cursor Rules支持自定义规则，规则定义使用YAML格式：
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- name: rule-name # 规则名称
|
||||
pattern: "regex-pattern" # 正则表达式模式
|
||||
message: "error-message" # 错误提示信息
|
||||
severity: "warning" # 严重程度：error, warning, info
|
||||
scope: "scope-selector" # 应用范围：可选
|
||||
```
|
||||
|
||||
### 2. 正则表达式说明
|
||||
|
||||
- **基本匹配**：使用标准正则表达式语法
|
||||
- **捕获组**：使用()进行分组捕获
|
||||
- **反向引用**：使用\1, \2等引用捕获组
|
||||
|
||||
### 3. 规则应用范围
|
||||
|
||||
- **全局规则**：适用于整个文档
|
||||
- **语言规则**：适用于特定语言内容
|
||||
- **块级规则**：适用于特定类型的块，如代码块、表格等
|
||||
|
||||
## 九、规则应用建议
|
||||
|
||||
### 1. 适用场景
|
||||
|
||||
- **文档初始化**：在开始编写文档前配置规则
|
||||
- **协作编写**：多人协作编写时确保风格一致
|
||||
- **文档审核**：文档审核阶段检查规范性
|
||||
|
||||
### 2. 使用策略
|
||||
|
||||
- **渐进应用**：先应用基础规则，再逐步增加专业规则
|
||||
- **规则优先级**：设置规则优先级，解决规则冲突
|
||||
- **规则抑制**：对特定内容可临时抑制规则检查
|
||||
|
||||
## 十、常见问题解决
|
||||
|
||||
### 1. 规则冲突
|
||||
|
||||
- **问题描述**：多个规则之间存在冲突，导致无法同时满足
|
||||
- **解决方案**：设置规则优先级，明确哪条规则更重要
|
||||
|
||||
### 2. 误报处理
|
||||
|
||||
- **问题描述**：规则检查结果出现误报
|
||||
- **解决方案**：优化规则正则表达式，或为特定内容添加规则抑制标记
|
||||
|
||||
### 3. 规则过于严格
|
||||
|
||||
- **问题描述**：规则要求过于严格，影响编写效率
|
||||
- **解决方案**：调整规则严重程度，将部分规则从error降级为warning或info
|
||||
|
||||
### 4. 规则不生效
|
||||
|
||||
- **问题描述**：配置的规则不生效
|
||||
- **解决方案**：检查规则语法，确保YAML格式正确，正则表达式有效
|
||||
Loading…
x
Reference in New Issue
Block a user