create-wakii-stack 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,46 @@
+package com.example.springsvc.web;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.servlet.http.HttpServletRequest;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Map;
+
+/**
+ * Naked probes (conventions/02): /healthz liveness (process sống),
+ * /readyz readiness (Flyway xong + DB pass). Body shape CỐ ĐỊNH
+ * {"status":"ok"} — CI boot-smoke grep đúng shape này.
+ * 503 readiness trả envelope conventions/04 (code DEPENDENCY_DOWN catalog).
+ */
+@RestController
+public class HealthController {
+
+    public static final Map<String, String> OK = Map.of("status", "ok");
+
+    private final ReadinessService readiness;
+    private final ObjectMapper mapper;
+    private final HttpServletRequest request;
+
+    public HealthController(ReadinessService readiness, ObjectMapper mapper, HttpServletRequest request) {
+        this.readiness = readiness;
+        this.mapper = mapper;
+        this.request = request;
+    }
+
+    @GetMapping("/healthz")
+    public Map<String, String> healthz() {
+        return OK;
+    }
+
+    @GetMapping("/readyz")
+    public ResponseEntity<Object> readyz() {
+        if (readiness.isReady()) {
+            return ResponseEntity.ok(OK);
+        }
+        String requestId = request.getHeader("X-Request-Id");
+        return ResponseEntity.status(503)
+                .body(new ErrorEnvelope.ErrorWrapper(ApiError.of("DEPENDENCY_DOWN", "Service not ready", requestId)));
+    }
+}

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

@@ -0,0 +1,40 @@
+package com.example.springsvc.web;
+
+import org.springframework.boot.actuate.health.Health;
+import org.springframework.boot.actuate.health.HealthIndicator;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Component;
+
+/**
+ * /readyz — kiểm THẬT (conventions/02: không hardcode 200): DB reachable +
+ * Flyway đã migrate xong (bảng users query được = seed migration đã chạy).
+ */
+@Component("dbReadiness")
+public class ReadinessService implements HealthIndicator {
+
+    private static final org.slf4j.Logger log =
+            org.slf4j.LoggerFactory.getLogger(ReadinessService.class);
+
+    private final JdbcTemplate jdbc;
+
+    public ReadinessService(JdbcTemplate jdbc) {
+        this.jdbc = jdbc;
+    }
+
+    public boolean isReady() {
+        try {
+            // bảng users chỉ tồn tại sau V1 + seed V2 → query được = migration xong + DB sống
+            jdbc.queryForObject("SELECT count(*) FROM users", Integer.class);
+            return true;
+        } catch (Exception e) {
+            // conventions/03: lỗi có dấu vết đọc được — operator chẩn đoán 503 từ log
+            log.error("readyz check failed: {}", e.toString(), e);
+            return false;
+        }
+    }
+
+    @Override
+    public Health health() {
+        return isReady() ? Health.up().build() : Health.down().build();
+    }
+}

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

