📡 AisFeedParser

AisFeedParser یک سامانه با کارایی بالا برای دریافت، تجزیه و ذخیره‌سازی خوراک داده‌های AIS (سیستم شناسایی خودکار) است. این پروژه با زبان C# و سکوی .NET 8 توسعه یافته و از معماری تمیز (Clean Architecture) پیروی می‌کند.

قابلیت‌های اصلی

• دریافت جمله‌های NMEA با پروتکل‌های TCP و UDP
• تجزیه پیام‌های AIS انواع ۱-۵، ۱۸-۱۹، ۲۴، ۲۷
• ذخیره‌سازی لاگ‌های خام ساعتی برای بازپخش (Replay)
• ذخیره‌سازی داده‌ها در SQLite (توسعه) و SQL Server (تولید)
• ارائه REST API برای پرس‌وجوی داده‌های کشتی‌ها
• پایش سلامت ارائه‌دهندگان AIS

فناوری‌های به‌کار رفته

ساختار پروژه

AisFeedParser/
├── src/
│   ├── AisFeedParser.Domain/          # موجودیت‌ها، رمزگشا، تجزیه NMEA
│   ├── AisFeedParser.Application/     # موارد استفاده، DTOها، انتزاع‌ها
│   ├── AisFeedParser.Infrastructure/  # ماندگاری، سرویس‌ها، مخزن‌ها
│   └── AisFeedParser.Api/             # کنترلرهای ASP.NET Core، میان‌افزارها
├── tests/
│   ├── AisFeedParser.Domain.Tests/    # آزمون‌های رمزگشا
│   └── AisFeedParser.Application.Tests/
├── docs/                              # مستندات فنی (فارسی و انگلیسی)
├── openspec/                          # مشخصات رسمی و پیشنهادات تغییر
└── ais_temp.txt                       # نمونه داده NMEA

این پروژه از معماری تمیز (Clean Architecture) یا معماری لایه‌ای به سبک DDD-lite پیروی می‌کند. وابستگی‌ها از بیرونی‌ترین لایه (API) به سمت داخلی‌ترین لایه (Domain) جهت‌گیری شده‌اند. هر لایه فقط به لایه داخلی‌تر از خود وابسته است.

نمودار معماری

الگوهای طراحی به‌کار رفته

لایه Presentation (API) — AisFeedParser.Api

نقطه ورود برنامه. شامل:

لایه Application — AisFeedParser.Application

موارد استفاده و انتزاع‌های کسب‌وکار:

لایه Domain — AisFeedParser.Domain

هسته برنامه بدون وابستگی خارجی:

لایه Infrastructure — AisFeedParser.Infrastructure

پیاده‌سازی ماندگاری و سرویس‌های زیرساختی:

داده از ارائه‌دهنده AIS وارد شده و از یک خط لوله ناهمزمان عبور می‌کند. هر مرحله از طریق Channelهای bounded با سیاست DropOldest به مرحله بعد متصل است.

نمودار خط لوله

مراحل خط لوله

جزئیات Channel‌ها

// Channel خطوط NMEA خام
Channel<AisRawMessage> lineChannel = Channel.CreateBounded<AisRawMessage>(
    new BoundedChannelOptions(capacity) {
        FullMode = BoundedChannelFullMode.DropOldest
    });

// Channel ردیف‌های پارس شده
Channel<AisParsedRow> parsedChannel = Channel.CreateBounded<AisParsedRow>(
    new BoundedChannelOptions(capacity) {
        FullMode = BoundedChannelFullMode.DropOldest
    });

AisDecoder.cs

کلاس استاتیک رمزگشای AIS. شامل ۳۸۹ خط کد. پیمایش بیتی با استفاده از BitArray و متدهای کمکی SixBit()، ToBits()، Get()، ToSignedCoord()، Decode6BitString().

انواع پیام‌های پشتیبانی شده

متدهای کلیدی

// متد اصلی رمزگشایی
public static AisMessage? Parse(string payload, int msgType, int fillBits)

// متدهای کمکی
private static BitArray SixBit(string payload)  // تبدیل payload بیس-۶۴ به بیت
private static uint ToBits(BitArray bits, int start, int length)  // استخراج بیت
private static double? ToSignedCoord(BitArray bits, int start, int length)  // مختصات امضا‌دار
private static string Decode6BitString(BitArray bits, int start, int length)  // رشته ۶ بیتی

AisMessage.cs

