Logic/PROJECT_WEAKNESSES_AUDIT_FA.md

# گزارش ممیزی ضعف‌های حل‌نشده پروژه

این سند فقط روی **مشکلات حل‌نشده و باقی‌مانده** تمرکز دارد و مواردی را که در auditهای قبلی رفع شده‌اند، از فهرست ضعف‌های فعال خارج می‌کند.

مبنای این گزارش:

- کد فعلی پروژه
- سند `Ai/API_RELIABILITY_AUDIT_FA.md`
- سند `Backend/AI_ROUTE_CONNECTION_AUDIT.md`
- سند قبلی `PROJECT_WEAKNESSES_AUDIT_FA.md`

---

## خلاصه مدیریتی

مهم‌ترین ضعف‌های حل‌نشده فعلی:

1. هنوز بین `docs`، `spec`، routeهای واقعی و ownership سرویس‌ها چند ناهماهنگی مهم وجود دارد.
2. بخشی از flowها هنوز `contract-only`، `partially_implemented` یا `transitional` هستند.
3. در چند سرویس مهم هنوز الگوی `silent fallback` و بازگشت `{}` یا `[]` دیده می‌شود.
4. بعضی adapterهای mock هنوز در runtime code حضور دارند و می‌توانند باعث false confidence شوند.
5. چند فایل کلیدی backend و AI هنوز بیش از حد بزرگ و چندمسئولیتی هستند.
6. migration معماری `farm_data` هنوز کامل نشده و بعضی relationهای transitional باقی مانده‌اند.
7. بخشی از تست‌ها هنوز بیشتر contract/proxy-oriented هستند تا behavior واقعی production.

---

## مواردی که دیگر ضعف فعال محسوب نمی‌شوند

این موارد در گزارش حاضر **حل‌شده** در نظر گرفته می‌شوند و جزو مشکلات باز نیستند:

- provider پیش‌فرض AI در `Ai/config/settings.py` دیگر روی `mock` نیست.
- استفاده از `mock` در محیط‌های non-dev/non-test در `Ai/config/settings.py` با startup check محدود شده است.
- وابستگی مستقیم `Backend/irrigation/services.py` به `mock_data` حذف شده است.
- naming قبلی مبتنی بر `mock_data` در بعضی سرویس‌ها مانند dashboard و irrigation تا حدی تمیز شده است.

---

## 1) ناهماهنگی بین route واقعی، docs و contract

این هنوز یکی از اصلی‌ترین ضعف‌های پروژه است.

### نشانه‌ها

- `POST /api/farm-alerts/timeline/` هنوز `missing` است و route واقعی ندارد.
- endpointهای status برای پیشنهاد آبیاری و کوددهی هنوز `contract_only` هستند:
  - `GET /api/irrigation/recommend/{task_id}/status/`
  - `GET /api/fertilization/recommend/{task_id}/status/`
- بخشی از routeهای irrigation در backend هنوز با routeهای واقعی AI کاملاً reconcile نشده‌اند.
- بعضی مسیرهای crop simulation روی AI واقعی هستند ولی canonical backend هنوز زیر `yield-harvest/*` تعریف می‌شود.

### ریسک

- فرانت یا تیم‌های دیگر ممکن است روی endpointهایی حساب کنند که public-ready نیستند.
- onboarding توسعه‌دهنده جدید سخت می‌شود.
- اختلاف بین semantics واقعی و docs باعث خطای integration می‌شود.

### شواهد

- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:40`
- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:41`
- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:66`
- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:68`
- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:72`
- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:74`
- `Ai/API_RELIABILITY_AUDIT_FA.md:50`

### اقدام پیشنهادی

- برای هر endpoint فقط یکی از این وضعیت‌ها نهایی شود:
  - `implemented`
  - `deprecated`
  - `contract-only`
  - `missing`
- docs داخلی و frontend-facing از هم تفکیک شوند.
- مسیرهای AI internal و backend public با برچسب ownership مشخص شوند.

---

