# 区域侦查任务前端集成文档

## 📋 概述

本文档详细说明前端如何集成区域侦查任务API，包括接口调用、数据格式、错误处理等完整的前端集成方案。

## 🚀 快速开始

### 基础配置

```javascript
// API基础配置
const API_BASE_URL = 'http://localhost:8080/api/v1/region-reconnaissance';

// 动态获取鉴权头（如有需要）
function getAuthHeaders() {
  const token = window.localStorage.getItem('token');
  return token ? { Authorization: `Bearer ${token}` } : {};
}

// 统一请求方法（基于 fetch）
async function request(path, options = {}) {
  const url = path.startsWith('http') ? path : `${API_BASE_URL}${path}`;
  const headers = {
    'Content-Type': 'application/json',
    ...getAuthHeaders(),
    ...(options.headers || {})
  };

  const response = await fetch(url, { ...options, headers });

  // 尝试解析响应体（可能为 204 无内容）
  let payload = null;
  if (response.status !== 204) {
    try {
      payload = await response.json();
    } catch {
      // 非 JSON 响应体容忍
    }
  }

  if (!response.ok) {
    const message = payload?.message || `HTTP ${response.status}`;
    throw new Error(message);
  }

  // 兼容 204 的删除等请求
  return payload ?? { code: 200, message: 'OK', data: null };
}
```

## 📡 API接口集成

### 1. 创建区域侦查任务

#### 接口信息
- **URL**: `POST /api/v1/region-reconnaissance/tasks`
- **功能**: 创建新的区域侦查任务
- **返回**: 任务ID和创建结果

#### 前端实现

```javascript
/**
 * 创建区域侦查任务
 * @param {Object} taskData - 任务数据
 * @returns {Promise<Object>} 创建结果
 */
async function createRegionReconnaissanceTask(taskData) {
  try {
    const result = await request('/tasks', {
      method: 'POST',
      body: JSON.stringify(taskData)
    });
    console.log('任务创建成功:', result);
    return result;
  } catch (error) {
    console.error('创建任务失败:', error);
    throw error;
  }
}
```

#### 请求数据格式

```javascript
// 完整的任务创建数据示例（区域闭合由后端自动处理，前端无需首尾重复）
const taskData = {
  taskName: "测试区域侦查任务",
  taskType: 1, // 1-区域侦查, 2-航线侦查
  regionZone: {
    pointList: [
      { latitude: 39.9042, longitude: 116.4074, altitude: 100.0 },
      { latitude: 39.9142, longitude: 116.4174, altitude: 100.0 },
      { latitude: 39.9242, longitude: 116.4274, altitude: 100.0 }
    ]
  },
  description: "这是一个测试任务",
  executeTime: "2025-01-27T10:00:00Z" // 使用 ISO 8601（UTC）
};
```

> 说明
> - 区域闭合规则：后端会基于点列表自动闭合多边形，前端不需要重复首尾点。
> - 时间与时区：所有时间字段使用 ISO 8601 UTC（例如 `2025-01-27T10:00:00Z`）。服务端按 UTC 存储与计算，前端展示时可按本地时区格式化。

### 2. 获取任务列表

#### 接口信息
- **URL**: `GET /api/v1/region-reconnaissance/tasks`
- **功能**: 获取区域侦查任务列表
- **支持分页**: 是

#### 前端实现

```javascript
/**
 * 获取任务列表
 * @param {Object} params - 查询参数
 * @returns {Promise<Object>} 任务列表
 */
async function getRegionReconnaissanceTasks(params = {}) {
  try {
    const qp = Object.fromEntries(
      Object.entries({ page: params.page ?? 1, size: params.size ?? 10, ...params })
        .filter(([, v]) => v !== undefined && v !== null && v !== '')
    );
    const queryParams = new URLSearchParams(qp).toString();
    const result = await request(`/tasks?${queryParams}`, { method: 'GET' });
    return result;
  } catch (error) {
    console.error('获取任务列表失败:', error);
    throw error;
  }
}
```

### 3. 获取任务详情

