FarmOS 토지 포트폴리오은(는) 무엇을 하나요?
소유 및 임차 토지, 임대 조건, 임대인 관계, 지불 내역 및 연간 토지 비용을 추적합니다.
중요: 데이터 완전성 규칙
부분적이거나 잘린 데이터를 절대 사용하지 마십시오. 다음 규칙은 반드시 준수해야 합니다:
- 절대
/api/integration/dashboard를 사용하지 마십시오 — 결과가 5개로 잘립니다. 부분적인 지불 데이터는 완전한 데이터가 없는 것보다 더 나쁩니다. 잘못된 완전성 인식을 주기 때문입니다. - 항상 아래 나열된
/all엔드포인트를 사용하여 완전한 데이터를 가져오십시오. - 엔드포인트가 오류를 반환하거나 빈 결과를 반환하면, 사용자에게 오류를 보고하십시오. 다른 엔드포인트로 조용히 대체하거나 부분 데이터를 제시하지 마십시오.
- 항상 반환된 레코드의 총 개수를 명시하여 사용자가 데이터가 완전하다는 것을 알 수 있도록 하십시오. 예: "3월에 납부해야 할 지불 11건, 총액 $175,058을 찾았습니다."
- 완전한 데이터를 얻을 수 없으면 명시적으로 말하십시오. "완전한 지불 데이터를 검색할 수 없습니다"라고 말하는 것이 11건 중 5건만 보여주는 것보다 훨씬 낫습니다.
이 스킬이 트리거되는 경우
- "임대 계약은 언제 만료됩니까?"
- "Smith 땅의 임대료는 얼마입니까?"
- "올해 총 토지 비용은?"
- "연체된 지불 보기"
- "임대인 연락처 정보"
- "필지별 에이커당 비용"
- "임차된 모든 필지 나열"
- "3월에 납부해야 할 지불은 무엇입니까?"
- "다음 달 현금 요구 사항"
- "지불 [X]를 납부됨으로 표시"
- "모든 3월 지불을 납부됨으로 표시"
- "Smith 임대 갱신"
- "임대 갱신 미리보기"
접근 제어
임대 조건, 임대료 금액 및 임대인 정보는 민감한 비즈니스 데이터입니다. admin 또는 manager 역할로만 제한하십시오.
역할 매핑: ~/.openclaw/farmos-users.json에서 발신자의 역할을 확인하십시오. 사용자가 admin 또는 manager가 아니면 토지 포트폴리오 데이터에 접근할 수 없다고 알리십시오.
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월 임대료 지불"
}
사용자가 "모든 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개월 이내에 만료되는 임대 계약에 플래그를 지정하십시오.
- 지불 상태(납부 기한/연체)는 중요합니다. 연체 지불에 즉시 플래그를 지정하십시오.
- 에이커당 비용 분석은 소유 토지와 임차 토지의 경제성을 비교하는 데 도움이 됩니다.
- 임대인 연락처 정보는 비공개입니다. admin/manager 채널 밖에서는 절대 공유하지 마십시오.
- "현금 요구 사항" 또는 "우리가 얼마를 빚고 있나요"와 같은 질문을 받으면 항상
/api/integration/payments/all을 날짜 필터링과 함께 사용하여 완전한 그림을 얻으십시오. - 재무 계획 질문의 경우
/api/integration/payments/all과/api/integration/finance/costs를 결합하여 전체 보기를 얻으십시오. - 쓰기 작업: 지불 납부 표시 또는 임대 갱신에는 항상 인증된 엔드포인트를 사용하십시오. 대량 작업을 수행할 때는 먼저 미리보기를 하십시오.
- 대량 지불 표시: 사용자가 "모든 3월 지불을 납부됨으로 표시"라고 말하면 개별 호출 대신 대량 날짜 기반 엔드포인트를 사용하십시오.