fujian_water_biz_doc/cursor_rules.md

Cursor Rules 配置指南

一、Cursor Rules 概述

Cursor Rules 是一套文档编写规范检查工具，用于确保福建水务营收系统概要设计文档的一致性、规范性和可读性。通过配置适当的规则，可以帮助文档编写者遵循统一的格式和风格，提高文档质量和协作效率。

二、基础规则配置

1. 文档格式规则

1.1 文档结构规则

• 文件命名规则：所有文档文件名应使用英文小写，单词之间使用下划线连接，以.md为扩展名，例如：water_biz_system_architecture.md
• 标题层级规则：最多使用四级标题，使用数字编号（如：一、1、1.1、1.1.1）
• 标题格式规则：一级标题使用#，二级标题使用##，以此类推

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缩进，使用空格对齐

rules:
  - name: paragraph-length
    pattern: ".{500,}"
    message: "段落长度不应超过500个字符"
    
  - name: paragraph-spacing
    pattern: "\n\n"
    message: "段落之间应保留一个空行"

2. 语言规范

2.1 术语一致性

• 专业术语：保持专业术语的一致性，遵循术语表中的定义
• 缩写规则：首次出现的缩写应给出全称解释，例如：RBAC（基于角色的访问控制）

rules:
  - name: abbreviation-explanation
    pattern: "[A-Z]{2,}(?!（.*）|\\(.*\\))"
    message: "首次出现的缩写应给出全称解释"

2.2 标点符号

• 使用全角标点：中文内容中使用全角标点（如：，。；：""）
• 使用半角标点：英文内容中使用半角标点（如: , . ; : ""）

rules:
  - name: chinese-punctuation
    pattern: "[，。；：""！？]"
    scope: "chinese-content"
    message: "中文内容应使用全角标点"
    
  - name: english-punctuation
    pattern: "[,.;:\"\"!?]"
    scope: "english-content"
    message: "英文内容应使用半角标点"

三、业务领域规则

1. 水务营收术语规范

• 统一术语：使用统一的水务营收领域术语，如：抄表、水价、阶梯水价、远传水表等
• 术语解释：关键业务术语首次出现时应提供简要解释

rules:
  - name: water-business-terms
    pattern: "(抄表|水价|阶梯水价|远传水表|客户编号|水表编号|账务|账单周期)"
    message: "请检查水务营收术语使用是否规范"

2. 技术术语规范

• 统一框架术语：使用RuoYi-Vue-Pro和yudao-ui-admin-vue3框架的官方术语
• 版本一致性：技术组件版本号应保持一致，如：Spring Boot 2.7.x

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语法编写
• 图表标题：每个图表应有明确的标题
• 流程方向：流程图应从上到下或从左到右展示

rules:
  - name: mermaid-flow-chart
    pattern: "```mermaid\\s+graph (TD|LR)"
    message: "流程图应使用Mermaid语法，并明确方向(TD或LR)"

2. ER图规范

• 使用Mermaid：ER图应使用Mermaid语法的erDiagram编写
• 关系表示：实体间关系应使用标准符号表示，如：||--o{

rules:
  - name: mermaid-er-diagram
    pattern: "```mermaid\\s+erDiagram"
    message: "ER图应使用Mermaid语法的erDiagram"

3. 架构图规范

• 使用Mermaid：架构图应使用Mermaid语法编写
• 分层清晰：架构图应清晰显示系统分层
• 组件关系：组件间关系应明确标示

rules:
  - name: mermaid-architecture-diagram
    pattern: "```mermaid\\s+graph (TD|LR)\\s+subgraph"
    message: "架构图应使用Mermaid语法，并使用subgraph表示分层"

五、代码示例规范

1. 代码块规范

• 语言标记：代码块应标明语言类型，如：```java
• 代码缩进：代码应使用统一的缩进风格
• 注释规范：关键代码处应添加注释

rules:
  - name: code-block-language
    pattern: "```(java|xml|yaml|json|sql|html|css|javascript)"
    message: "代码块应标明语言类型"

2. 配置示例规范

• 格式一致：配置示例应使用统一的格式
• 关键参数：关键配置参数应有注释说明

rules:
  - name: config-example-format
    pattern: "```(yaml|properties|json)\\s+"
    message: "配置示例应使用统一的格式并标明语言类型"

六、引用链接规范

1. 内部链接规范

• 相对路径：文档间链接应使用相对路径
• 锚点链接：同一文档内的跳转应使用锚点链接

rules:
  - name: relative-path-link
    pattern: "\\[.*?\\]\\((?!http|https|ftp).*?\\)"
    message: "文档间链接应使用相对路径"

2. 外部链接规范

• 完整URL：外部链接应使用完整URL，包含协议头
• 链接描述：链接文本应描述链接目标内容

rules:
  - name: external-link-format
    pattern: "\\[.*?\\]\\((http|https|ftp)://.*?\\)"
    message: "外部链接应使用完整URL，包含协议头"

七、表格规范

1. 表格格式规则

• 表头行：每个表格应有表头行
• 对齐方式：表格列应根据内容类型设置对齐方式（左对齐、居中、右对齐）
• 单元格内容：单元格内容应简洁明了

rules:
  - name: table-header
    pattern: "\\|.*?\\|.*?\\|\\s*\\n\\|\\s*[-:]+\\s*\\|"
    message: "表格应有表头行和分隔行"
    
  - name: table-alignment
    pattern: "\\|\\s*:?-+:?\\s*\\|"
    message: "表格列应设置对齐方式"

2. 表格内容规则

• 字段描述：数据库表字段应包含字段名、类型、长度、是否必填、说明等内容
• 接口描述：接口表格应包含参数名、类型、是否必填、说明等内容

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格式：

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格式正确，正则表达式有效