Server Metrics Access-log Drill-down 前端整合

本文件描述 cortex-management「系統監控 / 伺服器狀態」頁從 GET /api/admin/server-metrics 統計值下鑽至 GET /api/admin/access-logs 實際請求的最終契約。所有請求都需要 admin Bearer token。

Endpoint 與 response

GET /api/admin/access-logs

Response wrapper 不變：

type AccessLogListResponse = {
  total: number;
  items: AccessLogItem[];
};

total 是套用全部 filter 後的總筆數，不是當頁筆數；即使 offset 超出最後一頁，仍回正確 total。

新增 query parameters

參數	TypeScript	預設	行為
status_gte	number	無	100..599，篩選 status_code >= value（含）
status_lte	number	無	100..599，篩選 status_code <= value（含）
min_duration_ms	number	無	有限值且 >= 0，篩選 duration_ms >= value（含）；NULL 不符合
order_by	'timestamp_desc' \| 'duration_desc'	'timestamp_desc'	指定排序

四個參數可與既有 from_ts、to_ts、status、method、path、member_id、request_id、limit、offset 任意組合，條件間採 AND。若同時傳 status 與 status 級距，也必須同時符合。

order_by 的穩定排序：

• timestamp_desc：記錄時間新到舊，再以 id 新到舊。
• duration_desc：耗時大到小，NULL 排最後；相同耗時再以記錄時間、id 新到舊。

Server-metrics 下鑽呼叫

5xx 錯誤率：

GET /api/admin/access-logs?from_ts=<區間起>&to_ts=<區間迄>&status_gte=500&status_lte=599&order_by=timestamp_desc&limit=50&offset=0

4xx 錯誤率：

GET /api/admin/access-logs?from_ts=<區間起>&to_ts=<區間迄>&status_gte=400&status_lte=499&order_by=timestamp_desc&limit=50&offset=0

P95 延遲（平均、P50、P99 可套用相同模式）：

GET /api/admin/access-logs?from_ts=<區間起>&to_ts=<區間迄>&min_duration_ms=<p95值>&order_by=duration_desc&limit=50&offset=0

from_ts 是 inclusive，to_ts 是 exclusive。請沿用 server-metrics 所選日期換算出的相同 UTC 時間邊界，並以標準 ISO 8601 URL encoding 傳送。

時間欄位

AccessLogItem 新增：

type AccessLogItem = {
  // existing fields...
  timestamp: string;
  request_started_at: string | null;
  response_completed_at: string | null;
};

欄位語意：

• request_started_at：middleware 真實記錄的請求開始時間。
• response_completed_at：final response body 成功送出後的真實完成時間。
• timestamp：背景 writer 建立／持久化 access-log row 的時間，可能比 response completion 晚；不是 request start 或 response completion。

前端「請求時間／回應時間」兩欄應直接使用新欄位。Migration 117 上線前的歷史 row 兩欄都是 null；例外或未完整送出 response 的 row，其 response_completed_at 也可能為 null。遇到 null 建議顯示 —，不要用 timestamp ± duration_ms 冒充真實時間。若畫面仍顯示 timestamp，欄名應為「記錄時間」。

Validation errors

下列情況回 FastAPI 422 validation response：

• status_gte 或 status_lte 不在 100..599。
• status_gte > status_lte。
• min_duration_ms 不是有限數值或 < 0。
• order_by 不是 timestamp_desc 或 duration_desc。

部署相依

先套用 117_access_log_request_response_timestamps.sql，再部署 API。Schema 變更是 additive nullable，歷史資料不回填；application rollback 時保留欄位即可。