feature/conluz-122 to main (#123)

* [conluz-122] Initialized claude file

* [conluz-122] Implemented new endpoint to get a user by id

Author: viktorKhan

CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Conluz is an energy community management application built with Spring Boot 3. It manages community members, supply points, consumption data, production metrics from energy plants, and electricity prices. The application is API-driven with JWT authentication, uses PostgreSQL for relational data and InfluxDB for time-series data.
+
+## Development Commands
+
+### Build and Run
+```bash
+./gradlew build                 # Build the project
+./gradlew bootRun               # Run the application (accessible at https://localhost:8443)
+./gradlew clean build --info    # Clean build with detailed output
+```
+
+### Testing
+```bash
+./gradlew test                  # Run all tests (uses JUnit 5)
+./gradlew test --tests ClassName  # Run a specific test class
+```
+
+Tests use Testcontainers for PostgreSQL and InfluxDB integration tests.
+
+### Docker Deployment
+```bash
+# From project root:
+docker build -t conluz:1.0 -f Dockerfile .
+cd deploy
+docker compose up -d            # Start all services
+docker compose up -d postgres   # Start only PostgreSQL
+docker compose up -d influxdb   # Start only InfluxDB
+docker stop conluz              # Stop the app
+```
+
+## Architecture
+
+### Package Structure
+
+The codebase follows **Hexagonal Architecture** (Ports and Adapters):
+
+- **`domain/`**: Core business logic, pure Java classes
+  - `admin/`: User, supply point, and plant management
+  - `consumption/`: Consumption data from Datadis and other sources
+  - `production/`: Production data from Huawei inverters and other sources
+  - `price/`: Electricity price data management
+  - `shared/`: Domain-level shared utilities
+
+- **`infrastructure/`**: Adapters for external systems
+  - Controllers (REST endpoints)
+  - Repositories (JPA/InfluxDB implementations)
+  - External integrations (Datadis, Huawei, Shelly)
+  - `shared/`: Infrastructure-level shared components (security, DB config, jobs, i18n, etc.)
+
+### Key Components
+
+- **Authentication**: JWT-based with HMAC-SHA256, tokens contain user ID, role, expiration
+- **Controllers**: REST endpoints in `infrastructure/*/` packages, documented with OpenAPI/Swagger
+- **Services**: Business logic in `domain/*/` packages (e.g., `*Service.java`)
+- **Repositories**: Interfaces in `domain/`, implementations in `infrastructure/`
+- **Database Migrations**: Liquibase changesets in `src/main/resources/db/liquibase/`
+- **Scheduled Jobs**: Quartz-based scheduled tasks enabled via `@EnableScheduling`
+
+### Data Storage
+
+1. **PostgreSQL**: Users, supplies, configuration (managed via Liquibase migrations)
+2. **InfluxDB**: Time-series data for consumption, production, and prices with retention policies (1 month, 1 year, forever)
+
+## Configuration
+
+### Required Environment Variables
+
+- `CONLUZ_JWT_SECRET_KEY`: JWT secret key (≥256 bits, HMAC-SHA compatible). Generate using `org.lucoenergia.conluz.infrastructure.shared.security.JwtSecretKeyGenerator`
+- `SPRING_DATASOURCE_URL`: PostgreSQL connection (default: `jdbc:postgresql://localhost:5432/conluz_db`)
+
+### Database Setup
+
+For new installations, use `deploy/docker-compose.yaml`. For existing databases:
+
+**PostgreSQL:**
+```sql
+CREATE DATABASE conluz_db;
+CREATE DATABASE conluz_db_test;
+CREATE USER luz WITH PASSWORD 'blank';
+GRANT ALL PRIVILEGES ON DATABASE conluz_db TO luz;
+GRANT ALL PRIVILEGES ON DATABASE conluz_db_test TO luz;
+```
+
+**InfluxDB:**
+```sql
+CREATE DATABASE conluz_db
+CREATE USER luz WITH PASSWORD 'blank'
+GRANT ALL ON conluz_db TO luz
+CREATE RETENTION POLICY one_month ON conluz_db DURATION 30d REPLICATION 1
+CREATE RETENTION POLICY one_year ON conluz_db DURATION 365d REPLICATION 1
+CREATE RETENTION POLICY forever ON conluz_db DURATION INF REPLICATION 1 DEFAULT
+```
+
+## API Documentation
+
+With the app running:
+- OpenAPI spec: https://localhost:8443/api-docs
+- Swagger UI: https://localhost:8443/api-docs/swagger-ui/index.html
+
+## Git Workflow
+
+- Main branch: `main`
+- Feature branches: `feature/conluz-XXX` (where XXX is the issue number)
+- Commit format: `[conluz-XXX] Your commit message`
+- Merge strategy: Squash and merge to main
+- Direct pushes to `main` are not allowed
+
+## Code Standards
+
+- Follow Clean Code principles
+- Code and comments must be in English
+- Code should be self-explanatory with comments when additional explanation is needed
+- All new code must have automated tests
+- Architecture tests are enforced via ArchUnit (see `src/test/java/org/lucoenergia/conluz/architecture/`)

src/main/java/org/lucoenergia/conluz/domain/admin/user/get/GetUserService.java

@@ -1,10 +1,13 @@
 package org.lucoenergia.conluz.domain.admin.user.get;
 
 import org.lucoenergia.conluz.domain.admin.user.User;
+import org.lucoenergia.conluz.domain.shared.UserId;
 import org.lucoenergia.conluz.domain.shared.pagination.PagedRequest;
 import org.lucoenergia.conluz.domain.shared.pagination.PagedResult;
 
 public interface GetUserService {
 
     PagedResult<User> findAll(PagedRequest pagedRequest);
+
+    User findById(UserId id);
 }

src/main/java/org/lucoenergia/conluz/infrastructure/admin/supply/create/CreateSupplyBody.java

@@ -2,6 +2,7 @@
 
 import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
 import jakarta.validation.constraints.Positive;
 import org.lucoenergia.conluz.domain.admin.supply.Supply;
 import org.lucoenergia.conluz.domain.admin.user.User;
@@ -19,6 +20,7 @@ public class CreateSupplyBody {
     private String address;
     @NotEmpty
     private String addressRef;
+    @NotNull
     @Positive
     private Float partitionCoefficient;
     private String name;

src/main/java/org/lucoenergia/conluz/infrastructure/admin/user/UserExceptionHandler.java

@@ -55,6 +55,6 @@ public ResponseEntity<RestError> handleException(UserNotFoundException e) {
                 List.of(e.getId()).toArray(),
                 LocaleContextHolder.getLocale()
         );
-        return errorBuilder.build(message, HttpStatus.BAD_REQUEST);
+        return errorBuilder.build(message, HttpStatus.NOT_FOUND);
     }
 }

