┌─────────────────────────────────────────────────────────┐
│                  軟體開發標準程序目標                      │
├─────────────────────────────────────────────────────────┤
│  ✓ 確保可預期的品質輸出                                   │
│  ✓ 降低人員異動的衝擊                                     │
│  ✓ 提供可稽核的開發過程                                   │
│  ✓ 建立持續改善的基礎                                     │
│  ✓ 符合企業治理與法規要求                                  │
└─────────────────────────────────────────────────────────┘

需求階段 → 瀑布式（確保需求完整性）
     ↓
設計階段 → 瀑布式（架構穩定性）
     ↓
開發測試 → 敏捷式（快速迭代、持續交付）
     ↓
上線維運 → DevOps（自動化、持續監控）

## 功能需求範例：使用者登入

### FR-001：使用者登入功能

**需求描述**：
系統應提供使用者以帳號密碼進行身分驗證登入。

**前置條件**：
- 使用者已完成註冊
- 使用者帳號為啟用狀態

**處理流程**：
1. 使用者輸入帳號與密碼
2. 系統驗證帳號密碼正確性
3. 驗證成功後建立 Session
4. 導向至系統首頁

**驗收條件**：
- [ ] 正確帳密可成功登入
- [ ] 錯誤帳密顯示錯誤訊息
- [ ] 連續失敗 5 次鎖定帳號 30 分鐘
- [ ] 登入成功記錄稽核日誌

## BRD 標準章節

1. 文件資訊（版本、作者、審核）
2. 專案背景與目標
3. 業務流程現況（As-Is）
4. 業務流程目標（To-Be）
5. 效益分析（量化指標）
6. 風險評估
7. 時程與資源需求
8. 利害關係人簽核

## FRD 標準章節

1. 文件資訊
2. 功能清單與優先序
3. 使用案例（Use Case）
4. 業務規則（Business Rules）
5. 畫面流程（UI Flow）
6. 介面需求（外部系統整合）
7. 資料需求
8. 非功能性需求摘要
9. 術語定義

┌─────────────────────────────────────────────────────────┐
│                    Presentation Layer                    │
│              （Web / Mobile / API Gateway）               │
├─────────────────────────────────────────────────────────┤
│                    Application Layer                     │
│                （Business Logic / Services）              │
├─────────────────────────────────────────────────────────┤
│                      Domain Layer                        │
│              （Domain Model / Business Rules）            │
├─────────────────────────────────────────────────────────┤
│                   Infrastructure Layer                   │
│          （Database / External Services / MQ）            │
└─────────────────────────────────────────────────────────┘

## URL 命名規範

✅ 正確範例：
- GET    /api/v1/users              # 取得用戶列表
- GET    /api/v1/users/{id}         # 取得特定用戶
- POST   /api/v1/users              # 建立用戶
- PUT    /api/v1/users/{id}         # 更新用戶（完整）
- PATCH  /api/v1/users/{id}         # 更新用戶（部分）
- DELETE /api/v1/users/{id}         # 刪除用戶

❌ 錯誤範例：
- GET    /api/v1/getUsers           # 動詞不應出現在 URL
- POST   /api/v1/user/create        # 使用 HTTP Method 表達動作
- GET    /api/v1/Users              # 應使用小寫

{
  "success": true,
  "code": "0000",
  "message": "Success",
  "data": {
    "id": "U001",
    "name": "張三",
    "email": "zhang@example.com"
  },
  "timestamp": "2026-02-05T10:30:00Z",
  "traceId": "abc123-def456"
}

{
  "success": false,
  "code": "E1001",
  "message": "使用者不存在",
  "errors": [
    {
      "field": "userId",
      "message": "找不到指定的使用者 ID"
    }
  ],
  "timestamp": "2026-02-05T10:30:00Z",
  "traceId": "abc123-def456"
}

-- 資料表命名：使用大寫底線分隔
CREATE TABLE CUSTOMER_ORDER (
    -- 主鍵：表名_ID
    CUSTOMER_ORDER_ID   BIGINT PRIMARY KEY,
    
    -- 外鍵：關聯表名_ID
    CUSTOMER_ID         BIGINT NOT NULL,
    
    -- 一般欄位：語意清楚的名稱
    ORDER_DATE          DATE NOT NULL,
    ORDER_STATUS        VARCHAR(20) NOT NULL,
    TOTAL_AMOUNT        DECIMAL(15,2) NOT NULL,
    
    -- 標準稽核欄位
    CREATED_BY          VARCHAR(50) NOT NULL,
    CREATED_AT          TIMESTAMP NOT NULL,
    UPDATED_BY          VARCHAR(50),
    UPDATED_AT          TIMESTAMP,
    
    -- 軟刪除欄位
    IS_DELETED          CHAR(1) DEFAULT 'N',
    DELETED_AT          TIMESTAMP,
    DELETED_BY          VARCHAR(50)
);

-- 索引命名：IDX_表名_欄位名
CREATE INDEX IDX_CUSTOMER_ORDER_CUSTOMER_ID 
    ON CUSTOMER_ORDER(CUSTOMER_ID);

-- 外鍵命名：FK_表名_關聯表名
ALTER TABLE CUSTOMER_ORDER 
    ADD CONSTRAINT FK_CUSTOMER_ORDER_CUSTOMER 
    FOREIGN KEY (CUSTOMER_ID) REFERENCES CUSTOMER(CUSTOMER_ID);

## 效能設計檢核清單

### 資料庫層
- [ ] 查詢使用適當索引
- [ ] 避免 SELECT *
- [ ] 批次處理使用分頁
- [ ] 連線池配置適當大小

### 應用層
- [ ] 適當使用快取（Redis）
- [ ] 非同步處理長時間任務
- [ ] 避免 N+1 查詢問題
- [ ] API 回應啟用 GZIP

### 架構層
- [ ] 靜態資源使用 CDN
- [ ] 讀寫分離（主從架構）
- [ ] 水平擴展能力

package com.company.project.service;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

/**
 * 客戶服務類別
 * 
 * <p>負責處理客戶相關的業務邏輯，包含查詢、建立、更新等操作。</p>
 * 
 * @author 開發團隊
 * @since 1.0.0
 */
@Service
public class CustomerService {

