# MF919 Application Version Push Changes

This document explains the changes made to support MF919 application version pushes in the TMS flow.

## Goal

Before these changes, the TMS could push:

- parameter config
- EMV config
- keys config

But for `application`, the MF919 flow was incomplete.

The system was sending a generic `UPDATE_APPLICATION` command without:

- fetching the active application version from the database
- including the application version in the MQTT payload
- including a downloadable file URL for the APK/package

Because of that, the terminal could not clearly receive and process application version updates in the same structured way as EMV config.

## Files Changed

### 1. `apps/tms_core/lib/tms_core/terminal_management/config_file_version.ex`

#### What changed

- Added `application` to the allowed `config_type` values.
- Updated the module documentation to mention application package artifacts.

#### Why this was needed

This schema is the version registry for file-based artifacts. It already supported `emv_config` and `keys_config`, but not `application`.

Without this change, the TMS could not officially treat the application package as a versioned file coming from `config_file_versions`.

#### Simple meaning

This change tells the system:

"Application is also a real versioned config file, just like EMV and keys."

---

### 2. `apps/tms_core/lib/tms_core/terminal_management/mqtt_command_builder.ex`

#### What changed

- Added `UPDATE_APPLICATION` to the MF919 command list.

#### Why this was needed

The builder already knew how to include fields like:

- `command`
- `requestId`
- `downloadUrl`
- `version`

But MF919 command metadata did not explicitly include `UPDATE_APPLICATION` in the supported command list.

#### Simple meaning

This change tells the MF919 command layer:

"Application update is a valid command type for this device model."

---

### 3. `apps/tms_core/lib/tms_core/terminal_management/version_compliance_checker.ex`

#### What changed

- Added `application` to the list of version checks.
- Added targeted re-push handling for `application`.

#### Why this was needed

This module compares:

- version reported by device
- version currently active in TMS

Earlier it only checked:

- parameter config
- EMV config
- keys config

So even if the terminal reported an outdated application version, TMS would not detect it or re-push it.

After this change, the checker can:

- read the target application version from `config_file_versions`
- compare it with the terminal-reported application version
- trigger an application push if the device version is outdated

#### Simple meaning

This change tells the compliance checker:

"Also watch the application version. If the terminal is behind, send it again."

---

### 4. `apps/tms_core/lib/tms_core/terminal_management/auto_push_service.ex`

#### What changed

This file got the main implementation changes:

- Added MF919-specific handling for `application` pushes.
- Added a new function: `push_mf919_application/4`.
- Added helper logic to resolve the application artifact path.
- Added helper logic to stage a local file into the OTA folder when needed.
- Added logic to build a public download URL.
- Added push logging with `version_sent`, checksum, size, and file path.

#### What the new flow does

When TMS decides to push the application for MF919, it now:

1. Looks up the active `application` row from `config_file_versions` using vendor and model.
2. Reads the configured application version.
3. Resolves the file path:
   - if it is already a full URL, use it directly
   - if it is a root static path like `/uploads/...`, convert it to a full public URL
   - if it is a local file path, copy it into `priv/ota/<serial_number>/`
4. Creates a push log entry in `parameter_push_logs`.
5. Sends an MQTT command with:
   - `command = UPDATE_APPLICATION`
   - `downloadUrl = <public file url>`
   - `version = <application version>`

#### Why this was needed

Earlier, application push was too generic. It did not behave like EMV push.

That meant:

- no proper DB lookup for active application version
- no version sent to device
- no download URL sent to device
- no reliable artifact resolution for APK/package files

This change makes application push work like a real versioned OTA artifact.

#### Simple meaning

This is the main fix.

It tells TMS:

"For MF919 application updates, fetch the version from DB, find the APK file, create a download link, log it, and send the device a proper update command."

---

## End-to-End Result

After these changes, the intended MF919 application push flow is:

1. TMS checks whether the device application version is missing or outdated.
2. TMS fetches the active application version from `config_file_versions`.
3. TMS resolves the APK/package location.
4. TMS sends an MQTT `UPDATE_APPLICATION` command with version and download URL.
5. Device downloads and installs the package.
6. Device later reports its installed application version back to TMS.

## Important Limitation Found During Validation

The code changes are correct, but the runtime flow can still fail if the application artifact path in the database does not point to a real file.

Example failure seen during validation:

- TMS successfully fetched the `application` row from DB
- but the file path `priv/static/mf919/app-release.apk` was missing at runtime in that test scenario
- so the application MQTT push stopped before sending the final command

That means:

- DB lookup is now working
- application version logic is now implemented
- but the actual APK file path must be valid and reachable for the push to complete

## Very Simple Summary

Earlier, `application` was treated like a plain command.

Now it is treated like a real versioned OTA file.

That means the system now:

- reads application version from DB
- finds the APK file
- creates a download URL
- sends version + URL to the terminal
- checks whether the terminal is outdated and re-pushes if needed

So the change is mainly about making `application` behave the same structured way as `emv_config`.