@@ -0,0 +1,79 @@
+package com.example.springsvc.web;
+
+import com.example.springsvc.api.TeamsApi;
+import com.example.springsvc.api.model.CreateTeamRequest;
+import com.example.springsvc.api.model.Team;
+import com.example.springsvc.api.model.TeamList;
+import com.example.springsvc.domain.TeamRepository;
+import com.example.springsvc.service.TeamService;
+import jakarta.validation.ConstraintViolation;
+import jakarta.validation.Validator;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * Teams API — implement generated TeamsApi. FINAL path (contract-resolved):
+ * /api/users/teams, /api/users/teams/{teamId}. interfaceOnly KHÔNG gắn base path
+ * → class-level @RequestMapping như UserController. memberIds dedupe trước insert
+ * (team_members PK (team_id, user_id) — tránh 500 vi phạm PK).
+ * SF-4 (FI-78): createTeam DELEGATE sang TeamService — @Transactional N-step
+ * rollback demo nằm ở service layer (không ở controller).
+ */
+@RestController
+@RequestMapping("${openapi.usersAPI.base-path:/api/users}")
+public class TeamController implements TeamsApi {
+
+    private final TeamRepository teams;
+    private final TeamService teamService;
+    private final Validator validator;
+
+    public TeamController(TeamRepository teams, TeamService teamService, Validator validator) {
+        this.teams = teams;
+        this.teamService = teamService;
+        this.validator = validator;
+    }
+
+    @Override
+    public ResponseEntity<TeamList> listTeams() {
+        List<com.example.springsvc.domain.Team> all = teams.findAll();
+        TeamList list = new TeamList();
+        list.setItems(all.stream().map(TeamController::toApi).toList());
+        list.setTotal(all.size());
+        return ResponseEntity.ok(list);
+    }
+
+    @Override
+    public ResponseEntity<Team> createTeam(CreateTeamRequest createTeamRequest) {
+        var violations = validator.validate(createTeamRequest);
+        if (!violations.isEmpty()) {
+            ConstraintViolation<CreateTeamRequest> first = violations.iterator().next();
+            throw ApiException.badRequest(first.getPropertyPath() + " " + first.getMessage());
+        }
+        TeamService.CreatedTeam created = teamService.createTeam(
+                createTeamRequest.getName(), createTeamRequest.getMemberIds());
+        Team team = new Team();
+        team.setId(created.team().getId());
+        team.setName(created.team().getName());
+        team.setMemberIds(created.memberIds());
+        return ResponseEntity.status(201).body(team);
+    }
+
+    @Override
+    public ResponseEntity<Team> getTeam(UUID teamId) {
+        com.example.springsvc.domain.Team team = teams.findById(teamId)
+                .orElseThrow(() -> ApiException.notFound("Team " + teamId + " not found"));
+        return ResponseEntity.ok(toApi(team));
+    }
+
+    private static Team toApi(com.example.springsvc.domain.Team entity) {
+        Team team = new Team();
+        team.setId(entity.getId());
+        team.setName(entity.getName());
+        team.setMemberIds(List.copyOf(entity.getMemberIds()));
+        return team;
+    }
+}

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

