Add comments to virtual_* database files

Add human-readable comments explaining each function's purpose,
parameters, and return values for better documentation.

backend/internal/db/virtual_users.go

@@ -1,5 +1,15 @@
+// Package db provides database access for the IMC application.
+// It uses GORM (Go ORM) for database operations.
+
 package db
 
+// =============================================================================
+// VirtualUser - Mail user operations
+// These functions interact with the ISPmail virtual_users table.
+// =============================================================================
+
+// GetAllMailUsers retrieves all mail users from the database.
+// Returns a slice of VirtualUser or an error.
 func (d *DB) GetAllMailUsers() ([]VirtualUser, error) {
 	var users []VirtualUser
 	if err := d.Preload("Domain").Find(&users).Error; err != nil {
@@ -11,6 +21,9 @@ func (d *DB) GetAllMailUsers() ([]VirtualUser, error) {
 	return users, nil
 }
 
+// GetUsersByDomain retrieves all mail users belonging to a specific domain.
+// domainID: the ID of the domain.
+// Returns a slice of VirtualUser or an error.
 func (d *DB) GetUsersByDomain(domainID uint) ([]VirtualUser, error) {
 	var users []VirtualUser
 	if err := d.Where("domain_id = ?", domainID).Find(&users).Error; err != nil {
@@ -22,6 +35,9 @@ func (d *DB) GetUsersByDomain(domainID uint) ([]VirtualUser, error) {
 	return users, nil
 }
 
+// GetUserByID retrieves a single mail user by their ID.
+// id: the user's ID.
+// Returns the VirtualUser or an error (including "record not found").
 func (d *DB) GetUserByID(id uint) (*VirtualUser, error) {
 	var user VirtualUser
 	if err := d.Preload("Domain").First(&user, id).Error; err != nil {
@@ -30,6 +46,9 @@ func (d *DB) GetUserByID(id uint) (*VirtualUser, error) {
 	return &user, nil
 }
 
+// GetUserByEmail looks up a mail user by their email address.
+// email: the full email address (e.g., "user@example.org").
+// Returns the VirtualUser or an error (including "record not found").
 func (d *DB) GetUserByEmail(email string) (*VirtualUser, error) {
 	var user VirtualUser
 	if err := d.Where("email = ?", email).First(&user).Error; err != nil {
@@ -38,6 +57,11 @@ func (d *DB) GetUserByEmail(email string) (*VirtualUser, error) {
 	return &user, nil
 }
 
+// CreateUser creates a new mail user without a domain association.
+// email: the full email address.
+// passwordHash: the bcrypt hash of the user's password.
+// quota: mailbox size limit in bytes (0 = use system default).
+// Returns the created VirtualUser or an error.
 func (d *DB) CreateUser(email, passwordHash string, quota int64) (*VirtualUser, error) {
 	user := VirtualUser{
 		Email:    email,
@@ -50,6 +74,12 @@ func (d *DB) CreateUser(email, passwordHash string, quota int64) (*VirtualUser,
 	return &user, nil
 }
 
+// CreateUserInDomain creates a new mail user in a specific domain.
+// email: the full email address.
+// passwordHash: the bcrypt hash of the user's password.
+// quota: mailbox size limit in bytes (0 = use system default).
+// domainID: the ID of the domain this user belongs to.
+// Returns the created VirtualUser or an error.
 func (d *DB) CreateUserInDomain(email, passwordHash string, quota int64, domainID uint) (*VirtualUser, error) {
 	user := VirtualUser{
 		DomainID: domainID,
@@ -63,14 +93,25 @@ func (d *DB) CreateUserInDomain(email, passwordHash string, quota int64, domainI
 	return &user, nil
 }
 
+// UpdateUserPassword updates the password for a mail user.
+// id: the user's ID.
+// passwordHash: the new bcrypt hash of the password.
+// Returns an error if the update fails.
 func (d *DB) UpdateUserPassword(id uint, passwordHash string) error {
 	return d.Model(&VirtualUser{}).Where("id = ?", id).Update("password", passwordHash).Error
 }
 
+// UpdateUserQuota updates the mailbox quota for a mail user.
+// id: the user's ID.
+// quota: new quota in bytes (0 = use system default).
+// Returns an error if the update fails.
 func (d *DB) UpdateUserQuota(id uint, quota int64) error {
 	return d.Model(&VirtualUser{}).Where("id = ?", id).Update("quota", quota).Error
 }
 
+// DeleteUser permanently removes a mail user from the database.
+// id: the user's ID to delete.
+// Returns an error if the deletion fails.
 func (d *DB) DeleteUser(id uint) error {
 	return d.Delete(&VirtualUser{}, id).Error
 }