CRM_AGENTES_CARGA/docs/planes/T2026-08-046_prompt.md

Documento Prompt versionado — T2026-08-046.

Es el plan con el que trabajó la corrida SUNRISE del 2026-08-07, tal como estaba al arrancar. Se versiona para que las decisiones del código tengan su porqué a la vista sin depender de una carpeta de corrida.

Dos avisos para quien lo lea:

1. Está completo, pero esta corrida solo ejecutó las fases 5, 6 y 7 (las del repo del CRM). Las fases 1-4 son del backend de EFC y corren con su propio orquestador, desde EFC/SUNRISE/2026-08-07/. Al cerrar esta corrida todavía no estaban.
2. Un dato se sustituyó al versionar. El caso 3 de la tabla de pruebas de EFC traía un storage_token con forma de llave de pedimento real; aquí va como 00-00-0000-0000000. El caso prueba que un token con forma de pedimento real se rechace, así que el número concreto no aporta nada y no tiene por qué quedar versionado.

Lo que la corrida acabó decidiendo, y en qué se apartó de este plan, está en SUNRISE/2026-08-07/Diario-2026-08-07.md y en el reporte de la misma carpeta.

---

T2026-08-046 — Integración CRM Agentes de Carga ↔ EFC: expedientes y documentos

Plan de implementación asincrónica (documento Prompt del ticket). Productos: CRM Agentes de Carga + EFC 2.0 · Repos: CRM CRM_AGENTES_CARGA (backend y frontend) + EFC backend · Prioridad: NORMAL · Tipo: NUEVO REQUERIMIENTO · Rama: feature/T2026-08-046 en cada repo

Un solo ticket. Cruza dos productos con repos separados, así que lleva una rama y un PR por repo (Orquestacion.md §1: la unidad de trabajo es el ticket; el número de ramas es Σ tickets × repos que toca). El trabajo va en siete fases con dependencias duras — §7 manda el orden.

Nota de ejecución. EFC/SUNRISE/Orquestacion.md solo opera sobre backend, frontend y microservice de EFC. La copia de este ticket en EFC/SUNRISE/2026-08-07/T2026-08-046.md cubre las fases 1-4 y corre con ese orquestador. Las fases 5-7 son del repo del CRM y necesitan otra vía: la ventana nocturna de SUNRISE/VENTANA-NOCTURNA-AUTONOMA.md de este repo, o ejecución interactiva.

---

1. Contexto

Problema

El CRM de agentes de carga genera documentos —constancia fiscal, MBL/HBL/MAWB, factura comercial, packing list, PDF de factura— que hoy viven en su propio MinIO: sin expediente que los agrupe, sin catálogo validado en backend, y con un delete_document que hace soft delete y nunca borra el objeto (backend/api/v1/modules/crm/documents/service.py, función delete_document). EFC es el sistema de expedientes electrónicos de la casa y debe ser la fuente única de esos archivos.

El obstáculo estructural. En EFC el expediente es el Pedimento, y record.Document.pedimento es FK NOT NULL con llave de negocio pedimento_app = AA-XX-PPPP-NNNNNNN. El CRM no tiene ni un dato de pedimento: verificado que no existe ningún campo de aduana, patente, número ni año en los modelos de crm/ ni de ops/; ops.shipments solo tiene customs_agent_id (FK a crm.suppliers).

Y el CRM no tiene entidad expediente ni generador de folio. Verificado: las tres apariciones de "expediente" son herencia de plantilla —core/s3_keys.py tiene expediente_archivo_document_key y expediente_archivo_artifact_key con cero llamadores, y alembic/versions/9db46c604463_initial_schema.py crea la tabla huérfana a76.expediente_archivo sin modelo ni ruta—. reference en crm.service_requests, crm.quotes, ops.shipments y fin.invoices es String(40) nullable sin server_default, sin trigger y sin código que lo genere.

Qué se entrega

Un expediente en el CRM con folio EXP2026-08-001 generado al crear una solicitud, un pedimento provisional en EFC por cada uno, y un carril máquina-a-máquina que sube los documentos del CRM al expediente de EFC con reintentos, borrando la copia local al confirmar. Cuando llega la data aduanera real, el provisional se completa sin mover un solo archivo.

Resultado esperado

El usuario adjunta un MBL desde la ficha del embarque y lo ve aparecer con badge En expediente. Si EFC está caído, lo ve como Pendiente de enviar en vez de perder su trabajo, y el sistema lo entrega solo cuando EFC vuelve, sin duplicarlo. Un operador de EFC abre el expediente y ve el documento con fuente = APP-CRM.

Por qué el enlace va en una tabla desechable

Anexo22 es el sistema centralizado de pedimentos y EFC ya es su espejo (Pedimento.anexo22_pedimento_id). Está planeado que el CRM se conecte a Anexo22, y ese día los embarques del CRM se ligarán directo al pedimento de Anexo22. Por eso el acoplamiento vive todo en una tabla nueva (pedimento_expediente) y no se agrega ni una columna a pedimento: la tabla se dropea el día de la unión y no queda nada que migrar.

---

2. Decisiones cerradas — no re-abrir durante la implementación

Tema	Decisión	Por qué
Dónde vive el enlace	Tabla nueva pedimento_expediente en EFC. Cero columnas nuevas en pedimento	La tabla se dropea cuando el CRM se una a Anexo22; una columna obligaría a otra migración
Handle del CRM hacia EFC	folio + crm_expediente_id. Nunca pedimento_id ni pedimento_app	pedimento_app es mutable: se reescribe al completar. Mismo principio que el gateway de Anexo22, que "no guarda referencias de EFC"
Llave del provisional	storage_token = CRM-{company_id}-EXP{YYYY}-{MM}-{NNN}	Empieza con letras → imposible colisionar con ^\d{2}-\d{2}-\d{4}-\d{7}$. Y el company_id evita que dos companies del mismo tenant generen el mismo valor
Carpeta de MinIO	Se pasa siempre storage_token a save_document(), no pedimento.pedimento_app	El token es inmutable → ningún objeto se mueve nunca al completar
Escrituras sobre Pedimento	.update() de queryset, siempre	Ver H1: save() cuesta un sleep(4) síncrono
Autenticación del carril	Clon literal de HasAnexo22IntegrationApiKey con secreto propio CRM_INTEGRATION_API_KEY	Consistencia con el carril de referencia. La deuda (key sin binding a organización) se documenta, no se cierra aquí
Modo de entrega	Outbox + Celery, sin HTTP inline en el request	Es como funciona el gateway de Anexo22, y es lo que se pidió: "guarda temporal y reintenta en cola"
"Fuente única"	Vía delete_local: el objeto local se borra al confirmar la entrega	"Solo EFC" es el estado final (eventual), no el inmediato
Borrado en el CRM	Desasocia, no destruye en EFC	El gateway de Anexo22 nunca llama al DELETE de EFC. record.Document no tiene vigencia ni purga → la política implícita es conservar
Tipos de documento	Conjunto cerrado validado en ambos lados	En el CRM doc_type es texto libre sin validación de backend; un typo crearía basura en el catálogo global de EFC
Colisión al completar	409, no se fusiona	Es dato fiscal: un fallo visible es mejor que colgar documentos del pedimento equivocado
Ancla del expediente	La solicitud (crm.service_requests)	Un expediente por hilo comercial, de RFQ a factura, siguiendo la cadena que el CRM ya tiene
Descarga	Proxy con streaming en el CRM	EFC nunca entrega URL de MinIO: reescribir el host de una URL firmada invalida SigV4

Nomenclatura fija — se usa literal en todas las fases

Fuente en EFC .................. "APP-CRM"
storage_token .................. CRM-{company_id}-EXP{YYYY}-{MM}-{NNN}   ej. CRM-1-EXP2026-08-001
folio del CRM .................. EXP{YYYY}-{MM}-{NNN}                    ej. EXP2026-08-001
Pedimento.pedimento ............ el folio, sin prefijo                   ej. EXP2026-08-001
crm_document_ref ............... {TABLA}-{company_id}-{row_id}           ej. SHPDOC-1-4471, CRMDOC-1-903
                                 LEGACY-{tabla}-{id} para el backfill
                                 INVOICE-{company_id}-{invoice_id} para el PDF de factura
Prefijo de tipos en EFC ........ "CRM - "        ej. "CRM - MBL (Master Bill of Lading)"

Datos dummy — nunca reales

RFC XAXX010101000, pedimento 0000-0000000, patente 0000, aduana 000.

---

3. El carril de referencia: Anexo22 → EFC

Directriz. El carril CRM → EFC se construye clonando el carril Anexo22 → EFC que ya está en producción, con los nombres cambiados. No es una reinterpretación.

Ruta: C:\Users\USUARIO\Desktop\anexo 22\anexo22\backend\api\v1\modules\pedimentos\pedimento_gateway\

Archivo	Líneas	Qué se calca
client.py	269	EfcClient, EfcClientError(status_code, code, retryable), reintentos, backoff, corte en 4xx, mTLS, is_configured, transport inyectable
models.py	124	Las dos tablas de outbox, los estados, MAX_ATTEMPTS, delete_local
service.py	~1670	Enganche best-effort, entrega, _register_failure, _ya_entregado, ensure-then-upload, ops, reconciliación de huecos
tasks.py	171	Entrega inmediata + barridos + reconciliación
routes.py	52	Tablero de ops: listar, reintentar, métricas

Y el patrón de folio concurrente-seguro: catalogos/customs_brokers/folios.py + pedimentos/folio_validacion.py del mismo repo.

La máquina de reintentos, en sus tres capas — esto es lo que se clona

Capa 1, en el cliente HTTP. retries = 2 → 3 intentos. Backoff lineal time.sleep(0.15 * (attempt + 1)). 2xx éxito · >=500 con intentos restantes reintenta · 4xx NO reintenta y extrae code/message del cuerpo estructurado de EFC · TimeoutException/NetworkError reintenta y al agotarse lanza retryable=True · cualquier otra excepción retryable=False. El error lleva retryable para que el worker decida por el campo y nunca parseando strings, y code para ramificar.

Capa 2, en el worker.

def _register_failure(db, row, exc, retryable):
    row.attempts = (row.attempts or 0) + 1
    row.last_error = str(exc)[:2000]
    if (not retryable) or row.attempts >= MAX_ATTEMPTS:
        row.status = STATUS_FAILED
    db.commit()

deliver_row nunca lanza: captura EfcClientError y Exception y registra el fallo en la propia fila. Un fallo no mata al worker ni pierde la intención.

Capa 3, barridos de Celery beat. Cada 120 s para las dos tablas de outbox, 300 s para la reconciliación de huecos. Leen pending (limit 100, created_at ASC) sin contexto de tenant y re-despachan una tarea hija por fila con sus headers RLS.

