FEATURE (cursor): Update cursor rules

Author: RostislavDugin

backend/.cursor/rules/codestyle-rule.mdc

@@ -1,14 +1,152 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
+
 Always place private methods to the bottom of file
 
-Code should look like:
+**This rule applies to ALL Go files including tests, services, controllers, repositories, etc.**
+
+In Go, exported (public) functions/methods start with uppercase letters, while unexported (private) ones start with lowercase letters.
+
+## Structure Order:
+
+1. Type definitions and constants
+2. Public methods/functions (uppercase)
+3. Private methods/functions (lowercase)
+
+## Examples:
+
+### Service with methods:
+
+```go
+type UserService struct {
+    repository *UserRepository
+}
+
+// Public methods first
+func (s *UserService) CreateUser(user *User) error {
+    if err := s.validateUser(user); err != nil {
+        return err
+    }
+    return s.repository.Save(user)
+}
+
+func (s *UserService) GetUser(id uuid.UUID) (*User, error) {
+    return s.repository.FindByID(id)
+}
+
+// Private methods at the bottom
+func (s *UserService) validateUser(user *User) error {
+    if user.Name == "" {
+        return errors.New("name is required")
+    }
+    return nil
+}
+```
+
+### Package-level functions:
+
+```go
+package utils
+
+// Public functions first
+func ProcessData(data []byte) (Result, error) {
+    cleaned := sanitizeInput(data)
+    return parseData(cleaned)
+}
+
+func ValidateInput(input string) bool {
+    return isValidFormat(input) && checkLength(input)
+}
+
+// Private functions at the bottom
+func sanitizeInput(data []byte) []byte {
+    // implementation
+}
+
+func parseData(data []byte) (Result, error) {
+    // implementation
+}
+
+func isValidFormat(input string) bool {
+    // implementation
+}
+
+func checkLength(input string) bool {
+    // implementation
+}
+```
+
+### Test files:
+
+```go
+package user_test
+
+// Public test functions first
+func Test_CreateUser_ValidInput_UserCreated(t *testing.T) {
+    user := createTestUser()
+    result, err := service.CreateUser(user)
+
+    assert.NoError(t, err)
+    assert.NotNil(t, result)
+}
+
+func Test_GetUser_ExistingUser_ReturnsUser(t *testing.T) {
+    user := createTestUser()
+    // test implementation
+}
+
+// Private helper functions at the bottom
+func createTestUser() *User {
+    return &User{
+        Name:  "Test User",
+        Email: "[email protected]",
+    }
+}
+
+func setupTestDatabase() *Database {
+    // setup implementation
+}
+```
+
+### Controller example:
+
+```go
+type ProjectController struct {
+    service *ProjectService
+}
+
+// Public HTTP handlers first
+func (c *ProjectController) CreateProject(ctx *gin.Context) {
+    var request CreateProjectRequest
+    if err := ctx.ShouldBindJSON(&request); err != nil {
+        c.handleError(ctx, err)
+        return
+    }
+    // handler logic
+}
+
+func (c *ProjectController) GetProject(ctx *gin.Context) {
+    projectID := c.extractProjectID(ctx)
+    // handler logic
+}
+
+// Private helper methods at the bottom
+func (c *ProjectController) handleError(ctx *gin.Context, err error) {
+    ctx.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+}
+
+func (c *ProjectController) extractProjectID(ctx *gin.Context) uuid.UUID {
+    return uuid.MustParse(ctx.Param("projectId"))
+}
+```
 
-type SomeService struct {
-    func PublicMethod(...) ...
+## Key Points:
 
-    func privateMethod(...) ...
-}
+- **Exported/Public** = starts with uppercase letter (CreateUser, GetProject)
+- **Unexported/Private** = starts with lowercase letter (validateUser, handleError)
+- This improves code readability by showing the public API first
+- Private helpers are implementation details, so they go at the bottom
+- Apply this rule consistently across ALL Go files in the project

backend/.cursor/rules/comments.mdc

@@ -1,7 +1,45 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
-Do not write obvious comments.
-Write meaningful code, give meaningful names
+
+## Comment Guidelines
+
+1. **No obvious comments** - Don't state what the code already clearly shows
+2. **Functions and variables should have meaningful names** - Code should be self-documenting
+3. **Comments for unclear code only** - Only add comments when code logic isn't immediately clear
+
+## Key Principles:
+
+- **Code should tell a story** - Use descriptive variable and function names
+- **Comments explain WHY, not WHAT** - The code shows what happens, comments explain business logic or complex decisions
+- **Prefer refactoring over commenting** - If code needs explaining, consider making it clearer instead
+- **API documentation is required** - Swagger comments for all HTTP endpoints are mandatory
+- **Complex algorithms deserve comments** - Mathematical formulas, business rules, or non-obvious optimizations
+
+Example of useless comment:
+
+1.
+
+```sql
+// Create projects table
+CREATE TABLE projects (
+    id                    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name                  TEXT NOT NULL,
+    created_at            TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+```
+
+2.
+
+```go
+// Create test project
+project := CreateTestProject(projectName, user, router)
+```
+
+3.
+
+```go
+// CreateValidLogItems creates valid log items for testing
+func CreateValidLogItems(count int, uniqueID string) []logs_receiving.LogItemRequestDTO {
+```

backend/.cursor/rules/controllers-rule.mdc

@@ -14,42 +14,114 @@ func (c *TasksController) GetAvailableTasks(ctx *gin.Context) ...
 
 3. We document all routes with Swagger in the following format:
 
