366 lines
11 KiB
Plaintext
366 lines
11 KiB
Plaintext
# 福建水务营收系统概要设计文档编写 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级质量要求
|
||
- 所有代码示例必须基于RuoYi-Vue-Pro框架
|
||
- 所有图表必须使用Mermaid语法
|
||
|
||
3. **操作后更新**：
|
||
- 更新 `project_progress.md` 中对应文档的完成度和质量评级
|
||
- 在 `task_checklist.md` 中标记完成的任务
|
||
- 记录变更日志和风险评估
|
||
|
||
### 2.3 质量控制检查点
|
||
**每次文档编辑后必须检查：**
|
||
|
||
- ✅ 内容是否符合甲方A级交付标准
|
||
- ✅ 是否包含完整的RuoYi-Vue-Pro代码示例
|
||
- ✅ 是否包含必要的Mermaid图表
|
||
- ✅ 格式是否符合交付规范
|
||
- ✅ 是否更新了项目管理文件
|
||
|
||
## 3. 文档编写核心原则
|
||
|
||
### 3.1 技术架构原则
|
||
- 必须基于 RuoYi-Vue-Pro 后端框架和 yudao-ui-admin-vue3 前端框架
|
||
- 采用前后端分离架构，使用 RESTful API 设计
|
||
- 遵循微服务设计思想，模块化组织代码
|
||
- 必须考虑系统安全性、可扩展性和高可用性
|
||
|
||
### 3.2 甲方交付质量原则
|
||
- **A级标准**：内容完整性、技术可实施性、业务准确性、文档规范性、代码示例完整
|
||
- **可实施性**：所有技术方案必须可直接指导开发实施
|
||
- **业务完整性**：覆盖水务营收系统的所有核心业务功能
|
||
- **专业性**：符合水务行业特点和技术规范
|
||
|
||
## 4. 文档结构规范
|
||
|
||
### 4.1 标准文档头部
|
||
每个文档必须包含以下标准头部：
|
||
|
||
```markdown
|
||
# [文档标题]
|
||
|
||
## 文档信息
|
||
| 项目信息 | 详情 |
|
||
|---------|------|
|
||
| **项目名称** | 福建水务营收系统 |
|
||
| **文档类型** | 概要设计文档 |
|
||
| **技术框架** | RuoYi-Vue-Pro + yudao-ui-admin-vue3 |
|
||
| **文档版本** | v1.0 |
|
||
| **编写日期** | 2024-12-19 |
|
||
| **文档状态** | 🟡 进行中 / ✅ 已完成 |
|
||
```
|
||
|
||
### 4.2 标准章节结构
|
||
每个模块设计文档必须包含以下标准章节：
|
||
1. 功能概述
|
||
2. 需求分析
|
||
3. 技术架构
|
||
4. 功能模块设计
|
||
5. 数据库设计
|
||
6. 接口设计
|
||
7. 安全设计
|
||
8. 性能设计
|
||
9. 部署设计
|
||
10. 测试方案
|
||
|
||
### 4.3 标题编号规范
|
||
- 一级标题：# 一、二、三...
|
||
- 二级标题：## 1、2、3...
|
||
- 三级标题：### 1.1、1.2、1.3...
|
||
- 四级标题：#### 1.1.1、1.1.2、1.1.3...
|
||
|
||
### 4.4 文件命名规范
|
||
- 主设计文档：water_biz_[模块名]_design.md
|
||
- 项目管理文档：project_progress.md, task_checklist.md, delivery_standards.md
|
||
|
||
## 5. 代码示例强制规范
|
||
|
||
### 5.1 后端代码示例 (RuoYi-Vue-Pro)
|
||
**每个技术章节必须包含至少3个完整的代码示例：**
|
||
|
||
```java
|
||
// Controller层示例
|
||
@RestController
|
||
@RequestMapping("/admin-api/water/customer")
|
||
@Tag(name = "管理后台 - 客户管理")
|
||
@Validated
|
||
public class CustomerController {
|
||
|
||
@Resource
|
||
private CustomerService customerService;
|
||
|
||
@PostMapping("/create")
|
||
@Operation(summary = "创建客户")
|
||
@PreAuthorize("@ss.hasPermission('water:customer:create')")
|
||
public CommonResult<Long> createCustomer(@Valid @RequestBody CustomerSaveReqVO createReqVO) {
|
||
return success(customerService.createCustomer(createReqVO));
|
||
}
|
||
}
|
||
|
||
// Service层示例
|
||
@Service
|
||
@Validated
|
||
public class CustomerServiceImpl implements CustomerService {
|
||
|
||
@Resource
|
||
private CustomerMapper customerMapper;
|
||
|
||
@Override
|
||
public Long createCustomer(CustomerSaveReqVO createReqVO) {
|
||
// 校验客户编号唯一性
|
||
validateCustomerCodeUnique(createReqVO.getCustomerCode());
|
||
|
||
// 创建客户
|
||
CustomerDO customer = BeanUtils.toBean(createReqVO, CustomerDO.class);
|
||
customerMapper.insert(customer);
|
||
return customer.getId();
|
||
}
|
||
}
|
||
|
||
// Entity层示例
|
||
@TableName("water_customer")
|
||
@Data
|
||
@EqualsAndHashCode(callSuper = true)
|
||
@ToString(callSuper = true)
|
||
@Builder
|
||
@NoArgsConstructor
|
||
@AllArgsConstructor
|
||
public class CustomerDO extends BaseDO {
|
||
|
||
@TableId(value = "id", type = IdType.ASSIGN_ID)
|
||
private Long id;
|
||
|
||
@Schema(description = "客户编号", requiredMode = Schema.RequiredMode.REQUIRED, example = "C001")
|
||
private String customerCode;
|
||
|
||
@Schema(description = "客户名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "张三")
|
||
private String customerName;
|
||
}
|
||
```
|
||
|
||
### 5.2 前端代码示例 (yudao-ui-admin-vue3)
|
||
**每个前端相关章节必须包含Vue 3 + TypeScript示例：**
|
||
|
||
```typescript
|
||
<script setup lang="ts">
|
||
import { ref, onMounted } from 'vue'
|
||
import { CustomerApi, CustomerVO } from '@/api/water/customer'
|
||
import { formatDate } from '@/utils/formatTime'
|
||
|
||
const customerList = ref<CustomerVO[]>([])
|
||
const loading = ref(true)
|
||
const queryParams = ref({
|
||
pageNo: 1,
|
||
pageSize: 10,
|
||
customerName: '',
|
||
customerCode: ''
|
||
})
|
||
|
||
const getCustomerList = async () => {
|
||
loading.value = true
|
||
try {
|
||
const data = await CustomerApi.getCustomerPage(queryParams.value)
|
||
customerList.value = data.list
|
||
} finally {
|
||
loading.value = false
|
||
}
|
||
}
|
||
|
||
onMounted(() => {
|
||
getCustomerList()
|
||
})
|
||
</script>
|
||
```
|
||
|
||
## 6. Mermaid图表强制要求
|
||
|
||
### 6.1 必须包含的图表类型
|
||
每个设计文档必须包含以下类型的Mermaid图表：
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[系统架构图] --> B[业务流程图]
|
||
B --> C[数据库ER图]
|
||
C --> D[接口时序图]
|
||
D --> E[部署架构图]
|
||
```
|
||
|
||
### 6.2 系统架构图示例
|
||
```mermaid
|
||
graph TB
|
||
subgraph "前端层"
|
||
A[Vue3 + TypeScript]
|
||
B[Element Plus]
|
||
C[移动端 uni-app]
|
||
end
|
||
|
||
subgraph "应用层"
|
||
D[Spring Boot 3.x]
|
||
E[Spring Security]
|
||
F[MyBatis Plus]
|
||
end
|
||
|
||
subgraph "数据层"
|
||
G[(MySQL 8.0+)]
|
||
H[(Redis 6.0+)]
|
||
end
|
||
|
||
A --> D
|
||
B --> D
|
||
C --> D
|
||
D --> G
|
||
D --> H
|
||
```
|
||
|
||
### 6.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
|
||
```
|
||
|
||
## 7. 数据库设计强制要求
|
||
|
||
### 7.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 '详细地址',
|
||
`tenant_id` bigint NOT NULL DEFAULT '0' COMMENT '租户ID',
|
||
`creator` varchar(64) DEFAULT '' COMMENT '创建者',
|
||
`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
|
||
`updater` varchar(64) DEFAULT '' COMMENT '更新者',
|
||
`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
|
||
`deleted` bit(1) NOT NULL DEFAULT b'0' COMMENT '是否删除',
|
||
PRIMARY KEY (`id`),
|
||
UNIQUE KEY `uk_customer_code` (`customer_code`),
|
||
KEY `idx_tenant_customer_type` (`tenant_id`, `customer_type`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客户基本信息表';
|
||
```
|
||
|
||
## 8. 项目管理操作指令
|
||
|
||
### 8.1 任务管理指令
|
||
- **查看进度**：`检查 project_progress.md 获取当前项目状态`
|
||
- **查看任务**：`检查 task_checklist.md 获取待完成任务`
|
||
- **更新状态**：`编辑后必须更新进度文件中的完成度和质量评级`
|
||
|
||
### 8.2 质量检查指令
|
||
- **质量验证**：`对照 delivery_standards.md 检查文档质量`
|
||
- **代码验证**：`确保所有代码示例基于RuoYi-Vue-Pro框架`
|
||
- **图表验证**：`确保所有图表使用Mermaid语法且清晰易懂`
|
||
|
||
### 8.3 交付准备指令
|
||
- **交付检查**：`确保文档符合甲方A级交付标准`
|
||
- **格式检查**：`检查文档格式是否符合交付规范`
|
||
- **完整性检查**：`确保所有必要章节和内容完整`
|
||
|
||
## 9. 技术术语标准化
|
||
|
||
### 9.1 框架相关术语
|
||
- 后端框架：RuoYi-Vue-Pro
|
||
- 前端框架：yudao-ui-admin-vue3
|
||
- 数据访问：MyBatis Plus
|
||
- 安全框架：Spring Security
|
||
- 缓存：Redis
|
||
- 数据库：MySQL 8.0+
|
||
|
||
### 9.2 水务业务术语
|
||
- 抄表：meter reading
|
||
- 阶梯水价：tiered water pricing
|
||
- 远传水表：remote water meter
|
||
- 客户编号：customer code
|
||
- 水表编号：meter code
|
||
- 账务：accounting
|
||
- 收费：billing
|
||
- 营业网点：service outlet
|
||
|
||
## 10. 错误处理与修复
|
||
|
||
### 10.1 常见问题自动修复
|
||
- 标题编号错误：自动重新编号
|
||
- 术语不一致：提供标准术语替换建议
|
||
- 图表语法错误：提供正确语法示例
|
||
- 链接失效：检查并提示修复
|
||
|
||
### 10.2 质量问题警告
|
||
- 章节内容过少：警告并提供内容扩展建议
|
||
- 缺少图表：提醒添加必要的图表
|
||
- 代码示例不规范：提供规范的代码模板
|
||
|
||
## 11. 输出要求
|
||
|
||
### 11.1 始终使用中文
|
||
- 所有文档内容必须使用中文编写
|
||
- 技术术语可以保留英文，但需要中文解释
|
||
- 代码注释必须使用中文
|
||
|
||
### 11.2 保持专业性
|
||
- 使用专业的技术语言
|
||
- 确保内容的准确性和完整性
|
||
- 遵循软件工程文档编写最佳实践
|
||
|
||
### 11.3 注重实用性
|
||
- 提供可实施的技术方案
|
||
- 包含具体的配置示例
|
||
- 考虑实际开发中的技术约束
|
||
|
||
---
|
||
|
||
## 📋 重要提醒清单
|
||
|
||
### 🚨 每次操作前必须检查
|
||
- [ ] 查看 `project_progress.md` 中对应文档状态
|
||
- [ ] 查看 `task_checklist.md` 中相关任务
|
||
- [ ] 确认操作符合 `delivery_standards.md` 要求
|
||
|
||
### ✅ 每次操作中必须确保
|
||
- [ ] 内容符合甲方A级交付标准
|
||
- [ ] 包含RuoYi-Vue-Pro框架代码示例
|
||
- [ ] 包含必要的Mermaid图表
|
||
- [ ] 格式符合交付规范
|
||
|
||
### 📝 每次操作后必须更新
|
||
- [ ] 更新 `project_progress.md` 中的完成度
|
||
- [ ] 标记 `task_checklist.md` 中完成的任务
|
||
- [ ] 记录变更日志和质量评估
|
||
|
||
**记住：你的目标是创建符合甲方A级交付标准的高质量、专业、实用的系统概要设计文档，确保文档能够直接指导实际的系统开发工作。** |