Analyse Des Ecarts Du Contrat Bridge

Objectif

Ce document inventorie les ecarts entre:

• les actions bridge utilisees ou documentees dans TVCAST_DISPLAY_WEB
• les actions actuellement declarees dans le contrat officiel
• les actions exposees dans les capacites host (GET_HOST_CAPABILITIES)

Il sert de base pour preparer une evolution du depot officiel:

comminter/tvcast-display-hosts-api-contracts

Etat Du Contrat Actuel

Le schema request officiel est:

schemas/envelope/request.schema.json

Actions actuellement autorisees dans TV_API_REQUEST:

CAN_LAUNCH_APP
GET_DEVICE_POLICY_STATUS
GET_HOST_CAPABILITIES
GET_NETWORK_INFO
GET_STORAGE_INFO
GET_SYSTEM_INFO
LAUNCH_TV
OPEN_MANUFACTURER_SETTINGS
OPEN_SETTINGS
OPEN_SYSTEM_SETTINGS
PURGE_DATA
REBOOT
REMOVE_OWNER_OR_ADMIN
REQUEST_DEVICE_ADMIN
RESTART_APP

Le contrat est donc incomplet par rapport au bridge effectivement utilise par l'application Web et par les hotes.

Ecarts Critiques

Ces actions sont utilisees par l'application Web ou attendues par les hotes, mais ne sont pas declarees dans l'enum TV_API_REQUEST.

Action	Usage actuel	Impact	Priorite
GET_IDENTIFIER	Recuperation de l'identifiant device via platformBridge.getIdentifier()	L'identification device n'est pas validable contractuellement	Haute
INITIALIZE_HOST	Handshake Web vers Host au demarrage	L'initialisation standard du host n'est pas contractee	Haute
LAUNCH_APP	Lancement d'application externe	Present dans les capacites mais absent de l'enum request	Haute
APP_IS_FOREGROUND	Verification qu'une app est au premier plan	Utilise par le bridge et les probes de diagnostic	Haute
PURGE_USER_DATA	Action canonique de purge utilisateur	Present dans les capacites, absent de l'enum request	Haute
HOTSPOT_GET	Lecture de l'etat hotspot	Present dans les capacites, absent de l'enum request	Haute
HOTSPOT_SET	Modification de l'etat ou des credentials hotspot	Present dans les capacites, absent de l'enum request	Haute

Ecarts Fonctionnels A Standardiser

Ces actions existent dans le code ou les diagnostics, mais leur statut doit etre confirme avant de les promouvoir dans le contrat officiel.

Action	Usage actuel	Remarque	Priorite
GET_MAC	Recuperation directe de l'adresse MAC	Peut etre couvert par GET_NETWORK_INFO, mais reste utilise par le bridge	Moyenne
GET_MANUFACTURER	Recuperation du fabricant	Peut etre derive de GET_HOST_CAPABILITIES.host.vendor	Moyenne
GET_MODEL	Recuperation du modele	Peut etre derive de GET_HOST_CAPABILITIES.host.model	Moyenne
GET_DEVICE_INFO	Probe de diagnostic composee	Dans l'app Web, compose manufacturer/model/mac/system/storage	Moyenne
INSTALL_APP	Demande d'installation d'application	Fonction sensible, besoin de schema params et erreurs dediees	Moyenne
SWITCH_INPUT_SOURCE	Declare dans les capacites host	Absent de l'enum request et sans schema params/success	Moyenne

Actions Legacy

Ces actions doivent rester documentees pour compatibilite, mais ne doivent pas etre le chemin prioritaire des nouveaux hotes.

Action	Statut	Remarque
PURGE_DATA	Legacy temporaire	Remplacee par PURGE_USER_DATA
OPEN_SETTINGS	Legacy temporaire	Remplacee par OPEN_SYSTEM_SETTINGS et OPEN_MANUFACTURER_SETTINGS
PREPARE_DEVICE	Legacy LG	Fallback apres echec de INITIALIZE_HOST
GET_INFO	Legacy LG/Chromecast	Ancienne action d'information globale
GET_SOFTAP	Legacy LG	Remplacee par HOTSPOT_GET / HOTSPOT_SET si standardise

Decision Sur La Purge Utilisateur

PURGE_USER_DATA est l'action canonique.

PURGE_DATA est legacy et doit rester supportee temporairement pour compatibilite avec les hotes existants.

Les nouveaux hotes doivent implementer PURGE_USER_DATA.

Contrat Android Actuel

L'implementation host Android utilise le format suivant.

Request:

{
	"type": "TV_API_REQUEST",
	"requestId": "req-123",
	"action": "PURGE_USER_DATA",
	"params": {}
}

Success response:

{
	"type": "TV_API_RESPONSE",
	"requestId": "req-123",
	"ok": true,
	"payload": {}
}

