覆核流程

管理覆核權限、人員群組、可重用範本、已送出的流程、Webhook 投遞與覆核決定。自訂資料表的 require_approval 規則會參照覆核範本；符合規則的寫入會先成為暫存變更，並建立對應的覆核流程。

GET

路由範本/private/module/review/access

列出覆核模組權限

用途

列出目前公司中仍有效的覆核角色授權，並回傳分頁總數。

適用時機

適合用來稽核哪些使用者或部門可建立、管理覆核流程。

實際掛載路徑

完整路由/private/module/review/access

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`REVIEW_MANAGER`

參數

欄位	位置	型別	必填	說明
`skip`	query	`int >= 0`	否	略過前幾筆授權，預設為 0。
`limit`	query	`int 1..100`	否	最多回傳幾筆授權，可填 1 到 100，預設為 50。

回應結構

ReviewAccessListResponse

欄位	型別	必填	說明
`entries`	`ReviewAccessEntry[]`	是	Page of access grant rows
`total`	`integer`	是	Total number of matching access grants, ignoring pagination

範例

列出第一頁有效授權

請求

{
  "pathParams": {},
  "query": {
    "skip": "0",
    "limit": "50"
  }
}

回應200

{
  "entries": [
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "user_id": "22222222-2222-4222-8222-222222222222",
      "department_id": null,
      "role_type": "creator",
      "granted_by": "22222222-2222-4222-8222-222222222222",
      "created_at": "2026-07-19T02:00:00"
    }
  ],
  "total": 1
}

錯誤

狀態	發生條件	錯誤本文
403	呼叫者不是覆核模組管理者。	`{ "detail": "Insufficient permissions. Review manager access required." }`

POST

路由範本/private/module/review/access

授予覆核模組角色

用途

把 creator 或 manager 角色授予同公司的單一使用者或部門。

適用時機

在使用者或部門需要建立或管理覆核資源前呼叫。

實際掛載路徑

完整路由/private/module/review/access

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`COMPANY_MANAGER`

請求結構

ReviewAccessCreate

欄位	型別	必填	說明
`department_id`	`string \| null`	否	Grant target: a department's UUID (mutually exclusive with user_id)
`role_type`	`"creator" \| "manager"`	是	Review module role to grant: creator or manager
`user_id`	`string \| null`	否	Grant target: a single user's UUID (mutually exclusive with department_id)

回應結構

ReviewAccessEntry

欄位	型別	必填	說明
`created_at`	`string (date-time)`	是	Timestamp the grant was created
`department_id`	`string \| null`	否	Granted department's UUID, when the grant targets a department
`granted_by`	`string \| null`	否	UUID of the admin who created this grant
`id`	`string`	是	Access grant UUID
`role_type`	`"creator" \| "manager"`	是	Review module role granted: creator or manager
`user_id`	`string \| null`	否	Granted user's UUID, when the grant targets a user

範例

授予使用者 creator 角色

請求

{
  "pathParams": {},
  "body": {
    "user_id": "22222222-2222-4222-8222-222222222222",
    "role_type": "creator"
  }
}

回應200

{
  "id": "44444444-4444-4444-8444-444444444444",
  "user_id": "22222222-2222-4222-8222-222222222222",
  "department_id": null,
  "role_type": "creator",
  "granted_by": "22222222-2222-4222-8222-222222222222",
  "created_at": "2026-07-19T02:00:00"
}

錯誤

狀態	發生條件	錯誤本文
404	指定的使用者或部門不屬於目前公司。	`{ "detail": "User not found in this company" }`
409	相同目標與角色已有有效授權。	`{ "detail": "Grant already exists" }`

DELETE

路由範本/private/module/review/access/{access_id}

撤銷覆核模組角色

用途

將公司範圍內的有效 Review grant 軟刪除，並把被撤銷的使用者或部門及角色寫入稽核紀錄。

適用時機

當使用者或部門不應再擁有該覆核角色時使用。

實際掛載路徑

完整路由/private/module/review/access/{access_id}

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`COMPANY_MANAGER`

參數

欄位	位置	型別	必填	說明
`access_id`	path	`uuid`	是	要撤銷的授權 UUID。

回應結構

ReviewAccessEntry

欄位	型別	必填	說明
`created_at`	`string (date-time)`	是	Timestamp the grant was created
`department_id`	`string \| null`	否	Granted department's UUID, when the grant targets a department
`granted_by`	`string \| null`	否	UUID of the admin who created this grant
`id`	`string`	是	Access grant UUID
`role_type`	`"creator" \| "manager"`	是	Review module role granted: creator or manager
`user_id`	`string \| null`	否	Granted user's UUID, when the grant targets a user

範例

撤銷指定授權

請求

{
  "pathParams": {
    "access_id": "44444444-4444-4444-8444-444444444444"
  }
}

回應200

{
  "id": "44444444-4444-4444-8444-444444444444",
  "user_id": "22222222-2222-4222-8222-222222222222",
  "department_id": null,
  "role_type": "creator",
  "granted_by": "22222222-2222-4222-8222-222222222222",
  "created_at": "2026-07-19T02:00:00"
}

錯誤

狀態	發生條件	錯誤本文
404	目前公司找不到這筆有效授權。	`{ "detail": "Grant not found" }`

POST

路由範本/private/module/review/groups

建立覆核群組

用途

建立可供覆核關卡條件引用的公司內人員群組。

適用時機

在設計範本或行內關卡前，先把實際覆核人員整理成群組。

實際掛載路徑

完整路由/private/module/review/groups

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`REVIEW_MANAGER`

請求結構

ReviewGroupCreate

欄位	型別	必填	說明
`description`	`string \| null`	否	Optional free-text notes about the group's purpose
`member_ids`	`string[]`	是	User UUIDs belonging to this group (deduped, max 500 unique)
`name`	`string`	是	Review group display name

回應結構

ReviewGroupResponse

欄位	型別	必填	說明
`created_at`	`string (date-time)`	是	Timestamp the group was created
`created_by`	`string \| null`	否	UUID of the user who created this group
`description`	`string \| null`	否	Free-text notes about the group's purpose
`id`	`string`	是	Review group UUID
`member_ids`	`string[]`	是	User UUIDs currently belonging to this group
`name`	`string`	是	Review group display name
`updated_at`	`string (date-time) \| null`	否	Timestamp of the group's last update, if modified

範例

建立訂單覆核群組

請求

{
  "pathParams": {},
  "body": {
    "name": "訂單覆核人員",
    "description": "負責審核高金額訂單",
    "member_ids": [
      "22222222-2222-4222-8222-222222222222"
    ]
  }
}

回應200

{
  "id": "55555555-5555-4555-8555-555555555555",
  "name": "訂單覆核人員",
  "description": "負責審核高金額訂單",
  "created_by": "22222222-2222-4222-8222-222222222222",
  "member_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "created_at": "2026-07-19T02:00:00",
  "updated_at": "2026-07-19T02:05:00"
}

錯誤

狀態	發生條件	錯誤本文
422	member_ids 內含不屬於目前公司的使用者。	`{ "detail": "member_ids not found in this company: ['22222222-2222-4222-8222-222222222222']" }`

GET

路由範本/private/module/review/groups

列出覆核群組

用途

列出目前公司仍有效的覆核群組及其成員。

適用時機

適合用於範本編輯器的群組選單或群組管理頁面。

實際掛載路徑

完整路由/private/module/review/groups

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`REVIEW_CREATOR`

參數

欄位	位置	型別	必填	說明
`skip`	query	`int >= 0`	否	略過前幾筆群組，預設為 0。
`limit`	query	`int 1..100`	否	最多回傳幾筆群組，可填 1 到 100，預設為 50。