src/main/java/org/lucoenergia/conluz/infrastructure/admin/user/get/GetUserByIdController.java

@@ -0,0 +1,69 @@
+package org.lucoenergia.conluz.infrastructure.admin.user.get;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import org.lucoenergia.conluz.domain.admin.user.User;
+import org.lucoenergia.conluz.domain.admin.user.get.GetUserService;
+import org.lucoenergia.conluz.domain.shared.UserId;
+import org.lucoenergia.conluz.infrastructure.admin.user.UserResponse;
+import org.lucoenergia.conluz.infrastructure.shared.web.apidocs.ApiTag;
+import org.lucoenergia.conluz.infrastructure.shared.web.apidocs.response.BadRequestErrorResponse;
+import org.lucoenergia.conluz.infrastructure.shared.web.apidocs.response.ForbiddenErrorResponse;
+import org.lucoenergia.conluz.infrastructure.shared.web.apidocs.response.InternalServerErrorResponse;
+import org.lucoenergia.conluz.infrastructure.shared.web.apidocs.response.NotFoundErrorResponse;
+import org.lucoenergia.conluz.infrastructure.shared.web.apidocs.response.UnauthorizedErrorResponse;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.UUID;
+
+/**
+ * Get user by ID
+ */
+@RestController
+@RequestMapping(value = "/api/v1/users")
+public class GetUserByIdController {
+
+    private final GetUserService service;
+
+    public GetUserByIdController(GetUserService service) {
+        this.service = service;
+    }
+
+    @GetMapping("/{id}")
+    @Operation(
+            summary = "Retrieves a single user by ID",
+            description = """
+                    This endpoint retrieves detailed information about a specific user by their unique identifier.
+
+                    **Required Role: ADMIN**
+
+                    Authentication is required using a Bearer token.
+                    """,
+            tags = ApiTag.USERS,
+            operationId = "getUserById",
+            security = @SecurityRequirement(name = "bearerToken", scopes = {"ADMIN"})
+    )
+    @ApiResponses(value = {
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "User found and returned successfully",
+                    useReturnTypeSchema = true
+            )
+    })
+    @ForbiddenErrorResponse
+    @UnauthorizedErrorResponse
+    @BadRequestErrorResponse
+    @NotFoundErrorResponse
+    @InternalServerErrorResponse
+    @PreAuthorize("hasRole('ADMIN')")
+    public UserResponse getUserById(@PathVariable("id") UUID userId) {
+        User user = service.findById(UserId.of(userId));
+        return new UserResponse(user);
+    }
+}