    private static final int MAX_RETRY_COUNT = 3;
    private static final String DEFAULT_STATUS = "ACTIVE";
    
    private final CustomerRepository customerRepository;
    private final NotificationService notificationService;
    
    /**
     * 建構子注入依賴
     */
    public CustomerService(CustomerRepository customerRepository,
                          NotificationService notificationService) {
        this.customerRepository = customerRepository;
        this.notificationService = notificationService;
    }
    
    /**
     * 根據客戶 ID 查詢客戶資訊
     * 
     * @param customerId 客戶識別碼
     * @return 客戶資訊 DTO
     * @throws CustomerNotFoundException 當客戶不存在時拋出
     */
    public CustomerDTO findByCustomerId(String customerId) {
        // 參數驗證
        if (customerId == null || customerId.isBlank()) {
            throw new IllegalArgumentException("Customer ID cannot be empty");
        }
        
        // 查詢客戶
        Customer customer = customerRepository.findById(customerId)
            .orElseThrow(() -> new CustomerNotFoundException(customerId));
        
        // 轉換並返回
        return CustomerMapper.toDTO(customer);
    }
    
    /**
     * 建立新客戶
     * 
     * @param request 建立客戶請求
     * @return 建立後的客戶資訊
     */
    @Transactional
    public CustomerDTO createCustomer(CreateCustomerRequest request) {
        // 1. 驗證請求
        validateCreateRequest(request);
        
        // 2. 檢查重複
        checkDuplicateEmail(request.getEmail());
        
        // 3. 建立實體
        Customer customer = Customer.builder()
            .name(request.getName())
            .email(request.getEmail())
            .status(DEFAULT_STATUS)
            .build();
        
        // 4. 儲存
        Customer saved = customerRepository.save(customer);
        
        // 5. 發送通知
        notificationService.sendWelcomeEmail(saved);
        
        // 6. 返回結果
        return CustomerMapper.toDTO(saved);
    }
    
    private void validateCreateRequest(CreateCustomerRequest request) {
        // 驗證邏輯...
    }
    
    private void checkDuplicateEmail(String email) {
        // 重複檢查邏輯...
    }
}

/**
 * 類別層級 JavaDoc（必要）
 * - 說明類別職責
 * - 標註 @author 與 @since
 */

/**
 * 方法層級 JavaDoc（公開方法必要）
 * - 說明方法用途
 * - @param 說明參數
 * - @return 說明回傳值
 * - @throws 說明可能拋出的例外
 */

// 單行註解：說明複雜邏輯的「為什麼」
// 不要寫「做什麼」（程式碼本身應該自我說明）

/*
 * 多行註解：
 * 用於暫時停用的程式碼區塊
 * 或較長的說明文字
 */

// TODO: 待完成的功能（需標註負責人與預計完成時間）
// FIXME: 需要修復的問題
// HACK: 臨時解法，需要重構

src/main/java/com/company/project/
├── controller/                    # 控制器層
│   ├── CustomerController.java
│   ├── OrderController.java
│   └── dto/                       # Request/Response DTO
│       ├── request/
│       └── response/
│
├── application/                   # 應用層
│   ├── service/                   # 應用服務
│   │   ├── CustomerApplicationService.java
│   │   └── OrderApplicationService.java
│   ├── usecase/                   # 用例
│   └── mapper/                    # DTO 轉換器
│
├── domain/                        # 領域層
│   ├── model/                     # 領域模型
│   │   ├── Customer.java
│   │   └── Order.java
│   ├── service/                   # 領域服務
│   ├── repository/                # Repository 介面
│   ├── event/                     # 領域事件
│   └── exception/                 # 領域例外
│
├── infrastructure/                # 基礎設施層
│   ├── persistence/               # 資料庫存取
│   │   ├── repository/            # Repository 實作
│   │   ├── entity/                # JPA Entity
│   │   └── mapper/                # Entity 轉換
│   ├── external/                  # 外部服務整合
│   │   ├── payment/
│   │   └── notification/
│   └── config/                    # 設定類別
│
└── common/                        # 共用元件
    ├── exception/                 # 通用例外
    ├── util/                      # 工具類別
    └── constant/                  # 常數定義

// ✅ 良好的共用模組設計

// 1. 定義清楚的介面
public interface NotificationService {
    void send(Notification notification);
    NotificationResult getStatus(String notificationId);
}

// 2. 提供多種實作
@Service
@ConditionalOnProperty(name = "notification.type", havingValue = "email")
public class EmailNotificationService implements NotificationService {
    // Email 實作
}

@Service
@ConditionalOnProperty(name = "notification.type", havingValue = "sms")
public class SmsNotificationService implements NotificationService {
    // SMS 實作
}

// 3. 使用時依賴介面
@Service
public class OrderService {
    private final NotificationService notificationService;
    
    public OrderService(NotificationService notificationService) {
        this.notificationService = notificationService;
    }
}

## 輸入驗證
- [ ] 所有外部輸入都經過驗證
- [ ] 使用白名單而非黑名單驗證
- [ ] 限制輸入長度與格式
- [ ] 驗證檔案上傳類型與大小

## SQL Injection 防護
- [ ] 使用 Prepared Statement
- [ ] 避免字串拼接 SQL
- [ ] ORM 使用參數綁定

## XSS 防護
- [ ] 輸出編碼（HTML Encode）
- [ ] 使用 Content Security Policy
- [ ] HttpOnly Cookie

## 認證與授權
- [ ] 密碼加密儲存（bcrypt/scrypt）
- [ ] Session 管理安全
- [ ] 實作適當的權限檢查

## 敏感資料處理
- [ ] 傳輸加密（TLS 1.3）
- [ ] 儲存加密（AES-256）
- [ ] 日誌不記錄敏感資訊
- [ ] 記憶體中敏感資料及時清除

// ❌ 不安全的寫法 - SQL Injection
public User findUser(String username) {
    String sql = "SELECT * FROM users WHERE username = '" + username + "'";
    return jdbcTemplate.queryForObject(sql, User.class);
}

// ✅ 安全的寫法 - Prepared Statement
public User findUser(String username) {
    String sql = "SELECT * FROM users WHERE username = ?";
    return jdbcTemplate.queryForObject(sql, new Object[]{username}, User.class);
}