回應結構

ReviewGroupListResponse

欄位	型別	必填	說明
`entries`	`ReviewGroupResponse[]`	是	Page of review group rows
`total`	`integer`	是	Total number of matching review groups, ignoring pagination

範例

列出第一頁覆核群組

請求

{
  "pathParams": {},
  "query": {
    "skip": "0",
    "limit": "50"
  }
}

回應200

{
  "entries": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "name": "訂單覆核人員",
      "description": "負責審核高金額訂單",
      "created_by": "22222222-2222-4222-8222-222222222222",
      "member_ids": [
        "22222222-2222-4222-8222-222222222222"
      ],
      "created_at": "2026-07-19T02:00:00",
      "updated_at": "2026-07-19T02:05:00"
    }
  ],
  "total": 1
}

錯誤

狀態	發生條件	錯誤本文
403	呼叫者沒有 creator 或 manager 角色。	`{ "detail": "Insufficient permissions. Review creator access required." }`

GET

路由範本/private/module/review/groups/{group_id}

取得覆核群組

用途

取得一個有效覆核群組的名稱、說明與目前成員。

適用時機

在調整成員或建立 template gate 前讀取，取得有效群組目前的中繼資料與完整 member_ids。

實際掛載路徑

完整路由/private/module/review/groups/{group_id}

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`REVIEW_CREATOR`

參數

欄位	位置	型別	必填	說明
`group_id`	path	`uuid`	是	覆核群組 UUID。

回應結構

ReviewGroupResponse

欄位	型別	必填	說明
`created_at`	`string (date-time)`	是	Timestamp the group was created
`created_by`	`string \| null`	否	UUID of the user who created this group
`description`	`string \| null`	否	Free-text notes about the group's purpose
`id`	`string`	是	Review group UUID
`member_ids`	`string[]`	是	User UUIDs currently belonging to this group
`name`	`string`	是	Review group display name
`updated_at`	`string (date-time) \| null`	否	Timestamp of the group's last update, if modified

範例

取得指定覆核群組

請求

{
  "pathParams": {
    "group_id": "55555555-5555-4555-8555-555555555555"
  }
}

回應200

{
  "id": "55555555-5555-4555-8555-555555555555",
  "name": "訂單覆核人員",
  "description": "負責審核高金額訂單",
  "created_by": "22222222-2222-4222-8222-222222222222",
  "member_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "created_at": "2026-07-19T02:00:00",
  "updated_at": "2026-07-19T02:05:00"
}

錯誤

狀態	發生條件	錯誤本文
404	目前公司找不到這個有效群組。	`{ "detail": "Review group not found" }`

PATCH

路由範本/private/module/review/groups/{group_id}

更新覆核群組

用途

更新群組名稱、說明，或以完整清單取代成員。

適用時機

當未來啟動的關卡應使用不同人員名單時使用。

實際掛載路徑

完整路由/private/module/review/groups/{group_id}

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`REVIEW_MANAGER`

參數

欄位	位置	型別	必填	說明
`group_id`	path	`uuid`	是	要更新的覆核群組 UUID。

請求結構

ReviewGroupUpdate

欄位	型別	必填	說明
`description`	`string \| null`	否	New free-text notes; omit to leave unchanged
`member_ids`	`string[] \| null`	否	Replacement set of member user UUIDs (deduped, max 500 unique); omit to leave unchanged
`name`	`string \| null`	否	New display name; omit to leave unchanged

回應結構

ReviewGroupResponse

欄位	型別	必填	說明
`created_at`	`string (date-time)`	是	Timestamp the group was created
`created_by`	`string \| null`	否	UUID of the user who created this group
`description`	`string \| null`	否	Free-text notes about the group's purpose
`id`	`string`	是	Review group UUID
`member_ids`	`string[]`	是	User UUIDs currently belonging to this group
`name`	`string`	是	Review group display name
`updated_at`	`string (date-time) \| null`	否	Timestamp of the group's last update, if modified

範例

更新群組說明與成員

請求

{
  "pathParams": {
    "group_id": "55555555-5555-4555-8555-555555555555"
  },
  "body": {
    "description": "負責審核高金額與例外訂單",
    "member_ids": [
      "22222222-2222-4222-8222-222222222222"
    ]
  }
}

回應200

{
  "id": "55555555-5555-4555-8555-555555555555",
  "name": "訂單覆核人員",
  "description": "負責審核高金額與例外訂單",
  "created_by": "22222222-2222-4222-8222-222222222222",
  "member_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "created_at": "2026-07-19T02:00:00",
  "updated_at": "2026-07-19T02:05:00"
}

錯誤

狀態	發生條件	錯誤本文
404	目前公司找不到這個有效群組。	`{ "detail": "Review group not found" }`

DELETE

路由範本/private/module/review/groups/{group_id}

刪除覆核群組

用途

將不再使用的覆核群組標記為已刪除；若仍被 in_review 流程引用，會以 409 阻止刪除。

適用時機

確認沒有進行中流程仍引用群組後再使用。

實際掛載路徑

完整路由/private/module/review/groups/{group_id}

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`REVIEW_MANAGER`

參數

欄位	位置	型別	必填	說明
`group_id`	path	`uuid`	是	要刪除的覆核群組 UUID。

回應結構

ReviewGroupResponse

欄位	型別	必填	說明
`created_at`	`string (date-time)`	是	Timestamp the group was created
`created_by`	`string \| null`	否	UUID of the user who created this group
`description`	`string \| null`	否	Free-text notes about the group's purpose
`id`	`string`	是	Review group UUID
`member_ids`	`string[]`	是	User UUIDs currently belonging to this group
`name`	`string`	是	Review group display name
`updated_at`	`string (date-time) \| null`	否	Timestamp of the group's last update, if modified

範例

刪除未被引用的群組

請求

{
  "pathParams": {
    "group_id": "55555555-5555-4555-8555-555555555555"
  }
}

回應200

{
  "id": "55555555-5555-4555-8555-555555555555",
  "name": "訂單覆核人員",
  "description": "負責審核高金額訂單",
  "created_by": "22222222-2222-4222-8222-222222222222",
  "member_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "created_at": "2026-07-19T02:00:00",
  "updated_at": "2026-07-19T02:05:00"
}

錯誤

狀態	發生條件	錯誤本文
409	仍有進行中的覆核流程引用這個群組。	`{ "detail": "Group is referenced by a review process still in review" }`

POST

路由範本/private/module/review/templates

建立覆核範本

用途

建立可重用的有序關卡與簽名要求，供新流程展開使用。

適用時機

當多個業務流程或自訂資料表規則要共用同一套覆核邏輯時使用。

實際掛載路徑

完整路由/private/module/review/templates

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`REVIEW_MANAGER`

請求結構

ReviewTemplateCreate

欄位	型別	必填	說明
`description`	`string \| null`	否	Optional free-text notes about when to use this template
`gates`	`ReviewGateCreate[]`	是	Ordered approval gates (1-20), snapshot-copied into a process's own gates at creation time
`name`	`string`	是	Template display name
`require_signature`	`boolean`	否	When true, processes created from this template require reviewers to attach a raster signature image with their decision

回應結構

ReviewTemplateResponse

欄位	型別	必填	說明
`created_at`	`string (date-time)`	是	Timestamp the template was created
`description`	`string \| null`	否	Free-text notes about when to use this template
`gates`	`ReviewGateResponseGate[] \| null`	否	Ordered gates configured on this template; null unless the caller is a review creator or manager
`id`	`string`	是	Review template UUID
`name`	`string`	是	Template display name
`require_signature`	`boolean`	是	Whether processes created from this template require a signature
`updated_at`	`string (date-time)`	是	Timestamp the template was last updated

