FarmOS 土地組合
追蹤自有與租賃土地、租約條款、地主關係、付款以及年度土地成本。
關鍵:資料完整性規則
絕對不可使用部分或不完整的資料。以下規則沒有協商空間:
- 絕對不可使用
/api/integration/dashboard— 它會將結果截斷為 5 筆資料。不完整的付款資料比沒有資料更糟,因為它會造成資料完整的假象。 - 一律使用下方列出的
/all端點 以取得完整資料。 - 若端點回傳錯誤或空結果,請向使用者報告失敗。 不要默默退回其他端點或呈現部分資料。
- 一律說明回傳的記錄總數,讓使用者知道資料是完整的。範例:「找到 3 月份有 11 筆待付款,總計 $175,058。」
- 若無法取得完整資料,請明確告知。 「我無法取得完整的付款資料」遠比僅顯示 11 筆付款中的 5 筆要好。
觸發此技能的時機
- 「我們的租約何時到期?」
- 「Smith 地塊的租金是多少?」
- 「今年的土地總成本是多少?」
- 「顯示逾期付款」
- 「地主的聯絡資訊」
- 「每英畝成本按地塊劃分」
- 「列出所有租賃地塊」
- 「3 月份有哪些付款即將到期?」
- 「下個月的現金需求」
- 「將付款 [X] 標記為已付」
- 「將所有 3 月付款標記為已付」
- 「續約 Smith 的租約」
- 「預覽租約續約」
存取控制
租約條款、租金金額和地主資訊為敏感的商業資料。僅限管理員或經理角色存取。
角色對應: 檢查 ~/.openclaw/farmos-users.json 中寄件者的角色。若使用者並非管理員或經理,請告知其無權存取土地組合資料。
API 基礎位址
整合端點(無需驗證)— 僅限讀取操作
重要:寫入操作(標記已付、續約)請使用需要驗證的端點。讀取操作(列出付款、租約、地主)請使用整合 /all 端點。
付款(完整 — 使用此端點,非儀表板)
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 驗證。請參閱下方驗證章節。
驗證
此技能存取受保護的 FarmOS 端點,需要 JWT 令牌。
取得令牌: 使用適當角色執行驗證輔助腳本:
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": "3 月租金付款"
}
當使用者說「將所有 3 月付款標記為已付」或類似的大量基於日期的操作時,請使用此端點。
預覽租約續約
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 筆。絕對不可使用。 |
關鍵概念
- 地塊 (Parcel): 土地單位 — 可能為自有或租賃。
- 租約類型: 現金租金、作物分紅、彈性租金。
- 租約到期: 追蹤此項至關重要 — 即將到期的租約需要積極處理。
- 土地付款: 租金、房貸、地產稅、保險 — 每項都有到期日。
使用說明
- 租約到期追蹤是價值最高的查詢 — 務必標記未來 6 個月內到期的租約。
- 付款狀態(到期/逾期)至關重要 — 立即標記逾期付款。
- 每英畝成本分析有助於比較自有與租賃的經濟效益。
- 地主聯絡資訊屬於隱私 — 絕不可在管理員/經理管道外分享。
- 被問到「現金需求」或「我們還欠多少」時,一律使用
/api/integration/payments/all並加上日期篩選,以取得完整的畫面。 - 對於財務規劃問題,請合併使用
/api/integration/payments/all與/api/integration/finance/costs以獲得完整檢視。 - 寫入操作: 將付款標記為已付或續約租約時,一律使用需驗證的端點。進行大量操作時,務必先進行預覽。
- 大量付款標記: 當使用者說「將所有 3 月付款標記為已付」時,請使用大量按日期標記的端點,而非逐筆呼叫。