farmos-land-portfolio（法莫斯土地组合）

FarmOS Land Portfolio

Track owned and leased land, lease terms, landlord relationships, payments, and annual land costs.

CRITICAL: Data Completeness Rules

NEVER use partial or truncated data. These rules are non-negotiable:

1. NEVER use /api/integration/dashboard — it truncates results to 5 items. Partial payment data is worse than no data because it creates a false sense of completeness.
2. ALWAYS use the /all endpoints listed below for complete data.
3. If an endpoint returns an error or empty results, REPORT THE FAILURE to the user. Do not silently fall back to a different endpoint or present partial data.
4. ALWAYS state the total count of records returned so the user knows the data is complete. Example: "Found 11 payments due in March totaling $175,058."
5. If you cannot get complete data, say so explicitly. "I was unable to retrieve complete payment data" is infinitely better than showing 5 of 11 payments.

When This Skill Triggers

• "When do our leases expire?"
• "What's the rent on the Smith ground?"
• "Total land costs this year?"
• "Show overdue payments"
• "Landlord contact info"
• "Cost per acre by parcel"
• "List all leased parcels"
• "What payments are due in March?"
• "Cash requirements for next month"
• "Mark payment [X] as paid"
• "Mark all March payments paid"
• "Renew the Smith lease"
• "Preview lease renewals"

Access Control

Lease terms, rent amounts, and landlord info are sensitive business data. Restrict to admin or manager roles only.

Role mapping: Check the sender's role in ~/.openclaw/farmos-users.json. If the user is not admin or manager, tell them they don't have access to land portfolio data.

API Base

http://100.102.77.110:8009

Integration Endpoints (No Auth Required) — READ OPERATIONS ONLY

IMPORTANT: Use auth endpoints for WRITE operations (mark-paid, renewals). Use integration /all endpoints for READ operations (listing payments, leases, landlords).

Payments (FULL — use this, not dashboard)

GET /api/integration/payments/all

• Returns ALL payments with full details — parcel names, landlord names, overdue status
• Query parameters:

- status — pending, paid, overdue, scheduled - payment_type — rent, mortgage, property_tax, insurance, improvement, other - parcel_id — filter by specific parcel - due_date_from — YYYY-MM-DD range start - due_date_to — YYYY-MM-DD range end - crop_year — filter by crop year

• Examples:

- All overdue: /api/integration/payments/all?status=overdue - March 2026 payments: /api/integration/payments/all?due_date_from=2026-03-01&due_date_to=2026-03-31 - All rent payments: /api/integration/payments/all?payment_type=rent

Upcoming Payments (next N days)

GET /api/integration/payments/upcoming?days=30

• Returns ALL upcoming payments within N days (no truncation)
• Use days=60 or days=90 for longer lookahead

Leases (FULL)

GET /api/integration/leases/all

• Returns ALL leases with landlord contact info, rent terms, expiration status
• Query parameters:

- status — active, expired - landlord_id — filter by landlord

Expiring Leases

GET /api/integration/leases/expiring?days=90

• Returns ALL leases expiring within N days

Landlords (FULL)

GET /api/integration/landlords/all

• Returns ALL landlords with contact info, active lease count, total acres, total rent

Parcels

GET /api/integration/parcels

• Returns ALL parcels with ownership type, acres, county
• Query parameter: ownership_type — owned, leased

Summary Stats

GET /api/integration/summary

• Total acres, owned/leased breakdown, parcel/lease/landlord counts, annual cost

Annual Land Costs (by month and entity)

GET /api/integration/finance/costs?year=2026

• Monthly cost breakdown by category (rent, mortgage, tax, insurance)
• Entity breakdown
• Query parameters: year, entity_id

Cost Per Field (for P&L)

GET /api/integration/finance/cost-per-field?year=2026

• Land costs allocated to production fields
• Query parameters: year, entity_id

Overdue Items

GET /api/integration/tasks/overdue

• All overdue payments and reminders — high priority items