範例

建立高金額訂單覆核範本

請求

{
  "pathParams": {},
  "body": {
    "name": "高金額訂單覆核",
    "description": "單一關卡的訂單覆核流程",
    "gates": [
      {
        "name": "主管覆核",
        "condition": {
          "type": "group",
          "group_id": "55555555-5555-4555-8555-555555555555",
          "mode": "any"
        }
      }
    ],
    "require_signature": false
  }
}

回應200

{
  "id": "66666666-6666-4666-8666-666666666666",
  "name": "高金額訂單覆核",
  "description": "單一關卡的訂單覆核流程",
  "require_signature": false,
  "gates": [
    {
      "name": "主管覆核",
      "condition": {
        "type": "group",
        "group_id": "55555555-5555-4555-8555-555555555555",
        "mode": "any"
      }
    }
  ],
  "created_at": "2026-07-19T02:00:00",
  "updated_at": "2026-07-19T02:05:00"
}

一關：覆核群組任一人，或指名的某一個人（直接 user leaf）皆可通過

請求

{
  "pathParams": {},
  "body": {
    "name": "合約簽核",
    "description": "覆核群組任一人，或負責人本人，即可放行",
    "gates": [
      {
        "name": "負責人簽核",
        "condition": {
          "type": "or",
          "children": [
            {
              "type": "group",
              "group_id": "55555555-5555-4555-8555-555555555555",
              "mode": "any"
            },
            {
              "type": "user",
              "user_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
            }
          ]
        }
      }
    ],
    "require_signature": false
  }
}

回應200

{
  "id": "66666666-6666-4666-8666-666666666666",
  "name": "合約簽核",
  "description": "覆核群組任一人，或負責人本人，即可放行",
  "require_signature": false,
  "gates": [
    {
      "name": "負責人簽核",
      "condition": {
        "type": "or",
        "children": [
          {
            "type": "group",
            "group_id": "55555555-5555-4555-8555-555555555555",
            "mode": "any"
          },
          {
            "type": "user",
            "user_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
          }
        ]
      }
    }
  ],
  "created_at": "2026-07-19T02:00:00",
  "updated_at": "2026-07-19T02:05:00"
}

錯誤

狀態	發生條件	錯誤本文
422	關卡條件無效，或引用了其他公司的群組。	`{ "detail": "review groups not found: ['55555555-5555-4555-8555-555555555555']" }`
422	被引用的群組沒有任何成員通過 reviewer 判定式。現在成員全部未驗證或全部已到期時也會觸發——這種 template 以前會通過驗證，然後開出沒有人投得下去的選票。	`{ "detail": "review groups have no active members: ['55555555-5555-4555-8555-555555555555']" }`
422	`{"type":"user"}` leaf 指到的 `user_id` 不存在、已軟刪、已停用、未驗證、已到期，或屬於其他公司。最多只列出前五個。	`{ "detail": "review users not found or inactive: ['eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee']" }`
422	該 gate 的 reviewer 聯集——有效群組成員加上直接 user leaf——超過 MAX_GATE_ASSIGNEES（500）。與 leaf／depth 上限不同，這一則確實是單一字串的 `detail`。	`{ "detail": "gate 1 would assign 501 reviewers, exceeds max 500" }`
422	condition 物件帶了該節點種類未宣告的鍵。三種節點都是 `extra="forbid"`，因此 `{"type":"user", …, "mode":"all"}` 在業務驗證之前就被請求驗證擋下；過去它會被接受，多餘的鍵被默默丟掉。	`{ "detail": [ { "type": "extra_forbidden", "loc": [ "body", "gates", 0, "condition", "user", "mode" ], "msg": "Extra inputs are not permitted", "input": "all" } ] }`
422	單一 gate 超過 20 個 leaf——group leaf 與 user leaf 合併計算。它由 model validator 拋出，因此以 Pydantic `value_error` 條目送出，訊息落在 `detail[].msg`，絕不會是單一字串的 `detail`。`condition depth {d} exceeds max 5` 形狀相同。	`{ "detail": [ { "type": "value_error", "loc": [ "body", "gates", 0 ], "msg": "Value error, condition has 21 leaves, exceeds max 20" } ] }`

注意事項

自訂資料表的 require_approval 規則以 template_id 參照這類範本。
建立流程時會複製範本關卡；之後修改範本不會改動既有流程。
condition 可以直接指名一個人：`{"type":"user","user_id":"<36 字元 uuid>"}`，可裸用也可掛在任何 and/or 節點下，與 group leaf 自由混用，不必為此建一個只有一人的群組。該使用者成為單人選舉人團，拿到剛好一筆 assignment。
condition 物件是嚴格的。允許的鍵集合剛好是 `{type, group_id, mode}`、`{type, user_id}` 與 `{type, children}`（2–20 個 children）。user leaf 沒有 `mode`。
一位 reviewer 要四個條件全中才算數：未刪除、未停用、`verified` 為 true、未到期——role -2（部門虛擬管理員）豁免到期檢查，因為 `get_current_user` 也豁免它。建立時與 gate 啟用時跑的是同一個判定式，兩者不可能各說各話。
每個 gate：最多 20 個 leaf（group 與 user 合併計算）、深度最多 5、每個 and/or 節點最多 20 個 children、聯集最多 500 位 reviewer。leaf 上限訊息拿掉了 group 一字，現在是 `condition has {n} leaves, exceeds max 20`。

GET

路由範本/private/module/review/templates

列出覆核範本

用途

列出目前公司仍有效的覆核範本與分頁總數。

適用時機

適合用於 require_approval 規則或新覆核流程的範本選單。

實際掛載路徑

完整路由/private/module/review/templates

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user (company member)`

參數

欄位	位置	型別	必填	說明
`skip`	query	`int >= 0`	否	略過前幾筆範本，預設為 0。
`limit`	query	`int 1..100`	否	最多回傳幾筆範本，可填 1 到 100，預設為 50。

回應結構

ReviewTemplateListResponse

欄位	型別	必填	說明
`entries`	`ReviewTemplateResponse[]`	是	Page of review template rows
`total`	`integer`	是	Total number of matching review templates, ignoring pagination

範例

列出第一頁覆核範本

請求

{
  "pathParams": {},
  "query": {
    "skip": "0",
    "limit": "50"
  }
}

回應200

{
  "entries": [
    {
      "id": "66666666-6666-4666-8666-666666666666",
      "name": "高金額訂單覆核",
      "description": "單一關卡的訂單覆核流程",
      "require_signature": false,
      "gates": [
        {
          "name": "主管覆核",
          "condition": {
            "type": "group",
            "group_id": "55555555-5555-4555-8555-555555555555",
            "mode": "any"
          }
        }
      ],
      "created_at": "2026-07-19T02:00:00",
      "updated_at": "2026-07-19T02:05:00"
    }
  ],
  "total": 1
}

錯誤

狀態	發生條件	錯誤本文
403	呼叫者不屬於任何公司。	`{ "detail": "User must belong to a company to access the Review module" }`

GET

路由範本/private/module/review/templates/{template_id}

取得覆核範本

用途

取得公司內有效範本；一般成員只看到中繼資料，Review creator／manager 才會收到 gates 設定。

適用時機

在顯示或編輯範本，或確認規則所參照範本時使用。

實際掛載路徑

完整路由/private/module/review/templates/{template_id}

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user (company member)`

參數

欄位	位置	型別	必填	說明
`template_id`	path	`uuid`	是	覆核範本 UUID。

回應結構

ReviewTemplateResponse

