TEKNOFEST Savaşan İHA Yarışması - Mock Server

This project is a Spring Boot application designed to simulate the server-side API for the TEKNOFEST Savaşan İHA (Combat UAV) Competition. It allows teams to test their ground control station (GCS) software's communication capabilities by providing a mock environment that replicates the documented API endpoints and data structures.

Features

• API Endpoint Emulation: Implements all major API endpoints described in the communication document:
  • /api/giris: Team login.
  • /api/sunucusaati: Get current server time.
  • /api/telemetri_gonder: Send UAV telemetry and receive other teams' positions.
  • /api/kilitlenme_bilgisi: Send lock-on information.
  • /api/kamikaze_bilgisi: Send kamikaze mission (QR code scan) information.
  • /api/qr_koordinati: Get the coordinates of the QR code target for the kamikaze mission.
  • /api/hss_koordinatlari: Get coordinates of active Air Defense Systems (HSS).
• Data Structures: Uses DTOs (Data Transfer Objects) matching the JSON formats specified in the document.
• In-Memory Data Storage: Utilizes HashMaps for storing team data, telemetry, and other competition states for simplicity and quick iteration.
• Mock UAVs: Includes two simulated UAVs (Team IDs 998 and 999) that continuously fly in circular patterns, providing dynamic data for GCS testing.
• HSS Activation: Provides a (non-competition standard) admin endpoint to toggle the active state of HSS, allowing teams to test their GCS response to HSS becoming active/inactive.
• Lombok: Uses Lombok to reduce boilerplate code.

Getting Started

Prerequisites

• Java JDK 17 (or a compatible recent LTS version)
• Maven 3.6+ (or use the embedded Maven wrapper ./mvnw)

Running the Application

1. Clone the repository:

   git clone https://github.com/KardasLand/teknofest-spring-replica
   cd teknofest-spring-replica

2. Build the project (optional, as Spring Boot can run directly):

   ./mvnw clean package

3. Run the application:
   • Using Maven:

     ./mvnw spring-boot:run

   • Or, if you built a JAR:

     java -jar target/teknofest-spring-replica-0.0.1-SNAPSHOT.jar

   • From your IDE: Find the TeknofestSpringReplicaApplication.java class and run its main method.

The server will start on http://localhost:5000 by default (as specified in application.yaml).

API Usage and Testing

Use a tool like Postman, Insomnia, or curl to interact with the API endpoints.

Default Test Users

The DataStorageService.java pre-populates some test users:

• Username: takimkadi1, Password: takimsifresi1, Team ID: 1
• Username: takimkadi2, Password: takimsifresi2, Team ID: 2
• Username: takimkadi3, Password: takimsifresi3, Team ID: 3

Example Test Flow

1. Team Login (e.g., Team 1):

   • POST http://localhost:5000/api/giris
   • Body (JSON):

     {
         "kadi": "takimkadi1",
         "sifre": "takimsifresi1"
     }

   • Response: 1 (Team ID).
   • Note: This sets a session cookie (JSESSIONID). Ensure your client handles and sends this cookie for subsequent authenticated requests.

2. Get Server Time:

   • GET http://localhost:5000/api/sunucusaati
   • (Requires authentication cookie from login)
   • Response (Example):

     {
         "gun": 14,
         "saat": 11,
         "dakika": 29,
         "saniye": 4,
         "milisaniye": 653
     }

3. Send Telemetry (e.g., from Team 1):

   • POST http://localhost:5000/api/telemetri_gonder
   • Body (JSON - example for Team 1, refer to TelemetryRequestDto.java and competition doc):

     {
         "takim_numarasi": 1,
         "iha_enlem": 41.508775,
         "iha_boylam": 36.118335,
         "iha_irtifa": 38,
         "iha_dikilme": 7,
         "iha_yonelme": 210,
         "iha_yatis": -30,
         "iha_hiz": 28,
         "iha_batarya": 50,
         "iha_otonom": 1,
         "iha_kilitlenme": 0, // Set to 1 if locking, then include hedef_merkez_X/Y etc.
         "gps_saati": {
             "saat": 11,
             "dakika": 38,
             "saniye": 37,
             "milisaniye": 654
         }
     }

   • Response will include current server time and konumBilgileri for other active teams (including mock UAVs 998 and 999). Example:

     {
         "sunucusaati": { "gun": 13, "saat": 11, "dakika": 38, "saniye": 38, "milisaniye": 739 },
         "konumBilgileri": [
             // Data for mock UAV 998
             {
                 "takim_numarasi": 998,
                 "iha_enlem": 41.509...,
                 "iha_boylam": 36.119...,
                 // ... other fields
                 "zaman_farki": 50 // ms difference from server's receive time
             },
             // Data for mock UAV 999
             {
                 "takim_numarasi": 999,
                 // ...
             }
         ]
     }

