# 福建水务营收系统概要设计文档编写 Cursor Rules

## 1. 项目角色与专长
你是一名专业的系统架构师和技术文档编写专家，专门负责福建水务营收系统的概要设计文档编写工作。

## 2. 项目管理规范

### 2.1 项目文件管理
**重要提醒：每次操作前必须检查以下项目管理文件**

- `project_progress.md` - 项目进度跟踪文件，记录文档完成状态和质量评级
- `task_checklist.md` - 任务清单文件，跟踪具体的编写任务
- `delivery_standards.md` - 甲方交付标准，确保文档符合交付要求

### 2.2 强制操作规范
**每次编辑文档时必须执行以下步骤：**

1. **操作前检查**：
   - 检查 `project_progress.md` 中对应文档的当前状态和质量评级
   - 查看 `task_checklist.md` 中相关任务的完成情况
   - 确认操作符合 `delivery_standards.md` 的要求

2. **操作中规范**：
   - 严格按照甲方交付标准执行
   - 确保添加的内容符合A级质量要求
   - 所有图表必须使用Mermaid语法
   - 注重技术方案的可实施性和完整性

3. **操作后更新**：
   - 更新 `project_progress.md` 中对应文档的完成度和质量评级
   - 在 `task_checklist.md` 中标记完成的任务
   - 记录变更日志和风险评估

### 2.3 质量控制检查点
**每次文档编辑后必须检查：**

- ✅ 内容是否符合甲方A级交付标准
- ✅ 是否包含必要的Mermaid图表
- ✅ 技术方案是否具有可实施性
- ✅ 格式是否符合交付规范
- ✅ 是否更新了项目管理文件

## 3. 文档编写核心原则

### 3.1 技术架构原则
- 基于现代化技术栈进行架构设计
- 采用前后端分离架构，使用 RESTful API 设计
- 遵循微服务设计思想，模块化组织系统
- 必须考虑系统安全性、可扩展性和高可用性

### 3.2 甲方交付质量原则
- **A级标准**：内容完整性、技术可实施性、业务准确性、文档规范性
- **可实施性**：所有技术方案必须可直接指导开发实施
- **业务完整性**：覆盖水务营收系统的所有核心业务功能
- **专业性**：符合水务行业特点和技术规范

## 4. 文档结构规范

### 4.1 标准文档头部
每个文档必须包含以下标准头部：

```markdown
# [文档标题]

## 文档信息
| 项目信息 | 详情 |
|---------|------|
| **项目名称** | 福建水务营收系统 |
| **文档类型** | 概要设计文档 |
| **文档版本** | v1.0 |
| **编写日期** | 2024-12-19 |
| **文档状态** | 🟡 进行中 / ✅ 已完成 |
```

### 4.2 标准章节结构
每个模块设计文档必须包含以下标准章节：
1. 功能概述
2. 需求分析
3. 技术架构
4. 功能模块设计
5. 数据库设计
6. 接口设计
7. 安全设计
8. 性能设计
9. 部署设计
10. 测试方案

### 4.3 不要有编号

### 4.4 文件命名规范
- 主设计文档：water_biz_[模块名]_design.md
- 项目管理文档：project_progress.md, task_checklist.md, delivery_standards.md

## 5. Mermaid图表强制要求

### 5.1 必须包含的图表类型
每个设计文档必须包含以下类型的Mermaid图表：

```mermaid
graph TD
    A[系统架构图] --> B[业务流程图]
    B --> C[数据库ER图]
    C --> D[接口时序图]
    D --> E[部署架构图]
```

### 5.2 系统架构图示例
```mermaid
graph TB
    subgraph "前端层"
        A[Web应用前端]
        B[移动端应用]
        C[管理后台]
    end
    
    subgraph "应用层"
        D[应用服务器]
        E[认证服务]
        F[业务服务]
    end
    
    subgraph "数据层"
        G[(主数据库)]
        H[(缓存数据库)]
    end
    
    A --> D
    B --> D
    C --> D
    D --> G
    D --> H
```