// ❌ 不安全的寫法 - 密碼明文比對
public boolean authenticate(String username, String password) {
    User user = userRepository.findByUsername(username);
    return user.getPassword().equals(password);  // 明文比對
}

// ✅ 安全的寫法 - 密碼雜湊比對
public boolean authenticate(String username, String password) {
    User user = userRepository.findByUsername(username);
    return passwordEncoder.matches(password, user.getPasswordHash());
}

// ❌ 不安全的寫法 - 日誌記錄敏感資訊
log.info("User login: username={}, password={}", username, password);

// ✅ 安全的寫法 - 遮罩敏感資訊
log.info("User login: username={}", username);
// 或使用遮罩
log.info("User login: username={}, password={}", username, maskPassword(password));

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Nested;
import static org.assertj.core.api.Assertions.*;
import static org.mockito.Mockito.*;

class CustomerServiceTest {

    private CustomerRepository customerRepository;
    private NotificationService notificationService;
    private CustomerService customerService;

    @BeforeEach
    void setUp() {
        customerRepository = mock(CustomerRepository.class);
        notificationService = mock(NotificationService.class);
        customerService = new CustomerService(customerRepository, notificationService);
    }

    @Nested
    @DisplayName("findByCustomerId 方法測試")
    class FindByCustomerIdTests {

        @Test
        @DisplayName("當客戶存在時，應返回客戶資訊")
        void shouldReturnCustomer_WhenCustomerExists() {
            // Given
            String customerId = "C001";
            Customer customer = Customer.builder()
                .id(customerId)
                .name("張三")
                .email("zhang@example.com")
                .build();
            when(customerRepository.findById(customerId))
                .thenReturn(Optional.of(customer));

            // When
            CustomerDTO result = customerService.findByCustomerId(customerId);

            // Then
            assertThat(result).isNotNull();
            assertThat(result.getId()).isEqualTo(customerId);
            assertThat(result.getName()).isEqualTo("張三");
            verify(customerRepository).findById(customerId);
        }

        @Test
        @DisplayName("當客戶不存在時，應拋出 CustomerNotFoundException")
        void shouldThrowException_WhenCustomerNotFound() {
            // Given
            String customerId = "INVALID";
            when(customerRepository.findById(customerId))
                .thenReturn(Optional.empty());

            // When & Then
            assertThatThrownBy(() -> customerService.findByCustomerId(customerId))
                .isInstanceOf(CustomerNotFoundException.class)
                .hasMessageContaining(customerId);
        }

        @Test
        @DisplayName("當客戶 ID 為空時，應拋出 IllegalArgumentException")
        void shouldThrowException_WhenCustomerIdIsEmpty() {
            // When & Then
            assertThatThrownBy(() -> customerService.findByCustomerId(""))
                .isInstanceOf(IllegalArgumentException.class)
                .hasMessage("Customer ID cannot be empty");
        }
    }

    @Nested
    @DisplayName("createCustomer 方法測試")
    class CreateCustomerTests {

        @Test
        @DisplayName("建立客戶成功時，應發送歡迎郵件")
        void shouldSendWelcomeEmail_WhenCustomerCreated() {
            // Given
            CreateCustomerRequest request = new CreateCustomerRequest("李四", "li@example.com");
            Customer savedCustomer = Customer.builder()
                .id("C002")
                .name("李四")
                .email("li@example.com")
                .build();
            when(customerRepository.save(any())).thenReturn(savedCustomer);

            // When
            customerService.createCustomer(request);

            // Then
            verify(notificationService).sendWelcomeEmail(savedCustomer);
        }
    }
}

@SpringBootTest
@AutoConfigureMockMvc
@Transactional
class CustomerControllerIntegrationTest {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private ObjectMapper objectMapper;

    @Autowired
    private CustomerRepository customerRepository;

    @Test
    @DisplayName("GET /api/v1/customers/{id} - 成功取得客戶")
    void getCustomer_Success() throws Exception {
        // Given
        Customer customer = customerRepository.save(
            Customer.builder()
                .name("測試客戶")
                .email("test@example.com")
                .build()
        );

        // When & Then
        mockMvc.perform(get("/api/v1/customers/{id}", customer.getId())
                .contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.success").value(true))
            .andExpect(jsonPath("$.data.name").value("測試客戶"))
            .andExpect(jsonPath("$.data.email").value("test@example.com"));
    }

    @Test
    @DisplayName("POST /api/v1/customers - 成功建立客戶")
    void createCustomer_Success() throws Exception {
        // Given
        CreateCustomerRequest request = new CreateCustomerRequest("新客戶", "new@example.com");

        // When & Then
        mockMvc.perform(post("/api/v1/customers")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(request)))
            .andExpect(status().isCreated())
            .andExpect(jsonPath("$.success").value(true))
            .andExpect(jsonPath("$.data.id").isNotEmpty());
    }
}

## 測試資料管理原則

### 1. 資料隔離
- 各測試案例使用獨立資料
- 測試後清理（或使用 @Transactional 自動 Rollback）
- 避免測試間的資料依賴

### 2. 敏感資料處理
- 禁止使用生產環境真實資料
- 個資欄位需脫敏處理
- 使用假資料產生器（Faker）

### 3. 資料版本控制
- 測試資料腳本納入版本控制
- 與程式碼一同維護
- 支援自動化初始化

// 使用 Java Faker 產生測試資料
import com.github.javafaker.Faker;

public class TestDataFactory {
    
    private static final Faker faker = new Faker(new Locale("zh-TW"));
    
    public static Customer createRandomCustomer() {
        return Customer.builder()
            .name(faker.name().fullName())
            .email(faker.internet().emailAddress())
            .phone(faker.phoneNumber().cellPhone())
            .address(faker.address().fullAddress())
            .birthDate(faker.date().birthday())
            .build();
    }
    
    public static List<Customer> createRandomCustomers(int count) {
        return IntStream.range(0, count)
            .mapToObj(i -> createRandomCustomer())
            .collect(Collectors.toList());
    }
}

## Bug 標題
[模組名稱] 簡述問題現象

## 環境資訊
- 環境：SIT / UAT / Production
- 版本：v1.2.3
- 瀏覽器：Chrome 120
- 作業系統：Windows 11

## 重現步驟
1. 開啟客戶查詢頁面
2. 輸入客戶 ID: C001
3. 點擊查詢按鈕

