mirror of
https://github.com/deepseek-ai/DeepSeek-Coder-V2.git
synced 2026-11-05 00:57:27 +00:00
[GH-ISSUE #102] OceanAtlas MIL-OS #85
Labels
No labels
pull-request
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
deepseek-ai/DeepSeek-Coder-V2#85
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @hanymahdy2 on GitHub (May 2, 2026).
Original GitHub issue: https://github.com/deepseek-ai/DeepSeek-Coder-V2/issues/102
🌊 OceanAtlas MIL-OS — Master Engineering Prompt
Maritime Intelligence & Logistics Operating System
Unified Production-Grade Technical Specification — v1.0
تعليمات الدور:
أنت تعمل بصفة كبير مهندسي Full-Stack ومحلل استخباراتي بحري أول (Principal Full-Stack Engineer & Senior Maritime Intelligence Analyst).
مهمتك هي تصميم وبناء وتوثيق منصة استخباراتية بحرية شاملة باسم داخلي: OceanAtlas.
المنصة هي نظام تشغيل لوجستي وأمني بحري مُتكامل يعمل في الوقت الفعلي (Real-Time) ويخدم كلاً من المحللين الاستراتيجيين، المورّدين البحريين، مشغّلي السفن، والجهات التجارية والرقابية.
─── SECTION 0: المتطلبات العامة للتنفيذ ───
0.1 مبادئ الكود الأساسية
المنطق: هذه المبادئ تُحكم كل سطر كود يُكتب في المشروع، وتضمن استدامته وقابليته للتوسع والصيانة.
PRINCIPLES:
0.2 المتطلبات الإلزامية لكل Endpoint
المنطق: كل نقطة API في المنصة يجب أن تحمل هذه الخصائص لضمان الاتساق والأمان والتوثيق.
API CONTRACT (per endpoint):
✅ Documented via OpenAPI 3.0 / Swagger UI
✅ Input Validation (Pydantic / Zod schemas)
✅ Rate Limiting (prevent API abuse)
✅ Authentication via JWT Bearer Token
✅ Versioning: /api/v1/...
✅ Structured JSON Response: { success, data, meta, error }
✅ Request/Response Logging (no PII in logs)
─── SECTION 1: المكدس التقني الكامل (Technology Stack) ───
المنطق: تحديد المكدس التقني مسبقاً يضمن تجانس القرارات المعمارية عبر كل طبقات النظام، ويمنع التعارض بين الأدوات.
1.1 Frontend Layer
Framework : Next.js 14+ (App Router) — يُتيح Server Components + Streaming لتحديثات الخريطة اللحظية
UI Library : React 18 مع Suspense Boundaries لعزل مناطق التحديث اللحظي
Styling : Tailwind CSS v3 — "Control Room" dark aesthetic مع CSS Variables للـ theming
Maps : Mapbox GL JS v3 — خرائط بحرية عالية الأداء مع Maritime Custom Layers
State Mgmt : Zustand — إدارة حالة خفيفة لـ vessel tracking state و session data
Data Fetching : React Query (TanStack) — Caching + Real-time invalidation لبيانات AIS
Real-Time : WebSocket (Socket.IO client) — تحديثات مباشرة لمواقع السفن
Charting : Recharts — رسوم بيانية للـ Risk Score و behavioral analytics
Forms : React Hook Form + Zod — validation client-side مُتزامن مع server schema
i18n : next-i18next — دعم كامل للعربية (RTL) والإنجليزية مع dynamic switching
PDF Export : React-PDF (@react-pdf/renderer) — توليد تقارير PDF مُنسّقة احترافياً
1.2 Backend Layer
Runtime : Python 3.11+ (FastAPI) — الخيار الأمثل لمعالجة البيانات الثقيلة وAI logic
Web Framework : FastAPI — أداء عالٍ، Async I/O، Pydantic validation مدمج، Swagger تلقائي
Task Queue : Celery + Redis — جدولة مهام الـ scraping والـ enrichment بشكل غير متزامن
Caching : Redis — تخزين مؤقت لبيانات AIS المتكررة ولنتائج OFAC Screening
WebSocket : FastAPI WebSocket endpoints — بث تحديثات السفن للـ frontend
Scraping : Playwright (Python) — أتمتة المتصفح للبوابات المُقيّدة (Equasis, OFAC)
Proxy Mgmt : Rotating residential proxies — للتحايل على حدود الـ rate limiting في المصادر الخارجية
Auth : JWT + OAuth2 via python-jose — مع refresh token rotation
Secrets : HashiCorp Vault أو AWS Secrets Manager — إدارة آمنة لبيانات الاعتماد
Serverless : AWS Lambda (Python runtime) — لتنفيذ "Live Scrape-and-Merge" عند الطلب
1.3 Database Layer
Primary DB : PostgreSQL 15+ مع PostGIS extension — لتخزين البيانات الجيومكانية وتنفيذ Spatial Queries
Search Engine : Elasticsearch — للبحث النصي في سجلات الملكية والحوادث التاريخية
Cache Store : Redis 7+ — Pub/Sub للـ real-time events + Session Store + Rate Limiting counters
Time-Series : TimescaleDB (PostgreSQL extension) — لتخزين مسارات AIS التاريخية بكفاءة عالية
Object Storage: AWS S3 / MinIO — لحفظ ملفات PDF المُوّلدة وصور السفن
Migrations : Alembic (Python) — إدارة تغييرات Schema بشكل منضبط وقابل للتراجع
1.4 Infrastructure & DevOps
Containerization : Docker + Docker Compose (dev) / Kubernetes (prod)
CI/CD : GitHub Actions — automated testing, linting, deployment
Monitoring : Prometheus + Grafana — مراقبة أداء APIs وقواعد البيانات
Logging : ELK Stack (Elasticsearch, Logstash, Kibana) — logging مركزي مُهيكل
API Gateway : Kong أو AWS API Gateway — Rate limiting, Auth, Load balancing
Environment : .env.local (dev) / AWS Parameter Store (prod)
─── SECTION 2: بنية قاعدة البيانات (Database Schema) ───
المنطق: IMO Number هو المفتاح الأساسي الثابت الذي يربط كل الجداول. لا تُعرض أي بيانات إذا كان هناك تعارض بين هوية AIS وهوية السجل الرسمي للسفينة.
2.1 Core Vessel Identity Tables
sql-- ═══════════════════════════════════════════════════════════════
-- الجدول الأساسي: هوية السفينة الموحّدة
-- المنطق: يمثّل السجل الكنسي (canonical record) للسفينة.
-- كل جدول آخر يرتبط به عبر imo_number كـ Foreign Key.
-- ═══════════════════════════════════════════════════════════════
CREATE TABLE vessels (
imo_number VARCHAR(7) PRIMARY KEY CHECK (imo_number ~ '^\d{7}$'),
mmsi VARCHAR(9) UNIQUE,
vessel_name VARCHAR(255) NOT NULL,
vessel_name_history JSONB DEFAULT '[]', -- مصفوفة بتواريخ تغيير الاسم
vessel_type VARCHAR(100), -- Tanker, Bulker, Reefer, etc.
flag_current VARCHAR(3), -- ISO 3166-1 alpha-3
flag_history JSONB DEFAULT '[]', -- تاريخ تغييرات العلم
gross_tonnage NUMERIC(10,2),
deadweight_tonnage NUMERIC(10,2), -- DWT: لمقارنة الحمولة بالغاطس الفعلي
length_overall NUMERIC(7,2),
year_built SMALLINT,
shipyard VARCHAR(255),
ship_status VARCHAR(50) DEFAULT 'active', -- active, scrapped, unknown
data_source VARCHAR(50) DEFAULT 'equasis', -- مصدر السجل الرسمي
last_verified_at TIMESTAMPTZ, -- آخر مرة جرى فيها التحقق من البيانات
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
-- ═══════════════════════════════════════════════════════════════
-- شبكة الملكية: الخوارزمية العودية لتتبع "Corporate Web"
-- المنطق: كل سفينة قد تمر بسلسلة من أصحاب الملكية والمشغّلين.
-- النوع (type) يُميّز بين المالك القانوني والمدير التقني والمشغّل التجاري.
-- ═══════════════════════════════════════════════════════════════
CREATE TABLE vessel_ownership (
id BIGSERIAL PRIMARY KEY,
imo_number VARCHAR(7) REFERENCES vessels(imo_number) ON DELETE CASCADE,
entity_name VARCHAR(255) NOT NULL,
entity_type VARCHAR(50) NOT NULL CHECK (entity_type IN (
'registered_owner', 'technical_manager',
'commercial_operator', 'ism_manager', 'beneficial_owner'
)),
country VARCHAR(3),
valid_from DATE NOT NULL,
valid_to DATE, -- NULL = سجل ساري حالياً
is_current BOOLEAN DEFAULT TRUE,
source_verified BOOLEAN DEFAULT FALSE,
created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_ownership_imo ON vessel_ownership(imo_number);
CREATE INDEX idx_ownership_entity ON vessel_ownership(entity_name);
-- ═══════════════════════════════════════════════════════════════
-- الموقع الآني والتاريخ الكينماتيكي (AIS Kinematics)
-- المنطق: استخدام TimescaleDB يجعل الاستعلام عن نطاق زمني أو
-- اكتشاف "Dark Activity" في ثوانٍ بدلاً من دقائق.
-- PostGIS (GEOGRAPHY) يُتيح حساب المسافات والتقاطع مع مناطق محظورة.
-- ═══════════════════════════════════════════════════════════════
CREATE TABLE ais_positions (
id BIGSERIAL,
imo_number VARCHAR(7) REFERENCES vessels(imo_number) ON DELETE CASCADE,
mmsi VARCHAR(9),
recorded_at TIMESTAMPTZ NOT NULL,
position GEOGRAPHY(Point, 4326) NOT NULL, -- WGS84 Lat/Lng
speed_over_ground NUMERIC(5,2), -- SOG بالعقد (Knots)
course_over_ground NUMERIC(5,2), -- COG بالدرجات (0–360)
true_heading SMALLINT,
navigation_status VARCHAR(50), -- "Moored", "At anchor", "Waiting for orders", etc.
static_draught NUMERIC(4,1), -- الغاطس الفعلي لمقارنته بـ DWT
destination VARCHAR(100),
eta TIMESTAMPTZ,
source VARCHAR(20) DEFAULT 'ais_live',
PRIMARY KEY (id, recorded_at) -- مطلوب لـ TimescaleDB hypertable
);
SELECT create_hypertable('ais_positions', 'recorded_at'); -- TimescaleDB partitioning
CREATE INDEX idx_ais_imo_time ON ais_positions(imo_number, recorded_at DESC);
CREATE INDEX idx_ais_geo ON ais_positions USING GIST(position); -- Spatial Index
-- ═══════════════════════════════════════════════════════════════
-- نتائج الفحص الأمني (Sanctions & Compliance)
-- المنطق: لا تُخزَّن نتائج OFAC بشكل نهائي — يُعاد تشغيل الفحص
-- دورياً لأن قوائم العقوبات تتغير. الحقل screening_result
-- هو JSONB لاستيعاب تفاصيل متعددة الصيغ من مصادر مختلفة.
-- ═══════════════════════════════════════════════════════════════
CREATE TABLE compliance_screenings (
id BIGSERIAL PRIMARY KEY,
imo_number VARCHAR(7) REFERENCES vessels(imo_number),
screened_entity VARCHAR(255) NOT NULL, -- اسم الكيان المفحوص
entity_role VARCHAR(50), -- owner, manager, operator
source VARCHAR(50) DEFAULT 'ofac',
screening_result JSONB, -- { matched: bool, list_type: "SDN", score: 0.98 }
risk_flag BOOLEAN DEFAULT FALSE,
screened_at TIMESTAMPTZ DEFAULT NOW(),
valid_until TIMESTAMPTZ GENERATED ALWAYS AS (screened_at + INTERVAL '24 hours') STORED
);
-- ═══════════════════════════════════════════════════════════════
-- السجل الجنائي للسفينة (Behavioral & Incident History)
-- المنطق: يُغذّى من محركات تجميع الأخبار ومن سجلات PSC detentions.
-- يُستخدم لاحتساب Risk Score المركّب للسفينة.
-- ═══════════════════════════════════════════════════════════════
CREATE TABLE vessel_incidents (
id BIGSERIAL PRIMARY KEY,
imo_number VARCHAR(7) REFERENCES vessels(imo_number),
incident_type VARCHAR(100) NOT NULL, -- "PSC Detention", "Dark Activity", "STS Transfer", etc.
incident_date DATE,
location GEOGRAPHY(Point, 4326),
port_name VARCHAR(100),
severity SMALLINT CHECK (severity BETWEEN 1 AND 5),
description TEXT,
source_url TEXT,
verified BOOLEAN DEFAULT FALSE,
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- ═══════════════════════════════════════════════════════════════
-- نقاط Risk Score المحتسَبة (Aggregated Risk Profile)
-- المنطق: يُحتسب Risk Score بشكل دوري (Celery task) ويُخزَّن هنا.
-- التفاصيل component_scores تُوضّح مساهمة كل عامل في النتيجة.
-- ═══════════════════════════════════════════════════════════════
CREATE TABLE vessel_risk_scores (
id BIGSERIAL PRIMARY KEY,
imo_number VARCHAR(7) REFERENCES vessels(imo_number),
total_score NUMERIC(5,2) NOT NULL, -- 0.0 → 100.0
risk_level VARCHAR(20) GENERATED ALWAYS AS (
CASE WHEN total_score >= 70 THEN 'CRITICAL'
WHEN total_score >= 40 THEN 'HIGH'
WHEN total_score >= 20 THEN 'MEDIUM'
ELSE 'LOW' END
) STORED,
component_scores JSONB NOT NULL, -- { sanctions: 30, dark_activity: 15, psc: 10, ... }
calculated_at TIMESTAMPTZ DEFAULT NOW()
);
-- ═══════════════════════════════════════════════════════════════
-- MODULE: Maritime Connector — جدول الموردين والمشترين
-- المنطق: يمتد Schema الأصلي دون تعديل جداول vessel_intelligence.
-- Zero-Conflict: الجدول الجديد يُكمّل النظام ولا يتعارض معه.
-- ═══════════════════════════════════════════════════════════════
CREATE TABLE maritime_suppliers (
id BIGSERIAL PRIMARY KEY,
company_name VARCHAR(255) NOT NULL,
service_type VARCHAR(100), -- "Spare Parts", "Bunker Fuel", "Manning", etc.
port_coverage JSONB DEFAULT '[]', -- مصفوفة من UN/LOCODE لموانئ التغطية
contact_email VARCHAR(255),
contact_phone VARCHAR(50),
whatsapp_number VARCHAR(50),
verified BOOLEAN DEFAULT FALSE,
geo_fence_zones JSONB DEFAULT '[]', -- مناطق Geo-Fence التي يُغطّيها المورّد
created_at TIMESTAMPTZ DEFAULT NOW()
);
-- ═══════════════════════════════════════════════════════════════
-- MODULE: Maritime Connector — جدول التواصل B2B
-- المنطق: يتتبع كل تفاعل بين المورّد والسفينة/الشركة.
-- يُحافظ على خصوصية البيانات: لا تُكتب بيانات الأشخاص
-- إلى الجداول الأساسية بل تُخزَّن هنا فقط للغرض التجاري.
-- ═══════════════════════════════════════════════════════════════
CREATE TABLE matchmaking_connections (
id BIGSERIAL PRIMARY KEY,
supplier_id BIGINT REFERENCES maritime_suppliers(id),
imo_number VARCHAR(7) REFERENCES vessels(imo_number),
target_entity VARCHAR(255), -- اسم شركة الشحن المستهدفة
contact_name VARCHAR(255), -- Fleet Manager / Technical Superintendent
contact_email VARCHAR(255),
contact_source VARCHAR(50), -- "linkedin", "apollo", "hunter"
connection_type VARCHAR(50), -- "outbound_contact", "sos_alert", "inbound_query"
status VARCHAR(30) DEFAULT 'pending', -- pending, sent, replied, closed
notes TEXT,
triggered_at TIMESTAMPTZ DEFAULT NOW(),
responded_at TIMESTAMPTZ
);
-- ═══════════════════════════════════════════════════════════════
-- MODULE: Human Capital Intelligence — صانعو القرار
-- المنطق: يُغذَّى بشكل برمجي عند تحديد الـ Technical/Commercial Manager
-- من Equasis. البيانات لأغراض تجارية فقط ولا تُدمج في vessel records.
-- ═══════════════════════════════════════════════════════════════
CREATE TABLE decision_makers (
id BIGSERIAL PRIMARY KEY,
entity_name VARCHAR(255) NOT NULL, -- اسم شركة الإدارة
full_name VARCHAR(255),
role_title VARCHAR(150), -- "Fleet Manager", "Technical Superintendent"
linkedin_url TEXT,
email_verified VARCHAR(255),
phone_verified VARCHAR(50),
email_source VARCHAR(50), -- "apollo", "hunter", "rocketreach"
confidence_score NUMERIC(3,2), -- 0.00 → 1.00 للتحقق من صحة البريد
fetched_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE (entity_name, full_name) -- تجنب التكرار
);
-- ═══════════════════════════════════════════════════════════════
-- Validation Alert Log
-- المنطق: عند اكتشاف تعارض بين AIS identity وRegistry identity
-- لنفس IMO Number، لا تُعرض بيانات متعارضة — بل يُسجَّل
-- تنبيه هنا ويُعلَم المستخدم بـ "Validation Alert".
-- ═══════════════════════════════════════════════════════════════
CREATE TABLE coherence_alerts (
id BIGSERIAL PRIMARY KEY,
imo_number VARCHAR(7) REFERENCES vessels(imo_number),
alert_type VARCHAR(100) NOT NULL, -- "NAME_MISMATCH", "FLAG_CONFLICT", "DRAUGHT_ANOMALY"
ais_value TEXT,
registry_value TEXT,
resolved BOOLEAN DEFAULT FALSE,
created_at TIMESTAMPTZ DEFAULT NOW()
);
─── SECTION 3: طبقة استيعاب البيانات (Data Ingestion Layer) ───
المنطق: كل مصدر بيانات يُعامَل ككيان مستقل له Service class خاصة به، لضمان قابلية الاستبدال والاختبار. IMO Number هو مفتاح الربط الثابت بين جميع المصادر.
3.1 مصادر البيانات وآليات الاستيعاب
┌──────────────────────────────────────────────────────────────────────┐
│ UNIFIED DATA SOURCE MATRIX │
│ (Single Source of Truth Architecture) │
├────────────────┬──────────────────┬──────────────────────────────────┤
│ المصدر │ آلية الاستيعاب │ البيانات المستخرجة │
├────────────────┼──────────────────┼──────────────────────────────────┤
│ AIS Global │ REST API │ SOG, COG, Position, Nav Status │
│ Endpoint │ WebSocket Stream │ Real-time lat/lng, Draught │
│ │ → كل 30 ثانية │ Destination, ETA │
├────────────────┼──────────────────┼──────────────────────────────────┤
│ Equasis.org │ Playwright │ IMO, Flag, Ownership chain, │
│ │ (Headless) │ PSC Detentions, ISM Manager │
│ │ + Session Auth │ Technical Specs, DWT │
├────────────────┼──────────────────┼──────────────────────────────────┤
│ OFAC Sanctions │ Playwright │ SDN List match, Non-SDN match, │
│ Search │ + REST fallback │ Match score, List type │
├────────────────┼──────────────────┼──────────────────────────────────┤
│ Kpler.com │ REST API │ Cargo grade, Quantity, Loading/ │
│ │ (Authenticated) │ Discharging port, Voyage history │
├────────────────┼──────────────────┼──────────────────────────────────┤
│ News Aggregator│ RSS + NLP │ Incidents: smuggling, detention, │
│ (Multi-source) │ (spaCy pipeline) │ environmental violations │
├────────────────┼──────────────────┼──────────────────────────────────┤
│ LinkedIn │ Sales Navigator │ Decision-maker role, Company │
│ Apollo.io │ REST API │ Verified B2B email, Mobile │
│ Hunter.io │ REST API │ Email pattern, Deliverability % │
│ RocketReach │ REST API │ Contact verification fallback │
└────────────────┴──────────────────┴──────────────────────────────────┘
3.2 بنية خدمات الاستيعاب (Service Architecture)
python# ══════════════════════════════════════════════════════════════
ملف: app/services/data_sources/ais_service.py
المنطق: مسؤول حصرياً عن استيعاب AIS. يُطبّق Coherence Check
فور استلام البيانات: يقارن اسم السفينة في AIS مع اسمها
في جدول vessels. إذا وُجد تعارض → يُنشئ coherence_alert
ولا يُحدِّث السجل الرئيسي حتى يُحسم التعارض.
══════════════════════════════════════════════════════════════
class AISIngestionService:
"""
Handles real-time AIS data ingestion and position storage.
══════════════════════════════════════════════════════════════
ملف: app/services/data_sources/equasis_service.py
المنطق: يستخدم Playwright بـ session persistence للتعامل مع
Equasis الذي يتطلب تسجيل دخول. يُشغَّل كـ Celery task
بدلاً من الطلب المتزامن لتجنب حظر الـ API.
بيانات الاعتماد تُجلب من Vault/Secrets Manager.
══════════════════════════════════════════════════════════════
class EquasisScrapingService:
"""
Retrieves verified vessel registry data from Equasis.
══════════════════════════════════════════════════════════════
ملف: app/services/data_sources/ofac_service.py
المنطق: يفحص كل كيان في سلسلة الملكية (مالك، مدير، مشغّل)
ضد قوائم SDN و Non-SDN. نتيجة الفحص تنتهي صلاحيتها
بعد 24 ساعة (valid_until) لإجبار إعادة الفحص الدوري.
══════════════════════════════════════════════════════════════
class OFACScreeningService:
"""
Real-time sanctions screening against OFAC SDN and Non-SDN lists.
─── SECTION 4: محرك التحليلات السلوكية والتنبؤية ───
المنطق: هذا المحرك يحوّل البيانات الخام (مواقع، تواريخ ملكية، حوادث) إلى استخبارات قابلة للتنفيذ. كل خوارزمية موثّقة بمنطقها الكامل.
4.1 كاشف النشاط المشبوه (Behavioral Anomaly Engine)
python# ملف: app/services/analytics/behavioral_engine.py
class BehavioralAnalyticsEngine:
"""
Detects anomalous vessel behavior using multi-factor heuristic analysis.
4.2 محرك احتساب Risk Score
RISK SCORE FORMULA (0–100 Scale):
score = (
sanctions_match_score × 0.35 + # وزن 35%: أعلى عامل خطر
dark_activity_score × 0.20 + # وزن 20%: نشاط مخفي
psc_detention_score × 0.15 + # وزن 15%: سجل احتجازات
incident_history_score × 0.15 + # وزن 15%: حوادث موثّقة
flag_risk_score × 0.10 + # وزن 10%: علم مخاطر عالية
ownership_opacity_score × 0.05 # وزن 5%: غموض هيكل الملكية
)
risk_level:
70–100 → CRITICAL (أحمر)
40–69 → HIGH (برتقالي)
20–39 → MEDIUM (أصفر)
0–19 → LOW (أخضر)
4.3 محرك التنبؤ (Predictive Port Call Engine)
pythonclass PredictiveIntelligenceEngine:
"""
Predicts future vessel movements and cargo matching opportunities.
─── SECTION 5: نقاط API (FastAPI Endpoints) ───
المنطق: كل Endpoint موثّق ومحدّد المسؤولية. بنية الاستجابة موحّدة لتسهيل استهلاك الـ Frontend والتكاملات الخارجية.
python# ═══════════════════════════════════════════════════════════════
ملف: app/api/v1/vessels.py
═══════════════════════════════════════════════════════════════
"""
Vessel Intelligence API — v1
Base URL: /api/v1/vessels
Auth: Bearer JWT (required on all endpoints)
Response envelope: { "success": bool, "data": any, "meta": {}, "error": str|null }
"""
GET /api/v1/vessels/{imo}/profile
المنطق: نقطة الدخول الرئيسية لملف السفينة.
تُجمّع البيانات من: vessels + vessel_ownership + vessel_risk_scores
+ آخر موقع AIS + آخر فحص OFAC.
إذا وُجدت coherence_alerts غير محسومة → تُرجع الاستجابة مع
validation_alerts: [...] ولا تُخفي البيانات المتعارضة بل تُوضّحها.
GET /api/v1/vessels/{imo}/live-sync
المنطق: يُشغّل AWS Lambda function تُنفّذ "Scrape-and-Merge" فوري:
1. Equasis live scrape → تحديث vessel_ownership
2. AIS live fetch → إضافة سجل ais_positions جديد
3. OFAC re-screen → تحديث compliance_screenings
يتجاوز الـ Cache تماماً للحصول على 100% دقة.
يبثّ النتيجة عبر WebSocket لتحديث Dashboard فورياً.
GET /api/v1/vessels/{imo}/ownership-tree
المنطق: يُعيد شجرة الملكية الكاملة بتنسيق مناسب لعرض D3.js/React Flow.
يُطبّق الخوارزمية العودية لتتبع Corporate Web بأكمله.
GET /api/v1/vessels/{imo}/behavioral-analysis
المنطق: يُشغّل BehavioralAnalyticsEngine ويُعيد:
- قائمة الأنشطة المشبوهة المكتشفة
- Risk Score المُحتسَب مع تفاصيل المكوّنات
- Timeline للحوادث التاريخية
GET /api/v1/vessels/{imo}/decision-makers
المنطق: عند تحديد Commercial/Technical Manager من Equasis،
يُشغّل Apollo/Hunter/RocketReach search تلقائياً.
يُعيد أفضل 3 جهات اتصال مع درجة الثقة لكل منها.
GET /api/v1/vessels/waiting-for-orders
المنطق: يُعيد قائمة السفن ذات nav_status "Waiting for Orders".
لكل سفينة: موقعها، نوعها، آخر شحنة، بيانات تواصل المشغّل.
هذه نقطة دخول وحدة "Cargo Matchmaker".
POST /api/v1/vessels/{imo}/validate-coherence
المنطق: يُحسم coherence_alert يدوياً بعد مراجعة بشرية.
يسجّل القرار مع timestamp ومعرّف المستخدم.
═══════════════════════════════════════════════════════════════
ملف: app/api/v1/connector.py (Maritime Connector Module)
═══════════════════════════════════════════════════════════════
POST /api/v1/connector/supplier-intelligence
المنطق: يُجري cross-reference بين الأسطول الحي للشركة المستهدفة
وGeofence المورّد. يُعيد "Vessels in Range" مع بيانات التواصل.
GET /api/v1/connector/suppliers
المنطق: يُعيد قائمة الموردين مُصنَّفة حسب الخدمة أو الميناء.
يُستخدم في "Procurement Efficiency Mode" لـ Ship Managers.
POST /api/v1/connector/sos-alert
المنطق: يُشغّل Webhook Broadcast لجميع الموردين المسجّلين
في الميناء القادم للسفينة عبر Twilio/WhatsApp Business API.
═══════════════════════════════════════════════════════════════
ملف: app/api/v1/reports.py
═══════════════════════════════════════════════════════════════
POST /api/v1/reports/vessel-passport/{imo}
المنطق: يُولّد PDF يجمع: الهوية الكاملة + سلسلة الملكية +
السجل الأمني + الملف السلوكي. يُخزَّن في S3 ويُعاد رابطه.
POST /api/v1/reports/risk-assessment/{imo}
المنطق: يُولّد PDF للتقرير القانوني/الأمني بصيغة احترافية.
POST /api/v1/reports/logistics-brief/{imo}
المنطق: يُولّد PDF يتضمن: المسار المتوقع + توافق الشحنة +
بيانات تواصل المشغّلين في الموانئ المتوقعة.
─── SECTION 6: المكوّنات الأمامية (Frontend Architecture) ───
المنطق: Next.js App Router يُتيح تقسيم التطبيق إلى Server Components (للبيانات الثقيلة) و Client Components (للتفاعلية). هذا يُحسّن الأداء ويُقلّل حجم JavaScript المُرسَل للمتصفح.
6.1 هيكل المجلدات
app/
├── (auth)/
│ └── login/page.tsx # صفحة تسجيل الدخول
├── (dashboard)/
│ ├── layout.tsx # Layout الرئيسي (Sidebar + Header)
│ ├── page.tsx # Dashboard الرئيسي: الخريطة + إحصائيات
│ ├── vessels/
│ │ ├── page.tsx # قائمة السفن مع فلتر
│ │ └── [imo]/
│ │ ├── page.tsx # ملف السفينة الكامل
│ │ ├── ownership/page.tsx # شجرة الملكية التفاعلية
│ │ ├── behavioral/page.tsx # التحليل السلوكي والـ Risk Score
│ │ └── contacts/page.tsx # Decision Makers وبيانات التواصل
│ ├── waiting-for-orders/page.tsx # Radar Module: السفن في انتظار الأوامر
│ ├── connector/
│ │ ├── supplier-mode/page.tsx # Supplier Intelligence Mode
│ │ ├── procurement/page.tsx # Procurement Efficiency Mode
│ │ └── sos/page.tsx # S.O.S Protocol
│ └── reports/page.tsx # مركز إنشاء التقارير
├── api/ # Next.js API Routes (proxy layer)
└── globals.css # CSS Variables: color tokens
components/
├── map/
│ ├── OceanAtlasMap.tsx # Mapbox GL: الخريطة الرئيسية
│ ├── VesselMarker.tsx # Marker مخصص لكل سفينة حسب نوعها
│ ├── MaritimeLayers.tsx # Layers: Sea lanes, ECA zones, Port zones
│ └── GeofenceOverlay.tsx # طبقة Geofencing للـ Connector Module
├── vessel/
│ ├── VesselProfileCard.tsx # بطاقة السفينة الرئيسية
│ ├── OwnershipTree.tsx # D3.js / React Flow لشجرة الملكية
│ ├── RiskScoreGauge.tsx # مقياس الـ Risk Score البصري
│ ├── BehavioralTimeline.tsx # Timeline الأنشطة المشبوهة
│ └── ValidationAlertBanner.tsx # تنبيه التعارض في البيانات
├── connector/
│ ├── SupplierCard.tsx # بطاقة المورّد مع زر WhatsApp
│ ├── DecisionMakerCard.tsx # بطاقة صانع القرار مع بيانات التواصل
│ └── VesselsInRangeWidget.tsx # إحصائية السفن داخل Geofence
├── reports/
│ ├── VesselPassportPDF.tsx # Template PDF: الجواز الكامل
│ ├── RiskAssessmentPDF.tsx # Template PDF: التقرير الأمني
│ └── LogisticsBriefPDF.tsx # Template PDF: الموجز اللوجستي
└── shared/
├── LanguageToggle.tsx # زر تبديل العربية/الإنجليزية (RTL/LTR)
├── CoherenceAlert.tsx # مكوّن تنبيه التعارض
└── LiveSyncButton.tsx # زر Live Sync مع حالة التحميل
6.2 تصميم واجهة المستخدم
DESIGN SYSTEM — OceanAtlas Control Room Aesthetic:
Color Tokens (CSS Variables):
--color-bg-primary: #0A0E1A (كون مظلم عميق — الخلفية الرئيسية)
--color-bg-surface: #0F1629 (سطح البطاقات)
--color-bg-elevated: #1A2240 (العناصر المرفوعة)
--color-accent-cyan: #00D4FF (التمييز الرئيسي — بيانات حية)
--color-accent-amber: #FFB800 (تحذيرات — Risk MEDIUM)
--color-accent-red: #FF3B5B (حرج — Risk CRITICAL)
--color-accent-green: #00E5A0 (آمن — Risk LOW)
--color-text-primary: #E8EBF5
--color-text-secondary:#8B97C7
Typography:
Display: "Space Mono" (Monospace — بث البيانات والإحداثيات)
UI: "IBM Plex Sans Arabic" (دعم كامل RTL + LTR)
Data: "JetBrains Mono" (الأرقام والإحداثيات والـ IMO numbers)
Arabic/English Toggle:
6.3 تدفق البيانات اللحظية
Real-Time Data Flow Architecture:
Backend (FastAPI)
│
├── AIS Ingestion Service → Redis Pub/Sub Channel: "ais:positions"
│
FastAPI WebSocket Endpoint (/ws/vessels)
│
├── Subscribe to Redis "ais:positions"
├── Filter by user's subscribed IMOs / Geofence
└── Push JSON position updates to connected clients
Next.js Frontend (Client Component)
│
├── useWebSocket() hook → connects to /ws/vessels
├── Receives: { imo, lat, lng, sog, cog, nav_status, timestamp }
├── Updates: Zustand store → vessel positions map
└── Triggers: Mapbox GL marker position update (requestAnimationFrame)
React Query (TanStack):
├── Static vessel data: Cache 30min (profile, ownership, specs)
├── Risk scores: Cache 15min (re-calculated on behavioral events)
└── OFAC results: Cache 24h (matching valid_until in DB)
─── SECTION 7: بروتوكول التماسك والجودة (Coherence Protocol) ───
المنطق: هذا البروتوكول هو "القاضي" الذي يمنع عرض بيانات متعارضة أو مُزيَّفة. يُطبَّق آلياً في طبقة الـ Service قبل أي كتابة في قاعدة البيانات.
COHERENCE VALIDATION RULES (Hard Gates):
RULE-001: IMO_PRIMARY_KEY_INTEGRITY
─────────────────────────────────────
قبل كتابة أي بيانات من AIS:
IF ais.vessel_name ≠ vessels.vessel_name WHERE imo = ais.imo:
→ CREATE coherence_alert (type: "NAME_MISMATCH")
→ LOG both values without displaying to user
→ BLOCK update until manually resolved or auto-resolved by Equasis re-verification
RULE-002: DRAUGHT_VS_DWT_COHERENCE
─────────────────────────────────────
IF ais.static_draught > vessels.max_draught × 1.05:
→ CREATE coherence_alert (type: "DRAUGHT_ANOMALY")
→ Flag for behavioral analysis (potential overloading)
RULE-003: LIVE_FETCH_PRIMACY
─────────────────────────────────────
عند الضغط على "Live Sync":
→ Bypass ALL Redis cache
→ Execute concurrent scrape: Equasis + AIS + OFAC simultaneously
→ Merge results and re-run coherence validation
→ Update DB only if validation passes
→ Broadcast updated profile via WebSocket
RULE-004: ZERO_CONFLICT_SCHEMA
─────────────────────────────────────
وحدة Maritime Connector تستخدم AIS data الموجود فقط.
ممنوع إنشاء AIS ingestion pipeline إضافية أو تعديل vessel_intelligence tables.
كل البيانات الجديدة تُكتب فقط في: matchmaking_connections + decision_makers.
RULE-005: SANCTIONS_DISPLAY_RULE
─────────────────────────────────────
IF compliance_screenings.valid_until < NOW():
→ Mark OFAC result as "STALE" في الواجهة
→ Auto-queue re-screening Celery task
→ لا تُعرض نتائج OFAC قديمة على أنها نتائج حالية
RULE-006: DATA_PRIVACY_ENFORCEMENT
─────────────────────────────────────
بيانات decision_makers تُعرض فقط في سياق B2B transactional.
ممنوع دمجها مع vessel_intelligence tables.
ممنوع تصديرها في تقارير Vessel Passport أو Risk Assessment.
تُعرض فقط في: Supplier Intelligence Mode + Procurement Mode.
─── SECTION 8: التوثيق المطلوب (Documentation Requirements) ───
المنطق: التوثيق جزء من الكود وليس إضافة اختيارية. يضمن استمرارية المشروع واستقلاليته عن شخص بعينه.
DOCUMENTATION DELIVERABLES:
API Documentation (OpenAPI 3.0)
─────────────────────────────────
Database Schema Documentation
─────────────────────────────────
Service Layer Documentation
─────────────────────────────────
Frontend Component Documentation
─────────────────────────────────
Deployment Documentation
─────────────────────────────────
─── SECTION 9: تعليمات التنفيذ للذكاء الاصطناعي ───
هذه التعليمات موجّهة للـ AI الذي سيُنفّذ البناء.
أوامر التنفيذ الحرجة:
HARD STOP:
❌ ممنوع منعاً باتاً استخدام بيانات demo أو hard-coded JSON.
❌ ممنوع إنشاء قاعدة بيانات مؤقتة أو Mock API responses.
❌ ممنوع تسمية أي مصدر بيانات خارجي أو نسبة البيانات إليه في واجهة المستخدم.
❌ ممنوع تكرار منطق AIS — وحدة Maritime Connector تستهلك البيانات الموجودة.
✅ كل بيانات في الواجهة تُوصَف بـ "OceanAtlas Verified Data".
EXECUTION ORDER (الترتيب الإلزامي):
Phase 1: Database Schema + Alembic migrations
Phase 2: FastAPI services (AIS → Equasis → OFAC)
Phase 3: Coherence Protocol implementation
Phase 4: Risk Score engine
Phase 5: Next.js frontend (Map → Vessel Profile → Reports)
Phase 6: Maritime Connector module
Phase 7: Human Capital Intelligence (Apollo/Hunter integration)
Phase 8: PDF Report generation
Phase 9: i18n Arabic/English
Phase 10: Documentation + API Swagger
FIRST DELIVERABLE (ابدأ بهذا):
(يعرض مواقع السفن فور وصولها من AIS feed)
QUALITY GATE (شرط القبول لكل مرحلة):
✅ الكود مكتوب بمعيار Clean Code (أسماء وصفية، دوال مُركَّزة)
✅ كل Service موثَّق بـ docstring كامل
✅ كل Endpoint موثَّق في Swagger
✅ لا بيانات اعتماد في الكود (استخدام env variables)
✅ بروتوكول Coherence مُطبَّق في طبقة الـ Service
✅ لا تكرار لمنطق AIS (DRY)
✅ كل جدول جديد يمتد الـ Schema دون تعديل الجداول الأساسية
─── ملخص المنصة الكامل ───
OceanAtlas MIL-OS هو نظام تشغيل استخباراتي بحري موحّد يجمع:
🛰️ AIS Real-Time Tracking → مواقع السفن الحية كل 30 ثانية
📋 Registry Intelligence → بيانات Equasis الرسمية والموثَّقة
⚖️ Sanctions Screening → فحص OFAC مع صلاحية 24 ساعة
🕵️ Behavioral Analytics → Dark Activity, STS, Loitering, Port Hopping
🏢 Corporate Web Mapping → خوارزمية عودية لتتبع شبكة الملكية
📊 Risk Scoring Engine → نتيجة مركّبة من 6 عوامل موزونة
👔 Human Capital Intelligence → ربط السفينة بصانع القرار البشري
🤝 Maritime Connector → B2B Matchmaking: موردون × مشغّلون
📦 Cargo Matchmaker → مزاوجة السفن الشاغرة مع الشحنات المتاحة
📄 Automated PDF Reports → 3 أنواع من التقارير الاحترافية
🌐 Bilingual Interface → عربي/إنجليزي مع RTL كامل
🔒 Coherence Protocol → لا بيانات متعارضة تصل للمستخدم أبداً
OceanAtlas MIL-OS — Proprietary Maritime Intelligence System
All data presented as OceanAtlas Verified Intelligence — No external source attribution in UI
Documentation Standard: OpenAPI 3.0 + JSDoc + Storybook
Code Standard: Clean Code + SOLID + DRY + Full Test Coverag