مدل پیام رمزگشایی شده با ۷۹ خاصیت init. تمام فیلدهای مشترک و اختصاصی هر نوع پیام پشتیبانی می‌شود:

Nmea.cs

تجزیه‌کننده استاتیک جمله‌های NMEA. جمله‌های پشتیبانی شده:

• !AIVDM / !AIVDO — داده AIS با Checksum
• $GPGGA — موقعیت GPS
• $GPVTG — مسیر و سرعت
• $GPZDA — زمان و تاریخ
• $PSHI — اختصاصی

اعتبارسنجی XOR Checksum با TryValidate(). مونتاژ پیام‌های چندبخشی (Multi-part) از طریق MultipartBuffer.

موجودیت‌ها (Entities)

این لایه شامل موارد استفاده (Use Cases) و واسط‌های انتزاعی است. تمام منطق کسب‌وکار مختص به یک سناریوی خاص در کلاس‌های Use Case کپسوله شده است.

موارد استفاده (Use Cases)

AisParsedRow — مدل جامع داده

کلاس AisParsedRow یک رکورد با ۹۹ پارامتر است که تمام داده‌های ممکن از جمله‌های AIS، NMEA و فراداده را در بر می‌گیرد. دارای ۶ متد کارخانه:

VesselLatestDataDto — DTO غنی

این DTO داده‌های موقعیتی AIS را با داده‌های پروفایل کشتی ترکیب می‌کند. دارای خواص Effective* است که از پروفایل یا داده مستقیم پر می‌شود:

public sealed record VesselLatestDataDto
{
    // داده مستقیم از AIS
    public long Mmsi { get; init; }
    public int? MsgType { get; init; }
    public double? Lat, Lon, Cog, Sog;
    public int? Heading, NavStatus;

    // خواص ترکیبی (Effective)
    public string? EffectiveName;       // از پروفایل یا داده AIS
    public string? EffectiveCallSign;
    public string? EffectiveShipType;
    public string? EffectiveDestination;
    public string? EffectiveImo;

    // ابعاد محاسبه شده
    public int? OverallLength;  // DimBow + DimStern
    public int? OverallWidth;   // DimPort + DimStar
}

MultiSocketIngestor — دریافت TCP/UDP

یک سرویس پس‌زمینه که از معماری host groups پشتیبانی می‌کند. هر گروه host شامل یک میزبان primary و چند میزبان passive است:

• TCP: از TcpClient با keep-alive، بافر خطی، و ارسال اولیه (init send)
• UDP: از UdpClient با بافر دریافتی قابل تنظیم
• Failover: در صورت قطع connection میزبان primary، به passive‌ها سوئیچ می‌کند
• HostConnectionTracker: آخرین زمان دریافت داده را رهگیری می‌کند (پنجره ۶۰ ثانیه)
• ExponentialBackoff: تاخیر تصاعدی با jitter تصادفی برای اتصال مجدد

ساختار پیکربندی میزبان

{
  "Ais:Hosts": [
    {
      "Host": "ais.example.com",
      "Port": 1234,
      "Transport": "Tcp",
      "Passives": [
        { "Host": "ais2.example.com", "Port": 1234, "Transport": "Tcp" }
      ]
    }
  ]
}

ParserService — تجزیه NMEA

سرویس پس‌زمینه با N کارگر (قابل تنظیم). وظایف:

1. خواندن خط از lineChannel
2. اعتبارسنجی Checksum NMEA با Nmea.TryValidate()
3. مونتاژ پیام‌های چندبخشی با MultipartBuffer
4. رمزگشایی payload AIS با AisDecoder.Parse()
5. به‌روزرسانی پروفایل کشتی با IAisProfileUpdater
6. نوشتن ردیف پارس شده در parsedChannel

SqlBulkWriter — نوشتن حجیم SQL Server

یکی از پیچیده‌ترین سرویس‌ها با ۱۰۱۴ خط کد. ویژگی‌ها:

SqliteWriter — نوشتن SQLite

سرویس ساده‌تر با ۲۳۸ خط. از یک جدول AisJson استفاده می‌کند با ستون‌های کافی برای تمام انواع پیام. مهاجرت خودکار برای ستون‌های جدید پشتیبانی می‌شود. از INSERT INTO پارامترشده با تراکنش استفاده می‌کند.

AisDataRepository — پرس‌وجوی مستقیم

۶۱۰ خط کد با پیاده‌سازی موازی برای SQLite و SQL Server. پرس‌وجوهای اصلی:

• GetLatestVesselsByMmsiAsync(): استفاده از CTE/ROW_NUMBER (SQLite) یا stored procedure (SQL Server)
• GetLatestVesselDataAsync(): پرس‌وجوی داده کشتی در بازه زمانی

سایر سرویس‌ها

این لایه شامل کنترلرهای ASP.NET Core، میان‌افزارها، Swagger و نقطه ورود برنامه است.

نقاط پایانی API

راه‌اندازی (Startup.cs)

public sealed class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddPresentation();    // کنترلرها، Swagger
        services.AddApplication();     // Use Cases
        services.AddInfrastructure(configuration); // Infrastructure
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseSwagger();
        app.UseSwaggerUI();
        app.UseRouting();
        app.UseEndpoints(endpoints => endpoints.MapControllers());
    }
}

ثبت ساختاریافته (Serilog)

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console()
    .WriteTo.File("logs/ais-.log",
        rollingInterval: RollingInterval.Day,
        retainedFileCountLimit: 14,
        fileSizeLimitBytes: 50 * 1024 * 1024)
    .CreateLogger();

این پروژه از دو نوع پایگاه داده پشتیبانی می‌کند: SQLite برای محیط توسعه و SQL Server برای محیط تولید.

SQLite — جدول AisJson

یک جدول با ستون‌های کافی برای تمام انواع پیام AIS و NMEA:

CREATE TABLE IF NOT EXISTS AisJson (
    Id              INTEGER PRIMARY KEY AUTOINCREMENT,
    IngestedAtUtc   TEXT NOT NULL,
    SourceIp        TEXT,
    Mmsi            INTEGER,
    MsgType         INTEGER,
    Lat             REAL,
    Lon             REAL,
    Cog             REAL,
    Sog             REAL,
    Heading         INTEGER,
    RawLine         TEXT,
    ChecksumOk      INTEGER,
    ParserError     TEXT,
    RepeatIndicator INTEGER,
    NavStatus       INTEGER,
    RotRaw          INTEGER,
    UtcSec          INTEGER,
    Maneuver        INTEGER,
    PosAcc          INTEGER,
    Raim            INTEGER,
    Radio           INTEGER,
    PayloadJson     TEXT,
    Transport       TEXT,
    Port            INTEGER
);

SQL Server — ۹ جدول نرمال شده

Stored Procedure — sp_GetLatestVesselsByMmsi

CREATE PROCEDURE sp_GetLatestVesselsByMmsi
    @SinceMinutes INT = 1440
AS
BEGIN
    WITH Ranked AS (
        SELECT *,
            ROW_NUMBER() OVER (PARTITION BY Mmsi ORDER BY IngestedAtUtc DESC) AS rn
        FROM AisPositionReport
        WHERE IngestedAtUtc >= DATEADD(MINUTE, -@SinceMinutes, GETUTCDATE())
    )
    SELECT r.*, vp.VesselName, vp.CallSign, vp.ShipType,
           vp.Destination, vp.Imo, vp.DimBow, vp.DimStern, vp.DimPort, vp.DimStar
    FROM Ranked r
    LEFT JOIN VesselProfiles vp ON r.Mmsi = vp.Mmsi
    WHERE r.rn = 1
    ORDER BY r.IngestedAtUtc DESC;
END

جداول EF Core

• Vessels — Id, Mmsi, Name
• VesselProfiles — تمام فیلدهای پروفایل
• ProviderStatus — وضعیت ارائه‌دهندگان AIS

پیکربندی برنامه در src/AisFeedParser.Api/appsettings.json قرار دارد و از الگوی Options Pattern با کلاس‌های strongly-typed استفاده می‌کند.

ساختار کامل پیکربندی