Backoff de intervalo fijo, no exponencial. No hay autoretry_for, retry_backoff ni max_retries en las tareas: el reintento es el bucle de 0.15/0.30 s del cliente más el barrido de 120 s, hasta MAX_ATTEMPTS = 8.

Cuatro guardas de idempotencia. (1) _ya_entregado(source_table, source_id, kind) antes de encolar — EXISTS(status='sent'); su docstring en el original explica el defecto: sin ella, un reintento encolaba otra entrega que además falla al leer el objeto local porque la primera ya lo borró. (2) if row.status == STATUS_SENT: return al entrar a entregar. (3) Preguntar a EFC por crm_document_ref antes de subir. (4) El UniqueConstraint parcial del lado de EFC: una entrega repetida devuelve el documento que ya existía (200) en vez de crear otro (201).

Ensure-then-upload. Si el upload devuelve 404 expediente_no_encontrado, se crea el provisional y se reintenta el upload una vez. Resuelve la carrera entre la creación del expediente y la subida.

Corte directo (delete_local). Al confirmar, borra el objeto de MinIO local, envuelto en su propio try porque "ya está en EFC".

Best-effort en todo el enganche. if not settings.EFC_API_URL: return en cada punto de entrada; el encolado en try/except con rollback() y return None para que la integración nunca afecte la operación local; el despacho también best-effort — "si el broker no responde, el sweep la recoge".

---

4. Hallazgos verificados — las tres primeras corrompen datos fiscales

H1 — .update() obligatorio, nunca save(). En EFC/backend/api/customs/signals/procesamiento.py, el receptor trigger_celery_task_on_update tiene como única condición if not created: → cualquier save() sobre un Pedimento ejecuta un sleep(4) síncrono y encola procesamiento espurio. Anexo22PedimentoIngestView (buscar pedimento_obj.save() en api/customs/views_integrations_anexo22.py) sí lo hace. Es la única parte de Anexo22 que NO se clona.

H2 — trampa del rango VU 13-26. DocumentType.objects.get_or_create() deja al autoincrement asignar el id; si cae en 13-26, Document.save() marca vu=True (buscar 13 <= en api/record/models.py) y el documento entra en los borrados masivos de VU (api/record/views.py, acciones bulk-delete-partidas-vu, bulk-delete-coves-vu, bulk-delete-edocs-vu) → pérdida de archivo fiscal. Usar siempre _resolver_document_type de api/record/views_integrations_anexo22.py, que fuerza max(max(id)+1, 27) y avanza la secuencia con setval(). get_or_create para DocumentType está prohibido.

H3 — el provisional SÍ recibe checklist. En EFC/backend/core/cumplimiento_documental.py, buscar generales.get(org_id): sin clave_pedimento ni tipo_operacion_id la resolución cae al checklist TipoChecklist.TODOS. Si la organización tiene uno configurado, cada provisional publica un porcentaje bajo real en las 8 columnas cumplimiento_* de Pedimento — el modo de fallo que el autor del motor documentó y quiso evitar (buscar contamina reportes).

H4 — Anexo22 no propaga bajas a EFC hoy, pero Document.pedimento es CASCADE. El campo operacion se declara en Anexo22PedimentoIngestSerializer y nunca se lee en la vista; el cliente de Anexo22 no tiene método DELETE. Cuando esa propagación se construya, borrar un pedimento borraría los documentos del CRM en silencio. Por eso el enlace va con on_delete=PROTECT.

H5 — colisión de folio entre companies. El puente es Organizacion.hub_tenant_slug ↔ Tenant.slug, o sea tenant → organización 1:1, pero un tenant tiene N companies. Dos companies generando EXP2026-08-001 colisionarían en unique_together(organizacion, pedimento_app) y el get_or_create devolvería el provisional de la company A a la B. Por eso el company_id entra en el storage_token.

---

5. Contrato

5.1 EFC — carril máquina-a-máquina

Header obligatorio en todas: X-Api-Key: <CRM_INTEGRATION_API_KEY>.

GET    /api/v1/organization/integrations/crm/organizaciones/?q=texto
POST   /api/v1/organization/integrations/crm/organizaciones/resolver/
POST   /api/v1/customs/integrations/crm/expedientes/
POST   /api/v1/customs/integrations/crm/expedientes/{folio}/completar/
GET    /api/v1/customs/integrations/crm/expedientes/{folio}/
POST   /api/v1/record/integrations/crm/documentos/
GET    /api/v1/record/integrations/crm/documentos/list/
GET    /api/v1/record/integrations/crm/documentos/{uuid:pk}/descargar/
DELETE /api/v1/record/integrations/crm/documentos/{uuid:pk}/eliminar/
PUT    /api/v1/record/integrations/crm/documentos/{uuid:pk}/reemplazar/

Resolver organización — body A: {"tenant_slug": "temex", "tenant_name": "TEMEX"}; body B (alta manual): {"nombre": "...", "rfc": "XAXX010101000"}. Respuesta 200/201: {"id","nombre","rfc","hub_tenant_slug","is_active","created"}.

Crear expediente provisional — body:

{"crm_tenant_slug": "temex", "crm_company_id": 1, "crm_expediente_id": 42,
 "folio": "EXP2026-08-001", "storage_token": "CRM-1-EXP2026-08-001"}

201 (nuevo) / 200 (ya existía):

{"status": "created", "vucem": "no_aplica",
 "efc": {"pedimento_id": "<uuid>", "pedimento_app": "CRM-1-EXP2026-08-001",
         "storage_token": "CRM-1-EXP2026-08-001", "estado": "provisional",
         "consultar_vucem": false, "existe_expediente": false}}

Completar — body: {"crm_expediente_id": 42, "pedimento": {"numero_pedimento": "0000001", "aduana": "000", "patente": "0000", "anio": 2026, "clave_documento": "A1", "tipo_operacion": "IMP", "regimen": "IMD", "fecha_inicio": "...", "fecha_final": "...", "fecha_pago": "..."}, "importador": {"rfc": "XAXX010101000", "nombre_razon_social": "..."}, "agente_aduanal": {"rfc_agente": "...", "curp_apoderado": "..."}}. 200: {"status":"completed","efc":{"pedimento_id","pedimento_app","pedimento_app_anterior","consultar_vucem":false}}

Subir documento — parser_classes = [MultiPartParser], solo multipart, no base64. form-data: crm_company_id, crm_expediente_id, tipo, crm_document_ref, y file como archivo. 201 (nuevo) / 200 (idempotente) con _crm_doc_to_dict = _doc_to_dict + crm_document_ref.

Formato de error uniforme: {"error": {"code": "...", "message": "..."}}

Código	error.code	Cuándo
400	payload_invalido	serializer inválido
400	pedimento_app_reservado	el storage_token matchea ^\d{2}-\d{2}-\d{4}-\d{7}$
400	storage_token_invalido	más de 25 caracteres
400	efc_pedimento_app_incompleto	al completar falta aduana/patente/número/año
400	tipo_invalido, archivo_faltante, extension_no_permitida, archivo_demasiado_grande	validación de subida
400	espacio_insuficiente	cuota de licencia agotada
403	documento_no_eliminable	la fuente del documento no es APP-CRM
403	(sin cuerpo)	API key ausente, vacía o incorrecta
404	expediente_no_encontrado	dispara el ensure-then-upload del cliente
404	documento_no_encontrado	incluye el caso cross-organización: 404, no 403
409	organizacion_no_utilizable	is_active/is_verified en False
409	licencia_sin_espacio	licencia en 0 GB
409	expediente_ya_completado	el pedimento_app ya no empieza con CRM-
409	pedimento_real_ya_existe	+ {pedimento_id, pedimento_app, total_documentos} del existente
409	conflicto	carrera perdida en el IntegrityError
502	error_storage	save_document devolvió falsy

5.2 CRM — API de usuario

GET  /api/v1/crm/expedientes?company_id=1
GET  /api/v1/crm/expedientes/{id}?company_id=1
POST /api/v1/crm/expedientes/ensure?company_id=1
POST /api/v1/crm/expedientes/{expediente_id}/documentos?company_id=1
     multipart: file · form: doc_type, name?, target?, target_owner_id?
GET  /api/v1/crm/expedientes/{expediente_id}/documentos/{document_id}/archivo?company_id=1
GET  /api/v1/crm/expediente-gateway/outbox?tipo=&status=&limit=&company_id=1
POST /api/v1/crm/expediente-gateway/outbox/{outbox_id}/retry?company_id=1
GET  /api/v1/crm/expediente-gateway/metrics?company_id=1

Todos con company_id: int = Query(...) obligatorio y current_user: dict = Depends(get_current_user), como el resto del CRM.

POST documentos → 201 con {expediente_id, folio, document_id, doc_type, name, content_type, size_bytes, efc_sync_state, efc_document_ref}. Sin file_key ni file_url. 404 si el expediente no existe en ese tenant/company; 422 por doc_type, extensión o tamaño.

GET archivo → StreamingResponse con el Content-Type y el Content-Disposition de EFC. 404 si el documento no pertenece a ese tenant/company; 502 si EFC falla, salvo un 404 de EFC que pasa como 404.

retry → {"status":"requeued","id":<id>}; si la fila no existe para ese tenant/company → 404 con mensaje específico, no 200: es contrato con el frontend. metrics → {"pending","sent","failed"}.

Formato del folio: EXP{YYYY}-{MM}-{NNN}, consecutivo por (tenant, company, mes), que reinicia cada mes. Al pasar de 999 crece a 4 dígitos.

---

6. Fases

Cada fase es un bloque coherente y verificable. Las dependencias son de código, no de reloj.

#	Repo	Alcance	Depende de
1	EFC backend	Credencial X-Api-Key + resolver de organización	—
2	EFC backend	Tabla pedimento_expediente + provisional + completado	1
3	EFC backend	Endpoints de documentos + crm_document_ref	1, 2
4	EFC backend	Anti-contaminación: cumplimiento + grid	2
5	CRM backend	crm.expedientes + generador de folio	—
6	CRM backend	crm/expediente_gateway — clon del gateway de Anexo22	5
7	CRM back+front	Subida de un paso, proxy de descarga, UI	6

Si la fase 1 no queda mergeable, las fases 2, 3 y 4 no se empiezan y se registran como no ejecutadas con el motivo. Si la 2 no queda mergeable, tampoco la 3 ni la 4. La 4 no depende de la 3. Las fases 5-7 son de otro repo y no dependen de las de EFC para compilar: el gateway se desarrolla contra httpx.MockTransport sin EFC arriba. La 7 sí necesita la 6.

