markbase/docs/USER_UPLOAD_GUIDE.md

# 一键上传完整流程（用户操作指南）

## 您需要执行的3个步骤

---

## 步骤1：准备空目录（您运行命令）

**执行时机：** 上传前准备阶段

**您需要运行的命令：**

```bash
# 格式1：从本地目录准备
bash scripts/prepare_upload.sh "<您的目录路径>"

# 实际示例：
# AccuSys Downloads目录
bash scripts/prepare_upload.sh "/Users/accusys/Downloads/AccuSys Downloads"

# 从外部硬盘
bash scripts/prepare_upload.sh "/Volumes/ExternalDrive/ProductFiles"

# 从服务器共享
bash scripts/prepare_upload.sh "/Volumes/ServerShare/DownloadFiles"
```

**执行结果：**
- ✅ 所有空目录添加`.keep`文件
- ✅ Nested目录自动处理（4层深度支持）
- ✅ 输出处理统计信息

---

## 步骤2：上传文件夹（您操作浏览器）

**执行时机：** 准备完成后立即上传

**您需要操作的步骤：**

1. **打开浏览器访问：**
   ```
   https://download.accusys.ddns.net/upload
   ```

2. **填写User ID：**
   - 输入：`accusys`（或您的用户名）

3. **选择文件夹：**
   - 点击"Select Folder"按钮
   - 选择您准备好的文件夹
   - **重要：** 必须是包含`.keep`文件的文件夹

4. **开始上传：**
   - 点击"Start Upload"
   - 等待进度条完成

5. **上传完成：**
   - 所有文件上传成功
   - SHA256校验完成
   - 目录结构完整保留

---

## 步骤3：验证结果（您查看）

**执行时机：** 上传完成后验证

**您需要查看的内容：**

### Web界面验证：
```
https://download.accusys.ddns.net/files
```

### API验证（可选）：

```bash
# 查看总文件数和总大小
curl -s https://download.accusys.ddns.net/api/v2/files/accusys | jq '{
  "总文件数": .total_files,
  "总大小(KB)": (.total_size / 1024 | floor)
}'

# 查看所有.keep文件（验证空目录）
curl -s https://download.accusys.ddns.net/api/v2/files/accusys | \
  jq '.files[] | select(.filename == ".keep") | .relative_path'

# 查看nested目录
curl -s https://download.accusys.ddns.net/api/v2/files/accusys | \
  jq '.files[] | select(.relative_path | contains("Level")) | .relative_path'
```

---

## 实际操作示例（完整流程）

### 示例：上传AccuSys Downloads（290个文件）

```bash
# === 步骤1：准备空目录 ===
# 您运行此命令：
bash scripts/prepare_upload.sh "/Users/accusys/Downloads/AccuSys Downloads"

# 输出：
=== Preparing upload for /Users/accusys/Downloads/AccuSys Downloads ===

Added .keep in: ExaSAN-DAS/Model002/EmptyFolder
Added .keep in: ExaSAN-DAS/EmptySubFolder
Added .keep in: Gamma/EmptyFolder
...

=== Preparation complete ===
Empty directories: 0
Total .keep files: 10
Ready for webkitdirectory upload
```

```bash
# === 步骤2：上传文件夹 ===
# 您操作浏览器：
1. 打开 https://download.accusys.ddns.net/upload
2. User ID: accusys
3. Select Folder: 选择"AccuSys Downloads"
4. Start Upload
5. 等待完成（290个文件 + 10个.keep）

# 浏览器显示：
Uploading: ExaSAN-DAS/Model001/readme.pdf
Uploading: ExaSAN-DAS/Model002/EmptyFolder/.keep
Uploading: Gamma/manual.pdf
...
Progress: 100% complete
Total files: 300 uploaded
```

```bash
# === 步骤3：验证结果 ===
# 您运行此命令验证：
curl -s https://download.accusys.ddns.net/api/v2/files/accusys | jq '.total_files'

# 输出：
300（290个文件 + 10个.keep）

# 查看目录结构：
find /Users/accusys/Downloads/accusys -type d | head -20

# 输出：
/Users/accusys/Downloads/accusys/ExaSAN-DAS
/Users/accusys/Downloads/accusys/ExaSAN-DAS/Model001
/Users/accusys/Downloads/accusys/ExaSAN-DAS/Model002
/Users/accusys/Downloads/accusys/ExaSAN-DAS/Model002/EmptyFolder
/Users/accusys/Downloads/accusys/ExaSAN-DAS/EmptySubFolder
/Users/accusys/Downloads/accusys/Gamma
/Users/accusys/Downloads/accusys/Gamma/EmptyFolder
...

# 所有空目录完整保留 ✅
```

---

## Nested目录支持验证

**测试多层嵌套空目录：**

```bash
# 创建测试结构
mkdir -p /tmp/test_nested/Level1/Level2/Level3/DeepEmpty
mkdir -p /tmp/test_nested/Level1/Level2/EmptyAtLevel2

# 运行准备脚本
bash scripts/prepare_upload.sh /tmp/test_nested

# 输出：
Added .keep in: /tmp/test_nested/Level1/Level2/Level3/DeepEmpty
Added .keep in: /tmp/test_nested/Level1/Level2/EmptyAtLevel2

# 上传后验证
find /Users/accusys/Downloads/accusys -type d | grep Level

# 输出：
/Users/accusys/Downloads/accusys/Level1
/Users/accusys/Downloads/accusys/Level1/Level2
/Users/accusys/Downloads/accusys/Level1/Level2/Level3
/Users/accusys/Downloads/accusys/Level1/Level2/Level3/DeepEmpty
/Users/accusys/Downloads/accusys/Level1/Level2/EmptyAtLevel2

# ✅ 4层nested目录完整保留
```

---

## 常见问题解答

### Q1: 脚本在哪里？
**答：** `/Users/accusys/markbase/scripts/prepare_upload.sh`

### Q2: 我需要什么权限？
**答：** 只需要文件读取权限，无需sudo

### Q3: 准备后可以删除.keep吗？
**答：** 可以，但建议保留（作为目录标记）

### Q4: Nested目录最多支持几层？
**答：** 无限制（测试已验证4层深度成功）

### Q5: 上传时浏览器做什么？
**答：** webkitdirectory自动选择所有文件（包括.keep）

---

## 责任分工总结

| 步骤 | 执行者 | 操作 |
|------|--------|------|
| **步骤1** | **您** | 运行`prepare_upload.sh` |
| **步骤2** | **您** | 操作浏览器上传 |
| **步骤3** | **您** | 查看验证结果 |
| **系统** | MarkBase | 接收、存储、校验 |

---

**总结：您只需要运行prepare_upload.sh脚本，然后操作浏览器上传，系统自动处理所有nested空目录。**

---

**Last Updated：** 2026-06-09 15:00
**Version：** 2.9 (完整操作流程指南)