#### 接口信息
- **URL**: `GET /api/v1/region-reconnaissance/tasks/{taskId}`
- **功能**: 获取指定任务的详细信息

#### 前端实现

```javascript
/**
 * 获取任务详情
 * @param {string} taskId - 任务ID
 * @returns {Promise<Object>} 任务详情
 */
async function getRegionReconnaissanceTaskDetail(taskId) {
  try {
    const result = await request(`/tasks/${taskId}`, { method: 'GET' });
    return result;
  } catch (error) {
    console.error('获取任务详情失败:', error);
    throw error;
  }
}
```

### 4. 更新任务状态

#### 接口信息
- **URL**: `PUT /api/v1/region-reconnaissance/tasks/{taskId}/status`
- **功能**: 更新任务状态

#### 前端实现

```javascript
/**
 * 更新任务状态
 * @param {string} taskId - 任务ID
 * @param {number} status - 新状态
 * @returns {Promise<Object>} 更新结果
 */
async function updateTaskStatus(taskId, status) {
  try {
    const result = await request(`/tasks/${taskId}/status`, {
      method: 'PUT',
      body: JSON.stringify({ status })
    });
    return result;
  } catch (error) {
    console.error('更新任务状态失败:', error);
    throw error;
  }
}
```

### 5. 删除任务

#### 接口信息
- **URL**: `DELETE /api/v1/region-reconnaissance/tasks/{taskId}`
- **功能**: 删除指定任务

#### 前端实现

```javascript
/**
 * 删除任务
 * @param {string} taskId - 任务ID
 * @returns {Promise<Object>} 删除结果
 */
async function deleteRegionReconnaissanceTask(taskId) {
  try {
    const result = await request(`/tasks/${taskId}`, { method: 'DELETE' });
    return result; // 兼容 204，无内容时返回 { code: 200, message: 'OK', data: null }
  } catch (error) {
    console.error('删除任务失败:', error);
    throw error;
  }
}
```

## 🎨 前端组件示例

### React组件示例

```jsx
import React, { useState, useEffect } from 'react';

const RegionReconnaissanceTaskManager = () => {
  const [tasks, setTasks] = useState([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  // 获取任务列表
  const fetchTasks = async () => {
    setLoading(true);
    try {
      const result = await getRegionReconnaissanceTasks();
      setTasks(result.data?.records ?? []);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };

  // 创建任务
  const handleCreateTask = async (taskData) => {
    try {
      await createRegionReconnaissanceTask(taskData);
      await fetchTasks(); // 刷新列表
      alert('任务创建成功！');
    } catch (err) {
      alert(`创建失败: ${err.message}`);
    }
  };

  // 删除任务
  const handleDeleteTask = async (taskId) => {
    if (window.confirm('确定要删除这个任务吗？')) {
      try {
        await deleteRegionReconnaissanceTask(taskId);
        await fetchTasks(); // 刷新列表
        alert('任务删除成功！');
      } catch (err) {
        alert(`删除失败: ${err.message}`);
      }
    }
  };

  useEffect(() => {
    fetchTasks();
  }, []);

  return (
    <div className="task-manager">
      <h2>区域侦查任务管理</h2>
      
      {loading && <div>加载中...</div>}
      {error && <div className="error">错误: {error}</div>}
      
      <div className="task-list">
        {tasks.map(task => (
          <div key={task.taskId} className="task-item">
            <h3>{task.taskName}</h3>
            <p>类型: {task.taskType === 1 ? '区域侦查' : '航线侦查'}</p>
            <p>状态: {getStatusText(task.status)}</p>
            <p>创建时间: {new Date(task.createTime).toLocaleString()}</p>
            <button onClick={() => handleDeleteTask(task.taskId)}>
              删除
            </button>
          </div>
        ))}
      </div>
    </div>
  );
};

// 状态文本转换
const getStatusText = (status) => {
  const statusMap = {
    0: '待执行',
    1: '执行中',
    2: '已完成',
    3: '已取消',
    4: '执行失败'
  };
  return statusMap[status] || '未知状态';
};

export default RegionReconnaissanceTaskManager;
```

