123 lines
4.6 KiB
Markdown
123 lines
4.6 KiB
Markdown
# FORMAT
|
|
|
|
# Title: External System Adapters
|
|
|
|
# Description:
|
|
|
|
Component Adapter xử lý giao tiếp với các hệ thống bên ngoài. Adapter giúp tách biệt core domain logic khỏi các chi tiết triển khai bên ngoài.
|
|
|
|
## Adapter Categories
|
|
|
|
### Database Adapters
|
|
* **PersistenceAdapter**:
|
|
* **Functionality**: Interface with PostgreSQL database
|
|
* **Location**: `internal/adapter/postgres/`
|
|
* **Key Components**:
|
|
* `connection.go`: Database connection pool management
|
|
* `profile_repo.go`: Repository for Profile aggregate
|
|
* `match_repo.go`: Repository for MatchOutcome aggregate
|
|
* `gift_repo.go`: Repository for Gift and GiftAllocation aggregates
|
|
* `models.go`: Database model definitions
|
|
|
|
### Email Adapters
|
|
* **EmailAdapter**:
|
|
* **Functionality**: Send emails for user registration, match results, and gift notifications
|
|
* **Location**: `internal/adapter/email/`
|
|
* **Key Components**:
|
|
* `client.go`: Client interface to email service
|
|
* `templates.go`: Email templates management
|
|
|
|
### Storage Adapters
|
|
* **FileStorageAdapter**:
|
|
* **Functionality**: Upload and retrieve files (profile photos)
|
|
* **Location**: `internal/adapter/filestorage/`
|
|
* **Key Components**:
|
|
* `s3_client.go`: S3 API client implementation
|
|
* `validation.go`: File validation
|
|
|
|
## Implementation Guidelines
|
|
|
|
* All adapters should implement a standard interface defined in their respective domain
|
|
* Error handling should follow the system-wide error handling strategy
|
|
* Configuration should be loaded from environment variables and config files
|
|
* Connection pooling should be used where appropriate
|
|
* Adapters should be easily replaceable with mock implementations for testing
|
|
|
|
# System Connections
|
|
|
|
## 1. External Connections
|
|
|
|
### 1.1. Database (PostgreSQL)
|
|
* **Purpose:** Lưu trữ các Aggregate nghiệp vụ (Profile, MatchOutcome, Gift, GiftAllocation)
|
|
* **Type:** Relational Database (PostgreSQL)
|
|
* **Connection Details:** DSN qua biến môi trường (`host`, `port`, `user`, `password`, `dbname`)
|
|
* **Authentication:** Credential DB
|
|
* **Adapter Module:** `internal/adapter/postgres/connection.go`
|
|
* **Notes:** Hỗ trợ JSONB cho các trường linh hoạt
|
|
|
|
### 1.2. Email Service
|
|
* **Purpose:** Gửi email xác nhận, kết quả match, thông báo quà tặng
|
|
* **Type:** SMTP/REST
|
|
* **Connection Details:** Cấu hình SMTP server hoặc API endpoint qua env vars
|
|
* **Authentication:** Basic Auth/API Key qua env vars
|
|
* **Adapter Module:** `internal/adapter/email/client.go`
|
|
* **Notes:** Templates tại `internal/adapter/email/templates.go`
|
|
|
|
### 1.3. File Storage (AWS S3)
|
|
* **Purpose:** Lưu trữ ảnh người dùng
|
|
* **Type:** Object Storage (Amazon S3)
|
|
* **Connection Details:** S3 bucket và credentials qua env vars
|
|
* **Authentication:** AWS IAM Role/Access Keys
|
|
* **Adapter Module:** `internal/adapter/filestorage/s3_client.go`
|
|
* **Notes:** Validation logic tại `internal/adapter/filestorage/validation.go`
|
|
|
|
## 2. Internal Connections
|
|
|
|
### 2.1. API Handlers <-> Persistence Adapter
|
|
* **Purpose:** Thao tác dữ liệu nghiệp vụ
|
|
* **Interaction Type:** Direct function calls
|
|
* **Details:** Ví dụ: `handler.profile` gọi các method của `ProfileRepository`
|
|
|
|
### 2.2. Transactions <-> Adapters
|
|
* **UserRegistrationTransaction:** PersistenceAdapter, EmailAdapter, FileStorageAdapter
|
|
* **MatchingTransaction:** PersistenceAdapter
|
|
* **ResultNotificationTransaction:** PersistenceAdapter, EmailAdapter
|
|
* **MatchSelectionTransaction:** PersistenceAdapter
|
|
* **GiftAllocationTransaction:** PersistenceAdapter
|
|
* **GiftNotificationTransaction:** PersistenceAdapter, EmailAdapter
|
|
|
|
# Adapters
|
|
|
|
## 1. Persistence Adapter (PostgreSQL)
|
|
|
|
### Profile Repository
|
|
- `SaveProfile(profile Profile) error`
|
|
- `GetProfileByID(id string) (Profile, error)`
|
|
- `GetProfileByAccessCode(code string) (Profile, error)`
|
|
|
|
### MatchOutcome Repository
|
|
- `SaveMatchOutcome(outcome MatchOutcome) error`
|
|
- `GetMatchOutcomeByProfileID(profileID string) (MatchOutcome, error)`
|
|
- `UpdateMatchOutcomeStatus(id string, status string) error`
|
|
|
|
### Gift Repository
|
|
- `GetActiveGifts() ([]Gift, error)`
|
|
- `GetGiftByID(id string) (Gift, error)`
|
|
|
|
## 2. Email Adapter
|
|
|
|
### Email Client
|
|
- `SendConfirmationEmail(to string, name string, accessCode string) error`
|
|
- `SendMatchResultEmail(to string, profile Profile, matches []Profile) error`
|
|
- `SendGiftNotificationEmail(to string, profile Profile, gift Gift) error`
|
|
|
|
### Email Templates
|
|
- Pre-defined templates for each email type with support for variables
|
|
|
|
## 3. File Storage Adapter (S3)
|
|
|
|
### Photo Storage
|
|
- `UploadPhoto(file []byte, filename string) (string, error)`
|
|
- `GetPhotoURL(reference string) (string, error)`
|
|
- `ValidatePhoto(file []byte) error`
|
|
--- |