rp-mapper

Créer un plan de mapping à partir du schéma source découvert en entités et structures de données Wix.

Purpose

Cette skill traduit les entités et champs sources en cibles Wix. Elle doit définir ce que devient chaque enregistrement source dans Wix, comment les champs se transforment, et où des schémas personnalisés ou des champs étendus sont requis.

Required inputs

migrations/<project>/source-schema.json
migrations/<project>/source-profile.md quand disponible
migrations/<project>/orchestration/checkpoints.json
migrations/<project>/orchestration/decisions.json
toute contrainte de modèle cible Wix fournie par l'utilisateur

Lisez uniquement ces artefacts canoniques par défaut. N'ingérez pas le dump de découverte brut (migrations/<project>/data/...) en bloc — il est spécifique à la plateforme et volumineux. À la place, quand le mapping d'une entité est ambigu, suivez le pointeur rawFile de cette entité dans source-schema.json pour ouvrir juste ce fichier brut à titre de vérification. Ignorez les entités dont inUse est false (annoncées par la source mais ne contenant aucun enregistrement).

Adapter-supplied hints in `sourceMeta`

Un adaptateur source peut pré-remplir une partie du mapping quand il reconnaît le format source. Deux clés sourceMeta portent cela, et les deux sont optionnelles — un schéma sans elles se mappe exactement comme avant :

sourceMeta.mappingHints[] ({ column, wixTarget, matchedAlias }) — un pré-remplissage consultatif, par ex. à partir d'un profil CSV de vendeur reconnu. Amorcez les entrées fieldMappings[] correspondantes à partir de celui-ci pour que l'utilisateur révise et corrige au lieu d'écrire à partir de zéro, et enregistrez decisionProvenance: source_platform_rule. Ce n'est jamais autoritaire : la propre liste de champs source gouverne toujours, et chaque hint passe toujours par le checkpoint de révision du mapping.
sourceMeta.drift.unmappedColumns[] — colonnes source réelles que le profil de l'adaptateur n'a pas reconnues. Chacune doit être explicitement mappée ou explicitement enregistrée comme ignorée ; les laisser non adressées est comment un profil obsolète se transforme en données silencieusement perdues.

En plus des artefacts de projet ci-dessus, consultez la ressource d'adaptateur pertinente groupée quand le mapping dépend d'un comportement de plateforme qui ne doit pas être deviné :

sémantique de lecture/entité côté source à partir de replatform/resources/rp-source-<platform>/SKILL.md
contraintes de cible Wix et comportement de domaine à partir de replatform/resources/rp-target-wix/SKILL.md
adéquation d'entité cible Wix à partir de replatform/resources/rp-target-wix/scripts/domain-knowledge.js

Traitez ces ressources d'adaptateur comme la source faisant autorité pour la connaissance de plateforme. Ne copiez pas les règles de comportement source/Wix dans le plan de mapping comme si elles en provenaient ; citez-les et appliquez-les là.

Deterministic first — resolve before you reason

N'écrivez pas les mappings de champs à la main quand un overlay de vendeur les connaît déjà. Exécutez d'abord le résolveur déterministe et laissez-le faire la jointure mécanique ; votre jugement n'est nécessaire que pour ce qu'il ne peut pas décider.

node scripts/resolve-mapping.js --fileset <migrations-root>/<project>/data/csv-discovery/fileset.json \
  --out <migrations-root>/<project>/mapping

Il joint trois entrées qui sont toutes déjà des données — l'ensemble d'en-tête réellement découvert, la columnMap de l'overlay du vendeur, et la lib/wix-target-spec.js de rp-target-wix — et écrit mapping/mapping-resolution.json plus mapping/mapping-residue.json. Le code de sortie 2 signifie bloqué : une entrée Wix requise est vide, ou un overlay nomme un champ canonique qui n'existe pas.

Ce qu'il décide, pour que vous ne le fassiez pas :

