規格三巨頭

# 傳統做法的問題
API 文件說：POST /users 需要 email 欄位
資料庫有：users.email_address 欄位
測試程式：request.put("mail", value)  ← 三方各自維護，容易不一致

# entity_to_table_mapping.yml
entity_to_table_mapping:
  - 使用者: users

-- DDL (schema.sql)
CREATE TABLE users (user_id INT PRIMARY KEY, email VARCHAR(255) NOT NULL);

# api-spec.yml
paths:
  /users:
    post:
      summary: 建立使用者
      requestBody:
        properties:
          email:
            type: string

When (No Actor) 建立使用者, call table:       # ← 對應 API Spec（summary: 建立使用者）
  | email             |
  | alice@example.com |

Then 應該存在一個使用者, with table:           # ← 對應 Entity Spec（使用者 → users）
  | email             |
  | alice@example.com |

API Spec 新增必填欄位：requestBody.properties 加入 department (required)
            ↓
Lint 檢查 .feature：所有「建立使用者」的 call table 是否包含 department 欄位

DDL 欄位異動：users 資料表將 email 改為 email_address
            ↓
Lint 檢查 .feature：所有「使用者」的 with table 是否使用正確的欄位名稱

Phase 1: 產品經理定義 API Spec
         ↓
Phase 2: DBA 設計資料表，建立 Entity Spec
         ↓
Phase 3: QA 撰寫 .feature 測試（此時測試會失敗）
         ↓
Phase 4: 開發者實作功能，讓測試通過

src/test/resources/specs/api/
├── api-spec.yml          # 可拆分為多個檔案
├── auth-api.yml          # 例如依模組拆分
└── ...

openapi: 3.0.0
info:
  title: 我的應用程式 API
  version: 1.0.0

paths:
  /punch:
    post:
      summary: 打卡          # ← ApiCall 與 ResponseValidate 指令的識別依據
      operationId: punch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agentId
                - punchType
              properties:
                agentId:
                  type: integer
                punchType:
                  type: string
                  enum: [IN, OUT]
                punchTime:
                  type: string
                  format: date-time
      responses:
        "200":
          description: 打卡成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  recordId:
                    type: integer
                  agentId:
                    type: integer
                  punchType:
                    type: string
                  punchTime:
                    type: string
                  dailyWorkHours:
                    type: number

When (UID="$Agent.id") 打卡, call table:
  | agentId      | punchType | punchTime              |
  | $Agent.id    | IN        | @time("2026-01-27T09:00:00") |

Then 打卡(200)回應, with table:
  | recordId | agentId | punchType |
  | &isNotNull | 1       | IN        |

src/test/resources/specs/data/
└── primary/
    ├── entity_to_table_mapping.yml   # 實體對應
    ├── agents.sql                    # DDL（檔名不限，*.sql 皆可，可多檔）
    └── punch_records.sql

# entity_to_table_mapping.yml
entity_to_table_mapping:
  - 特務: agents
  - 打卡記錄: punch_records

-- agents.sql
CREATE TABLE agents (
    agent_id INT PRIMARY KEY,
    name     VARCHAR(100) NOT NULL,
    email    VARCHAR(255) NOT NULL
);

-- punch_records.sql
CREATE TABLE punch_records (
    record_id  INT PRIMARY KEY,
    agent_id   INT NOT NULL,
    punch_type VARCHAR(10),
    punch_time DATETIME
);

Given 準備一個特務, with table:
  | name    | email               |
  | Manager | manager@company.com |

Then 應該存在一個打卡記錄, with table:
  | agentId | punchType |
  | 1       | IN        |

Gherkin: agentId    → DB: agent_id
Gherkin: punchType  → DB: punch_type
Gherkin: punchTime  → DB: punch_time

src/test/resources/isa.yml

config:
  api:
    resource_path: specs/api                          # classpath 路徑，框架讀取用
    project_path: src/test/resources/specs/api        # 原始碼路徑，Lint 報錯用
  data:
    source:
      - name: primary
        resource_path: specs/data/primary             # classpath 路徑，框架讀取用
        project_path: src/test/resources/specs/data/primary  # 原始碼路徑，Lint 報錯用
        db_type: mssql

instructions:
  - name: Time control
    format: ^現在時間為 "(?P<time>[^"]+)"$
    instruction_type: time_control

  - name: Data preparation
    format: ^準備一個(?P<entity>[\u4e00-\u9fffa-zA-Z0-9_]+), with table:$
    instruction_type: entity_setup

  - name: API call
    format: ^\((?:No Actor|UID="(?P<userId>\$[\w.]+)")\) (?P<summary>.+?), call table:$
    instruction_type: api_call

  - name: Response validation with API summary and status code
    format: ^(?P<summary>.+?)\((?P<status_code>\d{3})\)回應,?\s*with table:$
    instruction_type: response_validate
    data_format: data_table

  - name: Database validation
    format: ^應該存在一個(?P<entity>[\u4e00-\u9fffa-zA-Z0-9_]+), with table:$
    instruction_type: entity_validate

  - name: Database non-existence validation
    format: ^應該不存在一個(?P<entity>[\u4e00-\u9fffa-zA-Z0-9_]+), with table:$
    instruction_type: entity_non_existence_validate

1. 在 API Spec 新增 path 定義
2. 撰寫 .feature 測試
3. 實作 API
4. 執行測試驗證

1. 更新 DDL（*.sql）
2. 若資料表名稱變更，更新 entity_to_table_mapping.yml 的對應
3. 若欄位名稱變更，更新 .feature 中的欄位名稱
4. 執行 Lint 檢查一致性
5. 執行測試驗證

1. 更新 api-spec.yml 中的 request/response schema
2. 更新相關 .feature 測試的預期結果
3. 修改 API 實作
4. 執行測試驗證

# ✅ 好的 summary：動詞 + 名詞，清楚描述操作
summary: 建立使用者
summary: 查詢訂單列表
summary: 更新商品庫存

# ❌ 避免的 summary：太短或太技術性
summary: create
summary: POST user
summary: updateInventoryById

# ✅ 使用業務團隊熟悉的名稱
entity_to_table_mapping:
  - 會員: members
  - 訂單: orders
  - 商品: products

# ❌ 避免使用技術名稱
entity_to_table_mapping:
  - member_entity: members
  - tbl_order: orders

# 在 CI 中加入 Lint 步驟
# TODO: 指令待補充

mvn test

dotnet test