Colisión de archivos entre fases (para resolver el conflicto conservando los dos bloques al mergear): las fases 1 y 3 tocan EFC/backend/config/settings.py; las fases 2 y 4 usan EFC/backend/api/customs/models_crm.py; las fases 5, 6 y 7 tocan CRM/backend/tests/conftest.py y api/v1/modules/crm/router.py. Las fases 3 y 4 no comparten un solo archivo.

---

7. Compuertas previas — sin estas tres verdes, el carril no se habilita

No son código: son verificaciones que van al reporte.

1. Licencia. Licencia.almacenamiento en GB de la organización EFC destino. La licencia "Hub SSO Default" tiene 0 GB (api/organization/views_integrations.py, buscar el get_or_create de la licencia) → Document.save() lanza ValueError y falla el 100% de las subidas.
2. Visibilidad. Organizacion.is_active y is_verified en True. Con is_verified=False los cuatro mixins de backend/mixins/filtrado_organizacion.py (buscar is_verified) hacen la organización invisible incluso para superusuarios.
3. Tamaño. Hoy hay tres números desalineados: CRM 25 MB (crm/uploads/routes.py, MAX_UPLOAD_BYTES), nginx de producción client_max_body_size 100M (fuera de git), y Document.size es PositiveIntegerField (~2.1 GB). Elegir uno y aplicarlo en los tres lugares.

---

8. Fase 1 — EFC: credencial del carril y resolver de organización

8.1 Archivos nuevos

api/organization/views_integrations_crm.py — CrmOrganizacionSearchView (GET) y CrmOrganizacionResolverView (POST). Ambas con authentication_classes = [] y permission_classes = [HasCrmIntegrationApiKey].

Helper _asegurar_organizacion_visible_crm(org): fuerza is_verified=True y una licencia con almacenamiento > 0. NO toca apply_auto_download ni credenciales_desde_mve — el CRM no transporta e.firma y sus provisionales van con consultar_vucem=False.

Se clona views_integrations_anexo22.py de la misma app, no el de MVE: _asegurar_organizacion_visible_mve enciende además apply_auto_download=True y credenciales_desde_mve=True, que en el CRM no aplican.

_org_to_dict y _ensure_efc_organization se importan (de organization/views_integrations.py y cuser/sso_views.py), no se reescriben.

8.2 Archivos a modificar

Archivo	Qué cambia	Ancla de texto
core/permissions.py	Añadir HasCrmIntegrationApiKey	class HasAnexo22IntegrationApiKey — insertar después de esa clase completa
config/settings.py	CRM_INTEGRATION_API_KEY = os.getenv('CRM_INTEGRATION_API_KEY', '')	ANEXO22_INTEGRATION_API_KEY
.env.example (backend y raíz)	Declarar CRM_INTEGRATION_API_KEY= vacía	ANEXO22_INTEGRATION_API_KEY
api/organization/urls.py	2 paths explícitos, nunca en el router	integrations/anexo22/organizaciones

class HasCrmIntegrationApiKey(permissions.BasePermission):
    """Autenticación del carril CRM Agentes de Carga -> EFC (expedientes provisionales + documentos).

    Carril propio con su propio secreto: no se reusa el de MVE ni el de Anexo22 porque una key
    compartida hace imposible revocar un solo consumidor.

    INTERINA, igual que las de MVE y Anexo22: la key NO está ligada a una organización — el
    organizacion_id lo elige el llamador, así que una key da acceso a TODAS las organizaciones.
    Endurecer con require_permission('integration.crm_replicate') + mTLS terminado en nginx antes de
    producción. El scaffolding de mTLS ya existe del lado del cliente (EFC_MTLS_*), así que activarlo
    es configuración, no código.
    """
    message = 'API key inválida o no configurada.'

    def has_permission(self, request, view):
        from django.conf import settings
        expected = getattr(settings, 'CRM_INTEGRATION_API_KEY', '') or ''
        if not expected:
            # Fail-closed: sin secreto configurado no se atiende a nadie.
            return False
        provided = request.headers.get('X-Api-Key', '') or ''
        return hmac.compare_digest(provided, expected)

Migración: no agrega migración.

---

9. Fase 2 — EFC: tabla de enlace, provisional y completado

9.1 Archivos nuevos

api/customs/models_crm.py — precedente de archivo de modelos aparte: api/record/models_descargas.py.

class PedimentoExpediente(models.Model):
    """Enlace TEMPORAL entre un expediente del CRM de agentes de carga y su pedimento en EFC.

    ESTA TABLA ESTÁ DESTINADA A DESAPARECER. Existe solo mientras el CRM no esté conectado a
    Anexo22 —el sistema centralizado de pedimentos del que EFC ya es espejo vía
    Pedimento.anexo22_pedimento_id—. Cuando esa unión ocurra, Anexo22 creará el pedimento real, EFC lo
    replicará por su carril, este enlace repuntará `pedimento` y finalmente la tabla se dropea. Por eso
    el acoplamiento vive AQUÍ y no como columnas en `pedimento`: una columna en `pedimento` obligaría a
    otra migración el día del retiro.

    `pedimento` va con PROTECT y no con CASCADE: `record.Document.pedimento` es CASCADE, así que borrar
    el pedimento borraría los documentos que el CRM guardó. Hoy Anexo22 no propaga bajas a EFC (el campo
    `operacion` de su serializer de ingesta se declara y nunca se lee), pero cuando esa propagación se
    construya, un borrado silencioso se llevaría archivo fiscal. PROTECT hace que falle ruidosamente y
    obliga a repuntar o soltar el enlace primero, que es el orden correcto.

    `storage_token` es INMUTABLE: es la carpeta de MinIO. El carril del CRM lo pasa a
    storage_service.save_document() en lugar de `pedimento.pedimento_app` —que sí cambia al completar—,
    de modo que todos los objetos de un expediente viven bajo un solo prefijo para siempre y ninguno
    necesita moverse nunca.
    """
    pedimento = models.ForeignKey('customs.Pedimento', on_delete=models.PROTECT,
                                  related_name='enlace_crm')
    organizacion = models.ForeignKey('organization.Organizacion', on_delete=models.CASCADE,
                                     related_name='enlaces_crm')
    crm_expediente_id = models.IntegerField()
    folio = models.CharField(max_length=20)
    storage_token = models.CharField(max_length=25)
    crm_tenant_slug = models.CharField(max_length=100, blank=True, default='')
    crm_company_id = models.IntegerField()
    estado = models.CharField(max_length=20, default='provisional')  # provisional | completado
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        db_table = 'pedimento_expediente'
        constraints = [
            models.UniqueConstraint(fields=['organizacion', 'crm_company_id', 'crm_expediente_id'],
                                    name='uq_crm_link_org_company_exp'),
            models.UniqueConstraint(fields=['organizacion', 'folio'], name='uq_crm_link_org_folio'),
            models.UniqueConstraint(fields=['pedimento'], name='uq_crm_link_pedimento'),
        ]

api/customs/views_integrations_crm.py — CrmExpedienteProvisionalView, CrmExpedienteCompletarView, CrmExpedienteDetalleView.

Se importan de api/customs/views_integrations.py, no se reescriben: _err, _construir_pedimento_app, _ImportadorDataSerializer, _AgenteAduanalDataSerializer, _PedimentoDataSerializer.

_construir_pedimento_app se importa. Tiene tres implementaciones en la casa que deben coincidir (ésta, la del alta manual en api/customs/views.py, y la de api/datastage/tasks.py). Reimplementarla aquí sería la cuarta.

fecha_pago no existe en _PedimentoDataSerializer; se agrega por subclase para no tocar el serializer que usan MVE y Anexo22:

class _PedimentoCrmDataSerializer(_PedimentoDataSerializer):
    fecha_pago = serializers.DateField(required=False, allow_null=True)

Guarda de reserva, antes de cualquier escritura:

_RE_PEDIMENTO_REAL = re.compile(r'^\d{2}-\d{2}-\d{4}-\d{7}$')

# El carril del CRM NO PUEDE crear ni pisar un pedimento real por ningún bug. La llave real es todo
# dígitos con tres guiones; el provisional empieza con letras. Se rechaza explícitamente en vez de
# confiar en que el CRM mande bien el prefijo.
if _RE_PEDIMENTO_REAL.match(storage_token):
    return _err("pedimento_app_reservado", "...", status.HTTP_400_BAD_REQUEST)

Creación del provisional:

with transaction.atomic():
    pedimento_obj, created = Pedimento.objects.get_or_create(
        organizacion=organizacion,
        pedimento_app=storage_token,
        defaults={
            "pedimento": folio[:20],
            "numero_operacion": folio[:20],
            # OBLIGATORIO en False: trigger_celery_task_on_create
            # (api/customs/signals/procesamiento.py) retorna temprano si no está en True, así que
            # crear el provisional no dispara el pipeline VUCEM. El CRM no manda pedimentos a la
            # Ventanilla; EFC solo resguarda sus documentos.
            "consultar_vucem": False,
            # Cinturón: si algún save() futuro sobre esta fila disparara
            # trigger_celery_task_on_update, con estos dos en cero no encola remesa ni partida.
            "remesas": False,
            "numero_partidas": 0,
        },
    )
    PedimentoExpediente.objects.get_or_create(
        organizacion=organizacion, crm_company_id=..., crm_expediente_id=...,
        defaults={"pedimento": pedimento_obj, "folio": folio,
                  "storage_token": storage_token, "crm_tenant_slug": ...,
                  "estado": "provisional"},
    )

Si created es False, NO se hace pedimento_obj.save(). Cualquier ajuste va con Pedimento.objects.filter(pk=...).update(...).

Completado:

def _completar_pedimento_provisional(enlace, *, campos: dict, pedimento_app_nuevo: str):
    """Completa un provisional del carril CRM con la data aduanera real.

    Escribe SIEMPRE con .update() de queryset y NUNCA con .save(): el receptor
    trigger_celery_task_on_update (api/customs/signals/procesamiento.py) tiene como única condición
    `if not created:`, así que un save() ejecuta un sleep(4) SÍNCRONO dentro del request y encola
    procesamiento espurio. .update() no dispara señales.

    Los documentos ya subidos NO se tocan: la FK Document.pedimento no cambia. Y los objetos de MinIO
    NO se mueven, porque el carril del CRM guarda bajo `storage_token`, que es inmutable, y no bajo
    `pedimento_app`, que es lo que acaba de cambiar. Mover objetos exigiría una API de copia que
    storage_service no tiene, y un fallo a medias dejaría filas de Document apuntando a keys
    inexistentes: peor que un prefijo viejo.

    Devuelve (ok, codigo_error).
    """
    try:
        with transaction.atomic():
            Pedimento.objects.filter(pk=enlace.pedimento_id).update(
                pedimento_app=pedimento_app_nuevo, **campos)
            enlace.estado = 'completado'
            enlace.save(update_fields=['estado', 'updated_at'])
    except IntegrityError:
        # unique_together (organizacion, pedimento_app): ese pedimento REAL ya existe en EFC
        # (datastage/MVE/Anexo22 lo sembraron). Mover los documentos del provisional al real es una
        # fusión de datos fiscales y NO se hace en silencio.
        return False, "pedimento_real_ya_existe"
    return True, None