## 2) باقی‌ماندن `silent fallback` و empty-shape handling

با اینکه بخشی از error handling بهتر شده، این ضعف هنوز حل نشده است.

### نقاط مهم

- در `Backend/irrigation/services.py` هنوز helperهایی وجود دارند که در حالت invalid/empty با `{}` یا `[]` برمی‌گردند.
- در برخی سرویس‌های backend و AI هنوز failure به‌صورت شفاف surface نمی‌شود.
- این الگو مخصوصاً برای debugging و observability مشکل‌ساز است.

### شواهد

- `Backend/irrigation/services.py:126`
- `Backend/irrigation/services.py:138`
- `Backend/irrigation/services.py:150`
- `Backend/irrigation/services.py:173`
- `Backend/irrigation/services.py:189`
- `Backend/irrigation/services.py:208`
- `Backend/yield_harvest/views.py:137`
- `Ai/rag/embedding.py:34`

### ریسک

- سیستم ظاهراً پاسخ موفق می‌دهد ولی داده ناقص یا تحریف‌شده است.
- root cause واقعی پشت empty response پنهان می‌شود.
- قرارداد خروجی API برای empty-state و error-state یکدست نیست.

### اقدام پیشنهادی

- empty-state مجاز فقط برای caseهای مستند و قابل‌تشخیص باشد.
- برای fallbackها `warning`, `reason`, `source`, `status` یا failure contract صریح برگردد.
- broad exception handling محدود و log-aware شود.

---

## 3) حضور mock adapterها در runtime code

گرچه provider پیش‌فرض دیگر mock نیست، اما حضور mock در runtime code هنوز یک ضعف معماری است.

### نقاط مهم

- `Ai/location_data/soil_adapters.py` هنوز `MockSoilDataAdapter` دارد.
- `Ai/weather/adapters.py` هنوز `MockWeatherAdapter` دارد.
- هر دو adapter رفتار synthetic و حتی delay مصنوعی دارند.

### شواهد

- `Ai/location_data/soil_adapters.py:102`
- `Ai/location_data/soil_adapters.py:107`
- `Ai/weather/adapters.py:76`
- `Ai/weather/adapters.py:77`
- `Ai/weather/adapters.py:275`

### ریسک

- realistic mock می‌تواند با داده واقعی اشتباه گرفته شود.
- اگر تنظیمات محیط اشتباه شود، نتیجه تست‌مانند به‌جای رفتار production دیده می‌شود.
- اعتماد کاذب در validation دستی ایجاد می‌کند.

### اقدام پیشنهادی

- mock adapterها فقط در `dev/test` load شوند.
- همه responseهای mock برچسب اجباری `source=mock` و `is_synthetic=true` داشته باشند.
- delay مصنوعی از runtime عادی حذف و فقط در test fixture نگه داشته شود.

---

## 4) debt معماری در `Backend/device_hub/services.py`

این فایل هنوز یکی از سنگین‌ترین نقاط technical debt است.

### مسئله

فایل همزمان چند مسئولیت را انجام می‌دهد:

- ingestion
- farm-data forwarding
- chart building
- anomaly payload shaping
- history formatting

همچنین هنوز fallbackهای empty و الگوهای نرمِ failure در آن دیده می‌شود.

### شواهد

- `Backend/device_hub/services.py:13`
- `Backend/device_hub/services.py:20`
- `Backend/device_hub/services.py:64`
- `Backend/device_hub/services.py:152`
- `Backend/device_hub/services.py:181`
- `Backend/device_hub/services.py:636`
- `Backend/device_hub/services.py:685`
- `Backend/device_hub/services.py:725`

### ریسک

- تغییرات کوچک، regressionهای پیش‌بینی‌نشده ایجاد می‌کند.
- تست‌پذیری و نگهداری فایل پایین است.
- ownership دقیق data flow سخت فهمیده می‌شود.

### اقدام پیشنهادی