Error response possible si le deeplink de purge n'est pas disponible ou echoue:

{
	"type": "TV_API_RESPONSE",
	"requestId": "req-123",
	"ok": false,
	"payload": {
		"message": "Purge deeplink is not available on this device",
		"code": "NOT_AVAILABLE_ON_DEVICE"
	}
}

Evolution Recommandee Du Contrat

Dans tvcast-display-hosts-api-contracts:

1. Ajouter PURGE_USER_DATA dans schemas/envelope/request.schema.json.
2. Garder PURGE_DATA dans l'enum request comme action legacy/deprecated.
3. Ajouter examples/requests/purge-user-data.request.json.
4. Ajouter examples/responses/purge-user-data.success.json avec payload: {}.
5. Ajouter un schema de succes vide reutilisable ou dedie a PURGE_USER_DATA.
6. Ajouter ce schema dans le oneOf succes de schemas/envelope/response.schema.json.
7. Conserver PURGE_USER_DATA dans schemas/actions/get-host-capabilities-success.schema.json.
8. Documenter PURGE_DATA comme legacy dans docs/schemas/actions.md.

Incoherences Internes Du Contrat

Certaines actions sont exposees dans les capacites host mais absentes de l'enum request.

Action	Presence actuelle	Probleme
LAUNCH_APP	capabilities.actions seulement	Un host peut declarer la capacite, mais une request LAUNCH_APP est invalide
HOTSPOT_GET	capabilities.actions seulement	Capacite declaree sans action request valide
HOTSPOT_SET	capabilities.actions seulement	Capacite declaree sans action request valide
PURGE_USER_DATA	capabilities.actions seulement	Action canonique absente de l'enum request
SWITCH_INPUT_SOURCE	capabilities.actions seulement	Capacite declaree sans action request valide

Certaines actions sont dans l'enum request mais pas dans les capacites host.

Action	Remarque
GET_HOST_CAPABILITIES	Normal: action de decouverte, pas forcement une capacite fonctionnelle
OPEN_SETTINGS	Legacy, peut rester hors capabilities modernes
PURGE_DATA	Legacy, remplacee par PURGE_USER_DATA

Actions Host Vers Web Et Evenements

Ces messages ne doivent pas etre melanges avec les requests Web vers Host. Ils doivent etre traites par des schemas separes si le contrat officiel les standardise.

Action ou type	Sens	Statut recommande
PING	Host vers Web	Schema dedie health-check
NOTIFY_KEY	Web vers Host, notification sans reponse metier	Schema dedie event/notification ou request async
TV_API_EVENT	Host vers Web	Schema event separe
UPDATE_CONTENT_PREVIEW	Host vers Web	Schema event preview separe
UPDATE_LAYOUT_PREVIEW	Host vers Web	Schema event preview separe

Verification Dans Le Host Android

Le repo host Android consulte est:

C:\Users\User\AndroidStudioProjects\TVCAST_TV_HOST_ANDROID

Le handler central est:

app/src/main/kotlin/fr/tvcast/display/WebBridgeInterface.kt

Le host Android confirme que plusieurs actions absentes du contrat officiel sont deja implementees.

Actions Android implementees mais absentes de l'enum TV_API_REQUEST officielle:

• INITIALIZE_HOST
• GET_IDENTIFIER
• GET_MODEL
• GET_MANUFACTURER
• GET_MAC
• LAUNCH_APP
• APP_IS_FOREGROUND
• PURGE_USER_DATA
• INSTALL_APP
• HOTSPOT_GET
• HOTSPOT_SET

Le repo Android possede deja une validation contractuelle locale:

contract/
├── fixtures/
│   ├── inbound-requests/
│   ├── outbound-responses/
│   └── host-requests/
├── package.json
└── scripts/validate-contract.mjs

Cette structure utilise les noms inbound-requests et outbound-responses, alors que le guide generique host recommande les noms moins ambigus web-to-host et host-to-web. Les deux approches sont acceptables si la documentation du projet hote explicite clairement le sens des messages.

Payloads Android Confirmes

Ces payloads doivent servir de base aux schemas officiels ou aux fixtures de transition.

