# 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 ```gherkin 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) ```gherkin 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 ```gherkin 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 ```gherkin 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 ```gherkin 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 ```gherkin 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 ```gherkin 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) - [x] Historia claramente escrita (quien, que, por que) - [x] Criterios de aceptacion definidos con Gherkin - [x] Story points estimados (8 SP) - [x] Dependencias identificadas - [x] Sin bloqueadores - [x] Modelo de datos definido - [x] 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 - [EPIC-MGN-005: Catalogos Maestros](../../08-epicas/EPIC-MGN-005-catalogs.md) - [RF-MGN-003-001: Gestion de Partners](../../04-modelado/requerimientos-funcionales/mgn-003/RF-MGN-003-001-gestion-partners.md) - [TEMPLATE-HISTORIA-USUARIO.md](/home/isem/workspace/core/orchestration/templates/TEMPLATE-HISTORIA-USUARIO.md) --- **Creada por:** Requirements-Analyst **Fecha:** 2025-12-05 **Ultima actualizacion:** 2025-12-05