# RF-MGN-002-001: Gestión de Empresas

**Módulo:** MGN-002 - Empresas y Organizaciones
**Prioridad:** P0 (MVP)
**Story Points:** 8
**Estado:** Definido
**Fecha:** 2025-11-23

## Descripción

El sistema debe permitir la creación, lectura, actualización y desactivación (soft delete) de empresas. Cada empresa tiene datos generales, fiscales, dirección y configuración. Una empresa también es un partner (patrón Odoo).

## Actores

- **Actor Principal:** Administrador de Sistema
- **Actores Secundarios:** Contador (configura datos fiscales)

## Precondiciones

1. Usuario administrador debe estar autenticado
2. Tenant debe estar activo
3. Catálogo de países y monedas debe estar disponible (MGN-003)

## Flujo Principal

1. Administrador accede a módulo de Gestión de Empresas
2. Administrador crea nueva empresa con datos generales:
   - Nombre comercial y nombre legal
   - RFC/NIT/Tax ID
   - Email corporativo, teléfono, sitio web
3. Administrador configura dirección:
   - Calle, número, colonia
   - Ciudad, estado, país, código postal
4. Administrador configura datos fiscales:
   - Régimen fiscal
   - Moneda principal (currency_id)
5. Sistema crea partner automáticamente (is_company=true)
6. Sistema vincula empresa con partner (company.partner_id)
7. Sistema guarda logo de empresa (opcional)
8. Sistema crea registro en core.companies
9. Empresa queda disponible para asignar usuarios

## Flujos Alternativos

### FA-1: Actualización de Datos de Empresa
1. Administrador selecciona empresa existente
2. Administrador modifica datos (nombre, dirección, fiscal)
3. Sistema valida cambios
4. Sistema actualiza core.companies y core.partners
5. Cambios se reflejan inmediatamente

### FA-2: Configuración de Holdings (Jerarquía)
1. Administrador crea empresa hija
2. Administrador selecciona parent_id (empresa padre/holding)
3. Sistema valida que no haya ciclos (A → B → A)
4. Sistema crea jerarquía en core.companies
5. Sistema puede visualizar organigrama de empresas

### FA-3: Desactivación de Empresa
1. Administrador desactiva empresa (status='inactive')
2. Sistema valida que no haya documentos pendientes (órdenes, facturas draft)
3. Si hay pendientes, sistema retorna error 400: "Empresa tiene documentos pendientes"
4. Si no hay pendientes, sistema desactiva empresa
5. Usuarios pierden acceso a empresa desactivada

### FA-4: Subir Logo de Empresa
1. Administrador sube logo (PNG, JPG, max 2MB)
2. Sistema valida formato y tamaño
3. Sistema guarda en storage (S3 o file system)
4. Sistema actualiza company.logo_url
5. Logo se muestra en documentos (facturas, cotizaciones)

## Reglas de Negocio

- **RN-1:** Una empresa también es un partner (company.partner_id)
- **RN-2:** Tax ID debe ser único por país
- **RN-3:** Empresa debe tener moneda principal definida
- **RN-4:** Empresa puede ser parte de holding (parent_id)
- **RN-5:** No se permiten ciclos en jerarquías (validación)
- **RN-6:** Empresa desactivada no permite creación de nuevos documentos
- **RN-7:** Logo máximo 2MB, formatos: PNG, JPG, SVG

## Criterios de Aceptación

- [ ] Administrador puede crear empresas con datos generales y fiscales
- [ ] Sistema crea partner automáticamente para cada empresa
- [ ] Administrador puede configurar dirección y país de empresa
- [ ] Administrador puede subir logo de empresa (max 2MB)
- [ ] Empresa tiene moneda principal definida
- [ ] Administrador puede crear jerarquías (holdings con empresas hijas)
- [ ] Sistema valida que Tax ID sea único por país
- [ ] Sistema previene ciclos en jerarquías
- [ ] Administrador puede desactivar empresas sin documentos pendientes
- [ ] Logo de empresa se muestra en documentos (facturas, cotizaciones)

## Entidades Involucradas

- **Principales:**
  - core.companies (name, legal_name, tax_id, currency_id, parent_id, logo_url)
  - core.partners (empresa también es partner)
- **Relacionadas:**
  - core.countries (país de empresa)
  - core.currencies (moneda principal)

## Referencias

- [ALCANCE-POR-MODULO.md - MGN-002](../../01-definicion-modulos/ALCANCE-POR-MODULO.md#mgn-002-empresas-y-organizaciones)
- [Auth Schema DDL](../database-design/schemas/auth-schema-ddl.sql)
- [Core Schema DDL](../database-design/schemas/core-schema-ddl.sql)
- [Gap Analysis MGN-002](../../01-definicion-modulos/gaps/GAP-ANALYSIS-MGN-002.md)

## Notas Técnicas

- **Patrón Odoo:** res.company (empresa también es res.partner)
- **Validación Tax ID:** Regex por país (México RFC: 12-13 chars alfanumérico)
- **Logo Storage:**
  - Desarrollo: file system local
  - Producción: AWS S3 o similar
- **Jerarquías:** Visualización con tree view o organigrama D3.js
- **Backend:** NestJS CompaniesService
- **Frontend:** Formulario con tabs (General, Fiscal, Dirección)

## Dependencias

- **RF Dependientes:**
  - RF-MGN-001-001 (Autenticación)
  - RF-MGN-003-001 (Partners - se crea automáticamente)
  - RF-MGN-003-002 (Países)
  - RF-MGN-003-003 (Monedas)
- **Bloqueante para:** RF-MGN-002-003 (Asignación usuarios a empresas)