birc-generator 0.9.0 → 1.0.0

package/templates/clockin/ClockInController.hbs

@@ -0,0 +1,77 @@
+package {{basePackage}}.controller;
+
+import java.util.List;
+import java.util.Map;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PatchMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import {{basePackage}}.client.ClockInClient;
+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}}.web.Result;
+
+/**
+ * 直接轉打中心簽到系統，沒有自己的資料表。 要加自己的規則（例如限制只能簽自己的帳號）再補一層 service。
+ */
+@RestController
+@RequestMapping("/api/clockin")
+@RequiredArgsConstructor
+public class ClockInController {
+
+    private final ClockInClient clockInClient;
+
+    @GetMapping("/today")
+    public Result<List<UnclockedMember>> todayUnclocked() {
+        return Result.success(clockInClient.findTodayUnclocked());
+    }
+
+    @GetMapping("/me")
+    public Result<UserPermission> me() {
+        return Result.success(clockInClient.findMyPermission());
+    }
+
+    @GetMapping("/onduty")
+    public Result<List<OnDutyWeek>> onDuty() {
+        return Result.success(clockInClient.findAllOnDuty());
+    }
+
+    // year / month 不帶就是不限月份，跟簽到系統一致，不要在這裡補今天的年月當預設。
+    @GetMapping("/{userAccount}")
+    public Result<ClockInPage> memberRecords(
+            @PathVariable String userAccount,
+            @RequestParam(required = false) Integer year,
+            @RequestParam(required = false) Integer month,
+            @RequestParam(defaultValue = "1") int nowPage) {
+        return Result.success(clockInClient.findMemberRecords(userAccount, year, month, nowPage));
+    }
+
+    @GetMapping("/students")
+    public Result<List<ClockInRecord>> studentRecords(
+            @RequestParam(required = false) Integer year, @RequestParam(required = false) Integer month) {
+        return Result.success(clockInClient.findStudentRecords(year, month));
+    }
+
+    @PostMapping("/{stuNumber}")
+    public Result<String> clockIn(@PathVariable String stuNumber) {
+        return Result.success(clockInClient.clockIn(stuNumber));
+    }
+
+    @PatchMapping("/clockout/{userAccount}")
+    public Result<String> clockOut(@PathVariable String userAccount) {
+        return Result.success(clockInClient.clockOut(userAccount));
+    }
+
+    @PatchMapping("/content/{id}")
+    public Result<String> editContent(@PathVariable int id, @RequestBody Map<String, String> body) {
+        return Result.success(clockInClient.editContent(id, body.get("content")));
+    }
+}

package/templates/clockin/ClockInPage.hbs

@@ -0,0 +1,11 @@
+package {{basePackage}}.dto.clockin;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+
+/**
+ * 分頁的打卡紀錄。分頁欄位用包裝型別：/clockin/students 只回 list、不帶分頁，
+ * 那時這三個會是 null，用 int 會在反序列化就失敗。
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record ClockInPage(List<ClockInRecord> list, Integer totalPages, Long totalElements, Integer currentPage) {}

package/templates/clockin/ClockInProperties.hbs

@@ -0,0 +1,34 @@
+package {{basePackage}}.config;
+
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import lombok.Getter;
+import lombok.Setter;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+import org.springframework.validation.annotation.Validated;
+
+/**
+ * 中心簽到系統的連線設定，對應 application.yml 的 birc.clockin.*。
+ * account / password 沒有預設值，放環境變數；沒設就等到第一次呼叫才失敗，不擋專案啟動。
+ */
+@Getter
+@Setter
+@Validated
+@Component
+@ConfigurationProperties(prefix = "birc.clockin")
+public class ClockInProperties {
+
+    @NotBlank
+    private String baseUrl = "http://140.131.115.44:50035";
+
+    private String account = "";
+
+    private String password = "";
+
+    @Min(1)
+    private int connectTimeoutMs = 3000;
+
+    @Min(1)
+    private int readTimeoutMs = 10000;
+}

