feat(docs): update README with correct year for stock API endpoint an…

…d improve formatting

feat(api.http): change example year for stock API endpoint to 2023 and enhance documentation structure
refactor(handlers): move error response struct to models package for better organization and reuse
refactor(handlers): update stock handler functions to use models for stock and purification requests
refactor(middleware): improve year validation middleware to use models for error codes
feat(models): add new models for error responses, stocks, and purification requests
chore(utils): add utility function for safe string conversion to handle different types
style: improve code formatting and add section comments for better readability across files

README.md

@@ -190,7 +190,7 @@ GET {{baseUrl}}/
 Content-Type: {{contentType}}
 
 ### Get Stocks by Year
-GET {{baseUrl}}/api/v1/stocks/year/2025  
+GET {{baseUrl}}/api/v1/stocks/year/2023  
 Content-Type: {{contentType}}
 
 ### Search Stocks with Parameters
@@ -293,8 +293,13 @@ Data source: [Almaqased Cleansing Calculator](https://almaqased.net/cleansing-ca
 │   ├── middleware
 │   │   ├── middleware.go
 │   │   └── year_validator.go
-│   └── routes
-│       └── routes.go
+│   ├── models
+│   │   ├── error.go
+│   │   └── stock.go
+│   ├── routes
+│   │   └── routes.go
+│   └── utils
+│       └── safe.go
 ├── LICENSE
 ├── Makefile
 └── README.md

api.http

@@ -1,7 +1,13 @@
-### Environment Variables
+// ###############################################################################
+// Environment Variables
+// ###############################################################################
 @baseUrl = http://localhost:3000
 @contentType = application/json
 
+// ###############################################################################
+// API Endpoints
+// ###############################################################################
+
 ### Health Check
 GET {{baseUrl}}/api/health
 Content-Type: {{contentType}}
@@ -15,7 +21,7 @@ GET {{baseUrl}}/
 Content-Type: {{contentType}}
 
 ### Get Stocks by Year
-GET {{baseUrl}}/api/v1/stocks/year/2018
+GET {{baseUrl}}/api/v1/stocks/year/2023
 Content-Type: {{contentType}}
 
 ### Search Stocks with Parameters
@@ -33,7 +39,9 @@ Content-Type: {{contentType}}
     "stock_code": "1111"
 }
 
-### Search Examples
+// ###############################################################################
+// Search Examples
+// ###############################################################################
 
 ### Search by Name
 GET {{baseUrl}}/api/v1/stocks/year/2023/search?name=%D8%A3%D8%B1%D8%A7%D9%85%D9%83%D9%88

internal/handlers/errors.go

@@ -1,27 +1,21 @@
 package handlers
 
 import (
+	"github.com/anqorithm/naqa-api/internal/models"
 	"github.com/gofiber/fiber/v2"
 )
 
-type ErrorResponse struct {
-	Status  string      `json:"status"`
-	Code    string      `json:"code"`
-	Message string      `json:"message"`
-	Details interface{} `json:"details,omitempty"`
-}
+// ###############################################################################
+// Error Handling Functions
+// ###############################################################################
 
-func NewErrorResponse(code string, message string, details interface{}) *ErrorResponse {
-	return &ErrorResponse{
+func SendError(c *fiber.Ctx, status int, code string, message string, details interface{}) error {
+	return c.Status(status).JSON(&models.ErrorResponse{
 		Status:  "error",
 		Code:    code,
 		Message: message,
 		Details: details,
-	}
-}
-
-func SendError(c *fiber.Ctx, status int, code string, message string, details interface{}) error {
-	return c.Status(status).JSON(NewErrorResponse(code, message, details))
+	})
 }
 
 // Common error codes

internal/handlers/handlers.go

@@ -19,6 +19,10 @@ func NewHandler(db *mongo.Database) *Handler {
 	}
 }
 
+// ###############################################################################
+// Handler Functions
+// ###############################################################################
+
 // RootHandler handles the "/" endpoint
 func (h *Handler) RootHandler(c *fiber.Ctx) error {
 	return c.JSON(fiber.Map{
@@ -33,18 +37,18 @@ func (h *Handler) RootHandler(c *fiber.Ctx) error {
 
 // ApiV1Handler handles the "/api/v1" endpoint
 func (h *Handler) ApiV1Handler(c *fiber.Ctx) error {
-    return c.JSON(fiber.Map{
-        "status":      "active",
-        "message":     "Welcome to NAQA API v1",
-        "version":     "1.0.0",
-        "env":         os.Getenv("APP_ENV"),
-        "server_time": time.Now().Format(time.RFC3339),
-        "request_id":  c.Get("X-Request-ID", uuid.New().String()),
-        "endpoints": []string{
-            "/api/v1/stocks",
-            "/api/v1/health",
-        },
-    })
+	return c.JSON(fiber.Map{
+		"status":      "active",
+		"message":     "Welcome to NAQA API v1",
+		"version":     "1.0.0",
+		"env":         os.Getenv("APP_ENV"),
+		"server_time": time.Now().Format(time.RFC3339),
+		"request_id":  c.Get("X-Request-ID", uuid.New().String()),
+		"endpoints": []string{
+			"/api/v1/stocks",
+			"/api/v1/health",
+		},
+	})
 }
 
 // HealthCheckHandler handles the health check endpoint