欄位	型別	必填	說明
`created_at`	`string (date-time)`	是	Timestamp the template was created
`description`	`string \| null`	否	Free-text notes about when to use this template
`gates`	`ReviewGateResponseGate[] \| null`	否	Ordered gates configured on this template; null unless the caller is a review creator or manager
`id`	`string`	是	Review template UUID
`name`	`string`	是	Template display name
`require_signature`	`boolean`	是	Whether processes created from this template require a signature
`updated_at`	`string (date-time)`	是	Timestamp the template was last updated

範例

取得指定覆核範本

請求

{
  "pathParams": {
    "template_id": "66666666-6666-4666-8666-666666666666"
  }
}

回應200

{
  "id": "66666666-6666-4666-8666-666666666666",
  "name": "高金額訂單覆核",
  "description": "單一關卡的訂單覆核流程",
  "require_signature": false,
  "gates": [
    {
      "name": "主管覆核",
      "condition": {
        "type": "group",
        "group_id": "55555555-5555-4555-8555-555555555555",
        "mode": "any"
      }
    }
  ],
  "created_at": "2026-07-19T02:00:00",
  "updated_at": "2026-07-19T02:05:00"
}

錯誤

狀態	發生條件	錯誤本文
404	目前公司找不到這個有效範本。	`{ "detail": "Review template not found" }`

PUT

路由範本/private/module/review/templates/{template_id}

更新覆核範本

用途

更新範本名稱、說明、簽名要求或完整關卡設定。

適用時機

當未來新建流程應採用新的覆核設計時使用。

實際掛載路徑

完整路由/private/module/review/templates/{template_id}

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`REVIEW_MANAGER`

參數

欄位	位置	型別	必填	說明
`template_id`	path	`uuid`	是	要更新的覆核範本 UUID。

請求結構

ReviewTemplateUpdate

欄位	型別	必填	說明
`description`	`string \| null`	否	New free-text notes; omit to leave unchanged
`gates`	`ReviewGateCreate[] \| null`	否	Replacement ordered approval gates (1-20); omit to leave unchanged. Only future process creations see the change
`name`	`string \| null`	否	New display name; omit to leave unchanged
`require_signature`	`boolean \| null`	否	New require_signature value; omit to leave unchanged

回應結構

ReviewTemplateResponse

欄位	型別	必填	說明
`created_at`	`string (date-time)`	是	Timestamp the template was created
`description`	`string \| null`	否	Free-text notes about when to use this template
`gates`	`ReviewGateResponseGate[] \| null`	否	Ordered gates configured on this template; null unless the caller is a review creator or manager
`id`	`string`	是	Review template UUID
`name`	`string`	是	Template display name
`require_signature`	`boolean`	是	Whether processes created from this template require a signature
`updated_at`	`string (date-time)`	是	Timestamp the template was last updated

範例

更新範本說明與簽名要求

請求

{
  "pathParams": {
    "template_id": "66666666-6666-4666-8666-666666666666"
  },
  "body": {
    "description": "更新後的訂單覆核流程",
    "require_signature": true
  }
}

回應200

{
  "id": "66666666-6666-4666-8666-666666666666",
  "name": "高金額訂單覆核",
  "description": "更新後的訂單覆核流程",
  "require_signature": true,
  "gates": [
    {
      "name": "主管覆核",
      "condition": {
        "type": "group",
        "group_id": "55555555-5555-4555-8555-555555555555",
        "mode": "any"
      }
    }
  ],
  "created_at": "2026-07-19T02:00:00",
  "updated_at": "2026-07-19T02:05:00"
}

錯誤

狀態	發生條件	錯誤本文
404	目前公司找不到這個有效範本。	`{ "detail": "Review template not found" }`
422	與建立時同一套 reviewer 判定式：替換後的 gate 中，某個群組沒有任何成員能認證並投票。	`{ "detail": "review groups have no active members: ['55555555-5555-4555-8555-555555555555']" }`
422	替換後的 gate 中，某個直接 user leaf 指到的使用者不存在、已軟刪、已停用、未驗證、已到期，或屬於其他公司。	`{ "detail": "review users not found or inactive: ['eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee']" }`

DELETE

路由範本/private/module/review/templates/{template_id}

刪除覆核範本

用途

軟刪除不再使用、且沒有有效消費端參照的範本。

適用時機

移除所有 require_approval 規則參照後，再淘汰範本。

實際掛載路徑

完整路由/private/module/review/templates/{template_id}

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`REVIEW_MANAGER`

參數

欄位	位置	型別	必填	說明
`template_id`	path	`uuid`	是	要刪除的覆核範本 UUID。

回應結構

ReviewTemplateResponse

欄位	型別	必填	說明
`created_at`	`string (date-time)`	是	Timestamp the template was created
`description`	`string \| null`	否	Free-text notes about when to use this template
`gates`	`ReviewGateResponseGate[] \| null`	否	Ordered gates configured on this template; null unless the caller is a review creator or manager
`id`	`string`	是	Review template UUID
`name`	`string`	是	Template display name
`require_signature`	`boolean`	是	Whether processes created from this template require a signature
`updated_at`	`string (date-time)`	是	Timestamp the template was last updated

範例

刪除未被使用的範本

請求

{
  "pathParams": {
    "template_id": "66666666-6666-4666-8666-666666666666"
  }
}

回應200

{
  "id": "66666666-6666-4666-8666-666666666666",
  "name": "高金額訂單覆核",
  "description": "單一關卡的訂單覆核流程",
  "require_signature": false,
  "gates": [
    {
      "name": "主管覆核",
      "condition": {
        "type": "group",
        "group_id": "55555555-5555-4555-8555-555555555555",
        "mode": "any"
      }
    }
  ],
  "created_at": "2026-07-19T02:00:00",
  "updated_at": "2026-07-19T02:05:00"
}

錯誤

狀態	發生條件	錯誤本文
409	仍有規則或垃圾桶中的資料表參照範本；detail 會回傳 usage_count。	`{ "detail": { "error": "template_in_use", "usage_count": 1 } }`

POST

路由範本/private/module/review/blobs

上傳覆核附件

用途

上傳一般覆核內容附件或手寫簽名影像，並歸屬呼叫者公司。

適用時機

在建立含附件的流程，或簽名必填的覆核決定前使用。

實際掛載路徑

