docs: Update IAM Service documentation for new features and architecture

- Revised IAM Service documentation to incorporate recent updates, including the transition to Duende IdentityServer for OAuth2/OpenID Connect. - Added sections for new features such as email verification, 2FA/MFA support, and social login options. - Enhanced clarity by reorganizing API sections and updating the implementation roadmap to reflect completed and planned enhancements.
2026-01-14 13:29:39 +07:00
parent 6a2af6f14c
commit d28ecc158d
1 changed files with 344 additions and 0 deletions
--- a/docs/vi/architecture/storage-proposal.md
+++ b/docs/vi/architecture/storage-proposal.md
@@ -0,0 +1,344 @@
+# Đề Xuất Kiến Trúc Storage Service
+
+Tài liệu này mô tả kiến trúc cho Storage Service, microservice quản lý lưu trữ file với hỗ trợ multi-provider.
+
+## Tổng Quan: Storage Service
+
+**Storage Service** cung cấp:
+- **Multi-provider Storage** - MinIO (S3-compatible) và Aliyun OSS
+- **Direct Client Upload** - Pre-signed URLs để bypass backend (khuyến nghị)
+- **Multipart Upload** - Hỗ trợ files lớn > 100MB
+- **Logical Folder Architecture** - Folder trong DB, flat storage trong bucket
+- **Pre-signed URLs** - Download/Upload URLs có thời hạn với AWS Signature V4
+- **User Quota Management** - Giới hạn dung lượng và số file
+- **Inter-service Communication** - Xác thực JWT qua IAM Service với caching
+- **CQRS Pattern** - MediatR cho Commands/Queries
+- **Clean Architecture** - Domain, Infrastructure, API layers
+
+> [!NOTE]
+> Storage Service đã được triển khai với .NET 10, Clean Architecture tại `services/storage-service-net/`
+
+---
+
+## 1. Phạm Vi Storage Service
+
+### 1.1 File Management (Quản Lý File)
+
+#### A. Upload Operations ✅
+- Direct Client Upload (pre-signed PUT URL) - **Đã triển khai**
+- Proxy Upload qua backend - **Đã triển khai**
+- Multipart Upload cho files lớn - **Đã triển khai**
+- Access Level (Private, Public, Shared) - **Đã triển khai**
+
+#### B. Download Operations ✅
+- Pre-signed Download URLs - **Đã triển khai**
+- Direct URLs cho Public files - **Đã triển khai**
+- AWS Signature V4 security - **Đã triển khai**
+
+#### C. File Lifecycle ✅
+- Soft delete - **Đã triển khai**
+- File metadata management - **Đã triển khai**
+- User ownership validation - **Đã triển khai**
+
+#### D. Folder Management (Planned)
+- 🔄 Logical folder hierarchy
+- 🔄 Folder CRUD operations
+- 🔄 Move files between folders
+
+### 1.2 Storage Infrastructure ✅
+
+#### A. Multi-provider Support
+- ✅ MinIO (S3-compatible) - **Đã triển khai**
+- ✅ Aliyun OSS - **Đã triển khai**
+- ✅ Runtime provider switching - **Đã triển khai**
+
+#### B. Quota Management ✅
+- ✅ Per-user storage limits - **Đã triển khai**
+- ✅ File count limits - **Đã triển khai**
+- ✅ Usage tracking - **Đã triển khai**
+
+### 1.3 Advanced Features (Planned)
+
+#### A. File Sharing
+- 🔄 Share links với expiration
+- 🔄 Permission-based sharing
+- 🔄 Password-protected links
+
+#### B. File Versioning
+- 🔄 Version history
+- 🔄 Rollback support
+- 🔄 Diff between versions
+
+#### C. Search & Discovery
+- 🔄 Full-text search trong metadata
+- 🔄 Tag-based filtering
+- 🔄 Advanced search queries
+
+---
+
+## 2. Kiến Trúc Module Structure (Thực Tế)
+
+```
+services/storage-service-net/
+├── src/
+│   ├── StorageService.API/              # Presentation Layer
+│   │   ├── Controllers/                  # FilesController, SignedUrlController, QuotaController
+│   │   ├── Application/                  # CQRS Commands, Queries, Handlers
+│   │   │   ├── Commands/                 # UploadFile, SignUpload, ConfirmUpload, Delete
+│   │   │   ├── Queries/                  # GetFile, GetFiles, GetDownloadUrl, GetQuota
+│   │   │   └── Validators/               # FluentValidation validators
+│   │   └── Program.cs                    # App entry point
+│   ├── StorageService.Domain/           # Domain Layer
+│   │   ├── AggregatesModel/              # StorageFile, UserStorageQuota
+│   │   ├── Events/                       # FileUploadedEvent, FileDeletedEvent
+│   │   ├── Exceptions/                   # FileNotFoundException, QuotaExceededException
+│   │   └── SeedWork/                     # Entity, IAggregateRoot, IRepository
+│   └── StorageService.Infrastructure/   # Infrastructure Layer
+│       ├── Providers/                    # MinioStorageProvider, AliyunOssStorageProvider
+│       ├── StorageServiceContext.cs      # DbContext
+│       ├── Repositories/                 # FileRepository, QuotaRepository
+│       └── Services/                     # IamServiceClient
+├── tests/
+│   ├── StorageService.UnitTests/
+│   └── StorageService.FunctionalTests/
+├── docs/
+├── Dockerfile
+└── StorageService.slnx
+```
+
+### Sơ Đồ Kiến Trúc Clean Architecture
+
+```mermaid
+graph TD
+    classDef base fill:#202020,stroke:#505050,color:#fff,stroke-width:1px;
+    classDef core fill:#1a237e,stroke:#3949ab,color:#fff,stroke-width:1px;
+    classDef newModule fill:#1b5e20,stroke:#43a047,color:#fff,stroke-width:1px;
+    classDef database fill:#4a148c,stroke:#7b1fa2,color:#fff,stroke-width:1px;
+    classDef storage fill:#b71c1c,stroke:#f44336,color:#fff,stroke-width:1px;
+
+    STORAGE[Storage Service]:::core
+
+    subgraph FileOps [File Operations]
+        direction TB
+        UPLOAD[Upload Handler]:::newModule
+        DOWNLOAD[Download Handler]:::newModule
+        MULTIPART[Multipart Upload]:::newModule
+    end
+
+    subgraph StorageBackend [Storage Backend]
+        direction TB
+        MINIO[MinIO Provider]:::storage
+        OSS[Aliyun OSS Provider]:::storage
+    end
+
+    subgraph DataLayer [Data Layer]
+        direction TB
+        QUOTA[Quota Service]:::newModule
+        FOLDER[Folder Service]:::newModule
+    end
+
+    DB[(PostgreSQL)]:::database
+    IAMSVC[IAM Service]:::core
+
+    STORAGE --> FileOps
+    STORAGE --> DataLayer
+    FileOps --> StorageBackend
+    DataLayer -.-> DB
+    STORAGE --> IAMSVC
+```
+
+---
+
+## 3. Database Schema
+
+### 3.1 Core Tables (Đã Triển Khai)
+
+- **storage_files**: Metadata files (id, file_name, storage_key, content_type, size, access_level, provider)
+- **user_storage_quotas**: Quota per user (max_storage, used_storage, max_files, current_files)
+
+### 3.2 Extended Tables (Planned)
+
+- **folders**: Logical folder hierarchy
+- **file_shares**: Share links và permissions
+- **file_versions**: Version history
+- **multipart_uploads**: Tracking upload sessions
+- **multipart_upload_parts**: Individual parts
+
+---
+
+## 4. API Endpoints (Thực Tế)
+
+### 4.1 Direct Upload APIs ✅ (Khuyến Nghị)
+
+| Method | Endpoint | Mô tả | Auth |
+|--------|----------|-------|------|
+| `POST` | `/api/v1/storage/sign-upload` | Lấy pre-signed PUT URL để upload trực tiếp | ✅ |
+| `POST` | `/api/v1/storage/confirm-upload` | Xác nhận upload và lưu metadata | ✅ |
+
+### 4.2 Legacy Upload APIs ✅ (Proxy)
+
+| Method | Endpoint | Mô tả | Auth |
+|--------|----------|-------|------|
+| `POST` | `/api/v1/files/upload` | Upload file qua backend (tối đa 100MB) | ✅ |
+
+### 4.3 File Management APIs ✅
+
+| Method | Endpoint | Mô tả | Auth |
+|--------|----------|-------|------|
+| `GET` | `/api/v1/files` | Danh sách files với phân trang | ✅ |
+| `GET` | `/api/v1/files/{id}` | Lấy metadata file theo ID | ✅ |
+| `GET` | `/api/v1/files/{id}/download-url` | Lấy pre-signed download URL | ✅ |
+| `DELETE` | `/api/v1/files/{id}` | Xóa file (soft delete) | ✅ |
+
+### 4.4 Quota APIs ✅
+
+| Method | Endpoint | Mô tả | Auth |
+|--------|----------|-------|------|
+| `GET` | `/api/v1/quota` | Lấy quota storage của user hiện tại | ✅ |
+
+### 4.5 Multipart Upload APIs ✅
+
+| Method | Endpoint | Mô tả | Auth |
+|--------|----------|-------|------|
+| `POST` | `/api/v1/files/multipart/initiate` | Khởi tạo upload session | ✅ |
+| `POST` | `/api/v1/files/multipart/upload-part` | Upload 1 chunk | ✅ |
+| `POST` | `/api/v1/files/multipart/complete` | Hoàn thành và merge parts | ✅ |
+| `DELETE` | `/api/v1/files/multipart/abort` | Hủy upload, cleanup | ✅ |
+| `GET` | `/api/v1/files/multipart/{uploadId}` | Kiểm tra tiến độ | ✅ |
+
+### 4.6 Folder APIs (Planned)
+
+> [!NOTE]
+> Các APIs dưới đây là tính năng **đang được lên kế hoạch**, chưa triển khai.
+
+```
+POST   /api/v1/folders              # Tạo folder
+GET    /api/v1/folders              # List folders
+GET    /api/v1/folders/{id}         # Lấy folder info
+PUT    /api/v1/folders/{id}         # Đổi tên folder
+DELETE /api/v1/folders/{id}         # Xóa folder
+GET    /api/v1/folders/{id}/files   # List files trong folder
+POST   /api/v1/files/{id}/move      # Move file giữa folders
+```
+
+### 4.7 File Sharing APIs (Planned)
+
+> [!NOTE]
+> Các APIs dưới đây là tính năng **đang được lên kế hoạch**, chưa triển khai.
+
+```
+POST   /api/v1/files/{id}/share     # Tạo share link
+GET    /api/v1/shares/{token}       # Access shared file
+DELETE /api/v1/shares/{id}          # Revoke share
+```
+
+---
+
+## 5. Implementation Roadmap
+
+### Phase 1: Core Storage ✅ (Completed)
+- ✅ Multi-provider storage (MinIO, Aliyun OSS)
+- ✅ Proxy upload qua backend
+- ✅ Pre-signed download URLs
+- ✅ User quota management
+- ✅ File CRUD operations
+- ✅ Inter-service communication với IAM
+
+### Phase 2: Direct Upload ✅ (Completed)
+- ✅ Pre-signed PUT URLs cho direct upload
+- ✅ Confirm upload flow
+- ✅ Access level support (Private, Public, Shared)
+- ✅ AWS Signature V4 security
+
+### Phase 3: Large File Support ✅ (Completed)
+- ✅ Multipart upload initiation
+- ✅ Part-by-part upload
+- ✅ Upload completion/abort
+- ✅ Progress tracking
+
+### Phase 4: Logical Folders (Planned)
+- 🔄 Folder hierarchy trong database
+- 🔄 Folder CRUD APIs
+- 🔄 Move files giữa folders
+- 🔄 Recursive delete
+
+### Phase 5: File Sharing (Planned)
+- 🔄 Share link generation
+- 🔄 Expiring share links
+- 🔄 Password protection
+- 🔄 Access logging
+
+### Phase 6: File Versioning (Planned)
+- 🔄 Version tracking
+- 🔄 Rollback support
+- 🔄 Retention policies
+
+---
+
+## 6. Kiến Trúc Đặc Biệt
+
+### 6.1 Direct Upload Pattern
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Storage as Storage Service
+    participant MinIO
+
+    Client->>Storage: POST /sign-upload (metadata)
+    Storage->>Storage: Validate JWT, Check Quota
+    Storage-->>Client: Pre-signed PUT URL + ObjectKey
+    Client->>MinIO: PUT file binary (direct)
+    MinIO-->>Client: 200 OK
+    Client->>Storage: POST /confirm-upload (objectKey)
+    Storage->>MinIO: Verify file exists
+    Storage->>Storage: Save metadata, Update quota
+    Storage-->>Client: File metadata
+```
+
+**Lợi ích:**
+- Backend không xử lý file binary → Giảm 90%+ tải
+- Có thể xử lý hàng triệu uploads đồng thời
+- Tốc độ upload nhanh hơn
+
+### 6.2 Logical Folder Architecture
+
+| Layer | Trách nhiệm |
+|-------|-------------|
+| **Database** | Quản lý folder hierarchy, paths, permissions |
+| **Bucket** | Lưu trữ file binary với flat UUID keys |
+
+**Lợi ích:**
+- Rename folder: O(1) - chỉ update DB
+- Move file: O(1) - chỉ update folder_id
+- UUID keys không predictable → Bảo mật cao
+- Dễ migrate storage provider
+
+---
+
+## 7. Lợi Ích
+
+### Cho Developers
+- ✅ Multi-provider abstraction
+- ✅ Clean Architecture
+- ✅ CQRS Pattern với MediatR
+- ✅ Pre-signed URL handling
+
+### Cho End Users
+- ✅ Fast direct uploads
+- ✅ Large file support (multipart)
+- ✅ Clear quota visibility
+- ✅ Secure file access
+
+---
+
+## Kết Luận
+
+Storage Service là một microservice hoàn chỉnh cho file storage với:
+- **Direct Upload Pattern** cho high scalability
+- **Multi-provider Support** (MinIO, Aliyun OSS)
+- **Multipart Upload** cho large files
+- **Logical Folder Architecture** theo Data Sovereignty principles
+- **Pre-signed URLs** với AWS Signature V4 security
+
+Các tính năng tiếp theo (Folders, Sharing, Versioning) sẽ được triển khai trong các phase tới.