## 預期結果
顯示客戶詳細資訊

## 實際結果
顯示錯誤訊息「系統異常，請稍後再試」

## 截圖/日誌
[附上錯誤截圖或相關日誌]

## 影響範圍
- 影響功能：客戶查詢
- 影響用戶：所有使用者

## Commit Message 格式

<type>(<scope>): <subject>

<body>

<footer>

## Type 類型
- feat:     新功能
- fix:      Bug 修復
- docs:     文件更新
- style:    程式碼格式（不影響功能）
- refactor: 重構（不是新功能也不是修 Bug）
- perf:     效能優化
- test:     測試相關
- chore:    建置/工具相關

## 範例
feat(customer): 新增客戶查詢功能

- 實作根據 ID 查詢客戶 API
- 新增客戶不存在的錯誤處理
- 補充單元測試

Closes #123

## Code Review Checklist

### 功能正確性
- [ ] 程式碼符合需求規格
- [ ] 邊界條件處理完整
- [ ] 錯誤處理適當

### 程式碼品質
- [ ] 命名清楚有意義
- [ ] 程式碼簡潔易讀
- [ ] 沒有重複程式碼
- [ ] 適當的註解

### 測試
- [ ] 包含單元測試
- [ ] 測試覆蓋重要邏輯
- [ ] 測試案例有意義

### 安全性
- [ ] 輸入驗證完整
- [ ] 無硬編碼敏感資訊
- [ ] 權限檢查正確

### 效能
- [ ] 無明顯效能問題
- [ ] 資料庫查詢優化
- [ ] 資源正確釋放

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

範例：
1.0.0          # 正式版
1.0.1          # Patch 更新（Bug 修復）
1.1.0          # Minor 更新（新功能，向下相容）
2.0.0          # Major 更新（重大變更，不向下相容）
1.0.0-alpha.1  # 預發布版本
1.0.0-rc.1     # Release Candidate
1.0.0+20260205 # 包含建置資訊

# application.yml - 基礎設定（共用）
spring:
  application:
    name: customer-service
  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: Asia/Taipei

# application-dev.yml - 開發環境
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/dev_db
    username: dev_user
  
logging:
  level:
    root: DEBUG
    com.company: DEBUG

# application-prd.yml - 生產環境
spring:
  datasource:
    url: ${DB_URL}           # 從環境變數讀取
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
  
logging:
  level:
    root: INFO
    com.company: INFO

## 敏感設定禁止事項

❌ 禁止將以下資訊放入版本控制：
- 資料庫密碼
- API Key / Secret
- 私鑰 / 憑證
- 加密金鑰

## 建議方案

✅ 環境變數
- 透過 CI/CD 工具注入
- K8s Secrets

✅ 設定中心
- Spring Cloud Config
- HashiCorp Vault
- AWS Secrets Manager

✅ 設定檔範本
- 提供 application-prd.yml.template
- 實際設定檔加入 .gitignore

# .github/workflows/ci-cd.yml
name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

env:
  JAVA_VERSION: '21'
  MAVEN_OPTS: '-Xmx1024m'

jobs:
  build:
    name: Build & Test
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: 'temurin'
          cache: maven

      - name: Build with Maven
        run: mvn clean compile -B

      - name: Run Unit Tests
        run: mvn test -B

      - name: Run Integration Tests
        run: mvn verify -B -Pintegration-test

      - name: Upload Test Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: target/surefire-reports/

  code-quality:
    name: Code Quality Analysis
    runs-on: ubuntu-latest
    needs: build
    
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: 'temurin'
          cache: maven

      - name: SonarQube Scan
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: |
          mvn sonar:sonar \
            -Dsonar.projectKey=customer-service \
            -Dsonar.host.url=${{ secrets.SONAR_HOST_URL }} \
            -Dsonar.login=${{ secrets.SONAR_TOKEN }}

  security-scan:
    name: Security Scan
    runs-on: ubuntu-latest
    needs: build
    
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Run OWASP Dependency Check
        uses: dependency-check/Dependency-Check_Action@main
        with:
          project: 'customer-service'
          path: '.'
          format: 'HTML'
          
      - name: Upload Dependency Check Report
        uses: actions/upload-artifact@v4
        with:
          name: dependency-check-report
          path: reports/

  deploy-dev:
    name: Deploy to DEV
    runs-on: ubuntu-latest
    needs: [build, code-quality, security-scan]
    if: github.ref == 'refs/heads/develop'
    environment: development
    
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: 'temurin'
          cache: maven

      - name: Package Application
        run: mvn package -DskipTests -B

      - name: Build Docker Image
        run: |
          docker build -t customer-service:${{ github.sha }} .
          docker tag customer-service:${{ github.sha }} ${{ secrets.REGISTRY }}/customer-service:dev

      - name: Push to Registry
        run: |
          echo ${{ secrets.REGISTRY_PASSWORD }} | docker login -u ${{ secrets.REGISTRY_USERNAME }} --password-stdin ${{ secrets.REGISTRY }}
          docker push ${{ secrets.REGISTRY }}/customer-service:dev

      - name: Deploy to Kubernetes
        run: |
          kubectl set image deployment/customer-service \
            customer-service=${{ secrets.REGISTRY }}/customer-service:dev \
            --namespace=development

  deploy-production:
    name: Deploy to Production
    runs-on: ubuntu-latest
    needs: [build, code-quality, security-scan]
    if: github.ref == 'refs/heads/main'
    environment: production
    
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        
      # ... 生產部署步驟（需人工審核）

## 自動回滾觸發條件

1. **健康檢查失敗**
   - Pod 連續 3 次 Readiness Probe 失敗
   - 錯誤率超過閾值（> 5%）

2. **效能指標異常**
   - 回應時間超過 SLA（P95 > 2s）
   - CPU/Memory 使用率異常飆升

3. **業務指標異常**
   - 交易成功率下降
   - 關鍵 API 錯誤率上升

# 查看部署歷史
kubectl rollout history deployment/customer-service -n production

# 回滾到上一版本
kubectl rollout undo deployment/customer-service -n production

# 回滾到指定版本
kubectl rollout undo deployment/customer-service -n production --to-revision=3

# 查看回滾狀態
kubectl rollout status deployment/customer-service -n production

