birc-generator 0.9.1 → 1.0.0

package/templates/auth/JwtService.hbs

@@ -0,0 +1,60 @@
+package {{basePackage}}.security;
+
+import io.jsonwebtoken.Claims;
+import io.jsonwebtoken.JwtException;
+import io.jsonwebtoken.Jwts;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.util.Date;
+import java.util.List;
+import javax.crypto.SecretKey;
+import io.jsonwebtoken.security.Keys;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import {{basePackage}}.config.JwtProperties;
+
+/**
+ * 發與驗 JWT。權限代碼放在 authorities claim，跟 {@code @RequirePermission} 比對的是
+ * 同一組字串，不加 ROLE_ 前綴。
+ */
+@Service
+@RequiredArgsConstructor
+public class JwtService {
+
+    private static final String AUTHORITIES_CLAIM = "authorities";
+
+    private final JwtProperties properties;
+
+    private SecretKey key() {
+        return Keys.hmacShaKeyFor(properties.getSecret().getBytes(StandardCharsets.UTF_8));
+    }
+
+    public String issue(String account, List<String> authorities) {
+        Instant now = Instant.now();
+        return Jwts.builder()
+                .subject(account)
+                .claim(AUTHORITIES_CLAIM, authorities)
+                .issuedAt(Date.from(now))
+                .expiration(Date.from(now.plusSeconds(properties.getExpirationSeconds())))
+                .signWith(key())
+                .compact();
+    }
+
+    /**
+     * 驗章並取出內容。簽章不對、過期、格式壞掉都回 null，由呼叫端當成沒登入處理——
+     * 不要把解析失敗的原因回給客戶端，那會變成攻擊者的除錯工具。
+     */
+    public AuthenticatedUser parse(String token) {
+        try {
+            Claims claims = Jwts.parser().verifyWith(key()).build().parseSignedClaims(token).getPayload();
+            List<?> raw = claims.get(AUTHORITIES_CLAIM, List.class);
+            List<String> authorities =
+                    raw == null ? List.of() : raw.stream().map(String::valueOf).toList();
+            return new AuthenticatedUser(claims.getSubject(), authorities);
+        } catch (JwtException | IllegalArgumentException e) {
+            return null;
+        }
+    }
+
+    public record AuthenticatedUser(String account, List<String> authorities) {}
+}

package/templates/auth/LoginFailedException.hbs

@@ -0,0 +1,27 @@
+package {{basePackage}}.exception;
+
+import org.springframework.http.HttpStatus;
+
+/**
+ * 帳號不存在與密碼錯誤共用這一種錯誤。分開回會讓人可以拿登入端點列舉帳號。
+ */
+public class LoginFailedException extends ProjectException {
+
+    public LoginFailedException() {
+        super("帳號或密碼錯誤");
+    }
+
+    public LoginFailedException(String message) {
+        super(message);
+    }
+
+    @Override
+    public String getErrorCode() {
+        return "LoginFailed";
+    }
+
+    @Override
+    public HttpStatus getHttpStatus() {
+        return HttpStatus.UNAUTHORIZED;
+    }
+}

package/templates/auth/LoginRequest.hbs

@@ -0,0 +1,16 @@
+package {{basePackage}}.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+@Setter
+public class LoginRequest {
+
+    @NotBlank(message = "帳號不可為空")
+    private String account;
+
+    @NotBlank(message = "密碼不可為空")
+    private String password;
+}

package/templates/auth/V1__create_auth_users_table.sql.hbs

