cykj/hzdyjs
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

优化cursor使用形式，增加项目文档过程管理，方便cursor生成代码

Browse Source
This commit is contained in:
zlwu committed 2025-06-28 09:48:53 +08:00
1 parent 2f7e1a9c16
commit 65d2d71469
36 files changed
+8872 -1530
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/业务模块/业务模块开发模板.md
+575
View File
@@ -0,0 +1,575 @@
# 业务模块开发模板
> 🎯 **模板用途**：本模板用于创建新业务模块的文档结构，为 Cursor AI 提供标准的开发和文档生成参考
## 📋 模块基本信息
**模块名称**：[模块英文名称] / [模块中文名称]
**负责人**：[开发负责人]
**开发状态**：🟢 已完成 / 🟡 开发中 / ⭕ 待开始
**技术栈**：[具体技术栈]
**依赖模块**：[依赖的其他模块]
**开发周期**：[开始时间] - [结束时间]
## 🎯 模块概述
### 业务价值
[描述这个模块解决的业务问题和创造的价值]
### 核心功能
- **功能 1**：[功能描述]
- **功能 2**：[功能描述]
- **功能 3**：[功能描述]
- **功能 4**：[功能描述]
### 技术特点
- **特点 1**：[技术特色说明]
- **特点 2**：[性能特点说明]
- **特点 3**：[安全特点说明]
## 📁 文档结构
```
[模块名称]/
├── README.md # 本文件 - 模块总览
├── 需求分析/
│ ├── 业务需求说明.md # 详细业务需求
│ ├── 功能需求清单.md # 功能点清单
│ ├── 非功能需求.md # 性能、安全要求
│ └── 用户故事.md # 用户使用场景
├── 技术设计/
│ ├── 数据库设计.md # 表结构设计
│ ├── API接口设计.md # 接口定义
│ ├── 架构设计.md # 模块架构
│ └── 技术选型.md # 技术决策说明
├── 实现文档/
│ ├── 后端实现说明.md # 后端代码结构
│ ├── 前端实现说明.md # 前端代码结构
│ ├── 关键业务逻辑.md # 核心算法逻辑
│ └── 代码规范.md # 编码规范
├── 测试文档/
│ ├── 测试计划.md # 测试策略
│ ├── 测试用例.md # 具体测试用例
│ └── 测试报告.md # 测试结果
└── 运维文档/
├── 部署指南.md # 部署步骤
├── 监控配置.md # 监控指标
└── 故障处理.md # 常见问题
```
## 🏗️ 系统架构
### 模块架构图
```mermaid
graph TB
subgraph "前端层"
A1[页面组件<br/>[页面说明]]
A2[业务组件<br/>[组件说明]]
end
subgraph "接口层"
B1[Controller<br/>[接口说明]]
end
subgraph "业务层"
C1[Service<br/>[业务逻辑]]
C2[Manager<br/>[业务组装]]
end
subgraph "数据层"
D1[Mapper<br/>[数据访问]]
D2[Database<br/>[数据库表]]
end
A1 --> B1
A2 --> B1
B1 --> C1
C1 --> C2
C2 --> D1
D1 --> D2
```
### 数据流向
```mermaid
sequenceDiagram
participant U as 用户
participant F as 前端
participant C as Controller
participant S as Service
participant M as Mapper
participant D as Database
U->>F: 用户操作
F->>C: HTTP请求
C->>S: 业务调用
S->>M: 数据查询
M->>D: SQL执行
D-->>M: 返回结果
M-->>S: 返回数据
S-->>C: 返回结果
C-->>F: JSON响应
F-->>U: 界面更新
```
## 📊 核心功能模块
### 1. [功能模块 1]
#### 业务描述
[详细描述这个功能模块的业务逻辑]
#### 技术实现
- **前端实现**：[前端技术方案]
- **后端实现**：[后端技术方案]
- **数据存储**：[数据库设计]
#### 关键流程
1. [步骤 1]
2. [步骤 2]
3. [步骤 3]
### 2. [功能模块 2]
#### 业务描述
[详细描述这个功能模块的业务逻辑]
#### 技术实现
- **前端实现**：[前端技术方案]
- **后端实现**：[后端技术方案]
- **数据存储**：[数据库设计]
#### 关键流程
1. [步骤 1]
2. [步骤 2]
3. [步骤 3]
## 🔌 API 接口概览
### 接口分类
#### 基础 CRUD 接口
| 接口名称 | 请求方式 | 路径 | 功能描述 |
| -------------- | -------- | --------------------------- | ---------------------- |
| 创建[实体] | POST | /api/[module]/[entity] | 创建新的[实体] |
| 查询[实体]列表 | GET | /api/[module]/[entity]/list | 分页查询[实体]列表 |
| 查询[实体]详情 | GET | /api/[module]/[entity]/{id} | 根据 ID 查询[实体]详情 |
| 更新[实体] | PUT | /api/[module]/[entity]/{id} | 更新指定[实体] |
| 删除[实体] | DELETE | /api/[module]/[entity]/{id} | 删除指定[实体] |
#### 业务逻辑接口
| 接口名称 | 请求方式 | 路径 | 功能描述 |
| ------------ | -------- | ------ | ---------- |
| [业务接口 1] | [方式] | [路径] | [功能描述] |
| [业务接口 2] | [方式] | [路径] | [功能描述] |
| [业务接口 3] | [方式] | [路径] | [功能描述] |
### 接口规范
- **请求格式**：JSON
- **响应格式**：统一响应体结构
- **认证方式**：JWT Token
- **权限控制**：基于角色的权限验证
## 🗄️ 数据模型
### 核心实体
#### [实体 1]表 (table_name)
| 字段名 | 类型 | 长度 | 非空 | 默认值 | 说明 |
| ----------- | -------- | ------ | ----- | -------- | -------- |
| id | BIGINT | - | Y | - | 主键 ID |
| [字段 1] | [类型] | [长度] | [Y/N] | [默认值] | [说明] |
| [字段 2] | [类型] | [长度] | [Y/N] | [默认值] | [说明] |
| tenant_id | VARCHAR | 20 | Y | - | 租户 ID |
| create_by | BIGINT | - | Y | - | 创建人 |
| create_time | DATETIME | - | Y | - | 创建时间 |
| update_by | BIGINT | - | Y | - | 更新人 |
| update_time | DATETIME | - | Y | - | 更新时间 |
| deleted | TINYINT | - | Y | 0 | 删除标记 |
#### [实体 2]表 (table_name)
| 字段名 | 类型 | 长度 | 非空 | 默认值 | 说明 |
| ----------- | -------- | ------ | ----- | -------- | -------- |
| id | BIGINT | - | Y | - | 主键 ID |
| [字段 1] | [类型] | [长度] | [Y/N] | [默认值] | [说明] |
| [字段 2] | [类型] | [长度] | [Y/N] | [默认值] | [说明] |
| tenant_id | VARCHAR | 20 | Y | - | 租户 ID |
| create_by | BIGINT | - | Y | - | 创建人 |
| create_time | DATETIME | - | Y | - | 创建时间 |
| update_by | BIGINT | - | Y | - | 更新人 |
| update_time | DATETIME | - | Y | - | 更新时间 |
| deleted | TINYINT | - | Y | 0 | 删除标记 |
### 实体关系图
```mermaid
erDiagram
ENTITY1 ||--o{ ENTITY2 : "一对多关系"
ENTITY2 }o--|| ENTITY3 : "多对一关系"
ENTITY1 }o--o{ ENTITY3 : "多对多关系"
ENTITY1 {
bigint id PK
varchar name
datetime create_time
}
ENTITY2 {
bigint id PK
bigint entity1_id FK
varchar description
datetime create_time
}
ENTITY3 {
bigint id PK
varchar code
varchar name
datetime create_time
}
```
## 🔄 业务流程
### 主要业务流程
#### [流程 1 名称]
```mermaid
flowchart TD
A[开始] --> B{条件判断}
B -->|满足条件| C[执行操作1]
B -->|不满足条件| D[执行操作2]
C --> E[更新状态]
D --> F[记录日志]
E --> G[发送通知]
F --> G
G --> H[结束]
```
**流程说明**：
1. [步骤 1 说明]
2. [步骤 2 说明]
3. [步骤 3 说明]
#### [流程 2 名称]
```mermaid
flowchart TD
A[开始] --> B[数据验证]
B --> C{验证通过?}
C -->|是| D[业务处理]
C -->|否| E[返回错误]
D --> F[数据存储]
F --> G[返回结果]
E --> H[结束]
G --> H
```
**流程说明**：
1. [步骤 1 说明]
2. [步骤 2 说明]
3. [步骤 3 说明]
## 🎨 前端设计
### 页面结构
#### [页面 1 名称]
- **功能**：[页面功能说明]
- **组件**：[使用的组件列表]
- **交互**：[用户交互方式]
- **数据**：[页面数据来源]
#### [页面 2 名称]
- **功能**：[页面功能说明]
- **组件**：[使用的组件列表]
- **交互**：[用户交互方式]
- **数据**：[页面数据来源]
### 组件设计
#### [组件 1 名称]
```typescript
// 组件属性接口
interface [Component1]Props {
[prop1]: [type];
[prop2]: [type];
[prop3]: [type];
}
// 组件事件接口
interface [Component1]Emits {
[event1]: [params];
[event2]: [params];
}
```
#### [组件 2 名称]
```typescript
// 组件属性接口
interface [Component2]Props {
[prop1]: [type];
[prop2]: [type];
[prop3]: [type];
}
// 组件事件接口
interface [Component2]Emits {
[event1]: [params];
[event2]: [params];
}
```
## 📝 开发规范
### 代码结构
#### 后端代码结构
```
src/main/java/org/dromara/modules/[module]/
├── controller/ # 控制器层
│ ├── [Entity]Controller.java
│ └── [Module]Controller.java
├── domain/ # 领域对象层
│ ├── bo/ # 业务对象
│ │ ├── [Entity]Bo.java
│ │ └── [Entity]QueryBo.java
│ └── vo/ # 视图对象
│ ├── [Entity]Vo.java
│ └── [Entity]DetailVo.java
├── mapper/ # 数据访问层
│ ├── [Entity]Mapper.java
│ └── [Entity]Mapper.xml
├── service/ # 业务服务层
│ ├── I[Entity]Service.java
│ └── impl/
│ └── [Entity]ServiceImpl.java
└── utils/ # 工具类
└── [Module]Utils.java
```
#### 前端代码结构
```
src/views/[module]/
├── index.vue # 主页面
├── components/ # 页面组件
│ ├── [Component1].vue
│ └── [Component2].vue
├── types/ # 类型定义
│ └── index.ts
└── api/ # API接口
└── index.ts
```
### 命名规范
#### 后端命名规范
- **类名**：PascalCase (如: UserController, UserService)
- **方法名**：camelCase (如: getUserList, createUser)
- **常量**：UPPER_SNAKE_CASE (如: MAX_RETRY_COUNT)
- **包名**：全小写 (如: com.example.module)
#### 前端命名规范
- **组件名**：PascalCase (如: UserList, UserForm)
- **方法名**：camelCase (如: handleSubmit, getUserInfo)
- **变量名**：camelCase (如: userList, isLoading)
- **常量**：UPPER_SNAKE_CASE (如: API_BASE_URL)
#### 数据库命名规范
- **表名**：下划线命名 (如: sys_user, sys_role)
- **字段名**：下划线命名 (如: user_name, create_time)
- **索引名**：idx*表名*字段名 (如: idx_user_username)
## 🧪 测试策略
### 测试分类
#### 单元测试
- **覆盖范围**：Service 层业务逻辑
- **测试框架**：JUnit 5 + Mockito
- **覆盖率要求**：> 80%
#### 集成测试
- **覆盖范围**：Controller 层 API 接口
- **测试框架**：Spring Boot Test
- **测试数据**：测试数据库
#### 前端测试
- **覆盖范围**：组件功能测试
- **测试框架**：Vue Test Utils + Jest
- **测试类型**：组件渲染、用户交互、数据绑定
### 测试用例设计
#### 功能测试用例
- **正常流程测试**：验证正常业务流程
- **边界值测试**：验证边界条件处理
- **异常流程测试**：验证错误处理逻辑
#### 性能测试用例
- **响应时间测试**：验证接口响应时间
- **并发测试**：验证并发处理能力
- **压力测试**：验证系统承载能力
## 🚀 部署运维
### 部署环境
#### 开发环境
- **部署方式**：本地 Docker 容器
- **数据库**：MySQL 8.0
- **缓存**：Redis 7.0
- **配置**：application-dev.yml
#### 测试环境
- **部署方式**：Docker Compose
- **数据库**：MySQL 8.0（测试库）
- **缓存**：Redis 7.0
- **配置**：application-test.yml
#### 生产环境
- **部署方式**：Kubernetes
- **数据库**：MySQL 8.0（集群）
- **缓存**：Redis 7.0（集群）
- **配置**：application-prod.yml
### 监控指标
#### 业务指标
- **功能使用率**：各功能模块的使用频率
- **用户活跃度**：日活、月活用户数
- **业务成功率**：业务操作成功率
#### 技术指标
- **接口响应时间**：平均响应时间 < 200ms
- **系统可用性**：99.9%可用性
- **错误率**：错误率 < 0.1%
## 📅 开发计划
### 开发阶段
#### 第一阶段：基础框架（[时间范围]）
- [ ] 数据库表结构设计
- [ ] 基础 CRUD 接口开发
- [ ] 基础页面和组件开发
- [ ] 单元测试编写
#### 第二阶段：核心功能（[时间范围]）
- [ ] [核心功能 1]开发
- [ ] [核心功能 2]开发
- [ ] [核心功能 3]开发
- [ ] 集成测试
#### 第三阶段：完善优化（[时间范围]）
- [ ] 功能完善和优化
- [ ] 性能测试和优化
- [ ] 用户体验优化
- [ ] 文档完善
### 里程碑
- **里程碑 1**：基础框架完成 ([日期])
- **里程碑 2**：核心功能完成 ([日期])
- **里程碑 3**：测试完成，准备发布 ([日期])
- **里程碑 4**：正式发布上线 ([日期])
## 🔧 开发工具
### 后端开发工具
- **IDE**：IntelliJ IDEA
- **构建工具**：Maven
- **代码质量**：SonarQube
- **API 测试**：Postman
### 前端开发工具
- **IDE**：VSCode
- **构建工具**：Vite
- **代码规范**：ESLint + Prettier
- **组件预览**：Storybook
### 数据库工具
- **管理工具**：Navicat Premium
- **版本控制**：Flyway
- **性能监控**：MySQL Performance Schema
## 📖 相关文档
- **项目总览**：[项目总览](../项目总览/README.md)
- **开发规范**：[开发文档](../开发文档/README.md)
- **API 接口**：[开发文档/API.md](../开发文档/API.md)
- **数据库设计**：[设计文档/database](../设计文档/database/)
- **变更记录**：[变更管理](../变更管理/README.md)
---
## 📝 模板使用说明
### 适用场景
- 新业务模块开发启动时
- 现有模块重构时
- 为 AI 辅助开发提供上下文
### 填写指南
1. **基本信息**：确保模块基本信息准确完整
2. **架构设计**：使用 Mermaid 图表清晰展示架构
3. **API 设计**：提供完整的接口定义和示例
4. **数据模型**：详细设计数据库表结构
5. **业务流程**：用流程图展示关键业务逻辑
### 文档维护
- **实时更新**：代码变更时同步更新文档
- **版本控制**：重要变更记录版本历史
- **质量检查**：定期检查文档完整性和准确性
### AI 辅助开发
- **上下文提供**：为 Cursor AI 提供完整的业务和技术上下文
- **代码生成**：基于文档规范生成标准化代码
- **文档生成**：自动生成和更新相关文档