Actionable Items

GET /api/integration/tasks/actionable?days_ahead=30

• Upcoming payments, expiring leases, pending reminders

Authenticated Endpoints — WRITE OPERATIONS

These require JWT auth. See Authentication section below.

Authentication

This skill accesses protected FarmOS endpoints that require a JWT token.

To get a token: Run the auth helper with the appropriate role:

TOKEN=$(~/clawd/scripts/farmos-auth.sh admin)

To use the token: Include it as a Bearer token:

curl -H "Authorization: Bearer $TOKEN" http://100.102.77.110:8009/api/endpoint

Token expiry: Tokens last 15 minutes. If you get a 401 response, request a new token.

Mark Single Payment Paid

POST /api/payments/{id}/mark-paid Authorization: Bearer {token} Content-Type: application/json

Body:

{
  "paid_date": "2026-02-15",
  "notes": "Check #1234"
}

Mark Multiple Payments Paid (Bulk)

POST /api/payments/bulk/mark-paid Authorization: Bearer {token} Content-Type: application/json

Body:

{
  "payment_ids": [12, 34, 56],
  "paid_date": "2026-02-15",
  "notes": "Batch check run"
}

Mark Payments Paid by Date Range

POST /api/payments/bulk/mark-paid-by-date Authorization: Bearer {token} Content-Type: application/json

Body:

{
  "due_date_from": "2026-03-01",
  "due_date_to": "2026-03-31",
  "paid_date": "2026-02-15",
  "payment_type": "rent",
  "notes": "March rent payments"
}

Use this when the user says "mark all March payments as paid" or similar bulk date-based operations.

Preview Lease Renewal

POST /api/leases/renewal-preview Authorization: Bearer {token} Content-Type: application/json

Body:

{
  "lease_ids": [5, 12],
  "new_start_date": "2027-03-01",
  "rent_increase_percent": 3.0
}

Returns: Preview of what the renewed leases would look like, including new payment schedules. Use this BEFORE executing bulk renewals so the user can confirm.

Execute Bulk Lease Renewal

POST /api/leases/bulk-renew Authorization: Bearer {token} Content-Type: application/json

Body:

{
  "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": "Annual renewal with 3% increase"
}

IMPORTANT: Always preview first, confirm with user, then execute.

Year-End Rollover Preview

POST /api/payments/year-end-rollover/preview Authorization: Bearer {token} Content-Type: application/json

Body:

{
  "from_year": 2026,
  "to_year": 2027
}

Returns: Preview of payment schedules that would be created for the new crop year.

Year-End Rollover Execute

POST /api/payments/year-end-rollover/execute Authorization: Bearer {token} Content-Type: application/json

Body:

{
  "from_year": 2026,
  "to_year": 2027,
  "apply_rent_increase": true,
  "rent_increase_percent": 2.5
}

IMPORTANT: This creates next year's payment schedules based on current year leases. Always preview first.

FORBIDDEN Endpoints — Do NOT Use

Key Concepts

• Parcel: A land unit — either owned or leased.
• Lease types: Cash rent, crop share, flex rent.
• Lease expiration: Critical to track — approaching expirations need proactive attention.
• Land payments: Rent, mortgage, property tax, insurance — each with due dates.

Usage Notes

• Lease expiration tracking is the highest-value query — always flag leases expiring within 6 months.
• Payment status (due/overdue) is critical — flag overdue payments immediately.
• Cost per acre analysis helps compare owned vs leased economics.
• Landlord contact info is private — never share outside admin/manager channels.
• When asked about "cash requirements" or "what do we owe", always use /api/integration/payments/all with date filtering to get the COMPLETE picture.
• For financial planning questions, combine /api/integration/payments/all with /api/integration/finance/costs for the full view.
• Write operations: Always use authenticated endpoints for marking payments paid or renewing leases. Preview first when doing bulk operations.
• Bulk payment marking: When user says "mark all March payments paid", use the bulk-by-date endpoint rather than individual calls.