Chore/clean up

.env.example

@@ -1,14 +1,24 @@
 APP_NAME=library
 APP_VERSION=0.1.0
 APP_ENV=development
-Port=8080
+
+# Application Port
+# For local development (make run-api): the port your app listens on
+# For Docker (make docker-up): container always listens on 8080 (hardcoded in docker-compose.yml)
+PORT=8080
+
+# Docker Host Port (optional, only used by docker-compose)
+# Maps host port to container port 8080
+# HOST_PORT=8080
 
 DATABASE_URL=postgres://library:secret@localhost:5432/library?sslmode=disable
 POSTGRES_USER=library
 POSTGRES_PASSWORD=secret
 POSTGRES_DB=library
 
-REDIS_URL=redis://localhost:6379
+# ⚠️ For local development (make run-api): use localhost:6380
+# ⚠️ For Docker (make docker-up): IGNORED - hardcoded to redis://redis:6379 in docker-compose.yml
+REDIS_URL=redis://localhost:6380
 
 JWT_SECRET=secret
 ACCESS_TOKEN_EXPIRY=30
@@ -20,6 +30,9 @@ GOOGLE_REDIRECT_URL=http://localhost:8080/api/v1/portal/auth/google/callback
 
 OTP_EXPIRY=1
 
+# Elasticsearch Configuration
+# ⚠️ For local development (make run-api): use localhost:9200
+# ⚠️ For Docker (make docker-up): IGNORED - hardcoded to http://elasticsearch:9200 in docker-compose.yml
 ELASTICSEARCH_URL=http://localhost:9200
 
 REQUEST_TIMEOUT=30s

.github/workflows/ci.yml

@@ -16,11 +16,11 @@ jobs:
 
       - uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version: '1.26'
           cache: true
 
       - name: golangci-lint
-        uses: golangci/golangci-lint-action@v6
+        uses: golangci/golangci-lint-action@v8
         with:
           version: latest
           args: --timeout=5m
@@ -33,7 +33,7 @@ jobs:
 
       - uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version: '1.26'
           cache: true
 
       - name: Download modules
@@ -56,7 +56,7 @@ jobs:
 
       - uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version: '1.26'
           cache: true
 
       - name: Download modules
@@ -76,7 +76,7 @@ jobs:
 
       - uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version: '1.26'
           cache: true
 
       - name: Build all binaries

.gitignore

@@ -29,5 +29,5 @@ go.work.sum
 .env
 
 # Editor/IDE
-# .idea/
+.idea/
 .vscode/

.golangci.yml

@@ -1,45 +1,50 @@
+version: "2"
 run:
   timeout: 5m
-  go: '1.23'
+  go: '1.26'
 
 linters:
   enable:
     - errcheck
-    - gosimple
     - govet
     - ineffassign
     - staticcheck
     - unused
-    - gofmt
     - misspell
     - revive
     - exhaustive
-    - godot
     - noctx
     - bodyclose
-
-linters-settings:
-  godot:
-    all: false
-    exclude:
-      - '^ *@'
-  revive:
+  settings:
+    revive:
+      rules:
+        - name: exported
+          disabled: true
+        - name: package-comments
+          disabled: true
+        - name: redefines-builtin-id
+          severity: warning
+        - name: unexported-return
+          severity: warning
+        - name: blank-imports
+          severity: warning
+    exhaustive:
+      default-signifies-exhaustive: true
+  exclusions:
     rules:
-      - name: exported
-        severity: warning
-      - name: unused-parameter
-        severity: warning
+      - path: _test\.go
+        linters: [errcheck, noctx]
+      - path: tests/
+        linters: [errcheck, noctx, revive]
+      - path: docs/
+        linters: [all]
+      - path: pkg/i18n/fa\.go
+        linters: [staticcheck]
 
-  exhaustive:
-    default-signifies-exhaustive: true
+formatters:
+  enable:
+    - gofmt
 
 issues:
-  exclude-rules:
-    - path: _test\.go
-      linters: [errcheck, gosimple]
-
-    - path: docs/
-      linters: [all]
-
   max-issues-per-linter: 0
   max-same-issues: 0

Dockerfile

@@ -10,7 +10,10 @@ RUN go mod download
 
 COPY . .
 
-RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main ./cmd/api
+ARG VERSION=dev
+RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo \
+    -ldflags "-s -w -X main.Version=${VERSION}" \
+    -o main ./cmd/api
 
 FROM alpine:latest
 

Makefile

@@ -4,13 +4,13 @@ GO_FILES   := $(shell find . -type f -name '*.go' -not -path './vendor/*' -not -
 
 VERSION    := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 LDFLAGS    := -ldflags "-s -w -X main.Version=$(VERSION)"
-
+GO_VERSION=1.26
 .PHONY: help run-api build build-all test test-unit test-integration test-coverage \
         lint fmt vet tidy docker-up docker-down docker-logs docker-psql \
-        migrate migrate-down migrate-version seed update-swagger clean
+        migrate migrate-down migrate-version migrate-force seed update-swagger clean
 
 docker-up:
-	docker compose up -d --build
+	VERSION=$(VERSION) docker compose up -d --build
 
 docker-down:
 	docker compose down
@@ -40,6 +40,11 @@ migrate-down:
 migrate-version:
 	go run ./cmd/migrate -cmd=version
 
+migrate-force:
+	@echo "Forcing migration to version $(VERSION)"
+	@if [ -z "$(VERSION)" ]; then echo "Error: VERSION is required. Usage: make migrate-force VERSION=4"; exit 1; fi
+	go run ./cmd/migrate -cmd=force -version=$(VERSION)
+
 seed:
 	go run ./cmd/seed --email=$(EMAIL) --password=$(PASSWORD) --mobile=$(MOBILE) --national-code=$(NATIONAL_CODE)
 
@@ -115,11 +120,12 @@ help:
 	@echo ""
 	@echo "Database:"
 	@echo "  docker-deps      Start postgres, redis, elasticsearch"
-	@echo "  docker-up        Start all services with docker compose"
+	@echo "  docker-up        Start all services with docker compose (builds with version $(VERSION))"
 	@echo "  docker-down      Stop all services"
 	@echo "  migrate          Run migrations up"
 	@echo "  migrate-down     Run migrations down (1 step)"
 	@echo "  migrate-version  Show migration version"
+	@echo "  migrate-force    Force migration to version (usage: make migrate-force VERSION=4)"
 	@echo "  seed             Seed super admin user"
 	@echo ""
 	@echo "Other:"

README.md

@@ -93,6 +93,7 @@ git clone https://github.com/YOUR_USERNAME/librecore.git
 cd librecore
 
 cp .env.example .env
+# Edit .env if needed (see Configuration section below)
 
 docker compose up -d
 
@@ -104,6 +105,30 @@ make run
 The API will be available at `http://localhost:8080`.
 Swagger UI at `http://localhost:8080/docs`.
 
+### Configuration
+
+The `.env` file contains different connection strings depending on how you run the application:
+
+**For local development (`make run-api`):**
+- Use `localhost` with host-mapped ports
+- Redis: `redis://localhost:6380` (Docker maps 6380→6379)
+- Elasticsearch: `http://localhost:9200`
+
+**For Docker (`make docker-up`):**
+- Environment variables are automatically overridden in `docker-compose.yml`
+- Redis: `redis://redis:6379` (internal Docker network)
+- Elasticsearch: `http://elasticsearch:9200` (internal Docker network)
+
+**For production:**
+- Point to your managed services (AWS ElastiCache, Elastic Cloud, etc.)
+- Set environment variables to override defaults:
+  ```bash
+  export REDIS_URL=redis://your-redis-cluster.amazonaws.com:6379
+  export ELASTICSEARCH_URL=https://your-es-cluster.elastic-cloud.com:9200
+  docker compose up -d
+  ```
+- Or update your production `.env` file directly with external service URLs
+
 ### Makefile Commands
 
 ```bash
@@ -120,21 +145,27 @@ make lint       # run golangci-lint
 The API binary embeds version information at build time using git tags or commit hash:
 
 ```bash
-# Build with version (uses git tag or commit hash)
+# Build locally with version (uses git tag or commit hash)
 make build-api
 
+# Build and run with Docker (automatically injects version)
+make docker-up
+
 # The version is injected at compile time and logged on startup:
-# [library] listening on :8080  env=development  version=1.2.3
+# [library] listening on :8080  env=development  version=e5d4239
 ```
 
-For manual builds without the Makefile:
+For manual builds:
 
 ```bash
-# Build with version from git
+# Local build with version from git
 go build -ldflags "-X main.Version=$(git describe --tags --always --dirty)" -o bin/library ./cmd/api
 
-# Or use a specific version
-go build -ldflags "-X main.Version=1.2.3" -o bin/library ./cmd/api
+# Docker build with specific version
+docker build --build-arg VERSION=1.2.3 -t library-api .
+
+# Docker Compose with custom version
+VERSION=1.2.3 docker compose up -d --build
 ```
 
 ---
@@ -201,7 +232,56 @@ Request → Middleware (auth, logger) → Handler → Service → Repository →
 Each layer has one responsibility and only communicates with the layer directly below it.
 Business rules live exclusively in `service/`. Handlers never touch the database.
 
+---
 
+## Security Considerations & Known Limitations
+
+⚠️ **This project is for educational/portfolio purposes. Before deploying to production, address the following:**
+
+### 🔴 Critical Security Issues
+
+1. **Google OAuth State Parameter (CSRF Vulnerability)**
+   - **Issue**: The `GoogleCallback` handler does not verify the OAuth `state` parameter
+   - **Risk**: Attackers can forge OAuth callbacks and potentially hijack authentication flows
+   - **Fix Required**: Store state in Redis with 5-minute TTL before redirecting to Google, then verify it in the callback:
+   ```go
+   // Before redirect
+   state := generateRandomState()
+   rdb.Set(ctx, "oauth:state:"+state, userID, 5*time.Minute)
+
+   // In callback
+   storedUserID := rdb.Get(ctx, "oauth:state:"+state)
+   if storedUserID == "" {
+       return errors.New("invalid state")
+   }
+   ```
+
+2. **Hardcoded OTP for Password Reset**
+   - **Issue**: Email OTP verification is not implemented; OTPs are logged but not sent
+   - **Risk**: Password reset flow is non-functional in production
+   - **Fix Required**: Integrate a real email service (SendGrid, AWS SES, etc.) in `pkg/mailer`
+
+### 🟡 Data Integrity Limitations
+
+3. **No Soft Deletes**
+   - **Issue**: Deleting customers/employees permanently removes records and orphans borrow history
+   - **Impact**: Historical data is lost; reports become inaccurate
+   - **Recommendation**: Add `deleted_at TIMESTAMPTZ` columns and filter with `WHERE deleted_at IS NULL`
+
+4. **Elasticsearch Sync Has No Recovery**
+   - **Issue**: Book indexing is fire-and-forget; if the API crashes between DB write and ES index, search results become stale
+   - **Impact**: Search index can drift from database state
+   - **Proper Solution**: Implement an outbox pattern with `es_sync_queue` table and background worker
+   - **Current Workaround**: Manually reindex via admin script if drift is detected
+
+### ✅ Already Implemented Correctly
+
+- **Unique Constraint Checking**: Uses pgx error codes (`23505`) instead of fragile string matching
+- **JWT Security**: RS256 with proper key rotation support
+- **SQL Injection Protection**: All queries use parameterized statements
+- **Password Hashing**: bcrypt with cost factor 12
+
+---
 
 ## License
 

cmd/api/backoffice_router.go

@@ -11,7 +11,7 @@ func registerBackofficeRoutes(api *gin.RouterGroup, deps *Dependencies) {
 	{
 		registerAuthRoutes(apiV1BackOffice, deps)
 		apiV1BackOffice.Use(middleware.RequireAuth(deps.AuthService, deps.SessionStore, domain.SubjectTypeEmployee))
-		apiV1BackOffice.Use(middleware.RequireRole(domain.RoleManager))
+		apiV1BackOffice.Use(middleware.RequireRole(domain.RoleManager, domain.RoleSuperAdmin))
 		registerBookRoutes(apiV1BackOffice, deps)
 		registerCustomerRoutes(apiV1BackOffice, deps)
 		registerEmployeeRoutes(apiV1BackOffice, deps)
@@ -84,7 +84,7 @@ func registerBorrowRoutes(api *gin.RouterGroup, deps *Dependencies) {
 		)
 		borrows.POST("", handler.Borrow)
 		borrows.PUT("/:id/return", handler.Return)
-		borrows.GET("/:id/customers/:id", handler.ListByCustomer)
+		borrows.GET("/customers/:id", handler.ListByCustomer)
 	}
 }