576 lines
15 KiB
Markdown
576 lines
15 KiB
Markdown
# 业务模块开发模板
|
||
|
||
> 🎯 **模板用途**：本模板用于创建新业务模块的文档结构，为 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 提供完整的业务和技术上下文
|
||
- **代码生成**：基于文档规范生成标准化代码
|
||
- **文档生成**：自动生成和更新相关文档
|