- split به ماژول‌های جدا برای ingestion، forwarding، analytics و formatters
- حذف mock-oriented chart shaping از مسیر runtime
- تعریف service boundary روشن برای sensor processing

---

## 5) debt معماری در `Backend/farm_alerts/services.py` و semantics مبهم tracker

### مسئله

- `farm-alerts/tracker` در backend فعلاً snapshot/cached semantics دارد، نه live AI request-time.
- فایل service همزمان context build، persistence، snapshot update و notification save را انجام می‌دهد.

### شواهد

- `Backend/farm_alerts/views.py:57`
- `Backend/farm_alerts/services.py:13`
- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:40`

### ریسک

- مصرف‌کننده API ممکن است این endpoint را live AI تصور کند.
- مرز بین cache، snapshot و inference شفاف نیست.
- نگهداری و تغییر behavior آینده پرریسک می‌شود.

### اقدام پیشنهادی

- semantics endpoint در docs و response metadata صریح شود.
- service به ماژول‌های کوچک‌تر مثل `tracker_context`, `tracker_sync`, `snapshots`, `notifications` شکسته شود.

---

## 6) ضعف‌های باقی‌مانده در access control

### مسئله

- `Backend/access_control/services.py` هنوز بزرگ و چندمنظوره است.
- بخشی از exceptionها swallowed می‌شوند.
- parsing داده درخواست در همان لایه authorization پیچیده شده است.
- اگر dependencyهایی مثل OPA ناپایدار باشند، degradation policy هنوز کاملاً شفاف نیست.

### شواهد

- `Backend/access_control/services.py:321`
- `Backend/access_control/services.py:332`
- `Backend/access_control/services.py:343`

### ریسک

- رفتار authorization در failure modeها غیرقابل پیش‌بینی می‌شود.
- fail-open / fail-closed policy ممکن است ناهمگون شود.

### اقدام پیشنهادی

- policy هر endpoint برای fail-open یا fail-closed مستند و enforce شود.
- cache exceptionها با logging و classification مناسب مدیریت شوند.
- request parsing از authorization logic جدا شود.

---

## 7) ضعف‌های باقی‌مانده در `Backend/plants`

این بخش نسبت به قبل بهتر شده، اما هنوز canonical backend CRUD کاملاً نهایی نیست.

### مسئله

- backend plant catalog هنوز از نظر تمام operationهای canonical کاملاً تثبیت نشده است.
- بخشی از تفاوت AI route و backend public route هنوز باقی است.
- مسیر incremental sync/change-feed یا webhook/task-based sync هنوز به‌صورت روشن نهایی نشده است.

### شواهد

- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:58`
- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:59`
- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:60`
- `Backend/plants/services.py:94`

### ریسک

- source-of-truth بین catalog backend و مصرف AI ممکن است drift کند.
- عملیات مدیریتی catalog به‌صورت کامل و یکنواخت قابل اتکا نیست.

### اقدام پیشنهادی

- CRUD canonical backend کامل و صریح شود.
- مکانیزم sync از backend به AI از push ساده به مدل change-feed یا task-based نزدیک شود.

---

## 8) باقی‌ماندن contract/mock catalog در `Backend/external_api_adapter/json/ai/index.json`

### مسئله

این فایل هنوز شامل endpointهایی است که route واقعی production نیستند یا فقط `contract-only` هستند.

### شواهد

- `Backend/external_api_adapter/json/ai/index.json`
- `Backend/AI_ROUTE_CONNECTION_AUDIT.md:94`
- `Ai/API_RELIABILITY_AUDIT_FA.md:57`

### ریسک

- این فایل ممکن است به‌اشتباه به‌عنوان source-of-truth production خوانده شود.
- mock/spec با implementation واقعی قاطی می‌شود.

### اقدام پیشنهادی

- endpointهای mock/spec از routeهای واقعی جدا برچسب‌گذاری شوند.
- این فایل صریحاً به‌عنوان `contract/mock catalog` حفظ شود، نه production route registry.

---

## 9) migration ناتمام در `Ai/farm_data`