4. Send Lock-on Information (e.g., Team 1 locked onto a target):

   • POST http://localhost:5000/api/kilitlenme_bilgisi
   • Body (JSON):

     {
         "kilitlenmeBitisZamani": {
             "saat": 11,
             "dakika": 41,
             "saniye": 3,
             "milisaniye": 141
             // "gun" is not specified in the example, assuming server uses current day or it's implied by server time context
         },
         "otonom_kilitlenme": 1
     }

   • Expected Response: 200 OK (no specific body defined in document).

5. Get QR Code Target Coordinates:

   • GET http://localhost:5000/api/qr_koordinati
   • (Requires authentication cookie)
   • Response (Example):

     {
         "qrEnlem": 41.51238882,
         "qrBoylam": 36.11935778
     }

6. Send Kamikaze Mission Information (after QR scan):

   • POST http://localhost:5000/api/kamikaze_bilgisi
   • Body (JSON):

     {
         "kamikazeBaslangicZamani": { "saat": 11, "dakika": 44, "saniye": 13, "milisaniye": 361 },
         "kamikazeBitisZamani": { "saat": 11, "dakika": 44, "saniye": 27, "milisaniye": 874 },
         "qrMetni": "teknofest2025"
     }

   • Expected Response: 200 OK (no specific body).

7. Control HSS (Admin Endpoint - For Testing Only):

   • Admin Login (Simulated):
     • POST http://localhost:5000/api/admin/login
     • Form Data: user=admin, pass=adminpass
   • Toggle HSS:
     • POST http://localhost:5000/api/admin/hss_toggle?active=true (to activate)
     • POST http://localhost:5000/api/admin/hss_toggle?active=false (to deactivate)

8. Get HSS Coordinates:

   • GET http://localhost:5000/api/hss_koordinatlari
   • (Requires team authentication cookie).
   • Response if HSS active (Example):

     {
         "sunucusaati": { "gun": 19, "saat": 15, "dakika": 51, "saniye": 43, "milisaniye": 775 },
         "hss_koordinat_bilgileri": [
             { "id": 0, "hssEnlem": 40.23260922, "hssBoylam": 29.00573015, "hssYaricap": 50 },
             { "id": 1, "hssEnlem": 40.23351019, "hssBoylam": 28.99976492, "hssYaricap": 50 }
             // ... more HSS if defined and active
         ]
     }

   • Response if HSS inactive:

     {
         "sunucusaati": { /* ... */ },
         "hss_koordinat_bilgileri": []
     }

Refer to the competition's "Haberleşme Dokümanı" for detailed JSON structures and expected behavior for all endpoints.

Current Limitations & Known "Flaws"

This mock server is intended for GCS development and testing, not for production use or as a secure system.

1. Simplified Authentication:

   • The authentication mechanism (/api/giris) is basic and relies on simple username/password checks stored in-memory.
   • It uses standard HTTP sessions (JSESSIONID cookie).
   • No Spring Security: Spring Security is not implemented. This was because robust security is not the primary focus of such temporary event systems. The goal is to test GCS compatibility with the documented API, flaws and all.
   • The "admin" endpoints for HSS control have a very trivial, non-secure authentication check.

2. In-Memory Data Storage:

   • All data (users, telemetry, HSS state) is stored in HashMaps and is lost when the application stops.
   • This is suitable for testing but not for persistent data. The next step would be to integrate a database like Redis if persistence or shared state across multiple instances were required.

3. Limited Validation:

   • While some basic DTO validation might occur via Spring, comprehensive business rule validation (e.g., ensuring telemetry values are within realistic physical bounds, strict 2Hz telemetry rate limiting per team) is not fully implemented. The document mentions a 400 error for >2Hz telemetry, which is complex to perfectly enforce in this mock without more state per team.
   • Error code 204 for "Gönderilen paketin Formatı Yanlış" is unusual. This mock server mostly uses 400 Bad Request for such client-side errors, which is more conventional.

4. Single Instance:

   • Designed to run as a single instance. No considerations for clustering or load balancing.

5. Mock UAV Behavior:

   • The mock UAVs fly simple circular paths. They do not react to other UAVs, HSS, or perform advanced maneuvers. Their purpose is to provide dynamic telemetry data.

6. No Real-Time Guarantees:

   • While @Scheduled is used for mock UAV updates, it's subject to Java's scheduling and thread execution, not hard real-time.

Future Improvements (Potential)

• Integrate Redis for more persistent/shared data storage.
• Implement more detailed validation rules as per the competition specification.
• Add more sophisticated mock UAV behaviors.
• Introduce configurable scenarios (e.g., define HSS activation times, QR code values programmatically).
• If the actual competition server implements more robust authentication, this mock could be updated to reflect that (e.g., token-based auth).

Contributing

Feel free to fork the project, make improvements, and submit pull requests. If you find discrepancies with the official competition document, please open an issue.

---

License

This project is licensed under the GNU AGPLv3 License. See the LICENSE file for details.