需求方窗口

需求方（組織身份 requester）在 /r 前台留言提需求，一則需求是一條對話（conversation）。組織裡的窗口負責回覆、開票、回報進度。這份說明給當窗口的人或 agent 用。

• 誰是窗口
• 被叫醒：事件游標
• 對話 API
• 需求方看到的狀態：站屬性 requester_dialog
• 錯誤
• 限制

誰是窗口#

• 接待窗口：組織設定的一位（GET https://station-flow.staging.quanhox.com.tw/api/v1/auth/me 回的 organization.requester_reception_user_id）。還沒開票的對話、被退回的對話都歸他。
• 例行事務窗口＝該例行事務的事務負責人（GET https://station-flow.staging.quanhox.com.tw/api/v1/routines/{id} 回的 owner）。開票後對話轉給這條 routine 的負責人。
• 負責人不是本組織 admin 或 staff（被移出組織、或改成需求方）時，由接待窗口代接。
• 換事務負責人時，舊負責人手上這條 routine 還沒結束的對話會一起轉給新負責人。
• 每條對話的 handler_user_id 是目前的負責窗口。只有他能回覆、開票、轉手；其他人回 409 not_current_handler。

被叫醒：事件游標#

curl -s "https://station-flow.staging.quanhox.com.tw/api/v1/me/requester-events?since=0" \
  -H "Authorization: Bearer $SF_KEY" -H "Accept: application/json"

回 data（事件陣列）、next_since、has_more。下次把 next_since 帶進 since；has_more 是 true 就馬上再抓一頁（一頁 100 筆）。事件只回 5 秒前建立的，不會漏。

每筆事件有 id、type、conversation_id、task_id、created_at，不帶內文，要看內容再打對話詳情。自己做的動作不會叫醒自己。

對話 API#

以下都在 https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations 底下，帶同樣兩個 header。讀不到的對話回 404。

列表與詳情

• GET https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations：你的收件匣，需求方在等回覆的排最上。unbound=1 只看未開票，project=<id> 篩專案。每列有 handler_user_id、task_id、awaiting_handler、unread。
• GET https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}：詳情與貼文。帶 since=<上次的 last_post_id> 只抓新貼文。貼文的 visibility 是 requester（需求方看得到）或 internal（內部備註）。
• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}/read：標已讀，可帶 post_id，省略＝讀到最新。

回覆

curl -s -X POST "https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/42/posts" \
  -H "Authorization: Bearer $SF_KEY" -H "Accept: application/json" \
  -F "body=收到，我們今天下午回您" -F "files[]=@draft.png"

• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}/posts：body 必填；internal=1 存成內部備註；files[] 最多 10 個、每個 50MB。
• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}/replied：不留言，只標「已回覆」。

開票與分流

curl -s -X POST "https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/42/tickets" \
  -H "Authorization: Bearer $SF_KEY" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"tickets":[{"name":"廣告 A","routine_id":7,"project_id":3}],"handoff_summary":"需求原話、已問到的資訊、選這條流程的理由"}'

• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}/tickets：tickets 1–20 張，每張要 name、routine_id、project_id。開票後對話轉給該 routine 的窗口；換人時 handoff_summary 必填（422 handoff_summary_required）。同一人不用寫。已開過票回 409 already_bound；你不在開始站角色、又不是 admin／接待窗口／事務負責人回 403 routine_forbidden。
• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}/split：選幾則貼文（post_ids）拆成新對話＋新票，tickets 只取第一張。
• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}/handoff：已開票的對話重新交給該 routine 的現任窗口，可帶 handoff_summary。沒開票回 422 not_bound。
• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}/return：覺得不是你的，退回接待窗口，reason 必填。沒開票或你就是接待窗口回 409 cannot_return。

從票開對話（票是窗口自己開的、沒有需求方對話時）

• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/tasks/{task}/conversations：替這張票對指定需求方開一條對話並綁票。requester_user_id 必填，body（第一則訊息，10000 字內）可省略。回 201 {"data":{"conversation_id":…,"task_id":…}}。你就是這條對話的負責窗口，之後照常用上面的 posts／cards／progress。

curl -s -X POST "https://station-flow.staging.quanhox.com.tw/api/v1/requester/tasks/120/conversations" \
  -H "Authorization: Bearer $SF_KEY" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"requester_user_id":31,"body":"今天的題目請您確認"}'

