# 使用 MCP API 文档进行二次开发详细指南

## 一、什么是 MCP API 文档

MCP (Model Context Protocol) 是一种协议，允许 AI 助手访问外部 API 文档资源。在您的项目中，已经配置了 Apifox 文档站点的 MCP 服务器，可以读取 OpenAPI 规范文档。

## 二、MCP 工具说明

您的项目中可用的 MCP 工具：

1. **`mcp_apifox-doc-site-5448103_read_project_oas_7vtrve`** - 读取 OpenAPI Spec 文件内容
2. **`mcp_apifox-doc-site-5448103_refresh_project_oas_7vtrve`** - 从服务器重新下载最新的 OpenAPI Spec 文件内容

## 三、详细开发步骤

### 步骤 1: 读取 API 文档

当您需要实现某个功能时，首先让我读取 API 文档：

**示例对话：**
```
您：根据API文档，实现组织管理下的告警信息接口
我：我会先读取API文档，然后根据文档生成代码
```

我会自动调用 MCP 工具读取最新的 API 文档。

### 步骤 2: 分析 API 文档结构

读取文档后，我会分析：
- **接口路径**：如 `/openapi/v0.9/manage/api/v1/organizations/{org_uuid}/manage-devices/hms`
- **HTTP 方法**：GET、POST、PUT、DELETE
- **请求参数**：路径参数、查询参数、请求体
- **响应结构**：响应数据格式、分页信息等

### 步骤 3: 创建实体类（Entity/DTO）

根据 API 文档中的 Schema 定义，创建对应的 Java 实体类：

**示例：HMS 告警信息实体**
```java
@Data
public class DjiHmsEvent {
    private String id;
    private String device_sn;
    private String device_name;
    private Integer event_type;
    private String event_type_name;
    // ... 其他字段
}
```

**位置：** `ilot-business/src/main/java/com/codeman/business/dji/domain/`

### 步骤 4: 创建请求 DTO

对于需要请求体的接口，创建对应的请求 DTO：

**示例：更新 HMS 已读时间请求**
```java
@Data
public class HmsReadTimeUpdateRequest {
    private Long read_time;
}
```

**位置：** `ilot-business/src/main/java/com/codeman/business/dji/domain/dto/`

### 步骤 5: 在 Service 接口中定义方法

在对应的 Service 接口中添加方法定义：

**文件：** `IDjiOrganizationService.java`
```java
/**
 * 获取组织设备HMS事件列表（告警信息）
 */
ResponseData<DjiHmsEvent> getHmsEvents(String orgUuid, Map<String, Object> params);

/**
 * 更新组织设备HMS已读时间
 */
ResponseData<?> updateHmsReadTime(String orgUuid, HmsReadTimeUpdateRequest request);
```

### 步骤 6: 实现 Service 方法

在 Service 实现类中调用 `IDjiApiService` 进行 API 调用：

**文件：** `DjiOrganizationServiceImpl.java`
```java
@Override
public ResponseData<DjiHmsEvent> getHmsEvents(String orgUuid, Map<String, Object> params) {
    String apiPath = MessageFormat.format("manage/api/v1/organizations/{0}/manage-devices/hms", orgUuid);
    String resultStr = djiApiService.get(apiPath, params);
    return JSONUtil.toBean(resultStr, new TypeReference<ResponseData<DjiHmsEvent>>() {}, false);
}
```

**关键点：**
- 使用 `MessageFormat.format()` 处理路径参数
- 使用 `djiApiService.get/post/put/delete()` 调用 API
- 使用 `JSONUtil.toBean()` 将响应转换为实体类

### 步骤 7: 在 Controller 中添加接口

在对应的 Controller 中暴露 RESTful 接口：

**文件：** `DjiOrganizationController.java`
```java
@ApiOperation("获取组织设备HMS事件列表（告警信息）")
@GetMapping("/manage-devices/hms")
public TableDataInfo getHmsEvents(@RequestParam(required = false) Map<String, Object> params) {
    // 实现逻辑
}
```

**关键点：**
- 继承 `DjiBaseController` 获取公共配置（`djiOrgUuid`, `djiProjectUuid` 等）
- 使用 `startDjiPage()` 处理分页参数
- 使用 `getDataTable()` 返回分页数据
- 使用 `AjaxResult` 返回操作结果

