toko

嚮導與排班

替嚮導建檔、派到梯次。開通帳號後,嚮導用手機就能看自己帶的梯次、成員名單,並登記代墊成本。

txt
建檔 → 派到梯次(預派 → 正式派) → 嚮導 portal 看得到這一梯
     └→ 開通登入帳號 ────────────────┘

「嚮導」與「領隊」只是畫面上的職稱。在後台 →「公司設定」→「出團作業」的「隨團人員職稱」可以改,例:派領隊的旅行社填「領隊 / 導遊」,登山業者填「嚮導 / 協作嚮導」。本篇統一稱「嚮導」。

嚮導建檔

在後台 →「資源」→「嚮導」按新增。只有姓名必填。其他欄位:

  • 嚮導分類: 嚮導與公司的關係,例:正職、兼職、外聘。按「嚮導分類」自訂名稱與順序。
  • 入行年份: 系統依今年自動算出年資,不能直接填年資。
  • 聯絡電話、聯絡 Email、專長路線、個人簡介。
  • 內部備註: 只給員工看,派嚮導時會一起顯示。
  • 狀態: 封存後不再出現在派班選單。資料保留,改回啟用即可再用。

嚮導清單可以拖曳排序,順序全公司共用,派班選單也照這個順序。按「恢復預設順序」會改回依嚮導分類、再依暱稱排。

投保個資

保險名冊與入山、入園申請要用正式資料,不是對外顯示的暱稱。這些欄位在嚮導頁的個資區另外填:

  • 正式姓名、英文姓名(與護照一致,自動轉大寫)
  • 性別、生日、國籍(外籍才填)、通訊地址
  • 身分證或護照號碼(加密保存,畫面預設遮罩)
  • 緊急聯絡人與電話

規則:

  • 看與改個資要另外的權限。能編嚮導介紹,不代表看得到身分證。內建角色只有管理員與 OP 有這個權限。
  • 本國嚮導的身分證會驗檢查碼。同一張證件只能屬於一位嚮導。
  • 每次顯示證件全碼都會留下稽核紀錄。

批次匯入

人數多時,用「批次匯入嚮導」一次建立或更新:

  1. 下載範本,一列填一位嚮導。
  2. 上傳 Excel 或 CSV(5 MB、500 列以內)。
  3. 看預覽。暱稱和既有嚮導相同就更新那位,留空的欄位不變;否則新建。有錯的列會標出原因,不會匯入,也不影響其他列。
  4. 確認後寫入。

證照

一位嚮導可以有多張證照。每張填類別、發證日、到期日(留空表示終身有效),可加證號與掃描件。

  • 證照類別由公司自訂。停用的類別不能再選,既有證照保留。還有證照在用的類別不能刪。
  • 證號與掃描件算個資,要有個資權限才看得到、才能改或刪。
  • 派班時,系統用梯次的回程日檢查證照。回程前到期標「出團期間失效」;回程日加上提醒天數後才到期,標「即將到期」。提醒天數在「公司設定」→「出團作業」調整,預設 60 天。這只是提醒,不擋派班。

派嚮導到梯次

在後台 →「梯次」→「帶團排班」操作。頁面有兩個分頁。

派嚮導清單

一梯一列,直接在列上派人。預設只列要處理的梯次:

  • 已成團、但還沒派滿人的梯次。
  • 還沒成團,但差幾人以內就成團的梯次。人數在「公司設定」→「出團作業」的「派嚮導清單:差幾人算快成團」設定,預設 2 人;填 0 只列已成團的梯次。

按「顯示全部」列出所有還沒結束的梯次。標成「不需嚮導」的梯次永遠不列。

派人的方式:

動作結果
預派先把人排進去,還不算數,不寄信
正式派正式確認,寄派任信給嚮導
轉正式把預派改成正式,寄派任信給嚮導

選嚮導時,這幾天已派到別梯的人會標出撞到哪一梯。

排班矩陣

以月為單位,看每位嚮導每天在哪一梯、這個月帶了幾天。跨月的梯次按實際日期拆開算:10/29 出發、11/2 回程的梯次,10 月算 3 天、11 月算 2 天。嚮導的每月上限天數也照這個算法比對。

帶團期間與綁名

行程可用 guideStartDay、guideEndDay 指定帶團期間。D1 是出發日,兩欄須成對設定。兩欄為 null 時使用完整梯次。 每筆指派可用 guideStartDate、guideEndDate 覆寫日期,格式為 YYYY-MM-DD。兩欄須成對設定;兩欄傳 null 時回復行程預設。 系統依實際帶團期間計算排班天數與撞期。開始日和結束日都計入。

