webscope-mcp 0.2.0__py3-none-any.whl

webscope_adaptadores/laravel.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Mapa de una pantalla o ruta del backend Laravel: endpoint, controlador, servicio, modelo y tabla, cruzado con las llamadas del frontend.
+
+Uso: python3 -I laravel.py <carpeta-backend> <carpeta-módulos-frontend> <módulo del front o fragmento de ruta API> [--obligatorios <captura>]
+Con `--obligatorios`, compara los campos que exige el backend en cada guardado de la captura con los que marca el formulario.
+Lee las rutas de `php artisan route:list --json` en el contenedor Docker (WEBSCOPE_CONTENEDOR o `proyecto.contenedor` del
+manifiesto); sin contenedor, o si no responde, las deduce de los archivos app/Modules/**/Routes/*.php.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import proyecto  # noqa: E402
+import vue_ts  # noqa: E402
+
+RECURSO = {"index": ("GET", ""), "store": ("POST", ""), "show": ("GET", "/{}"), "update": ("PUT", "/{}"), "destroy": ("DELETE", "/{}")}
+RUTA = re.compile(r"Route::(get|post|put|patch|delete|apiResource)\(\s*'([^']*)'\s*,\s*\[?\s*([\w\\]+)::class(?:\s*,\s*'(\w+)')?[^;]*;", re.S)
+PREFIJO = re.compile(r"Route::prefix\('([^']+)'\)[^;{]*?->group\(\s*function\s*\(\)\s*\{", re.S)
+
+
+def normaliza(uri):
+    """La dirección sin `api/`, sin `?`, sin `/` inicial y con cada parámetro como `{}`."""
+    return re.sub(r"\$\{[^}]*\}|\{[^}]*\}", "{}", uri.split("?")[0]).strip("/").removeprefix("api/")
+
+
+def rutas_artisan(contenedor):
+    """Rutas de `route:list --json` dentro del contenedor, o None si Docker o el contenedor no responden."""
+    try:
+        proc = subprocess.run(["docker", "exec", contenedor, "php", "artisan", "route:list", "--json"], capture_output=True, text=True,
+                              timeout=90, stdin=subprocess.DEVNULL)
+        filas = json.loads(proc.stdout)
+    except (OSError, subprocess.SubprocessError, ValueError):
+        return None
+    return [{"metodo": f["method"].split("|")[0], "uri": normaliza(f["uri"]), "accion": f["action"]}
+            for f in filas if "@" in f["action"] or "\\" in f["action"]]
+
+
+def rutas_archivos(backend):
+    """Rutas deducidas de Routes/*.php.
+
+    shortcut: parámetros de apiResource como `{}`, grupos solo con Route::prefix, `api/` supuesto; mejorar si hay rutas fuera de ese patrón.
+    """
+    rutas = []
+    for f in sorted((backend / "app/Modules").rglob("Routes/*.php")):
+        texto = f.read_text(errors="ignore")
+        usos = {m[1].split("\\")[-1]: m[1] for m in re.finditer(r"^use ([\w\\]+);", texto, re.M)}
+        tramos = []
+        for m in PREFIJO.finditer(texto):
+            nivel, j = 1, m.end()
+            while j < len(texto) and nivel:
+                nivel += (texto[j] == "{") - (texto[j] == "}")
+                j += 1
+            tramos.append((m.start(), j, m[1].strip("/")))
+        for m in RUTA.finditer(texto):
+            tipo, uri, clase, metodo = m[1], m[2].strip("/"), usos.get(m[3].split("\\")[-1], m[3]), m[4]
+            uri = "/".join([p for a, b, p in tramos if a < m.start() < b] + ([uri] if uri else []))
+            if tipo == "apiResource":
+                limite = re.search(r"->(only|except)\(\[([^\]]*)\]\)", m[0])
+                nombres = set(re.findall(r"'(\w+)'", limite[2])) if limite else set()
+                for nombre, (verbo, sufijo) in RECURSO.items():
+                    if not limite or (nombre in nombres) == (limite[1] == "only"):
+                        rutas.append({"metodo": verbo, "uri": normaliza(uri + sufijo), "accion": f"{clase}@{nombre}", "en": f"{f}"})
+            else:
+                rutas.append({"metodo": tipo.upper(), "uri": normaliza(uri), "accion": f"{clase}@{metodo or '__invoke'}", "en": f"{f}"})
+    return rutas
+
+
+def archivo_de(backend, clase):
+    """Ruta del archivo PHP de la clase `App\\...\\Nombre`, o None si no existe."""
+    ruta = backend / (clase.replace("App\\", "app/", 1).replace("\\", "/") + ".php")
+    return ruta if ruta.is_file() else None
+
+
+def tabla_de(modelo):
+    """Valor de `$table` en el archivo del modelo, o None."""
+    m = re.search(r"\$table\s*=\s*['\"]([^'\"]+)['\"]", modelo.read_text(errors="ignore"))
+    return m and m[1]
+
+
+def importa(archivo, carpeta):
+    """Clases importadas con `use` cuyo espacio de nombres contiene `\\carpeta\\`."""
+    return re.findall(rf"^use ([\w\\]*\\{carpeta}\\[\w\\]+)(?: as \w+)?;", archivo.read_text(errors="ignore"), re.M)
+
+
+REGLA = re.compile(r"""['"]([\w.*]+)['"]\s*=>\s*(\[[^\]]*\]|'[^']*'|"[^"]*")""")
+
+
+def requeridos(texto):
+    """Claves de primer nivel con la regla `required` (no `required_if` ni otras condicionales) en un texto de reglas."""
+    return [k for k, v in REGLA.findall(texto) if "." not in k and re.search(r"""['"|]required['"|]""", v)]
+
+
+def obligatorios_de(backend, accion):
+    """Claves obligatorias que valida `Clase@metodo`: las del Request tipado en la firma o las de `$request->validate([...])`."""
+    clase, _, metodo = accion.partition("@")
+    archivo = archivo_de(backend, clase)
+    if not archivo:
+        return None
+    texto = archivo.read_text(errors="ignore")
+    cuerpo = re.search(rf"function {metodo}\(([^)]*)\)(.*?)(?=\n\s*(?:public|protected|private) function|\Z)", texto, re.S)
+    if not cuerpo:
+        return None
+    tipo = re.search(r"(\w+Request)\s+\$\w+", cuerpo[1])
+    if tipo:
+        usada = re.search(rf"^use ([\w\\]+\\{tipo[1]});", texto, re.M)
+        req = archivo_de(backend, usada[1]) if usada else None
+        if req:
+            reglas = re.search(r"function rules\(.*?(?=\n\s*(?:public|protected|private) function|\Z)", req.read_text(errors="ignore"), re.S)
+            return requeridos(reglas[0] if reglas else "")
+    validar = re.search(r"validate\(\s*\[(.*?)\]\s*\)", cuerpo[2], re.S)
+    return requeridos(validar[1]) if validar else []
+
+
+def cruce_obligatorios(backend, rutas, captura):
+    """Compara, por cada guardado de la captura, los obligatorios del backend con los marcados en el formulario.
+
+    Empareja cada etiqueta con la clave del cuerpo enviado que lleva el mismo valor; lo que no empareja se dice, no se adivina."""
+    salida = []
+    for linea in Path(captura).read_text(errors="ignore").splitlines():
+        p = linea.split(" ")
+        if len(p) < 3 or p[0] not in ("POST", "PUT", "PATCH") or " f {" not in linea:
+            continue
+        uri = normaliza(p[2])
+        ruta = next((r for r in rutas if r["metodo"] == p[0] and re.fullmatch(re.escape(r["uri"]).replace(r"\{\}", r"[^/]+"), uri)), None)
+        if not ruta:
+            salida.append(f"{p[0]} {uri}: sin ruta en el backend")
+            continue
+        back = obligatorios_de(backend, ruta["accion"])
+        if back is None:
+            salida.append(f"{p[0]} {uri}: no encontré el método {ruta['accion']}")
+            continue
+        q = dict(re.findall(r"(\w+):\w+\((.*?)\)(?= \w+:|$)", linea.split(" q ", 1)[1].split(" r ", 1)[0])) if " q " in linea else {}
+        form = json.loads(linea.split(" f ", 1)[1])
+        clave = {}
+        for etiqueta, x in form.items():
+            iguales = [k for k, v in q.items() if x[1] not in (None, "") and str(v) == str(x[1])]
+            if len(iguales) == 1:
+                clave[etiqueta] = iguales[0]
+        en_form = {clave[e] for e, x in form.items() if e in clave and len(x) > 3 and x[3]}
+        salida.append(f"## {p[0]} {uri} ({ruta['accion'].split(chr(92))[-1]})")
+        salida.append("backend exige: " + (", ".join(back) or "nada"))
+        if any(len(x) < 4 for x in form.values()):
+            salida.append("captura sin la marca de obligatorio del formulario (hecha con un __f anterior): vuelve a capturar")
+            continue
+        salida += [f"❌ {k}: el backend lo exige y el formulario no lo marca" for k in back if k in clave.values() and k not in en_form]
+        salida += [f"❌ «{e}» ({clave[e]}): el formulario lo marca y el backend no lo exige" for e, x in form.items()
+                   if e in clave and len(x) > 3 and x[3] and clave[e] not in back]
+        salida += [f"sin emparejar: {k} (exigido, no lo vi en el formulario)" for k in back if k not in clave.values()]
+    return "\n".join(salida) or "la captura no tiene guardados con sección f (formulario)"
+
+
+def mapa(backend, front, consulta, rutas, origen, raiz):
+    """Texto del mapa para `consulta`: módulo del frontend (cruza sus llamadas con las rutas) o fragmento de dirección de la API."""
+    mf = vue_ts.cargado(front)
+    modulos = {n: m for n, m in mf.items() if consulta in n}
+    llamadas = {}
+    for nombre, m in mf.items():
+        for c in m["llamadas"]:
+            metodo, url, donde = re.match(r"(\w+) (.+?)  (\S+:\d+)$", c).groups()
+            llamadas.setdefault((metodo, normaliza(url)), []).append(f"{front.relative_to(raiz)}/{donde}")
+    salida = [f"Backend de «{consulta}»: de la ruta del front al endpoint (dirección de la API), controlador, servicio y tabla. Sigue: leer(controlador, método).",
+              f"rutas leídas de: {origen}"]
+    if modulos:
+        for n, m in modulos.items():
+            salida.append(f"## front {n}")
+            salida += [f"ruta {r['path']} -> {r['vista']}  {front.relative_to(raiz)}/{r.get('en', '?')}" for r in m["rutas"]]
+        pedidas = {normaliza(c.split(" ", 1)[1].rsplit("  ", 1)[0]) for m in modulos.values() for c in m["llamadas"]}
+        elegidas = [r for r in rutas if r["uri"] in pedidas]
+        sin_ruta = pedidas - {r["uri"] for r in elegidas}
+    else:
+        elegidas, sin_ruta = [r for r in rutas if consulta in r["uri"]], set()
+    controladores = {}
+    salida.append("## backend")
+    for r in elegidas:
+        clase, _, metodo = r["accion"].partition("@")
+        archivo = archivo_de(backend, clase)
+        linea = ""
+        if archivo:
+            controladores[clase] = archivo
+            n = next((i for i, l in enumerate(archivo.read_text(errors="ignore").splitlines(), 1) if re.search(rf"function {metodo}\(", l)), 0)
+            linea = f"  {archivo.relative_to(raiz)}:{n}"
+        cruce = ", ".join(llamadas.get((r["metodo"], r["uri"]), [])[:2])
+        salida.append(f"api {r['metodo']} {r['uri']} -> {clase.split(chr(92))[-1]}@{metodo}{linea}" + (f"  <- {cruce}" if cruce else ""))
+    salida += [f"api sin ruta en el backend: {u}" for u in sorted(sin_ruta)]
+    servicios, modelos = {}, {}
+    for archivo in controladores.values():
+        for s in importa(archivo, "Services"):
+            if (f := archivo_de(backend, s)):
+                servicios[s] = f
+        modelos.update({m: archivo_de(backend, m) for m in importa(archivo, "Models")})
+    for f in list(servicios.values()):
+        modelos.update({m: archivo_de(backend, m) for m in importa(f, "Models")})
+    salida += [f"servicio {f.relative_to(raiz)}" for f in servicios.values()]
+    salida += [f"modelo {f.relative_to(raiz)} -> tabla {tabla_de(f) or '?'}" for f in modelos.values() if f]
+    return "\n".join(salida) if elegidas or modulos else f"sin módulo ni ruta que contenga «{consulta}»"
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 4:
+        sys.exit(__doc__)
+    raiz = Path.cwd()
+    backend, front = Path(sys.argv[1]).resolve(), Path(sys.argv[2]).resolve()
+    contenedor = os.environ.get("WEBSCOPE_CONTENEDOR") or proyecto.config()["contenedor"]
+    rutas = rutas_artisan(contenedor) if contenedor else None
+    origen = "artisan route:list" if rutas else "archivos Routes/*.php (sin contenedor o Docker apagado)"
+    if "--obligatorios" in sys.argv:
+        print(cruce_obligatorios(backend, rutas or rutas_archivos(backend), sys.argv[sys.argv.index("--obligatorios") + 1]))
+        tablas = [l.rsplit(" ", 1)[1] for l in mapa(backend, front, sys.argv[3], rutas or rutas_archivos(backend), origen, raiz).splitlines()
+                  if l.startswith("modelo ") and not l.endswith(" ?")]
+        sys.exit(print("\n".join(f"limpieza: limpiar_zz {t} --prefijo <prefijo del pedido> (halla la columna sola)" for t in tablas)))
+    print(mapa(backend, front, sys.argv[3], rutas or rutas_archivos(backend), origen, raiz))

webscope_adaptadores/limpiar_zz.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Borra de la base las filas de prueba cuyo código empieza por `ZZ_`, con escritura controlada (proyectos Laravel).
+
+Uso: python3 -I limpiar_zz.py <tabla> [<columna>] [--prefijo ZZ_E2E] [--llave COL --hijas tabla.col,tabla.col] [--borrar]
+Sin columna, usa la única columna de texto que tenga filas con el prefijo (si son varias, pide la columna).
+Sin `--borrar` solo lista las filas (solo lectura). Con `--borrar` guarda las filas en `~/.cache/webscope/zz-respaldo/`,
+borra con el script `tinker` del manifiesto (`<script> <archivo.php> --commit`) únicamente si el número de filas es el mismo
+que mostró la lista, y vuelve a contar.
+Con `--llave` y `--hijas` también borra, en la misma transacción, las filas de cada tabla hija cuya columna tiene la llave
+de una fila padre encontrada (p. ej. lo que siembra crear una cotización).
+El prefijo debe empezar por `ZZ_` y tener al menos 2 caracteres más: filas ajenas como `ZZTAB1` nunca coinciden.
+"""
+import json
+import re
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import proyecto  # noqa: E402
+
+RESPALDO = Path.home() / ".cache" / "webscope" / "zz-respaldo"
+
+
+def validar(tabla, columna, prefijo):
+    """Lanza ValueError si la tabla, la columna o el prefijo no son seguros para armar la consulta."""
+    if not re.fullmatch(r"\w+", tabla) or not re.fullmatch(r"\w+", columna):
+        raise ValueError("tabla y columna: solo letras, dígitos y _")
+    if not re.fullmatch(r"ZZ_[A-Za-z0-9_]{2,}", prefijo):
+        raise ValueError("el prefijo debe ser ZZ_ más al menos 2 caracteres de letras, dígitos o _")
+
+
+def filas(tabla, columna, prefijo):
+    """Filas de la tabla cuyo `columna` empieza por `prefijo`, como lista de {columna: valor}."""
+    cols = [f[0] for f in proyecto.consulta(f"SHOW COLUMNS FROM {tabla}")]
+    datos = proyecto.consulta(f"SELECT * FROM {tabla} WHERE LEFT({columna}, {len(prefijo)}) = '{prefijo}'")
+    return [dict(zip(cols, (None if v == "\\N" else v for v in f))) for f in datos]
+
+
+def oculto(fila):
+    """La fila con `***` en las columnas de contraseñas, tokens y secretos (el respaldo las guarda completas)."""
+    return {k: "***" if v and re.search(r"pass|token|secret|clave", k, re.I) else v for k, v in fila.items()}
+
+
+def columnas_con_prefijo(tabla, prefijo):
+    """Columnas de texto de la tabla con alguna fila que empieza por `prefijo`."""
+    texto = [f[0] for f in proyecto.consulta(f"SHOW COLUMNS FROM {tabla}") if re.search(r"char|text", f[1], re.I)]
+    if not texto:
+        return []
+    sumas = ", ".join(f"SUM(LEFT(`{c}`, {len(prefijo)}) = '{prefijo}')" for c in texto)
+    cuentas = proyecto.consulta(f"SELECT {sumas} FROM {tabla}")[0]
+    return [c for c, n in zip(texto, cuentas) if n not in ("\\N", "0", "")]
+
+
+def validar_hijas(hijas, llaves):
+    """Lanza ValueError si una tabla.columna hija o un valor de llave no son seguros para armar la consulta."""
+    for h in hijas:
+        if not re.fullmatch(r"\w+\.\w+", h):
+            raise ValueError(f"hija `{h}`: debe ser tabla.columna")
+    for v in llaves:
+        if not re.fullmatch(r"[\w.+\-]+", v):
+            raise ValueError(f"llave `{v}`: solo letras, dígitos, _, ., + y -")
+
+
+def filas_hijas(hija, llaves):
+    """Filas de `tabla.columna` cuya columna está en `llaves`, como lista de {columna: valor}."""
+    tabla, col = hija.split(".")
+    cols = [f[0] for f in proyecto.consulta(f"SHOW COLUMNS FROM {tabla}")]
+    lista = ",".join(f"'{v}'" for v in llaves)
+    datos = proyecto.consulta(f"SELECT * FROM {tabla} WHERE {col} IN ({lista})")
+    return [dict(zip(cols, (None if v == "\\N" else v for v in f))) for f in datos]
+
+
+def script_php(tabla, columna, prefijo, esperadas, hijas=None):
+    """PHP para el script `tinker` del proyecto: borra las hijas y luego las filas con ese prefijo, y falla (rollback) si algún número no coincide.
+
+    `hijas` es {tabla.columna: (llaves, filas esperadas)}.
+    """
+    donde = f"->whereRaw('LEFT(`{columna}`, {len(prefijo)}) = ?', ['{prefijo}'])"
+    php = f"$db = {proyecto.config()['php_db']};\n$db->transaction(function () use ($db) {{\n"
+    db = "$db"
+    for hija, (llaves, n) in (hijas or {}).items():
+        t, c = hija.split(".")
+        lista = ", ".join(f"'{v}'" for v in llaves)
+        php += (f"$b = {db}->table('{t}')->whereIn('{c}', [{lista}])->delete();\n"
+                f"if ($b !== {int(n)}) throw new RuntimeException(\"{hija}: se esperaban {int(n)} y se borraron $b\");\n"
+                f"echo \"{hija}: borradas $b\" . PHP_EOL;\n")
+    php += (f"$n = {db}->table('{tabla}'){donde}->count();\n"
+            f"if ($n !== {int(esperadas)}) throw new RuntimeException(\"se esperaban {int(esperadas)} filas y hay $n\");\n"
+            f"$b = {db}->table('{tabla}'){donde}->delete();\n"
+            f"echo \"borradas $b filas\" . PHP_EOL;\n")
+    return php + "});\n"
+
+
+def main(argv):
+    """Lista las filas ZZ_ y, con --borrar, las respalda, las borra y comprueba que no queden."""
+    borrar = "--borrar" in argv
+    argv = [a for a in argv if a != "--borrar"]
+    prefijo = "ZZ_E2E"
+    if "--prefijo" in argv:
+        i = argv.index("--prefijo")
+        prefijo = argv[i + 1]
+        argv = argv[:i] + argv[i + 2:]
+    opc = {}
+    for nombre in ("--llave", "--hijas"):
+        if nombre in argv:
+            i = argv.index(nombre)
+            opc[nombre] = argv[i + 1]
+            argv = argv[:i] + argv[i + 2:]
+    if len(argv) not in (1, 2) or ("--hijas" in opc) != ("--llave" in opc):
+        print(__doc__, file=sys.stderr)
+        return 2
+    tabla, columna = (argv + [None])[:2]
+    try:
+        validar(tabla, columna or "x", prefijo)
+        if "--llave" in opc:
+            validar(tabla, opc["--llave"], prefijo)
+    except ValueError as e:
+        print(f"ERR {e}", file=sys.stderr)
+        return 2
+    if not proyecto.consulta(f"SHOW TABLES LIKE '{tabla}'"):
+        print(f"ERR la tabla {tabla} no existe: el nombre de la API no siempre es la tabla; "
+              "`mapa_back <módulo>` da la real en la línea «modelo … -> tabla …»", file=sys.stderr)
+        return 2
+    if columna is None:
+        cols = columnas_con_prefijo(tabla, prefijo)
+        if not cols:
+            print(f"{tabla}: ninguna columna de texto empieza por {prefijo}: 0 filas")
+            return 0
+        if len(cols) > 1:
+            print(f"ERR {tabla}: {prefijo} aparece en {', '.join(cols)}; pasa la columna", file=sys.stderr)
+            return 2
+        columna = cols[0]
+    encontradas = filas(tabla, columna, prefijo)
+    print(f"{tabla}.{columna} empieza por {prefijo}: {len(encontradas)} filas")
+    for f in encontradas:
+        print("  " + json.dumps(oculto(f), ensure_ascii=False))
+    hijas, respaldo = {}, {tabla: encontradas}
+    if "--hijas" in opc and encontradas:
+        llaves = sorted({str(f[opc["--llave"]]) for f in encontradas})
+        lista_hijas = opc["--hijas"].split(",")
+        try:
+            validar_hijas(lista_hijas, llaves)
+        except ValueError as e:
+            print(f"ERR {e}", file=sys.stderr)
+            return 2
+        for h in lista_hijas:
+            fh = filas_hijas(h, llaves)
+            hijas[h] = (llaves, len(fh))
+            respaldo[h] = fh
+            print(f"  hija {h} con {opc['--llave']} en {llaves}: {len(fh)} filas")
+    if not borrar or not encontradas:
+        print("Sin cambios." if not borrar else "Nada que borrar.")
+        return 0
+    if not proyecto.config()["tinker"]:
+        print("ERR el proyecto no define `tinker` en la sección `proyecto` del manifiesto")
+        return 1
+    RESPALDO.mkdir(parents=True, exist_ok=True)
+    archivo = RESPALDO / f"{tabla}-{time.strftime('%Y%m%d-%H%M%S')}.json"
+    archivo.write_text(json.dumps(respaldo if hijas else encontradas, ensure_ascii=False, indent=1))
+    with tempfile.NamedTemporaryFile("w", suffix=".php") as php:
+        php.write(script_php(tabla, columna, prefijo, len(encontradas), hijas))
+        php.flush()
+        p = subprocess.run([str(proyecto.RAIZ / proyecto.config()["tinker"]), php.name, "--commit"], capture_output=True, text=True)
+    print((p.stdout + p.stderr).strip()[-300:])
+    if p.returncode:
+        return 1
+    quedan = len(filas(tabla, columna, prefijo))
+    print(f"Respaldo: {archivo}. Quedan {quedan} filas.")
+    return 0 if quedan == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

webscope_adaptadores/payload_check.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""Cruza lo que la pantalla envía y recibe (captura de `e2e_chrome.py --detalle`) con el FormRequest, el Resource y la tabla del backend.
+
+Uso: python3 -I payload_check.py <captura.json> <Area/Modulo> <tabla> [--llave col1,col2]
+     python3 -I payload_check.py --foto <tabla> <valor1,valor2> --llave col1,col2   (foto de la fila antes de editar)
+Si la captura trae la sección `f` (campos del formulario, de `e2e_chrome --form`), marca lo que se puso y no viajó y, con
+foto previa, las columnas que cambiaron en la base sin que el usuario las editara.
+Con `--llave` (columnas que identifican la fila, en el orden de la ruta: `tipo,codigo`) lee la fila de la base tras cada
+POST/PUT/DELETE y la compara con lo enviado; corre el chequeo después de cada acción de la pantalla (`--detalle <desde>`)
+para ver el estado tras esa acción: la fila se compara con la última escritura de cada llave.
+La captura es la lista de intercambios {m: método, u: ruta, s: estado, q: cuerpo enviado, r: forma de la respuesta}.
+Imprime una línea por hallazgo (❌ rompe, ⚠️ riesgo de datos, ❓ revisar); lee la base en solo lectura con proyecto.consulta.
+"""
+import json
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import proyecto  # noqa: E402
+
+FOTOS = Path(tempfile.gettempdir()) / "webscope-fotos"
+
+
+def valor(texto):
+    """Convierte `tipo(valor)` de la captura en el valor de Python; `obj{...}` y `array3{...}` (claves de la primera fila) dan
+    un dict de claves; `array3` y `null` quedan como texto o None."""
+    m = re.fullmatch(r"(string|number|boolean)\((.*)\)", texto, re.S)
+    lista = re.fullmatch(r"array\d+\{(.*)\}", texto)
+    if texto.startswith("obj{") or lista:
+        return {k: None for k in (lista.group(1) if lista else texto[4:-1]).split(",") if k}
+    if not m:
+        return None if texto == "null" else texto
+    tipo, v = m.groups()
+    return v if tipo == "string" else (float(v) if "." in v else int(v)) if tipo == "number" else v == "true"
+
+
+def campos(texto):
+    """Pares campo -> valor de una sección `campo:tipo(valor) campo:tipo(valor)` de la captura; None si es `-`."""
+    if texto.strip() in ("", "-"):
+        return None
+    return {k: valor(v) for k, v in re.findall(r"(\w+):((?:string|number|boolean)\([^)]*\)|null|array\d+(?:\{[^}]*\})?|obj\{[^}]*\})", texto)}
+
+
+def leer_captura(texto):
+    """Intercambios de una captura: JSON, o una línea por petición `MÉTODO estado ruta q <campos> r <campos>`."""
+    if texto.lstrip().startswith("["):
+        return json.loads(texto)
+    salida = []
+    for linea in texto.strip().splitlines():
+        m = re.fullmatch(r"(\w+) (\w+) (\S+) q (.*?) r (.*?)(?: f (\{.*\}))?", linea.strip())
+        if m:
+            metodo, estado, ruta, q, r, f = m.groups()
+            x = {"m": metodo, "s": estado if estado == "ERR" else int(estado), "u": ruta, "q": campos(q), "r": campos(r)}
+            if f:
+                x["f"] = json.loads(f)
+            salida.append(x)
+    return salida
+
+
+def claves_recurso(php):
+    """Claves que devuelve un Resource: los nombres a la izquierda de `'clave' => $this->…`, con o sin cast `(float)`."""
+    return re.findall(r"'(\w+)'\s*=>\s*(?:\(\w+\)\s*)?\$this->", php)
+
+
+def comparar(intercambios, reglas, mapa, columnas, distintos, recurso):
+    """Líneas de hallazgo al cruzar los cuerpos enviados y las respuestas con reglas, columnas, valores en la tabla y Resource.
+
+    `columnas` es {columna: nullable}; `distintos` es {columna: valores que hoy tiene la tabla}.
+    """
+    sal = []
+    for x in intercambios:
+        nombre = f"{x['m']} {x['u']}"
+        if x["s"] == "ERR" or int(x["s"]) >= 400:
+            sal.append(f"❌ {nombre}: respondió {x['s']} con {json.dumps(x.get('r'), ensure_ascii=False)[:160]}")
+            continue
+        q = x.get("q")
+        if x["m"] in ("POST", "PUT", "PATCH") and isinstance(q, dict):
+            for k in q:
+                if k not in reglas:
+                    sal.append(f"❓ {nombre}: envía `{k}` y el FormRequest no tiene regla para ese campo")
+            for k, r in reglas.items():
+                if r["required"] and k not in q:
+                    sal.append(f"❌ {nombre}: falta `{k}`, obligatorio en el FormRequest")
+            for k, v in q.items():
+                r = reglas.get(k)
+                col = mapa.get(k)
+                if r and r["in"] and v not in r["in"]:
+                    sal.append(f"❌ {nombre}: `{k}`={v!r} no está en in:{','.join(r['in'])}")
+                if v == "" and col and columnas.get(col):
+                    sal.append(f"❓ {nombre}: `{k}` viaja como '' y la columna `{col}` admite NULL; queda '' en la base")
+                if r and r["max"] and isinstance(v, str) and len(v) > r["max"]:
+                    sal.append(f"❌ {nombre}: `{k}` mide {len(v)} y la regla permite {r['max']}")
+        if isinstance(x.get("r"), dict) and recurso:
+            obj = next((v for v in x["r"].values() if isinstance(v, dict)), None)
+            if obj is not None and set(obj) != set(recurso):
+                sal.append(f"❓ {nombre}: la respuesta trae {sorted(obj)} y el Resource declara {sorted(recurso)}")
+    for k, r in reglas.items():
+        col = mapa.get(k)
+        if r["in"] and col and distintos.get(col):
+            fuera = sorted(v for v in distintos[col] if v not in r["in"])
+            if fuera:
+                sal.append(f"⚠️ `{k}` acepta solo {','.join(r['in'])} y la tabla (`{col}`) tiene también {', '.join(map(repr, fuera))}: esas filas no se pueden guardar desde la pantalla")
+    return sal
+
+
+def elegir_request(q, candidatos):
+    """Nombre del FormRequest de `candidatos` ({nombre: reglas}) que cubre más claves de `q` y deja menos obligatorias sin enviar; None si `q` no trae claves."""
+    # shortcut: elige por claves, no por la ruta; resolver controlador→Request con mapa_back si dos Requests empatan.
+    if not isinstance(q, dict) or not q or not candidatos:
+        return None
+    mejor = max(sorted(candidatos), key=lambda n: (len(set(q) & set(candidatos[n])),
+                                                    -sum(r["required"] and k not in q for k, r in candidatos[n].items())))
+    return mejor if set(q) & set(candidatos[mejor]) else None
+
+
+def llave_de(x, llaves, inverso):
+    """Valores de la llave de la fila que tocó el intercambio: del cuerpo en POST, de los últimos segmentos de la ruta en PUT/PATCH/DELETE.
+
+    `llaves` son columnas, `inverso` es {campo: columna}; devuelve None si no se puede deducir.
+    """
+    if x["m"] == "POST":
+        campo = {c: f for f, c in inverso.items()}
+        q = x.get("q") or {}
+        valores = [q.get(campo.get(c)) for c in llaves]
+    else:
+        segmentos = x["u"].strip("/").split("/")
+        valores = segmentos[-len(llaves):] if len(segmentos) > len(llaves) else None
+    return None if not valores or any(v in (None, "") for v in valores) else [str(v) for v in valores]
+
+
+def comparar_fila(x, fila, inverso, estados):
+    """Hallazgos al comparar la fila leída de la base (`{columna: valor}`, None si no existe) con el intercambio `x`.
+
+    `estados` son las columnas de reglas `in:` (p. ej. status), que se muestran tras un DELETE.
+    """
+    nombre = f"{x['m']} {x['u']}"
+    if x["m"] == "DELETE":
+        if fila is None:
+            return [f"✅ {nombre}: la fila ya no está en la tabla (borrado duro)"]
+        visto = ", ".join(f"{c}={fila[c]!r}" for c in estados if c in fila)
+        return [f"❓ {nombre}: la fila sigue en la tabla ({visto or 'sin columna de estado conocida'}): borrado lógico, no queda limpia"]
+    if fila is None:
+        return [f"❌ {nombre}: respondió {x['s']} y la fila no existe en la tabla"]
+    sal = []
+    for campo, v in (x.get("q") or {}).items():
+        col = inverso.get(campo)
+        if col is None or col not in fila or isinstance(v, dict):
+            continue
+        guardado = fila[col]
+        if guardado is None and v == "":
+            sal.append(f"⚠️ {nombre}: `{campo}` envió '' y la base tiene NULL")
+        elif guardado is None or str(guardado) != str(v):
+            sal.append(f"❌ {nombre}: `{campo}` envió {v!r} y la base tiene {guardado!r}")
+    return sal or [f"✅ {nombre}: la fila en la base coincide con lo enviado"]
+
+
+def leer_fila(tabla, columnas, llaves, valores):
+    """Fila de `tabla` con esa llave como {columna: valor}; None si no existe. Valores restringidos a letras, dígitos, `_`, `.` y `-` antes de consultar."""
+    if not all(re.fullmatch(r"[\w.\-]+", v) for v in valores) or not all(re.fullmatch(r"\w+", c) for c in llaves):
+        return None
+    donde = " AND ".join(f"{c} = '{v}'" for c, v in zip(llaves, valores))
+    filas = proyecto.consulta(f"SELECT * FROM {tabla} WHERE {donde}")
+    return dict(zip(columnas, (None if v == "\\N" else v for v in filas[0]))) if filas else None
+
+
+def editados(x):
+    """Campos que el usuario cambió en el formulario: {etiqueta: valor después}, de la sección `f` ({etiqueta: [antes, después, visto]})."""
+    return {k: v[1] for k, v in (x.get("f") or {}).items() if v[1] not in (None, "") and v[0] != v[1]}
+
+
+def comparar_formulario(x):
+    """Hallazgos de lo que el usuario puso en el formulario y no viajó en el cuerpo enviado."""
+    q = x.get("q")
+    if not isinstance(q, dict):
+        return []
+    enviados = {str(v) for v in q.values() if v is not None}
+    return [f"❌ {x['m']} {x['u']}: en «{k}» pusiste {v!r} y no viajó en el cuerpo"
+            for k, v in editados(x).items() if str(v) not in enviados]
+
+
+def ruta_foto(tabla, valores):
+    """Archivo temporal con la foto de la fila de `tabla` y esa llave."""
+    return FOTOS / f"{tabla}-{'-'.join(valores)}.json"
+
+
+def cambios_sin_editar(antes, fila, inverso, x):
+    """Columnas del formulario que cambiaron en la base entre la foto `antes` y `fila` sin que el usuario las editara."""
+    puestos = {str(v) for v in editados(x).values()}
+    columnas = set(inverso.values())
+    return [f"⚠️ {x['m']} {x['u']}: `{c}` pasó de {antes[c]!r} a {fila[c]!r} y no lo editaste en el formulario"
+            for c in sorted(columnas & set(antes) & set(fila))
+            if str(antes[c]) != str(fila[c]) and str(fila[c]) not in puestos]
+
+
+def filas_finales(intercambios, llaves, inverso, columnas, tabla, estados):
+    """Hallazgos de fila para el último intercambio de escritura de cada llave; con foto previa y formulario, también lo que cambió sin editarse."""
+    ultimos = {}
+    for x in intercambios:
+        if x["m"] in ("POST", "PUT", "PATCH", "DELETE") and x["s"] != "ERR" and int(x["s"]) < 400:
+            v = llave_de(x, llaves, inverso)
+            if v:
+                ultimos[tuple(v)] = x
+    sal = []
+    for v, x in ultimos.items():
+        fila = leer_fila(tabla, list(columnas), llaves, v)
+        sal += comparar_fila(x, fila, inverso, estados)
+        foto = ruta_foto(tabla, v)
+        if fila and x["m"] in ("PUT", "PATCH") and x.get("f") and foto.exists():
+            sal += cambios_sin_editar(json.loads(foto.read_text()), fila, inverso, x)
+    return sal
+
+
+def main(argv):
+    """Carga la captura, lee reglas, Resource y tabla, e imprime los hallazgos."""
+    llaves = []
+    if "--llave" in argv:
+        i = argv.index("--llave")
+        llaves = argv[i + 1].split(",")
+        argv = argv[:i] + argv[i + 2:]
+    if argv[:1] == ["--foto"] and len(argv) == 3 and llaves:
+        tabla, valores = argv[1], argv[2].split(",")
+        columnas = [f[0] for f in proyecto.consulta(f"SHOW COLUMNS FROM {tabla}")] if re.fullmatch(r"\w+", tabla) else []
+        fila = leer_fila(tabla, columnas, llaves, valores) if columnas and len(valores) == len(llaves) else None
+        if fila is None:
+            print(f"❌ no hay fila en {tabla} con {llaves}={valores}")
+            return 1
+        FOTOS.mkdir(exist_ok=True)
+        ruta_foto(tabla, valores).write_text(json.dumps(fila, ensure_ascii=False))
+        print(f"Foto de {tabla} {valores} guardada ({len(fila)} columnas). Sigue: edita en la pantalla y corre payload_check con --llave.")
+        return 0
+    if len(argv) != 3:
+        print(__doc__, file=sys.stderr)
+        return 2
+    captura, modulo, tabla = argv
+    area, nombre = modulo.split("/")
+    base = proyecto.modulo(f"{area}/{nombre}")
+    carp = proyecto.config()["carpetas"]
+    candidatos = {p.stem: proyecto.reglas_back(p.read_text())
+                  for p in (base / carp["requests"]).glob("*Request.php") if "Filter" not in p.name}
+    servicios = "".join(p.read_text() for p in (base / carp["servicios"]).glob("*.php"))
+    inverso = {campo: col for col, campo in re.findall(r"'(\w+)'\s*=>\s*\$data\['(\w+)'\]", servicios)}
+    recurso = claves_recurso(next((base / carp["recursos"]).glob("*Resource.php")).read_text()) if (base / carp["recursos"]).exists() else []
+    columnas = {f[0]: f[2] == "YES" for f in proyecto.consulta(f"SHOW COLUMNS FROM {tabla}")}
+    intercambios = leer_captura(Path(captura).read_text())
+    grupos = {}
+    for x in intercambios:
+        grupos.setdefault(elegir_request(x.get("q"), candidatos), []).append(x)
+    lineas, estados = [], []
+    for nombre_req, xs in grupos.items():
+        reglas = candidatos.get(nombre_req, {})
+        distintos = {}
+        for k, r in reglas.items():
+            col = inverso.get(k)
+            if r["in"] and col:
+                distintos[col] = {f[0] for f in proyecto.consulta(f"SELECT DISTINCT {col} FROM {tabla}")}
+        lineas += comparar(xs, reglas, inverso, columnas, distintos, recurso)
+        estados += [inverso[k] for k, r in reglas.items() if r["in"] and k in inverso and inverso[k] not in estados]
+    for x in intercambios:
+        lineas += comparar_formulario(x)
+    if not inverso:
+        lineas.append("❓ no pude mapear campos a columnas (los Services no usan `'columna' => $data['campo']`): solo se revisó el FormRequest")
+    if llaves:
+        lineas += filas_finales(intercambios, llaves, inverso, columnas, tabla, estados)
+    print(f"Verificación de {tabla}: cruza la captura con {', '.join(sorted(n for n in grupos if n)) or 'ningún FormRequest'}, el Resource y las columnas. Sigue: revisar cada línea.")
+    print("\n".join(lineas) or "sin hallazgos")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))