常見驗證流程

API key only

項目	內容
主要資料表	api_keys
常見程式	ApiValidation::assertApiKey() / hasValidApiKey()
代表身份	client/app
user id 來源	無

規則：API key 只代表呼叫端合法，不代表登入使用者。

User session

項目	內容
主要資料表	api_sessions, users
常見程式	ApiValidation::assertApiSession() / hasValidApiSession()
代表身份	登入使用者
user id 來源	$usersDO->id

簡化流程：

$usersDO = null;
$passed = ApiValidation::hasValidApiSession($request, true, $usersDO);
if ($passed && $usersDO !== null) {
    $userId = (int)$usersDO->id;
}

Session access side effect

Legacy RestApiHelper::hasValidApiSession() 通過後不只是驗證 session，還會更新 users 的 access 欄位。搬移需要保留時，要把它視為 legacy session helper 的副作用，而不是單一 API 的 business logic。

欄位 / 行為	說明
users.iphone_last_access	歷史命名；不只 iPhone，Web / iOS / Android 等 valid API session 都會更新為本次 request 時間。
users.last_access_client	本次 API key 對應的平台，例如 web、ios、android。
task_queue.returnedQuoteService	若 user 是專家、iphone_last_access 超過 180 天且有 active service，legacy 會條件式寫入。

相近欄位不要混用：

• last_logged_in_time：偏登入 / 建 session 時間。
• last_login_ip_id：最後登入 IP。
• iphone_last_request：其他 request / phone confirm 相關時間，不是一般 session access。

Legacy 來源：get-lancer-php56/app/Controller/RestApiHelper.php::hasValidApiSession()。
New 搬移時若是為了對齊 legacy，可用專用 helper 或明確命名的 method 保留，例如 applyLegacyApiSessionSideEffects()；不要因為 endpoint 是 read-only 就自行移除。

Security hash

項目	內容
主要資料表	security_hashes, 目標資源表
常見程式	SecurityHash::getByHash($model, $hash)
代表身份	hash 授權的資源 owner
user id 來源	security_hashes.user_id

規則：hash 不是存在目標主表，而是存在 security_hashes。要再用 model + foreign_id 指回目標資源。

Hash first, session fallback

順序	規則	user id
1	有 hash 時先查 security_hashes	通過後用 security_hashes.user_id
2	hash 的 foreign_id 必須等於目標資源 id	不符合就不通過
3	hash 不通過才檢查 session	通過後用 $usersDO->id
4	hash 和 session 都失敗	回 invalid session