package/templates/clockin/ClockInRecord.hbs

@@ -0,0 +1,20 @@
+package {{basePackage}}.dto.clockin;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * 一筆打卡紀錄。date 是 yyyy-MM-dd，clockInTime / clockOutTime 是 yyyy/MM/dd HH:mm:ss，
+ * 兩種格式不同，所以先留字串，要算時間再自己 parse。
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record ClockInRecord(
+        Integer id,
+        String date,
+        String userAccount,
+        String name,
+        String clockInTime,
+        String clockOutTime,
+        Double hours,
+        String content,
+        @JsonProperty("isClockOut") Boolean isClockOut) {}

package/templates/clockin/MemberImage.hbs

@@ -0,0 +1,7 @@
+package {{basePackage}}.dto.clockin;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/** 成員圖檔。filePath 是相對路徑，要接檔案服務的網址（例如 http://140.131.115.44:50035）才拿得到。 */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record MemberImage(Integer fileNo, String fileName, String filePath) {}

package/templates/clockin/OnDutyWeek.hbs

@@ -0,0 +1,26 @@
+package {{basePackage}}.dto.clockin;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.List;
+
+/**
+ * 一週的值班。一週兩個人，所以欄位是 1 / 2 兩組，不是清單。
+ * startDate / deadline 是 yyyy/MM/dd。isFish / isDinner / isClear 是那週的值班工作有沒有完成。
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record OnDutyWeek(
+        Integer id,
+        Integer week,
+        String memberId1,
+        String userAccount1,
+        String name1,
+        String memberId2,
+        String userAccount2,
+        String name2,
+        String startDate,
+        String deadline,
+        @JsonProperty("isFish") Boolean isFish,
+        @JsonProperty("isDinner") Boolean isDinner,
+        @JsonProperty("isClear") Boolean isClear,
+        List<MemberImage> memberImg) {}

package/templates/clockin/UnclockedMember.hbs

@@ -0,0 +1,7 @@
+package {{basePackage}}.dto.clockin;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/** 今天還沒簽到的成員。category 是群組名，例如「後端群」。 */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record UnclockedMember(String userAccount, String name, String category) {}

package/templates/clockin/UserPermission.hbs

