Community Financial Movements and Ledger Management

The financial ledger in Comunidades Vecinos is built from Movimiento records. Every euro that enters or leaves the community is captured as a movement with a type, a date, an amount, and an optional link to the resident and receipt that originated it. The ledger is append-only: movements can be created but never deleted, which preserves a complete and tamper-proof financial history.

Movement Types

The TipoMovimiento enum contains two values:

INGRESO

Income. Created by an ADMIN to record a payment. When the movement includes a recibo reference, the service automatically marks that receipt as PAGADO. Can also be created without a receipt for non-fee income such as grants or room rentals.

GASTO

Expense. Created manually by an ADMIN to record community expenditure — maintenance work, cleaning services, insurance premiums, utilities, etc. The usuario and recibo fields are null for expense movements.

The Movimiento Entity

Field	Column	Type	Description
`id`	`id_movimiento`	`Long` (auto)	Primary key
`nombre`	`nombre`	`String`	Description / concept of the movement
`comunidad`	`id_comunidad` (FK)	`Comunidad`	The community this movement belongs to
`usuario`	`id_usuario` (FK, nullable)	`Usuario`	Resident linked to the movement (null for expenses)
`fecha`	`fecha`	`LocalDate`	Date of the movement
`importe`	`importe`	`BigDecimal`	Amount in euros (always positive)
`tipo`	`tipo`	`TipoMovimiento` enum	`GASTO` or `INGRESO`
`recibo`	`id_recibo` (FK, nullable)	`Recibo`	The receipt that originated this movement, if any

Linking a Receipt Payment to a Movement

When an ADMIN records an INGRESO movement and includes a recibo reference in the request body, the service automatically marks that receipt as PAGADO. This means the community ledger and the receipt status are kept in sync: creating the movement is the single action that records both the income and the payment.

ADMIN creates INGRESO Movimiento
    │  (with recibo reference in body)
    ▼
Movimiento saved ──────────────► Receipt marked PAGADO
                                    via reciboService.marcarPagado()

Only movements of type INGRESO may carry a recibo reference. Attempting to attach a receipt to a GASTO movement returns 400 Bad Request from the service layer.

Manual Expense Entry

ADMINs record community expenses by creating GASTO movements directly:

POST /api/movimientos
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "nombre": "Reparación portal principal",
  "fecha": "2025-06-15",
  "importe": 850.00,
  "tipo": "GASTO"
}

The community is resolved from the JWT — do not include it in the request body. The usuario and recibo fields are optional and can be omitted for pure expenses.

Querying Movements

Community ledger
My movements
Movement by ID
All movements (SUPER_ADMIN)

GET /api/movimientos/comunidad
Authorization: Bearer <user_or_admin_token>

Returns all movements for the authenticated user’s community. Available to both USER and ADMIN. This is the data source for the CuentasPage frontend, which groups movements by year and month and calculates a running balance.

[
  {
    "id": 101,
    "nombre": "Cuota ordinaria mayo 2025 - María García",
    "fecha": "2025-05-03",
    "importe": 105.00,
    "tipo": "INGRESO",
    "usuario": { "nombre": "María", "apellidos": "García López" },
    "recibo": { "id": 47, "estadoRecibo": "PAGADO" }
  },
  {
    "id": 98,
    "nombre": "Empresa limpieza — mayo",
    "fecha": "2025-05-01",
    "importe": 320.00,
    "tipo": "GASTO",
    "usuario": null,
    "recibo": null
  }
]

GET /api/movimientos/me
Authorization: Bearer <user_token>

Returns only movements linked to the authenticated user’s account. Useful for residents who want to verify their own payment history beyond what is shown in receipts.

GET /api/movimientos/{idMovimiento}
Authorization: Bearer <admin_token>

Returns a single movement. The backend verifies that the movement belongs to the ADMIN’s community; a 403 Forbidden is returned otherwise.

GET /api/movimientos
Authorization: Bearer <super_admin_token>

Returns every movement across all communities. Restricted to SUPER_ADMIN. Intended for platform-level auditing and reporting.

Dashboard Balance

The CuentasPage frontend calculates three summary figures from the movement list returned by GET /api/movimientos/comunidad:

Metric	Calculation
Total Ingresado	Sum of `importe` for all `INGRESO` movements
Total Gastado	Sum of `importe` for all `GASTO` movements
Saldo Actual	Total Ingresado − Total Gastado

Movements are then grouped by calendar year and month, each month showing its own income, expense, and net balance line, collapsed in an accordion for easy navigation.

Access Control Summary

Action	USER	ADMIN	SUPER_ADMIN
Read community movements	✅	✅	✅
Read own movements	✅	✅	—
Read movement by ID	—	✅	—
Create a movement	—	✅	✅
Read all movements (global)	—	—	✅
Delete a movement	❌	❌	❌

Movements cannot be deleted by any role. Once a financial record is created — whether automatically (from a paid receipt) or manually (an expense entry) — it is permanent. This is a deliberate design decision to preserve the integrity of the community’s accounting history.

Getting Started

Core Features

Configuration

Community Financial Movements and Ledger Management

Movement Types

INGRESO

GASTO

The Movimiento Entity

Linking a Receipt Payment to a Movement

Manual Expense Entry

Querying Movements

Dashboard Balance

Access Control Summary

Build docs developers (and LLMs) love

Getting Started

Core Features

Configuration

Documentation Index

​Movement Types

INGRESO

GASTO

​The Movimiento Entity

​Linking a Receipt Payment to a Movement

​Manual Expense Entry

​Querying Movements

​Dashboard Balance

​Access Control Summary

Build docs developers (and LLMs) love

Movement Types

The Movimiento Entity

Linking a Receipt Payment to a Movement

Manual Expense Entry

Querying Movements

Dashboard Balance

Access Control Summary