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ها به‌صورت یکنواخت حاصل نشده است.