### 步骤 8: 处理不同的响应结构

根据 API 返回的数据结构，选择合适的方式处理：

**列表接口（带分页）：**
```java
ResponseData<DjiHmsEvent> responseData = service.getHmsEvents(orgUuid, params);
if (responseData.getCode() == 0 && responseData.getData() != null) {
    List<DjiHmsEvent> list = responseData.getData().getList();
    return getDataTable(list);
}
```

**详情接口（直接对象）：**
```java
ResponseData<Organization> responseData = service.getOrganizationDetail(orgUuid);
if (responseData.getCode() == 0) {
    Organization org = responseData.getDataObject(); // 使用 dataObject
    return AjaxResult.success(org);
}
```

## 四、开发模式总结

### 模式 A：列表查询接口

```
1. 创建实体类 Entity
2. Service 返回 ResponseData<Entity>
3. Controller 使用 TableDataInfo 返回分页数据
```

### 模式 B：详情查询接口

```
1. 创建实体类 Entity
2. Service 返回 ResponseData<Entity>，数据在 dataObject 字段
3. Controller 使用 AjaxResult 返回单个对象
```

### 模式 C：创建/更新接口

```
1. 创建请求 DTO
2. Service 返回 ResponseData<?>
3. Controller 使用 AjaxResult 返回操作结果
```

## 五、最佳实践

### 1. 统一使用实体类
- ✅ 使用强类型实体类，不要使用 `Map<String, Object>`
- ✅ 提高代码可维护性和类型安全

### 2. 统一错误处理
```java
try {
    // API 调用
} catch (Exception ex) {
    logger.error("操作失败", ex);
    return AjaxResult.error("操作失败：" + ex.getMessage());
}
```

### 3. 统一使用配置
- 从 `DjiBaseController` 继承获取 `djiOrgUuid`、`djiProjectUuid`
- 外部调用不需要传递这些参数

### 4. 统一分页处理
```java
if (params == null) {
    params = new HashMap<>();
}
startDjiPage(params); // 自动处理 page 和 page_size
```

## 六、常见问题

### Q1: 如何知道 API 文档中有哪些接口？
**A:** 直接告诉我您要实现的功能，我会读取 API 文档并找到相关接口。

### Q2: 如何刷新 API 文档？
**A:** 我可以调用 `refresh_project_oas` 工具从服务器重新下载最新文档。

### Q3: 响应数据结构不确定怎么办？
**A:** 可以先查看 API 文档的 Schema 定义，或者提供实际的 JSON 响应示例，我会根据示例创建实体类。

### Q4: 如何处理嵌套对象？
**A:** 创建嵌套的实体类，如 `DjiDevice` 中包含 `DjiDeviceModel`。

## 七、开发流程示例

**完整示例：实现 HMS 告警信息接口**

1. **您提出需求：** "根据API文档，实现组织管理下的告警信息接口"

2. **我读取文档：** 自动调用 MCP 工具读取 API 文档

3. **我分析文档：** 找到相关接口：
   - GET `/manage/api/v1/organizations/{org_uuid}/manage-devices/hms`
   - PUT `/manage/api/v1/organizations/{org_uuid}/manage-devices/hms`

4. **我创建实体：**
   - `DjiHmsEvent.java` - HMS 事件实体
   - `HmsReadTimeUpdateRequest.java` - 更新请求 DTO

5. **我实现 Service：**
   - `IDjiOrganizationService` 添加方法
   - `DjiOrganizationServiceImpl` 实现方法

6. **我实现 Controller：**
   - `DjiOrganizationController` 添加 RESTful 接口

7. **我检查代码：** 运行 linter 检查，确保没有错误

8. **完成：** 所有代码已生成并集成到项目中

## 八、快速开始

**现在就可以开始：**

1. 告诉我您要实现的功能，例如：
   - "根据API文档，实现XXX功能"
   - "实现XXX模块下的所有接口"
   - "根据API文档，生成XXX的实体类和接口"

2. 我会自动：
   - 读取 API 文档
   - 分析接口结构
   - 生成实体类和代码
   - 实现 Service 和 Controller

3. 您只需要：
   - 检查生成的代码
   - 测试接口功能
   - 根据实际响应调整实体类（如有需要）

---

**提示：** 如果您有实际的 JSON 响应示例，直接提供给我，我会根据示例创建更准确的实体类。