# 空目录上传完整指南

## 问题说明

**webkitdirectory限制：**
- HTML5标准：浏览器只选择**文件**
- 空目录不包含在`fileInput.files`中
- 无法上传完全空的目录

## 解决方案：.keep标记文件

**原理：**
- 在每个空目录中添加`.keep`文件（0字节）
- webkitdirectory会上传包含`.keep`的目录
- 目录结构完整保留

---

## 完整工作流程

### 步骤1：准备源目录

```bash
# 查看源目录结构
tree /path/to/source

# 示例结构：
/path/to/AccuSys Downloads/
├── ExaSAN-DAS/
│   ├── Model001/
│   │   └── readme.pdf          # 有文件
│   ├── EmptyFolder1/           # 空目录
│   └── EmptyFolder2/           # 空目录
├── Gamma/
│   └── EmptySubFolder/         # 空目录
└── T-Share/
    └── manual.pdf              # 有文件
```

---

### 步骤2：运行prepare_upload.sh脚本

```bash
# 一键添加.keep文件
bash scripts/prepare_upload.sh "/path/to/AccuSys Downloads"

# 输出示例：
=== Preparing upload for /path/to/AccuSys Downloads ===

Added .keep in: /path/to/AccuSys Downloads/ExaSAN-DAS/EmptyFolder1
Added .keep in: /path/to/AccuSys Downloads/ExaSAN-DAS/EmptyFolder2
Added .keep in: /path/to/AccuSys Downloads/Gamma/EmptySubFolder

=== Preparation complete ===
Empty directories: 0
Total .keep files: 3

Ready for webkitdirectory upload
All empty directories will be uploaded with .keep files
```

---

### 步骤3：验证准备结果

```bash
# 查看所有.keep文件
find "/path/to/AccuSys Downloads" -name ".keep"

# 查看完整目录结构
tree "/path/to/AccuSys Downloads"
```

**预期结果：**
```
AccuSys Downloads/
├── ExaSAN-DAS/
│   ├── Model001/
│   │   └── readme.pdf
│   ├── EmptyFolder1/
│   │   └── .keep              ✅ 添加成功
│   ├── EmptyFolder2/
│   │   └ keep              ✅ 添加成功
├── Gamma/
│   ├── EmptySubFolder/
│   │   └ keep              ✅ 添加成功
└── T-Share/
    └ manual.pdf
```

---

### 步骤4：上传文件夹

```bash
# 打开Web界面
https://download.accusys.ddns.net/upload

# 选择文件夹
1. 点击"Select Folder"
2. 选择整个"AccuSys Downloads"文件夹
3. 自动上传所有文件（包括.keep）

# 上传结果：
- ✅ 所有文件上传成功
- ✅ 所有空目录保留（包含.keep）
- ✅ 目录结构完整
```

---

### 步骤5：验证上传结果

```bash
# 查看上传文件列表
curl -s https://download.accusys.ddns.net/api/v2/files/accusys | jq '.total_files'

# 查看目录结构（在服务器端）
find /Users/accusys/Downloads/accusys -type d

# 验证.keep文件
curl -s https://download.accusys.ddns.net/api/v2/files/accusys | jq '.files[] | select(.filename == ".keep")'
```

---

## .keep文件说明

**文件特性：**
- 文件名：`.keep`（或`.gitkeep`）
- 文件大小：0字节（空文件）
- 文件作用：标记空目录存在
- SHA256：`e3b0c44298fc1c149afbf4c8996fb924...`（标准空文件hash）

**保留策略：**
- ✅ 上传后保留`.keep`文件
- ✅ 不影响其他文件
- ✅ 不占用额外空间
- ✅ 符合Git标准惯例

---

## 脚本源码（prepare_upload.sh）

```bash
#!/bin/bash
# prepare_upload.sh - Prepare directory for upload
# Add .keep files in all empty directories

SOURCE_DIR="$1"

if [ -z "$SOURCE_DIR" ]; then
    echo "Usage: bash scripts/prepare_upload.sh <source_directory>"
    exit 1
fi

if [ ! -d "$SOURCE_DIR" ]; then
    echo "Error: Directory not found: $SOURCE_DIR"
    exit 1
fi

echo "=== Preparing upload for $SOURCE_DIR ==="
echo ""

# Find empty directories and add .keep
empty_count=0
find "$SOURCE_DIR" -type d -empty | while read dir; do
    touch "$dir/.keep"
    empty_count=$((empty_count + 1))
    echo "Added .keep in: $dir"
done

echo ""
echo "=== Preparation complete ==="
echo "Empty directories: $(find "$SOURCE_DIR" -type d -empty | wc -l)"
echo "Total .keep files: $(find "$SOURCE_DIR" -name ".keep" | wc -l)"
echo ""
echo "Ready for webkitdirectory upload"
echo "All empty directories will be uploaded with .keep files"
```

