create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/domain/Team.java

@@ -0,0 +1,64 @@
+package com.example.springsvc.domain;
+
+import jakarta.persistence.CollectionTable;
+import jakarta.persistence.Column;
+import jakarta.persistence.ElementCollection;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.Table;
+
+import java.util.LinkedHashSet;
+import java.util.Set;
+import java.util.UUID;
+
+@Entity
+@Table(name = "teams")
+public class Team {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    private UUID id;
+
+    @Column(nullable = false)
+    private String name;
+
+    // team_members (team_id, user_id) — dedupe bằng Set (contract: memberIds uuid[])
+    @ElementCollection
+    @CollectionTable(name = "team_members", joinColumns = @JoinColumn(name = "team_id"))
+    @Column(name = "user_id", nullable = false)
+    private Set<UUID> memberIds = new LinkedHashSet<>();
+
+    public Team() {
+    }
+
+    public Team(String name) {
+        this.name = name;
+    }
+
+    public UUID getId() {
+        return id;
+    }
+
+    public void setId(UUID id) {
+        this.id = id;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    public Set<UUID> getMemberIds() {
+        return memberIds;
+    }
+
+    public void setMemberIds(Set<UUID> memberIds) {
+        this.memberIds = memberIds;
+    }
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/domain/TeamRepository.java

@@ -0,0 +1,34 @@
+package com.example.springsvc.domain;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.UUID;
+
+public interface TeamRepository extends JpaRepository<Team, UUID> {
+
+    /**
+     * Insert team_members TỪNG DÒNG — mỗi lần gọi là 1 lệnh ghi riêng trong
+     * transaction của TeamService (demo @Transactional N-step, Situation A).
+     * Gọi SAU khi team row đã flush (FK team_members → teams).
+     */
+    @Modifying
+    @Query(value = "INSERT INTO team_members (team_id, user_id) VALUES (:teamId, :userId)",
+            nativeQuery = true)
+    int insertMember(@Param("teamId") UUID teamId, @Param("userId") UUID userId);
+
+    // Rollback assert qua repository (Rule 0 — không chỉ nhìn response code)
+    boolean existsByName(String name);
+
+    @Query(value = "SELECT COUNT(*) FROM team_members tm "
+            + "WHERE tm.team_id IN (SELECT id FROM teams WHERE name = :name)", nativeQuery = true)
+    long countMembersByTeamName(@Param("name") String name);
+
+    // Test cleanup (test non-transactional commit thật) — DB cascade dọn team_members.
+    // Derived delete query KHÔNG tự mở tx như CRUD methods → cần @Transactional tường minh.
+    @Transactional
+    long deleteByName(String name);
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/domain/User.java

@@ -0,0 +1,72 @@
+package com.example.springsvc.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import org.hibernate.annotations.JdbcTypeCode;
+import org.hibernate.type.SqlTypes;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+@Entity
+@Table(name = "users")
+public class User {
+
+    @Id
+    private UUID id;
+
+    @Column(nullable = false, unique = true)
+    private String email;
+
+    @Column(name = "display_name", nullable = false)
+    private String displayName;
+
+    @JdbcTypeCode(SqlTypes.ARRAY)
+    @Column(nullable = false, columnDefinition = "text[]")
+    private List<String> roles = new ArrayList<>();
+
+    public User() {
+    }
+
+    public User(UUID id, String email, String displayName, List<String> roles) {
+        this.id = id;
+        this.email = email;
+        this.displayName = displayName;
+        this.roles = roles;
+    }
+
+    public UUID getId() {
+        return id;
+    }
+
+    public void setId(UUID id) {
+        this.id = id;
+    }
+
+    public String getEmail() {
+        return email;
+    }
+
+    public void setEmail(String email) {
+        this.email = email;
+    }
+
+    public String getDisplayName() {
+        return displayName;
+    }
+
+    public void setDisplayName(String displayName) {
+        this.displayName = displayName;
+    }
+
+    public List<String> getRoles() {
+        return roles;
+    }
+
+    public void setRoles(List<String> roles) {
+        this.roles = roles;
+    }
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/domain/UserRepository.java

@@ -0,0 +1,10 @@
+package com.example.springsvc.domain;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.UUID;
+
+public interface UserRepository extends JpaRepository<User, UUID> {
+
+    boolean existsByEmail(String email);
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/logging/LowercaseLevelJsonProvider.java

@@ -0,0 +1,24 @@
+package com.example.springsvc.logging;
+
+import ch.qos.logback.classic.spi.ILoggingEvent;
+import com.fasterxml.jackson.core.JsonGenerator;
+import net.logstash.logback.composite.AbstractFieldJsonProvider;
+
+import java.io.IOException;
+import java.util.Locale;
+
+/**
+ * Level lowercase — platform/conventions/03 bắt buộc "info"|"warn"|...
+ * (LogstashEncoder mặc định emit "INFO" uppercase).
+ */
+public class LowercaseLevelJsonProvider extends AbstractFieldJsonProvider<ILoggingEvent> {
+
+    public LowercaseLevelJsonProvider() {
+        setFieldName("level");
+    }
+
+    @Override
+    public void writeTo(JsonGenerator generator, ILoggingEvent event) throws IOException {
+        generator.writeStringField(getFieldName(), event.getLevel().toString().toLowerCase(Locale.ROOT));
+    }
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/security/JwtAuthFilter.java

@@ -0,0 +1,89 @@
+package com.example.springsvc.security;
+
+import com.example.springsvc.web.ErrorEnvelope;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.jsonwebtoken.Claims;
+import io.jsonwebtoken.JwtException;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.slf4j.MDC;
+import org.springframework.stereotype.Component;
+import org.springframework.web.util.ContentCachingRequestWrapper;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import java.io.IOException;
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * JWT enforcement mọi route TRỪ: /healthz, /readyz, /actuator/**, /v3/api-docs/**,
+ * /swagger-ui/** (docs chỉ schema tài liệu — precedent auth-mock) và mọi OPTIONS
+ * preflight (preflight không mang Authorization — chặn = CORS native gãy).
+ * Fail bất kỳ → 401 TỪ SERVICE với envelope conventions/04. Request id:
+ * echo X-Request-Id (gateway sinh nếu thiếu — conventions/03).
+ */
+@Component
+public class JwtAuthFilter extends OncePerRequestFilter {
+
+    private static final Set<String> EXACT_SKIP = Set.of("/healthz", "/readyz", "/actuator");
+    private static final List<String> PREFIX_SKIP = List.of("/actuator/", "/v3/api-docs", "/swagger-ui");
+
+    private final JwtVerifier verifier;
+    private final ObjectMapper mapper;
+
+    public JwtAuthFilter(JwtVerifier verifier, ObjectMapper mapper) {
+        this.verifier = verifier;
+        this.mapper = mapper;
+    }
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
+            throws ServletException, IOException {
+        if (shouldSkip(request)) {
+            chain.doFilter(request, response);
+            return;
+        }
+
+        String requestId = requestId(request);
+        MDC.put("requestId", requestId);
+        try {
+            String auth = request.getHeader("Authorization");
+            if (auth == null || !auth.startsWith("Bearer ")) {
+                unauthorized(response, requestId, "Missing Bearer token");
+                return;
+            }
+            try {
+                Claims claims = verifier.verify(auth.substring(7).trim());
+                request.setAttribute("jwt.claims", claims);
+                // ContentCaching: controller đọc key-presence raw body (vd PATCH roles:[])
+                chain.doFilter(new ContentCachingRequestWrapper(request), response);
+            } catch (JwtException | IllegalArgumentException e) {
+                // KHÔNG log token — chỉ log lý do chung (conventions/03)
+                unauthorized(response, requestId, "Invalid or expired token");
+            }
+        } finally {
+            MDC.remove("requestId");
+        }
+    }
+
+    private boolean shouldSkip(HttpServletRequest request) {
+        if ("OPTIONS".equalsIgnoreCase(request.getMethod())) {
+            return true; // CORS preflight
+        }
+        String path = request.getRequestURI();
+        return EXACT_SKIP.contains(path)
+                || PREFIX_SKIP.stream().anyMatch(path::startsWith);
+    }
+
+    private String requestId(HttpServletRequest request) {
+        String fromGateway = request.getHeader("X-Request-Id");
+        return fromGateway != null && !fromGateway.isBlank() ? fromGateway : UUID.randomUUID().toString();
+    }
+
+    private void unauthorized(HttpServletResponse response, String requestId, String message) throws IOException {
+        ErrorEnvelope.write(response, mapper, 401, "UNAUTHORIZED", message, requestId);
+    }
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/security/JwtVerifier.java

@@ -0,0 +1,48 @@
+package com.example.springsvc.security;
+
+import io.jsonwebtoken.Claims;
+import io.jsonwebtoken.Jwts;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import javax.crypto.SecretKey;
+import javax.crypto.spec.SecretKeySpec;
+import java.nio.charset.StandardCharsets;
+
+/**
+ * Lớp 2 enforcement — contracts/auth/token-contract.md §4: service TỰ verify
+ * signature (HS256, secret = UTF-8 bytes — khớp auth-mock node jsonwebtoken)
+ * + expiry (jjwt tự check khi parse) + iss. KHÔNG tin gateway.
+ * JWT_SECRET fail-fast lúc boot (platform/conventions/06 rule 6).
+ */
+@Component
+public class JwtVerifier {
+
+    public static final String REQUIRED_ISSUER = "auth-mock";
+
+    private final SecretKey key;
+
+    public JwtVerifier(@Value("${app.jwt-secret:}") String secret) {
+        if (secret == null || secret.isBlank()) {
+            throw new IllegalStateException("JWT_SECRET is required (contracts/auth/token-contract.md §2)");
+        }
+        this.key = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
+    }
+
+    /**
+     * @return claims khi token hợp lệ (sig + exp + iss)
+     * @throws io.jsonwebtoken.JwtException sai signature / hết hạn / sai iss / malformed
+     */
+    public Claims verify(String token) {
+        return Jwts.parser()
+                .verifyWith(key)
+                .requireIssuer(REQUIRED_ISSUER)
+                .build()
+                .parseSignedClaims(token)
+                .getPayload();
+    }
+
+    public SecretKey getKey() {
+        return key;
+    }
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/service/TeamService.java

@@ -0,0 +1,84 @@
+package com.example.springsvc.service;
+
+import com.example.springsvc.domain.Team;
+import com.example.springsvc.domain.TeamRepository;
+import com.example.springsvc.domain.UserRepository;
+import com.example.springsvc.web.ApiException;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * TeamService — service layer (SF-4, FI-78): demo Situation A.
+ *
+ * Situation A — nhiều step CÙNG 1 DB: 1 transaction là đủ. Method tạo team qua
+ * N lệnh ghi riêng biệt (teams.save + team_members từng dòng qua repository),
+ * có step GIỮA có thể fail → @Transactional rollback TOÀN BỘ (team + members
+ * đã insert trước đó cùng biến mất). So sánh Situation B (cross-service —
+ * Kafka saga, xem docs/superpowers/specs/2026-10-13-kafka-outbox-saga.md):
+ * 1 transaction KHÔNG phủ được service khác → cần outbox + compensation.
+ */
+@Service
+public class TeamService {
+
+    /**
+     * Rollback trigger DEMO — deterministic, dùng fixture CÓ SẴN trong
+     * contracts/auth/users.json (không cần user mới). Member có email này
+     * KHÔNG thể thêm vào team → step insert member đó throw giữa chừng.
+     */
+    public static final String ROLLBACK_TRIGGER_EMAIL = "alice@demo.local";
+
+    private final TeamRepository teams;
+    private final UserRepository users;
+
+    public TeamService(TeamRepository teams, UserRepository users) {
+        this.teams = teams;
+        this.users = users;
+    }
+
+    /**
+     * Tạo team + members qua N step trong MỘT transaction:
+     * step 1 — INSERT teams row (flush ngay để FK team_members thấy row);
+     * step 2..n — INSERT team_members từng dòng qua repository; member trùng
+     * trigger email → throw 409 → rollback toàn bộ các step trước.
+     *
+     * // Tạo team + members qua N step — fail giữa chừng = rollback toàn bộ
+     * // Create team + members in N steps — mid-fail rolls back everything
+     */
+    @Transactional
+    public CreatedTeam createTeam(String name, List<UUID> memberIds) {
+        if (name == null || name.isBlank()) {
+            throw ApiException.badRequest("name không được trống");
+        }
+        // dedupe giữ insertion order (team_members PK (team_id, user_id)) — "vị trí giữa" deterministic
+        LinkedHashSet<UUID> deduped = new LinkedHashSet<>(
+                memberIds == null ? List.of() : memberIds);
+
+        // Step 1 — lệnh ghi 1: team row
+        Team team = teams.saveAndFlush(new Team(name));
+
+        // Step 2..n — lệnh ghi 2+: từng member, insert line-by-line qua repository
+        for (UUID memberId : deduped) {
+            users.findById(memberId)
+                    .filter(user -> ROLLBACK_TRIGGER_EMAIL.equals(user.getEmail()))
+                    .ifPresent(user -> {
+                        throw ApiException.conflict("Member " + user.getEmail()
+                                + " không thể thêm vào team (rollback demo trigger)");
+                    });
+            teams.insertMember(team.getId(), memberId);
+        }
+        return new CreatedTeam(team, List.copyOf(deduped));
+    }
+
+    /**
+     * Kết quả create — memberIds là danh sách ĐÃ dedupe (echo contract);
+     * KHÔNG đọc qua entity collection vì members được insert native
+     * (không nằm trong persistence context — mutate managed collection sẽ
+     * khiến flush cascade ghi trùng PK).
+     */
+    public record CreatedTeam(Team team, List<UUID> memberIds) {
+    }
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/web/ApiError.java

@@ -0,0 +1,15 @@
+package com.example.springsvc.web;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+/**
+ * Error envelope chung — platform/conventions/04.
+ * Body: {"error":{"code","message","requestId","details"}}
+ */
+@JsonInclude(JsonInclude.Include.ALWAYS)
+public record ApiError(String code, String message, String requestId, Object details) {
+
+    public static ApiError of(String code, String message, String requestId) {
+        return new ApiError(code, message, requestId, null);
+    }
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/web/ApiException.java

@@ -0,0 +1,37 @@
+package com.example.springsvc.web;
+
+/**
+ * Business error có code theo catalog conventions/04 — map bởi
+ * GlobalExceptionHandler thành envelope.
+ */
+public class ApiException extends RuntimeException {
+
+    private final int status;
+    private final String code;
+
+    private ApiException(int status, String code, String message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+
+    public static ApiException badRequest(String message) {
+        return new ApiException(400, "VALIDATION_ERROR", message);
+    }
+
+    public static ApiException notFound(String message) {
+        return new ApiException(404, "NOT_FOUND", message);
+    }
+
+    public static ApiException conflict(String message) {
+        return new ApiException(409, "CONFLICT", message);
+    }
+
+    public int getStatus() {
+        return status;
+    }
+
+    public String getCode() {
+        return code;
+    }
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/web/DevCorsConfig.java

@@ -0,0 +1,41 @@
+package com.example.springsvc.web;
+
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Profile;
+import org.springframework.web.servlet.config.annotation.CorsRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * CORS dev-profile — platform/conventions/07: chỉ profile "dev" (native dev,
+ * không docker) mở CORS cho đúng origin trong CORS_DEV_ORIGIN (comma list);
+ * prod/compose → bean không active → không ACAO nào emit (deny-by-default).
+ */
+@Configuration
+@Profile("dev")
+public class DevCorsConfig implements WebMvcConfigurer {
+
+    private final String originsConfig;
+
+    public DevCorsConfig(org.springframework.core.env.Environment env) {
+        this.originsConfig = env.getProperty("app.cors-dev-origins", "");
+    }
+
+    @Override
+    public void addCorsMappings(CorsRegistry registry) {
+        List<String> origins = Arrays.stream(originsConfig.split(","))
+                .map(String::trim)
+                .filter(s -> !s.isEmpty())
+                .toList();
+        if (origins.isEmpty()) {
+            return; // deny-by-default — không emit ACAO
+        }
+        registry.addMapping("/api/**")
+                .allowedOrigins(origins.toArray(String[]::new))
+                .allowedMethods("GET", "POST", "PATCH")
+                .allowedHeaders("Authorization", "Content-Type", "X-Request-Id")
+                .exposedHeaders("X-Request-Id");
+    }
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/web/ErrorEnvelope.java

@@ -0,0 +1,27 @@
+package com.example.springsvc.web;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.servlet.http.HttpServletResponse;
+
+import java.io.IOException;
+
+/**
+ * Ghi error envelope conventions/04 thẳng vào response (dùng trong filter,
+ * nơi chưa có @RestControllerAdvice).
+ */
+public final class ErrorEnvelope {
+
+    private ErrorEnvelope() {
+    }
+
+    public static void write(HttpServletResponse response, ObjectMapper mapper,
+                             int status, String code, String message, String requestId) throws IOException {
+        response.setStatus(status);
+        response.setContentType("application/json");
+        mapper.writeValue(response.getOutputStream(), new ErrorWrapper(ApiError.of(code, message, requestId)));
+    }
+
+    // Shape {"error": {...}} — không serialize record ApiError trực tiếp ở top-level
+    public record ErrorWrapper(ApiError error) {
+    }
+}

package/stack-template/services/spring-svc/src/main/java/com/example/springsvc/web/GlobalExceptionHandler.java

@@ -0,0 +1,90 @@
+package com.example.springsvc.web;
+
+import jakarta.servlet.http.HttpServletRequest;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.slf4j.MDC;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.converter.HttpMessageNotReadableException;
+import org.springframework.validation.FieldError;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import org.springframework.web.method.annotation.HandlerMethodValidationException;
+import org.springframework.dao.DataIntegrityViolationException;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Map mọi 4xx/5xx về error envelope chung — platform/conventions/04.
+ * requestId = echo X-Request-Id (gateway sinh nếu thiếu).
+ */
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
+
+    private final HttpServletRequest request;
+
+    public GlobalExceptionHandler(HttpServletRequest request) {
+        this.request = request;
+    }
+
+    @ExceptionHandler(ApiException.class)
+    public ResponseEntity<ErrorEnvelope.ErrorWrapper> apiException(ApiException e) {
+        return respond(e.getStatus(), e.getCode(), e.getMessage(), null);
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<ErrorEnvelope.ErrorWrapper> invalidBody(MethodArgumentNotValidException e) {
+        Map<String, String> details = new HashMap<>();
+        for (FieldError fe : e.getBindingResult().getFieldErrors()) {
+            details.put(fe.getField(), fe.getDefaultMessage());
+        }
+        return respond(400, "VALIDATION_ERROR", "Payload không hợp lệ", details);
+    }
+
+    @ExceptionHandler({HttpMessageNotReadableException.class, HandlerMethodValidationException.class,
+            jakarta.validation.ConstraintViolationException.class})
+    public ResponseEntity<ErrorEnvelope.ErrorWrapper> unreadable(Exception e) {
+        return respond(400, "VALIDATION_ERROR", "Payload không hợp lệ hoặc sai định dạng", null);
+    }
+
+    @ExceptionHandler(DataIntegrityViolationException.class)
+    public ResponseEntity<ErrorEnvelope.ErrorWrapper> conflict(DataIntegrityViolationException e) {
+        return respond(409, "CONFLICT", "Dữ liệu vi phạm ràng buộc (vd email đã tồn tại)", null);
+    }
+
+    // Framework 4xx — KHÔNG để rơi vào catch-all 500 (conventions/04: INTERNAL chỉ unhandled)
+    @ExceptionHandler(org.springframework.web.servlet.resource.NoResourceFoundException.class)
+    public ResponseEntity<ErrorEnvelope.ErrorWrapper> noResource(org.springframework.web.servlet.resource.NoResourceFoundException e) {
+        return respond(404, "NOT_FOUND", "Không tìm thấy resource", null);
+    }
+
+    @ExceptionHandler(org.springframework.web.HttpRequestMethodNotSupportedException.class)
+    public ResponseEntity<ErrorEnvelope.ErrorWrapper> methodNotSupported(org.springframework.web.HttpRequestMethodNotSupportedException e) {
+        return respond(405, "METHOD_NOT_ALLOWED", "Method không được hỗ trợ", null);
+    }
+
+    @ExceptionHandler(org.springframework.web.HttpMediaTypeNotSupportedException.class)
+    public ResponseEntity<ErrorEnvelope.ErrorWrapper> mediaTypeNotSupported(org.springframework.web.HttpMediaTypeNotSupportedException e) {
+        return respond(415, "UNSUPPORTED_MEDIA_TYPE", "Content-Type không được hỗ trợ", null);
+    }
+
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ErrorEnvelope.ErrorWrapper> internal(Exception e) {
+        // KHÔNG lộ stack trong message (conventions/04) — log đầy đủ có err
+        log.error("Unhandled error: {}", e.toString(), e);
+        return respond(500, "INTERNAL", "Lỗi không xử lý được", null);
+    }
+
+    private ResponseEntity<ErrorEnvelope.ErrorWrapper> respond(
+            int status, String code, String message, Object details) {
+        String requestId = MDC.get("requestId") != null
+                ? MDC.get("requestId")
+                : request.getHeader("X-Request-Id");
+        return ResponseEntity.status(status)
+                .body(new ErrorEnvelope.ErrorWrapper(new ApiError(code, message, requestId, details)));
+    }
+}