PD-299 — Livrable agent-developer : module sharing-ui¶

• Story : PD-299 — Consolidation PD-298, A2 (guard propriétaire CTA) + A6 (blocage offline) + A7 (correction useProofShares)
• Agent : agent-developer (Claude)
• Module : sharing-ui
• Projet : ProbatioVault-app
• Scope fichiers :
• ProbatioVault-app/src/sharing/screens/**
• ProbatioVault-app/src/sharing/components/**
• ProbatioVault-app/src/sharing/guards/**
• ProbatioVault-app/src/sharing/hooks/**
• ProbatioVault-app/src/proofs/screens/ProofDetailScreen.tsx (point d'intégration cross-module)

1. Objectif¶

Matérialiser les invariants sharing-ui de PD-299 :

• A2 / INV-299-03 : OwnershipGuard React component qui conditionne le rendu de ShareCTA à isValidUuid(ownerUserId) && isValidUuid(currentUser.id) && ownerUserId === currentUser.id. Aucun fallback "" pour currentUserId undefined (le CTA reste caché).
• A6 / INV-299-07 : useNetworkGuard hook fail-closed traitant netinfo_is_connected === null comme false. Tous les handlers sharing (onCreateShare, onRevokeShare) checkent ce hook avant émission.
• A7 / INV-299-08 : useSafeProofShares wrapper qui valide proofId (UUID v4 non vide) avant d'invoquer useProofShares. Les call-sites useProofShares(undefined) explicites sont éliminés.
• Exposition des interfaces du contrat : OwnershipGuard, ShareCTA, useNetworkGuard, useSafeProofShares, SharingError (re-export), ShareCreateScreen, ShareDetailScreen.
• Point d'intégration cross-module ProofDetailScreen qui matérialise la règle « ShareCTA n'est jamais monté sans passer par OwnershipGuard ».

2. Fichiers modifiés / créés¶

Aucun fichier hors périmètre files (voir §7 pour les signalements cross-module).

3. Conformité aux invariants contractuels¶

4. Conformité aux interdits contractuels¶

5. Interfaces exposées¶

Toutes listées dans sharing-ui.interfaces :

// guards/
export function OwnershipGuard(props: Readonly<OwnershipGuardProps>): JSX.Element;
export interface OwnershipGuardProps {
  readonly ownerUserId: UserId | undefined;
  readonly currentUserId: UserId | undefined;
  readonly children: React.ReactNode;
  readonly fallback?: React.ReactNode;
}

// components/
export function ShareCTA(props: Readonly<ShareCTAProps>): JSX.Element;
export interface ShareCTAProps {
  readonly onPress: () => void;
  readonly disabled?: boolean;
  readonly testID?: string;
}

// hooks/
export function useNetworkGuard(): NetworkGuardState;
export interface NetworkGuardState { readonly isConnected: boolean; readonly isReady: boolean; }
export function useSafeProofShares(
  proofId: ProofId | string | undefined | null,
): UseQueryResult<ShareListResponse, Error>;

// screens/
export { ShareCreateScreen, ShareDetailScreen } from "./screens";

// Re-export
export { SharingError } from "../errors"; // déjà exporté par sharing/index.ts (PD-299 sharing-telemetry)

6. Flux de propagation offline (F-299-06)¶

useNetworkGuard() ──► NetInfo.addEventListener + NetInfo.fetch()
        │
        ▼
  isConnected := (state.isConnected === true)   // null/undefined => false
        │
        ▼
  handler sharing (handleSubmit/handleRevoke)
        │
        ├─ isConnected === false ──► Alert.alert(t("offline.blockedTitle"), ...)
        │                         └─► throw new SharingError("SHARE_OFFLINE", {
        │                                 userMessage: "sharing.offline.blockedMessage",
        │                                 technicalDetail: "network unavailable for <action>"
        │                              })
        │
        └─ isConnected === true  ──► mutation.mutate(...)

7. Décisions architecturales (code contract)¶

DEC-UI-01 — currentUserId: UserId | undefined strict (pas de fallback "")¶

• Décision : les écrans sharing ne substituent JAMAIS une chaîne vide ou un placeholder à currentUserId absent. Le type reste UserId | undefined ; côté rendu, OwnershipGuard cache le CTA.
• Rationale : un placeholder ("current-user-placeholder" en PD-298) produirait une égalité accidentelle avec un ownerUserId fabriqué sur le même motif et ouvrirait un chemin d'accès non-propriétaire. Le fail-closed est plus sûr que la permissivité.
• Alternatives considérées :
• Extraire currentUser.id depuis AuthContext — rejeté car AuthContext est hors périmètre sharing-ui.files (src/context/** non listé) et n'expose pas encore l'identité utilisateur.
• Ajouter un prop currentUser à ShareCreateScreen — reporté : la navigation actuelle n'a pas de mécanisme pour propager l'identité par route params. Sera tranché avec l'extension de AuthContext (dépendance future).
• Trade-offs : le DRM warning ne se déclenche pas tant que currentUserId est undefined (dégradation acceptée : le DRM warning sera rétabli dès que l'identité est exposée via useAuth).

DEC-UI-02 — useNetworkGuard basé sur NetInfo.addEventListener + NetInfo.fetch¶

• Décision : double canal addEventListener (updates temps réel) + fetch (bootstrap immédiat) pour éviter le flash offline initial avant la première résolution.
• Rationale : sans fetch, isReady=false jusqu'au premier event, ce qui peut bloquer abusivement un submit légitime au montage.
• Alternatives considérées :
• fetch seul — rejeté : pas de mise à jour si le réseau change pendant la session.
• addEventListener seul — rejeté : fenêtre de flash initial où isConnected=false par défaut.
• Trade-offs : appel réseau initial supplémentaire (négligeable, NetInfo est cache côté OS).

DEC-UI-03 — useSafeProofShares délègue à useProofShares(undefined) si invalide¶

• Décision : le wrapper ne lève pas d'exception si proofId est invalide ; il transforme l'appel en useProofShares(undefined) qui est une query désactivée (enabled: !!proofId).
• Rationale : lever une exception au rendu casse l'écran et déclenche un crash. Une query désactivée est un état valide (data=undefined, isLoading=false).
• Alternatives considérées :
• Lever SharingError("HOOK_SKIPPED_INVALID_PROOF_ID") — rejeté : la gestion d'erreur dans un useQuery est complexe et amène à des re-render loops.
• Retourner un mock directement — rejeté : casse la compatibilité UseQueryResult.
• Trade-offs : un proofId invalide produit un état « pas de données » identique à un fetch réussi avec 0 items. Les call-sites doivent distinguer via validation amont si nécessaire.

8. Signalements cross-module et hors scope¶

9. Tests couverts / à couvrir par sharing-tests (Wave 2)¶

Cette livraison produit uniquement du code applicatif. Les 45 tests contractuels sont à la charge du module sharing-tests (agent dédié, Wave 2). Les points d'observation suivants sont prêts à être testés :

10. Vérifications exécutées¶

• npx tsc --noEmit : 0 erreur dans src/sharing/** et src/proofs/** (les 94 erreurs TypeScript présentes dans le repo sont toutes pré-existantes et hors scope sharing-ui : modules __tests__, crypto, context, screens/Auth, etc.).
• Périmètre de fichiers respecté : tous les fichiers modifiés/créés sont dans sharing-ui.files (contrat).
• Aucun console.log/console.error introduit dans src/sharing/guards, src/sharing/components, src/sharing/hooks, src/sharing/screens, src/proofs/screens.
• Aucun accès direct à auth_access_token ni interpolation Bearer côté UI.

11. Hypothèses et points de vigilance¶

• H-UI-01 (issue de DEC-UI-01) : AuthContext sera étendu pour exposer currentUser.id dans une story ultérieure. Jusque-là, currentUserId reste undefined côté sharing-ui et OwnershipGuard masque systématiquement le CTA. Impact utilisateur : le CTA « Partager » sur ProofDetailScreen n'est pas visible tant que la propriété n'est pas matérialisée — c'est le comportement fail-closed attendu par INV-299-03 mais qui peut surprendre en revue si le contexte n'est pas rappelé.
• H-UI-02 : ProofDetailScreen est livré comme fichier isolé (point d'intégration). Son wiring dans AppNavigator n'est pas fait ici (hors scope). Une story dédiée devra ajouter la route ProofDetail et injecter proofId, ownerUserId, currentUserId.
• H-UI-03 : les clés i18n offline.blockedTitle, offline.blockedMessage, proofDetail.title, shareCta.label sont référencées dans le code. L'ajout effectif dans les fichiers de ressources i18n est hors scope sharing-ui (module locales/** non listé). À couvrir en Wave 2 ou en agent dédié.
• H-UI-04 : useSafeProofShares délègue à useProofShares sans émettre de log pour le cas invalide. Le code d'erreur DEC-05 HOOK_SKIPPED_INVALID_PROOF_ID est défini dans sharing/errors/index.ts mais n'est pas loggué (rejet silencieux). Si la télémétrie de ces skips devient nécessaire, prévoir un flush via logShareEvent (nécessite clé allowlist, ce qui contredit INV-299-05 allowlist vide — à arbitrer).

12. Références¶

• Spec : docs/epics/workflow/PD-299-consolidation-pd298/PD-299-specification.md §4 (INV-299-03, 07, 08), §5.5 (F-299-02, F-299-06), §5.6 (contraintes inter-modules).
• Plan : docs/epics/workflow/PD-299-consolidation-pd298/PD-299-plan.md §1.1, §2.2, §2.6, §2ter, §6.1, §7.1, DEC-05/DEC-10.
• Code contracts : docs/epics/workflow/PD-299-consolidation-pd298/PD-299-code-contracts.yaml module sharing-ui.
• Tests : docs/epics/workflow/PD-299-consolidation-pd298/PD-299-tests.md TC-NOM-03/07/08, TC-ERR-02/07, TC-NEG-06.
• Classes d'erreur : ProbatioVault-app/src/sharing/errors/index.ts (livré par sharing-telemetry).
• Validation UUID : ProbatioVault-app/src/sharing/validation/index.ts (livré PD-298, validateUuidV4).