Después del .update(): llamar _recalcular_cumplimiento(enlace.pedimento_id) (importado de api/record/views.py) envuelto en try/except. Es necesario aquí: el checklist aplicable depende de clave_pedimento y tipo_operacion, que acaban de aparecer, así que la proyección cumplimiento_* quedó obsoleta.

Bitácora igual que Anexo22 (registrar_actividad / construir_cambios) dentro de try/except: pass con el comentario "la bitácora nunca debe interrumpir la ingesta".

9.2 Archivos a modificar

Archivo	Qué cambia	Ancla de texto
api/customs/models.py	Import de models_crm para que Django registre el modelo	fin del archivo
api/customs/urls.py	3 paths integrations/crm/expedientes/...	integrations/anexo22/pedimento

Migración: agrega migración de customs. Se genera con python manage.py makemigrations customs y se deja sin aplicar. Nombre esperado 0027_pedimentoexpediente. Verificar el número real con ls api/customs/migrations/, no asumirlo, y comprobar con makemigrations --check --dry-run que quede una sola hoja.

---

10. Fase 3 — EFC: endpoints de documentos

10.1 Archivos nuevos

api/record/views_integrations_crm.py — cinco vistas + _crm_doc_to_dict + _resolver_expediente + FUENTE_CRM + TIPOS_DOCUMENTO_CRM.

Se importan, no se copian:

from api.record.views_integrations import _doc_to_dict, _err, _resolver_pedimento
from api.record.views_integrations_anexo22 import _resolver_document_type
from api.record.views import _asignar_tipo_expediente, _recalcular_cumplimiento

_doc_to_dict no se modifica. Su propio comentario advierte que es el punto de serialización de dos integraciones que viven en otros repos y que los cambios deben ser aditivos. Se define _crm_doc_to_dict(doc) que lo llama y agrega crm_document_ref.

FUENTE_CRM = "APP-CRM"

# Conjunto CERRADO, a diferencia del carril Anexo22, que manda el tipo libre y deja que EFC lo resuelva
# por nombre. Ahí funciona porque sus 9 tipos son constantes de código; en el CRM `doc_type` es
# String(60)/String(30) SIN validación de backend —los catálogos viven solo en TypeScript— así que un
# typo crearía un DocumentType basura en el catálogo GLOBAL de EFC. El prefijo "CRM - " garantiza además
# que _resolver_document_type nunca choque con un nombre de MVE o de Anexo22, y que el id caiga en >= 27.
TIPOS_DOCUMENTO_CRM = {
    # --- crm.documents (DOC_TYPES de frontend/src/lib/api/crm/format.ts) ---
    "constancia_fiscal":     ("CRM - Constancia de Situación Fiscal", "Documento de cliente/proveedor del CRM"),
    "acta_constitutiva":     ("CRM - Acta Constitutiva", "..."),
    "identificacion":        ("CRM - Identificación Oficial", "..."),
    "comprobante_domicilio": ("CRM - Comprobante de Domicilio", "..."),
    "contrato":              ("CRM - Contrato", "..."),
    "presentacion":          ("CRM - Presentación Comercial", "..."),
    "certificacion":         ("CRM - Certificación", "..."),
    "licencia":              ("CRM - Licencia", "..."),
    "convenio":              ("CRM - Convenio", "..."),
    "tarifario":             ("CRM - Tarifario", "..."),
    # --- ops.shipment_documents (SHIPMENT_DOC_TYPES del mismo archivo) ---
    "MBL":  ("CRM - MBL (Master Bill of Lading)", "Documento de transporte del embarque"),
    "HBL":  ("CRM - HBL (House Bill of Lading)", "..."),
    "MAWB": ("CRM - MAWB (Master Air Waybill)", "..."),
    "HAWB": ("CRM - HAWB (House Air Waybill)", "..."),
    "CMR":  ("CRM - CMR (Carta Porte Internacional)", "..."),
    "factura_comercial":   ("CRM - Factura Comercial", "..."),
    "packing_list":        ("CRM - Packing List", "..."),
    "carta_encomienda":    ("CRM - Carta Encomienda", "..."),
    "carta_garantia":      ("CRM - Carta Garantía", "..."),
    "certificado_permiso": ("CRM - Certificado / Permiso", "..."),
    # --- fin.invoices ---
    "factura_venta": ("CRM - Factura de venta (PDF)", "PDF de factura generado por el CRM"),
    # --- 'otro' existe en AMBAS listas del CRM y significa lo mismo: una sola entrada ---
    "otro": ("CRM - Otro", "Documento sin tipo específico enviado desde el CRM"),
}

Orden no negociable del POST — las doce reglas de EFC, en el orden en que se aplican:

1. Validar tipo contra TIPOS_DOCUMENTO_CRM → 400 tipo_invalido. Validar extensión contra allowlist (.pdf .xml .png .jpg .jpeg .json .txt .zip .docx .xlsx) y file.size contra CRM_MAX_UPLOAD_BYTES. EFC hoy no tiene ni allowlist ni tope propio; el único freno real es la cuota de licencia.
2. _resolver_expediente(organizacion, crm_company_id, crm_expediente_id) → 404 expediente_no_encontrado.
3. _resolver_document_type(nombre, descripcion) — nunca get_or_create (H2).
4. Fuente.objects.get_or_create(nombre=FUENTE_CRM, ...).
5. Idempotencia ANTES de save_document(): Document.objects.filter(organizacion=org, crm_document_ref=ref).first() → 200 con ese documento. Comprobarlo aquí y no después es lo que evita el objeto huérfano en MinIO y que la cuota se cobre dos veces.
6. Cuota: UsoAlmacenamiento.objects.get_or_create(...); uso.espacio_utilizado + file.size > organizacion.licencia.almacenamiento * 1024**3 → 400 espacio_insuficiente.
7. storage_service.save_document(file=file, organizacion_id=org.id, pedimento_app=enlace.storage_token, metadata={"source": "crm", "crm_document_ref": ref}). Falsy → 502 error_storage.

   Se pasa enlace.storage_token, NO pedimento.pedimento_app. Es la única diferencia real con Anexo22 en esta llamada, y es lo que hace que ningún objeto tenga que moverse al completar.

8. Document.objects.create(..., nombre_original=file.name, size=file.size, extension=..., crm_document_ref=ref), envuelto en:
   • except ValueError → storage_service.delete_file(ruta) + 400 espacio_insuficiente. Document.save() revalida la cuota en su propia transacción y lanza ValueError; sin limpiar la ruta queda un objeto huérfano cobrando espacio.
   • except IntegrityError → delete_file(ruta), releer el que ganó la carrera → 200, o 409 conflicto.
9. _asignar_tipo_expediente(documento, organizacion.id). Devolverá False para los tipos del CRM (el mapa solo cubre los 7 legacy de sistema); se llama por consistencia y para no divergir si el mapa crece.

   _asignar_tipo_por_nomenclatura NO se llama — el carril Anexo22 tampoco lo hace. Si algún día se llama, recibe file.name y nunca la ruta guardada: el uuid4().hex[:8] que inyecta _generate_filename puede contener por azar una nomenclatura corta de letras hex.

10. _recalcular_cumplimiento(enlace.pedimento_id) en try/except — "el recálculo es una consecuencia de la operación, no parte de ella".
11. 201 con _crm_doc_to_dict.

DELETE: exige documento.fuente.nombre == FUENTE_CRM → si no, 403 documento_no_eliminable. Verifica que el documento pertenezca al pedimento del enlace. Captura la ruta y el pedimento_id antes del delete() (no hay post_delete sobre Document, a propósito), luego delete_file y _recalcular_cumplimiento. Cross-organización → 404, no 403: no filtrar existencia.

PUT reemplazar: clon fiel de Anexo22DocumentoReemplazarView, con las tres cosas que su código documenta:

• Cuota por delta: uso - (documento.size or 0) + file.size > max_bytes (Document.save() solo cobra la diferencia).
• Subir el nuevo ANTES de borrar el viejo. El precedente de api/record/views.py borra antes de subir y eso pierde archivo fiscal si la subida falla.
• Preservar vu, partida_id, cove_id, edocument_id con un .update() posterior si save() los movió: Document.save() recalcula vu y re-resuelve las FKs de sub-entidad por heurística de nombre vía resolver_fk.

GET descargar: streaming, con minio_client.abrir_objeto() y release_conn() en finally, siguiendo api/record/views_descargas.py.

No clonar el NamedTemporaryFile(delete=False) + atexit.register(unlink) de Anexo22DocumentoDescargarView: atexit corre al terminar el proceso, y bajo un worker de vida larga los temporales se acumulan hasta llenar disco.

No se clona Anexo22DocumentoAsignarIdView (el PATCH .../anexo22-id/): era una pasada de relleno histórica y el CRM no tiene nada que rellenar.

10.2 Archivos a modificar

Archivo	Qué cambia	Ancla de texto
api/record/models.py	Campo crm_document_ref + UniqueConstraint parcial en Meta.constraints	anexo22_document_id para el campo; document_anexo22_id_tipo_uniq para el constraint
api/record/urls.py	5 paths integrations/crm/documentos/...	integrations/anexo22/documentos
config/settings.py	CRM_MAX_UPLOAD_BYTES, CRM_ALLOWED_EXTENSIONS	CRM_INTEGRATION_API_KEY (lo dejó la fase 1)

crm_document_ref = models.CharField(
    max_length=64, null=True, blank=True, db_index=False,
    help_text="Handle del documento de origen en el CRM de agentes de carga",
)
# Es TEXTO y no un entero como anexo22_document_id porque el CRM tiene DOS tablas de documentos con
# secuencias independientes —crm.documents y ops.shipment_documents— más fin.invoices: un solo entero
# colisionaría entre ellas (crm.documents.id = 5 y ops.shipment_documents.id = 5 coexisten).
# Formato: {TABLA}-{company_id}-{row_id}.
#
# Es la CUARTA capa de idempotencia del carril, y la única que la base garantiza: la entrega del CRM la
# hace un worker con reintentos, así que un timeout ambiguo —EFC commiteó y contestó tarde— duplicaría
# el documento sin esto.
#
# db_index=False EXPLÍCITO: la tabla ronda los 5M de renglones. El índice único lo crea una migración
# aparte con CREATE INDEX CONCURRENTLY.

