UPDATE
This commit is contained in:
@@ -0,0 +1,409 @@
|
||||
# گزارش ممیزی ضعفهای حلنشده پروژه
|
||||
|
||||
این سند فقط روی **مشکلات حلنشده و باقیمانده** تمرکز دارد و مواردی را که در 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ها بهصورت یکنواخت حاصل نشده است.**
|
||||
Reference in New Issue
Block a user