@@ -0,0 +1,11 @@
+package {{basePackage}}.dto.clockin;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+
+/**
+ * 目前登入者是誰、權限是什麼。authority 例如 Student、Admin；
+ * 要不要顯示全中心的紀錄看這個，不要自己猜。
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public record UserPermission(String userId, String userName, String authority, List<MemberImage> images) {}

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

@@ -0,0 +1,10 @@
+---
+# --- clockin（由 birc-generator add 產生） ---
+# 帳號密碼放環境變數，不要寫進這份檔案。沒設的話第一次呼叫才會失敗，不影響啟動。
+birc:
+  clockin:
+    base-url: ${BIRC_CLOCKIN_BASE_URL:http://140.131.115.44:50035}
+    account: ${BIRC_CLOCKIN_ACCOUNT:}
+    password: ${BIRC_CLOCKIN_PASSWORD:}
+    connect-timeout-ms: 3000
+    read-timeout-ms: 10000

package/templates/docker/docker-compose.prod.yml.hbs

@@ -44,6 +44,11 @@ services:
       TZ: ${TZ:-Asia/Taipei}
       SPRING_PROFILES_ACTIVE: prod
       FILE_STORAGE_PATH: /app/upload
+      CORS_ALLOWED_ORIGIN_PATTERNS: ${CORS_ALLOWED_ORIGIN_PATTERNS:-}
+      CORS_ALLOW_CREDENTIALS: ${CORS_ALLOW_CREDENTIALS:-false}
+      # 正式環境預設關掉 API 文件，要開再在部署環境覆寫。
+      API_DOCS_ENABLED: ${API_DOCS_ENABLED:-false}
+      JWT_SECRET: ${JWT_SECRET:-}
       SENTRY_DSN: ${SENTRY_DSN:-}
     volumes:
       - type: volume

package/templates/docker/docker-compose.yml.hbs

@@ -10,7 +10,9 @@ services:
       MYSQL_PASSWORD: ${DB_PASSWORD}
       TZ: ${TZ:-Asia/Taipei}
     ports:
-      - "${DB_PORT:-3306}:3306"
+      # 開發用資料庫綁 loopback，不要讓同網段的人直接連。要從別台連就改
+      # DB_BIND_HOST，或用 SSH tunnel。
+      - "${DB_BIND_HOST:-127.0.0.1}:${DB_PORT:-3306}:3306"
     volumes:
       - db_data:/var/lib/mysql
     command:
@@ -41,6 +43,10 @@ services:
       TZ: ${TZ:-Asia/Taipei}
       SPRING_PROFILES_ACTIVE: dev
       FILE_STORAGE_PATH: /app/upload
+      CORS_ALLOWED_ORIGIN_PATTERNS: ${CORS_ALLOWED_ORIGIN_PATTERNS:-}
+      CORS_ALLOW_CREDENTIALS: ${CORS_ALLOW_CREDENTIALS:-false}
+      API_DOCS_ENABLED: ${API_DOCS_ENABLED:-true}
+      JWT_SECRET: ${JWT_SECRET:-}
     volumes:
       - ./upload:/app/upload
     depends_on:

package/templates/docker/env.example.hbs

@@ -5,6 +5,8 @@ DB_DATABASE={{snakeCase projectNameKebab}}
 DB_USER={{snakeCase projectNameKebab}}_user
 DB_PASSWORD={{dbPassword}}
 DB_PORT=3306
+# 開發用資料庫預設只綁 127.0.0.1。要開放同網段連線才改成 0.0.0.0。
+DB_BIND_HOST=127.0.0.1
 
 # Spring Boot（bootRun 前先把 .env 載入目前 shell；Bash 用 source，PowerShell 見 README）
 DB_URL=jdbc:mysql://127.0.0.1:3306/{{snakeCase projectNameKebab}}
@@ -16,6 +18,19 @@ FILE_STORAGE_PATH=./upload
 LOG_LEVEL=INFO
 LOG_PATH=./logs
 
+# 前端 Origin，用逗號分隔（例如 http://localhost:5173）。留空 = 不開放跨來源。
+# 不要填 *，啟動會失敗。
+CORS_ALLOWED_ORIGIN_PATTERNS=
+# 只有改用 cookie 驗證時才設 true。
+CORS_ALLOW_CREDENTIALS=false
+
+# JWT 簽章金鑰，至少 32 個字元。裝了 auth 時 create / add 會寫進 .env；
+# clone 後若 .env 還是空的，第一次啟動也會自己補。不要把填好的 .env 提交。
+JWT_SECRET=
+
+# Swagger UI / OpenAPI JSON。正式環境設 false。
+API_DOCS_ENABLED=true
+
 # 正式環境映像（docker-compose.prod.yml）
 DOCKER_IMAGE={{snakeCase projectNameKebab}}_app
 APP_TAG=latest

package/templates/file-upload/FileExtensionUtils.hbs

@@ -11,10 +11,55 @@ public class FileExtensionUtils {
     public static final Set<String> IMAGE = Set.of("png", "jpg", "jpeg", "webp");
     public static final Set<String> DOCUMENT = Set.of("pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx");
 
+    private static final byte[] PNG = {(byte) 0x89, 'P', 'N', 'G'};
+    private static final byte[] JPEG = {(byte) 0xFF, (byte) 0xD8, (byte) 0xFF};
+    private static final byte[] RIFF = {'R', 'I', 'F', 'F'};
+    private static final byte[] WEBP = {'W', 'E', 'B', 'P'};
+    private static final byte[] PDF = {'%', 'P', 'D', 'F'};
+    private static final byte[] ZIP = {'P', 'K', 0x03, 0x04};
+    private static final byte[] OLE2 = {(byte) 0xD0, (byte) 0xCF, 0x11, (byte) 0xE0};
+
+    /**
+     * 讀開頭這麼多 bytes 就夠判斷所有支援的格式（webp 的簽章在 offset 8）。
+     */
+    public static final int HEADER_LENGTH = 12;
+
     public void assertAllowed(String fileName, Set<String> allowed) {
         String extension = FileUtils.getFileExtension(fileName).toLowerCase(Locale.ROOT);
         if (extension.isBlank() || !allowed.contains(extension)) {
             throw new FileExtensionIllegalException("不允許的副檔名：" + extension);
         }
     }