• 只有該票 routine 的事務負責人（owner）或組織 admin 能開，其他人 403 task_forbidden。票或需求方不在你目前的組織回 404。
• requester_user_id 可以是本組織的需求方，或開了「兼任需求方」開關的內部成員（admin／staff，見下）。兩者都不是回 422（errors.requester_user_id）。
• 票已經有對話（不論是不是同一位需求方）回 409 conversation_exists，回應多帶 conversation_id，直接沿用那條，不會重建也不會改綁。票已掛另一位需求方回 409 requester_mismatch。
• 需求方在 /r 會多一列，看得到票的狀態與進度，收到推播（有開推播時）。

內部成員兼任需求方（同一個帳號，不改角色）

• PUT https://station-flow.staging.quanhox.com.tw/api/v1/organization/members/{user}/requester-access，body {"enabled": true|false}：只有目前組織的 admin 能設，其他人 403；對象不在本組織 404；對象本身是需求方回 422（不需要開關）。回 200 {"data":{"user_id":…,"role":…,"requester_access":…}}。
• 開了之後，這位成員可以被上面的端點指定為需求方，收到 conversation_opened 事件與 /r 推播；他從後台登入後開 /r，只看得到自己是需求方的對話。後台權限不受影響。
• 關掉後立刻失效，下一個 request 起 /r 就進不去。目前沒有設定畫面，只能用 API。

進度、交付、卡片

• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}/progress：body（500 字內）、expected_on（預計日期，可省略）。
• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}/deliverables：把對話裡的附件（attachment_id）標成交付物，放進專案的公開目錄。票沒掛專案回 422 project_required。
• POST https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/{id}/cards：發問卷或確認卡。

curl -s -X POST "https://station-flow.staging.quanhox.com.tw/api/v1/requester/conversations/42/cards" \
  -H "Authorization: Bearer $SF_KEY" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"kind":"questionnaire","body":"請選尺寸","questions":[{"label":"尺寸","options":["1:1","9:16"]}]}'

kind 是 questionnaire 或 confirm。問卷最多 20 題、每題 2–20 個選項；確認卡要先開票（422 not_bound）。

卡片綁定發卡當下的票和站。票離開那一站（送出口、退回、改綁別張票），還沒答的卡就失效：GET 對話時卡片帶 stale: true，需求方前台顯示「已處理，不需要回覆」，按不了；硬送回 409 card_handled。開票前發的問卷沒綁票，不會失效。

需求方前台每題會自動多一個「其它」選項（不會寫進 questions[].options，發卡時別自己加）。需求方選其它時可寫文字、附檔或貼上圖片。答完後 GET 對話，card 帶：

• answers[i]：選項字串；選其它時是 "其它"。

• others：物件，題號 → {"text": "…或 null", "attachment_ids": [12]}；沒有人選其它時是 null。附件在同一次 GET 的需求方回覆貼文 posts[].attachments 裡，用 id 對得上。

• 有 attribute_key 的題目選了其它，票屬性寫文字；只有附件時寫 其它（見附件）。

• 等需求方回答時，別先送出口。答案回來（questionnaire_answered／confirm_clicked／confirm_rejected 事件）再推進。

• 已經轉站了，就在新站重發一張，舊卡不用管。

需求方看到的狀態：站屬性 requester_dialog#

站的 requester_dialog（PUT https://station-flow.staging.quanhox.com.tw/api/v1/stations/{id}，admin 設）決定需求方在 /r 看到什麼。只能是 discuss、deliver 或 null：

• discuss：討論站。票停在這站時，需求方看到「等您回覆」。
• deliver：交付站。票從這站走正常出口（不是退回）離開，就算交付。
• null：內部站（預設）。需求方只看到「製作中」。

綁票後的狀態，依序判斷：

1. 曾經從交付站走正常出口離開＝已交付。之後被退回或取消也不變。
2. 票在結束站（end）或存查站（archive）：最後一次進結束站時走的是取消類出口＝已取消，其他＝已交付。流程沒設交付站也一樣。最後一次進結束站時，若來源站只有一條出口（例如事務報告），就往前看進入那一站的出口，直到遇到有選擇的出口。
3. 票在討論站，或有需求方還沒答的問卷／確認卡＝等您回覆。
4. 票在開始站＝受理中；其他＝製作中。

取消類出口：出口 tone 是 negative，或出口的來源站是異常站（type=exception）。要讓需求方看到「已取消」，往結束站的取消出口要設 tone: negative，或從異常站接過去。

錯誤#

錯誤回 {"code": "...", "message": "..."}。常見：

限制#

• 需求方只能用 /r 前台，API 不開放。
• 推播給需求方的通知只說「有新訊息／新進度」，不帶內文。