models.UniqueConstraint(
    fields=['organizacion', 'crm_document_ref'],
    condition=models.Q(crm_document_ref__isnull=False),
    name='document_crm_ref_uniq',
),
# Parcial como uq_organizacion_hub_tenant_slug_nonblank: las filas que no vienen del CRM comparten NULL
# y no deben colisionar entre sí. Sobre (organizacion, ref) y no sobre la ref sola porque toda lectura
# de este carril ya filtra por organizacion.

Migración: agrega dos migraciones de record, ambas generadas y sin aplicar:

1. 0015_document_crm_ref — solo el AddField con db_index=False y sin el constraint. En PostgreSQL ≥ 11 un ADD COLUMN nullable sin default volátil es metadata-only: no reescribe los 5M de renglones.
2. 0016_document_crm_ref_index — atomic = False, con SeparateDatabaseAndState: state_operations=[AddConstraint(...)] y database_operations=[RunSQL('CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS "document_crm_ref_uniq" ON "document" ("organizacion_id", "crm_document_ref") WHERE "crm_document_ref" IS NOT NULL;', reverse_sql=...)].

Precedente exacto a leer antes de escribirla: api/record/migrations/0004_document_subentidad_fk.py y 0005_document_subentidad_idx.py, incluido el IF NOT EXISTS para que el reintento sea idempotente y la nota de recuperación si un build queda INVALID.

No clonar 0008_document_anexo22_document_id.py: hizo el campo con db_index=True y el AddConstraint en la misma migración bloqueante sobre la tabla de 5M.

El reporte debe decir que la 0016 hay que medirla en dev antes de producción y que aplicarla es ventana de mantenimiento humana, no trabajo de la corrida.

---

11. Fase 4 — EFC: anti-contaminación de los provisionales

Todo derivado de pedimento_expediente, sin columnas nuevas en Pedimento. Cuando la tabla se dropee, estos tres cambios se retiran y no queda migración pendiente.

from django.db.models import Exists, OuterRef
from api.customs.models_crm import PedimentoExpediente

_ES_PROVISIONAL = Exists(
    PedimentoExpediente.objects.filter(pedimento=OuterRef('pk'), estado='provisional')
)

Archivo	Qué cambia	Ancla de texto
api/customs/cumplimiento.py	Si el pedimento es provisional, dejar las 8 columnas cumplimiento_* en NULL y salir	la función que hace el .update() de las columnas cumplimiento_
api/customs/views.py	ViewSetPedimento.get_queryset(): anotar y excluir provisionales salvo ?incluir_provisionales=true	class ViewSetPedimento → su get_queryset
api/customs/views.py	PedimentoFilter.Meta.fields += es_provisional, crm_expediente_folio	class PedimentoFilter
api/customs/serializers.py	PedimentoSerializer += los dos campos derivados (aditivo)	class PedimentoSerializer

Justificación para el docstring de la guarda de cumplimiento:

Un expediente provisional del CRM no tiene clave_pedimento ni tipo_operacion, así que no hay checklist
ADUANAL aplicable: publicar un porcentaje sería medir el vacío. porcentaje=None ya es el contrato del
motor para "nada aplicable" (core/cumplimiento_documental.py), así que todo lo de aguas abajo es
null-safe. Sin esta guarda el provisional cae al checklist TipoChecklist.TODOS de la organización y
emite un porcentaje bajo REAL que arrastra los reportes.

Un solo cambio cubre cuatro endpoints: verificado que list, export_excel, activo_fijo y export_excel_activo_fijo todos entran por self.get_queryset(). Importa porque PedimentoPagination.page_size es None y paginate_queryset devuelve None sin page_size, así que /pedimentos/ devuelve TODOS los pedimentos.

NO aplicar la exclusión a DescargaExpedienteViewSet ni a los tres bulk-delete-*-vu: reciben listas explícitas de ids y filtrar ahí sería incorrecto.

Los dos campos nuevos van fuera de ordering_fields y de search_fields, igual que las columnas cumplimiento_*.

Migración: no agrega migración.

---

12. Fase 5 — CRM: entidad expediente y generador de folio

12.1 Archivos nuevos

Módulo api/v1/modules/crm/expedientes/ con la convención rígida del repo: __init__.py, models.py, dto.py (Pydantic v2, Base/Create/Update/Response, ConfigDict(from_attributes=True)), service.py (funciones libres que reciben db, tenant_id, company_id), routes.py (APIRouter sin prefijo propio), folio.py, doc_types.py.

crm.expedientes (Base, TenantScopedMixin, TimestampMixin):

Campo	Tipo	Nota
id	Integer PK
folio	String(20) NOT NULL	EXP2026-08-001
period_year / period_month / sequence	Integer NOT NULL	folio descompuesto → el contador es un constraint real, no un parse de string
service_request_id	FK crm.service_requests.id nullable index	el ancla
account_id	FK crm.accounts.id nullable
status	String(20) NOT NULL server_default 'abierto'	abierto | completado | cerrado
efc_organizacion_id / efc_pedimento_id	String(36) nullable	espejo, no handle
efc_storage_token	String(25) nullable	inmutable una vez asignado
efc_link_state	String(20) NOT NULL server_default 'PENDING'	PENDING | LINKED | FAILED
efc_error_code String(60) / efc_error_detail Text	nullable	diagnóstico visible en la ficha, sin ir a logs
patente, aduana, numero_pedimento, anio, clave_pedimento, regimen, fecha_pago, rfc_importador, rfc_agente_aduanal		data aduanera real, se llena al completar
created_by / updated_by	String(64)

Constraints: uq_crm_expedientes_folio UNIQUE (tenant_id, company_id, folio) y uq_crm_expedientes_periodo_seq UNIQUE (tenant_id, company_id, period_year, period_month, sequence).

Es la red de seguridad: si el contador se corrompe, un folio duplicado falla ruidosamente en vez de mezclar dos expedientes.

class ExpedienteFolioCounter(Base) — expediente_folio_counters, schema crm, PK compuesta (tenant_id, company_id, period) con period String(7) ("2026-08"), y last_seq Integer NOT NULL default 0.

folio.py:

def next_folio(db: Session, tenant_id: int, company_id: int, on: date | None = None) -> tuple[str, int, int, int]:
    """Reserva el siguiente consecutivo del mes y devuelve (folio, year, month, sequence).

    Una sola sentencia atómica, sin read-modify-write: el INSERT ... ON CONFLICT DO UPDATE serializa
    sobre la fila de ese (tenant, company, mes) y devuelve el valor ya incrementado. Un
    `SELECT max(sequence)+1` es exactamente la carrera que hay que evitar, y un SELECT ... FOR UPDATE
    también sirve pero son dos viajes.

    NO hace commit: opera sobre la sesión que recibe, para que un fallo posterior en la creación del
    expediente pueda hacer rollback sin quemar el folio. Es la misma disciplina del asignador de folios
    de Anexo22 (catalogos/customs_brokers/folios.py): validar antes de tocar el contador, no commitear
    dentro del asignador, y fallar cerrado ante ambigüedad.

    Un rollback deja HUECO en la secuencia. Los huecos son aceptables; los duplicados no.
    """

INSERT INTO crm.expediente_folio_counters (tenant_id, company_id, period, last_seq)
VALUES (:t, :c, :p, 1)
ON CONFLICT (tenant_id, company_id, period)
DO UPDATE SET last_seq = crm.expediente_folio_counters.last_seq + 1
RETURNING last_seq

service.py — ensure_expediente_for_service_request(db, service_request_id, tenant_id, company_id, user_id=None) -> Expediente (idempotente), get_expediente, list_expedientes, complete_expediente.

doc_types.py — EFC_DOC_TYPES: frozenset[str] con exactamente las 22 claves de TIPOS_DOCUMENTO_CRM de la fase 3.

12.2 Archivos a modificar

Archivo	Qué cambia	Ancla de texto
api/v1/common/base_models.py	Añadir EfcDocumentRefMixin	class TenantScopedMixin — insertar después
api/v1/modules/crm/documents/models.py	Aplicar el mixin a Document	class Document(Base, TenantScopedMixin, TimestampMixin)
api/v1/modules/ops/shipments/models.py	Aplicar el mixin a ShipmentDocument	class ShipmentDocument
api/v1/modules/crm/service_requests/service.py	create_service_request y create_from_opportunity llaman a ensure_expediente_for_service_request en la misma transacción, antes del db.commit()	def create_service_request y def create_from_opportunity
api/v1/modules/crm/router.py	include_router del módulo nuevo	el include_router de documents
api/v1/modules/crm/permissions.py	Añadir la entidad expediente	la lista de entidades
tests/conftest.py	import api.v1.modules.crm.expedientes.models # noqa	los imports de modelos existentes

Sin la línea del conftest.py las tablas nuevas no entran a Base.metadata y los tests fallan de forma opaca.

EfcDocumentRefMixin — una sola definición para no duplicar diez columnas en dos tablas: expediente_id, efc_document_ref, efc_document_id, efc_sync_state, efc_synced_at, efc_error_code, efc_error_detail, efc_attempts, content_sha256.

"""Columnas del espejo de un documento en EFC. Se aplica a crm.documents y a ops.shipment_documents.

`efc_document_ref` es el handle AUTORITATIVO —el CRM lo construye y EFC lo guarda—; `efc_document_id`
es solo un CACHE de la resolución, recuperable por el endpoint de lista si se pierde. Es el mismo
principio que aplica el gateway de Anexo22: el sistema de origen conserva el registro de SU dato, y con
eso pide el archivo de vuelta, en lugar de guardar identificadores ajenos en columnas propias.

`efc_sync_state` es el estado del ESPEJO (lo que pinta la UI: badge, botón reintentar). La cola de
trabajo vive aparte, en crm.efc_file_outbox. No son redundantes: el outbox es indexable por
next_attempt_at y sobrevive a un borrado cuya fila ya no está.
"""

Migración: agrega migración de Alembic. down_revision = el head real, verificado con alembic heads, no asumido. Estilo idéntico a alembic/versions/d5e6f7a8b9c0_pdf_compliance.py: op.create_table(..., schema="crm"), op.add_column(..., schema=...), op.create_foreign_key(..., source_schema=, referent_schema=), y downgrade() completo en orden inverso.

backend/main.py corre alembic upgrade head al arrancar, así que en este repo no hay paso manual — pero tampoco se corre upgrade a mano en este ticket.

---

13. Fase 6 — CRM: expediente_gateway, clon del gateway de Anexo22

Leer completo antes de escribir una línea: C:\Users\USUARIO\Desktop\anexo 22\anexo22\backend\api\v1\modules\pedimentos\pedimento_gateway\.

