# 按狀態批量刪除鏈接接口說明

## 功能概述
新增了一個按鏈接狀態批量刪除鏈接的接口，允許用戶根據指定的狀態列表批量刪除自己的鏈接。

## 接口詳情

### 請求路徑
`POST /api/link/batch-delete-by-status`

### 請求參數
```json
{
  "statusList": ["EXPIRED", "REFUNDED"],
  "confirmDelete": true
}
```

#### 參數說明
- `statusList`: 要刪除的鏈接狀態列表，支持的狀態值：
  - `NEW`: 新建
  - `USING`: 使用中  
  - `LOGGED_IN`: 已登錄
  - `COMPLETED`: 已完成
  - `REFUNDED`: 已退款
  - `EXPIRED`: 已過期
- `confirmDelete`: 是否確認刪除操作，必須設置為 `true` 才能執行刪除

#### 驗證規則
- 狀態列表不能為空
- 單次最多指定10個狀態
- 必須確認刪除操作（`confirmDelete = true`）
- 只能刪除用戶自己創建的鏈接

### 響應格式
```json
{
  "successCount": 15,
  "failedCount": 0,
  "totalCount": 15,
  "successCodeNos": ["ABC123", "DEF456", "..."],
  "failedCodeNos": [],
  "failedReasons": [],
  "allSuccess": true
}
```

#### 響應字段說明
- `successCount`: 成功刪除的數量
- `failedCount`: 刪除失敗的數量
- `totalCount`: 總數量
- `successCodeNos`: 成功刪除的鏈接編號列表
- `failedCodeNos`: 刪除失敗的鏈接編號列表
- `failedReasons`: 刪除失敗的原因列表
- `allSuccess`: 是否全部成功

## 實現細節

### 新增文件
1. `BatchDeleteByStatusRequest.java` - 請求DTO
2. `test_batch_delete_by_status.http` - 接口測試文件
3. `docs/按狀態批量刪除鏈接接口說明.md` - 接口說明文檔

### 修改文件
1. `LinkTaskMapper.java` - 添加數據庫查詢方法
2. `LinkTaskMapper.xml` - 添加SQL映射
3. `LinkStatusService.java` - 添加業務邏輯方法
4. `LinkController.java` - 添加控制器接口

### 數據庫操作
- `findByStatusListAndAgentId`: 查詢指定狀態和用戶的鏈接列表
- `countByStatusListAndAgentId`: 統計指定狀態和用戶的鏈接數量
- `batchDeleteByStatusListAndAgentId`: 批量刪除指定狀態和用戶的鏈接

## 安全考慮

### 權限控制
- 用戶只能刪除自己創建的鏈接
- 通過JWT token進行用戶身份驗證
- 通過 `agentId` 過濾確保數據隔離

### 操作確認
- 必須設置 `confirmDelete = true` 才能執行刪除操作
- 避免誤操作導致的數據丟失

### 參數驗證
- 驗證狀態值的有效性
- 限制單次操作的狀態數量（最多10個）
- 參數非空驗證

## 使用示例

### 1. 刪除過期鏈接
```http
POST /api/link/batch-delete-by-status
Authorization: Bearer {token}
Content-Type: application/json

{
  "statusList": ["EXPIRED"],
  "confirmDelete": true
}
```

### 2. 清理已退款和已過期的鏈接
```http
POST /api/link/batch-delete-by-status
Authorization: Bearer {token}
Content-Type: application/json

{
  "statusList": ["EXPIRED", "REFUNDED"],
  "confirmDelete": true
}
```

## 錯誤處理

### 常見錯誤
- `用戶未認證` - JWT token無效或過期
- `必須確認刪除操作` - confirmDelete不為true
- `要删除的状态列表不能为空` - statusList為空
- `无效的状态值` - 狀態值不在允許範圍內
- `单次最多只能指定10个状态` - 狀態數量超過限制

### 響應狀態碼
- `200` - 操作成功
- `400` - 請求參數錯誤
- `401` - 用戶未認證
- `500` - 服務器內部錯誤

## 日誌記錄
系統會記錄以下關鍵信息：
- 刪除操作的發起用戶
- 指定的狀態列表
- 實際刪除的鏈接數量
- 操作結果（成功/失敗）
- 失敗原因（如有）

這些日誌有助於問題排查和操作審計。