rckrdmrd/erp-core
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
main
erp-core/docs/05-user-stories/mgn-003/US-MGN-003-001-001-crud-partners.md

12 KiB
Raw Permalink Blame History

US-MGN-003-001-001: CRUD de Partners (Clientes/Proveedores)

Metadata

Campo Valor
ID US-MGN-003-001-001
Epica EPIC-MGN-005 - Catalogos Maestros
Modulo MGN-003 - Partners
Prioridad P0 (MVP)
Story Points 8
Sprint Sprint 5
Estado Ready
Asignado a Backend-Agent, Frontend-Agent

Historia de Usuario

Como usuario del sistema (vendedor, comprador, contador), quiero crear y gestionar partners (clientes, proveedores, contactos), para registrar las entidades con las que mi empresa tiene relaciones comerciales y utilizarlas en transacciones.

Descripcion Detallada

Los Partners son entidades fundamentales del ERP que representan clientes, proveedores, empleados o cualquier contacto comercial. Un partner puede tener multiples tipos simultaneamente (ej: ser cliente y proveedor a la vez).

Cada partner tiene:

  • Datos basicos: nombre, RFC/NIT, email, telefono
  • Direcciones multiples (fiscal, entrega, facturacion)
  • Tipo(s): Cliente, Proveedor, Contacto, Empleado
  • Datos bancarios para pagos
  • Credito y condiciones de pago
  • Clasificacion por categorias/etiquetas

El partner es usado por:

  • Ventas (clientes)
  • Compras (proveedores)
  • Contabilidad (cuentas por cobrar/pagar)
  • CRM (leads convertidos)

Mockups / Wireframes

Pagina de Partners:

  • Header: Titulo "Partners" + Boton "Nuevo Partner"
  • Filtros: Tipo (Cliente/Proveedor/Todos), Activo/Inactivo, Busqueda
  • Tabla con columnas: Nombre, RFC, Tipo, Email, Telefono, Acciones
  • Paginacion: 25 items por pagina

Formulario de Partner:

  • Tabs: Datos Generales | Direcciones | Datos Bancarios | Credito
  • Tab Generales: Nombre*, RFC*, Email*, Telefono, Tipo (checkboxes), Categoria
  • Tab Direcciones: Lista de direcciones con tipo (fiscal, entrega, otro)
  • Tab Bancarios: Banco, Cuenta, CLABE
  • Tab Credito: Limite de credito, Dias de credito, Condicion de pago

Criterios de Aceptacion

Escenario 1: Crear partner cliente exitosamente

DADO que soy un usuario con permiso "partner.create"
Y estoy en la pagina de Partners
CUANDO hago clic en "Nuevo Partner"
Y completo nombre="ACME Corp", RFC="ACM010101ABC", email="contacto@acme.com"
Y selecciono tipo="Cliente"
Y hago clic en "Guardar"
ENTONCES el sistema crea el partner con id generado
Y muestra mensaje "Partner creado exitosamente"
Y el partner aparece en la lista
Y el partner tiene tenant_id de mi tenant actual

Escenario 2: Crear partner multi-tipo (Cliente y Proveedor)

DADO que estoy creando un nuevo partner
CUANDO selecciono tipo="Cliente" Y tipo="Proveedor"
Y completo los datos requeridos
Y hago clic en "Guardar"
ENTONCES el sistema crea el partner con ambos tipos
Y el partner esta disponible en modulo de Ventas (como cliente)
Y el partner esta disponible en modulo de Compras (como proveedor)

Escenario 3: Validar RFC duplicado en tenant

DADO que existe un partner con RFC="DUP010101XYZ" en mi tenant
CUANDO intento crear un nuevo partner con el mismo RFC
ENTONCES el sistema muestra error "Ya existe un partner con este RFC"
Y no permite guardar el registro

Escenario 4: RFC puede repetirse entre tenants

DADO que existe un partner con RFC="COM010101ABC" en tenant "empresa-a"
CUANDO un usuario de tenant "empresa-b" crea partner con RFC="COM010101ABC"
ENTONCES el sistema permite la creacion
Y cada tenant tiene su propio registro del partner

Escenario 5: Busqueda rapida de partners

DADO que existen 1000+ partners en mi tenant
CUANDO escribo "acme" en el campo de busqueda
ENTONCES el sistema filtra por nombre y RFC que contengan "acme"
Y los resultados aparecen en menos de 200ms
Y la busqueda es case-insensitive

