Initial commit: Horux Backend API
- API REST para gestion de facturas electronicas mexicanas (CFDI) - Laravel 9 con autenticacion OAuth 2.0 (Passport) - Integracion con Syntage, Clerk y Facturama - 30 modelos Eloquent, 39 controladores - Documentacion completa en /docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
447
docs/MODELS.md
Normal file
447
docs/MODELS.md
Normal file
@@ -0,0 +1,447 @@
|
||||
# Modelos y Base de Datos - Horux Backend
|
||||
|
||||
Documentacion de los modelos Eloquent y estructura de la base de datos.
|
||||
|
||||
## Diagrama de Relaciones
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ User │◄─────►│ Rfc │◄─────►│ Invoice │
|
||||
└─────────────┘ M:N └─────────────┘ 1:N └─────────────┘
|
||||
│ │ │
|
||||
│ 1:N │ 1:N │ 1:N
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│LinkedSocialAcct │ │ Taxpayer │ │ InvoiceLine │
|
||||
└─────────────────┘ └─────────────┘ └─────────────┘
|
||||
│
|
||||
│ M:N
|
||||
▼
|
||||
┌─────────────┐ ┌─────────────────┐
|
||||
│ TaxRegime │ │ InvoicePayment │
|
||||
└─────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Modelos Principales
|
||||
|
||||
### User
|
||||
Usuario del sistema.
|
||||
|
||||
**Tabla:** `users`
|
||||
|
||||
| Campo | Tipo | Descripcion |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | ID primario |
|
||||
| name | string | Nombre del usuario |
|
||||
| email | string | Correo electronico |
|
||||
| email_verified_at | timestamp | Fecha verificacion |
|
||||
| password | string | Contrasena hasheada |
|
||||
| remember_token | string | Token de sesion |
|
||||
| created_at | timestamp | Fecha creacion |
|
||||
| updated_at | timestamp | Fecha actualizacion |
|
||||
|
||||
**Relaciones:**
|
||||
- `rfcs()` - BelongsToMany con Rfc
|
||||
- `linkedSocialAccounts()` - HasMany con LinkedSocialAccount
|
||||
|
||||
---
|
||||
|
||||
### Rfc
|
||||
RFC (Registro Federal de Contribuyentes) asociado a usuarios.
|
||||
|
||||
**Tabla:** `rfcs`
|
||||
|
||||
| Campo | Tipo | Descripcion |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | ID primario |
|
||||
| rfc | string(13) | RFC del contribuyente |
|
||||
| razon_social | string | Razon social |
|
||||
| created_at | timestamp | Fecha creacion |
|
||||
| updated_at | timestamp | Fecha actualizacion |
|
||||
|
||||
**Relaciones:**
|
||||
- `users()` - BelongsToMany con User
|
||||
- `invoices()` - HasMany con Invoice
|
||||
- `taxpayers()` - HasMany con Taxpayer
|
||||
|
||||
---
|
||||
|
||||
### Invoice
|
||||
Factura electronica (CFDI).
|
||||
|
||||
**Tabla:** `invoices`
|
||||
|
||||
| Campo | Tipo | Descripcion |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | ID primario |
|
||||
| uuid | string(36) | UUID unico del CFDI |
|
||||
| serie | string | Serie de la factura |
|
||||
| folio | string | Folio de la factura |
|
||||
| fecha | datetime | Fecha de emision |
|
||||
| subtotal | decimal(18,2) | Subtotal |
|
||||
| descuento | decimal(18,2) | Descuento aplicado |
|
||||
| total | decimal(18,2) | Total de la factura |
|
||||
| moneda | string(3) | Codigo de moneda |
|
||||
| tipo_cambio | decimal(10,4) | Tipo de cambio |
|
||||
| emisor_rfc | string(13) | RFC del emisor |
|
||||
| emisor_nombre | string | Nombre del emisor |
|
||||
| receptor_rfc | string(13) | RFC del receptor |
|
||||
| receptor_nombre | string | Nombre del receptor |
|
||||
| tipo_comprobante | string(1) | Tipo (I, E, T, N, P) |
|
||||
| metodo_pago | string(3) | Metodo de pago |
|
||||
| forma_pago | string(2) | Forma de pago |
|
||||
| uso_cfdi | string(4) | Uso del CFDI |
|
||||
| iva_trasladado | decimal(18,2) | IVA trasladado |
|
||||
| iva_retenido | decimal(18,2) | IVA retenido |
|
||||
| isr_retenido | decimal(18,2) | ISR retenido |
|
||||
| rfc_id | bigint | FK a rfcs |
|
||||
| conciliado | boolean | Estado de conciliacion |
|
||||
| created_at | timestamp | Fecha creacion |
|
||||
| updated_at | timestamp | Fecha actualizacion |
|
||||
|
||||
**Relaciones:**
|
||||
- `rfc()` - BelongsTo con Rfc
|
||||
- `lines()` - HasMany con InvoiceLine
|
||||
- `payments()` - HasMany con InvoicePayment
|
||||
- `invoiceType()` - BelongsTo con InvoiceType
|
||||
- `conciliations()` - HasMany con Conciliation
|
||||
|
||||
---
|
||||
|
||||
### InvoiceLine
|
||||
Linea/concepto de una factura.
|
||||
|
||||
**Tabla:** `invoice_lines`
|
||||
|
||||
| Campo | Tipo | Descripcion |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | ID primario |
|
||||
| invoice_id | bigint | FK a invoices |
|
||||
| clave_prod_serv | string(8) | Codigo SAT producto/servicio |
|
||||
| clave_unidad | string(6) | Codigo SAT unidad |
|
||||
| descripcion | text | Descripcion del concepto |
|
||||
| cantidad | decimal(18,6) | Cantidad |
|
||||
| valor_unitario | decimal(18,6) | Valor unitario |
|
||||
| importe | decimal(18,2) | Importe |
|
||||
| descuento | decimal(18,2) | Descuento |
|
||||
| created_at | timestamp | Fecha creacion |
|
||||
| updated_at | timestamp | Fecha actualizacion |
|
||||
|
||||
**Relaciones:**
|
||||
- `invoice()` - BelongsTo con Invoice
|
||||
- `prodServCode()` - BelongsTo con ProdServCode
|
||||
- `unitCode()` - BelongsTo con UnitCode
|
||||
|
||||
---
|
||||
|
||||
### InvoicePayment
|
||||
Pago de factura (complemento de pago PPD).
|
||||
|
||||
**Tabla:** `invoice_payments`
|
||||
|
||||
| Campo | Tipo | Descripcion |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | ID primario |
|
||||
| invoice_id | bigint | FK a invoice (CFDI de pago) |
|
||||
| doc_relacionado_uuid | string(36) | UUID factura pagada |
|
||||
| fecha_pago | datetime | Fecha del pago |
|
||||
| monto | decimal(18,2) | Monto pagado |
|
||||
| num_parcialidad | integer | Numero de parcialidad |
|
||||
| imp_saldo_ant | decimal(18,2) | Saldo anterior |
|
||||
| imp_pagado | decimal(18,2) | Importe pagado |
|
||||
| imp_saldo_insoluto | decimal(18,2) | Saldo insoluto |
|
||||
| created_at | timestamp | Fecha creacion |
|
||||
| updated_at | timestamp | Fecha actualizacion |
|
||||
|
||||
**Relaciones:**
|
||||
- `invoice()` - BelongsTo con Invoice
|
||||
|
||||
---
|
||||
|
||||
### Taxpayer
|
||||
Informacion del contribuyente.
|
||||
|
||||
**Tabla:** `taxpayers`
|
||||
|
||||
| Campo | Tipo | Descripcion |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | ID primario |
|
||||
| rfc_id | bigint | FK a rfcs |
|
||||
| nombre | string | Nombre o razon social |
|
||||
| tipo_persona | string | Fisica o Moral |
|
||||
| situacion | string | Situacion fiscal |
|
||||
| fecha_inicio_operaciones | date | Inicio de operaciones |
|
||||
| created_at | timestamp | Fecha creacion |
|
||||
| updated_at | timestamp | Fecha actualizacion |
|
||||
|
||||
**Relaciones:**
|
||||
- `rfc()` - BelongsTo con Rfc
|
||||
- `taxRegimes()` - BelongsToMany con TaxRegime
|
||||
- `economicActivities()` - BelongsToMany con EconomicActivity
|
||||
- `risks()` - BelongsToMany con Risk
|
||||
|
||||
---
|
||||
|
||||
### LinkedSocialAccount
|
||||
Cuenta social vinculada al usuario.
|
||||
|
||||
**Tabla:** `linked_social_accounts`
|
||||
|
||||
| Campo | Tipo | Descripcion |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | ID primario |
|
||||
| user_id | bigint | FK a users |
|
||||
| provider | string | Proveedor (clerk, google, etc) |
|
||||
| provider_id | string | ID en el proveedor |
|
||||
| created_at | timestamp | Fecha creacion |
|
||||
| updated_at | timestamp | Fecha actualizacion |
|
||||
|
||||
**Relaciones:**
|
||||
- `user()` - BelongsTo con User
|
||||
|
||||
---
|
||||
|
||||
## Modelos de Catalogos
|
||||
|
||||
### InvoiceType
|
||||
Tipos de comprobante fiscal.
|
||||
|
||||
| Codigo | Nombre |
|
||||
|--------|--------|
|
||||
| I | Ingreso |
|
||||
| E | Egreso |
|
||||
| T | Traslado |
|
||||
| N | Nomina |
|
||||
| P | Pago |
|
||||
|
||||
---
|
||||
|
||||
### PaymentMethod
|
||||
Metodos de pago.
|
||||
|
||||
| Codigo | Nombre |
|
||||
|--------|--------|
|
||||
| PUE | Pago en una sola exhibicion |
|
||||
| PPD | Pago en parcialidades o diferido |
|
||||
|
||||
---
|
||||
|
||||
### PaymentType
|
||||
Formas de pago (30+ tipos).
|
||||
|
||||
| Codigo | Nombre |
|
||||
|--------|--------|
|
||||
| 01 | Efectivo |
|
||||
| 02 | Cheque nominativo |
|
||||
| 03 | Transferencia electronica |
|
||||
| 04 | Tarjeta de credito |
|
||||
| ... | ... |
|
||||
|
||||
---
|
||||
|
||||
### Currency
|
||||
Monedas.
|
||||
|
||||
| Codigo | Nombre |
|
||||
|--------|--------|
|
||||
| MXN | Peso Mexicano |
|
||||
| USD | Dolar Americano |
|
||||
| EUR | Euro |
|
||||
| ... | ... |
|
||||
|
||||
---
|
||||
|
||||
### TaxRegime
|
||||
Regimenes fiscales.
|
||||
|
||||
| Codigo | Nombre |
|
||||
|--------|--------|
|
||||
| 601 | General de Ley Personas Morales |
|
||||
| 603 | Personas Morales con Fines no Lucrativos |
|
||||
| 605 | Sueldos y Salarios |
|
||||
| 606 | Arrendamiento |
|
||||
| 612 | Personas Fisicas con Actividades Empresariales |
|
||||
| 621 | Incorporacion Fiscal |
|
||||
| 626 | Regimen Simplificado de Confianza |
|
||||
| ... | ... |
|
||||
|
||||
---
|
||||
|
||||
### Tax
|
||||
Impuestos.
|
||||
|
||||
| Codigo | Nombre |
|
||||
|--------|--------|
|
||||
| 001 | ISR |
|
||||
| 002 | IVA |
|
||||
| 003 | IEPS |
|
||||
|
||||
---
|
||||
|
||||
### TaxRate
|
||||
Tasas de impuestos.
|
||||
|
||||
| Impuesto | Tasa |
|
||||
|----------|------|
|
||||
| IVA | 0.16 (16%) |
|
||||
| IVA | 0.08 (8% frontera) |
|
||||
| IVA | 0.00 (0%) |
|
||||
| ISR | Variable |
|
||||
| IEPS | Variable |
|
||||
|
||||
---
|
||||
|
||||
### Status
|
||||
Estados de factura.
|
||||
|
||||
| Codigo | Nombre |
|
||||
|--------|--------|
|
||||
| 1 | Vigente |
|
||||
| 0 | Cancelado |
|
||||
|
||||
---
|
||||
|
||||
### CancellationType
|
||||
Tipos de cancelacion.
|
||||
|
||||
| Codigo | Nombre |
|
||||
|--------|--------|
|
||||
| 01 | Con relacion |
|
||||
| 02 | Sin relacion |
|
||||
|
||||
---
|
||||
|
||||
### EconomicActivity
|
||||
Actividades economicas.
|
||||
|
||||
---
|
||||
|
||||
### Industry
|
||||
Industrias/sectores.
|
||||
|
||||
---
|
||||
|
||||
### Risk
|
||||
Riesgos fiscales.
|
||||
|
||||
---
|
||||
|
||||
### Dimension
|
||||
Dimensiones de empresa.
|
||||
|
||||
---
|
||||
|
||||
## Modelos de Codigos SAT
|
||||
|
||||
### ProdServCode
|
||||
Catalogo de productos y servicios SAT.
|
||||
|
||||
| Campo | Tipo | Descripcion |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | ID primario |
|
||||
| code | string(8) | Codigo SAT |
|
||||
| description | string | Descripcion |
|
||||
|
||||
---
|
||||
|
||||
### UnitCode
|
||||
Catalogo de unidades SAT.
|
||||
|
||||
| Campo | Tipo | Descripcion |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | ID primario |
|
||||
| code | string(6) | Codigo SAT |
|
||||
| name | string | Nombre de la unidad |
|
||||
|
||||
---
|
||||
|
||||
### PostalCode
|
||||
Codigos postales.
|
||||
|
||||
---
|
||||
|
||||
## Modelos Financieros
|
||||
|
||||
### SalesRevenue
|
||||
Ingresos por ventas.
|
||||
|
||||
---
|
||||
|
||||
### Expenditure
|
||||
Egresos/gastos.
|
||||
|
||||
---
|
||||
|
||||
### Conciliation
|
||||
Conciliaciones de facturas.
|
||||
|
||||
| Campo | Tipo | Descripcion |
|
||||
|-------|------|-------------|
|
||||
| id | bigint | ID primario |
|
||||
| invoice_id | bigint | FK a invoices |
|
||||
| fecha_conciliacion | datetime | Fecha de conciliacion |
|
||||
| usuario_id | bigint | Usuario que concilio |
|
||||
| created_at | timestamp | Fecha creacion |
|
||||
| updated_at | timestamp | Fecha actualizacion |
|
||||
|
||||
---
|
||||
|
||||
## Modelos Auxiliares
|
||||
|
||||
### ManagerOTP
|
||||
Gestion de One-Time Passwords.
|
||||
|
||||
---
|
||||
|
||||
### InvoiceRequest
|
||||
Solicitudes de facturas.
|
||||
|
||||
---
|
||||
|
||||
### Usage
|
||||
Usos de CFDI.
|
||||
|
||||
---
|
||||
|
||||
### Role
|
||||
Roles de usuario.
|
||||
|
||||
---
|
||||
|
||||
## Migraciones
|
||||
|
||||
El proyecto incluye 41 migraciones que crean toda la estructura de base de datos. Para ejecutarlas:
|
||||
|
||||
```bash
|
||||
# Ejecutar todas las migraciones
|
||||
php artisan migrate
|
||||
|
||||
# Revertir migraciones
|
||||
php artisan migrate:rollback
|
||||
|
||||
# Refrescar base de datos (elimina y recrea)
|
||||
php artisan migrate:fresh
|
||||
|
||||
# Ver estado de migraciones
|
||||
php artisan migrate:status
|
||||
```
|
||||
|
||||
## Seeders
|
||||
|
||||
```bash
|
||||
# Ejecutar todos los seeders
|
||||
php artisan db:seed
|
||||
|
||||
# Ejecutar seeder especifico
|
||||
php artisan db:seed --class=InvoiceTypeSeeder
|
||||
```
|
||||
|
||||
## Dump de Base de Datos
|
||||
|
||||
El archivo `horux360bd.sql` contiene un dump completo de la base de datos para importar:
|
||||
|
||||
```bash
|
||||
mysql -u usuario -p horux360bd < horux360bd.sql
|
||||
```
|
||||
Reference in New Issue
Block a user