## 部署前檢核

### 程式碼品質
- [ ] 所有測試通過
- [ ] Code Review 完成
- [ ] 靜態分析無重大問題
- [ ] 弱點掃描通過

### 環境準備
- [ ] 資料庫 Migration 已準備
- [ ] 設定檔已更新
- [ ] 相依服務已就緒
- [ ] 監控告警已設定

### 部署計畫
- [ ] 部署時間已排定
- [ ] 相關人員已通知
- [ ] 回滾計畫已準備
- [ ] 緊急聯絡人已確認

## 部署後驗證

- [ ] 健康檢查通過
- [ ] 冒煙測試通過
- [ ] 關鍵指標正常
- [ ] 日誌無異常錯誤

## STRIDE 威脅分類

| 威脅類型 | 說明 | 對應安全屬性 | 防護措施範例 |
|---------|------|-------------|-------------|
| **S**poofing（偽冒） | 冒充他人身分 | 認證 | MFA、憑證驗證 |
| **T**ampering（竄改） | 未授權修改資料 | 完整性 | 數位簽章、MAC |
| **R**epudiation（否認） | 否認執行過的動作 | 不可否認性 | 稽核日誌、時戳 |
| **I**nformation Disclosure（資訊洩露） | 未授權存取資訊 | 機密性 | 加密、存取控制 |
| **D**enial of Service（阻斷服務） | 使服務無法使用 | 可用性 | 限流、CDN |
| **E**levation of Privilege（權限提升） | 獲取更高權限 | 授權 | 最小權限、RBAC |

# 安全掃描 Job
security-scan:
  name: Security Scan
  runs-on: ubuntu-latest
  
  steps:
    # SAST - 靜態程式碼分析
    - name: Run SonarQube SAST
      run: |
        mvn sonar:sonar \
          -Dsonar.projectKey=${{ env.PROJECT_KEY }} \
          -Dsonar.qualitygate.wait=true
    
    # SCA - 軟體組成分析
    - name: Run OWASP Dependency Check
      uses: dependency-check/Dependency-Check_Action@main
      with:
        project: 'my-project'
        path: '.'
        format: 'JSON'
        args: >
          --failOnCVSS 7
          --enableRetired
    
    # Container 掃描
    - name: Run Trivy Container Scan
      uses: aquasecurity/trivy-action@master
      with:
        image-ref: '${{ env.IMAGE_NAME }}:${{ github.sha }}'
        format: 'sarif'
        severity: 'CRITICAL,HIGH'
        exit-code: '1'
    
    # 上傳掃描結果
    - name: Upload Security Reports
      uses: github/codeql-action/upload-sarif@v2
      with:
        sarif_file: trivy-results.sarif

## 權限設計原則

### 1. 最小權限原則（Principle of Least Privilege）
- 僅授予完成工作所需的最小權限
- 定期檢視並移除不必要的權限

### 2. 職責分離（Separation of Duties）
- 重要操作需多人協作完成
- 開發人員不應有生產環境直接存取權

### 3. 角色型存取控制（RBAC）
- 透過角色管理權限，而非個人
- 角色設計應符合業務需求

// 角色定義
public enum Role {
    VIEWER,      // 只能檢視
    OPERATOR,    // 可執行一般操作
    MANAGER,     // 可管理資料
    ADMIN        // 系統管理員
}

// 權限定義
public enum Permission {
    CUSTOMER_READ,
    CUSTOMER_CREATE,
    CUSTOMER_UPDATE,
    CUSTOMER_DELETE,
    REPORT_VIEW,
    REPORT_EXPORT,
    SYSTEM_CONFIG
}

// 角色權限對應
public class RolePermissionConfig {
    
    private static final Map<Role, Set<Permission>> ROLE_PERMISSIONS = Map.of(
        Role.VIEWER, Set.of(
            Permission.CUSTOMER_READ,
            Permission.REPORT_VIEW
        ),
        Role.OPERATOR, Set.of(
            Permission.CUSTOMER_READ,
            Permission.CUSTOMER_CREATE,
            Permission.CUSTOMER_UPDATE,
            Permission.REPORT_VIEW,
            Permission.REPORT_EXPORT
        ),
        Role.MANAGER, Set.of(
            Permission.CUSTOMER_READ,
            Permission.CUSTOMER_CREATE,
            Permission.CUSTOMER_UPDATE,
            Permission.CUSTOMER_DELETE,
            Permission.REPORT_VIEW,
            Permission.REPORT_EXPORT
        ),
        Role.ADMIN, EnumSet.allOf(Permission.class)
    );
}

// 權限檢查 Annotation
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RequirePermission {
    Permission[] value();
}

// 使用範例
@RestController
@RequestMapping("/api/v1/customers")
public class CustomerController {
    
    @GetMapping
    @RequirePermission(Permission.CUSTOMER_READ)
    public List<CustomerDTO> listCustomers() {
        // ...
    }
    
    @DeleteMapping("/{id}")
    @RequirePermission(Permission.CUSTOMER_DELETE)
    public void deleteCustomer(@PathVariable String id) {
        // ...
    }
}

// 稽核日誌實體
@Entity
@Table(name = "AUDIT_LOG")
public class AuditLog {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "EVENT_TIME", nullable = false)
    private LocalDateTime eventTime;
    
    @Column(name = "USER_ID", nullable = false)
    private String userId;
    
    @Column(name = "USER_NAME")
    private String userName;
    
    @Column(name = "CLIENT_IP")
    private String clientIp;
    
    @Column(name = "ACTION", nullable = false)
    @Enumerated(EnumType.STRING)
    private AuditAction action;
    
    @Column(name = "RESOURCE_TYPE", nullable = false)
    private String resourceType;
    
    @Column(name = "RESOURCE_ID")
    private String resourceId;
    
    @Column(name = "DESCRIPTION", length = 2000)
    private String description;
    
    @Column(name = "REQUEST_DATA", columnDefinition = "CLOB")
    private String requestData;
    
    @Column(name = "RESPONSE_STATUS")
    private String responseStatus;
    
    @Column(name = "TRACE_ID")
    private String traceId;
}

// 稽核動作類型
public enum AuditAction {
    CREATE, READ, UPDATE, DELETE,
    LOGIN, LOGOUT, LOGIN_FAILED,
    EXPORT, IMPORT,
    APPROVE, REJECT,
    CONFIG_CHANGE
}