Action	Params Android actuels	Success payload Android actuel	Erreurs observees
INITIALIZE_HOST	{}	{}	Non specifie
GET_IDENTIFIER	{}	{ "id": "<android_id>" }	NOT_AVAILABLE_ON_DEVICE
GET_MODEL	{}	{ "model": "<Build.MODEL>" }	Non specifie
GET_MANUFACTURER	{}	{ "manufacturer": "<Build.MANUFACTURER>" }	Non specifie
GET_MAC	{}	{ "mac": "<mac>" }	NOT_AVAILABLE_ON_DEVICE
LAUNCH_APP	{ "appId": string, "dataUri"?: string } ou { "package": string } legacy	{}	INVALID_PARAMS, APP_NOT_INSTALLED, APP_NOT_LAUNCHABLE, INTERNAL_ERROR
APP_IS_FOREGROUND	{ "package": string } actuellement cote Android	{ "isForeground": boolean }	INVALID_PARAMS, NOT_AVAILABLE_ON_DEVICE
INSTALL_APP	{ "url": string }	{}	INVALID_PARAMS, INTERNAL_ERROR
HOTSPOT_GET	{}	Objet hotspot avec ssid, password, softApStatus, stationsCount, updatedAt, shizukuStatus	NOT_AVAILABLE_ON_DEVICE, INTERNAL_ERROR
HOTSPOT_SET	{ "subAction": "open" | "start" | "stop" | "restart" }	{}	NOT_AVAILABLE_ON_DEVICE, SHIZUKU_NOT_READY, INVALID_PARAMS, INTERNAL_ERROR
PURGE_USER_DATA	{}	{}	NOT_AVAILABLE_ON_DEVICE
PURGE_DATA	{}	{}	NOT_AVAILABLE_ON_DEVICE

Ecart APP_IS_FOREGROUND

Il existe un ecart entre l'application Web et le host Android.

Cote Web, platformBridge.isAppInForeground(packageName) envoie actuellement:

{
	"appId": "com.example.app"
}

Cote Android, le handler lit actuellement:

params.package

Recommandation de standardisation:

1. Le contrat officiel doit utiliser appId, pour rester coherent avec LAUNCH_APP et CAN_LAUNCH_APP.
2. Le host Android doit accepter appId en priorite.
3. Le host Android peut accepter package temporairement comme alias legacy.
4. Les fixtures doivent couvrir le format canonique appId.

Fixtures Android Manquantes

Le repo Android a des fixtures pour les actions deja couvertes par le contrat actuel, mais plusieurs actions implementees ne sont pas encore fixturees parce qu'elles ne passent pas contre le contrat officiel actuel.

Fixtures a ajouter dans le host Android apres evolution du contrat:

• request/response INITIALIZE_HOST
• request/response GET_IDENTIFIER
• request/response GET_MODEL
• request/response GET_MANUFACTURER
• request/response GET_MAC
• request/response LAUNCH_APP
• request/response APP_IS_FOREGROUND
• request/response INSTALL_APP
• request/response HOTSPOT_GET
• request/response HOTSPOT_SET
• request/response PURGE_USER_DATA

La presence de PURGE_DATA doit rester limitee a une fixture legacy si le contrat conserve l'action pendant la periode de compatibilite.

Priorites De Correction Du Contrat

Priorite Haute

1. GET_IDENTIFIER
2. INITIALIZE_HOST
3. LAUNCH_APP
4. APP_IS_FOREGROUND
5. PURGE_USER_DATA
6. HOTSPOT_GET
7. HOTSPOT_SET

Priorite Moyenne

1. GET_MAC
2. GET_MANUFACTURER
3. GET_MODEL
4. GET_DEVICE_INFO
5. INSTALL_APP
6. SWITCH_INPUT_SOURCE

Legacy A Documenter

1. PURGE_DATA
2. OPEN_SETTINGS
3. PREPARE_DEVICE
4. GET_INFO
5. GET_SOFTAP

Impact Pour TVCAST_DISPLAY_WEB

Apres mise a jour du contrat officiel:

1. Mettre a jour CONTRACT_VERSION dans la CI.
2. Ajouter les fixtures Web manquantes dans contract/fixtures/outbound-requests/.
3. Ajouter les fixtures Web manquantes dans contract/fixtures/inbound-responses/.
4. Modifier le bridge pour envoyer PURGE_USER_DATA en priorite.
5. Garder un fallback temporaire vers PURGE_DATA.
6. Mettre a jour les guides pour les hotes Tizen, Android, LG et Philips.

Impact Pour Les Applications Hotes

Les hotes doivent progressivement:

1. Declarer leurs capacites avec les actions canoniques.
2. Implementer PURGE_USER_DATA plutot que PURGE_DATA.
3. Garder PURGE_DATA uniquement si la compatibilite avec une version Web legacy est requise.
4. Ajouter des fixtures contractuelles pour chaque action supportee.
5. Valider ces fixtures contre le contrat officiel pinne via CONTRACT_VERSION.

References

• docs/technique/bridge/contract-validation.md
• docs/technique/bridge/host-tizen-contract-validation-guide.md
• docs/technique/bridge/exchanges.md
• src/lib/classes/platforms/platformBridge.ts
• src/lib/components/settings/HostBridgeSection.svelte
• schemas/envelope/request.schema.json dans tvcast-display-hosts-api-contracts
• schemas/actions/get-host-capabilities-success.schema.json dans tvcast-display-hosts-api-contracts