quelle colonne alimente quel champ canonique, et via quel alias (enregistré pour révision)
quelles colonnes rien ne réclame → residue.unmappedColumns
quelles colonnes mappées n'ont pas de foyer Wix, avec la raison déclarée → residue.unsupportedTargets
quelles entrées Wix requises rien n'alimente → residue.unfilledRequired (un bloqueur)
quelles entrées d'overlay référencent une colonne absente → overlayDrift (le profil est obsolète)
quelles entités arrivent par dérivation plutôt que par une colonne → derivedEntities, incluant requiresFaithfulnessLedgerEntry quand la taxonomie source est hiérarchique

Votre travail est residue, et seulement residue. Chaque entrée a besoin d'une décision explicite — mappez-la sur un champ canonique, ou enregistrez-la comme intentionnellement ignorée avec une raison. Laisser une entrée indécise est comment un overlay obsolète se transforme en données silencieusement perdues.

Deux règles gardent cela honnête :

La ligne d'en-tête lue au moment de la découverte est faisant autorité, pas l'overlay. Un overlay ne peut réclamer que les colonnes qui existent réellement ; une colonne qu'il ne connaît pas est surfacée, jamais abandonnée.
Quand vous résolvez une entrée de résidu que l'overlay aurait dû connaître, fixez l'overlay — rp-source-csv/vendors/<vendor>.json plus un fixture d'en-tête dans tests/fixtures/csv/headers/. C'est une édition de données sans changement de logique de skill, et cela signifie que la prochaine exécution la résout déterministiquement au lieu de demander à un modèle à nouveau. Une décision de mapping prise deux fois est une entrée d'overlay manquante.

Do not regenerate the payload builder

rp-target-wix/lib/wix-build.js transforme un enregistrement canonique en corps de création Wix Stores V3 déterministiquement, et lib/wix-target-spec.js déclare chaque champ, constante et piège sur lequel il dépend. Cette couche est indépendante du vendeur — Shopify, WooCommerce, Magento et BigCommerce convergent tous sur elle — donc la génération de code doit vendoriser et l'appeler, exactement comme le lecteur vendorise csv-parse.js. N'émettez pas un to-wix.js par projet re-dérivant des objets monétaires, la sanitisation de slug, les références de variant par nom de choix, ou le piège vide physicalProperties. Ceux-ci sont réglés, testés, et verrouillés par régression contre 220 payloads de deux imports vérifiés en direct (tests/mapping/wix-build-oracle-test.js).

La spec règle aussi la décision de prix unique qui récidive sur chaque vendeur : voir STORES_V3_TARGET.priceResolution. Une paire (regular, sale) est résolue en actualPrice/compareAtPrice de Wix, pas mappée champ-pour-champ — l'avoir à l'envers surcharge silencieusement chaque produit remisé.

Workflow

Lisez les artefacts de découverte source.
Exécutez le résolveur déterministe (ci-dessus) et lisez son résidu.
Identifiez les entités Wix cibles pour chaque entité source en utilisant d'abord le lecteur de connaissance de domaine. Commencez par sourceMeta.candidateTargetRefs[] quand la découverte l'a fourni ; sinon exécutez domain-knowledge.js resolve-source ; utilisez le raisonnement sémantique uniquement quand aucun candidat n'existe et enregistrez une confiance unverified.
Décidez uniquement le résidu du résolveur, puis définissez toutes les transformations et défauts restants.
Marquez les lacunes où les entités Wix natives sont insuffisantes — les unsupportedTargets du résolveur les nomment déjà avec raisons ; portez-les dans le registre de fidélité plutôt que de les redéclarer.
Identifiez les exigences pour les collections personnalisées, les champs étendus, les références, la gestion des médias, et la normalisation du contenu riche.
Sauvegardez le plan de mapping.
Écrivez un résumé de révision utilisateur concis après que le plan soit complet.
Pausez pour un checkpoint de révision du mapping avant que le travail de setup/génération de code en aval commence.

Artifacts to create or update

migrations/<project>/mapping/run.json
migrations/<project>/mapping/mapping-plan.json
migrations/<project>/mapping/entity-decisions/<entity>.json
migrations/<project>/mapping/llm-handoff.json
migrations/<project>/mapping/review/mapping-gaps.json
migrations/<project>/mapping/review/mapping-plan.md
migrations/<project>/mapping/review/mapping-summary.md
migrations/<project>/orchestration/checkpoints.json
migrations/<project>/orchestration/approvals.json

