reupload

manual.md

@@ -0,0 +1,80 @@
+# Mobile App Integration Manual
+
+## Overview
+This document outlines the initialization flow for the mobile application, specifically focusing on the version check process ensuring users are on the latest or a supported version of the app.
+
+## App Launch Flow
+
+When the mobile application launches, it must perform a version check against the API to determine if an update is available or mandatory.
+
+### Flow Logic
+1.  **App Launch**: User opens the application.
+2.  **Check Version**: The app sends a request to the API with its current version and operating system.
+3.  **Handle Response**:
+    *   **Update Required**: If the update is critical/mandatory, show a **blocking modal**. The user cannot dismiss it and must click a button to go to the App Store or Google Play Store.
+    *   **Update Optional**: If a new version is available but not mandatory, show a **dismissible notification** or modal suggesting the user to update for a better experience.
+    *   **Latest Version**: If the app is up-to-date, proceed to the app home screen silently.
+    *   **Version Not Found**: If the version is not recognized (e.g., development build), do not show any update prompts.
+
+## API Reference
+
+### Check App Version
+
+**Endpoint**
+`POST /api/app-version`
+
+**Description**
+Checks if the provided app version is the latest, requires an update, or is optional.
+
+**Headers**
+- `Content-Type: application/json`
+- `Accept: application/json`
+
+**Request Body**
+
+| Parameter | Type   | Required | Description                                      |
+| :-------- | :----- | :------- | :----------------------------------------------- |
+| `version` | string | Yes      | The current version of the mobile app (e.g., "1.0.0"). |
+| `os`      | string | Yes      | The operating system. Values: `ios`, `android`.  |
+
+**Example Request**
+```json
+{
+    "version": "1.0.0",
+    "os": "ios"
+}
+```
+
+**Responses**
+
+The API returns a JSON object with an `update` key indicating the status.
+
+| Status Value | Meaning | Action Required |
+| :--- | :--- | :--- |
+| `latest` | App is up to date. | None. |
+| `required` | A critical update is available. | **Block user**, redirect to store. |
+| `optional` | A new version is available. | **Notify user**, allow optional update. |
+| `version-not-found` | Version unknown. | None (treat as latest). |
+
+**Response Examples**
+
+*Latest Version:*
+```json
+{
+    "update": "latest"
+}
+```
+
+*Required Update:*
+```json
+{
+    "update": "required"
+}
+```
+
+*Optional Update:*
+```json
+{
+    "update": "optional"
+}
+```