裝備租借
裝備租借讓你把登山裝備（睡袋、冰爪、頭燈⋯⋯）借給旅客：租金與押金自動掛上訂單金流，庫存即時扣減；同時讓線控盤點每個梯次要借多少、跨梯次庫存夠不夠。
本篇從串接的角度說明裝備主檔、租借與歸還的生命週期，以及出團前的 per-departure 裝備需求盤點。裝備租借屬登山模組——未開通該模組的租戶，相關端點不存在。
裝備主檔
裝備主檔是可租借品項的清單（GET /equipment/items）。每個品項帶價格與一組庫存數字：
| 欄位（回傳） | 意義 |
|---|---|
name / category / spec | 品名、分類、規格 |
rentPriceTwd | 每日租金（整數台幣） |
depositTwd | 每件押金（整數台幣） |
totalCount | 庫存總數 |
outCount | 在租中（借出未還） |
maintenanceCount | 維修中、不可租借 |
availableCount | 可租數量（派生） |
isActive | 是否啟用 |
availableCount = totalCount − outCount − maintenanceCount，是算出來的可租量。outCount 由租借單自動扣減——你不直接設定在租量；要調整庫存改 totalCount 或 maintenanceCount（PATCH /equipment/items/{id}）。若把數字改到 在租 + 維修 > 總數，會被擋下回 409。
租借與歸還
一張租借單（rental）綁定一張訂單：你借出哪些品項、各借幾件，租金與押金就掛上那張訂單的應收。生命週期由 returnState（在租 / 已還 / 逾期）與 reconState（驗收結算）兩個狀態表達：
開租借單（POST /equipment/rentals）帶 orderId 與 lines（每筆 equipmentItemId + 數量），可選 departureId、renterName、rentStartDate / rentEndDate：
- 借出會即時扣庫存。若可租量不足，整筆失敗回
409（不會部分借出）；品項或訂單不存在回404。 - 成交當下會把每筆的租金與押金快照進明細（
rentPriceTwdSnapshot/depositTwdSnapshot）——事後改主檔價格不回頭改已開的租借單。 - 開單會在綁定訂單上產生租金應收與押金應收，並接上收款計畫。押金是代收暫收的一筆錢，跟租金一樣向客人收。
開租借單會動到綁定訂單的金流（新增應收、收款計畫與收款）。它不是孤立的庫存動作——租金與押金一律經訂單收款，請搭配訂單與金流模型理解。
歸還驗收（POST /equipment/rentals/{id}/return）帶 returnedLines（各明細歸還數量），可選 damageCostTwd：
- 歸還會把對應數量回補可租量；歸還數超過在租量回
409。 - 無破損 →
reconState結為reconciled，押金照退款流程退還客人。 - 有破損 → 登記
damageCostTwd、reconState轉deposit_pending（待結押金）；損壞費從押金扣抵，未退的部分留作收入。
歸還本身不退錢、不自動沖帳。押金的退還（或損壞扣抵後的餘額）一律走訂單的退款流程，由會計事後發起——驗收只負責盤點與結算狀態。
讀取用 GET /equipment/rentals（可依 returnState / reconState / orderId / departureId 篩選）與 GET /equipment/rentals/{id}（含明細與派生的 rentTotalTwd / depositTotalTwd）。
逾期
過了租期末日仍在租的單，會被標為逾期（POST /equipment/rentals/{id}/mark-overdue，平台也有排程自動掃描）：
- 逾期只改狀態（
returnState = overdue），不動庫存——東西還在客人手上、可租量不會回補。 - 逾期單照常可以走歸還驗收結案。
用 returnState=overdue 篩 GET /equipment/rentals 即可列出所有逾期未還的單。
出團裝備需求（per-departure）
租借單是「旅客真的借了」；裝備需求則是線控在某個梯次盤點「預計要借多少」——兩條線各自獨立、不重複扣款。需求掛在梯次上（POST /api/v1/departures/{depId}/prep/equipment-needs）：
- 每個梯次、每個品項一筆需求量；對同品項再送一次是覆寫數量，不是累加。把數量設為 0 或刪除該筆即移除需求。
- 平台會把同一段日期窗內各梯次對同一品項的需求加總，對比主檔可租量，提示是否超收或庫存吃緊——讓你在某梯次調查需求時，看見同窗其他梯次也借同款導致的缺口。
裝備需求屬於出團前準備的一環，由線控在梯次層維護；它是盤點與預警工具，不扣庫存、不產生應收。真正動庫存與金流的是上面的租借單。
下一步
- 出團準備與線控：per-departure 的裝備、分房、護照等盤點軸怎麼一起跑。
- 訂單與金流模型：租金與押金如何掛上訂單的應收與收款。
- 付款流程：押金退還與損壞扣抵走的退款流程。
- equipment API。