docs: migrate legacy docs to official site

docs/guide/chunked-uploads.md

@@ -1,63 +1,107 @@
 # Chunked Uploads
 
-OxiCloud supports TUS-like chunked uploads for large files. Uploads are parallel, resumable, and have MD5 integrity checks.
+OxiCloud exposes resumable chunked uploads under `/api/uploads`. The protocol is TUS-like in spirit, but the concrete API is OxiCloud-specific: create a session, stream chunks with `PATCH`, inspect progress with `HEAD`, then finalize the assembled file.
 
-## How It Works
+## Upload Flow
 
-1. Client sends `POST /api/files/upload/init` with file metadata → receives an `upload_id`
-2. Client splits the file into chunks and uploads them in parallel via `POST /api/files/upload/chunk`
-3. Each chunk includes its index, MD5 hash, and the `upload_id`
-4. When all chunks are uploaded, client calls `POST /api/files/upload/complete`
-5. Server reassembles the file, verifies integrity, and runs deduplication
+1. Create an upload session with `POST /api/uploads`
+2. Upload each chunk with `PATCH /api/uploads/{upload_id}?chunk_index=N`
+3. Optionally inspect progress with `HEAD /api/uploads/{upload_id}`
+4. Finalize with `POST /api/uploads/{upload_id}/complete`
+5. Cancel an in-flight upload with `DELETE /api/uploads/{upload_id}` if needed
 
 ## API Endpoints
 
-### Initialize Upload
+### Create upload session
 
 ```http
-POST /api/files/upload/init
+POST /api/uploads
 Content-Type: application/json
 
 {
-  "file_name": "large-video.mp4",
+  "filename": "large-video.mp4",
   "folder_id": "folder-uuid",
+  "content_type": "video/mp4",
   "total_size": 524288000,
-  "chunk_size": 8388608,
-  "total_chunks": 63
+  "chunk_size": 8388608
 }
 ```
 
-### Upload Chunk
-
-```http
-POST /api/files/upload/chunk
-Content-Type: multipart/form-data
-
-upload_id: "uuid"
-chunk_index: 0
-chunk_hash: "md5-hex"
-file: <binary>
-```
-
-### Complete Upload
-
-```http
-POST /api/files/upload/complete
-Content-Type: application/json
+Typical response:
 
+```json
 {
-  "upload_id": "uuid"
+  "upload_id": "uuid",
+  "chunk_size": 8388608,
+  "total_chunks": 63,
+  "expires_at": 86400
 }
 ```
 
-## Configuration
+### Upload a chunk
 
-| Parameter | Default | Description |
-|---|---|---|
-| Max parallel chunks | 8 | Concurrent chunk uploads |
-| Min size for chunking | 200 MB | Below this, single-shot upload is used |
-| Chunk size | 8 MB | Default chunk size |
+Chunks are sent as raw bytes, not multipart form uploads.
 
-## Frontend Behaviour
+```http
+PATCH /api/uploads/{upload_id}?chunk_index=0&checksum=md5-hex
+Content-Type: application/octet-stream
+Content-MD5: md5-hex
 
-The OxiCloud web UI automatically selects chunked upload for large files. A progress bar shows overall completion and current chunk status.
+<binary chunk bytes>
+```
+
+Notes:
+
+- `chunk_index` is required and zero-based
+- `checksum` is optional and can also be supplied with the `Content-MD5` header
+- Successful responses include progress headers such as `Upload-Offset`, `Upload-Progress`, and `Upload-Complete`
+
+### Inspect upload status
+
+```http
+HEAD /api/uploads/{upload_id}
+```
+
+The response includes upload metadata in headers such as:
+
+- `Upload-Offset`
+- `Upload-Length`
+- `Upload-Progress`
+- `Upload-Chunks-Total`
+- `Upload-Chunks-Complete`
+
+### Finalize upload
+
+```http
+POST /api/uploads/{upload_id}/complete
+```
+
+Successful responses return the created file metadata:
+
+```json
+{
+  "file_id": "uuid",
+  "filename": "large-video.mp4",
+  "size": 524288000,
+  "path": "/Videos/large-video.mp4"
+}
+```
+
+### Cancel upload
+
+```http
+DELETE /api/uploads/{upload_id}
+```
+
+This removes the in-progress session and temporary chunk data.
+
+## Validation Rules
+
+- `filename` is required
+- `total_size` must be greater than zero
+- `chunk_size` must be at least 1 MB when provided
+- Storage quota checks can reject the session before upload starts
+
+## Frontend Behavior
+
+The OxiCloud web UI can switch to chunked uploads for larger files, track aggregate progress, and retry individual chunks without restarting the full transfer.