src/main/java/org/lucoenergia/conluz/infrastructure/admin/user/get/GetUserServiceImpl.java

@@ -1,8 +1,10 @@
 package org.lucoenergia.conluz.infrastructure.admin.user.get;
 
 import org.lucoenergia.conluz.domain.admin.user.User;
+import org.lucoenergia.conluz.domain.admin.user.UserNotFoundException;
 import org.lucoenergia.conluz.domain.admin.user.get.GetUserRepository;
 import org.lucoenergia.conluz.domain.admin.user.get.GetUserService;
+import org.lucoenergia.conluz.domain.shared.UserId;
 import org.lucoenergia.conluz.domain.shared.pagination.Direction;
 import org.lucoenergia.conluz.domain.shared.pagination.Order;
 import org.lucoenergia.conluz.domain.shared.pagination.PagedRequest;
@@ -20,6 +22,7 @@ public GetUserServiceImpl(GetUserRepository getUserRepository) {
         this.getUserRepository = getUserRepository;
     }
 
+    @Override
     public PagedResult<User> findAll(PagedRequest pagedRequest) {
 
         // If not sorting is provided, sort by descendant order by default
@@ -30,4 +33,10 @@ public PagedResult<User> findAll(PagedRequest pagedRequest) {
 
         return getUserRepository.findAll(pagedRequest);
     }
+
+    @Override
+    public User findById(UserId id) {
+        return getUserRepository.findById(id)
+                .orElseThrow(() -> new UserNotFoundException(id));
+    }
 }

src/test/java/org/lucoenergia/conluz/infrastructure/admin/supply/create/CreateSupplyControllerTest.java

@@ -166,6 +166,10 @@ void testWithDuplicatedSupply() throws Exception {
     @MethodSource("getBodyWithMissingRequiredFields")
     void testMissingRequiredFields(String body) throws Exception {
 
+        User user = UserMother.randomUser();
+        user.setPersonalId("54889216G");
+        createUserRepository.create(user);
+
         String authHeader = loginAsDefaultAdmin();
 
         mockMvc.perform(post(URL)

src/test/java/org/lucoenergia/conluz/infrastructure/admin/user/delete/DeleteUserControllerTest.java

@@ -59,9 +59,9 @@ void testWithUnknownUser() throws Exception {
                         .header(HttpHeaders.AUTHORIZATION, authHeader)
                         .contentType(MediaType.APPLICATION_JSON))
                 .andDo(print())
-                .andExpect(status().isBadRequest())
+                .andExpect(status().isNotFound())
                 .andExpect(jsonPath("$.timestamp").isNotEmpty())
-                .andExpect(jsonPath("$.status").value(HttpStatus.BAD_REQUEST.value()))
+                .andExpect(jsonPath("$.status").value(HttpStatus.NOT_FOUND.value()))
                 .andExpect(jsonPath("$.message").isNotEmpty())
                 .andExpect(jsonPath("$.traceId").isNotEmpty());
     }

src/test/java/org/lucoenergia/conluz/infrastructure/admin/user/disable/DisableUserControllerTest.java

@@ -60,9 +60,9 @@ void testWithUnknownUser() throws Exception {
                         .header(HttpHeaders.AUTHORIZATION, authHeader)
                         .contentType(MediaType.APPLICATION_JSON))
                 .andDo(print())
-                .andExpect(status().isBadRequest())
+                .andExpect(status().isNotFound())
                 .andExpect(jsonPath("$.timestamp").isNotEmpty())
-                .andExpect(jsonPath("$.status").value(HttpStatus.BAD_REQUEST.value()))
+                .andExpect(jsonPath("$.status").value(HttpStatus.NOT_FOUND.value()))
                 .andExpect(jsonPath("$.message").isNotEmpty())
                 .andExpect(jsonPath("$.traceId").isNotEmpty());
     }

src/test/java/org/lucoenergia/conluz/infrastructure/admin/user/enable/EnableUserControllerTest.java

@@ -59,9 +59,9 @@ void testWithUnknownUser() throws Exception {
                         .header(HttpHeaders.AUTHORIZATION, authHeader)
                         .contentType(MediaType.APPLICATION_JSON))
                 .andDo(print())
-                .andExpect(status().isBadRequest())
+                .andExpect(status().isNotFound())
                 .andExpect(jsonPath("$.timestamp").isNotEmpty())
-                .andExpect(jsonPath("$.status").value(HttpStatus.BAD_REQUEST.value()))
+                .andExpect(jsonPath("$.status").value(HttpStatus.NOT_FOUND.value()))
                 .andExpect(jsonPath("$.message").isNotEmpty())
                 .andExpect(jsonPath("$.traceId").isNotEmpty());
     }