### Vue组件示例

```vue
<template>
  <div class="task-manager">
    <h2>区域侦查任务管理</h2>
    
    <div v-if="loading" class="loading">加载中...</div>
    <div v-if="error" class="error">错误: {{ error }}</div>
    
    <div class="task-list">
      <div 
        v-for="task in tasks" 
        :key="task.taskId" 
        class="task-item"
      >
        <h3>{{ task.taskName }}</h3>
        <p>类型: {{ task.taskType === 1 ? '区域侦查' : '航线侦查' }}</p>
        <p>状态: {{ getStatusText(task.status) }}</p>
        <p>创建时间: {{ formatDate(task.createTime) }}</p>
        <button @click="handleDeleteTask(task.taskId)">
          删除
        </button>
      </div>
    </div>
  </div>
</template>

<script>
export default {
  name: 'RegionReconnaissanceTaskManager',
  data() {
    return {
      tasks: [],
      loading: false,
      error: null
    };
  },
  async mounted() {
    await this.fetchTasks();
  },
  methods: {
    async fetchTasks() {
      this.loading = true;
      try {
        const result = await getRegionReconnaissanceTasks();
        this.tasks = result.data?.records ?? [];
      } catch (err) {
        this.error = err.message;
      } finally {
        this.loading = false;
      }
    },
    
    async handleCreateTask(taskData) {
      try {
        await createRegionReconnaissanceTask(taskData);
        await this.fetchTasks();
        alert('任务创建成功！');
      } catch (err) {
        alert(`创建失败: ${err.message}`);
      }
    },
    
    async handleDeleteTask(taskId) {
      if (confirm('确定要删除这个任务吗？')) {
        try {
          await deleteRegionReconnaissanceTask(taskId);
          await this.fetchTasks();
          alert('任务删除成功！');
        } catch (err) {
          alert(`删除失败: ${err.message}`);
        }
      }
    },
    
    getStatusText(status) {
      const statusMap = {
        0: '待执行',
        1: '执行中',
        2: '已完成',
        3: '已取消',
        4: '执行失败'
      };
      return statusMap[status] || '未知状态';
    },
    
    formatDate(dateString) {
      return new Date(dateString).toLocaleString();
    }
  }
};
</script>
```

## 📊 数据格式说明

### 任务对象结构

```typescript
interface RegionReconnaissanceTask {
  taskId: string;           // 任务ID
  taskName: string;         // 任务名称
  taskType: number;         // 任务类型 (1-区域侦查, 2-航线侦查)
  status: number;           // 任务状态 (0-待执行, 1-执行中, 2-已完成, 3-已取消, 4-执行失败)
  regionZone: RegionZone;   // 区域信息
  description?: string;     // 任务描述
  executeTime?: string;     // 执行时间
  createTime: string;       // 创建时间
  updateTime: string;       // 更新时间
  createUserId: string;     // 创建用户ID
  mqttSendStatus: number;   // MQTT发送状态
}

interface RegionZone {
  pointList: Point[];       // 区域点列表
}

interface Point {
  latitude: number;         // 纬度
  longitude: number;        // 经度
  altitude: number;         // 高度
}
```

### 响应数据格式

```typescript
// 成功响应
interface ApiResponse<T> {
  code: number;             // 响应码 (200-成功)
  message: string;          // 响应消息
  data: T;                  // 响应数据
  timestamp: string;        // 时间戳
}

// 分页响应
interface PageResponse<T> {
  code: number;
  message: string;
  data: {
    records: T[];           // 数据列表
    total: number;          // 总记录数
    size: number;           // 每页大小
    current: number;        // 当前页码
    pages: number;          // 总页数
  };
  timestamp: string;
}
```

## ⚠️ 错误处理

### 常见错误码

```javascript
const ERROR_CODES = {
  400: '请求参数错误',
  401: '未授权访问',
  403: '禁止访问',
  404: '资源不存在',
  500: '服务器内部错误',
  1001: '任务名称不能为空',
  1002: '区域点列表不能为空',
  1003: '任务不存在',
  1004: '任务状态不允许此操作'
};
```

