FarmOS 土地组合管理
跟踪自有和租赁土地、租约条款、地主关系、付款和年度土地成本。
关键:数据完整性规则
切勿使用部分或截断的数据。以下规则不可协商:
- 切勿使用
/api/integration/dashboard— 它仅返回5条结果。部分付款数据比没有数据更糟糕,因为它会造成完整性的假象。 - 始终使用下面列出的
/all端点获取完整数据。 - 如果端点返回错误或空结果,请向用户报告失败。 不要静默地回退到其他端点或呈现部分数据。
- 始终说明返回的记录总数,以便用户知道数据是完整的。例如:“发现3月份有11笔到期付款,总计$175,058。”
- 如果无法获取完整数据,请明确说明。 “我无法获取完整的付款数据”远比仅显示5笔中的11笔付款要好得多。
该技能触发场景
- “我们的租约什么时候到期?”
- “Smith地块的地租是多少?”
- “今年的土地总成本?”
- “显示逾期付款”
- “地主联系信息”
- “每英亩成本按地块划分”
- “列出所有租赁地块”
- “3月份有哪些付款到期?”
- “下个月的现金需求”
- “将付款 [X] 标记为已付”
- “将所有3月份付款标记为已付”
- “续签Smith租约”
- “预览租约续签”
访问控制
租约条款、租金金额和地主信息属于敏感业务数据。仅限管理员或经理角色访问。
角色映射: 在 ~/. 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认证。请参阅下面的认证部分。
认证
该技能访问需要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": "三月份地租"
}
当用户说“将所有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): 一个土地单元 — 自有的或租赁的。
- 租约类型 (Lease types): 现金地租、作物分成、灵活地租。
- 租约到期 (Lease expiration): 关键追踪项 — 即将到期需要主动关注。
- 土地付款 (Land payments): 地租、按揭、房产税、保险 — 各有到期日。
使用说明
- 租约到期跟踪是最高价值的查询 — 始终标记未来6个月内到期的租约。
- 付款状态(到期/逾期)至关重要 — 立即标记逾期付款。
- 每英亩成本分析有助于比较自有和租赁的经济效益。
- 地主联系信息是私密的 — 切勿在管理员/经理渠道之外共享。
- 当被问及“现金需求”或“我们欠什么”时,始终使用带有日期过滤的
/api/integration/payments/all来获取完整情况。 - 对于财务规划问题,结合使用
/api/integration/payments/all和/api/integration/finance/costs以获得完整视图。 - 写入操作: 标记付款已付或续签租约时,始终使用已认证的端点。在执行批量操作时,请先进行预览。
- 批量付款标记: 当用户说“将所有3月份付款标记为已付”时,使用按日期批量端点,而不是单独调用。