isNameBound 表示這筆指派已綁名。移除或解除綁名時,必須提供 nameBoundChangeReason。 換主要隨團人員使用原本的 reason,不論是否綁名都必填。未另外指定 nameBoundChangeReason 時,系統使用換人原因。原因會記入稽核紀錄。

API 編輯指派沿用 POST /api/v1/guide-roster/assignments。帶入同一組梯次與嚮導 ID,以及原本角色與狀態。 省略日期或綁名欄位會保留原值。移除指派的 nameBoundChangeReason 放在 DELETE 查詢參數。 撞期預檢 GET /api/v1/guide-roster/conflict-check 可帶成對日期,檢查預計帶團期間。

撞期

同一位嚮導在實際帶團日期重疊的兩個梯次都是正式指派,就是撞期。系統會擋下會造成撞期的正式派。預派不擋。在排班矩陣的指派視窗選好嚮導時,畫面會先顯示有沒有檔期衝突。

開通嚮導登入帳號

要讓嚮導登入自己的 portal,在嚮導頁按「開通嚮導登入帳號」:

  1. 先輸入密碼或驗證碼,確認是你本人。
  2. 確認姓名。登入 Email 是嚮導資料裡的聯絡 Email。沒有聯絡 Email 時,先到嚮導資料填寫。
  3. 系統寄啟用信到這個 Email。
  4. 密碼模式的嚮導從信件連結設定密碼。連結 24 小時內有效,逾時請使用「忘記密碼」。純 Email 模式的邀請只提供登入入口與說明,不要求設定密碼。

系統不顯示密碼,開通的人也拿不到密碼。

嚮導帳號看得到排班梯次全部旅客的資料,所以只有管理員能開通。要讓其他人開通,給他的自訂角色「開通嚮導登入帳號」權限。一位嚮導最多一個登入帳號。嚮導不能自己註冊。沒有開通帳號的嚮導,仍可以被派班。

嚮導 portal

嚮導登入後看到「我帶的梯次」,不是後台。只有正式派給他的梯次才看得到。 別人的梯次與旅客一律看不到。

每個梯次有這些分頁:

分頁內容
出團資訊集合、行程、車、餐、住宿等資訊
成員名單旅客名單與同行分組
證件旅客證件清單,身分證預設遮罩。顯示全碼會留下稽核紀錄
成本登記帶隊代墊的款項與發票、收據
  • 成員名單與證件只開放到回程日後 N 天,之後只剩出團資訊與成本。
  • 嚮導登記的成本送出後進後台覆核,不會自動入帳。覆核、轉請款與出款都在後台處理,見請款與出款批次。
  • 嚮導看不到應收、實收、毛利等金額。

嚮導 portal 設定

在後台 →「公司設定」→「嚮導 portal」調整:

  • 嚮導登入方式: 預設是密碼加兩步驟驗證。可選「密碼登入,免強制綁定第二因素」或「純 Email 驗證碼」。免強制綁定只豁免未綁定者;已綁定者仍要驗證。純 Email 模式每次都要新登入碼,拒絕密碼與 Passkey。一般員工與自訂角色維持原規則。
  • 變更政策: 模式實際改變時,全體嚮導的登入、信任裝置與未完成驗證會撤銷。儲存相同模式或只改名單天數不會登出。
  • Email 登入: 到租戶後台登入頁,選「嚮導使用 Email 驗證碼登入」。只有已開通且有效的嚮導可申請;切回密碼模式且沒有密碼時,由本人使用「忘記密碼」設定。
  • 名單開放天數: 回程日後 N 天當天仍可看名單與證件,隔天起關閉。預設 7 天;填 0 表示回程日隔天就關閉。旅客資料不會刪除,成本登記不受影響。

權限

誰能做什麼
有嚮導管理權限的員工建檔、編輯、封存、開通帳號、管理證照
有嚮導個資權限的員工看與改投保個資、批次匯入
有排班權限的員工派嚮導、轉正式、移除指派
嚮導本人只看自己正式帶的梯次,登記代墊成本

角色與權限的全貌見權限與角色。

›API 與 CLI 對應

所有端點見 guides API 與 guide-roster API。

嚮導資料