-// SignIn
-// @Summary Authenticate a user
-// @Description Authenticate a user with email and password
-// @Tags users
+package audit_logs
+
+import (
+	"net/http"
+
+	user_models "logbull/internal/features/users/models"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+type AuditLogController struct {
+	auditLogService *AuditLogService
+}
+
+func (c *AuditLogController) RegisterRoutes(router *gin.RouterGroup) {
+	// All audit log endpoints require authentication (handled in main.go)
+	auditRoutes := router.Group("/audit-logs")
+
+	auditRoutes.GET("/global", c.GetGlobalAuditLogs)
+	auditRoutes.GET("/users/:userId", c.GetUserAuditLogs)
+}
+
+// GetGlobalAuditLogs
+// @Summary Get global audit logs (ADMIN only)
+// @Description Retrieve all audit logs across the system
+// @Tags audit-logs
 // @Accept json
 // @Produce json
-// @Param request body SignInRequest true "User signin data"
-// @Success 200 {object} SignInResponse
-// @Failure 400
-// @Router /users/signin [post]
+// @Security BearerAuth
+// @Param limit query int false "Limit number of results" default(100)
+// @Param offset query int false "Offset for pagination" default(0)
+// @Param beforeDate query string false "Filter logs created before this date (RFC3339 format)" format(date-time)
+// @Success 200 {object} GetAuditLogsResponse
+// @Failure 401 {object} map[string]string
+// @Failure 403 {object} map[string]string
+// @Router /audit-logs/global [get]
+func (c *AuditLogController) GetGlobalAuditLogs(ctx *gin.Context) {
+	user, isOk := ctx.MustGet("user").(*user_models.User)
+	if !isOk {
+		ctx.JSON(http.StatusInternalServerError, gin.H{"error": "Invalid user type in context"})
+		return
+	}
 
-Do not forget to write docs.
-You can avoid description if it is useless.
-Specify particular acceping \ producing models
+	request := &GetAuditLogsRequest{}
+	if err := ctx.ShouldBindQuery(request); err != nil {
+		ctx.JSON(http.StatusBadRequest, gin.H{"error": "Invalid query parameters"})
+		return
+	}
 
-4. All controllers should have RegisterRoutes method which receives
-RouterGroup (always put this routes on the top of file under controller definition)
+	response, err := c.auditLogService.GetGlobalAuditLogs(user, request)
+	if err != nil {
+		if err.Error() == "only administrators can view global audit logs" {
+			ctx.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+			return
+		}
+		ctx.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to retrieve audit logs"})
+		return
+	}
 
-Example:
-
-func (c *OrderController) RegisterRoutes(router *gin.RouterGroup) {
-	router.POST("/bots/users/orders/generate", c.GenerateOrder)
-	router.POST("/bots/users/orders/generate-by-admin", c.GenerateOrderByAdmin)
-	router.GET("/bots/users/orders/mark-as-paid-by-admin", c.MarkOrderAsPaidByAdmin)
-	router.GET("/bots/users/orders/payments-by-bot", c.GetOrderPaymentsByBot)
-	router.GET("/bots/users/orders/payments-by-user", c.GetOrderPaymentsByUser)
-	router.GET("/bots/users/orders/orders-by-user-for-admin", c.GetOrdersByUserForAdmin)
-	router.POST("/bots/users/orders/orders-by-user-for-user", c.GetOrdersByUserForUser)
-	router.POST("/bots/users/orders/order", c.GetOrder)
-	router.POST("/bots/users/orders/cancel-subscription-by-user", c.CancelSubscriptionByUser)
-	router.GET("/bots/users/orders/cancel-subscription-by-admin", c.CancelSubscriptionByAdmin)
-	router.GET(
-		"/bots/users/orders/cancel-subscriptions-by-payment-option",
-		c.CancelSubscriptionsByPaymentOption,
-	)
+	ctx.JSON(http.StatusOK, response)
 }
 
-5. Check that use use valid .Query("param") and .Param("param") methods.
-If route does not have param - use .Query("query")
+// GetUserAuditLogs
+// @Summary Get user audit logs
+// @Description Retrieve audit logs for a specific user
+// @Tags audit-logs
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param userId path string true "User ID"
+// @Param limit query int false "Limit number of results" default(100)
+// @Param offset query int false "Offset for pagination" default(0)
+// @Param beforeDate query string false "Filter logs created before this date (RFC3339 format)" format(date-time)
+// @Success 200 {object} GetAuditLogsResponse
+// @Failure 400 {object} map[string]string
+// @Failure 401 {object} map[string]string
+// @Failure 403 {object} map[string]string
+// @Router /audit-logs/users/{userId} [get]
+func (c *AuditLogController) GetUserAuditLogs(ctx *gin.Context) {
+	user, isOk := ctx.MustGet("user").(*user_models.User)
+	if !isOk {
+		ctx.JSON(http.StatusInternalServerError, gin.H{"error": "Invalid user type in context"})
+		return
+	}
+
+	userIDStr := ctx.Param("userId")
+	targetUserID, err := uuid.Parse(userIDStr)
+	if err != nil {
+		ctx.JSON(http.StatusBadRequest, gin.H{"error": "Invalid user ID"})
+		return
+	}
+
+	request := &GetAuditLogsRequest{}
+	if err := ctx.ShouldBindQuery(request); err != nil {
+		ctx.JSON(http.StatusBadRequest, gin.H{"error": "Invalid query parameters"})
+		return
+	}
+
+	response, err := c.auditLogService.GetUserAuditLogs(targetUserID, user, request)
+	if err != nil {
+		if err.Error() == "insufficient permissions to view user audit logs" {
+			ctx.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+			return
+		}
+		ctx.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to retrieve audit logs"})
+		return
+	}
+
+	ctx.JSON(http.StatusOK, response)
+}