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）
- **标题格式规则**：一级标题使用`#`，二级标题使用`##`，以此类推

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