# 夸克网盘目录管理与文件删除API文档

本文档说明两个新创建的目录和文件管理API的使用方法。

> **重要更新（2025-10-26）：** 创建目录API已修正，现已正常工作。主要修复：
> - 修正了创建目录的API端点（使用正确的 `drive-pc.quark.cn` 域名）
> - 修正了请求参数格式（使用 `pdir_fid`、`dir_path` 等正确参数）
> - 简化了请求头构建逻辑
> - 修正了响应状态码判断逻辑

---

## API 1: 创建目录API

**文件名：** `quark_api_create_folder.php`

### 功能描述
在指定的父目录下创建新目录，如果目录已存在则返回已存在目录的信息。

### 核心特性
- ✅ 支持在任意父目录下创建子目录
- ✅ 自动检测目录是否已存在
- ✅ 已存在时返回现有目录信息（不会重复创建）
- ✅ 返回完整的目录信息（FID、名称、父目录等）
- ✅ 详细的日志记录和错误处理

### 接口地址
```
POST /quark_api_create_folder.php
```

### 请求参数
```json
{
    "cookie": "夸克网盘Cookie字符串（必填）",
    "parent_fid": "父目录ID（可选，默认'0'根目录）",
    "folder_name": "新目录名称（必填）"
}
```

**参数说明：**
- `cookie`: 有效的夸克网盘Cookie
- `parent_fid`: 在哪个目录下创建，'0'表示根目录
- `folder_name`: 要创建的目录名称

### 成功响应示例（新创建）
```json
{
    "success": true,
    "message": "目录创建成功",
    "data": {
        "fid": "123456789",
        "name": "我的文档",
        "parent_fid": "0",
        "parent_name": "根目录",
        "created_at": 1698765432,
        "created_at_formatted": "2024-10-31 12:30:32",
        "existed": false,
        "process_time": "234.56ms"
    }
}
```

### 成功响应示例（目录已存在）
```json
{
    "success": true,
    "message": "目录已存在",
    "data": {
        "fid": "123456789",
        "name": "我的文档",
        "parent_fid": "0",
        "parent_name": "根目录",
        "existed": true,
        "process_time": "156.32ms"
    }
}
```

### 失败响应示例
```json
{
    "success": false,
    "message": "Cookie无效：Cookie已过期或无效"
}
```

### 使用示例

#### 示例1：在根目录创建文件夹
```bash
curl -X POST http://localhost:8000/quark_api_create_folder.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "folder_name": "我的文档"
  }'
```

#### 示例2：在指定目录下创建子文件夹
```bash
curl -X POST http://localhost:8000/quark_api_create_folder.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "parent_fid": "123456789",
    "folder_name": "2024年资料"
  }'
```

#### PHP调用示例
```php
<?php
$url = 'http://localhost:8000/quark_api_create_folder.php';
$data = [
    'cookie' => 'your_cookie_here',
    'parent_fid' => '0',
    'folder_name' => '我的文档'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['success']) {
    if ($result['data']['existed']) {
        echo "目录已存在！\n";
    } else {
        echo "目录创建成功！\n";
    }
    echo "目录名称: {$result['data']['name']}\n";
    echo "目录ID: {$result['data']['fid']}\n";
} else {
    echo "操作失败: {$result['message']}\n";
}
?>
```

#### JavaScript调用示例
```javascript
fetch('http://localhost:8000/quark_api_create_folder.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        cookie: 'your_cookie_here',
        parent_fid: '0',
        folder_name: '我的文档'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log(data.data.existed ? '目录已存在' : '目录创建成功');
        console.log('目录名称:', data.data.name);
        console.log('目录ID:', data.data.fid);
    } else {
        console.error('操作失败:', data.message);
    }
});
```

#### Python调用示例
```python
import requests
import json

url = 'http://localhost:8000/quark_api_create_folder.php'
data = {
    'cookie': 'your_cookie_here',
    'parent_fid': '0',
    'folder_name': '我的文档'
}

response = requests.post(url, json=data)
result = response.json()

if result['success']:
    if result['data']['existed']:
        print("目录已存在！")
    else:
        print("目录创建成功！")
    print(f"目录名称: {result['data']['name']}")
    print(f"目录ID: {result['data']['fid']}")
else:
    print(f"操作失败: {result['message']}")
```

