Cursor rule

1---
2globs: *.go,go.mod,go.sum
3description: Golang backend development patterns and conventions for POS System
4---
5 
6# Backend Development Guidelines (Golang)
7 
8## Code Organization
9 
10### Package Structure
11Follow the [backend/internal/](mdc:backend/internal/) package layout:
12- `models/` - Data structures and DTOs
13- `handlers/` - HTTP request handlers  
14- `middleware/` - HTTP middleware functions
15- `database/` - Database connection and utilities
16- `api/` - Route definitions and setup
17- `utils/` - Shared utility functions
18 
19### Handler Pattern
20All handlers follow the pattern in [handlers/orders.go](mdc:backend/internal/handlers/orders.go):
21 
22```go
23type OrderHandler struct {
24    db *sql.DB
25}
26 
27func NewOrderHandler(db *sql.DB) *OrderHandler {
28    return &OrderHandler{db: db}
29}
30 
31func (h *OrderHandler) GetOrders(c *gin.Context) {
32    // Implementation
33}
34```
35 
36## Database Operations
37 
38### Raw SQL Usage
39- Use parameterized queries to prevent SQL injection
40- Follow the patterns in [handlers/orders.go](mdc:backend/internal/handlers/orders.go) for database operations
41- Always handle `sql.ErrNoRows` explicitly
42- Use transactions for multi-table operations
43 
44### Example Query Pattern:
45```go
46func (h *Handler) getRecord(id uuid.UUID) (*Model, error) {
47    var record Model
48    query := `SELECT id, field1, field2 FROM table WHERE id = $1`
49    
50    err := h.db.QueryRow(query, id).Scan(&record.ID, &record.Field1, &record.Field2)
51    if err == sql.ErrNoRows {
52        return nil, fmt.Errorf("record not found")
53    }
54    if err != nil {
55        return nil, fmt.Errorf("database error: %w", err)
56    }
57    
58    return &record, nil
59}
60```
61 
62## Authentication & Security
63 
64### JWT Middleware
65Use the authentication middleware from [middleware/auth.go](mdc:backend/internal/middleware/auth.go):
66- Protected routes must use `authMiddleware`
67- Role-based access with `RequireRoles([]string{"admin", "manager"})`
68- Extract user info with `GetUserFromContext(c)`
69 
70### Error Handling
71Follow the API response pattern from [models/models.go](mdc:backend/internal/models/models.go):
72 
73```go
74c.JSON(http.StatusBadRequest, models.APIResponse{
75    Success: false,
76    Message: "User-friendly error message",
77    Error:   stringPtr("error_code"),
78})
79```
80 
81## API Endpoints
82 
83### RESTful Design
84Follow REST conventions as shown in [api/routes.go](mdc:backend/internal/api/routes.go):
85- `GET /api/v1/orders` - List resources
86- `POST /api/v1/orders` - Create resource  
87- `GET /api/v1/orders/:id` - Get single resource
88- `PUT /api/v1/orders/:id` - Update entire resource
89- `PATCH /api/v1/orders/:id/status` - Partial update
90- `DELETE /api/v1/orders/:id` - Delete resource
91 
92### Response Format
93All API responses use the standard format from [models/models.go](mdc:backend/internal/models/models.go):
94 
95```go
96type APIResponse struct {
97    Success bool        `json:"success"`
98    Message string      `json:"message"`
99    Data    interface{} `json:"data,omitempty"`
100    Error   *string     `json:"error,omitempty"`
101}
102```
103 
104## Performance Best Practices
105 
106### Database Connections
107- Use connection pooling as configured in [database/connection.go](mdc:backend/internal/database/connection.go)
108- Set appropriate connection limits and timeouts
109- Always close rows and statements
110 
111### Query Optimization
112- Use indexes for frequently queried columns (see [database/init/01_schema.sql](mdc:database/init/01_schema.sql))
113- Avoid N+1 queries by using JOINs or batch loading
114- Implement pagination for large result sets
115 
116## Error Handling
117 
118### Database Errors
119- Always wrap database errors with context
120- Handle connection errors gracefully
121- Use the `IsConnectionError` helper from [database/connection.go](mdc:backend/internal/database/connection.go)
122 
123### HTTP Errors
124- Return appropriate HTTP status codes
125- Provide clear, actionable error messages
126- Don't expose internal system details to clients
127 
128## Testing Guidelines
129 
130### Unit Tests
131- Test handlers with mock database connections
132- Test middleware functions independently
133- Focus on business logic and edge cases
134 
135### Integration Tests
136- Test complete API endpoints
137- Use test database with proper cleanup
138- Test authentication and authorization flows
139 
140## Logging
141 
142### Structured Logging
143- Use Gin's built-in logging middleware
144- Log important business events (orders created, payments processed)
145- Include request IDs for tracing
146- Don't log sensitive information (passwords, tokens)