嚮導與排班
替嚮導建檔、派到梯次。開通帳號後,嚮導用手機就能看自己帶的梯次、成員名單,並登記代墊成本。
建檔 → 派到梯次(預派 → 正式派) → 嚮導 portal 看得到這一梯
└→ 開通登入帳號 ────────────────┘「嚮導」與「領隊」只是畫面上的職稱。在後台 →「公司設定」→「出團作業」的「隨團人員職稱」可以改,例:派領隊的旅行社填「領隊 / 導遊」,登山業者填「嚮導 / 協作嚮導」。本篇統一稱「嚮導」。
嚮導建檔
在後台 →「資源」→「嚮導」按新增。只有姓名必填。其他欄位:
- 嚮導分類: 嚮導與公司的關係,例:正職、兼職、外聘。按「嚮導分類」自訂名稱與順序。
- 入行年份: 系統依今年自動算出年資,不能直接填年資。
- 聯絡電話、聯絡 Email、專長路線、個人簡介。
- 內部備註: 只給員工看,派嚮導時會一起顯示。
- 狀態: 封存後不再出現在派班選單。資料保留,改回啟用即可再用。
嚮導清單可以拖曳排序,順序全公司共用,派班選單也照這個順序。按「恢復預設順序」會改回依嚮導分類、再依暱稱排。
投保個資
保險名冊與入山、入園申請要用正式資料,不是對外顯示的暱稱。這些欄位在嚮導頁的個資區另外填:
- 正式姓名、英文姓名(與護照一致,自動轉大寫)
- 性別、生日、國籍(外籍才填)、通訊地址
- 身分證或護照號碼(加密保存,畫面預設遮罩)
- 緊急聯絡人與電話
規則:
- 看與改個資要另外的權限。能編嚮導介紹,不代表看得到身分證。內建角色只有管理員與 OP 有這個權限。
- 本國嚮導的身分證會驗檢查碼。同一張證件只能屬於一位嚮導。
- 每次顯示證件全碼都會留下稽核紀錄。
批次匯入
人數多時,用「批次匯入嚮導」一次建立或更新:
- 下載範本,一列填一位嚮導。
- 上傳 Excel 或 CSV(5 MB、500 列以內)。
- 看預覽。暱稱和既有嚮導相同就更新那位,留空的欄位不變;否則新建。有錯的列會標出原因,不會匯入,也不影響其他列。
- 確認後寫入。
證照
一位嚮導可以有多張證照。每張填類別、發證日、到期日(留空表示終身有效),可加證號與掃描件。
- 證照類別由公司自訂。停用的類別不能再選,既有證照保留。還有證照在用的類別不能刪。
- 證號與掃描件算個資,要有個資權限才看得到、才能改或刪。
- 派班時,系統用梯次的回程日檢查證照。回程前到期標「出團期間失效」;回程日加上提醒天數後才到期,標「即將到期」。提醒天數在「公司設定」→「出團作業」調整,預設 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,在嚮導頁按「開通嚮導登入帳號」:
- 先輸入密碼或驗證碼,確認是你本人。
- 確認姓名。登入 Email 是嚮導資料裡的聯絡 Email。沒有聯絡 Email 時,先到嚮導資料填寫。
- 系統寄啟用信到這個 Email。
- 密碼模式的嚮導從信件連結設定密碼。連結 24 小時內有效,逾時請使用「忘記密碼」。純 Email 模式的邀請只提供登入入口與說明,不要求設定密碼。
系統不顯示密碼,開通的人也拿不到密碼。
嚮導帳號看得到排班梯次全部旅客的資料,所以只有管理員能開通。要讓其他人開通,給他的自訂角色「開通嚮導登入帳號」權限。一位嚮導最多一個登入帳號。嚮導不能自己註冊。沒有開通帳號的嚮導,仍可以被派班。
嚮導 portal
嚮導登入後看到「我帶的梯次」,不是後台。只有正式派給他的梯次才看得到。 別人的梯次與旅客一律看不到。
每個梯次有這些分頁:
| 分頁 | 內容 |
|---|---|
| 出團資訊 | 集合、行程、車、餐、住宿等資訊 |
| 成員名單 | 旅客名單與同行分組 |
| 證件 | 旅客證件清單,身分證預設遮罩。顯示全碼會留下稽核紀錄 |
| 成本 | 登記帶隊代墊的款項與發票、收據 |
- 成員名單與證件只開放到回程日後 N 天,之後只剩出團資訊與成本。
- 嚮導登記的成本送出後進後台覆核,不會自動入帳。覆核、轉請款與出款都在後台處理,見請款與出款批次。
- 嚮導看不到應收、實收、毛利等金額。
嚮導 portal 設定
在後台 →「公司設定」→「嚮導 portal」調整:
- 嚮導登入方式: 預設是密碼加兩步驟驗證。可選「密碼登入,免強制綁定第二因素」或「純 Email 驗證碼」。免強制綁定只豁免未綁定者;已綁定者仍要驗證。純 Email 模式每次都要新登入碼,拒絕密碼與 Passkey。一般員工與自訂角色維持原規則。
- 變更政策: 模式實際改變時,全體嚮導的登入、信任裝置與未完成驗證會撤銷。儲存相同模式或只改名單天數不會登出。
- Email 登入: 到租戶後台登入頁,選「嚮導使用 Email 驗證碼登入」。只有已開通且有效的嚮導可申請;切回密碼模式且沒有密碼時,由本人使用「忘記密碼」設定。
- 名單開放天數: 回程日後 N 天當天仍可看名單與證件,隔天起關閉。預設 7 天;填 0 表示回程日隔天就關閉。旅客資料不會刪除,成本登記不受影響。
權限
| 誰 | 能做什麼 |
|---|---|
| 有嚮導管理權限的員工 | 建檔、編輯、封存、開通帳號、管理證照 |
| 有嚮導個資權限的員工 | 看與改投保個資、批次匯入 |
| 有排班權限的員工 | 派嚮導、轉正式、移除指派 |
| 嚮導本人 | 只看自己正式帶的梯次,登記代墊成本 |
角色與權限的全貌見權限與角色。
›API 與 CLI 對應
所有端點見 guides API 與 guide-roster API。
嚮導資料
| 動作 | 端點 | 權限 |
|---|---|---|
| 列出、搜尋 | GET /api/v1/guides | guide.read |
| 建檔 | POST /api/v1/guides | guide.manage |
| 讀取、編輯 | GET /api/v1/guides/{id}、PATCH /api/v1/guides/{id} | guide.read、guide.manage |
| 封存 | POST /api/v1/guides/{id}/archive | guide.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}/pii | guide_pii.read |
| 改個資 | PATCH /api/v1/guides/{id}/pii | guide_pii.manage |
| 顯示證件全碼 | POST /api/v1/guides/{id}/pii/reveal | guide_pii.read |
| 匯入預覽、寫入 | POST /api/v1/guides/import/validate、POST /api/v1/guides/import | guide_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-account | guide.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/guides | guide_roster.read |
| 當月梯次與指派 | GET /api/v1/guide-roster/departures | guide_roster.read |
| 指派或改派 | POST /api/v1/guide-roster/assignments | guide_roster.manage |
| 轉正式 | POST /api/v1/guide-roster/assignments/{id}/confirm | guide_roster.manage |
| 移除指派 | DELETE /api/v1/guide-roster/assignments/{id} | guide_roster.manage |
| 換主要嚮導 | POST /api/v1/guide-roster/change-leader | guide_roster.manage |
| 預檢撞期 | GET /api/v1/guide-roster/conflict-check | guide_roster.read |
| 當月撞期清單 | GET /api/v1/guide-roster/conflicts | guide_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接合,不要用姓名。拉取失敗時保留上一次成功的名冊,不要用空白或部分結果覆蓋。