13.1 core/efc_client.py — clon de client.py

Copiar prácticamente literal, cambiando las constantes de path a .../integrations/crm/.... Se conserva todo: EfcClientError(message, status_code, code, retryable); retries = 2; backoff 0.15 * (attempt + 1); el corte en 4xx; _parse_error_body; _filename_from_response; _client_kwargs() con mTLS opcional; is_configured; el parámetro transport: httpx.BaseTransport | None —existe para los tests, con httpx.MockTransport—; y la instancia módulo-global efc_client = EfcClient().

httpx.Client síncrono, no async, por la misma razón que el original documenta: el consumidor es el worker de Celery, en contexto sync. El único punto async es el proxy de descarga, que es la fase 7.

Métodos: resolve_organizacion, ingest_expediente, completar_expediente, upload_documento, list_documentos, replace_documento, download_documento. No se clona asignar_anexo22_id.

13.2 crm/expediente_gateway/models.py — las dos tablas

Mismos estados y mismo tope que el original: STATUS_PENDING/SENT/FAILED, MAX_ATTEMPTS = 8.

crm.efc_sync_outbox: kind String(20), payload JSON, expediente_ref Integer index, status String(10) server_default pending, attempts Integer server_default 0, last_error Text, sent_at, efc_pedimento_id String(36). Índices (status) y (kind, status).

crm.efc_file_outbox: kind String(30), s3_key String(1024), file_name String(255), content_type String(100), efc_tipo String(40), source_table String(30), source_id Integer, expediente_ref Integer NOT NULL index, delete_local Boolean server_default true, y el mismo ciclo de vida. Mismos índices.

source_table es un añadido necesario sobre el original. El CRM tiene dos tablas de documentos con secuencias independientes, así que source_id solo es ambiguo. Es el mismo problema que Anexo22 resolvió con _DESTINO_POR_KIND, y su comentario dice exactamente qué pasa si se ignora: un UPDATE con el id de otra tabla vacía la columna de un documento ajeno que tuviera ese mismo entero — daño en el dato de otro, sin un solo error visible. Un (kind, source_table) que no esté en el mapa no toca nada, en vez de caer por omisión.

delete_local es el mecanismo de "EFC es la fuente única". El archivo se guarda en el MinIO del CRM (durable), la fila del outbox referencia su s3_key, y al confirmar la entrega se borra la copia local. "Solo EFC" es el estado FINAL (eventual), no el inmediato.

13.3 crm/expediente_gateway/service.py

Tabla de equivalencias que va en el docstring del módulo, para que quien conozca un carril lea el otro:

Anexo22	CRM
replicate_pedimento_best_effort	replicate_expediente_best_effort
_enqueue_pedimento_outbox	_enqueue_expediente_outbox
_dispatch_delivery	igual
deliver_row / _deliver_pedimento	deliver_row / _deliver_expediente
_register_failure	idéntico
_ya_entregado(source_id, kind)	_ya_entregado(source_table, source_id, kind)
deliver_file_row	idéntico, incluidos ensure-then-upload y delete_local
_register_file_failure	idéntico
_resolve_org_id + _org_id_cache	igual — dict módulo-global, por worker, sin invalidación
list_outbox / retry_outbox_row / outbox_metrics	igual, para las dos tablas
find_pedimento_gaps	find_expediente_gaps

Ensure-then-upload, literal del original:

try:
    resp = client.upload_documento(...)
except EfcClientError as exc:
    if exc.status_code == 404 and exc.code == "expediente_no_encontrado":
        # La creación del provisional puede venir en camino: se asegura y se reintenta UNA vez.
        client.ingest_expediente({...})
        resp = client.upload_documento(...)
    else:
        raise

Corte directo, con su try propio:

if row.delete_local:
    try:
        from core.storage_s3 import delete_object_if_exists
        delete_object_if_exists(row.s3_key)
    except Exception:
        # Ya está en EFC: no poder borrar la copia local no invalida la entrega.
        logger.warning(...)

Simplificación legítima por ser mono-base: en Anexo22 el outbox se commitea aparte del pedimento (dos bases distintas), y ese doble-commit es justo lo que obligó a inventar sweep_pedimento_gaps. El CRM es mono-base, así que la fila del outbox va en la misma transacción que el expediente o el documento. find_expediente_gaps se conserva igual —cubre lo creado antes de activar la integración y cualquier crash— pero deja de ser el parche de una ventana estructural. Dejarlo escrito en el docstring, o el siguiente que lo lea va a creer que es redundante.

13.4 crm/expediente_gateway/tasks.py

Tarea	Beat
expediente_gateway.deliver_outbox_row	—
expediente_gateway.sweep_outbox	120 s
expediente_gateway.deliver_file_outbox_row	—
expediente_gateway.sweep_file_outbox	120 s
expediente_gateway.sweep_expediente_gaps	300 s, no-op si not settings.EFC_API_URL

Trampa de RLS — el detalle que más fácil se pasa por alto. core/celery_app.py del CRM materializa el contexto desde los headers rls_tenant_id/rls_company_id, que solo pone api/v1/modules/core/tasks_tracking/dispatch.py::track_and_dispatch. Por tanto:

• Las tareas por fila deben despacharse con esos headers. Conviene ir por track_and_dispatch, que además queda registrado en el TaskTracker.
• Los barridos corren sin contexto de tenant: leen los ids pendientes con una sesión sin scope y despachan una tarea hija por fila con sus propios headers. Si un barrido abriera una sesión con scope e iterara, o no ve nada o se salta el aislamiento.
• LicenseValidationMiddleware es fail-closed contra el Hub pero no corre en el worker: el outbox no debe asumir contexto de licencia.

13.5 crm/expediente_gateway/routes.py

APIRouter(prefix="/expediente-gateway", tags=["EFC Gateway (ops)"]), bajo /v1/crm. Auth normal del CRM, tenant del token, company_id del query. Los tres endpoints del contrato §5.2.

13.6 Archivos a modificar

Archivo	Qué cambia	Ancla de texto
core/config.py	Las 8 variables de EFC	el bloque de S3_ENDPOINT_URL — insertar después
core/celery_app.py	include del módulo + 3 entradas de beat_schedule	el include= y el beat_schedule
api/v1/modules/crm/router.py	include_router del gateway	el include_router que dejó la fase 5
.env.example	Las 8 variables, todas vacías	fin del archivo
docker-compose.prod.yml	Las 8 variables en api, worker y beat	los environment: de los tres servicios
tests/conftest.py	Import de los modelos del gateway	los imports que dejó la fase 5

Se reusan los nombres de variable que Anexo22 ya definió, no se inventan otros:

EFC_API_URL: str = ""
EFC_API_KEY: str = ""              # == CRM_INTEGRATION_API_KEY del lado de EFC
EFC_API_VERIFY_SSL: bool = True
EFC_API_TIMEOUT_MS: int = 8000     # metadatos: resolver, ingest, completar
EFC_UPLOAD_TIMEOUT_MS: int = 55000 # subidas
EFC_MTLS_CA_PATH: str = ""
EFC_MTLS_CERT_PATH: str = ""
EFC_MTLS_KEY_PATH: str = ""

EFC_API_URL pasa por el field_validator(mode="before") que ya sanea las otras URLs del repo.

EFC_UPLOAD_TIMEOUT_MS es un añadido necesario: los 8000 ms del original sirven para metadatos, no para un archivo de 25 MB. Y tiene que quedar por debajo del proxy_read_timeout del nginx de EFC: si el timeout del CRM es mayor, el CRM ve un 504 opaco y no sabe si el documento entró. Fallando primero del lado del CRM, el reintento con el mismo crm_document_ref es limpio.

Los tres servicios necesitan las variables: la entrega la hace el worker y el barrido el beat.

Migración: agrega migración de Alembic con las dos tablas de outbox. down_revision = la de la fase 5.

---

14. Fase 7 — CRM: subida de un paso, proxy de descarga y UI

14.1 Backend

Archivo	Qué cambia	Ancla de texto
api/v1/modules/crm/expedientes/routes.py	Los dos endpoints nuevos	el router de la fase 5
api/v1/modules/crm/expedientes/service.py	attach_document, stream_document, detach_document	las funciones de la fase 5
core/storage_s3.py	put_object_stream(key, fileobj, content_type), open_object_stream(key)	def put_object_bytes
core/s3_keys.py	expediente_document_key(...)	def csv_import_key
api/v1/modules/crm/uploads/routes.py	Arreglar el read-antes-de-validar; allowlist; acotar el chequeo de prefijo	MAX_UPLOAD_BYTES y prefix = f"tenants/
api/v1/modules/crm/documents/service.py	delete_document encola DETACH en vez de solo marcar deleted_at	def delete_document

Tres defectos preexistentes que esta fase corrige de paso:

1. POST /v1/crm/uploads hace await file.read() completo antes de validar el tamaño → un archivo de 2 GB se bufferiza en RAM antes del 422.
2. No hay allowlist de MIME ni de extensión, a diferencia del avatar y del centro de ayuda, que sí la tienen.
3. GET /v1/crm/uploads/url valida solo que la key empiece con tenants/{tid}/companies/{cid}/, lo que permite firmar una URL para cualquier objeto de esa company —fin-invoices/, certificates/, imports/csv/— con solo crm.access.

Secuencia del POST de documentos:

1. Escribir en streaming al MinIO del CRM contando bytes y abortando al superar el tope. Nunca await file.read().
2. Validar extensión/MIME contra la allowlist y doc_type contra doc_types.EFC_DOC_TYPES → 422.
3. Resolver el expediente (tenant/company/deleted_at IS NULL) → 404.
4. efc_document_ref = f"{TABLA}-{company_id}-{row_id}" una vez creada la fila.
5. En una transacción: crear la fila del documento (efc_sync_state='PENDING', file_key = la key local, content_sha256) y la fila de crm.efc_file_outbox con delete_local=True, previo _ya_entregado.
6. _dispatch_file_delivery(...) best-effort y responder 201.

Proxy de descarga:

# EFC nunca entrega una URL de MinIO: reescribir el host de una URL ya firmada invalida SigV4
# (documentado en api/customs/serializers.py de EFC). Así que el CRM hace de segundo proxy.
#
# Dos guardas, las mismas que los tests del proxy de Anexo22 fijan:
#  1. Validar la pertenencia ANTES de tocar EFC. Sin esto, un document_id coincidente leería el
#     expediente de otro tenant — y peor: el organizacion_id se deriva del expediente, así que el proxy
#     iría a preguntar a la organización de otro cliente.
#  2. Mandar el organizacion_id del expediente, para que la verificación de EFC también dispare.
#
# El AsyncClient se crea DENTRO del generador y se cierra en finally. Si se creara en un `async with`
# que cierra antes de que empiece el streaming, la respuesta muere a medias.
async def _iter_upstream(...):
    client = httpx.AsyncClient(...)
    try:
        async with client.stream("GET", url, headers=...) as upstream:
            ...
            async for chunk in upstream.aiter_bytes():
                yield chunk
    finally:
        await client.aclose()