@@ -0,0 +1,187 @@
+package com.example.springsvc.web;
+
+import com.example.springsvc.api.UsersApi;
+import com.example.springsvc.api.model.CreateUserRequest;
+import com.example.springsvc.api.model.HealthStatus;
+import com.example.springsvc.api.model.Role;
+import com.example.springsvc.api.model.UpdateUserRequest;
+import com.example.springsvc.api.model.User;
+import com.example.springsvc.api.model.UserList;
+import com.example.springsvc.domain.UserRepository;
+import jakarta.persistence.EntityManager;
+import jakarta.persistence.PersistenceContext;
+import jakarta.validation.ConstraintViolation;
+import jakarta.validation.Validator;
+import org.springframework.http.ResponseEntity;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * Users API — implement generated UsersApi (codegen từ snapshot users.yaml).
+ * interfaceOnly KHÔNG gắn class-level base path → implementor tự gắn
+ * (property openapi.usersAPI.base-path, default /api/users khớp FINAL path table §4.5).
+ * Mirrors getHealthz/getReadyz → /api/users/healthz|readyz (probe thật dùng naked — HealthController).
+ */
+@RestController
+@RequestMapping("${openapi.usersAPI.base-path:/api/users}")
+public class UserController implements UsersApi {
+
+    private final UserRepository users;
+    private final Validator validator;
+    private final com.fasterxml.jackson.databind.ObjectMapper mapper;
+
+    @PersistenceContext
+    private EntityManager em;
+
+    public UserController(UserRepository users, Validator validator,
+            com.fasterxml.jackson.databind.ObjectMapper mapper) {
+        this.users = users;
+        this.validator = validator;
+        this.mapper = mapper;
+    }
+
+    @Override
+    public ResponseEntity<UserList> listUsers(Integer limit, Integer offset) {
+        int safeLimit = limit == null ? 50 : limit;
+        int safeOffset = offset == null ? 0 : offset;
+        if (safeLimit < 1 || safeLimit > 100) {
+            throw ApiException.badRequest("limit must be between 1 and 100");
+        }
+        if (safeOffset < 0) {
+            throw ApiException.badRequest("offset must be >= 0");
+        }
+        // raw offset (không divisible-safe như PageRequest) — đúng nghĩa query param của contract
+        List<com.example.springsvc.domain.User> items = em
+                .createQuery("select u from User u order by u.email", com.example.springsvc.domain.User.class)
+                .setFirstResult(safeOffset)
+                .setMaxResults(safeLimit)
+                .getResultList();
+        UserList list = new UserList();
+        list.setItems(items.stream().map(UserController::toApi).toList());
+        list.setTotal(Math.toIntExact(users.count()));
+        return ResponseEntity.ok(list);
+    }
+
+    @Override
+    @Transactional
+    public ResponseEntity<User> createUser(CreateUserRequest createUserRequest) {
+        validate(createUserRequest);
+        String email = createUserRequest.getEmail();
+        if (users.existsByEmail(email)) {
+            throw ApiException.conflict("Email already exists: " + mask(email));
+        }
+        // Contract default: [user] — server-side apply (codegen không apply khi deserialize)
+        List<Role> roles = createUserRequest.getRoles() == null || createUserRequest.getRoles().isEmpty()
+                ? List.of(Role.USER)
+                : createUserRequest.getRoles();
+        // ⚠️ import collision: User (imported) = api.model.User — entity phải fully-qualify
+        com.example.springsvc.domain.User user = new com.example.springsvc.domain.User(
+                UUID.randomUUID(), email,
+                createUserRequest.getDisplayName(), roles.stream().map(Role::getValue).toList());
+        users.save(user);
+        return ResponseEntity.status(201).body(toApi(user));
+    }
+
+    @Override
+    public ResponseEntity<User> getUser(UUID userId) {
+        return ResponseEntity.ok(toApi(find(userId)));
+    }
+
+    @Override
+    @Transactional
+    public ResponseEntity<User> updateUser(UUID userId, UpdateUserRequest updateUserRequest) {
+        // Constraint trên generated model (displayName minLength 1...) — @Valid trên interface
+        // param KHÔNG inherit xuống impl → validate thủ công như createUser (review P1)
+        var violations = validator.validate(updateUserRequest);
+        if (!violations.isEmpty()) {
+            ConstraintViolation<UpdateUserRequest> first = violations.iterator().next();
+            throw ApiException.badRequest(first.getPropertyPath() + " " + first.getMessage());
+        }
+        boolean hasDisplayName = updateUserRequest.getDisplayName() != null;
+        // Generated model init collection → roles empty không phân biệt absent/[] — đọc
+        // key-presence từ raw body (contract: minProperties đếm key; roles KHÔNG minItems
+        // nên {"roles":[]} hợp lệ = clear roles). JwtAuthFilter wrap ContentCachingRequestWrapper.
+        boolean hasRoles = bodyHas("roles");
+        if (!hasDisplayName && !hasRoles) {
+            // contract minProperties: 1
+            throw ApiException.badRequest("At least one of displayName, roles is required");
+        }
+        com.example.springsvc.domain.User user = find(userId);
+        if (hasDisplayName) {
+            user.setDisplayName(updateUserRequest.getDisplayName());
+        }
+        if (hasRoles) {
+            user.setRoles(updateUserRequest.getRoles().stream().map(Role::getValue).toList());
+        }
+        users.save(user);
+        return ResponseEntity.ok(toApi(user));
+    }
+
+    private boolean bodyHas(String field) {
+        var attrs = org.springframework.web.context.request.RequestContextHolder.getRequestAttributes();
+        if (attrs instanceof org.springframework.web.context.request.ServletRequestAttributes sra
+                && sra.getRequest() instanceof org.springframework.web.util.ContentCachingRequestWrapper wrapper) {
+            try {
+                byte[] content = wrapper.getContentAsByteArray();
+                if (content.length == 0) {
+                    return false;
+                }
+                return mapper.readTree(content).has(field);
+            } catch (java.io.IOException e) {
+                return false;
+            }
+        }
+        return false;
+    }
+
+    // ---- mirrors của healthz/readyz theo spec §4.5 (probe thật = naked path) ----
+
+    @Override
+    public ResponseEntity<HealthStatus> getHealthz() {
+        return ResponseEntity.ok(okStatus());
+    }
+
+    @Override
+    public ResponseEntity<HealthStatus> getReadyz() {
+        return ResponseEntity.ok(okStatus());
+    }
+
+    // ---- helpers ----
+
+    private void validate(CreateUserRequest request) {
+        var violations = validator.validate(request);
+        if (!violations.isEmpty()) {
+            ConstraintViolation<CreateUserRequest> first = violations.iterator().next();
+            throw ApiException.badRequest(first.getPropertyPath() + " " + first.getMessage());
+        }
+    }
+
+    private com.example.springsvc.domain.User find(UUID id) {
+        return users.findById(id)
+                .orElseThrow(() -> ApiException.notFound("User " + id + " not found"));
+    }
+
+    private static HealthStatus okStatus() {
+        HealthStatus status = new HealthStatus();
+        status.setStatus(HealthStatus.StatusEnum.OK);
+        return status;
+    }
+
+    private static User toApi(com.example.springsvc.domain.User entity) {
+        User user = new User();
+        user.setId(entity.getId());
+        user.setEmail(entity.getEmail());
+        user.setDisplayName(entity.getDisplayName());
+        user.setRoles(entity.getRoles().stream().map(Role::fromValue).toList());
+        return user;
+    }
+
+    private static String mask(String email) {
+        int at = email.indexOf('@');
+        return at <= 1 ? "***" : email.charAt(0) + "***" + email.substring(at);
+    }
+}