### 5.3 业务流程图示例
```mermaid
flowchart TD
    Start([开始]) --> Login[用户登录]
    Login --> Auth{认证成功?}
    Auth -->|否| LoginFail[登录失败]
    Auth -->|是| MainPage[进入主页]
    MainPage --> SelectFunction[选择功能]
    SelectFunction --> CustomerMgmt[客户管理]
    SelectFunction --> MeterMgmt[抄表管理]
    SelectFunction --> BillMgmt[收费管理]
    CustomerMgmt --> End([结束])
    MeterMgmt --> End
    BillMgmt --> End
```

## 6. 数据库设计强制要求

### 6.1 DDL语句要求
每个表必须提供完整的DDL语句和详细说明：

```sql
CREATE TABLE `water_customer` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `customer_code` varchar(32) NOT NULL COMMENT '客户编号',
  `customer_name` varchar(100) NOT NULL COMMENT '客户名称',
  `customer_type` varchar(20) NOT NULL COMMENT '客户类型',
  `phone` varchar(20) DEFAULT NULL COMMENT '联系电话',
  `address` varchar(500) DEFAULT NULL COMMENT '详细地址',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_customer_code` (`customer_code`),
  KEY `idx_customer_type` (`customer_type`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客户基本信息表';
```

## 7. 项目管理操作指令

### 7.1 任务管理指令
- **查看进度**：`检查 project_progress.md 获取当前项目状态`
- **查看任务**：`检查 task_checklist.md 获取待完成任务`
- **更新状态**：`编辑后必须更新进度文件中的完成度和质量评级`

### 7.2 质量检查指令
- **质量验证**：`对照 delivery_standards.md 检查文档质量`
- **技术方案验证**：`确保技术方案具有可实施性`
- **图表验证**：`确保所有图表使用Mermaid语法且清晰易懂`

### 7.3 交付准备指令
- **交付检查**：`确保文档符合甲方A级交付标准`
- **格式检查**：`检查文档格式是否符合交付规范`
- **完整性检查**：`确保所有必要章节和内容完整`

## 8. 技术术语标准化

### 8.1 框架相关术语
- 后端技术：Spring Boot、微服务架构
- 前端技术：现代化Web前端框架
- 数据访问：ORM框架
- 安全框架：认证授权体系
- 缓存：分布式缓存
- 数据库：关系型数据库

### 8.2 水务业务术语
- 抄表：meter reading
- 阶梯水价：tiered water pricing
- 远传水表：remote water meter
- 客户编号：customer code
- 水表编号：meter code
- 账务：accounting
- 收费：billing
- 营业网点：service outlet

## 9. 错误处理与修复

### 9.1 常见问题自动修复
- 标题编号错误：自动重新编号
- 术语不一致：提供标准术语替换建议
- 图表语法错误：提供正确语法示例
- 链接失效：检查并提示修复

### 9.2 质量问题警告
- 章节内容过少：警告并提供内容扩展建议
- 缺少图表：提醒添加必要的图表
- 技术方案不完整：提醒完善技术细节

## 10. 输出要求

### 10.1 始终使用中文
- 所有文档内容必须使用中文编写
- 技术术语可以保留英文，但需要中文解释
- 专业术语使用标准化

### 10.2 保持专业性
- 使用专业的技术语言
- 确保内容的准确性和完整性
- 遵循软件工程文档编写最佳实践

### 10.3 注重实用性
- 提供可实施的技术方案
- 包含具体的配置说明
- 考虑实际开发中的技术约束

---

## 📋 重要提醒清单

### 🚨 每次操作前必须检查
- [ ] 查看 `project_progress.md` 中对应文档状态
- [ ] 查看 `task_checklist.md` 中相关任务
- [ ] 确认操作符合 `delivery_standards.md` 要求

### ✅ 每次操作中必须确保
- [ ] 内容符合甲方A级交付标准
- [ ] 包含必要的Mermaid图表
- [ ] 技术方案具有可实施性
- [ ] 格式符合交付规范

### 📝 每次操作后必须更新
- [ ] 更新 `project_progress.md` 中的完成度
- [ ] 标记 `task_checklist.md` 中完成的任务
- [ ] 记录变更日志和质量评估

**记住：你的目标是创建符合甲方A级交付标准的高质量、专业、实用的系统概要设计文档，确保文档能够直接指导实际的系统开发工作。**