// AOP 自動記錄稽核日誌
@Aspect
@Component
@Slf4j
public class AuditLogAspect {
    
    private final AuditLogRepository auditLogRepository;
    
    @Around("@annotation(auditable)")
    public Object audit(ProceedingJoinPoint joinPoint, Auditable auditable) throws Throwable {
        AuditLog auditLog = new AuditLog();
        auditLog.setEventTime(LocalDateTime.now());
        auditLog.setUserId(SecurityContextHolder.getCurrentUserId());
        auditLog.setClientIp(RequestContextHolder.getClientIp());
        auditLog.setAction(auditable.action());
        auditLog.setResourceType(auditable.resourceType());
        auditLog.setTraceId(MDC.get("traceId"));
        
        try {
            Object result = joinPoint.proceed();
            auditLog.setResponseStatus("SUCCESS");
            return result;
        } catch (Exception e) {
            auditLog.setResponseStatus("FAILED: " + e.getMessage());
            throw e;
        } finally {
            auditLogRepository.save(auditLog);
        }
    }
}

## 日誌等級使用規範

| 等級 | 使用情境 | 範例 |
|------|---------|------|
| **ERROR** | 需要立即處理的錯誤 | 資料庫連線失敗、外部服務異常 |
| **WARN** | 潛在問題，但系統仍可運作 | 重試成功、降級處理 |
| **INFO** | 重要業務事件 | 交易完成、使用者登入 |
| **DEBUG** | 開發除錯資訊 | 方法參數、中間結果 |
| **TRACE** | 詳細追蹤資訊 | 迴圈內容、SQL 語句 |

## 日誌格式標準

```json
{
  "timestamp": "2026-02-05T10:30:00.123Z",
  "level": "INFO",
  "logger": "com.company.service.CustomerService",
  "message": "Customer created successfully",
  "traceId": "abc123-def456",
  "spanId": "span-789",
  "userId": "user001",
  "customerId": "C001",
  "duration": 150
}

> ⚠️ **實務注意事項**
> 1. 稽核日誌需保留至少 7 年（依法規要求）
> 2. 日誌應集中管理，便於查詢與分析
> 3. 重要操作需雙人覆核機制
> 4. 定期進行權限檢視（每季至少一次）

---

## 第十章：上線、維運與監控

### 10.1 上線檢核清單

#### 上線前檢核（Go-Live Checklist）

```markdown
## 一、程式碼品質 ✅

### 1.1 開發完成確認
- [ ] 所有功能開發完成
- [ ] 所有 User Story 已驗收
- [ ] Code Review 全數通過
- [ ] 技術債務已記錄（如有）

### 1.2 測試完成確認
- [ ] 單元測試通過（覆蓋率 ≥ 80%）
- [ ] 整合測試通過
- [ ] 系統測試通過
- [ ] UAT 簽核完成
- [ ] 效能測試通過（符合 NFR）
- [ ] 安全測試通過（無 Critical/High 弱點）

### 1.3 程式碼掃描
- [ ] SAST 掃描通過
- [ ] SCA 掃描通過（無已知高風險漏洞）
- [ ] Container 掃描通過

## 二、環境準備 ✅

### 2.1 基礎設施
- [ ] 伺服器資源已配置
- [ ] 網路設定已完成
- [ ] 防火牆規則已設定
- [ ] SSL 憑證已安裝
- [ ] DNS 設定已完成

### 2.2 應用環境
- [ ] 應用程式設定檔已準備
- [ ] 資料庫 Migration 已執行
- [ ] 快取服務已設定
- [ ] 訊息佇列已設定
- [ ] 外部服務連線已驗證

### 2.3 監控告警
- [ ] 監控 Dashboard 已設定
- [ ] 告警規則已設定
- [ ] 告警通知管道已驗證
- [ ] Log 收集已設定

## 三、文件與知識 ✅

### 3.1 文件準備
- [ ] Release Note 已撰寫
- [ ] 使用手冊已更新
- [ ] API 文件已更新
- [ ] 維運手冊已更新
- [ ] 回滾計畫已準備

### 3.2 教育訓練
- [ ] 客服人員已訓練
- [ ] 維運人員已訓練
- [ ] FAQ 已準備

## 四、上線執行 ✅

### 4.1 上線準備
- [ ] 上線時間已公告
- [ ] 相關人員已通知
- [ ] 緊急聯絡清單已確認
- [ ] War Room 已準備（如需要）

### 4.2 上線執行
- [ ] 資料備份完成
- [ ] 部署執行完成
- [ ] 冒煙測試通過
- [ ] 核心功能驗證通過

### 4.3 上線後監控
- [ ] 系統運作正常
- [ ] 效能指標正常
- [ ] 無異常錯誤
- [ ] 業務指標正常

# Prometheus AlertManager 規則範例
groups:
  - name: application-alerts
    rules:
      # 高錯誤率告警
      - alert: HighErrorRate
        expr: |
          sum(rate(http_requests_total{status=~"5.."}[5m])) 
          / sum(rate(http_requests_total[5m])) > 0.05
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "High error rate detected"
          description: "Error rate is {{ $value | humanizePercentage }} for the last 5 minutes"

      # 回應時間過長告警
      - alert: HighLatency
        expr: |
          histogram_quantile(0.95, 
            sum(rate(http_request_duration_seconds_bucket[5m])) by (le)
          ) > 2
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High latency detected"
          description: "P95 latency is {{ $value }}s"

      # Pod 重啟告警
      - alert: PodRestartingTooMuch
        expr: increase(kube_pod_container_status_restarts_total[1h]) > 3
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Pod restarting frequently"
          description: "Pod {{ $labels.pod }} has restarted {{ $value }} times in the last hour"

      # 記憶體使用率告警
      - alert: HighMemoryUsage
        expr: |
          container_memory_usage_bytes / container_spec_memory_limit_bytes > 0.85
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High memory usage"
          description: "Memory usage is {{ $value | humanizePercentage }}"

## Dashboard 設計原則

### 1. 概覽儀表板（Overview Dashboard）
- 系統整體健康狀態（紅綠燈）
- 關鍵 KPI 即時數值
- 重大告警列表

