Logic/Modules/Ai/API_RELIABILITY_AUDIT_FA.md

ممیزی وضعیت واقعی APIها

این سند فقط درباره reliability نیست؛ به‌عنوان یک مرجع فشرده برای وضعیت واقعی routeها و semantics فعلی هم استفاده می‌شود.

قانون runtime در برابر seed

• seed/fixture/bootstrap data مجاز است و باید برای bootstrap، dev و test باقی بماند.
• mock/sample/demo data نباید در runtime application code به عنوان fallback موفق استفاده شود.
• اگر داده واقعی موجود نیست، پاسخ باید empty state یا failure contract صریح باشد.

جدول مرجع وضعیت

Endpoint	وضعیت	semantics	توضیح کوتاه
POST /api/rag/chat/	implemented	live AI	route واقعی AI
POST /api/farm-alerts/tracker/	implemented	live AI	route واقعی AI؛ معادل backend آن cached است
`GET	POST /api/soil-data/`	implemented	provider-backed / task-backed
GET /api/soil-data/tasks/{task_id}/status/	implemented	async status	route واقعی AI
POST /api/soil-data/ndvi-health/	implemented	provider-backed	route واقعی AI
POST /api/soile/*	implemented	AI-owned derived output	routeهای واقعی AI
POST /api/farm-data/	implemented	AI-owned derived write-model	route واقعی AI
GET /api/farm-data/{farm_uuid}/detail/	implemented	AI-owned derived read-model	route واقعی AI
POST /api/farm-data/parameters/	implemented	AI-owned config	route واقعی AI
POST /api/weather/farm-card/	implemented	provider-backed	route واقعی AI
POST /api/weather/water-need-prediction/	implemented	derived output	route واقعی AI
POST /api/economy/overview/	implemented	provider-backed / persisted	route واقعی AI
`GET	POST /api/plants/`	implemented	canonical AI plant service
`GET	PUT	PATCH	DELETE /api/plants/{pk}/`
POST /api/plants/fetch-info/	implemented	provider-backed enrichment	route واقعی AI
POST /api/pest-disease/detect/	implemented	live AI	route واقعی AI
POST /api/pest-disease/risk/	implemented	derived output	route واقعی AI
`GET	POST /api/irrigation/`	implemented	AI-owned config + live recommendation support
`GET	PUT	PATCH	DELETE /api/irrigation/{pk}/`
POST /api/irrigation/recommend/	implemented	live AI + deterministic context	route واقعی AI
POST /api/irrigation/plan-from-text/	implemented	live AI parsing	route واقعی AI
POST /api/irrigation/water-stress/	implemented	AI-owned derived output	route واقعی AI
POST /api/fertilization/recommend/	implemented	live AI + optimizer context	route واقعی AI
POST /api/fertilization/plan-from-text/	implemented	live AI parsing	route واقعی AI
POST /api/crop-simulation/current-farm-chart/	implemented	live AI inference	route واقعی AI
POST /api/crop-simulation/harvest-prediction/	implemented	live AI inference	route واقعی AI
GET /api/crop-simulation/yield-harvest-summary/	implemented	AI-owned derived output	route واقعی AI
POST /api/crop-simulation/yield-prediction/	implemented	live AI inference	route واقعی AI
POST /api/crop-simulation/growth/	implemented	async live AI inference	route واقعی AI
GET /api/crop-simulation/growth/{task_id}/status/	implemented	async status	route واقعی AI

مواردی که نباید به‌عنوان route واقعی AI معرفی شوند

Endpoint	تصمیم
POST /api/farm-alerts/timeline/	missing
GET /api/fertilization/recommend/{task_id}/status/	stub/contract-only
GET /api/irrigation/recommend/{task_id}/status/	stub/contract-only
هر route موجود فقط در Backend/external_api_adapter/json/ai/index.json و بدون registration واقعی	stub/contract-only

توضیح مهم درباره mock/spec

فایل Backend/external_api_adapter/json/ai/index.json باید به‌عنوان contract/mock catalog دیده شود، نه لیست endpointهای تضمین‌شده‌ی production.
اگر endpoint فقط در آن فایل وجود دارد ولی در Ai/config/urls.py و routeهای اپ‌ها ثبت نشده، وضعیت آن stub/contract-only است.

Ownership مهم

• plant catalog canonical در Backend شروع می‌شود و AI snapshot/read-model آن را ingest می‌کند.
• farm_data در AI facade canonical برای مصرف AI روی farm/sensor/plant assignment است.
• relation قدیمی SensorData.plants transitional است و نباید به‌عنوان source-of-truth جدید مستند شود.

Known Gaps / Follow-up

• schema UI غیرفعال است؛ audit docs منبع فعلی truth هستند.
• بعضی endpointها در backend و AI هر دو وجود دارند اما semantics آن‌ها متفاوت است؛ همیشه live/cached/proxy بودن را جداگانه مستند کنید.