pos-system/services/storage-service-net/docs/vi

Storage Service

Microservice .NET 10 để quản lý lưu trữ file hỗ trợ MinIO và Aliyun OSS.

Tính Năng

• Multi-provider Storage: MinIO (tương thích S3) và Aliyun OSS
• Chuyển đổi Provider Runtime: Chuyển đổi giữa MinIO và Aliyun qua biến môi trường
• CRUD File Đầy Đủ: Upload, download, delete, list files
• Pre-signed URLs: URL download/upload an toàn có thời hạn
• Quota User: Giới hạn dung lượng và số file cho mỗi user
• Giao tiếp Inter-service: Xác thực JWT qua IAM Service với caching

Bắt Đầu Nhanh

Yêu Cầu

• .NET 10 SDK
• Docker & Docker Compose
• PostgreSQL (hoặc Neon)
• MinIO (hoặc tài khoản Aliyun OSS)

Chạy với Docker

cd services/storage-service-net
docker-compose up -d

Truy cập: http://localhost:5002/swagger

Chạy Local

cd services/storage-service-net

# Cài đặt dependencies
dotnet restore

# Chạy migrations (lần đầu)
dotnet ef database update --project src/StorageService.Infrastructure --startup-project src/StorageService.API

# Khởi động service
dotnet run --project src/StorageService.API

Cấu Hình

Biến Môi Trường

Biến	Mô tả	Mặc định
Storage__Provider	Chọn provider: minio hoặc aliyun	minio
Storage__DefaultBucket	Tên bucket mặc định	storage
Storage__MaxFileSizeBytes	Kích thước file tối đa	104857600 (100MB)
Storage__PreSignedUrlExpirationSeconds	Thời hạn pre-signed URL	3600

Cấu Hình MinIO

Biến	Mô tả	Mặc định
Storage__MinIO__Endpoint	Endpoint server MinIO	localhost:9000
Storage__MinIO__AccessKey	Access key	-
Storage__MinIO__SecretKey	Secret key	-
Storage__MinIO__UseSSL	Bật SSL	false

Cấu Hình Aliyun OSS

Biến	Mô tả	Mặc định
Storage__AliyunOSS__Endpoint	OSS endpoint	-
Storage__AliyunOSS__AccessKeyId	Access key ID	-
Storage__AliyunOSS__AccessKeySecret	Access key secret	-
Storage__AliyunOSS__Region	OSS region	-

Cấu Hình IAM Service

Biến	Mô tả	Mặc định
IamService__BaseUrl	URL IAM Service	http://localhost:5001
IamService__ServiceName	Định danh service	storage-service
IamService__TimeoutSeconds	Timeout request	30
IamService__CacheDurationSeconds	TTL cache user info	300
IamService__HealthCheckCacheDurationSeconds	TTL cache health check	60

API Endpoints

Files

Method	Endpoint	Mô tả
POST	/api/v1/files/upload	Upload file (tối đa 100MB)
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)

Quota

Method	Endpoint	Mô tả
GET	/api/v1/quota	Lấy quota storage của user hiện tại

Ví Dụ Upload

curl -X POST "http://localhost:5002/api/v1/files/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@document.pdf"

Giao Tiếp Inter-Service

Service giao tiếp với IAM Service để xác thực user:

• Headers: Authorization: Bearer <token>, X-Service-Name: storage-service
• Caching: User info được cache 5 phút
• Resilience: Polly retry (3x) + circuit breaker
• Các phương thức:
  • ValidateUserAsync - Xác thực JWT và lấy thông tin user
  • GetUserRolesAsync - Lấy roles của user
  • HasPermissionAsync - Kiểm tra permission cụ thể

Database Migrations

# Tạo migration mới
dotnet ef migrations add TenMigration \
  --project src/StorageService.Infrastructure \
  --startup-project src/StorageService.API

# Áp dụng migrations
dotnet ef database update \
  --project src/StorageService.Infrastructure \
  --startup-project src/StorageService.API

Testing

# Chạy tất cả tests
dotnet test

# Chạy với coverage
dotnet test --collect:"XPlat Code Coverage"

Cấu Trúc Dự Án

services/storage-service-net/
├── src/
│   ├── StorageService.API/           # Controllers, Commands, Queries
│   ├── StorageService.Domain/        # Entities, Repository interfaces
│   └── StorageService.Infrastructure/# Providers, DbContext, Repositories
├── tests/
│   ├── StorageService.UnitTests/
│   └── StorageService.FunctionalTests/
├── docs/
│   ├── en/                           # Tài liệu tiếng Anh
│   └── vi/                           # Tài liệu tiếng Việt
├── docker-compose.yml
├── Dockerfile
└── README.md

License

MIT