package/stack-template/services/spring-svc/src/main/java/db/migration/V2__SeedUsers.java

@@ -0,0 +1,66 @@
+package db.migration;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.flywaydb.core.api.migration.BaseJavaMigration;
+import org.flywaydb.core.api.migration.Context;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.sql.PreparedStatement;
+import java.util.UUID;
+
+/**
+ * V2 — seed bảng users ĐỌC contracts/auth/users.json qua env USERS_FIXTURE_PATH
+ * (compose mount /app/contracts/auth/users.json — cùng file auth-mock đọc runtime).
+ * Id phải khớp fixture 100% — assert trong SeedMatchIntegrationTest.
+ * Fail-fast khi thiếu/sai file/malformed (platform/conventions/06 rule 6).
+ * Fixture evolution: thêm user mới sau khi V2 đã applied = V3 migration riêng (README ADR).
+ */
+public class V2__SeedUsers extends BaseJavaMigration {
+
+    @Override
+    public void migrate(Context context) throws Exception {
+        String fixturePath = System.getenv("USERS_FIXTURE_PATH");
+        if (fixturePath == null || fixturePath.isBlank()) {
+            throw new IllegalStateException(
+                    "USERS_FIXTURE_PATH is required (seed đọc contracts/auth/users.json — conventions/06)");
+        }
+        Path path = Path.of(fixturePath);
+        if (!Files.exists(path)) {
+            throw new IllegalStateException("users fixture not found at " + fixturePath);
+        }
+
+        // readTree tree-model bỏ qua tự nhiên key "$comment" của fixture
+        ObjectMapper mapper = new ObjectMapper();
+        JsonNode users = mapper.readTree(path.toFile()).get("users");
+        if (users == null || !users.isArray() || users.isEmpty()) {
+            throw new IllegalStateException("users fixture malformed: expected non-empty users[] at " + fixturePath);
+        }
+
+        String sql = "INSERT INTO users (id, email, display_name, roles) VALUES (?, ?, ?, ?)";
+        try (PreparedStatement stmt = context.getConnection().prepareStatement(sql)) {
+            for (JsonNode u : users) {
+                stmt.setObject(1, UUID.fromString(required(u, "id").asText()));
+                stmt.setString(2, required(u, "email").asText());
+                stmt.setString(3, required(u, "displayName").asText());
+                JsonNode roles = required(u, "roles");
+                String[] roleArray = new String[roles.size()];
+                for (int i = 0; i < roles.size(); i++) {
+                    roleArray[i] = roles.get(i).asText();
+                }
+                stmt.setArray(4, context.getConnection().createArrayOf("text", roleArray));
+                stmt.addBatch();
+            }
+            stmt.executeBatch();
+        }
+    }
+
+    private static JsonNode required(JsonNode user, String field) {
+        JsonNode value = user.get(field);
+        if (value == null || value.isNull()) {
+            throw new IllegalStateException("users fixture entry missing required field: " + field);
+        }
+        return value;
+    }
+}

