FarmOS 土地组合管理
追踪自有和租赁土地、租赁条款、地主关系、付款以及年度土地成本。
关键:数据完整性规则
切勿使用部分或截断的数据。以下规则不可协商:
- 绝不使用
/api/integration/dashboard— 它仅返回 5 条结果。部分付款数据比没有数据更糟糕,因为它会产生虚假的完整性错觉。 - 始终使用下面列出的
/all端点 以获取完整数据。 - 如果端点返回错误或空结果,将失败情况报告给用户。 不要默默回退到其他端点或呈现部分数据。
- 始终说明返回的记录总数,以便用户知道数据是完整的。例如:“找到 3 月份应付的 11 笔付款,总计 175,058 美元。”
- 如果无法获取完整数据,请明确说明。 “我无法检索完整的付款数据”远比仅显示 11 笔付款中的 5 笔要好。
触发此技能的场景
- “我们的租赁什么时候到期?”
- “史密斯地块的租金是多少?”
- “今年的总土地成本是多少?”
- “显示逾期的付款”
- “地主联系信息”
- “按地块计算每英亩成本”
- “列出所有租赁的地块”
- “3 月份有哪些付款到期?”
- “下个月的现金需求是多少?”
- “将付款 [X] 标记为已支付”
- “将所有 3 月付款标记为已支付”
- “续约史密斯租赁”
- “预览租赁续约”
访问控制
租赁条款、租金金额和地主信息属于敏感业务数据。仅限于管理员或经理角色访问。
角色映射: 在 ~/.openclaw/farmos-users.json 中检查发送者的角色。如果用户不是管理员或经理,请告知他们无权访问土地组合数据。
API 基础地址
集成端点(无需认证)— 仅读取操作
重要:写入操作(标记已支付、续约)使用认证端点。读取操作(列出付款、租赁、地主)使用集成 /all 端点。
付款(完整 — 使用此端点,不要使用仪表板)
GET /api/integration/payments/all
- 返回所有付款及完整详情 — 地块名称、地主姓名、逾期状态
- 查询参数:
status— pending, paid, overdue, scheduledpayment_type— rent, mortgage, property_tax, insurance, improvement, otherparcel_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, expiredlandlord_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 月付款标记为已支付”或类似基于日期的批量操作时使用此端点。
预览租赁续约
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以获得全景视图。 - 写入操作: 始终使用认证端点进行标记付款已支付或续约租赁。批量操作时先预览。
- 批量付款标记: 当用户说“将所有 3 月付款标记为已支付”时,使用按日期批量端点而不是单个调用。