@@ -0,0 +1,13 @@
+-- 登入用的帳號表（由 birc-generator add auth 產生）
+-- 專案已經有 V1 的話，把這個檔改成還沒用過的版本號，Flyway 不允許重複版本。
+
+CREATE TABLE auth_users (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    account VARCHAR(50) NOT NULL UNIQUE,
+    password VARCHAR(100) NOT NULL,
+    display_name VARCHAR(50) NULL,
+    authorities VARCHAR(500) NULL,
+    enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

package/templates/auth/application-yml-block.hbs

@@ -0,0 +1,7 @@
+---
+# --- auth（由 birc-generator add 產生） ---
+# secret 從 JWT_SECRET 來。沒設時啟動會寫進 .env，不要把值寫死在這裡。
+birc:
+  auth:
+    secret: ${JWT_SECRET:}
+    expiration-seconds: ${JWT_EXPIRATION_SECONDS:28800}

package/templates/auth/build-gradle-dep.hbs

@@ -0,0 +1,4 @@
+    implementation 'org.springframework.boot:spring-boot-starter-security'
+    implementation 'io.jsonwebtoken:jjwt-api:{{jjwtVersion}}'
+    runtimeOnly 'io.jsonwebtoken:jjwt-impl:{{jjwtVersion}}'
+    runtimeOnly 'io.jsonwebtoken:jjwt-jackson:{{jjwtVersion}}'

package/templates/auth/spring.factories.hbs

@@ -0,0 +1 @@
+org.springframework.boot.EnvironmentPostProcessor={{basePackage}}.config.JwtSecretEnvironmentPostProcessor

package/templates/base/CorsTest.java.hbs

@@ -0,0 +1,93 @@
+package {{basePackage}};
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.util.List;
+import java.util.stream.Stream;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.web.server.LocalServerPort;
+import {{basePackage}}.config.SecurityConfig;
+import {{basePackage}}.config.SecurityCustomizer;
+
+/**
+ * CORS 是瀏覽器端唯一會靜默失敗的設定：漏掉就只有前端看得到錯誤，後端日誌乾乾淨淨。
+ * 這份測試打真的 preflight，確認放行與拒絕都如預期，並擋住「設定看起來合法、實際上全開」的寫法。
+ */
+@SpringBootTest(
+        webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
+        properties = "app.cors.allowed-origin-patterns=http://localhost:5173")
+class CorsTest {
+
+    @LocalServerPort
+    private int port;
+
+    private HttpResponse<String> preflight(String origin) throws Exception {
+        HttpRequest request = HttpRequest.newBuilder()
+                .uri(URI.create("http://localhost:" + port + "/api/preflight-probe"))
+                .method("OPTIONS", HttpRequest.BodyPublishers.noBody())
+                .header("Origin", origin)
+                .header("Access-Control-Request-Method", "GET")
+                .header("Access-Control-Request-Headers", "authorization")
+                .build();
+        return HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
+    }
+
+    @Test
+    void allowsConfiguredOrigin() throws Exception {
+        // 防住：CORS 沒掛在 SecurityFilterChain 上時，preflight 會被擋成 401。
+        HttpResponse<String> response = preflight("http://localhost:5173");
+
+        assertEquals(200, response.statusCode());
+        assertEquals(
+                "http://localhost:5173",
+                response.headers().firstValue("Access-Control-Allow-Origin").orElse(null));
+    }
+
+    @Test
+    void rejectsUnknownOrigin() throws Exception {
+        HttpResponse<String> response = preflight("https://evil.example.com");
+
+        assertNull(response.headers().firstValue("Access-Control-Allow-Origin").orElse(null));
+    }
+
+    /** 這幾條只驗 CORS 設定本身，不需要任何 SecurityCustomizer。 */
+    private static ObjectProvider<SecurityCustomizer> noCustomizers() {
+        return new ObjectProvider<>() {
+            @Override
+            public SecurityCustomizer getObject() {
+                throw new UnsupportedOperationException();
+            }
+
+            @Override
+            public Stream<SecurityCustomizer> orderedStream() {
+                return Stream.empty();
+            }
+        };
+    }
+
+    @Test
+    void rejectsOriginPatternsThatOpenTheApiToEveryone() {
+        // 防住：守衛只比對 "*" 這類字面字串時，https://*.* 會繞過去變成全開。
+        List<String> unsafe = List.of("*", "http://*", "https://*", "https://*.*", "http*://*", "https://*.com");
+
+        for (String pattern : unsafe) {
+            assertThrows(
+                    IllegalStateException.class,
+                    () -> new SecurityConfig(List.of(pattern), false, true, noCustomizers()).corsConfigurationSource(),
+                    pattern + " 應該要被拒絕");
+        }
+    }
+
+    @Test
+    void allowsSingleLevelSubdomainWildcard() {
+        new SecurityConfig(List.of("https://*.ntub.edu.tw"), false, true, noCustomizers()).corsConfigurationSource();
+    }
+}

package/templates/base/README.md.hbs

@@ -47,6 +47,12 @@ CORS_ALLOWED_ORIGIN_PATTERNS=http://localhost:5173
 
 逗號分隔、不要尾斜線、不要 `*`。只改這變數；不要在 `WebMvcConfigurer` 加 `addCorsMappings`，Spring Security 不會吃。
 
+## API 文件（Swagger）
+
+預設開著，開發時直接開 `/swagger-ui.html`。上正式環境設 `API_DOCS_ENABLED=false`，
+springdoc 端點與匿名放行會一起關掉——文件開著等於把所有端點與 schema 攤給任何人看。
+`docker-compose.prod.yml` 已經預設關閉。
+
 ## 生骨架
 
 在有 `.bircrc.json` 的目錄跑即可；子目錄也可以，`birc` 會往上找。

package/templates/base/application-test.yml.hbs

@@ -21,6 +21,9 @@ sentry:
 birc:
   sso:
     enabled: false
+  auth:
+    # 測試用的假金鑰。正式環境的 secret 一律走環境變數 JWT_SECRET，沒設就啟動失敗。
+    secret: test-secret-that-is-long-enough-for-hs256
 
 external:
   api:

package/templates/base/application.yml.hbs

@@ -13,6 +13,18 @@ spring:
 server:
   port: ${SPRING_SERVER_PORT:8080}
 
+app:
+  cors:
+    # 允許跨來源呼叫的前端 Origin，用逗號分隔，例如 http://localhost:5173。
+    # 留空 = 不開放跨來源。不接受 *，那等於讓任何網站帶著使用者憑證呼叫這支 API。
+    allowed-origin-patterns: ${CORS_ALLOWED_ORIGIN_PATTERNS:}
+    # 前端要帶 cookie 才需要打開。Bearer Token 的 Authorization 標頭不需要。
+    allow-credentials: ${CORS_ALLOW_CREDENTIALS:false}
+  api-docs:
+    # Swagger UI / OpenAPI JSON。開著等於公開所有端點與 schema，
+    # 正式環境設 false（同時會關掉 springdoc 端點與匿名放行）。
+    enabled: ${API_DOCS_ENABLED:true}
+
 # 下面這行是 plop add 的插入點，不要刪、不要移動位置。
 # 新的 feature 設定會被插到這行「之後」。
 # birc-generator:config-anchor

package/templates/clockin/ClockInApiException.hbs

@@ -0,0 +1,37 @@
+package {{basePackage}}.exception.clockin;
+
+import org.springframework.http.HttpStatus;
+import {{basePackage}}.exception.ProjectException;
+
+/**
+ * 簽到系統回 result=false，或連不上時丟這個。
+ * upstreamErrorCode 是對方的 errorCode，原樣往外帶，方便對照它的訊息。
+ */
+public class ClockInApiException extends ProjectException {
+
+    private final String upstreamErrorCode;
+
+    public ClockInApiException(String upstreamErrorCode, String message) {
+        super(message);
+        this.upstreamErrorCode = upstreamErrorCode;
+    }
+
+    public ClockInApiException(String message, Throwable cause) {
+        super(message, cause);
+        this.upstreamErrorCode = "";
+    }
+
+    public String getUpstreamErrorCode() {
+        return upstreamErrorCode;
+    }
+
+    @Override
+    public String getErrorCode() {
+        return "ClockInApiFailed";
+    }
+
+    @Override
+    public HttpStatus getHttpStatus() {
+        return HttpStatus.BAD_GATEWAY;
+    }
+}

package/templates/clockin/ClockInApiResponse.hbs

@@ -0,0 +1,14 @@
+package {{basePackage}}.dto.clockin;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import tools.jackson.databind.JsonNode;
+
+/**
+ * 簽到系統的統一外殼。它一律回 HTTP 200，成敗看 result；
+ * 失敗時 errorCode 例如 NotFound、User - AccessDenied。
+ *
+ * data 故意留 JsonNode 不直接定型：失敗時它是空物件 {}，先定成 ClockInPage 或 List 會在反序列化就炸掉，
+ * 蓋掉真正的錯誤訊息。所以先確認 result，成功才把 data 轉成要的型別。
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record ClockInApiResponse(boolean result, String errorCode, String message, JsonNode data) {}

package/templates/clockin/ClockInClient.hbs

@@ -0,0 +1,251 @@
+package {{basePackage}}.client;
+
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.stereotype.Component;
+import org.springframework.util.LinkedMultiValueMap;
+import org.springframework.util.MultiValueMap;
+import org.springframework.web.client.RestClient;
+import org.springframework.web.client.RestClientException;
+import org.springframework.web.util.UriBuilder;
+import tools.jackson.databind.ObjectMapper;
+import {{basePackage}}.config.ClockInProperties;
+import {{basePackage}}.dto.clockin.ClockInApiResponse;
+import {{basePackage}}.dto.clockin.ClockInPage;
+import {{basePackage}}.dto.clockin.ClockInRecord;
+import {{basePackage}}.dto.clockin.OnDutyWeek;
+import {{basePackage}}.dto.clockin.UnclockedMember;
+import {{basePackage}}.dto.clockin.UserPermission;
+import {{basePackage}}.exception.clockin.ClockInApiException;
+
+/**
+ * 中心簽到系統（BIRC CMS）的 API 封裝。
+ *
+ * 三件事跟一般 REST 不一樣，所以邏輯集中在這裡，不要散到 service：
+ * 1. 登入是 form-urlencoded 打 /login，JWT 從回應的 X-Auth-Token 標頭拿，之後用 Authorization: Bearer 帶。
+ * 2. 它一律回 HTTP 200，成敗看 body 的 result；權限過期是 errorCode「User - AccessDenied」，不是 401。
+ *    所以 token 失效要看 errorCode 判斷，重新登入後重試一次。
+ * 3. 回應的 Content-Type 是 text/plain，converter 設定在 ClockInClientConfig。
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class ClockInClient {
+
+    private static final String AUTH_TOKEN_HEADER = "X-Auth-Token";
+
+    private final RestClient clockInRestClient;
+
+    private final ClockInProperties properties;
+
+    private final ObjectMapper objectMapper;
+
+    private volatile String token;
+
+    /** 今天還沒簽到的成員。這支不需要權限，可以拿來確認連線通不通。 */
+    public List<UnclockedMember> findTodayUnclocked() {
+        UnclockedMember[] members = read(
+                jwt -> clockInRestClient.get()
+                        .uri("/clockin/today")
+                        .header(HttpHeaders.AUTHORIZATION, bearer(jwt))
+                        .retrieve()
+                        .body(ClockInApiResponse.class),
+                UnclockedMember[].class);
+        return members == null ? List.of() : List.of(members);
+    }
+
+    /** 目前登入者是誰、權限是什麼。要不要顯示全中心的紀錄看這支的 authority。 */
+    public UserPermission findMyPermission() {
+        return read(
+                jwt -> clockInRestClient.get()
+                        .uri("/user/permissions")
+                        .header(HttpHeaders.AUTHORIZATION, bearer(jwt))
+                        .retrieve()
+                        .body(ClockInApiResponse.class),
+                UserPermission.class);
+    }
+
+    /** 值班表，一週一筆。簽到頁面用它顯示這週誰值班。 */
+    public List<OnDutyWeek> findAllOnDuty() {
+        OnDutyWeek[] weeks = read(
+                jwt -> clockInRestClient.get()
+                        .uri("/onduty")
+                        .header(HttpHeaders.AUTHORIZATION, bearer(jwt))
+                        .retrieve()
+                        .body(ClockInApiResponse.class),
+                OnDutyWeek[].class);
+        return weeks == null ? List.of() : List.of(weeks);
+    }
+
+    /** 某個帳號的打卡紀錄，分頁。nowPage 從 1 開始；year / month 給 null 就是不限月份。 */
+    public ClockInPage findMemberRecords(String userAccount, Integer year, Integer month, int nowPage) {
+        return read(
+                jwt -> clockInRestClient.get()
+                        .uri(builder -> period(builder.path("/clockin/userAccount/{userAccount}"), year, month)
+                                .queryParam("nowPage", nowPage)
+                                .build(userAccount))
+                        .header(HttpHeaders.AUTHORIZATION, bearer(jwt))
+                        .retrieve()
+                        .body(ClockInApiResponse.class),
+                ClockInPage.class);
+    }
+
+    /** 全部學生的打卡紀錄。這支沒有分頁，但資料仍然包在 list 裡面，所以借用同一個型別再取 list。 */
+    public List<ClockInRecord> findStudentRecords(Integer year, Integer month) {
+        ClockInPage page = read(
+                jwt -> clockInRestClient.get()
+                        .uri(builder -> period(builder.path("/clockin/students"), year, month)
+                                .build())
+                        .header(HttpHeaders.AUTHORIZATION, bearer(jwt))
+                        .retrieve()
+                        .body(ClockInApiResponse.class),
+                ClockInPage.class);
+        return page == null || page.list() == null ? List.of() : page.list();
+    }
+
+    /** 全中心的打卡紀錄，分頁。要管理者權限，學生帳號會拿到 AccessDenied。 */
+    public ClockInPage findAllRecords(Integer year, Integer month, int nowPage) {
+        return read(
+                jwt -> clockInRestClient.get()
+                        .uri(builder -> period(builder.path("/clockin"), year, month)
+                                .queryParam("nowPage", nowPage)
+                                .build())
+                        .header(HttpHeaders.AUTHORIZATION, bearer(jwt))
+                        .retrieve()
+                        .body(ClockInApiResponse.class),
+                ClockInPage.class);
+    }
+
+    /** 用學號簽到。同一天重複簽到由簽到系統擋，這裡不先查。 */
+    public String clockIn(String stuNumber) {
+        return send(jwt -> clockInRestClient.post()
+                        .uri("/clockin/{stuNumber}", stuNumber)
+                        .header(HttpHeaders.AUTHORIZATION, bearer(jwt))
+                        .retrieve()
+                        .body(ClockInApiResponse.class))
+                .message();
+    }
+
+    /** 簽退，時數由簽到系統算。 */
+    public String clockOut(String userAccount) {
+        return send(jwt -> clockInRestClient.patch()
+                        .uri("/clockin/clockout/{userAccount}", userAccount)
+                        .header(HttpHeaders.AUTHORIZATION, bearer(jwt))
+                        .retrieve()
+                        .body(ClockInApiResponse.class))
+                .message();
+    }
+
+    /** 改某一筆紀錄的工作內容，id 是 ClockInRecord.id。 */
+    public String editContent(int id, String content) {
+        return send(jwt -> clockInRestClient.patch()
+                        .uri("/clockin/content/{id}", id)
+                        .header(HttpHeaders.AUTHORIZATION, bearer(jwt))
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .body(Map.of("content", content))
+                        .retrieve()
+                        .body(ClockInApiResponse.class))
+                .message();
+    }
+
+    private <T> T read(Function<String, ClockInApiResponse> request, Class<T> type) {
+        ClockInApiResponse response = send(request);
+        return response.data() == null ? null : objectMapper.treeToValue(response.data(), type);
+    }
+
+    /**
+     * 帶 token 呼叫一次；遇到權限錯誤就丟掉 token 重新登入再試一次，
+     * 仍然失敗或業務失敗就轉成 ClockInApiException。
+     */
+    private ClockInApiResponse send(Function<String, ClockInApiResponse> request) {
+        ClockInApiResponse response = execute(request);
+        if (response != null && !response.result() && isAuthFailure(response.errorCode())) {
+            log.info("簽到系統回 {}，重新登入後重試", response.errorCode());
+            token = null;
+            response = execute(request);
+        }
+        if (response == null) {
+            throw new ClockInApiException("EmptyResponse", "簽到系統沒有回應內容");
+        }
+        if (!response.result()) {
+            throw new ClockInApiException(response.errorCode(), response.message());
+        }
+        return response;
+    }
+
+    private ClockInApiResponse execute(Function<String, ClockInApiResponse> request) {
+        try {
+            return request.apply(token());
+        } catch (RestClientException e) {
+            throw new ClockInApiException("呼叫簽到系統失敗: " + properties.getBaseUrl(), e);
+        }
+    }
+
+    private String token() {
+        String current = token;
+        if (current != null) {
+            return current;
+        }
+        synchronized (this) {
+            if (token == null) {
+                token = login();
+            }
+            return token;
+        }
+    }
+
+    private String login() {
+        if (properties.getAccount().isBlank() || properties.getPassword().isBlank()) {
+            throw new ClockInApiException(
+                    "MissingCredential", "沒有設定 BIRC_CLOCKIN_ACCOUNT / BIRC_CLOCKIN_PASSWORD");
+        }
+
+        MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
+        form.add("account", properties.getAccount());
+        form.add("password", properties.getPassword());
+
+        ResponseEntity<ClockInApiResponse> response;
+        try {
+            response = clockInRestClient.post()
+                    .uri("/login")
+                    .contentType(MediaType.APPLICATION_FORM_URLENCODED)
+                    .body(form)
+                    .retrieve()
+                    .toEntity(ClockInApiResponse.class);
+        } catch (RestClientException e) {
+            throw new ClockInApiException("登入簽到系統失敗，請確認帳號密碼: " + properties.getAccount(), e);
+        }
+
+        String issued = response.getHeaders().getFirst(AUTH_TOKEN_HEADER);
+        if (issued == null || issued.isBlank()) {
+            throw new ClockInApiException("LoginFail", "登入沒有拿到 " + AUTH_TOKEN_HEADER + " 標頭");
+        }
+        log.info("已登入簽到系統: {}", properties.getAccount());
+        return issued;
+    }
+
+    private static String bearer(String jwt) {
+        return "Bearer " + jwt;
+    }
+
+    /** year / month 是可選的，兩個都不帶就查全部月份，所以 null 要整個略過、不能帶空值。 */
+    private static UriBuilder period(UriBuilder builder, Integer year, Integer month) {
+        if (year != null) {
+            builder.queryParam("year", year);
+        }
+        if (month != null) {
+            builder.queryParam("month", month);
+        }
+        return builder;
+    }
+
+    private static boolean isAuthFailure(String errorCode) {
+        return errorCode != null && errorCode.contains("AccessDenied");
+    }
+}