{
  "Database": {
    "UseInMemoryRepo": false,          // استفاده از مخزن درون‌حافظه‌ای
    "ConnectionString": "Data Source=ais.db"
  },
  "Ais": {
    "Hosts": [                         // میزبان‌های AIS
      {
        "Host": "ais.example.com",
        "Port": 1234,
        "Transport": "Tcp",           // Tcp یا Udp
        "Passives": [ ... ]           // میزبان‌های جایگزین
      }
    ],
    "ParserWorkers": 1,                // تعداد کارگرهای ParserService
    "ChannelCapacity": 50000,          // ظرفیت Channel‌ها
    "InitSend": "HELLO\r\n",           // پیام اولیه TCP
    "RawLogFolder": "raw",             // پوشه لاگ خام
    "Reconnect": {
      "InitialMs": 500,                // تاخیر اولیه اتصال مجدد
      "MaxMs": 30000                   // حداکثر تاخیر
    },
    "Replay": {
      "Enabled": true,                 // فعال‌سازی بازپخش
      "Folder": "raw",                 // پوشه لاگ
      "MaxLinesPerSecond": 1000        // نرخ بازپخش
    }
  },
  "Sql": {
    "Provider": "SqlServer",           // SqlServer یا Sqlite
    "ConnectionString": "...",
    "Writer": {
      "BatchSize": 300,                // اندازه دسته نوشتن
      "FlushMs": 200                   // فاصله فلاش
    }
  },
  "Serilog": {
    "MinimumLevel": "Information",
    "WriteTo": [
      { "Name": "Console" },
      {
        "Name": "File",
        "Args": {
          "path": "logs/ais-.log",
          "rollingInterval": "Day",
          "retainedFileCountLimit": 14,
          "fileSizeLimitBytes": 52428800
        }
      }
    ]
  }
}

کلاس‌های Options

آزمون‌ها با استفاده از چارچوب xUnit نوشته شده‌اند. در مجموع بیش از ۵۰ آزمون واحد وجود دارد.

AisDecoderTests.cs (۳۵+ آزمون)

AisDecoderSampleDataTests.cs (۱۴+ آزمون)

آزمون‌های مبتنی بر داده‌های واقعی از فایل ais_temp.txt:

• تبدیل payload به بیت
• مونتاژ پیام‌های چندبخشی
• محدوده مختصات (Lat: -90..90, Lon: -180..180)
• اعتبارسنجی ابعاد (غیرمنفی)
• معیار کارایی: پارس زیر ۱۰۰ میلی‌ثانیه

ابزار کمکی SetBits

// متد کمکی برای تنظیم بیت‌ها در آزمون‌ها
private static string SetBits(string payload, int offset, int length, uint value)
{
    var bits = SixBit(payload);
    for (int i = 0; i < length; i++)
        bits[offset + length - 1 - i] = ((value >> i) & 1) == 1;
    return string.Concat(
        Enumerable.Range(0, bits.Length / 6)
            .Select(i => SixBitChars(
                Enumerable.Range(0, 6).Select(j => bits[i * 6 + j] ? 1 : 0).ToArray()
            ))
    );
}

Azure DevOps Pipeline

# azure-build-pipelines.yml
trigger:
  - main

pool:
  vmImage: 'windows-latest'

steps:
  - task: NuGetToolInstaller@1
  - task: NuGetCommand@2
    inputs:
      restoreSolution: 'AisFeedParser.sln'
  - task: DotNetCoreCLI@2
    inputs:
      command: 'build'
      projects: 'src/**/*.csproj'
  - task: DotNetCoreCLI@2
    inputs:
      command: 'test'
      projects: 'tests/**/*.csproj'
    enabled: false  # فعلاً غیرفعال
  - task: DotNetCoreCLI@2
    inputs:
      command: 'publish'
      publishWebProjects: true
      arguments: '--configuration Release --output $(Build.ArtifactStagingDirectory)'
  - task: PublishBuildArtifacts@1

Docker — استقرار ظرف‌سازی شده

متغیرهای محیطی

پیکربندی محیط‌ها

پیشنهادات تغییر (Changes)

گردش کار OpenSpec

1. Proposal: ایجاد proposal در openspec/changes/<نام>/proposal.md
2. Implementation: پیاده‌سازی مطابق proposal + به‌روزرسانی spec
3. Archive: بایگانی change در openspec/changes/<نام>/

فایل‌های .windsurf/workflows/ شامل خودکارسازی‌های windsurf برای این گردش کار هستند.

راهنمای شروع سریع (Quick Start)

# ۱. کلون پروژه
git clone <repository-url>
cd ais-feed-parser

# ۲. باز کردن در Visual Studio
AisFeedParser.sln

# ۳. اجرا با SQLite (پیش‌فرض)
cd src/AisFeedParser.Api
dotnet run

# ۴. اجرا با SQL Server (نیازمند Docker)
docker-compose up -d     # راه‌اندازی SQL Server
dotnet run --environment Production

ساختار فایل‌های مستندات

خلاصه فایل‌ها و آمار

داده‌های تماس و منابع

• CI/CD: Azure DevOps Pipelines
• ظرف‌سازی: Docker + Docker Compose
• مستندات: پوشه docs/ و docs/fa/