FarmOS 土地投資組合
追蹤自有與承租土地、租約條款、地主關係、支付款項以及年度土地成本。
關鍵:資料完整性規則
絕對不要使用部分或不完整的資料。以下規則無可協商:
- 絕對不要使用
/api/integration/dashboard—— 它會將結果截斷為 5 筆。不完整的支付資料比沒有資料更糟,因為它會造成虛假的安全感。 - 一律使用下面列出的
/all端點 來取得完整資料。 - 如果端點回傳錯誤或空結果,請向使用者回報失敗。 不要默默改用其他端點或呈現部分資料。
- 務必說明回傳的記錄總數,讓使用者知道資料是完整的。例如:「找到 11 筆 3 月到期的付款,總計 $175,058。」
- 如果無法取得完整資料,請明確告知。 「我無法取得完整的支付資料」遠比只顯示 11 筆中的 5 筆來得好。
觸發此技能的時機
- 「我們的租約何時到期?」
- 「Smith 那塊地的租金是多少?」
- 「今年的總土地成本?」
- 「顯示逾期付款」
- 「地主聯絡資訊」
- 「每英畝成本,按地塊劃分」
- 「列出所有承租地塊」
- 「三月有哪些付款到期?」
- 「下個月的資金需求」
- 「將支付 [X] 標記為已付款」
- 「將所有三月付款標記為已付款」
- 「續約 Smith 的租約」
- 「預覽租約續約」
存取控制
租約條款、租金金額和地主資訊屬於敏感的商業資料。僅限管理員或經理角色存取。
角色對應: 檢查發送者在 ~/.openclaw/farmos-users.json 中的角色。如果使用者不是管理員或經理,請告知他們沒有存取土地投資組合資料的權限。
API 基礎位址
整合端點(無需驗證)—— 僅供讀取操作
重要:寫入操作(標記已付款、續約)請使用需要驗證的端點。讀取操作(列出付款、租約、地主)請使用整合式的 /all 端點。
付款(完整資料 —— 使用此端點,不要用 dashboard)
GET /api/integration/payments/all
- 回傳所有付款的完整詳細資料 —— 地塊名稱、地主姓名、逾期狀態
- 查詢參數:
status—— pending(待處理)、paid(已付款)、overdue(逾期)、scheduled(已排程)payment_type—— rent(租金)、mortgage(抵押貸款)、property_tax(財產稅)、insurance(保險)、improvement(改良)、other(其他)parcel_id—— 按特定地塊篩選due_date_from—— YYYY-MM-DD 範圍起始due_date_to—— YYYY-MM-DD 範圍結束crop_year—— 按作物年份篩選
- 範例:
- 所有逾期:
/api/integration/payments/all?status=overdue - 2026 年 3 月付款:
/api/integration/payments/all?due_date_from=2026-03-01&due_date_to=2026-03-31 - 所有租金付款:
/api/integration/payments/all?payment_type=rent
- 所有逾期:
即將到來的付款(未來 N 天)
GET /api/integration/payments/upcoming?days=30
- 回傳未來 N 天內的所有即將到來的付款(無截斷)
- 使用
days=60或days=90進行更長期的預測
租約(完整資料)
GET /api/integration/leases/all
- 回傳所有租約,包含地主聯絡資訊、租金條款、到期狀態
- 查詢參數:
status—— active(有效)、expired(已到期)landlord_id—— 按地主篩選
即將到期的租約
GET /api/integration/leases/expiring?days=90
- 回傳 N 天內到期的所有租約
地主(完整資料)
GET /api/integration/landlords/all
- 回傳所有地主,包含聯絡資訊、有效租約數量、總英畝數、總租金
地塊
GET /api/integration/parcels
- 回傳所有地塊,包含所有權類型、英畝數、縣市
- 查詢參數:
ownership_type—— owned(自有)、leased(承租)
摘要統計
GET /api/integration/summary
- 總英畝數、自有/承租細項、地塊/租約/地主數量、年度成本
年度土地成本(按月與實體劃分)
GET /api/integration/finance/costs?year=2026
- 按月劃分的成本細項(租金、抵押貸款、稅金、保險)
- 按實體劃分的成本細項
- 查詢參數:
year、entity_id
每塊地的成本(用於損益表)
GET /api/integration/finance/cost-per-field?year=2026
- 分配到生產田地的土地成本
- 查詢參數:
year、entity_id
逾期項目
GET /api/integration/tasks/overdue
- 所有逾期付款與提醒 —— 高優先級項目
可操作項目
GET /api/integration/tasks/actionable?days_ahead=30
- 即將到來的付款、即將到期的租約、待處理的提醒
需驗證的端點 —— 寫入操作
這些需要 JWT 驗證。請參閱下方的驗證章節。
驗證
此技能存取需要 JWT 權杖的受保護 FarmOS 端點。
取得權杖: 使用適當的角色執行驗證輔助腳本:
TOKEN=$(~/clawd/scripts/farmos-auth.sh admin)
使用權杖: 將其作為 Bearer 權杖包含在請求中:
curl -H "Authorization: Bearer $TOKEN" http://100.102.77.110:8009/api/endpoint
權杖到期: 權杖有效期為 15 分鐘。如果收到 401 回應,請請求新的權杖。
將單一付款標記為已付款
POST /api/payments/{id}/mark-paid Authorization: Bearer {token} Content-Type: application/json
請求主體:
{
"paid_date": "2026-02-15",
"notes": "支票 #1234"
}
將多筆付款標記為已付款(大量)
POST /api/payments/bulk/mark-paid Authorization: Bearer {token} Content-Type: application/json
請求主體:
{
"payment_ids": [12, 34, 56],
"paid_date": "2026-02-15",
"notes": "批次支票處理"
}
按日期區間將付款標記為已付款
POST /api/payments/bulk/mark-paid-by-date Authorization: Bearer {token} Content-Type: application/json
請求主體:
{
"due_date_from": "2026-03-01",
"due_date_to": "2026-03-31",
"paid_date": "2026-02-15",
"payment_type": "rent",
"notes": "三月租金付款"
}
當使用者說「將所有三月付款標記為已付款」或類似的大量日期型操作時,請使用此端點。
預覽租約續約
POST /api/leases/renewal-preview Authorization: Bearer {token} Content-Type: application/json
請求主體:
{
"lease_ids": [5, 12],
"new_start_date": "2027-03-01",
"rent_increase_percent": 3.0
}
回傳:續約後租約的預覽內容,包含新的付款排程。請在執行大量續約之前使用此端點,以便使用者確認。
執行大量租約續約
POST /api/leases/bulk-renew Authorization: Bearer {token} Content-Type: application/json
請求主體:
{
"lease_ids": [5, 12],
"new_start_date": "2027-03-01",
"new_end_date": "2028-02-28",
"new_rent_amount": 52000.00,
"rent_increase_percent": 3.0,
"notes": "年度續約,調漲 3%"
}
重要: 務必先預覽、經使用者確認後再執行。
年終結轉預覽
POST /api/payments/year-end-rollover/preview Authorization: Bearer {token} Content-Type: application/json
請求主體:
{
"from_year": 2026,
"to_year": 2027
}
回傳:為新作物年度建立的付款排程預覽。
執行年終結轉
POST /api/payments/year-end-rollover/execute Authorization: Bearer {token} Content-Type: application/json
請求主體:
{
"from_year": 2026,
"to_year": 2027,
"apply_rent_increase": true,
"rent_increase_percent": 2.5
}
重要: 此操作會根據當前年度的租約建立下一年度的付款排程。務必先預覽。
禁止使用的端點 —— 請勿使用
| 端點 | 原因 |
|---|---|
GET /api/integration/dashboard | 會將結果截斷為 5 筆。絕對不要使用。 |
關鍵概念
- 地塊: 土地單位 —— 可以是自有或承租。
- 租約類型: 現金地租、作物分成、彈性地租。
- 租約到期: 追蹤此項至關重要 —— 即將到期的租約需要主動處理。
- 土地支付款項: 租金、抵押貸款、財產稅、保險 —— 每項都有到期日。
使用說明
- 租約到期追蹤是價值最高的查詢 —— 務必標記未來 6 個月內到期的租約。
- 支付狀態(到期/逾期)至關重要 —— 立即標記逾期付款。
- 每英畝成本分析有助於比較自有與承租土地的經濟效益。
- 地主聯絡資訊屬於隱私 —— 絕不能在管理員/經理管道之外分享。
- 當被問及「資金需求」或「我們欠什麼」時,一律使用
/api/integration/payments/all並搭配日期篩選,以獲得完整的狀況。 - 對於財務規劃問題,請結合
/api/integration/payments/all與/api/integration/finance/costs以獲得完整視圖。 - 寫入操作: 標記付款為已付款或續約租約時,務必使用需要驗證的端點。進行大量操作時請先預覽。
- 大量標記付款: 當使用者說「將所有三月付款標記為已付款」時,請使用大量日期端點,而不是逐一呼叫。