Documents module (documents)

The documents module in src/cluster_erp/modules/documents/ keeps controlled documents. A document has a type, may be linked to any record by entity type and id, and carries numbered versions. One version at a time is active; a new version becomes active either at once or through an approval chain. The module also provides the "documents attached to this record" capability that the web app finds by metadata.

At a glance¶

What the module does¶

• Keeps documents with a business code, a type, a title, translations, a description, and an optional link to any record through entity_type and entity_id (src/cluster_erp/modules/documents/documents/models.py:26-49).
• Keeps numbered versions per document; each version points to a file in the core attachments store (src/cluster_erp/modules/documents/documents/models.py:52-87). Storage is described on attachments, notes, and storage.
• Activates a version directly or after an approval chain decides, and marks the previous active version as superseded (src/cluster_erp/modules/documents/documents/services.py:255-337).
• Keeps document types with allowed file extensions and seeds a default set (src/cluster_erp/modules/documents/settings/models.py:11-28, src/cluster_erp/modules/documents/module.py:37-46).
• Answers other modules: the documents of a record, and the file behind a version (src/cluster_erp/modules/documents/module.py:98-149).

Sub-modules¶

Data model¶

Document codes come from the sequence document and version codes from document_version (src/cluster_erp/modules/documents/documents/services.py:110-111, src/cluster_erp/modules/documents/documents/services.py:208). A new version takes the next number after the highest live version (src/cluster_erp/modules/documents/documents/services.py:200-221).

Screens and metadata¶

get_metadata declares a sidebar group Documents (Turkish Belgeler) with a list section Documents and a settings section with the tab document_type (src/cluster_erp/modules/documents/module.py:232-265). The module publishes provides={"record_documents": {...}}, so the web client finds the record documents feature by capability, not by module name (src/cluster_erp/modules/documents/module.py:228-230). The record documents panel and the viewer are described on records, documents, viewer, and share.

Status and actions¶

A version is draft, active, superseded, or withdrawn (src/cluster_erp/modules/documents/documents/services.py:200-337). The diagram shows the version and approval chain.

flowchart TD
 V["DocumentVersion draft"] --> S["POST /versions/id/submit-approval"]
 S --> Q{"GetApprovalChainForAction: document_version, activate"}
 Q -->|no chain| ACT["DocumentVersionService.activate"]
 Q -->|chain| SUB["SubmitForApproval"]
 SUB --> AC["ApprovalCompleted event"]
 AC -->|final_status approved| ACT
 AC -->|other status| STAY["version stays draft"]
 V --> D["POST /versions/id/activate"]
 D --> ACT
 ACT --> SUP["previous active version: superseded"]
 ACT --> NEW["this version: active, approved_by, approved_at"]
 NEW --> W["POST /versions/id/withdraw: withdrawn"]

In prose:

1. A version starts as a draft. Only a draft can be edited or deleted (src/cluster_erp/modules/documents/documents/services.py:223-253).
2. Submit for Approval asks GetApprovalChainForAction for the resource document_version and the action activate. Without a chain, it activates the version at once. With a chain, it calls SubmitForApproval and the version stays a draft (src/cluster_erp/modules/documents/documents/routes.py:302-351).
3. When the auth module publishes ApprovalCompleted for a document_version with final_status approved, the handler reads the decider through GetApprovalRequestById and activates the version. Any other final status leaves it as a draft (src/cluster_erp/modules/documents/module.py:151-204).
4. Activate needs a draft with an attachment. It marks the current active version superseded, sets the new one active with the approver and time, and emits DocumentVersionSuperseded and DocumentVersionActivated (src/cluster_erp/modules/documents/documents/services.py:255-295, src/cluster_erp/modules/documents/documents/services.py:316-337).
5. Withdraw moves an active version to withdrawn (src/cluster_erp/modules/documents/documents/services.py:297-314).

Approval chains are described on approvals and approval chains.

Business rules¶

• A version without an attachment cannot be activated (src/cluster_erp/modules/documents/documents/services.py:269-274).
• At most one version per document is active; activation supersedes the previous one (src/cluster_erp/modules/documents/documents/services.py:316-337).
• Tenant field values in extra are validated on create (src/cluster_erp/modules/documents/documents/services.py:110-115). See tenant fields.
• GET /versions/{id}/file streams the file of the version from storage and answers not found when the file is missing (src/cluster_erp/modules/documents/documents/routes.py:240-268).
• Deleting a document or a draft version sets deleted_at; bulk delete uses the core soft-delete helper (src/cluster_erp/modules/documents/documents/services.py:150-162, src/cluster_erp/modules/documents/documents/services.py:241-253).

Events and queries¶

The module consumes 5 contracts and produces 6, counted as on the fleet module page. The full list is on the contracts reference.

ResolveDocumentVersionFile serves the intranet delivery download, and GetDocumentsForEntity serves the intranet "my documents" list (src/cluster_erp/modules/intranet/delivery/routes.py:143-150, src/cluster_erp/modules/intranet/my_documents/services.py:17-28).

Permissions¶

Privacy, retention, and history¶

privacy_handlers.py lists the documents filed against a person (entity type party). Anonymisation is an operator decision (include_documents); when included, the documents are retired, their title and description replaced, and the version files reported for removal (src/cluster_erp/modules/documents/privacy_handlers.py:1-9). See privacy and data-subject requests. The module has no retention_handlers.py. Changes are captured by change history.

Analytics facts¶

This module has no analytics_facts.py.

Settings and reference data¶

Document types are reference data. On start the module seeds the default set through DocumentTypeService.seed_defaults, and Seed Defaults runs it on demand (src/cluster_erp/modules/documents/module.py:37-46, src/cluster_erp/modules/documents/settings/routes.py:52-58). seed_data.py holds 15 default types, for example form, instruction, procedure, and technical_drawing, each with an English name and a Turkish translation (src/cluster_erp/modules/documents/settings/seed_data.py:1-113).

Tests¶

Found by name (web-client/_e2e_doc*.mjs, web-client/_e2e_record_docs.mjs) and by a grep for documents in tests/*.py.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Records, documents, viewer, and share
• Attachments, notes, and storage
• Intranet my documents
• API reference for this module

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