---

## API 2: 删除文件/目录API

**文件名：** `quark_api_delete.php`

### 功能描述
删除指定的文件或目录，支持通过文件/目录名称或FID删除。

### 核心特性
- ✅ 支持通过文件名删除
- ✅ 支持通过FID直接删除
- ✅ 同时支持文件和目录删除
- ✅ 删除到回收站（可恢复）
- ✅ 返回被删除对象的详细信息
- ✅ 完整的错误处理和日志记录

### 接口地址
```
POST /quark_api_delete.php
```

### 请求参数
```json
{
    "cookie": "夸克网盘Cookie字符串（必填）",
    "parent_fid": "父目录ID（可选，默认'0'根目录）",
    "file_name": "文件/目录名称（可选）",
    "fid": "文件/目录ID（可选）"
}
```

**参数说明：**
- `cookie`: 有效的夸克网盘Cookie
- `parent_fid`: 文件/目录所在的父目录ID（仅当使用file_name时需要）
- `file_name`: 要删除的文件或目录名称
- `fid`: 要删除的文件或目录的唯一ID

**重要规则：**
- `file_name` 和 `fid` 必须提供其中之一
- 如果同时提供，优先使用 `fid`
- 使用 `file_name` 时，会在 `parent_fid` 指定的目录中查找

### 成功响应示例
```json
{
    "success": true,
    "message": "删除成功",
    "data": {
        "fid": "987654321",
        "name": "测试文件.mp4",
        "is_dir": false,
        "size": 1073741824,
        "size_formatted": "1.00 GB",
        "parent_fid": "0",
        "process_time": "312.45ms"
    }
}
```

### 失败响应示例
```json
{
    "success": false,
    "message": "未找到名称为 '测试文件.mp4' 的文件或目录"
}
```

### 使用示例

#### 示例1：通过FID删除文件
```bash
curl -X POST http://localhost:8000/quark_api_delete.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "fid": "987654321"
  }'
```

#### 示例2：通过文件名删除（根目录）
```bash
curl -X POST http://localhost:8000/quark_api_delete.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "file_name": "测试文件.mp4"
  }'
```

#### 示例3：通过文件名删除（指定目录）
```bash
curl -X POST http://localhost:8000/quark_api_delete.php \
  -H "Content-Type: application/json" \
  -d '{
    "cookie": "your_cookie_here",
    "parent_fid": "123456789",
    "file_name": "临时文件.txt"
  }'
```

#### PHP调用示例
```php
<?php
$url = 'http://localhost:8000/quark_api_delete.php';
$data = [
    'cookie' => 'your_cookie_here',
    'fid' => '987654321'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['success']) {
    echo "删除成功！\n";
    echo "文件名: {$result['data']['name']}\n";
    echo "类型: " . ($result['data']['is_dir'] ? '目录' : '文件') . "\n";
    echo "大小: {$result['data']['size_formatted']}\n";
} else {
    echo "删除失败: {$result['message']}\n";
}
?>
```

#### JavaScript调用示例
```javascript
fetch('http://localhost:8000/quark_api_delete.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        cookie: 'your_cookie_here',
        fid: '987654321'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('删除成功！');
        console.log('文件名:', data.data.name);
        console.log('类型:', data.data.is_dir ? '目录' : '文件');
        console.log('大小:', data.data.size_formatted);
    } else {
        console.error('删除失败:', data.message);
    }
});
```

#### Python调用示例
```python
import requests
import json

url = 'http://localhost:8000/quark_api_delete.php'
data = {
    'cookie': 'your_cookie_here',
    'fid': '987654321'
}

response = requests.post(url, json=data)
result = response.json()

if result['success']:
    print("删除成功！")
    print(f"文件名: {result['data']['name']}")
    print(f"类型: {'目录' if result['data']['is_dir'] else '文件'}")
    print(f"大小: {result['data']['size_formatted']}")
else:
    print(f"删除失败: {result['message']}")
```

---

## 组合使用场景

### 场景1：批量创建目录结构
```php
<?php
// 创建多层目录结构
$folders = ['文档', '图片', '视频', '音乐'];

foreach ($folders as $folder) {
    $result = callAPI('quark_api_create_folder.php', [
        'cookie' => $cookie,
        'folder_name' => $folder
    ]);
    
    if ($result['success']) {
        echo "创建目录: {$folder} - " . 
             ($result['data']['existed'] ? '已存在' : '创建成功') . "\n";
    }
}
?>
```