完整路由/private/module/review/blobs

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user`

請求結構

Body_upload_blob_private_module_review_blobs_post

欄位	型別	必填	說明
`file`	`string`	是	File to upload
`purpose`	`"content" \| "signature"`	否	未指定

回應結構

ReviewBlobResponse

欄位	型別	必填	說明
`content_type`	`string`	是	MIME type of the uploaded blob
`filename`	`string \| null`	否	Original filename, if provided at upload
`id`	`string`	是	Uploaded blob UUID
`url`	`string`	是	Signed download URL for the blob

範例

上傳 PNG 簽名影像

請求

{
  "pathParams": {},
  "body": {
    "file": "<binary PNG>",
    "purpose": "signature"
  }
}

回應200

{
  "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "url": "https://files.example.com/review/signature.png",
  "content_type": "image/png",
  "filename": "signature.png"
}

錯誤

狀態	發生條件	錯誤本文
422	簽名不是 PNG/JPEG，或檔案超過該用途的大小限制。	`{ "detail": "Signature blobs must be image/png or image/jpeg" }`

POST

路由範本/private/module/review/processes

建立並送出覆核流程

用途

以範本或行內關卡建立流程，驗證附件與 Webhook，並立即啟動第一關。

適用時機

當一項變更或業務內容已準備好交由覆核人員決定時使用。

實際掛載路徑

完整路由/private/module/review/processes

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`REVIEW_CREATOR`

請求結構

ReviewProcessCreate

欄位	型別	必填	說明
`blob_ids`	`string[]`	否	Uploaded review blob UUIDs to attach (deduped, max 50 unique)
`content`	`object \| null`	否	Free-form JSON payload to review (<=64 KB serialized)
`description`	`string \| null`	否	Longer free-text description of what is being reviewed
`gates`	`ReviewGateCreate[] \| null`	否	Ordered approval gates (1-20); gate 1 activates immediately on submit. Mutually exclusive with template_id
`require_signature`	`boolean`	否	When true, reviewers must attach a raster signature image with their decision. Ignored when template_id is set — the template's own require_signature applies instead
`template_id`	`string \| null`	否	Reusable ReviewProcessTemplate UUID: gates and require_signature are expanded from the template. Mutually exclusive with gates
`title`	`string`	是	Short title identifying the review process
`webhook`	`ReviewWebhookConfigIn \| null`	否	Optional callback fired on terminal process events

回應結構

ReviewProcessResponse

欄位	型別	必填	說明
`blobs`	`ReviewBlobResponse[]`	是	Blobs attached to this process
`company_id`	`string`	是	Owning company UUID
`completed_at`	`string (date-time) \| null`	否	Timestamp the process reached a terminal status, null while in_review
`content`	`object \| null`	否	Free-form JSON payload under review
`created_at`	`string (date-time)`	是	Timestamp the process was created
`current_gate_order`	`integer \| null`	否	Order of the currently active gate, null once resolved
`description`	`string \| null`	否	Longer free-text description of what is being reviewed
`gates`	`ReviewGateResponse[]`	是	Ordered approval gates for this process
`id`	`string`	是	Review process UUID
`requester_id`	`string \| null`	否	UUID of the user who submitted the process
`require_signature`	`boolean`	是	Whether reviewers must attach a raster signature image with their decision
`status`	`"in_review" \| "approved" \| "rejected" \| "cancelled"`	是	Process lifecycle state: in_review\|approved\|rejected\|cancelled
`title`	`string`	是	Short title identifying the review process
`webhook`	`ReviewWebhookConfigOut \| null`	否	Configured callback fired on terminal process events

範例

以範本送出訂單變更覆核

請求

{
  "pathParams": {},
  "body": {
    "title": "訂單 ORD-1042 變更覆核",
    "description": "確認折扣與付款條件",
    "content": {
      "table_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
      "operation": "update"
    },
    "blob_ids": [],
    "template_id": "66666666-6666-4666-8666-666666666666"
  }
}

回應200

{
  "id": "77777777-7777-4777-8777-777777777777",
  "company_id": "11111111-1111-4111-8111-111111111111",
  "title": "訂單 ORD-1042 變更覆核",
  "description": "確認折扣與付款條件",
  "content": {
    "table_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
    "operation": "update"
  },
  "requester_id": "22222222-2222-4222-8222-222222222222",
  "status": "in_review",
  "current_gate_order": 1,
  "require_signature": false,
  "webhook": null,
  "completed_at": null,
  "created_at": "2026-07-19T02:00:00",
  "gates": [
    {
      "id": "88888888-8888-4888-8888-888888888888",
      "gate_order": 1,
      "name": "主管覆核",
      "condition": {
        "type": "group",
        "group_id": "55555555-5555-4555-8555-555555555555",
        "mode": "any"
      },
      "status": "active",
      "activated_at": "2026-07-19T02:00:00",
      "resolved_at": null,
      "assignments": [
        {
          "id": "99999999-9999-4999-8999-999999999999",
          "gate_id": "88888888-8888-4888-8888-888888888888",
          "user_id": "22222222-2222-4222-8222-222222222222",
          "group_ids": [
            "55555555-5555-4555-8555-555555555555"
          ],
          "status": "pending",
          "comment": null,
          "signature_blob_id": null,
          "signature_blob": null,
          "decided_at": null
        }
      ]
    }
  ],
  "blobs": []
}

inline gate 直接指名一個人——回來的 assignment 帶 `group_ids: []`

請求

{
  "pathParams": {},
  "body": {
    "title": "訂單 ORD-1042 變更覆核",
    "description": "確認折扣與付款條件",
    "content": {
      "table_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
      "operation": "update"
    },
    "blob_ids": [],
    "gates": [
      {
        "name": "負責人簽核",
        "condition": {
          "type": "user",
          "user_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
        }
      }
    ]
  }
}

回應200

{
  "id": "77777777-7777-4777-8777-777777777777",
  "company_id": "11111111-1111-4111-8111-111111111111",
  "title": "訂單 ORD-1042 變更覆核",
  "description": "確認折扣與付款條件",
  "content": {
    "table_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
    "operation": "update"
  },
  "requester_id": "22222222-2222-4222-8222-222222222222",
  "status": "in_review",
  "current_gate_order": 1,
  "require_signature": false,
  "webhook": null,
  "completed_at": null,
  "created_at": "2026-07-19T02:00:00",
  "gates": [
    {
      "id": "88888888-8888-4888-8888-888888888888",
      "gate_order": 1,
      "name": "負責人簽核",
      "condition": {
        "type": "user",
        "user_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
      },
      "status": "active",
      "activated_at": "2026-07-19T02:00:00",
      "resolved_at": null,
      "assignments": [
        {
          "id": "ffffffff-ffff-4fff-8fff-ffffffffffff",
          "gate_id": "88888888-8888-4888-8888-888888888888",
          "user_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee",
          "group_ids": [],
          "status": "pending",
          "comment": null,
          "signature_blob_id": null,
          "signature_blob": null,
          "decided_at": null
        }
      ]
    }
  ],
  "blobs": []
}

錯誤

狀態	發生條件	錯誤本文
422	範本不可用、關卡無效、附件不屬於公司，或 Webhook 設定不合法。	`{ "detail": "review template not usable: 66666666-6666-4666-8666-666666666666" }`
422	inline gate 指到的 `user_id` 不存在、已軟刪、已停用、未驗證、已到期，或屬於其他公司。最多只列出前五個。	`{ "detail": "review users not found or inactive: ['eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee']" }`
422	inline gate 引用的群組沒有任何成員通過 reviewer 判定式——包含成員全部未驗證或全部已到期的情況。	`{ "detail": "review groups have no active members: ['55555555-5555-4555-8555-555555555555']" }`

注意事項

此 API 沒有草稿狀態；建立後會立即啟動第一關並通知覆核人員。
符合 require_approval 的自訂資料表寫入會先暫存，並以規則的 template_id 建立這類流程。
純直接 reviewer 的 `group_ids` 在建立與詳情回應的 gates[].assignments[] 裡是 `[]`——那是唯一會回這個欄位的地方；列表回應、pending queue、audit changes 與 webhook body 根本沒有這個欄位。引擎內部標記虛擬選舉人團的鍵在序列化前就被剝掉。同時被 group leaf 與 user leaf 指名的人只拿到一筆 assignment，其中只列真實 group id，而他那一票同時算給他所代表的每一個 leaf。
建立就可能回傳一個已經終止的流程。若第一關啟用時某個決定性 leaf 的選舉人團為空，該關立即失敗：`status: "rejected"`、`completed_at` 有值、`current_gate_order` 為 `null`，並留下一列 `gate_failed` audit，其 `changes.reason` 是 `gate_unsatisfiable`。若掛在 `or` 之下且還有可滿足的兄弟節點，這一關照常啟用，無法審核的人單純拿不到 assignment。

GET

路由範本/private/module/review/processes

列出覆核流程

用途

依生命週期狀態與相對於呼叫者的角色，列出可見的覆核流程摘要。

適用時機

不逐筆取得流程詳情，即可建立「我送出的」與「指派給我的」兩個檢視。

實際掛載路徑

完整路由/private/module/review/processes

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user`

參數