package/templates/clockin/ClockInClientConfig.hbs

@@ -0,0 +1,41 @@
+package {{basePackage}}.config;
+
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.http.MediaType;
+import org.springframework.http.client.SimpleClientHttpRequestFactory;
+import org.springframework.http.converter.json.JacksonJsonHttpMessageConverter;
+import org.springframework.web.client.RestClient;
+
+@Configuration
+@RequiredArgsConstructor
+public class ClockInClientConfig {
+
+    private final ClockInProperties properties;
+
+    @Bean
+    public RestClient clockInRestClient() {
+        SimpleClientHttpRequestFactory requestFactory = new SimpleClientHttpRequestFactory();
+        requestFactory.setConnectTimeout(properties.getConnectTimeoutMs());
+        requestFactory.setReadTimeout(properties.getReadTimeoutMs());
+
+        return RestClient.builder()
+                .baseUrl(properties.getBaseUrl())
+                .requestFactory(requestFactory)
+                .configureMessageConverters(
+                        converters -> converters.registerDefaults().withJsonConverter(jsonConverter()))
+                .build();
+    }
+
+    /**
+     * 簽到系統的 JSON 回應標成 text/plain，預設的 JSON converter 不會接手，
+     * 所以把 text/plain 也算進可讀的型別。form-urlencoded 的登入不受影響，還是走 FormHttpMessageConverter。
+     */
+    private static JacksonJsonHttpMessageConverter jsonConverter() {
+        JacksonJsonHttpMessageConverter converter = new JacksonJsonHttpMessageConverter();
+        converter.setSupportedMediaTypes(List.of(MediaType.APPLICATION_JSON, MediaType.TEXT_PLAIN));
+        return converter;
+    }
+}