# 业务模块开发模板

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