package/stack-template/services/spring-svc/src/main/resources/application.yml

@@ -0,0 +1,42 @@
+# ============================================================================
+# spring-svc config — 100% env-var (platform/conventions/06), fail-fast secret
+# Compose entry pre-seed inject: SERVER_PORT, SPRING_DATASOURCE_*, JWT_SECRET,
+# USERS_FIXTURE_PATH, CORS_DEV_ORIGIN, LOG_LEVEL (KHÔNG sửa compose).
+# ============================================================================
+server:
+  port: ${SERVER_PORT:8081} # conventions/05-ports.md
+
+spring:
+  application:
+    name: spring-svc
+  datasource:
+    # Role spring_svc có search_path=users (platform/postgres/init/01-init.sh)
+    url: ${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/boilerplate}
+    username: ${SPRING_DATASOURCE_USERNAME:spring_svc}
+    password: ${SPRING_DATASOURCE_PASSWORD:}
+  jpa:
+    open-in-view: false
+    hibernate:
+      # Flyway là schema owner — Hibernate không tự tạo/đổi schema
+      ddl-auto: none
+  flyway:
+    locations: classpath:db/migration
+
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health
+  endpoint:
+    health:
+      probes:
+        enabled: true # /actuator/health/liveness — conventions/02
+
+app:
+  jwt-secret: ${JWT_SECRET:}          # fail-fast validate ở JwtVerifier (task 4)
+  users-fixture-path: ${USERS_FIXTURE_PATH:} # seed V2 đọc contracts/auth/users.json
+  cors-dev-origins: ${CORS_DEV_ORIGIN:}      # CORS @Profile("dev") — conventions/07
+
+logging:
+  level:
+    root: ${LOG_LEVEL:info}

package/stack-template/services/spring-svc/src/main/resources/db/migration/V1__init.sql

@@ -0,0 +1,24 @@
+-- ============================================================================
+-- V1 — schema `users` DDL (spring-svc SF-3 sở hữu)
+-- Schema `users` + role spring_svc (search_path=users) do
+-- platform/postgres/init/01-init.sh tạo — file này KHÔNG tạo schema.
+-- ddl-auto: none — Flyway là schema owner duy nhất.
+-- ============================================================================
+
+CREATE TABLE users (
+    id           uuid PRIMARY KEY,
+    email        varchar(255) NOT NULL UNIQUE,
+    display_name varchar(255) NOT NULL,
+    roles        text[]       NOT NULL
+);
+
+CREATE TABLE teams (
+    id   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    name varchar(255) NOT NULL
+);
+
+CREATE TABLE team_members (
+    team_id uuid NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+    user_id uuid NOT NULL,
+    PRIMARY KEY (team_id, user_id)
+);

package/stack-template/services/spring-svc/src/main/resources/logback-spring.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- ============================================================================
+     JSON log shape — platform/conventions/03:
+     {"ts","level"(lowercase),"service","msg","requestId"(MDC),"err"(stack khi có)}
+     stdout-only (12-factor); LOG_LEVEL env điều khiển root level.
+     ============================================================================ -->
+<configuration>
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
+            <providers>
+                <timestamp>
+                    <fieldName>ts</fieldName>
+                    <pattern>yyyy-MM-dd'T'HH:mm:ss.SSS'Z'</pattern>
+                    <timeZone>UTC</timeZone>
+                </timestamp>
+                <provider class="com.example.springsvc.logging.LowercaseLevelJsonProvider"/>
+                <message>
+                    <fieldName>msg</fieldName>
+                </message>
+                <mdc/>
+                <stackTrace>
+                    <fieldName>err</fieldName>
+                </stackTrace>
+                <pattern>
+                    <pattern>{"service":"spring-svc"}</pattern>
+                </pattern>
+            </providers>
+        </encoder>
+    </appender>
+
+    <root level="${LOG_LEVEL:-info}">
+        <appender-ref ref="STDOUT"/>
+    </root>
+</configuration>