Traducción de errores: EfcClientError → 502, salvo 404 que pasa como 404. La asimetría es deliberada y está fijada por test en Anexo22.

Borrado: delete_document marca deleted_at y encola op='DETACH'. No destruye en EFC.

El gateway de Anexo22 nunca llama al DELETE de EFC —verificado: no existe el método en su cliente—. record.Document en EFC no tiene vigencia ni purga, así que la política implícita del sistema es conservar, y un documento que mañana puede ser parte del expediente de un pedimento real es riesgo de retención fiscal.

Migración: no agrega migración (las columnas las dejó la fase 5).

14.2 Frontend — frontend/

Archivos nuevos: src/lib/api/expedientes.ts (list, get, ensure, uploadExpedienteDocument, expedienteDocBlob, retrySync) y src/lib/components/ops/ExpedienteDocuments.svelte (tabla con badge de efc_sync_state, botón de reintento, modal de alta). SvelteKit 5 con runes.

Archivo	Qué cambia	Ancla de texto
src/lib/api/uploads.ts	Añadir las funciones nuevas. uploadFile y uploadUrl se conservan para lo legacy y para facturas	export async function uploadFile
src/lib/components/crm/RelatedManager.svelte	onFilePicked y openDoc se ramifican por efc_document_id con fallback a file_key; badge y reintento en la tabla; deshabilitar "URL externa" para documentos de expediente	async function onFilePicked, async function openDoc, y el campo de URL externa del modal
src/routes/dashboard/ops/embarques/[id]/+page.svelte	Usar ExpedienteDocuments	onFilePicked y openDoc de esa página
src/lib/api/crm/types.ts y el de ops	expediente_id, efc_document_id, efc_sync_state opcionales	las interfaces Document y ShipmentDocument

window.open(url, '_blank', 'noopener') no lleva el header Authorization. Para documentos de expediente hay que usar fetch → blob → URL.createObjectURL, con el api.getBlob que ya existe en src/lib/api.ts. Bufferiza en memoria del navegador, no del servidor; para archivos muy grandes habrá que migrar a un token firmado en el query string, y eso es otro ticket.

Barra de progreso: src/lib/api.ts ya tiene CsvFormDataUploadOptions con onProgress, pero uploads.ts usa api.request plano. Reusar esa opción.

DOC_TYPES y SHIPMENT_DOC_TYPES de src/lib/api/crm/format.ts no cambian: son la fuente del mapeo, y ahora el backend los valida.

14.3 Textos (es-MX) — fuente única

Situación	Texto exacto
Badge PENDING	Pendiente de enviar
Badge SYNCED	En expediente
Badge FAILED	No se pudo enviar
Botón de reintento	Reintentar envío
Tooltip del badge FAILED	El documento está guardado, pero todavía no llegó al expediente electrónico. Vuelve a intentarlo o avisa a soporte.
Error de doc_type inválido	Ese tipo de documento no está en el catálogo.
Error de extensión	Ese tipo de archivo no está permitido.
Error de tamaño	El archivo excede el tamaño máximo permitido.
Error del proxy de descarga	No se pudo obtener el archivo del expediente electrónico.
Modal de alta, título	Nuevo documento del expediente

---

15. Verificación

15.1 Tests automatizados — EFC (cd backend && python manage.py test)

api/organization/tests_integrations_crm.py

#	Caso	Qué prueba
1	Sin header X-Api-Key	403
2	CRM_INTEGRATION_API_KEY = '' y header vacío	403 — el fail-closed
3	Key incorrecta	403
4	Resolver tenant_slug nuevo	201, is_verified=True, licencia con almacenamiento > 0
5	Resolver dos veces	200 la segunda, mismo id
6	Organización con is_verified=False	queda en True (auto-reparador)
7	Resolver	NO enciende credenciales_desde_mve ni apply_auto_download

api/customs/tests_integrations_crm.py

#	Caso	Qué prueba
1	Crear provisional	201; consultar_vucem is False; pedimento == folio; numero_operacion == folio
2	Crear dos veces el mismo crm_expediente_id	200, mismo pedimento_id, un solo enlace
3	storage_token = "00-00-0000-0000000"	400 pedimento_app_reservado, cero filas
4	storage_token de 26 caracteres	400 storage_token_invalido
5	Crear	procesar_pedimento_completo_individual.apply_async no se llama (patch)
6	Re-crear	api.customs.signals.procesamiento.sleep NO se llama ← la prueba de H1
7	Completar	pedimento_app cambió, datos poblados, estado == 'completado', consultar_vucem sigue en False
8	Completar	sleep, crear_procesamiento_remesa y crear_procesamiento_partida no se llaman
9	Completar hacia un pedimento_app que ya existe	409 pedimento_real_ya_existe, provisional intacto
10	Completar uno ya completado	409 expediente_ya_completado
11	Completar sin aduana	400 efc_pedimento_app_incompleto
12	is_verified=False	409 organizacion_no_utilizable
13	Licencia en 0 GB	409 licencia_sin_espacio
14	Pedimento.delete() con enlace vivo	ProtectedError ← la prueba de H4

api/record/tests_integrations_crm.py

#	Caso	Qué prueba
1	POST multipart válido	201; nombre_original == file.name; fuente.nombre == "APP-CRM"
2	POST	document_type.id >= 27 y documento.vu is False ← el test de H2, el de mayor valor del ticket
3	DocumentType sembrado con pocas filas	el id asignado no cae en 13..26
4	El documento creado	no aparece en el queryset de los tres bulk-delete-*-vu
5	POST	el objeto queda bajo el prefijo del storage_token, no del pedimento_app
6	Dos POST con el mismo crm_document_ref	el segundo es 200 con el mismo id; la cuota no creció; save_document no se llamó
7	Cuota agotada	400 espacio_insuficiente y sin huérfano: delete_file llamado
8	ValueError desde Document.save()	igual que 7
9	crm_expediente_id inexistente	404 expediente_no_encontrado
10	tipo fuera del catálogo	400 tipo_invalido, cero filas
11	Extensión .exe	400 extension_no_permitida
12	DELETE de un documento APP-MVE	403, intacto
13	DELETE de un documento VU	403, intacto
14	DELETE / descargar / listar de otra organización	404, no 403
15	PUT reemplazar, subida falla	el anterior sigue descargable
16	PUT reemplazar, éxito	save_document antes de delete_file; vu/FKs preservadas
17	Alta y baja	_recalcular_cumplimiento llamado (patch)

storage_service parcheado: los tests no tocan MinIO.

api/record/tests_integrations_anexo22.py — verificado que no existe ni un test de los endpoints M2M de MVE ni de Anexo22. El carril del CRM importa _err, _resolver_pedimento, _doc_to_dict y _resolver_document_type de ellos, así que fijarlos es prerrequisito. Mínimo: idempotencia por (anexo22_document_id, tipo), el rango VU de _resolver_document_type, y la guarda de fuente en el borrado.

api/customs/tests_cumplimiento_provisional.py — regresión de H3: provisional en una organización con checklist TipoChecklist.TODOS mantiene las 8 columnas cumplimiento_* en NULL.

api/customs/tests_provisionales_grid.py — /pedimentos/ los excluye por defecto; ?incluir_provisionales=true los incluye; ?crm_expediente_folio= filtra; export-excel y activo-fijo heredan; la forma de la respuesta no cambia para los consumidores React actuales; un provisional completado vuelve a aparecer.

15.2 Tests automatizados — CRM (cd backend && pytest tests/ -v)

tests/test_efc_client.py — el hueco que el carril de referencia tiene y que aquí no debe repetirse: verificado que no existe ni un test de EfcClient._request en Anexo22, así que el bucle de reintentos, el backoff, el corte en 4xx y el header nunca se ejercitan. Con httpx.MockTransport por el parámetro transport:

#	Caso	Qué prueba
1	500 y luego 200	reintenta y devuelve el éxito
2	500 siempre	exactamente 3 intentos, retryable=True
3	Timeout siempre	3 intentos, retryable=True
4	400 con {"error":{"code":"espacio_insuficiente"}}	un solo intento, code extraído, retryable=False
5	401 / 403	no se reintentan
6	Cuerpo de error que no es JSON	no revienta, code is None
7	Cualquier llamada	X-Api-Key presente con el valor de settings
8	EFC_API_URL vacía	is_configured is False, error no-retryable sin tocar la red
9	base_url con y sin / final	misma URL

tests/test_efc_outbox.py

#	Caso	Qué prueba
1	_register_failure con retryable=True	attempts=1, sigue pending
2	_register_failure con retryable=False	failed de inmediato
3	Hasta attempts = MAX_ATTEMPTS	failed
4	Excepción de 5000 caracteres	last_error truncado a 2000
5	deliver_row con EFC lanzando	no propaga la excepción
6	deliver_row sobre una fila sent	retorna sin llamar a EFC
7	_ya_entregado con una fila sent del mismo (source_table, source_id, kind)	no se encola otra
8	Mismo source_id en distinta source_table	sí se encola ← la prueba de la ambigüedad de las dos secuencias
9	Barrido	recoge pending viejos y despacha con headers RLS
10	retry_outbox_row	resetea attempts=0, last_error=None, pending, re-despacha
11	retry_outbox_row de otro tenant	False
12	find_expediente_gaps	incluye los sin fila; excluye los failed
13	EFC_API_URL vacía	no encola nada
14	El encolado falla	rollback y return None, la operación local no se rompe

tests/test_efc_entrega_documento.py — entrega feliz; ensure-then-upload (404 expediente_no_encontrado → crea el provisional y reintenta una vez); 404 con otro code no hace ensure; delete_local=True borra el objeto local; si el borrado local falla la fila sigue sent; delete_local=False no borra; reintento tras timeout con el mismo ref no duplica.

tests/test_expediente_folio.py — formato; tres seguidos 001/002/003; reinicio mensual; independencia por company; N sesiones concurrentes → N folios distintos (requiere PostgreSQL, marcar para saltar en SQLite); rollback deja hueco y el siguiente avanza.

tests/test_expedientes.py — ensure_* idempotente; crear una solicitud nace con folio; dos expedientes con el mismo (tenant, company, folio) → IntegrityError; aislamiento por tenant/company.