Minimum contents of the mapping plan

Incluez pour chaque entité source :

sémantique source dans ce projet, spécialement quand le nom d'entité est générique (comment, item, entry, record, media, user, etc.). Déclarez ce que l'entité contient réellement ici, basé sur les données découvertes, pas juste le nom de route.
entité ou collection Wix cible
targetRef, targetDomain, targetEntity, targetClassification, importReliability, preferredWrite, et knowledgeEvidence sélectionnés quand la décision utilise un enregistrement d'entité de domaine groupé
clé primaire et stratégie de déduplication
tableau de mapping de champs
règles de transformation
règles de validation
politique de préservation d'URL pour les entités routées publiques
questions non résolues
implications de setup pour la configuration côté Wix
politique des médias quand l'entité porte des médias : si seuls les médias référencés sont en scope, si la cible accepte les URLs externes directement, et si les médias doivent exister dans Wix avant create/update
safeModeReplacements[] quand le mode sûr est activé, listant chaque champ email ou téléphone mappé qui entre dans un payload Wix sortant. Écrivez le même tableau dans mapping/mapping-plan.json pour la décision d'entité et mapping/entity-decisions/<entity>.json.
une note visible par l'humain en mode sûr dans le markdown de révision chaque fois qu'une entité a safeModeReplacements[], pour que la couverture de remplacement email/téléphone soit visible sans ouvrir les artefacts JSON

Quand une entité source est générique ou surchargée, le plan de mapping doit nommer les sous-types concrets ou contextes d'utilisation qu'il a observés. Exemples :

comment : commentaires de post de blog, avis de produit, commentaires de page
item : articles de ligne de commande, articles de catalogue, lignes CMS
media : images héros de blog, ressources de galerie produit, fichiers téléchargeables

Ne laissez pas une étiquette d'entité générique inexpliquée si les données découvertes montrent plusieurs significations du monde réel.

Safe-mode contact replacement metadata

Le mode sûr est activé par défaut via config/wix.env sauf si l'utilisateur définit explicitement SAFE_MODE=false avant le mapping. Quand activé, les artefacts de mapping doivent émettre des métadonnées de canal de contact sémantique pour que les imports générés puissent remplacer les valeurs email et téléphone sortantes via du code d'écrivain partagé déterministe.

Pour chaque entité mappée, marquez les champs pour remplacement en mode sûr quand la preuve source, la connaissance de domaine cible Wix, la sémantique de champ cible, les mappings dirigés par l'utilisateur, les champs CMS/personnalisés, les champs étendus, les soumissions de formulaire, les métadonnées, ou les champs de plugin indiquent un canal de contact email ou téléphone.

Chaque entrée safeModeReplacements[] doit inclure :

{
  "kind": "email",
  "sourcePath": "billing.email",
  "targetPath": "billingInfo.email",
  "required": true,
  "reason": "source and target are email fields"
}

targetPath est relatif à l'objet façonné Wix ou corps de requête défini par la décision de mapping. Utilisez la grammaire de chemin en mode sûr partagée : champs d'objet (billingInfo.email, contact.email.email) et caractères génériques de tableau (lineItems[].buyerInfo.email, contact.additionalEmails[].email). Quand la même valeur source est copiée vers plusieurs champs Wix, listez chaque chemin cible.

Chargez les hints côté cible à partir des entrées safeModeContactFields[] d'entités rp-target-wix sélectionnées et fusionnez-les avec la preuve source et les décisions de mapping utilisateur. Si SAFE_MODE=false avant le mapping, ne requérez pas cette métadonnée pour l'exécution.

Cette métadonnée doit être surfacée dans à la fois les artefacts de mapping machine et humain :