Escenario 6: Soft delete de partner

DADO que existe un partner "Cliente Inactivo"
Y el partner NO tiene transacciones asociadas (ventas, compras)
CUANDO hago clic en "Eliminar" y confirmo
ENTONCES el partner se marca como deleted_at = NOW()
Y el partner NO aparece en listados por defecto
Y el partner SI aparece si filtro por "Incluir eliminados"

Escenario 7: Impedir eliminar partner con transacciones

DADO que existe un partner "Cliente Activo"
Y el partner tiene 5 ventas asociadas
CUANDO intento eliminar el partner
ENTONCES el sistema muestra error "No se puede eliminar: tiene 5 transacciones asociadas"
Y sugiere "Puede desactivar el partner en lugar de eliminarlo"

Reglas de Negocio

  • RN-1: RFC/NIT es unico por tenant (no globalmente)
  • RN-2: Un partner puede tener multiples tipos simultaneamente
  • RN-3: Email es opcional pero si se proporciona debe ser valido
  • RN-4: Telefono acepta formatos variados (se normaliza internamente)
  • RN-5: Soft delete: partners eliminados no se borran, se marcan con deleted_at
  • RN-6: No se puede eliminar partner con transacciones, solo desactivar
  • RN-7: Al menos una direccion debe marcarse como "fiscal"
  • RN-8: Limite de credito por defecto es 0 (sin credito)

Tareas Tecnicas

Database

  • DB-MGN003-001: Verificar tabla core_catalogs.partners

    • Columnas: id, tenant_id, name, tax_id (RFC), email, phone, is_customer, is_supplier, is_contact, credit_limit, payment_term_id, status, created_at, updated_at, deleted_at
    • Indices: idx_partners_tenant_tax_id (UNIQUE), idx_partners_name_search (pg_trgm)
    • RLS: tenant_isolation_partners

  • DB-MGN003-002: Verificar tabla core_catalogs.partner_addresses

    • Columnas: id, partner_id, type (fiscal/delivery/other), street, city, state_id, country_id, zip_code, is_default
    • FK: partner_id -> partners.id

  • DB-MGN003-003: Verificar tabla core_catalogs.partner_bank_accounts

    • Columnas: id, partner_id, bank_name, account_number, clabe, is_default

Backend

  • BE-MGN003-001: Crear PartnerEntity con relaciones

    • Relaciones: addresses (OneToMany), bankAccounts (OneToMany), paymentTerm (ManyToOne)
    • Decoradores: @Entity, @Index, @Column con validaciones

  • BE-MGN003-002: Crear DTOs

    • CreatePartnerDto: name*, tax_id*, email?, phone?, types[], addresses[]
    • UpdatePartnerDto: Partial
    • PartnerFilterDto: type?, status?, search?, page, limit
    • PartnerResponseDto: Entity + computed fields

  • BE-MGN003-003: Crear PartnerService

    • create(dto, tenantId): Validar RFC unico, crear partner
    • findAll(filters, tenantId): Listar con paginacion y filtros
    • findOne(id, tenantId): Obtener con relaciones
    • update(id, dto, tenantId): Actualizar validando RFC
    • remove(id, tenantId): Soft delete si no tiene transacciones
    • search(query, tenantId): Busqueda rapida por nombre/RFC

  • BE-MGN003-004: Crear PartnerController

    • POST /api/v1/partners: Crear partner
    • GET /api/v1/partners: Listar con filtros
    • GET /api/v1/partners/:id: Obtener detalle
    • PATCH /api/v1/partners/:id: Actualizar
    • DELETE /api/v1/partners/:id: Eliminar (soft)
    • GET /api/v1/partners/search?q=: Busqueda rapida

  • BE-MGN003-005: Documentar endpoints en Swagger

    • Request/Response schemas
    • Ejemplos de uso
    • Codigos de error

  • BE-MGN003-006: Tests unitarios PartnerService (12 casos)

  • BE-MGN003-007: Tests integracion PartnerController (8 casos)