欄位	位置	型別	必填	說明
`status`	query	`enum:in_review\|approved\|rejected\|cancelled`	否	選填的流程狀態篩選：in_review、approved、rejected 或 cancelled。
`role`	query	`enum:requested\|assigned`	否	選填、相對於呼叫者的篩選：requested 是我送出的；assigned 是我目前或曾持有 ballot。Manager 也一樣只相對自己篩選。
`skip`	query	`int >= 0`	否	略過前幾筆流程，預設為 0。
`limit`	query	`int 1..100`	否	最多回傳幾筆流程，可填 1 到 100，預設為 50。

回應結構

ReviewProcessListResponse

欄位	型別	必填	說明
`entries`	`ReviewProcessSummary[]`	是	Page of review process summaries
`total`	`integer`	是	Total number of matching processes, ignoring pagination

範例

列出呼叫者送出的進行中覆核流程

請求

{
  "pathParams": {},
  "query": {
    "status": "in_review",
    "role": "requested",
    "skip": "0",
    "limit": "50"
  }
}

回應200

{
  "entries": [
    {
      "id": "77777777-7777-4777-8777-777777777777",
      "title": "訂單 ORD-1042 變更覆核",
      "requester_id": "22222222-2222-4222-8222-222222222222",
      "requester": {
        "id": "22222222-2222-4222-8222-222222222222",
        "name": "王小明",
        "department_id": "33333333-3333-4333-8333-333333333333",
        "department_name": "財務部"
      },
      "status": "in_review",
      "current_gate_order": 1,
      "require_signature": false,
      "completed_at": null,
      "created_at": "2026-07-19T02:00:00",
      "requested_by_me": true,
      "assigned_to_me": false
    }
  ],
  "total": 1
}

錯誤

狀態	發生條件	錯誤本文
401	缺少或無法驗證登入憑證。	`{ "detail": "Could not validate credentials" }`

GET

路由範本/private/module/review/processes/{process_id}

取得覆核流程

用途

取得流程、關卡、指派、附件與 Webhook 的完整狀態。

適用時機

在顯示覆核詳情或追蹤目前關卡時使用。

實際掛載路徑

完整路由/private/module/review/processes/{process_id}

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user (participant or manager)`

參數

欄位	位置	型別	必填	說明
`process_id`	path	`uuid`	是	覆核流程 UUID。

回應結構

ReviewProcessResponse

欄位	型別	必填	說明
`blobs`	`ReviewBlobResponse[]`	是	Blobs attached to this process
`company_id`	`string`	是	Owning company UUID
`completed_at`	`string (date-time) \| null`	否	Timestamp the process reached a terminal status, null while in_review
`content`	`object \| null`	否	Free-form JSON payload under review
`created_at`	`string (date-time)`	是	Timestamp the process was created
`current_gate_order`	`integer \| null`	否	Order of the currently active gate, null once resolved
`description`	`string \| null`	否	Longer free-text description of what is being reviewed
`gates`	`ReviewGateResponse[]`	是	Ordered approval gates for this process
`id`	`string`	是	Review process UUID
`requester_id`	`string \| null`	否	UUID of the user who submitted the process
`require_signature`	`boolean`	是	Whether reviewers must attach a raster signature image with their decision
`status`	`"in_review" \| "approved" \| "rejected" \| "cancelled"`	是	Process lifecycle state: in_review\|approved\|rejected\|cancelled
`title`	`string`	是	Short title identifying the review process
`webhook`	`ReviewWebhookConfigOut \| null`	否	Configured callback fired on terminal process events

範例

取得指定覆核流程

請求

{
  "pathParams": {
    "process_id": "77777777-7777-4777-8777-777777777777"
  }
}

回應200

{
  "id": "77777777-7777-4777-8777-777777777777",
  "company_id": "11111111-1111-4111-8111-111111111111",
  "title": "訂單 ORD-1042 變更覆核",
  "description": "確認折扣與付款條件",
  "content": {
    "table_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
    "operation": "update"
  },
  "requester_id": "22222222-2222-4222-8222-222222222222",
  "status": "in_review",
  "current_gate_order": 1,
  "require_signature": false,
  "webhook": null,
  "completed_at": null,
  "created_at": "2026-07-19T02:00:00",
  "gates": [
    {
      "id": "88888888-8888-4888-8888-888888888888",
      "gate_order": 1,
      "name": "主管覆核",
      "condition": {
        "type": "group",
        "group_id": "55555555-5555-4555-8555-555555555555",
        "mode": "any"
      },
      "status": "active",
      "activated_at": "2026-07-19T02:00:00",
      "resolved_at": null,
      "assignments": [
        {
          "id": "99999999-9999-4999-8999-999999999999",
          "gate_id": "88888888-8888-4888-8888-888888888888",
          "user_id": "22222222-2222-4222-8222-222222222222",
          "group_ids": [
            "55555555-5555-4555-8555-555555555555"
          ],
          "status": "pending",
          "comment": null,
          "signature_blob_id": null,
          "signature_blob": null,
          "decided_at": null
        }
      ]
    }
  ],
  "blobs": []
}

已定案的 gate：核准者保留 `approved`；從未投票的人是 `obsolete`

請求

{
  "pathParams": {
    "process_id": "77777777-7777-4777-8777-777777777777"
  }
}

回應200

{
  "id": "77777777-7777-4777-8777-777777777777",
  "company_id": "11111111-1111-4111-8111-111111111111",
  "title": "訂單 ORD-1042 變更覆核",
  "description": "確認折扣與付款條件",
  "content": {
    "table_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
    "operation": "update"
  },
  "requester_id": "22222222-2222-4222-8222-222222222222",
  "status": "approved",
  "current_gate_order": null,
  "require_signature": true,
  "webhook": null,
  "completed_at": "2026-07-19T02:05:00",
  "created_at": "2026-07-19T02:00:00",
  "gates": [
    {
      "id": "88888888-8888-4888-8888-888888888888",
      "gate_order": 1,
      "name": "負責人簽核",
      "condition": {
        "type": "or",
        "children": [
          {
            "type": "group",
            "group_id": "55555555-5555-4555-8555-555555555555",
            "mode": "any"
          },
          {
            "type": "user",
            "user_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
          }
        ]
      },
      "status": "passed",
      "activated_at": "2026-07-19T02:00:00",
      "resolved_at": "2026-07-19T02:05:00",
      "assignments": [
        {
          "id": "99999999-9999-4999-8999-999999999999",
          "gate_id": "88888888-8888-4888-8888-888888888888",
          "user_id": "22222222-2222-4222-8222-222222222222",
          "group_ids": [
            "55555555-5555-4555-8555-555555555555"
          ],
          "status": "approved",
          "comment": "內容正確",
          "signature_blob_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
          "signature_blob": {
            "id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
            "url": "https://files.example.com/review/signature.png",
            "content_type": "image/png",
            "filename": "signature.png",
            "created_at": "2026-07-19T02:00:00",
            "tags": [],
            "thumbnail": null
          },
          "decided_at": "2026-07-19T02:05:00"
        },
        {
          "id": "ffffffff-ffff-4fff-8fff-ffffffffffff",
          "gate_id": "88888888-8888-4888-8888-888888888888",
          "user_id": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee",
          "group_ids": [],
          "status": "obsolete",
          "comment": null,
          "signature_blob_id": null,
          "signature_blob": null,
          "decided_at": null
        }
      ]
    }
  ],
  "blobs": []
}

取得含在地化 table、scope、operation 與 requester context 的自訂資料表審批

請求

{
  "pathParams": {
    "process_id": "77777777-7777-4777-8777-777777777777"
  }
}

回應200

{
  "id": "77777777-7777-4777-8777-777777777777",
  "company_id": "11111111-1111-4111-8111-111111111111",
  "title": "表格「訂單」修改資料審核",
  "description": "確認折扣與付款條件",
  "content": {
    "record_id": "12121212-1212-4212-8212-121212121212",
    "change_type": "update",
    "change_type_label": "修改資料",
    "table": {
      "id": "34343434-3434-4434-8434-343434343434",
      "name": "訂單",
      "scope": "chatroom",
      "scope_label": "聊天室",
      "scope_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
      "scope_name": "訂單客服"
    },
    "requester": {
      "type": "user",
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "王小明",
      "channel_label": "內部使用者",
      "department_id": "33333333-3333-4333-8333-333333333333",
      "department_name": "財務部"
    },
    "diff": {
      "金額": {
        "old": 1000,
        "new": 1200
      }
    }
  },
  "requester_id": "22222222-2222-4222-8222-222222222222",
  "status": "in_review",
  "current_gate_order": 1,
  "require_signature": false,
  "webhook": null,
  "completed_at": null,
  "created_at": "2026-07-19T02:00:00",
  "gates": [
    {
      "id": "88888888-8888-4888-8888-888888888888",
      "gate_order": 1,
      "name": "主管覆核",
      "condition": {
        "type": "group",
        "group_id": "55555555-5555-4555-8555-555555555555",
        "mode": "any"
      },
      "status": "active",
      "activated_at": "2026-07-19T02:00:00",
      "resolved_at": null,
      "assignments": [
        {
          "id": "99999999-9999-4999-8999-999999999999",
          "gate_id": "88888888-8888-4888-8888-888888888888",
          "user_id": "22222222-2222-4222-8222-222222222222",
          "group_ids": [
            "55555555-5555-4555-8555-555555555555"
          ],
          "status": "pending",
          "comment": null,
          "signature_blob_id": null,
          "signature_blob": null,
          "decided_at": null
        }
      ]
    }
  ],
  "blobs": []
}

錯誤

狀態	發生條件	錯誤本文
404	流程不存在，或呼叫者不是參與者及 manager。	`{ "detail": "Review process not found" }`

注意事項

為避免洩漏流程存在與否，沒有可見權限時也回傳 404。
一張選票最後停在 `pending`、`approved`、`denied` 或 `obsolete`。`obsolete` 的意思是「從未投票」——gate 或流程在沒有他的情況下結束了。已投出的票一律保留自己的決定，包含讓 gate 定案的那一張；那張票以前會在這裡被覆寫成 `obsolete`，而 audit log 仍記著 `decision_approved`，於是詳情與稽核對「是誰決定的」說法不一致。
`gates[].assignments[].group_ids` 只列真實的 review group id。純以直接 user leaf 被指派的 reviewer 會是 `[]`，而且絕不會外洩內部的 `user:<uuid>` 選舉人團鍵。
已決定的 assignment 可同時回 signature_blob_id 與內嵌 signature_blob metadata（含可渲染 URL）。前端優先用內嵌物件，並處理 pending 或缺少簽名時的 null。

POST

路由範本/private/module/review/processes/{process_id}/cancel

取消覆核流程

用途

由送審者或 manager 取消仍在進行中的流程。

適用時機

內容撤回時由 requester 或 manager 在 in_review 階段終止流程；已完成的 terminal 流程不能取消。

實際掛載路徑

完整路由/private/module/review/processes/{process_id}/cancel

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user (requester or manager)`

