# گزارش ممیزی ضعف‌های حل‌نشده پروژه این سند فقط روی **مشکلات حل‌نشده و باقی‌مانده** تمرکز دارد و مواردی را که در 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ها به‌صورت یکنواخت حاصل نشده است.**