écrivez safeModeReplacements[] dans mapping/mapping-plan.json
écrivez les mêmes safeModeReplacements[] dans mapping/entity-decisions/<entity>.json
rendez une ligne en mode sûr par entité dans mapping/review/mapping-plan.md
quand des remplacements existent, incluez une courte section Safe mode replacements dans mapping/review/mapping-summary.md listant les entités affectées et les chemins email/téléphone mappés

Ne laissez pas la couverture de remplacement de contact en mode sûr implicite dans les tableaux de champs ou seulement en JSON. Un relecteur doit pouvoir confirmer à partir du markdown de révision quels champs email/téléphone sortants seront remplacés en mode sûr.

Identity and deduplication rules

Soyez explicite à propos de la différence entre un source ID et un ID cible Wix.

Préservez l'source ID dans les artefacts de migration, le code généré, l'état de crosswalk local, et toute collection CMS optionnelle miroir nécessaire pour la traçabilité site-local.
Ne supposez pas que les IDs d'entité Wix natifs peuvent être assignés par le client ou préservés. Pour la plupart des APIs Wix, l'ID cible est assigné par le serveur.
Quand une cible est une entité Wix native dont l'ID ne peut pas être contrôlé par le client, le plan de mapping doit définir une stratégie de crosswalk local : crosswalkAuthority: "local", une crosswalkStrategy par entité, et une reconciliationStrategy utilisée pour dedupe, resume, et résolution de relation.
CMS ImportCrosswalk est optionnel. Utilisez cmsMirror: "none" | "download" | "upload" | "download-and-upload" pour le requérir explicitement. C'est un adaptateur de copie/seed pour les flux de site existant ou remise de référence, pas l'autorité de résumé requise.
Dites seulement qu'un ID est « préservé » quand la destination a réellement un champ contrôlé par le client qui stocke l'source ID. Sinon dites que l'source ID est suivi ou crosswalkié.

URL preservation policy

Pour chaque entité source en scope qui apparaît sur le site public, incluez une urlPolicy explicite dans mapping/mapping-plan.json et l'artefact pertinent mapping/entity-decisions/<entity>.json.

Champs urlPolicy minimum :

public : true pour les entités routées publiques ; false pour les entités intentionnellement en dehors de la préservation d'URL.
sourceBasePath : le chemin de base source observé, tel que /shop/products ; utilisez null seulement quand l'URL source ne peut pas être dérivée et enregistrez ce risque.
sourceSlugField : champ source tenant le slug, quand présent.
sourceUrlField : champ source tenant l'URL pleine/permalink, quand présent.
targetBasePath : chemin de base de destination Wix connu, ou null quand la sélection de route du website-builder est différée.
targetSlugField : champ slug cible planifié, quand applicable.
preserveBasePath : si la phase website-builder future devrait essayer de préserver le chemin de base source.
preserveSlug : si le code généré devrait préserver le slug source sauf si la validation cible ou la gestion de collision force un changement.
redirectMode : record-if-different, manual-review, ou none.

Si le même type d'entité source a plusieurs formes de route publique, enregistrez chaque classe de route observée séparément au lieu de deviner un chemin de base. Les slugs sont des données d'identité et SEO, mais la préservation du slug seul n'est pas la préservation d'URL ; l'intention de route/chemin de base doit être capturée comme donnée pour la phase website-builder future.

Les artefacts de révision du mapping doivent inclure une courte section URL preservation listant :

types d'entité publique avec chemins de base source
si les chemins de base doivent être préservés
entités dont la route cible est différée à la phase website-builder
risques connus de normalisation de slug, collision, route, ou redirection

Verifying Wix APIs

Confirmez les noms exacts d'entité/collection/champ Wix avant de mapper un champ source sur eux — ne forgez jamais une API Wix ou un nom de champ.

Quand le mapping dépend du comportement runtime Wix plutôt que juste des noms de champ, vérifiez et suivez le contrat rp-target-wix pertinent aussi bien. Les exemples incluent l'ordre de création, la gestion des tags natifs, les exigences d'assignement de catégorie, les prérequis des membres, et si un champ produit/média devrait être envoyé comme une URL externe pour l'ingestion côté Wix.

Pour l'adéquation d'entité, ne grepez pas ou collez des fichiers de domaine entiers dans le plan. Utilisez :