參數

欄位	位置	型別	必填	說明
`process_id`	path	`uuid`	是	要取消的覆核流程 UUID。

回應結構

ReviewProcessResponse

欄位	型別	必填	說明
`blobs`	`ReviewBlobResponse[]`	是	Blobs attached to this process
`company_id`	`string`	是	Owning company UUID
`completed_at`	`string (date-time) \| null`	否	Timestamp the process reached a terminal status, null while in_review
`content`	`object \| null`	否	Free-form JSON payload under review
`created_at`	`string (date-time)`	是	Timestamp the process was created
`current_gate_order`	`integer \| null`	否	Order of the currently active gate, null once resolved
`description`	`string \| null`	否	Longer free-text description of what is being reviewed
`gates`	`ReviewGateResponse[]`	是	Ordered approval gates for this process
`id`	`string`	是	Review process UUID
`requester_id`	`string \| null`	否	UUID of the user who submitted the process
`require_signature`	`boolean`	是	Whether reviewers must attach a raster signature image with their decision
`status`	`"in_review" \| "approved" \| "rejected" \| "cancelled"`	是	Process lifecycle state: in_review\|approved\|rejected\|cancelled
`title`	`string`	是	Short title identifying the review process
`webhook`	`ReviewWebhookConfigOut \| null`	否	Configured callback fired on terminal process events

範例

取消進行中的流程

請求

{
  "pathParams": {
    "process_id": "77777777-7777-4777-8777-777777777777"
  }
}

回應200

{
  "id": "77777777-7777-4777-8777-777777777777",
  "company_id": "11111111-1111-4111-8111-111111111111",
  "title": "訂單 ORD-1042 變更覆核",
  "description": "確認折扣與付款條件",
  "content": {
    "table_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
    "operation": "update"
  },
  "requester_id": "22222222-2222-4222-8222-222222222222",
  "status": "cancelled",
  "current_gate_order": null,
  "require_signature": false,
  "webhook": null,
  "completed_at": "2026-07-19T02:05:00",
  "created_at": "2026-07-19T02:00:00",
  "gates": [
    {
      "id": "88888888-8888-4888-8888-888888888888",
      "gate_order": 1,
      "name": "主管覆核",
      "condition": {
        "type": "group",
        "group_id": "55555555-5555-4555-8555-555555555555",
        "mode": "any"
      },
      "status": "active",
      "activated_at": "2026-07-19T02:00:00",
      "resolved_at": null,
      "assignments": [
        {
          "id": "99999999-9999-4999-8999-999999999999",
          "gate_id": "88888888-8888-4888-8888-888888888888",
          "user_id": "22222222-2222-4222-8222-222222222222",
          "group_ids": [
            "55555555-5555-4555-8555-555555555555"
          ],
          "status": "pending",
          "comment": null,
          "signature_blob_id": null,
          "signature_blob": null,
          "decided_at": null
        }
      ]
    }
  ],
  "blobs": []
}

錯誤

狀態	發生條件	錯誤本文
403	呼叫者不是送審者或 manager。	`{ "detail": "Only the requester or a manager can cancel" }`
409	流程已進入終止狀態，不能再取消。	`{ "detail": "Process is no longer in review" }`

GET

路由範本/private/module/review/processes/{process_id}/audit

取得流程稽核紀錄

用途

以新到舊順序列出一個流程的結構化稽核事件。

適用時機

需要追查流程建立、關卡推進、決定或通知事件時使用。

實際掛載路徑