### 2. 應用儀表板（Application Dashboard）
- Request Rate（QPS）
- Error Rate
- Response Time（P50/P95/P99）
- Active Connections
- Thread Pool Status

### 3. 基礎設施儀表板（Infrastructure Dashboard）
- CPU / Memory / Disk 使用率
- Network I/O
- Container 狀態
- Pod 數量與狀態

### 4. 業務儀表板（Business Dashboard）
- 交易量趨勢
- 成功/失敗率
- 各功能使用統計

## 事件報告

### 基本資訊
- **事件編號**：INC-2026-0001
- **事件標題**：客戶查詢 API 回應逾時
- **發生時間**：2026-02-05 14:30 ~ 15:45
- **影響時間**：75 分鐘
- **事件等級**：P2
- **影響範圍**：所有使用客戶查詢功能的用戶

### 時間軸
| 時間 | 事件 |
|------|------|
| 14:30 | 監控告警觸發（API 回應時間 > 5s） |
| 14:35 | 維運人員確認問題 |
| 14:40 | 通知開發團隊 |
| 14:50 | 定位問題：資料庫 Slow Query |
| 15:00 | 執行緊急修復（新增索引） |
| 15:30 | 觀察修復效果 |
| 15:45 | 確認恢復正常，關閉事件 |

### 根本原因分析
**直接原因**：
- 客戶資料表缺少必要索引，導致全表掃描

**根本原因**：
- 需求評估時未考慮資料量成長
- Code Review 未檢查資料庫效能
- 缺乏 Slow Query 監控告警

### 五問分析（5 Whys）
1. **為什麼 API 回應逾時？**
   → 資料庫查詢耗時過長
2. **為什麼資料庫查詢耗時過長？**
   → 執行全表掃描
3. **為什麼執行全表掃描？**
   → 查詢欄位缺少索引
4. **為什麼缺少索引？**
   → 設計時未考慮效能
5. **為什麼設計時未考慮效能？**
   → 缺乏效能設計檢核流程

### 改善措施
| 項目 | 措施 | 負責人 | 預計完成日 | 狀態 |
|------|------|-------|-----------|------|
| 1 | 新增資料庫索引設計檢核清單 | 架構師 | 2026-02-15 | 進行中 |
| 2 | 建立 Slow Query 監控告警 | DevOps | 2026-02-10 | 已完成 |
| 3 | 新增 Code Review 效能檢核項目 | TL | 2026-02-12 | 進行中 |
| 4 | 執行現有 SQL 效能檢視 | DBA | 2026-02-20 | 待開始 |

### 經驗教訓
1. 資料量成長需在設計階段評估
2. 建立 Slow Query 監控的重要性
3. Code Review 需包含效能面向

# 專案名稱

> 專案簡短描述（一句話說明專案用途）

## 目錄