### 错误处理示例

```javascript
/**
 * 统一错误处理（配合 fetch 请求助手）
 * @param {Error} error - 错误对象
 * @returns {string} 用户友好的错误信息
 */
function handleApiError(error) {
  // request() 已将后端 message 或 HTTP 状态转为 Error(message)
  return error?.message || '请求失败';
}
```

## 🔧 工具函数

### 数据验证

```javascript
/**
 * 验证任务数据
 * @param {Object} taskData - 任务数据
 * @returns {Object} 验证结果
 */
function validateTaskData(taskData) {
  const errors = [];
  
  if (!taskData.taskName || taskData.taskName.trim() === '') {
    errors.push('任务名称不能为空');
  }
  
  if (![1, 2].includes(taskData.taskType)) {
    errors.push('任务类型必须是1(区域侦查)或2(航线侦查)');
  }
  
  if (!taskData.regionZone || !Array.isArray(taskData.regionZone.pointList)) {
    errors.push('区域信息不能为空');
  } else if (taskData.regionZone.pointList.length < 3) {
    errors.push('区域至少需要3个点');
  }
  
  return {
    isValid: errors.length === 0,
    errors
  };
}
```

### 数据转换

```javascript
/**
 * 转换区域数据为API格式
 * @param {Array} points - 前端点数据
 * @returns {Object} API格式的区域数据
 */
function convertRegionData(points) {
  return {
    pointList: points.map(point => ({
      latitude: parseFloat(point.latitude),
      longitude: parseFloat(point.longitude),
      altitude: parseFloat(point.altitude) || 0
    }))
  };
}
```

## 📱 移动端适配

### 响应式设计

```css
/* 移动端适配 */
@media (max-width: 768px) {
  .task-manager {
    padding: 10px;
  }
  
  .task-item {
    margin-bottom: 15px;
    padding: 10px;
    border: 1px solid #ddd;
    border-radius: 5px;
  }
  
  .task-item h3 {
    font-size: 16px;
    margin-bottom: 8px;
  }
  
  .task-item p {
    font-size: 14px;
    margin: 4px 0;
  }
  
  .task-item button {
    width: 100%;
    padding: 8px;
    margin-top: 10px;
  }
}
```

## 🧪 测试示例

### 单元测试

```javascript
// Jest测试示例
describe('RegionReconnaissanceTask API', () => {
  test('创建任务', async () => {
    const taskData = {
      taskName: '测试任务',
      taskType: 1,
      regionZone: {
        pointList: [
          { latitude: 39.9042, longitude: 116.4074, altitude: 100 },
          { latitude: 39.9142, longitude: 116.4174, altitude: 100 },
          { latitude: 39.9242, longitude: 116.4274, altitude: 100 }
        ]
      }
    };
    
    const result = await createRegionReconnaissanceTask(taskData);
    expect(result.code).toBe(200);
    expect(result.data.taskId).toBeDefined();
  });
  
  test('获取任务列表', async () => {
    const result = await getRegionReconnaissanceTasks();
    expect(result.code).toBe(200);
    expect(Array.isArray(result.data.records)).toBe(true);
  });
});
```

## 📚 最佳实践

### 1. 错误处理
- 始终使用try-catch包装API调用
- 提供用户友好的错误信息
- 记录详细的错误日志用于调试

### 2. 数据验证
- 在发送请求前验证数据格式
- 使用TypeScript或PropTypes进行类型检查
- 提供实时验证反馈

### 3. 用户体验
- 显示加载状态
- 提供操作确认
- 使用乐观更新提升响应速度

### 4. 性能优化
- 实现数据缓存
- 使用分页加载大量数据
- 防抖处理用户输入

## 🔗 相关资源

- [后端API接口说明](./后端API接口说明.md)
- [前端对接指南](./前端对接指南.md)
- [前端集成说明](./前端集成说明.md)

## 📞 技术支持

如有问题，请联系开发团队或查看项目文档。

---

*最后更新: 2025-01-27*