diff --git a/docs_v1.0/API_WORKSPACE/modules/05_process.md b/docs_v1.0/API_WORKSPACE/modules/05_process.md index f08b1a9..a3dd3e6 100644 --- a/docs_v1.0/API_WORKSPACE/modules/05_process.md +++ b/docs_v1.0/API_WORKSPACE/modules/05_process.md @@ -51,8 +51,8 @@ curl -s -X POST "$API/api/v1/file/$FILE_UUID/process" \ | `success` | boolean | Always true on 200 | | `job_id` | integer | Monitor job ID (for job tracking) | | `file_uuid` | string | 32-char hex UUID of the file | -| `status` | string | `"processing"` | -| `pids` | integer[] | Process IDs of started processors | +| `status` | string | `"queued"` — file enters the FIFO queue | +| `pids` | integer[] | Process IDs of started processors (empty for queued) | | `message` | string | Human-readable status | #### Error Responses @@ -237,6 +237,105 @@ curl -s "$API/api/v1/jobs" -H "X-API-Key: $KEY" | jq '{count, jobs: [.jobs[] | { | `page` | integer | Current page number | | `page_size` | integer | Jobs per page | +### `GET /api/v1/job/:uuid` + +**Auth**: Required +**Scope**: file-level + +Get detailed information about a specific processing job, including its queue position. + +#### Response (200) + +```json +{ + "id": 51, + "uuid": "c36f35685177c981aa139b66bbbccc5b", + "status": "queued", + "current_processor": null, + "progress_current": 0, + "progress_total": 0, + "processors": [], + "created_at": "2026-06-22 23:08:48.497018", + "started_at": null, + "updated_at": null, + "queue_position": 3 +} +``` + +| Field | Type | Description | +|-------|------|-------------| +| `id` | integer | Monitor job ID | +| `uuid` | string | File UUID | +| `status` | string | `"pending"`, `"queued"`, `"running"`, `"completed"`, `"failed"` | +| `current_processor` | string | Currently active processor, or null | +| `progress_current` | integer | Current progress count | +| `progress_total` | integer | Total progress count | +| `processors` | array | Processor list | +| `created_at` | string | Job creation timestamp | +| `started_at` | string | Processing start timestamp, or null | +| `updated_at` | string | Last update timestamp, or null | +| `queue_position` | integer | Position in FIFO queue (null if not pending/queued) | + +--- + +### Status Lifecycle + +``` +register ──→ pending + │ + trigger (POST /process) + │ + queued ←── queue_position counts jobs ahead + │ + worker picks up + │ + processing + │ + ┌────────┴────────┐ + ▼ ▼ + completed failed + │ + checkin ──→ indexed + checkout ──→ checked_out +``` + +| Status | Meaning | +|--------|---------| +| `pending` | File registered, not yet triggered | +| `queued` | Triggered, waiting for worker in FIFO queue | +| `processing` | Worker actively processing | +| `completed` | All processors finished successfully | +| `failed` | One or more essential processors failed | +| `indexed` | Post-processing checkin complete | +| `checked_out` | User checked out the file | + +Queue order is FIFO (`created_at ASC`). The `GET /api/v1/job/:uuid` endpoint returns `queue_position` showing how many jobs are ahead. + +### Frontend Status Mapping + +When displaying file status in the frontend list (e.g. after `GET /api/v1/files/scan`), map the `status` field as follows: + +| DB Status | Status Label | Filter: 待處理 | Filter: 處理中 | Count: pendingCount | Count: processingCount | +|-----------|-------------|----------------|----------------|---------------------|-----------------------| +| `unregistered` | 未註冊 | No | No | No | No | +| `registered` | 待處理 | **Yes** | No | **Yes** | No | +| `pending` | 待處理 | **Yes** | No | **Yes** | No | +| `queued` | 排隊中 | **Yes** | **Yes** | **Yes** | **Yes** | +| `processing` | 處理中 | No | **Yes** | No | **Yes** | +| `completed` | 已完成 | No | No | No | No | +| `failed` | 處理失敗 | No | No | No | No | +| `indexed` | 已入庫 | No | No | No | No | + +**`queued` 的特殊處理**: +- `statusLabel` → 顯示「排隊中」,加 `ms-badge-warn` 樣式(黃色) +- `filterPending` → 應包含 `queued`,讓它在「待處理」filter 可見 +- `pendingCount` + `processingCount` → 兩者都應包含 `queued`,因它既是「待處理」也是「正在排隊」 +- 在 `refreshAllStatus` / `loadFiles` 中,如果檔案狀態是 `queued`,應顯示簡單的排隊訊息(無需 polling progress) +- 當 worker pickup 後,狀態會變為 `processing`,此時 `refreshAllStatus` 會自動偵測到並開始 polling progress +- 也可以提供一個「queue_position」顯示:呼叫 `GET /api/v1/job/:uuid` 取得排在第幾位 + +--- + ### `GET /api/v1/file/:file_uuid/processor-counts` **Auth**: Required @@ -407,4 +506,4 @@ curl -s -X POST "$API/api/v1/file/$FILE_UUID/complete" \ Phase 1 (`/phase1`) combines store-asrx + rule1 + vectorize into one call. --- -*Updated: 2026-06-20 12:00:00* +*Updated: 2026-06-23 — Added queued status, FIFO queue order, queue_position in job detail, frontend status mapping table* diff --git a/docs_v1.0/doc/05_process.html b/docs_v1.0/doc/05_process.html index c250249..17120e8 100644 --- a/docs_v1.0/doc/05_process.html +++ b/docs_v1.0/doc/05_process.html @@ -119,12 +119,12 @@ curl -s -X
status"processing""queued" — file enters the FIFO queuepidsmessageGET /api/v1/job/:uuidAuth: Required +Scope: file-level
+Get detailed information about a specific processing job, including its queue position.
+{
+ "id": 51,
+ "uuid": "c36f35685177c981aa139b66bbbccc5b",
+ "status": "queued",
+ "current_processor": null,
+ "progress_current": 0,
+ "progress_total": 0,
+ "processors": [],
+ "created_at": "2026-06-22 23:08:48.497018",
+ "started_at": null,
+ "updated_at": null,
+ "queue_position": 3
+}
+| Field | +Type | +Description | +
|---|---|---|
id |
+integer | +Monitor job ID | +
uuid |
+string | +File UUID | +
status |
+string | +"pending", "queued", "running", "completed", "failed" |
+
current_processor |
+string | +Currently active processor, or null | +
progress_current |
+integer | +Current progress count | +
progress_total |
+integer | +Total progress count | +
processors |
+array | +Processor list | +
created_at |
+string | +Job creation timestamp | +
started_at |
+string | +Processing start timestamp, or null | +
updated_at |
+string | +Last update timestamp, or null | +
queue_position |
+integer | +Position in FIFO queue (null if not pending/queued) | +
register ──→ pending
+ │
+ trigger (POST /process)
+ │
+ queued ←── queue_position counts jobs ahead
+ │
+ worker picks up
+ │
+ processing
+ │
+ ┌────────┴────────┐
+ ▼ ▼
+ completed failed
+ │
+ checkin ──→ indexed
+ checkout ──→ checked_out
+| Status | +Meaning | +
|---|---|
pending |
+File registered, not yet triggered | +
queued |
+Triggered, waiting for worker in FIFO queue | +
processing |
+Worker actively processing | +
completed |
+All processors finished successfully | +
failed |
+One or more essential processors failed | +
indexed |
+Post-processing checkin complete | +
checked_out |
+User checked out the file | +
Queue order is FIFO (created_at ASC). The GET /api/v1/job/:uuid endpoint returns queue_position showing how many jobs are ahead.
When displaying file status in the frontend list (e.g. after GET /api/v1/files/scan), map the status field as follows:
| DB Status | +Status Label | +Filter: 待處理 | +Filter: 處理中 | +Count: pendingCount | +Count: processingCount | +
|---|---|---|---|---|---|
unregistered |
+未註冊 | +No | +No | +No | +No | +
registered |
+待處理 | +Yes | +No | +Yes | +No | +
pending |
+待處理 | +Yes | +No | +Yes | +No | +
queued |
+排隊中 | +Yes | +Yes | +Yes | +Yes | +
processing |
+處理中 | +No | +Yes | +No | +Yes | +
completed |
+已完成 | +No | +No | +No | +No | +
failed |
+處理失敗 | +No | +No | +No | +No | +
indexed |
+已入庫 | +No | +No | +No | +No | +
queued 的特殊處理:
+- statusLabel → 顯示「排隊中」,加 ms-badge-warn 樣式(黃色)
+- filterPending → 應包含 queued,讓它在「待處理」filter 可見
+- pendingCount + processingCount → 兩者都應包含 queued,因它既是「待處理」也是「正在排隊」
+- 在 refreshAllStatus / loadFiles 中,如果檔案狀態是 queued,應顯示簡單的排隊訊息(無需 polling progress)
+- 當 worker pickup 後,狀態會變為 processing,此時 refreshAllStatus 會自動偵測到並開始 polling progress
+- 也可以提供一個「queue_position」顯示:呼叫 GET /api/v1/job/:uuid 取得排在第幾位
GET /api/v1/file/:file_uuid/processor-countsAuth: Required Scope: file-level
@@ -652,7 +885,7 @@ curl -s -XPhase 1 (/phase1) combines store-asrx + rule1 + vectorize into one call.
Updated: 2026-06-20 12:00:00
+Updated: 2026-06-23 — Added queued status, FIFO queue order, queue_position in job detail, frontend status mapping table