Records module (records)

The records module in src/cluster_erp/modules/records/ owns the lifecycle of records under the rule that nothing is deleted outright. It keeps the catalogue of deactivation reasons, offers generic endpoints to list deactivated records of any entity and to reactivate them, and keeps the retention window after which the daily purge removes deactivated rows for good (src/cluster_erp/modules/records/module.py:15-22). The deactivation mechanism itself is described on soft delete and deactivation.

At a glance¶

What the module does¶

• Keeps the deactivation reasons an administrator can choose when a record is removed from use (src/cluster_erp/modules/records/deactivation_reasons/models.py:9-32).
• Lists the deactivated records of any deactivatable entity, resolves labels of records that may be inactive, and reactivates a record (src/cluster_erp/modules/records/lifecycle_routes.py:1-10).
• Keeps the retention window in years and the evidence rows of each retention pass (src/cluster_erp/modules/records/retention/models.py:14-49).
• Provides purge_expired, the function that physically deletes deactivated rows and change history older than the window (src/cluster_erp/modules/records/retention/purge.py:1-7).

Sub-modules¶

Data model¶

Record lifecycle¶

flowchart TD
 L["live record"] -->|DELETE with reason| D["deleted_at, deleted_by, deactivation_reason set"]
 R["DeactivationReason catalogue"] --> D
 D --> H["core_change_history row"]
 D --> P["GET /records/module/entity/inactive"]
 P -->|POST .../record_id/activate| L
 D -->|older than retention_years| X["purge_expired: physical delete"]
 X --> E["RetentionRun evidence row"]

In prose:

1. A delete route of any module sets deleted_at. The central change-history hook stamps deleted_by and the reason from the request context, so no module threads the reason itself (src/cluster_erp/core/change_history.py:245-259). The change is written to the change history; see change history.
2. GET /records/{module}/{entity}/inactive lists the deactivated rows of an entity, newest first, after checking {entity}.read and the app entitlement of the module (src/cluster_erp/modules/records/lifecycle_routes.py:114-172).
3. POST /records/{module}/{entity}/{record_id}/activate checks {entity}.delete, clears deleted_at and deactivation_reason, and emits RecordActivated (src/cluster_erp/modules/records/lifecycle_routes.py:224-269).
4. Once a day the server runs the retention pass. It calls purge_expired with the configured window for every database the node serves, and emits RetentionSweep so modules drop their own time-window rows (src/cluster_erp/server/app.py:227-260, src/cluster_erp/server/app.py:404-460).
5. purge_expired deletes the files of expired attachments first, then every table with a deleted_at column, each in its own savepoint, then change history and the legacy audit_log older than the window. A foreign-key conflict on one table is logged and skipped (src/cluster_erp/modules/records/retention/purge.py:33-176).
6. Each pass that removed data writes a RetentionRun row; a failure to write it does not block the purge (src/cluster_erp/modules/records/retention/services.py:20-32).

Screens and metadata¶

The module has no sidebar group; the code states that it is surfaced from the web Settings screen (src/cluster_erp/modules/records/module.py:15-22, src/cluster_erp/modules/records/module.py:72). Its one entity is deactivation_reason (src/cluster_erp/modules/records/module.py:73-75). The web client offers the reason list when a record is deactivated (webapp/js/a11y-ui.js:156). Passive lists and reactivation in the web app are described on records, documents, viewer, and share.

Status and actions¶

The module declares no ActionMeta. Its state is the deleted_at column of other modules' records.

Business rules¶

• Only entities whose metadata declares a delete endpoint are deactivatable. resolver.py builds the map from module and entity to model once at start, with hand-verified overrides for irregular table names, and logs every entity it cannot resolve as an error (src/cluster_erp/modules/records/resolver.py:1-19, src/cluster_erp/modules/records/resolver.py:35-40).
• The retention window is clamped between 6 and 250 years (src/cluster_erp/modules/records/retention/models.py:14-16, src/cluster_erp/modules/records/retention/services.py:49-54).
• The purge skips core_change_history, deleted_records, alembic_version, and core_retention_config in the generic sweep (src/cluster_erp/modules/records/retention/purge.py:23-30).
• A reason marked requires_note asks for a free-text note in the web client; a server-side check of the reason code against the catalogue was not found outside the web client (webapp/js/a11y-ui.js:156).
• Deleting a reason sets deleted_at (src/cluster_erp/modules/records/deactivation_reasons/services.py:73-79).

Events and queries¶

The module consumes no contract and produces 1, counted as on the fleet module page.

RetentionSweep is emitted by the server with source_module="records", not by the package itself (src/cluster_erp/server/app.py:240). The full list is on the contracts reference.

Permissions¶

Privacy, retention, and history¶

The module has no privacy_handlers.py. It owns the retention window and the purge described above. The scheduling of the daily pass is on scheduled jobs and retention.

Analytics facts¶

This module has no analytics_facts.py.

Settings and reference data¶

• GET and PUT /records/retention/ read and set the window; a missing row is created with the default of 10 years (src/cluster_erp/modules/records/retention/routes.py:17-35, src/cluster_erp/modules/records/retention/services.py:39-47).
• The deactivation reasons are the module's reference data. A seed of reasons was not found in the package.

Tests¶

Found by a grep for /records/ in web-client/_e2e_*.mjs and for modules.records, /records/, or retention in tests/*.py.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Soft delete and deactivation
• Change history
• Logs module
• API reference for this module

Verified against commit 92f8051 on 2026-11-13.