### مسئله

معماری جدید `farm_data` جهت درستی دارد، اما migration آن کامل نشده است.

### نقاط باقی‌مانده

- relation قدیمی `SensorData.plants` هنوز transitional است.
- همه consumerها هنوز کامل migrate نشده‌اند.
- strategy نهایی برای sync conflict و reconciliation کامل نشده است.

### شواهد

- `Ai/API_RELIABILITY_AUDIT_FA.md:64`
- `Ai/farm_data/models.py:111`

### ریسک

- دو source-of-truth موقت هم‌زمان فعال می‌مانند.
- ناسازگاری assignment گیاه، sensor و farm ممکن است رخ دهد.

### اقدام پیشنهادی

- relation قدیمی بعد از migration کامل consumerها حذف شود.
- backfill و reconciliation task رسمی تعریف شود.
- source-of-truth نهایی در docs و schemaها تثبیت شود.

---

## 10) ضعف reliability در `Ai/rag/embedding.py`

### مسئله

- مدیریت خطای provider call هنوز حداقلی است.
- retry/backoff/circuit-breaker مشخص ندارد.

### شواهد

- `Ai/rag/embedding.py:10`
- `Ai/rag/embedding.py:34`

### ریسک

- failureهای موقت provider می‌توانند تجربه ناپایدار ایجاد کنند.
- خطاها خوب classify نمی‌شوند.

### اقدام پیشنهادی

- retry محدود با backoff
- تفکیک خطاهای موقت و دائمی
- failure contract شفاف برای dependency بیرونی

---

## 11) تست‌ها هنوز در چند بخش بیشتر proxy/contract محور هستند

### مسئله

بخشی از تست‌ها route proxy شدن به AI یا mock call شدن dependency را چک می‌کنند، نه لزوماً behavior واقعی production و edge-caseهای داده.

### نشانه‌ها

- در `Backend/yield_harvest/tests.py` تمرکز زیادی روی proxy contract دیده می‌شود.
- در چند بخش integration واقعی کمتر از contract mocking پوشش داده شده است.

### ریسک

- drift بین قرارداد تست‌شده و رفتار واقعی runtime کشف نمی‌شود.
- regressionهای مربوط به payload semantics، empty-state و partial failure دیر دیده می‌شوند.

### اقدام پیشنهادی

- تست‌های behavior-oriented برای failure contract، empty-state و payload validation اضافه شود.
- برای flowهای critical، integration test سبک و کنترل‌شده بیشتر شود.

---

## اولویت‌بندی اصلاح

### P0

- reconcile کامل route/doc/spec
- حذف یا شفاف‌سازی `contract-only` endpointها
- حذف `silent fallback`های باقی‌مانده در flowهای حساس

### P1

- split فایل‌های چندمسئولیتی مانند `device_hub/services.py` و `farm_alerts/services.py`
- محدودکردن runtime mock adapterها به dev/test
- تثبیت ownership و migration در `farm_data`

### P2

- بهبود reliability برای embedding/provider callها
- تقویت تست‌های behavior-oriented
- پاکسازی بیشتر docs قدیمی و واژه‌های مبهم مثل live/proxy/cached

---

## جمع‌بندی نهایی

پروژه نسبت به auditهای قبلی **در حذف بخشی از وابستگی‌های مستقیم به mock و بهبود provider defaults پیشرفت داشته است**، اما هنوز این ضعف‌های حل‌نشده باقی مانده‌اند:

- ناهماهنگی contract و route واقعی
- endpointهای `missing` یا `contract-only`
- fallbackهای silent
- حضور mock adapter در runtime code
- technical debt در چند service بزرگ
- migration ناتمام در `farm_data`
- ضعف در behavior-driven validation

بنابراین وضعیت فعلی پروژه را می‌توان این‌طور جمع‌بندی کرد:

**پایه معماری نسبت به قبل بهتر شده، اما هنوز production-readiness کامل در همه flowها به‌صورت یکنواخت حاصل نشده است.**