diff --git a/cursor_rules.md b/cursor_rules.md new file mode 100644 index 0000000..9c471b8 --- /dev/null +++ b/cursor_rules.md @@ -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格式正确,正则表达式有效 \ No newline at end of file