70 lines
5.4 KiB
Markdown
70 lines
5.4 KiB
Markdown
# ممیزی وضعیت واقعی 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` | route واقعی AI |
|
|
| `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` | route واقعی AI |
|
|
| `GET|PUT|PATCH|DELETE /api/plants/{pk}/` | `implemented` | `canonical AI plant service` | route واقعی AI |
|
|
| `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` | route واقعی AI |
|
|
| `GET|PUT|PATCH|DELETE /api/irrigation/{pk}/` | `implemented` | `AI-owned config` | route واقعی AI |
|
|
| `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 بودن را جداگانه مستند کنید.
|