### 场景2：清理临时文件
```php
<?php
// 删除所有临时文件
$temp_files = ['temp1.txt', 'temp2.txt', 'cache.dat'];

foreach ($temp_files as $file) {
    $result = callAPI('quark_api_delete.php', [
        'cookie' => $cookie,
        'parent_fid' => '0',
        'file_name' => $file
    ]);
    
    if ($result['success']) {
        echo "已删除: {$result['data']['name']}\n";
    } else {
        echo "删除失败: {$file} - {$result['message']}\n";
    }
}
?>
```

### 场景3：转存到自动创建的分类目录
```php
<?php
// 先创建分类目录
$category_result = callAPI('quark_api_create_folder.php', [
    'cookie' => $cookie,
    'folder_name' => '电影'
]);

if ($category_result['success']) {
    $folder_id = $category_result['data']['fid'];
    
    // 转存到该目录
    $transfer_result = callAPI('quark_api_transfer.php', [
        'cookie' => $cookie,
        'share_url' => 'https://pan.quark.cn/s/abc123',
        'target_folder_id' => $folder_id
    ]);
    
    if ($transfer_result['success']) {
        echo "转存成功到目录: {$category_result['data']['name']}\n";
    }
}
?>
```

---

## 部署说明

### 使用PHP内置服务器
```bash
cd c:\Users\Administrator\Desktop\quark1.1
php -S localhost:8000

# 访问地址：
# http://localhost:8000/quark_api_create_folder.php
# http://localhost:8000/quark_api_delete.php
```

---

## 错误码说明

| HTTP状态码 | 说明 |
|-----------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | Cookie无效或已过期 |
| 404 | 未找到指定的文件或目录 |
| 405 | 请求方法错误（仅支持POST） |
| 500 | 服务器内部错误 |

---

## 注意事项

### 创建目录API
1. **重复创建**：如果目录已存在，不会报错，而是返回已存在的目录信息
2. **父目录**：如果指定的父目录不存在，会自动使用根目录
3. **目录名称**：建议使用中文或英文，避免特殊字符

### 删除API
1. **删除方式**：文件/目录会被删除到回收站，可以恢复
2. **批量删除**：如需批量删除，请多次调用API
3. **权限检查**：只能删除当前Cookie账号下的文件/目录
4. **查找方式**：使用file_name时，如果存在同名文件，会删除第一个匹配的

---

## 常见问题

### Q1: 如何创建多层嵌套目录？
A: 需要逐层创建。先创建父目录获取FID，再在该FID下创建子目录。

### Q2: 删除目录时会删除里面的文件吗？
A: 是的，删除目录会同时删除目录下的所有内容。

### Q3: 删除的文件可以恢复吗？
A: 可以。API使用的是删除到回收站（action_type=2），可以从回收站恢复。

### Q4: 如何彻底删除文件？
A: 当前API使用回收站模式。如需彻底删除，需要修改`deleteFile`函数中的`action_type`为1。

### Q5: 创建目录时如何判断是新创建还是已存在？
A: 查看响应中的`existed`字段，`false`表示新创建，`true`表示已存在。

---

## API功能对比表

| 功能 | 创建目录API | 删除API |
|------|-----------|---------|
| **主要功能** | 创建新目录 | 删除文件/目录 |
| **支持文件名** | ✅ | ✅ |
| **支持FID** | ❌ | ✅ |
| **父目录指定** | ✅ | ✅ |
| **重复处理** | 返回已存在 | N/A |
| **恢复能力** | N/A | ✅ 回收站 |
| **批量操作** | ❌ | ❌ |

---

## 版本信息

- **版本**: 1.0.0
- **创建日期**: 2025-10-26
- **作者**: AI Assistant
- **依赖**: PHP 7.0+, cURL扩展

---

## 更新日志

### v1.0.0 (2025-10-26)
- ✨ 初始版本发布
- ✨ 支持创建目录功能
- ✨ 支持通过名称或FID删除文件/目录
- ✨ 完整的错误处理和日志记录
- ✨ 自动检测目录是否已存在