# 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<CreatePartnerDto>
  - `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
