rckrdmrd 59f1e3badf Initial commit - erp-core

2026-01-04 06:12:07 -06:00

6.6 KiB

Raw Blame History

RF-FIN-003: Periodos Contables

Identificacion

Campo	Valor
ID	RF-FIN-003
Modulo	MGN-010 Financial
Titulo	Periodos Contables
Prioridad	P0 - Critica
Estado	Draft
Fecha	2025-12-05

Descripcion

El sistema debe gestionar años fiscales y periodos contables, controlando la apertura y cierre de periodos, y restringiendo el registro de movimientos fuera de periodos activos.

Requisitos Funcionales

RF-FIN-003.1: Estructura de Año Fiscal

interface FiscalYear {
  id: UUID;
  tenantId: UUID;
  name: string;             // "Ejercicio 2025"
  code: string;             // "2025"
  startDate: Date;          // "2025-01-01"
  endDate: Date;            // "2025-12-31"
  status: FiscalYearStatus;
  closedAt?: TIMESTAMPTZ;
  closedBy?: UUID;
  createdAt: TIMESTAMPTZ;
}

enum FiscalYearStatus {
  DRAFT = 'draft',         // En preparacion
  OPEN = 'open',           // Activo
  CLOSING = 'closing',     // En proceso de cierre
  CLOSED = 'closed'        // Cerrado
}

RF-FIN-003.2: Estructura de Periodo

interface FiscalPeriod {
  id: UUID;
  fiscalYearId: UUID;
  number: number;           // 1-12 o 1-13
  name: string;             // "Enero 2025"
  startDate: Date;
  endDate: Date;
  status: PeriodStatus;
  closedAt?: TIMESTAMPTZ;
  closedBy?: UUID;
}

enum PeriodStatus {
  FUTURE = 'future',       // Aun no inicia
  OPEN = 'open',           // Activo para movimientos
  CLOSED = 'closed',       // Cerrado
  LOCKED = 'locked'        // Bloqueado definitivamente
}

RF-FIN-003.3: Tipos de Periodos

Tipo	Periodos	Uso
Mensual	12	Mas comun
Bimestral	6	Algunos paises
Trimestral	4	Reportes
Semestral	2	Simplificado
Anual	1	Muy simplificado
Mensual + 13	13	Con periodo de ajuste

RF-FIN-003.4: Periodo de Ajuste

Periodo especial para asientos de cierre:

interface AdjustmentPeriod extends FiscalPeriod {
  number: 13;                // Periodo 13
  name: "Ajustes 2025";
  isAdjustment: true;
  // Fecha = ultimo dia del año
  startDate: "2025-12-31";
  endDate: "2025-12-31";
}

RF-FIN-003.5: Control de Fechas

// Validar si fecha permite movimientos
function canPostToDate(date: Date, tenantId: UUID): ValidationResult {
  const period = findPeriodByDate(date, tenantId);

  if (!period) {
    return { valid: false, error: 'No existe periodo para esta fecha' };
  }

  if (period.status === 'closed') {
    return { valid: false, error: 'Periodo cerrado' };
  }

  if (period.status === 'locked') {
    return { valid: false, error: 'Periodo bloqueado permanentemente' };
  }

  if (period.status === 'future') {
    return { valid: false, error: 'Periodo aun no abierto' };
  }

  return { valid: true };
}

RF-FIN-003.6: Proceso de Cierre de Periodo

interface PeriodCloseProcess {
  periodId: UUID;
  steps: CloseStep[];
  currentStep: number;
  status: 'pending' | 'in_progress' | 'completed' | 'failed';
  startedAt?: TIMESTAMPTZ;
  completedAt?: TIMESTAMPTZ;
}

interface CloseStep {
  name: string;
  description: string;
  status: 'pending' | 'running' | 'completed' | 'skipped' | 'failed';
  isRequired: boolean;
  error?: string;
}

// Pasos tipicos de cierre
const CLOSE_STEPS = [
  { name: 'validate_balances', description: 'Validar saldos cuadrados', required: true },
  { name: 'check_pending', description: 'Verificar documentos pendientes', required: false },
  { name: 'calculate_depreciation', description: 'Calcular depreciaciones', required: false },
  { name: 'accrue_expenses', description: 'Registrar provisiones', required: false },
  { name: 'close_temporary', description: 'Cerrar cuentas temporales', required: true },
  { name: 'generate_balances', description: 'Generar saldos de cierre', required: true }
];

RF-FIN-003.7: Cierre de Año Fiscal

Al cerrar el año:

Cerrar ultimo periodo
Generar asiento de cierre (P&L -> Utilidades)
Generar saldos iniciales del nuevo año
Marcar año como cerrado

interface YearCloseResult {
  fiscalYearId: UUID;
  closingEntryId: UUID;
  openingEntryId: UUID;      // En nuevo año
  retainedEarnings: Decimal; // Utilidad/perdida del ejercicio
  newFiscalYearId: UUID;     // Nuevo año creado
}

Operaciones

Listar Años Fiscales

GET /api/v1/financial/fiscal-years

Response:
{
  "data": [
    {
      "id": "uuid",
      "name": "Ejercicio 2025",
      "startDate": "2025-01-01",
      "endDate": "2025-12-31",
      "status": "open",
      "periodsCount": 12,
      "openPeriodsCount": 1
    }
  ]
}

Obtener Periodos del Año

GET /api/v1/financial/fiscal-years/:id/periods

Response:
{
  "fiscalYear": { "id": "...", "name": "2025" },
  "periods": [
    { "number": 1, "name": "Enero", "status": "closed" },
    { "number": 2, "name": "Febrero", "status": "closed" },
    // ...
    { "number": 12, "name": "Diciembre", "status": "open" }
  ]
}

Crear Año Fiscal

POST /api/v1/financial/fiscal-years
{
  "name": "Ejercicio 2026",
  "startDate": "2026-01-01",
  "endDate": "2026-12-31",
  "periodType": "monthly",
  "includeAdjustment": true
}

Cerrar Periodo

POST /api/v1/financial/periods/:id/close

Response:
{
  "periodId": "uuid",
  "status": "closed",
  "closedAt": "2025-12-05T10:00:00Z",
  "validationResults": [
    { "check": "balances_match", "passed": true },
    { "check": "no_pending_docs", "passed": true }
  ]
}

Reabrir Periodo (Excepcion)

POST /api/v1/financial/periods/:id/reopen
{
  "reason": "Correccion de asiento",
  "approvedBy": "uuid-supervisor"
}

// Requiere permiso especial
// Genera registro en audit log

Reglas de Negocio

ID	Regla	Severidad
BR-001	No registrar movimientos en periodos cerrados	Error
BR-002	Solo un periodo abierto por defecto	Warning
BR-003	No cerrar periodo con documentos pendientes	Warning
BR-004	Cierre de año genera asientos automaticos	Info
BR-005	Reabrir periodo requiere autorizacion	Security

Criterios de Aceptacion

CRUD de años fiscales
Generacion automatica de periodos
Control de fechas de contabilizacion
Proceso de cierre de periodo
Proceso de cierre de año
Generacion de saldos iniciales
Reabrir periodo con autorizacion

Historial

Version	Fecha	Autor	Cambios
1.0	2025-12-05	Requirements-Analyst	Creacion inicial

6.6 KiB Raw Blame History