Frontend

  • FE-MGN003-001: Crear partnersApi (API client)

    • getPartners(filters), getPartner(id), createPartner(data)
    • updatePartner(id, data), deletePartner(id), searchPartners(q)

  • FE-MGN003-002: Crear usePartnersStore (Zustand)

    • State: partners[], selectedPartner, filters, loading, error
    • Actions: fetchPartners, createPartner, updatePartner, deletePartner

  • FE-MGN003-003: Crear PartnersPage.tsx

    • Layout con header, filtros, tabla, paginacion
    • Modal para crear/editar partner

  • FE-MGN003-004: Crear PartnerForm.tsx

    • React Hook Form + Zod validation
    • Tabs para secciones
    • Manejo de direcciones dinamicas

  • FE-MGN003-005: Crear PartnerTable.tsx

    • Columnas configurables
    • Acciones: Ver, Editar, Eliminar
    • Sorting y filtros

  • FE-MGN003-006: Crear PartnerSearchSelect.tsx

    • Componente reutilizable para seleccionar partner
    • Busqueda con debounce
    • Usado en: Ventas, Compras, CRM

  • FE-MGN003-007: Tests de componentes (6 casos)

Dependencias

Depende de:

  • US-MGN-001-001-001: Login (autenticacion requerida)
  • US-MGN-001-004-001: Tenants (aislamiento de datos)
  • Catalogos de paises/estados (para direcciones)

Bloquea:

  • US-MGN-007-*: Ventas (requiere clientes)
  • US-MGN-008-*: Compras (requiere proveedores)
  • US-MGN-014-*: CRM (conversion de leads)

Notas Tecnicas

Endpoints:

Metodo Endpoint Descripcion
POST /api/v1/partners Crear partner
GET /api/v1/partners Listar con filtros
GET /api/v1/partners/:id Obtener detalle
PATCH /api/v1/partners/:id Actualizar
DELETE /api/v1/partners/:id Soft delete
GET /api/v1/partners/search Busqueda rapida

Entidades/Tablas:

  • core_catalogs.partners: Tabla principal
  • core_catalogs.partner_addresses: Direcciones
  • core_catalogs.partner_bank_accounts: Datos bancarios

Componentes UI:

  • PartnersPage: Pagina principal
  • PartnerForm: Formulario crear/editar
  • PartnerTable: Tabla con acciones
  • PartnerSearchSelect: Selector con busqueda

Definition of Ready (DoR)

  • Historia claramente escrita (quien, que, por que)
  • Criterios de aceptacion definidos con Gherkin
  • Story points estimados (8 SP)
  • Dependencias identificadas
  • Sin bloqueadores
  • Modelo de datos definido
  • Tareas tecnicas desglosadas

Definition of Done (DoD)

  • Codigo backend implementado segun especificacion
  • Codigo frontend implementado
  • Tests unitarios escritos y pasando (>80%)
  • Tests de integracion pasando
  • Code review aprobado
  • Documentacion Swagger actualizada
  • Inventarios actualizados (MASTER_INVENTORY.yml)
  • Traza registrada
  • QA manual completado
  • Desplegado en ambiente de pruebas

Casos de Prueba (Test Scenarios)

Funcionales

  1. TC-001: Crear partner cliente con datos minimos
  2. TC-002: Crear partner con todos los campos
  3. TC-003: Crear partner multi-tipo
  4. TC-004: Validar RFC duplicado
  5. TC-005: Actualizar partner existente
  6. TC-006: Soft delete partner sin transacciones
  7. TC-007: Impedir delete partner con transacciones
  8. TC-008: Busqueda por nombre (case-insensitive)
  9. TC-009: Busqueda por RFC parcial
  10. TC-010: Filtrar por tipo (cliente/proveedor)
  11. TC-011: Paginacion correcta
  12. TC-012: Aislamiento entre tenants

No Funcionales

  1. Performance: Busqueda < 200ms con 10k partners
  2. Seguridad: RLS impide acceso cross-tenant
  3. Usabilidad: Tab navigation funciona correctamente

Estimacion Detallada

Tarea Estimacion
Database (verificar/crear) 2 horas
Backend Entity + DTOs 3 horas
Backend Service + Controller 4 horas
Backend Tests 3 horas
Frontend API + Store 2 horas
Frontend Pagina + Form 4 horas
Frontend Tests 2 horas
Code Review 2 horas
TOTAL 22 horas

Equivalente: 8 Story Points

Historial de Cambios

Fecha Cambio Autor
2025-12-05 Creacion de US con formato completo Requirements-Analyst

Referencias

Creada por: Requirements-Analyst Fecha: 2025-12-05 Ultima actualizacion: 2025-12-05