---

## 高级用法

### 批量处理多个目录

```bash
# 处理290个文件所在的目录
bash scripts/prepare_upload.sh "/path/to/AccuSys Downloads"

# 处理嵌套空目录（多层）
bash scripts/prepare_upload.sh "/path/to/complex/structure"

# 查看处理结果
find "/path/to/AccuSys Downloads" -name ".keep" | wc -l
```

---

### 上传后清理.keep（可选）

```bash
# 如果需要删除.keep文件（保留空目录）
find /Users/accusys/Downloads/accusys -name ".keep" -delete

# 注意：删除后目录仍存在，但为空目录
```

---

## 测试案例

**测试目录：** `/tmp/test_upload`

**原始结构：**
```
/tmp/test_upload/
├── ExaSAN-DAS/
│   ├── Model001/readme.txt      # 有文件
│   ├── Model002/EmptyFolder/    # 空目录
│   └ EmptySubFolder/           # 空目录
├── Gamma/manual.pdf             # 有文件
└ T-Share/
    ├── EmptyFolder1/            # 空目录
    └ EmptyFolder2/            # 空目录
```

**运行脚本：**
```bash
bash scripts/prepare_upload.sh /tmp/test_upload
```

**处理结果：**
```
Added .keep in: /tmp/test_upload/T-Share/EmptyFolder2
Added .keep in: /tmp/test_upload/T-Share/EmptyFolder1
Added .keep in: /tmp/test_upload/ExaSAN-DAS/Model002/EmptyFolder
Added .keep in: /tmp/test_upload/ExaSAN-DAS/EmptySubFolder

Empty directories: 0
Total .keep files: 4
```

**最终结构：**
```
/tmp/test_upload/
├── ExaSAN-DAS/
│   ├── Model001/readme.txt
│   ├── Model002/EmptyFolder/.keep
│   ├── EmptySubFolder/.keep
├── Gamma/manual.pdf
└── T-Share/
    ├── EmptyFolder1/.keep
    ├── EmptyFolder2/.keep
```

---

## 常见问题

### Q1: .keep文件会影响其他文件吗？
**答：** 不会。`.keep`是独立文件，不影响其他文件的上传和下载。

### Q2: 可以使用其他名称吗？
**答：** 可以。常见替代名称：
- `.gitkeep`（Git标准）
- `.placeholder`
- `README.md`（如果需要说明文字）
- `.localized`（macOS系统文件）

### Q3: 上传后.keep文件必须保留吗？
**答：** 可选。如果删除`.keep`：
- 目录仍然存在（但变为空目录）
- 不影响其他文件
- 建议保留（作为目录存在标记）

### Q4: webkitdirectory有其他限制吗？
**答：** 有。其他限制：
- 无法上传隐藏文件（如`.DS_Store`）← 但MarkBase已支持
- 无法上传符号链接
- 无法控制上传顺序

---

## MarkBase特殊支持

**已实现功能：**
- ✅ 空文件上传（0字节文件）
- ✅ `.keep`、`.localized`、`.DS_Store`上传
- ✅ 子目录自动创建（`create_dir_all`）
- ✅ SHA256校验（包含空文件）
- ✅ 无文件大小限制

**API支持：**
```bash
# 上传空文件
curl -X POST https://download.accusys.ddns.net/api/v2/upload-unlimited/accusys \
  -F "file=@/tmp/test_upload/ExaSAN-DAS/EmptySubFolder/.keep;filename=ExaSAN-DAS/EmptySubFolder/.keep"

# 返回：
{
  "ok": true,
  "filename": "ExaSAN-DAS/EmptySubFolder/.keep",
  "file_size": 0,
  "file_hash": "e3b0c44298fc1c149afbf4c8996fb924..."
}
```

---

## 总结

**最佳实践：**
1. ✅ 使用`prepare_upload.sh`一键处理
2. ✅ 上传前验证`.keep`文件数量
3. ✅ 上传后检查目录结构完整性
4. ✅ 保留`.keep`文件（可选）

**适用场景：**
- ✅ AccuSys下载文件（290个文件）
- ✅ 产品资料库（多层目录）
- ✅ 软件发布包（含空目录）
- ✅ 文档管理系统

---

**Last Updated：** 2026-06-09 14:45
**Version：** 2.8 (Empty Directory Support Complete)