markbase/docs/DOWNLOAD_SERVICE_GUIDE.md

# AccuSys Download Service Guide

## Overview

**取代OneDrive的企业下载服务**

- 域名：`download.accusys.ddns.net`（HTTPS via Caddy）
- 服务：MarkBase v2.3（Rust + Axum）
- 存储：`/Users/accusys/Downloads/:user_id/`

---

## Current Features (Phase 1 Complete)

### Upload Service ✅

**Web界面：** https://download.accusys.ddns.net/upload

**功能：**
- ✅ 无限制上传（DefaultBodyLimit::disable()）
- ✅ 文件夹批量上传（webkitdirectory）
- ✅ 空文件支持（0 bytes）
- ✅ 空子目录支持（.keep workaround）
- ✅ SHA256完整性校验
- ✅ 30分钟超时保护（AbortController）
- ✅ 实时进度显示

**API：**
```
POST /api/v2/upload-unlimited/:user_id
```

**测试：**
- ✅ 50MB文件上传成功
- ✅ 子目录创建成功
- ✅ 空文件上传成功
- ✅ SHA256校验正确

---

### File List Service ✅ (NEW)

**Web界面：** https://download.accusys.ddns.net/files

**功能：**
- ✅ 完整文件列表（total_files, total_size）
- ✅ 文件详情（filename, size, hash, path, upload_time）
- ✅ 自动刷新按钮
- ✅ 企业级UI设计（Apple风格）

**API：**
```
GET /api/v2/files/:user_id           # 获取完整文件列表
GET /api/v2/files/:user_id/:filename # 获取单个文件信息
```

**响应示例：**
```json
{
  "user_id": "accusys",
  "total_files": 9,
  "total_size": 589893,
  "files": [
    {
      "filename": "Carousel01.png",
      "file_size": 573397,
      "file_hash": "0612cd4742caf17e77a5b00fa01bc4bff1820d842254f32a66f69758f2289e7e",
      "relative_path": "Carousel01.png",
      "upload_time": "2026-06-09T05:00:37Z"
    }
  ]
}
```

---

## Usage Guide

### 1. Upload Files (Single or Folder)

**步骤：**

```bash
# 1. 准备空目录（如果需要）
bash scripts/prepare_upload.sh /path/to/source_folder

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

# 3. 选择文件夹（webkitdirectory支持）
- 点击"Select Folder"
- 选择整个文件夹
- 自动上传所有文件
- 实时进度显示

# 4. 验证上传
https://download.accusys.ddns.net/files
```

---

### 2. View Uploaded Files

**Web界面：** https://download.accusys.ddns.net/files

**功能：**
- 显示总文件数、总大小
- 列出所有文件（filename, size, hash, path, time）
- 实时刷新按钮

**API方式：**
```bash
# 获取完整文件列表
curl -s https://download.accusys.ddns.net/api/v2/files/accusys | jq '.total_files, .total_size'

# 获取单个文件信息
curl -s https://download.accusys.ddns.net/api/v2/files/accusys/Carousel01.png | jq '.file_size, .file_hash'
```

---

## Next Steps (Phase 2-5)

### Phase 2: Product List API (TODO)

**目标：**按产品系列分类文件

**数据库设计：**
```sql
CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    product_name TEXT,
    series TEXT, -- ExaSAN-DAS, ExaSAN-SAN, Gamma, T-Share, InneRAID, Legacy
    description TEXT
);

CREATE TABLE product_files (
    id INTEGER PRIMARY KEY,
    product_id INTEGER,
    file_path TEXT,
    download_count INTEGER DEFAULT 0,
    uploaded_at TEXT,
    FOREIGN KEY (product_id) REFERENCES products(id)
);
```

**API设计：**
```
GET /api/v2/products              # 获取产品列表
GET /api/v2/products/:series      # 获取特定系列产品
GET /api/v2/products/:id/files    # 获取产品的文件列表
```

---

### Phase 3: Download API (TODO)

**目标：**提供下载URL

**API设计：**
```
GET /api/v2/download/:file_id     # 下载文件（增加下载计数）
GET /api/v2/download/stats        # 下载统计
```

**功能：**
- 文件下载（直接下载到浏览器）
- SHA256校验（下载后验证）
- 下载统计（每个文件下载次数）

---

### Phase 4: File Migration (TODO)

**目标：**迁移290个文件到正式目录

**迁移策略：**
```bash
# 1. 创建产品目录结构
mkdir -p /Users/accusys/Downloads/accusys/{ExaSAN-DAS,ExaSAN-SAN,Gamma,T-Share,InneRAID,Legacy}

# 2. 上传290个文件（按产品分类）
https://download.accusys.ddns.net/upload

# 3. 导入到数据库
INSERT INTO product_files ...
```

---

### Phase 5: Download Statistics (TODO)

**目标：**下载统计和访问控制

**数据库设计：**
```sql
CREATE TABLE download_log (
    id INTEGER PRIMARY KEY,
    file_id INTEGER,
    download_time TEXT,
    ip_address TEXT,
    user_agent TEXT,
    FOREIGN KEY (file_id) REFERENCES product_files(id)
);
```

---

## Architecture

```
MarkBase Download Service
├── Upload Service (✅ Complete)
│   ├── upload.html (Web界面)
│   ├── upload_unlimited API
│   └── storage.rs (文件存储)
│
├── File List Service (✅ Complete)
│   ├── file_list.html (Web界面)
│   ├── storage.rs (文件扫描)
│   ├── handlers.rs (API handlers)
│   └── db.rs (数据库准备)
│
├── Product Service (⚠️ TODO Phase 2)
│   ├── products/files API
│   └── download.sqlite
│
└── Download Service (⚠️ TODO Phase 3)
    ├── download API
    └── stats API
```

---

## Testing Results

**Upload Service Testing：**
- ✅ 50MB file upload (成功)
- ✅ Empty file upload (.localized)
- ✅ Empty directory (.keep workaround)
- ✅ SHA256 checksum verified

**File List Service Testing：**
- ✅ API endpoint working (GET /api/v2/files/accusys)
- ✅ Web UI working (https://download.accusys.ddns.net/files)
- ✅ File metadata correct (size, hash, path, time)
- ✅ Real-time refresh working

---

## Current Status

**已完成功能（2/5）：**
1. ✅ Upload Service（无限制上传 + 文件夹批量）
2. ✅ File List Service（文件列表查看）
3. ⚠️ Product List API（待开发）
4. ⚠️ Download API（待开发）
5. ⚠️ Download Statistics（待开发）

**已上传文件：**
- 总文件数：9个
- 总大小：576KB
- 用户：accusys
- 存储路径：/Users/accusys/Downloads/accusys/

---

## Deployment

**MarkBase PID：** 8936（运行中）

**Port：** 11438（HTTP）+ 80/443（HTTPS via Caddy）

**Caddy Config：**
```
download.accusys.ddns.net {
    reverse_proxy localhost:11438
}
```

---

**Last Updated：** 2026-06-09 14:22
**Version：** 2.7 (Download Service Phase 1 Complete)