15 KiB
15 KiB
业务模块开发模板
🎯 模板用途：本模板用于创建新业务模块的文档结构，为 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 # 常见问题
🏗️ 系统架构
模块架构图
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
数据流向
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]
- [步骤 2]
- [步骤 3]
2. [功能模块 2]
业务描述
[详细描述这个功能模块的业务逻辑]
技术实现
- 前端实现：[前端技术方案]
- 后端实现：[后端技术方案]
- 数据存储：[数据库设计]
关键流程
- [步骤 1]
- [步骤 2]
- [步骤 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 | 删除标记 |
实体关系图
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 名称]
flowchart TD
A[开始] --> B{条件判断}
B -->|满足条件| C[执行操作1]
B -->|不满足条件| D[执行操作2]
C --> E[更新状态]
D --> F[记录日志]
E --> G[发送通知]
F --> G
G --> H[结束]
流程说明：
- [步骤 1 说明]
- [步骤 2 说明]
- [步骤 3 说明]
[流程 2 名称]
flowchart TD
A[开始] --> B[数据验证]
B --> C{验证通过?}
C -->|是| D[业务处理]
C -->|否| E[返回错误]
D --> F[数据存储]
F --> G[返回结果]
E --> H[结束]
G --> H
流程说明：
- [步骤 1 说明]
- [步骤 2 说明]
- [步骤 3 说明]
🎨 前端设计
页面结构
[页面 1 名称]
- 功能：[页面功能说明]
- 组件：[使用的组件列表]
- 交互：[用户交互方式]
- 数据：[页面数据来源]
[页面 2 名称]
- 功能：[页面功能说明]
- 组件：[使用的组件列表]
- 交互：[用户交互方式]
- 数据：[页面数据来源]
组件设计
[组件 1 名称]
// 组件属性接口
interface [Component1]Props {
[prop1]: [type];
[prop2]: [type];
[prop3]: [type];
}
// 组件事件接口
interface [Component1]Emits {
[event1]: [params];
[event2]: [params];
}
[组件 2 名称]
// 组件属性接口
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
📖 相关文档
- 项目总览：项目总览
- 开发规范：开发文档
- API 接口：开发文档/API.md
- 数据库设计：设计文档/database
- 变更记录：变更管理
📝 模板使用说明
适用场景
- 新业务模块开发启动时
- 现有模块重构时
- 为 AI 辅助开发提供上下文
填写指南
- 基本信息：确保模块基本信息准确完整
- 架构设计：使用 Mermaid 图表清晰展示架构
- API 设计：提供完整的接口定义和示例
- 数据模型：详细设计数据库表结构
- 业务流程：用流程图展示关键业务逻辑
文档维护
- 实时更新：代码变更时同步更新文档
- 版本控制：重要变更记录版本历史
- 质量检查：定期检查文档完整性和准确性
AI 辅助开发
- 上下文提供：为 Cursor AI 提供完整的业务和技术上下文
- 代码生成：基于文档规范生成标准化代码
- 文档生成：自动生成和更新相关文档