tests/test_expediente_upload.py — 201 con fila PENDING y fila de outbox; archivo por encima del tope → 422 sin haberlo leído completo; el tope se aplica antes de consumir el cuerpo; .exe → 422; doc_type inválido → 422; expediente de otro tenant → 404; EFC caído → sigue devolviendo 201 y la fila queda PENDING.

tests/test_expediente_download.py — el proxy hace streaming y cierra la respuesta httpx; documento de otro tenant → 404; ninguna URL de MinIO en cuerpo ni headers; EfcClientError → 502 y 404 de EFC → 404.

tests/test_gateway_rutas.py — retry inexistente → 404 con mensaje específico; éxito → {"status":"requeued","id":...}; metrics cuenta por status; aislamiento por tenant/company.

tests/test_uploads_alcance.py — GET /uploads/url con una key de fin-invoices/ → 403.

tests/test_doc_types_paridad.py — EFC_DOC_TYPES del CRM == las 22 claves de TIPOS_DOCUMENTO_CRM de EFC. La lista está duplicada a mano en dos repos; este test es lo que la mantiene honesta.

Tests de contrato: un fixture JSON compartido con las formas de request/response y los códigos de error por endpoint, afirmado en las dos suites. Es lo único que atrapa la deriva entre dos repos con despliegue independiente.

15.3 Verificación manual — documento Pruebas Ingeniería

Requiere EFC arriba con las fases 1-4, y el worker + beat del CRM corriendo.

1. Poner CRM_INTEGRATION_API_KEY en el .env de EFC y EFC_API_URL/EFC_API_KEY en el del CRM. Reiniciar api, worker y beat de ambos.
2. curl al resolver de organización con la key → 200/201 con el UUID. Repetir con una key incorrecta → 403.
3. En el admin de EFC, confirmar is_verified=True y la licencia asignada.
4. Crear una solicitud desde la pantalla del CRM → confirmar el folio EXP2026-08-0NN. Crear tres más → consecutivos sin huecos.
5. En el módulo Expedientes del frontend de EFC → los provisionales no aparecen. curl con ?incluir_provisionales=true → aparecen, con aduana y patente vacías.
6. Intentar borrar un provisional desde el admin de EFC → debe negarse (PROTECT).
7. En la ficha del embarque, adjuntar un PDF → barra de progreso, y badge En expediente al confirmar.
8. En la consola de MinIO del CRM, confirmar que el objeto local ya no está (corte directo). En la de EFC, confirmar la ruta org_{uuid}/documents/CRM-1-EXP2026-08-001/.
9. En el admin de EFC, confirmar fuente = APP-CRM, vu = False, document_type.id >= 27.
10. Abrir el documento desde el CRM → el PDF se descarga y se ve.
11. Apagar EFC. Adjuntar otro → la subida tiene éxito con badge Pendiente de enviar. En GET /expediente-gateway/outbox, ver attempts subir y last_error poblado cada dos minutos.
12. Levantar EFC. Esperar un barrido → badge En expediente, y en EFC hay un solo documento.
13. Apagar EFC ~17 minutos para forzar 8 fallos → la fila queda failed y deja de reintentarse. POST /outbox/{id}/retry → vuelve a pending y se entrega.
14. GET /expediente-gateway/metrics → los conteos cuadran con el listado.
15. Completar el expediente con pedimento dummy 0000-0000000 → 200; el pedimento_app cambió, los documentos siguen colgados y descargables, y el objeto en MinIO no se movió.
16. Recargar el módulo Expedientes de EFC → ahora sí aparece, con sus datos.
17. Intentar adjuntar un .exe → Ese tipo de archivo no está permitido. Un archivo mayor al tope → mensaje de tamaño, y el navegador no se queda colgado subiendo el archivo completo.
18. Borrar un documento del expediente en el CRM → desaparece del CRM y sigue existiendo en EFC.
19. Probar la UI en tema claro y oscuro, y en un ancho de móvil.

---

16. Fuera de alcance

• La fusión de documentos de un provisional a un pedimento real preexistente. El completado devuelve 409 y no mueve nada. PENDIENTE DECISIÓN: si se quiere un ?modo=fusionar con opt-in explícito, es un ticket aparte y debe rechazar si el provisional tiene documentos de otra fuente.
• Que los documentos del CRM cuenten en cumplimiento_porcentaje. Llegan con tipo_documento_expediente = NULL porque mapa_tipos_por_legacy solo cubre los 7 ids legacy de sistema — exactamente lo que le pasa a Anexo22. PENDIENTE DECISIÓN: si se quiere que cuenten, hay que sembrar TipoDocumentoExpediente por organización con nomenclaturas.
• Ligar la API key a una organización, mTLS y require_permission. Deuda heredada del carril de referencia, documentada en el docstring de la clase de permiso.
• El PDF de factura (fin.invoices). Su pantalla y send_invoice no se tocan. Cuando entre, será con crm_document_ref = INVOICE-{cid}-{id} (estable → idempotente sin key del cliente).
• El backfill de documentos legacy del MinIO del CRM. Las filas con file_key se quedan con efc_document_id = NULL y la descarga se ramifica en tres (efc_document_id → proxy; file_key → presigned; file_url → externa). Cuando se haga, va por el mismo outbox con crm_document_ref = LEGACY-{tabla}-{id} (estable → re-ejecutable sin duplicar), y antes de empezar hay que sumar bytes y compararlos contra la cuota disponible.
• La limpieza de objetos huérfanos del bug histórico de delete_document: script aparte, dry-run por defecto, desacoplado de este trabajo.
• Una pestaña "Provisionales (CRM)" en el frontend de EFC. Los dos campos nuevos del serializer la habilitan sin más backend.
• Un token firmado para descargas grandes.
• PENDIENTE DECISIÓN (no bloquean nada de este ticket): NNN da 999 expedientes por mes y por company —ensancharlo después invalida folios ya comunicados—; una organización EFC por tenant significa que todas las companies comparten cuota y visibilidad; MAX_ATTEMPTS = 8 y barridos de 120 s son heredados de Anexo22, confirmar si sirven para el volumen del CRM; y la exclusión de provisionales del grid es un cambio visible para los operadores de EFC, hay que confirmarlo con ellos antes de mergear.

---

17. Prohibiciones específicas de este ticket

EFC

• Nunca pedimento_obj.save(). Solo Pedimento.objects.filter(...).update(...).
• DocumentType.objects.get_or_create() está prohibido. Solo _resolver_document_type.
• No poner consultar_vucem=True en ninguna ruta de este ticket.
• No agregar columnas a Pedimento. Todo el acoplamiento en pedimento_expediente.
• No modificar _doc_to_dict. Extenderlo con _crm_doc_to_dict.
• No pasar pedimento.pedimento_app a save_document. Siempre enlace.storage_token.
• No borrar el objeto de MinIO antes de subir el nuevo en el reemplazo.
• No usar NamedTemporaryFile + atexit en la descarga.
• No reusar MVE_INTEGRATION_API_KEY ni ANEXO22_INTEGRATION_API_KEY.
• No aplicar la exclusión de provisionales a DescargaExpedienteViewSet ni a los bulk-delete de VU.
• No quitar ni renombrar ningún campo existente de PedimentoSerializer.
• No dejar que el CRM cree organizaciones sin is_verified=True.

CRM

• No usar SELECT max(sequence) + 1. El contador con ON CONFLICT, nada más.
• No hacer commit dentro de next_folio.
• No hacer la llamada HTTP a EFC dentro del request del usuario. Encolar y despachar.
• No convertir EfcClient a async. httpx.Client síncrono, como el original.
• No agregar autoretry_for, retry_backoff ni max_retries a las tareas: duplicaría el mecanismo de reintento que ya está en el cliente y en el barrido.
• No dejar que un fallo de EFC propague una excepción desde deliver_row.
• No borrar el objeto local antes de confirmar la entrega.
• No usar await file.read() para el archivo completo.
• No devolver file_key ni file_url en la respuesta del endpoint nuevo.
• No crear el AsyncClient del proxy fuera del generador.
• No llamar al DELETE de EFC desde el soft delete.
• No romper uploadFile/uploadUrl: las filas legacy y la pantalla de facturas los usan.
• No reusar core/s3_keys.py::expediente_archivo_document_key ni expediente_archivo_artifact_key: son código muerto de la plantilla y se refieren al expediente del importador de EFC, que es otro concepto (cuelga de Importador por RFC, reglas 1.4.14/3.1.42). Sus nombres van a confundir.
• No inventar nombres de variables de entorno: reusar los de Anexo22.
• SvelteKit 5 con runes, nunca la sintaxis de v4.

Ambas

• No aplicar migraciones. Se generan y se dejan sin aplicar. Ni migrate ni alembic upgrade.

---

Lo que este ticket NO debe traer

• Entrada de CHANGELOG.md. El changelog lo escribe el orquestador al final, en un PR aparte (Orquestacion.md §9). Si algo de arriba pareciera pedirlo, esa instrucción queda derogada.
• Instrucciones de abrir el PR. El agente pushea las ramas y deja título, cuerpo y link de compare; el PR lo abre una persona.
• Pasos que esperen aprobación. No hay nadie despierto.
• Credenciales, tokens, contenido de .env ni datos de clientes reales.
• Instrucciones de registrar la actividad en el Kanban. El agente lo hace solo al cerrar el ticket, en el ticket P espejo.

Ambigüedad durante la corrida

Si algo no está en este ticket ni en el código, no adivinar: documentar como PENDIENTE DECISIÓN: <qué falta y qué se asumió> en el cuerpo del PR y seguir con la asunción más conservadora.

Riesgos conocidos que no cierra este ticket

• resolver_fk después del completado. Document.save() re-resuelve partida/cove/edocument por heurística de nombre. En un provisional no hay partidas, pero el pedimento real sí las tiene, así que cualquier save() sobre un documento del CRM podría auto-ligarlo a una partida ajena. Mitigación: nunca save() un documento del CRM después de crearlo, y un test que afirme que esas tres FK siguen en NULL.
• _construir_pedimento_app tiene tres implementaciones en la casa que deben coincidir. El carril de EFC la importa; si alguien las desalinea, el completado puede generar una llave que no case con la que ya creó datastage.
• Enforcement de permisos en el CRM. El repo registra ~48 permisos por entidad pero no los aplica en ninguna ruta: solo hay gate de módulo (crm.access). Para un carril que escribe documentos fiscales en otro sistema conviene aplicarlos por ruta con PermissionChecker, y es un ticket aparte.
• .env.example de EFC contiene valores reales (contraseña de BD y de SMTP) y hay ~6.5 GB de dumps de producción en la raíz de ese repo. Fuera del alcance, pero hay que rotar esas credenciales y revisar el .gitignore. Mismo cuidado con el .env de Anexo22.