+
+    /**
+     * 副檔名白名單擋不住改名：把 evil.exe 改成 evil.png 就過了。這裡再比對檔案開頭的
+     * 格式簽章，內容跟副檔名對不起來就拒絕。沒有已知簽章的副檔名交給白名單判斷。
+     */
+    public void assertContentMatchesExtension(String fileName, byte[] header) {
+        String extension = FileUtils.getFileExtension(fileName).toLowerCase(Locale.ROOT);
+        boolean matches = switch (extension) {
+            case "png" -> startsWith(header, 0, PNG);
+            case "jpg", "jpeg" -> startsWith(header, 0, JPEG);
+            case "webp" -> startsWith(header, 0, RIFF) && startsWith(header, 8, WEBP);
+            case "pdf" -> startsWith(header, 0, PDF);
+            case "docx", "xlsx", "pptx" -> startsWith(header, 0, ZIP);
+            case "doc", "xls", "ppt" -> startsWith(header, 0, OLE2);
+            default -> true;
+        };
+        if (!matches) {
+            throw new FileExtensionIllegalException("檔案內容與副檔名 " + extension + " 不符");
+        }
+    }
+
+    private boolean startsWith(byte[] header, int offset, byte[] signature) {
+        if (header == null || header.length < offset + signature.length) {
+            return false;
+        }
+        for (int i = 0; i < signature.length; i++) {
+            if (header[offset + i] != signature[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
 }

package/templates/file-upload/FileExtensionUtilsTest.hbs

@@ -0,0 +1,48 @@
+package {{basePackage}}.util.file;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import java.util.Set;
+import org.junit.jupiter.api.Test;
+import {{basePackage}}.exception.file.FileExtensionIllegalException;
+
+/**
+ * 副檔名白名單擋不住改名，格式簽章才擋得住。這份測試守住兩層都在。
+ */
+class FileExtensionUtilsTest {
+
+    private static final byte[] PNG_HEADER = {(byte) 0x89, 'P', 'N', 'G', 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0, 0};
+    private static final byte[] WINDOWS_EXECUTABLE = {'M', 'Z', (byte) 0x90, 0, 0, 0, 0, 0, 0, 0, 0, 0};
+
+    @Test
+    void rejectsExtensionOutsideWhitelist() {
+        assertThrows(
+                FileExtensionIllegalException.class,
+                () -> FileExtensionUtils.assertAllowed("evil.exe", FileExtensionUtils.IMAGE));
+    }
+
+    @Test
+    void rejectsExecutableRenamedToPng() {
+        // 防住：只驗副檔名時，evil.exe 改名成 evil.png 就能上傳。
+        assertThrows(
+                FileExtensionIllegalException.class,
+                () -> FileExtensionUtils.assertContentMatchesExtension("evil.png", WINDOWS_EXECUTABLE));
+    }
+
+    @Test
+    void acceptsRealPng() {
+        assertDoesNotThrow(() -> FileExtensionUtils.assertAllowed("photo.png", FileExtensionUtils.IMAGE));
+        assertDoesNotThrow(() -> FileExtensionUtils.assertContentMatchesExtension("photo.png", PNG_HEADER));
+    }
+
+    @Test
+    void acceptsExtensionsWithoutKnownSignature() {
+        // 沒有已知簽章的格式不該被誤擋，交給白名單判斷就好。
+        assertDoesNotThrow(
+                () -> FileExtensionUtils.assertContentMatchesExtension("notes.txt", WINDOWS_EXECUTABLE));
+        assertThrows(
+                FileExtensionIllegalException.class,
+                () -> FileExtensionUtils.assertAllowed("notes.txt", Set.of("png")));
+    }
+}

package/templates/file-upload/FileStorageServiceImpl.hbs

@@ -1,6 +1,7 @@
 package {{basePackage}}.service.impl;
 
 import java.io.IOException;
+import java.io.InputStream;
 import java.io.UncheckedIOException;
 import java.nio.file.Files;
 import java.nio.file.Path;
@@ -40,6 +41,11 @@ public class FileStorageServiceImpl implements FileStorageService {
         FileExtensionUtils.assertAllowed(originalName, allowed);
 
         try {
+            try (InputStream in = file.getInputStream()) {
+                FileExtensionUtils.assertContentMatchesExtension(
+                        originalName, in.readNBytes(FileExtensionUtils.HEADER_LENGTH));
+            }
+
             Path baseDir = Path.of(properties.getBasePath()).toAbsolutePath().normalize();
             Path targetDir = baseDir;
             if (subDirectory != null) {

package/templates/multi-module/config/SecurityConfig.java.hbs

@@ -1,8 +1,12 @@
 package {{basePackage}}.config;
 
 import java.util.List;
+import java.util.regex.Pattern;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.Customizer;
 import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
@@ -10,6 +14,9 @@ import org.springframework.security.config.http.SessionCreationPolicy;
 import org.springframework.security.crypto.factory.PasswordEncoderFactories;
 import org.springframework.security.crypto.password.PasswordEncoder;
 import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.web.cors.CorsConfiguration;
+import org.springframework.web.cors.CorsConfigurationSource;
+import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
 
 @Configuration
 @EnableWebSecurity
@@ -17,12 +24,60 @@ import org.springframework.security.web.SecurityFilterChain;
 public class SecurityConfig {
 
     public static final List<String> PUBLIC_PATHS = List.of(
-            "/swagger-ui/**",
-            "/v3/api-docs/**",
             "/actuator/health",
             "/actuator/health/**"
     );
 
+    /**
+     * Swagger UI 與 OpenAPI JSON。開著等於把所有端點與 schema 攤開給任何人看，
+     * 正式環境用 API_DOCS_ENABLED=false 關掉。
+     */
+    public static final List<String> API_DOCS_PATHS = List.of(
+            "/swagger-ui/**",
+            "/swagger-ui.html",
+            "/v3/api-docs/**"
+    );
+
+    /**
+     * 合法的 Origin 寫法：scheme://host[:port]，host 最多只能有一個開頭的 *. 子網域萬用字元。
+     */
+    private static final Pattern ORIGIN_SHAPE =
+            Pattern.compile("^https?://(\\*\\.)?[a-z0-9-]+(\\.[a-z0-9-]+)*(:\\d+)?$", Pattern.CASE_INSENSITIVE);
+
+    /**
+     * 允許跨來源的前端 Origin，來自 application.yml 的 app.cors.allowed-origin-patterns
+     * （環境變數 CORS_ALLOWED_ORIGIN_PATTERNS），用逗號分隔。留空代表不開放跨來源。
+     */
+    private final List<String> allowedOriginPatterns;
+
+    /**
+     * 是否允許前端帶 cookie。本專案是 Bearer Token，Authorization 標頭不需要這個開關，
+     * 所以預設關閉；改成 session cookie 驗證時才需要打開。
+     */
+    private final boolean allowCredentials;
+
+    /**
+     * API 文件是否開放匿名瀏覽。預設開著方便開發與課堂展示，正式環境請關掉。
+     */
+    private final boolean apiDocsEnabled;
+
+    /**
+     * 由 feature 或專案自己提供，沒有就是空的，行為跟沒有這個機制時一樣。
+     */
+    private final List<SecurityCustomizer> customizers;
+
+    public SecurityConfig(
+            @Value("${app.cors.allowed-origin-patterns:}") List<String> allowedOriginPatterns,
+            @Value("${app.cors.allow-credentials:false}") boolean allowCredentials,
+            @Value("${app.api-docs.enabled:true}") boolean apiDocsEnabled,
+            ObjectProvider<SecurityCustomizer> customizers) {
+        this.allowedOriginPatterns =
+                allowedOriginPatterns.stream().map(String::trim).filter(pattern -> !pattern.isEmpty()).toList();
+        this.allowCredentials = allowCredentials;
+        this.apiDocsEnabled = apiDocsEnabled;
+        this.customizers = customizers.orderedStream().toList();
+    }
+
     @Bean
     public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
         // 本專案是 STATELESS + Bearer Token 的 REST API，CSRF 攻擊需要瀏覽器
@@ -30,17 +85,77 @@ public class SecurityConfig {
         // 若之後改成 session cookie 驗證、或開放瀏覽器直接呼叫的非公開寫入
         // 端點，必須把下面這行換成 CookieCsrfTokenRepository.withHttpOnlyFalse()
         // 並讓前端帶上 X-XSRF-TOKEN。
-        http.csrf(csrf -> csrf.disable())
+        // CORS 必須掛在 Security 這條 chain 上。只在 WebMvcConfigurer 寫
+        // addCorsMappings 沒有用：preflight 的 OPTIONS 會先被 Security 擋成 401。
+        http.cors(Customizer.withDefaults())
+                .csrf(csrf -> csrf.disable())
                 .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
-                .authorizeHttpRequests(auth -> auth
-                        .requestMatchers(PUBLIC_PATHS.toArray(String[]::new))
-                        .permitAll()
-                        .anyRequest()
-                        .authenticated());
+                .authorizeHttpRequests(auth -> {
+                    auth.requestMatchers(PUBLIC_PATHS.toArray(String[]::new)).permitAll();
+                    if (apiDocsEnabled) {
+                        auth.requestMatchers(API_DOCS_PATHS.toArray(String[]::new)).permitAll();
+                    }
+                    for (SecurityCustomizer customizer : customizers) {
+                        List<String> paths = customizer.publicPaths();
+                        if (!paths.isEmpty()) {
+                            auth.requestMatchers(paths.toArray(String[]::new)).permitAll();
+                        }
+                    }
+                    auth.anyRequest().authenticated();
+                });
+
+        for (SecurityCustomizer customizer : customizers) {
+            customizer.customize(http);
+        }
 
         return http.build();
     }
 
+    @Bean
+    public CorsConfigurationSource corsConfigurationSource() {
+        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+        if (allowedOriginPatterns.isEmpty()) {
+            return source;
+        }
+
+        for (String pattern : allowedOriginPatterns) {
+            if (isUnsafeOriginPattern(pattern)) {
+                throw new IllegalStateException(
+                        "app.cors.allowed-origin-patterns 不接受會放行任意網站的寫法：" + pattern
+                                + "。請列出實際的前端網域，例如 http://localhost:5173，"
+                                + "或單層子網域萬用字元 https://*.ntub.edu.tw");
+            }
+        }
+
+        CorsConfiguration config = new CorsConfiguration();
+        // 用 allowedOriginPatterns 而不是 allowedOrigins：後者不接受 https://*.ntub.edu.tw
+        // 這種子網域萬用字元，一設就會在啟動時丟例外。
+        config.setAllowedOriginPatterns(allowedOriginPatterns);
+        config.setAllowedMethods(List.of("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"));
+        config.setAllowedHeaders(List.of("*"));
+        config.setAllowCredentials(allowCredentials);
+        config.setMaxAge(3600L);
+        source.registerCorsConfiguration("/**", config);
+        return source;
+    }
+
+    /**
+     * 擋掉會放行任意網站的設定。只認明確的 Origin，或 https://*.ntub.edu.tw 這種
+     * 開頭單層子網域萬用字元；*、https://*、https://*.*、https://*.com 都會被拒絕。
+     * 允許任意 Origin 等於把 API 開放給任何網頁呼叫。
+     */
+    private static boolean isUnsafeOriginPattern(String pattern) {
+        if (!ORIGIN_SHAPE.matcher(pattern).matches()) {
+            return true;
+        }
+        if (!pattern.contains("*")) {
+            return false;
+        }
+        // *.com、*.tw 幾乎等於全開，萬用字元後面至少要有兩層實名網域。
+        String host = pattern.substring(pattern.indexOf("://") + "://".length()).replaceFirst(":\\d+$", "");
+        return host.substring("*.".length()).split("\\.").length < 2;
+    }
+
     @Bean
     public PasswordEncoder passwordEncoder() {
         return PasswordEncoderFactories.createDelegatingPasswordEncoder();

package/templates/multi-module/config/SecurityCustomizer.java.hbs

@@ -0,0 +1,24 @@
+package {{basePackage}}.config;
+
+import java.util.List;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+
+/**
+ * 讓 feature 把自己的東西掛進 SecurityFilterChain，不用改寫 SecurityConfig。
+ *
+ * <p>沒有任何實作時 SecurityConfig 的行為完全不變。要加登入、JWT、OAuth2 時，
+ * 在專案裡寫一個 {@code @Component} 實作這個介面即可：{@code publicPaths()} 回傳
+ * 不需要登入的路徑，{@code customize()} 拿到 HttpSecurity 掛 filter。
+ *
+ * <p>publicPaths 會在 {@code anyRequest().authenticated()} 之前套用——Spring Security
+ * 不允許在 anyRequest 之後再加 matcher，所以放行路徑一定要走這個方法，不要在
+ * customize() 裡自己呼叫 authorizeHttpRequests。
+ */
+public interface SecurityCustomizer {
+
+    default List<String> publicPaths() {
+        return List.of();
+    }
+
+    default void customize(HttpSecurity http) throws Exception {}
+}

package/templates/openapi/ApiDocsAccessTest.hbs

@@ -0,0 +1,60 @@
+package {{basePackage}};
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.web.server.LocalServerPort;
+
+/**
+ * API 文件開著等於公開所有端點與 schema。預設開著方便開發，但一定要關得掉，
+ * 而且關掉之後連匿名讀 /v3/api-docs 都不行。
+ */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+class ApiDocsAccessTest {
+
+    @LocalServerPort
+    private int port;
+
+    @Test
+    void apiDocsAreReadableByDefault() throws Exception {
+        assertEquals(200, ApiDocs.status(port));
+    }
+}
+
+@SpringBootTest(
+        webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
+        properties = "app.api-docs.enabled=false")
+class ApiDocsDisabledTest {
+
+    @LocalServerPort
+    private int port;
+
+    @Test
+    void apiDocsAreNotReadableWhenDisabled() throws Exception {
+        // 防住：開關失效、或有人把 swagger 路徑塞回 PUBLIC_PATHS。
+        // 註：Security 擋下會是 401、springdoc 關掉會是 404，從匿名端看不出是哪一層，
+        // 這條只保證「關掉之後讀不到」，兩層各自的責任由 SecurityConfig 的斷言分擔。
+        assertNotEquals(200, ApiDocs.status(port));
+    }
+}
+
+final class ApiDocs {
+
+    private ApiDocs() {}
+
+    static int status(int port) throws Exception {
+        HttpRequest request = HttpRequest.newBuilder()
+                .uri(URI.create("http://localhost:" + port + "/v3/api-docs"))
+                .GET()
+                .build();
+        HttpResponse<String> response =
+                HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
+        return response.statusCode();
+    }
+}

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

@@ -0,0 +1,8 @@
+---
+# --- openapi（由 birc-generator add 產生） ---
+# 跟 SecurityConfig 讀同一個開關：關掉時端點直接不存在，不是只擋在 Security 前面。
+springdoc:
+  api-docs:
+    enabled: ${API_DOCS_ENABLED:true}
+  swagger-ui:
+    enabled: ${API_DOCS_ENABLED:true}