node skills/replatform/resources/rp-target-wix/scripts/domain-knowledge.js summarize-entities --refs <domain/entity,...>

Chargez les enregistrements d'entité complets uniquement pour les candidats sélectionnés qui affectent matériellement le projet actuel.

Vérifiez les valeurs enum, pas juste les noms : chaque Field.type que vous assignez doit être un vrai membre de l'enum Type Create Data Collection. (Piège courant : il n'y a pas de type SLUG — un slug mappe sur un champ TEXT. N'assignez jamais une valeur enum devinée et signalez-la unverified ; résolvez-la ou omettez-la.)
Si une surface d'outil Wix telle que Wix MCP est disponible dans le runtime, utilisez-la comme aide de vérification rapide pour les noms d'entité, champ, enum, app, et setup.
Si aucune surface d'outil Wix n'est disponible, appuyez-vous sur les contrats vérifiés de rp-target-wix plus la documentation Wix REST/SDK publiée et les noms conservateurs, connus comme bons. Marquez tout ce que vous n'aviez pas pu vérifier directement comme unverified dans le plan de mapping pour que le risque soit surfacé avant l'exécution.

Runtime policy

Résolvez les mappings ambigus en utilisant le défaut documenté, enregistrez la décision et rationale sous les artefacts de mapping machine et rendez-les dans mapping/review/mapping-plan.md, et continuez. Les forks de fidélité connus (par ex. les commentaires anonymisent vs. ignorent) devraient déjà être répondus par l'intake de soumission ; appliquez ces réponses plutôt que de re-demander. Si une entrée requise est vraiment manquante, surfacez-la comme un bloqueur plutôt que de silencieusement deviner.

Si le nom d'entité source est générique mais les données observées le disambiguïsent, enregistrez cette disambiguïsation explicitement dans les artefacts de mapping machine et le plan de révision. Ne forcez pas les étapes ultérieures à inférer ce que « comments », « items », ou des étiquettes tout aussi larges signifiaient dans cette migration spécifique.

Faithfulness ledger (detect lossiness here, early)

L'étape de mapping est où la perte de fidélité et les lacunes de couverture sont découvertes, donc c'est où elles doivent être enregistrées — pas au moment de l'exécution, qui est trop tard pour rien faire que de rapporter. Maintenez un registre de fidélité dans mapping/review/mapping-gaps.json et rendez-le dans mapping/review/mapping-plan.md, listant tout ce qui ne migrera pas proprement, incluant :

champs/relations aplatis ou abandonnés (par ex. hiérarchie → flat),
entités ignorées (par ex. PII gatée),
cibles sans primitif Wix vérifié — si Wix a une entité native, enregistrez que la génération de code doit utiliser un chemin REST natif unverified et notifiez l'équipe RePlatform à propos de l'écrivain manquant. Utilisez CMS seulement quand aucune entité Wix native adéquate n'existe, ou quand l'entité native est rejetée pour des raisons de fidélité/effet secondaire.

Déclencheur obligatoire — taxonomie source hiérarchique → cible Wix aplatie. Quand une entité source porte "hierarchical": true (ou toute auto-relation parent) dans source-schema.json et mappe sur une cible Wix aplatie telle que les catégories de Blog, vous devez écrire une entrée de registre de fidélité enregistrant que la hiérarchie parent/enfant est abandonnée à l'import (la cible catégorie Wix Blog est aplatie — elle n'a pas de relation parent/enfant). Ce n'est pas une discipline optionnelle : le drapeau existe précisément pour que l'avertissement soit basé sur les données. Ne mappez pas une telle taxonomie sans l'entrée de registre. (Si la hiérarchie doit être préservée, l'alternative est une taxonomie de collection CMS avec un champ de référence parent — notez ce compromis dans le registre à la place.)

Ce registre est la source à partir de laquelle le rapport du plan d'exécution tire pour surfacer « ce que nous ne ferons pas » à l'utilisateur avant consentement (rp-execute-import). Si ce n'est pas enregistré ici, l'utilisateur ne peut pas être averti là.