動作端點權限
列出、搜尋GET /api/v1/guidesguide.read
建檔POST /api/v1/guidesguide.manage
讀取、編輯GET /api/v1/guides/{id}、PATCH /api/v1/guides/{id}guide.read、guide.manage
封存POST /api/v1/guides/{id}/archiveguide.manage
嚮導分類GET /api/v1/guide-categories、POST /api/v1/guide-categories、PATCH /api/v1/guide-categories/{id}、DELETE /api/v1/guide-categories/{id}guide.read、guide.manage
讀個資(證件遮罩)GET /api/v1/guides/{id}/piiguide_pii.read
改個資PATCH /api/v1/guides/{id}/piiguide_pii.manage
顯示證件全碼POST /api/v1/guides/{id}/pii/revealguide_pii.read
匯入預覽、寫入POST /api/v1/guides/import/validate、POST /api/v1/guides/importguide_pii.manage + guide.manage
證照GET /api/v1/guides/{id}/certificates、POST /api/v1/guides/{id}/certificates、PUT /api/v1/guides/{id}/certificates/{certificateId}、DELETE /api/v1/guides/{id}/certificates/{certificateId}guide.read、guide.manage
證照類別GET /api/v1/guide-certificate-types、POST /api/v1/guide-certificate-types、PATCH /api/v1/guide-certificate-types/{id}、DELETE /api/v1/guide-certificate-types/{id}guide.read、guide.manage
開通登入帳號POST /api/v1/guides/{id}/invite-accountguide.invite_account
  • 嚮導欄位:name(必填,暱稱)、slug、bio、specialties、careerStartYear、contactPhone、contactEmail、status(active、inactive)。yearsExperience 唯讀,送它回 422 validation。
  • 個資欄位:legalName、englishName、gender(male、female、other)、emergencyContactName、emergencyContactPhone、idNumber、passportNo、birthDate、nationality、address。
  • 匯入上傳 JSON { filename, contentBase64 }。
  • 證照欄位:typeId、issuedOn、expiresOn(null 表示終身)、certNumber。送 certNumber 要另有 guide_pii.read + guide_pii.manage;沒有 guide_pii.read 時列表的 certNumber 回 null。到期日早於發證日、類別不存在或已停用回 409。
  • 開通帳號帶 name。登入 Email 取嚮導的 contactEmail,沒有時回 422 validation。回傳 email 與 activationSent,不回傳密碼。純 Email 模式寄入口說明;密碼模式寄設定密碼信。

排班

動作端點權限
當月嚮導名冊與帶團天數GET /api/v1/guide-roster/guidesguide_roster.read
當月梯次與指派GET /api/v1/guide-roster/departuresguide_roster.read
指派或改派POST /api/v1/guide-roster/assignmentsguide_roster.manage
轉正式POST /api/v1/guide-roster/assignments/{id}/confirmguide_roster.manage
移除指派DELETE /api/v1/guide-roster/assignments/{id}guide_roster.manage
換主要嚮導POST /api/v1/guide-roster/change-leaderguide_roster.manage
預檢撞期GET /api/v1/guide-roster/conflict-checkguide_roster.read
當月撞期清單GET /api/v1/guide-roster/conflictsguide_roster.read
  • 指派欄位:role(leader 主要、assistant 協同)、status(tentative 預派、confirmed 正式)。
  • 會造成正式撞期的動作回 409。conflict-check 帶 departureId、guideId,回傳撞到的梯次或 null。conflicts 帶 month=YYYY-MM。
  • change-leader 一次完成換人:移除原主要嚮導,把新的人設成正式主要嚮導。必填 reason,記入稽核紀錄。

嚮導名冊批次輸出

POST /api/v1/guides/roster-export 讓受控的伺服器或排程拉取全公司嚮導名冊,用於保險或入山申請。

  • 權限 guide_pii.roster_export,內建只有 admin 有。可建只含這個權限的自訂角色,再用 CLI 登入 取得 token。token 過期或撤銷時回 401,請重新登入。403 表示權限不足、未完成兩步驟驗證或未開通 API。
  • 回應 { ok: true, data }。data.kind 為 toko.guide-roster、version 為 1、exportedAt 為 UTC 時間,guides 依 id 排序,含 active 與 inactive。
  • 每列欄位:id、status、legalName、gender、birthDate、idNumber、phone、email、address、emergencyContactName、emergencyContactPhone、nickname。未填回 null。
  • 不輸出護照號碼與國籍。只有護照的嚮導,idNumber 回 null。address 是完整字串,不拆縣市鄉鎮。
  • 每次輸出記錄操作者、時間與筆數,不記名冊內容。失敗回 500 internal,不回部分名冊。回應帶 Cache-Control: private, no-store。
  • 呼叫端請以 id 接合,不要用姓名。拉取失敗時保留上一次成功的名冊,不要用空白或部分結果覆蓋。

相關指南

Command Palette

Search for a command to run...