完整路由/private/module/review/processes/{process_id}/audit

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user (participant or manager)`

參數

欄位	位置	型別	必填	說明
`process_id`	path	`uuid`	是	覆核流程 UUID。
`action`	query	`enum:ReviewAuditAction`	否	選填的 ReviewAuditAction 事件類型篩選。
`skip`	query	`int >= 0`	否	略過前幾筆稽核紀錄，預設為 0。
`limit`	query	`int 1..100`	否	最多回傳幾筆紀錄，可填 1 到 100，預設為 50。

回應結構

ReviewAuditLogResponse

欄位	型別	必填	說明
`entries`	`ReviewAuditLogEntry[]`	是	Page of audit log rows, newest first
`total`	`integer`	是	Total number of matching audit rows, ignoring pagination

範例

列出流程的稽核紀錄

請求

{
  "pathParams": {
    "process_id": "77777777-7777-4777-8777-777777777777"
  },
  "query": {
    "skip": "0",
    "limit": "50"
  }
}

回應200

{
  "entries": [
    {
      "id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
      "company_id": "11111111-1111-4111-8111-111111111111",
      "process_id": "77777777-7777-4777-8777-777777777777",
      "target_type": "process",
      "target_id": "77777777-7777-4777-8777-777777777777",
      "action": "process_created",
      "actor_id": "22222222-2222-4222-8222-222222222222",
      "changes": {
        "title": "訂單 ORD-1042 變更覆核"
      },
      "created_at": "2026-07-19T02:00:00"
    }
  ],
  "total": 1
}

錯誤

狀態	發生條件	錯誤本文
404	流程不存在，或呼叫者沒有參與者可見權限。	`{ "detail": "Review process not found" }`

GET

路由範本/private/module/review/processes/{process_id}/deliveries

列出流程 Webhook 投遞

用途

列出流程進入終止狀態後產生的 Webhook 投遞與結果。

適用時機

排查 Webhook 未送達，或決定是否手動重試時使用。

實際掛載路徑

完整路由/private/module/review/processes/{process_id}/deliveries

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user (requester or manager)`

參數

欄位	位置	型別	必填	說明
`process_id`	path	`uuid`	是	覆核流程 UUID。
`skip`	query	`int >= 0`	否	略過前幾筆投遞，預設為 0。
`limit`	query	`int 1..100`	否	最多回傳幾筆投遞，可填 1 到 100，預設為 50。

回應結構

ReviewDeliveryListResponse

欄位	型別	必填	說明
`entries`	`ReviewDeliveryEntry[]`	是	Page of webhook delivery rows, newest first
`total`	`integer`	是	Total number of matching deliveries, ignoring pagination

範例

列出失敗的 Webhook 投遞

請求

{
  "pathParams": {
    "process_id": "77777777-7777-4777-8777-777777777777"
  },
  "query": {
    "skip": "0",
    "limit": "50"
  }
}

回應200

{
  "entries": [
    {
      "id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
      "process_id": "77777777-7777-4777-8777-777777777777",
      "event": "approved",
      "status": "failed",
      "attempts": 1,
      "response_status": 503,
      "error": "upstream unavailable",
      "delivered_at": null,
      "created_at": "2026-07-19T02:00:00",
      "updated_at": "2026-07-19T02:05:00"
    }
  ],
  "total": 1
}

錯誤

狀態	發生條件	錯誤本文
403	呼叫者不是流程送審者或 manager。	`{ "detail": "Requester or manager access required" }`

POST

路由範本/private/module/review/deliveries/{delivery_id}/retry

重試 Webhook 投遞

用途

以原子方式認領失敗或逾時卡住的投遞，並重新排入佇列。

適用時機

修正下游服務後，重試一筆可重試的覆核 Webhook。

實際掛載路徑

完整路由/private/module/review/deliveries/{delivery_id}/retry

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user (requester or manager)`

參數

欄位	位置	型別	必填	說明
`delivery_id`	path	`uuid`	是	要重試的 Webhook 投遞 UUID。

回應結構

ReviewRetryResponse

欄位	型別	必填	說明
`delivery_id`	`string`	是	UUID of the webhook delivery that was re-queued
`status`	`"pending" \| "sending" \| "delivered" \| "failed"`	是	Delivery status after the retry claim, always pending on success

範例

重新排入失敗投遞

請求

{
  "pathParams": {
    "delivery_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"
  }
}

回應200

{
  "delivery_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "status": "pending"
}

錯誤

狀態	發生條件	錯誤本文
404	目前公司找不到這筆投遞。	`{ "detail": "Delivery not found" }`
409	投遞不是 failed，且 pending 或 sending 狀態尚未超過 10 分鐘。	`{ "detail": "Delivery is not retryable (not failed, and not stale)" }`

GET

路由範本/private/module/review/assignments/pending

列出我的待覆核指派

用途

列出目前登入者尚未投票的關卡指派與流程摘要。

適用時機

用來建立覆核人的個人收件匣，只列目前使用者尚未決定的 ballot，並帶回流程、關卡與簽名需求。

實際掛載路徑

完整路由/private/module/review/assignments/pending

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user`

參數

欄位	位置	型別	必填	說明
`skip`	query	`int >= 0`	否	略過前幾筆待辦，預設為 0。
`limit`	query	`int 1..100`	否	最多回傳幾筆待辦，可填 1 到 100，預設為 50。

回應結構

ReviewPendingListResponse

欄位	型別	必填	說明
`entries`	`ReviewPendingEntry[]`	是	Page of the caller's pending ballots
`total`	`integer`	是	Total number of matching pending ballots, ignoring pagination

範例

列出我的待覆核項目

請求

{
  "pathParams": {},
  "query": {
    "skip": "0",
    "limit": "50"
  }
}

回應200

{
  "entries": [
    {
      "assignment_id": "99999999-9999-4999-8999-999999999999",
      "process_id": "77777777-7777-4777-8777-777777777777",
      "process_title": "訂單 ORD-1042 變更覆核",
      "process_status": "in_review",
      "require_signature": false,
      "gate_id": "88888888-8888-4888-8888-888888888888",
      "gate_name": "主管覆核",
      "gate_order": 1,
      "created_at": "2026-07-19T02:00:00"
    }
  ],
  "total": 1
}

錯誤

狀態	發生條件	錯誤本文
401	缺少或無法驗證登入憑證。	`{ "detail": "Could not validate credentials" }`

POST

路由範本/private/module/review/assignments/{assignment_id}/decision

送出覆核決定

用途

對本人待辦指派投下 approved 或 denied，並推進關卡與流程狀態。

適用時機

覆核人員完成檢查並準備核准或否決時使用。

實際掛載路徑

完整路由/private/module/review/assignments/{assignment_id}/decision

範圍

範圍	是否提供	驗證與權限
完整路由	可使用	`get_current_user (assigned reviewer)`

參數

欄位	位置	型別	必填	說明
`assignment_id`	path	`uuid`	是	本人待辦指派的 UUID。

請求結構

ReviewDecisionRequest

欄位	型別	必填	說明
`comment`	`string \| null`	否	Required (non-empty) when denying
`decision`	`"approved" \| "denied"`	是	Ballot outcome: approved or denied
`signature_blob_id`	`string \| null`	否	Own uploaded image/png\|image/jpeg blob; required when the process has require_signature

回應結構

ReviewDecisionResult

欄位	型別	必填	說明
`assignment_id`	`string`	是	Assignment (ballot) UUID that was decided
`decision`	`"approved" \| "denied"`	是	Ballot outcome that was recorded: approved or denied
`gate_status`	`"pending" \| "active" \| "passed" \| "failed" \| "skipped"`	是	Resulting gate lifecycle state after this ballot
`process_status`	`"in_review" \| "approved" \| "rejected" \| "cancelled"`	是	Resulting process lifecycle state after this ballot

範例

核准一筆覆核指派

請求

{
  "pathParams": {
    "assignment_id": "99999999-9999-4999-8999-999999999999"
  },
  "body": {
    "decision": "approved",
    "comment": "內容正確"
  }
}

回應200

{
  "assignment_id": "99999999-9999-4999-8999-999999999999",
  "decision": "approved",
  "gate_status": "passed",
  "process_status": "approved"
}

錯誤

狀態	發生條件	錯誤本文
404	指派不存在，或不屬於目前登入者。	`{ "detail": "Assignment not found" }`
409	投票已處理、關卡已失效，或流程已不在覆核中。	`{ "detail": "Ballot already resolved" }`
422	否決時缺少非空白註解，或簽名附件不符合要求。	`{ "detail": "A non-empty comment is required when denying" }`