Chaque entité sélectionnée dont la connaissance de domaine inclut IMPORT_UNRELIABLE doit créer une entrée mapping/review/mapping-gaps.json avec la même chaîne de drapeau fixe, la targetRef sélectionnée, un résumé spécifique au projet, et l'action de repli ou révision choisie.

Default media scope

Par défaut, importez uniquement les médias référencés par des entités en scope telles que les posts, produits, collections, catégories, ou lignes CMS qui sont réellement migré. Le média de bibliothèque non attachée source est out of scope par défaut sauf si l'utilisateur demande explicitement une migration de bibliothèque/archive.

Quand une entité porte des médias, consultez rp-target-wix pour le comportement cible :

si la cible accepte les URLs externes et les ingère en arrière-plan, préférez ce chemin
sinon requérez l'import de médias dans Wix d'abord, puis attachez l'ID de média Wix résultant

Mapping summary for user review

Après que mapping/mapping-plan.json soit écrit, créez migrations/<project>/mapping/review/mapping-summary.md comme artefact de révision court pour l'utilisateur. Son but est de rendre la décision de mapping facile à réviser sans forcer l'utilisateur à travers le plan complet.

Le résumé devrait :

dire explicitement que les détails complets vivent dans mapping/review/mapping-plan.md
lister chaque entité source en scope et sa cible Wix planifiée
mettre en avant les lacunes principales, transformations lossy, entités ignorées, et chemins cibles unverified du registre de fidélité
résumer la préservation d'URL publique : chemins de base source, routes cible différées, et risques de slug ou redirection qui affectent l'approbation
mentionner les implications de setup les plus importantes que l'utilisateur devrait savoir maintenant (par exemple : apps Wix requises, collections CMS requises, miroir de crosswalk CMS optionnel, caveat de traçabilité des médias)
quand le mode sûr est activé et des remplacements existent, incluez un résumé court sur quelles entités ont des remplacements email/téléphone sortants et où ils s'appliquent
surfacez les questions non résolues seulement quand elles affectent matériellement si l'utilisateur devrait approuver le mapping

Gardez-le concis. L'utilisateur devrait pouvoir décider « oui, c'est la bonne forme de migration » à partir de ce fichier seul, puis consulter mapping/review/mapping-plan.md seulement quand il veut du détail.

Structure recommandée :

objectif d'une phrase / pointeur vers mapping/review/mapping-plan.md
Source -> Wix targets
URL preservation
Main gaps / lossiness
Important setup implications
Safe mode replacements quand applicable
Questions or risks to confirm

Ne redéclarez pas les tableaux de champs complets ou les règles de transformation détaillées ici sauf si un problème spécifique au niveau des champs est central à la décision d'approbation.

Mapping review checkpoint

Une fois que les deux artefacts de mapping existent, réinitialisez orchestration/approvals.json pour que mapping.status=pending, puis arrêtez et demandez à l'utilisateur de réviser migrations/<project>/mapping/review/mapping-summary.md. Le checkpoint devrait clarifier :

ceci est une révision sémantique de ce qui sera migré où
le détail technique complet reste dans mapping/review/mapping-plan.md
la découverte de setup en aval et la génération de code attendront l'acceptation

Ne procédez pas à rp-setup-discovery ou rp-import-codegen jusqu'à ce que l'utilisateur accepte ce checkpoint de révision du mapping, sauf si l'utilisateur demande explicitement de continuer provisoirement.

Guardrails

Ne collapez pas plusieurs concepts source dans un champ Wix sans documenter la perte de fidélité.
Appelez les données qui ne peuvent pas être migrées fidèlement — enregistrez-les dans le registre de fidélité ci-dessus.
Ne décrivez pas une entité source uniquement par une étiquette générique quand les données observées sont plus spécifiques ; nommez les sous-types concrets présents dans le projet.
Gardez les règles métier explicites pour que rp-import-codegen puisse les implémenter déterministiquement.
Ne devinez pas les noms de champ, enum, ou app Wix quand vous ne pouvez pas les vérifier. Marquez-les unverified et surfacez le risque avant l'exécution.