# 创建目录API修复说明

## 修复日期
2025-10-26

## 问题描述
原 `quark_api_create_folder.php` API 无法正常创建目录，请求失败。

## 根本原因分析

通过对比工作代码，发现以下问题：

### 1. API端点错误
**错误的端点：**
```
https://drive.quark.cn/1/clouddrive/file/create
```

**正确的端点：**
```
https://drive-pc.quark.cn/1/clouddrive/file?pr=ucpro&fr=pc&uc_param_str=
```

### 2. 请求参数格式错误
**错误的参数：**
```json
{
    "parent_fid": "0",
    "file_name": "目录名",
    "file_type": 1
}
```

**正确的参数：**
```json
{
    "pdir_fid": "0",
    "file_name": "目录名",
    "dir_path": "",
    "dir_init_lock": false
}
```

### 3. 响应判断逻辑错误
**错误的判断：**
```php
if (isset($json_resp['code']) && $json_resp['code'] === 0)
```

**正确的判断：**
```php
if ($http_code == 200 && isset($json_resp['status']) && $json_resp['status'] == 200)
```

### 4. 请求头过于复杂
原代码包含了很多不必要的请求头，简化后使用最基本的请求头即可正常工作。

## 修复内容

### 修改文件
- `quark_api_create_folder.php`

### 核心修改

#### 1. 修正 `buildQuarkHeaders` 函数
```php
function buildQuarkHeaders($cookie, $add_csrf = false) {
    $headers = [
        'Content-Type: application/json',
        'Origin: https://pan.quark.cn',
        'Referer: https://pan.quark.cn/',
        'User-Agent: Mozilla/5.0',
        'Cookie: ' . $cookie
    ];
    
    if ($add_csrf) {
        $cookie_arr = [];
        foreach (explode(';', $cookie) as $c) {
            $kv = explode('=', trim($c), 2);
            if (count($kv) == 2) {
                $cookie_arr[$kv[0]] = $kv[1];
            }
        }
        $csrf_token = isset($cookie_arr['csrf-token']) ? $cookie_arr['csrf-token'] : '';
        if ($csrf_token) {
            $headers[] = 'x-csrf-token: ' . $csrf_token;
        }
    }
    
    return $headers;
}
```

#### 2. 修正 `createFolder` 函数中的创建逻辑
```php
// 修正API端点
$create_url = 'https://drive-pc.quark.cn/1/clouddrive/file?pr=ucpro&fr=pc&uc_param_str=';

// 修正请求参数
$create_data = [
    "pdir_fid" => $parent_fid,
    "file_name" => $folder_name,
    "dir_path" => "",
    "dir_init_lock" => false
];

// 修正响应判断
if ($http_code == 200 && isset($json_resp['status']) && $json_resp['status'] == 200) {
    return ['success' => true, 'fid' => $json_resp['data']['fid'], 'existed' => false];
}
```

#### 3. 删除冗余函数
移除了 `extractCsrfToken` 函数，将其逻辑整合到 `buildQuarkHeaders` 中。

## 验证方法

### 测试文件
创建了 `test_create_folder.html` 用于快速测试API功能。

### 使用方法
1. 将测试文件放在与API相同的目录下
2. 通过Web服务器访问测试页面
3. 输入Cookie和目录名称
4. 点击"创建目录"按钮
5. 查看返回结果

### 成功响应示例
```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"
    }
}
```

## 技术要点

### 关键发现
1. **域名选择**：创建目录必须使用 `drive-pc.quark.cn` 而非 `drive.quark.cn`
2. **参数命名**：必须使用 `pdir_fid` 而非 `parent_fid`
3. **必需参数**：`dir_path` 和 `dir_init_lock` 是必需的参数
4. **响应格式**：API返回的是 `status: 200` 而非 `code: 0`
5. **简化原则**：简单的请求头反而更稳定可靠

### API行为确认
- ✅ 目录不存在时会自动创建
- ✅ 目录已存在时返回现有目录信息，不会报错
- ✅ 支持在根目录和子目录下创建
- ✅ 返回完整的目录信息包括FID

## 后续优化建议

虽然API现在已经可以正常工作，但还可以考虑以下优化：

1. **批量创建**：支持一次创建多级目录结构
2. **重命名功能**：添加目录重命名API
3. **移动功能**：添加目录移动API
4. **权限检查**：创建前检查是否有写入权限
5. **名称验证**：增加目录名称的合法性检查

## 参考代码来源

修复基于用户提供的工作代码，该代码经过验证可以正常工作。感谢用户提供参考实现！

## 相关文件

- `quark_api_create_folder.php` - 修复后的创建目录API
- `test_create_folder.html` - API测试页面
- `README_API_FOLDER_DELETE.md` - 更新后的API文档

## 总结

此次修复主要是通过对比工作代码，发现并修正了API端点、请求参数格式和响应判断逻辑的错误。修复后的API已经可以正常创建目录，并能正确处理目录已存在的情况。