- [功能特色](#功能特色)
- [系統需求](#系統需求)
- [快速開始](#快速開始)
- [設定說明](#設定說明)
- [API 文件](#api-文件)
- [開發指南](#開發指南)
- [測試](#測試)
- [部署](#部署)
- [貢獻指南](#貢獻指南)
- [版本歷程](#版本歷程)

## 功能特色

- ✅ 功能 1：說明
- ✅ 功能 2：說明
- ✅ 功能 3：說明

## 系統需求

- Java 21+
- Maven 3.9+
- PostgreSQL 15+
- Redis 7+

## 快速開始

### 1. 複製專案
```bash
git clone https://github.com/company/project.git
cd project

cp .env.example .env
# 編輯 .env 設定資料庫連線等資訊

mvn spring-boot:run

curl http://localhost:8080/actuator/health

# 單元測試
mvn test

# 整合測試
mvn verify -Pintegration-test

# 測試覆蓋率報告
mvn jacoco:report

### 11.2 文件維護責任

#### 文件維護 RACI

| 文件類型 | 撰寫(R) | 審核(A) | 諮詢(C) | 知會(I) |
|---------|--------|--------|--------|--------|
| BRD/FRD | BA | PM | SA、用戶 | 開發團隊 |
| SAD | 架構師 | 技術主管 | SA、開發人員 | 全團隊 |
| API Spec | 開發人員 | SA | 前端、測試 | PM |
| Test Plan | QA | QA主管 | SA、開發 | PM |
| 部署手冊 | DevOps | 技術主管 | 維運 | 開發團隊 |

#### 文件版本控制

```markdown
## 文件版本控制原則

### 1. 版本編號規則
- 格式：v{主版本}.{次版本}
- 範例：v1.0、v1.1、v2.0
- 重大變更升主版本，小幅修改升次版本

### 2. 變更記錄
每份文件需包含變更記錄表：

| 版本 | 日期 | 修改人 | 修改內容 |
|------|------|-------|---------|
| v1.0 | 2026-01-15 | 張三 | 初版 |
| v1.1 | 2026-02-05 | 李四 | 新增 API 規格 |

### 3. 文件審核流程
1. 撰寫完成
2. 自我檢查
3. 同儕審查
4. 主管審核
5. 發布

## 知識交接檢核清單

### 一、文件交接
- [ ] 所有文件已更新至最新版本
- [ ] 文件存放位置已說明
- [ ] 權限已移交

### 二、系統知識
- [ ] 系統架構已說明
- [ ] 關鍵業務邏輯已說明
- [ ] 已知問題與解法已說明
- [ ] 技術債務已列舉

### 三、維運知識
- [ ] 部署流程已說明
- [ ] 監控設定已說明
- [ ] 常見問題處理已說明
- [ ] 緊急聯絡人已更新

### 四、權限交接
- [ ] 程式碼倉庫權限
- [ ] 伺服器存取權限
- [ ] 監控系統權限
- [ ] 文件系統權限

### 五、實際演練
- [ ] 完成一次部署
- [ ] 處理一個問題
- [ ] 回答交接問題

## Sprint/Release 回顧會議記錄

### 會議資訊
- **日期**：2026-02-05
- **Sprint/版本**：Sprint 10 / v1.5.0
- **參與者**：團隊全員

### What Went Well（做得好的）
1. ✅ CI/CD Pipeline 穩定，部署零失敗
2. ✅ Code Review 落實，程式碼品質提升
3. ✅ 團隊溝通順暢

### What Didn't Go Well（待改善的）
1. ❌ 需求變更頻繁，影響開發進度
2. ❌ 測試環境不穩定
3. ❌ 文件更新落後

### Action Items（改善行動）
| 項目 | 行動 | 負責人 | 完成日 |
|------|------|-------|-------|
| 1 | 與 PM 討論需求凍結機制 | TL | 2026-02-10 |
| 2 | 優化測試環境自動化 | DevOps | 2026-02-15 |
| 3 | 建立文件更新提醒機制 | SA | 2026-02-12 |

### 團隊滿意度
- 專案進度：⭐⭐⭐⭐☆
- 程式碼品質：⭐⭐⭐⭐⭐
- 團隊合作：⭐⭐⭐⭐⭐
- 工作負荷：⭐⭐⭐☆☆

## 流程優化方向

### 1. 自動化
- 增加測試自動化覆蓋
- 自動化部署流程
- 自動化文件生成
- 自動化程式碼品質檢查

### 2. 標準化
- 建立程式碼範本
- 統一開發環境
- 標準化 API 設計
- 統一日誌格式

### 3. 可視化
- 建立即時監控儀表板
- 專案進度看板
- 效能指標趨勢圖
- 品質指標報表

### 4. 簡化
- 減少不必要的審核流程
- 簡化部署步驟
- 精簡文件範本
- 移除冗餘工具

## 軟體開發成熟度等級

### Level 1 - Initial（初始級）
- 流程不可預測
- 依賴個人能力
- 缺乏文件化

### Level 2 - Managed（管理級）
- 專案層級流程已建立
- 基本版本控制
- 有基本測試

### Level 3 - Defined（定義級）
- 組織層級標準流程
- 流程文件化
- 持續整合已實施

### Level 4 - Quantitatively Managed（量化管理級）
- 流程效能可量測
- 使用數據做決策
- 預防性品質管理

### Level 5 - Optimizing（最佳化級）
- 持續改善機制
- 創新與最佳實務分享
- 自動化程度高

## 開發開始前

### 需求確認
- [ ] 需求文件已閱讀並理解
- [ ] 不清楚的需求已釐清
- [ ] 技術可行性已評估
- [ ] 工時已估算

### 設計確認
- [ ] 架構設計已完成
- [ ] API 規格已定義
- [ ] 資料庫設計已審核
- [ ] 相關人員已對齊

## 開發進行中

### 程式碼品質
- [ ] 遵循命名規範
- [ ] 適當的註解
- [ ] 無重複程式碼
- [ ] 無硬編碼

### 測試
- [ ] 單元測試已撰寫
- [ ] 測試覆蓋核心邏輯
- [ ] 測試可重複執行

### 安全性
- [ ] 輸入驗證
- [ ] SQL Injection 防護
- [ ] 無敏感資訊在日誌

## 開發完成後

### 提交前
- [ ] 本地測試全數通過
- [ ] 程式碼已格式化
- [ ] Commit Message 符合規範
- [ ] 無不必要的檔案

### Code Review
- [ ] PR 描述清楚
- [ ] 變更範圍適當
- [ ] 已處理 Review 意見

## 部署前

### 程式碼
- [ ] 所有測試通過
- [ ] Code Review 完成
- [ ] 版本號已更新
- [ ] CHANGELOG 已更新

### 環境
- [ ] 設定檔已準備
- [ ] 資料庫 Migration 已準備
- [ ] 相依服務已確認

### 計畫
- [ ] 部署步驟已確認
- [ ] 回滾計畫已準備
- [ ] 相關人員已通知

## 部署中

### 執行
- [ ] 備份已完成
- [ ] 部署腳本執行成功
- [ ] 健康檢查通過

### 驗證
- [ ] 冒煙測試通過
- [ ] 核心功能驗證
- [ ] 日誌無異常

## 部署後

### 監控
- [ ] 監控指標正常
- [ ] 無異常告警
- [ ] 效能指標正常

### 收尾
- [ ] 部署結果已通知
- [ ] 文件已更新
- [ ] 經驗已記錄

## Code Review Checklist

### 功能正確性
- [ ] 實作符合需求
- [ ] 邊界條件處理完整
- [ ] 錯誤處理適當

### 程式碼品質
- [ ] 命名清楚有意義
- [ ] 程式碼簡潔易讀
- [ ] 無重複程式碼（DRY）
- [ ] 函式職責單一
- [ ] 適當的抽象層級

### 測試
- [ ] 有對應的測試案例
- [ ] 測試涵蓋重要邏輯
- [ ] 測試案例易讀易懂

### 安全性
- [ ] 輸入驗證完整
- [ ] 無 SQL Injection 風險
- [ ] 無硬編碼敏感資訊
- [ ] 權限檢查正確

### 效能
- [ ] 無明顯效能問題
- [ ] 資料庫查詢已優化
- [ ] 資源正確釋放
- [ ] 無 N+1 查詢

### 維護性
- [ ] 適當的註解
- [ ] 符合專案規範
- [ ] 可設定性適當
- [ ] 日誌記錄適當

## 安全性檢查清單

### 認證與授權
- [ ] 實作適當的認證機制
- [ ] 密碼加密儲存（bcrypt/scrypt）
- [ ] Session 管理安全
- [ ] 實作 RBAC 權限控制
- [ ] 敏感操作需重新驗證

### 輸入驗證
- [ ] 所有輸入經過驗證
- [ ] 使用白名單驗證
- [ ] 檔案上傳類型/大小限制
- [ ] API 參數驗證

### 資料保護
- [ ] 傳輸加密（TLS 1.3）
- [ ] 敏感資料加密儲存
- [ ] 個資適當遮罩
- [ ] 定期清理不需要的資料

### 注入防護
- [ ] SQL 使用 Prepared Statement
- [ ] 避免 OS Command Injection
- [ ] XSS 防護（輸出編碼）
- [ ] CSRF Token 驗證

### 日誌與監控
- [ ] 登入/登出記錄
- [ ] 敏感操作稽核
- [ ] 異常存取監控
- [ ] 日誌不含敏感資訊

### 設定安全
- [ ] 關閉不必要的服務
- [ ] 移除預設帳號密碼
- [ ] 錯誤訊息不洩漏系統資訊
- [ ] 安全的 HTTP Headers