Skip to content

Document Management Module

Overview

The Document Management module provides document upload, staging approval flow, attachment download, requirement-policy lookup, and temporary URL retrieval.

Base route: - /api/v1/document

Route mounting is defined in: - app/api/v1/router.py using router = APIRouter(prefix="/api/v1") - include_router(document_router, prefix="/document", tags=["Document"])

Verification Basis

This document is rebuilt from direct code scan of: - app/api/v1/endpoints/document.py - app/services/document.py - app/services/object_storage_service.py - app/models/document.py

Reference inventories: - API Route Live Reference - API Route Documentation TODO

Full Controller to Service Trace (Every Document API)

Route Method Controller Permission Service Call Path Status
/file/add POST upload_file upload_file upload_staged_file Implemented
/file/get POST get_both_files get_file get_both_file_by_id_response Implemented
/fileIdentity/fetch POST fetch_identity_files get_file get_active_files_by_identity_id Implemented
/fileIdentity/list POST list_identity_documents view_documents fetch_documents Implemented
/fileIdentity/delete POST delete_identity_files delete_file delete_files_by_identity_id Implemented
/file/edit POST update_file edit_file update_staged_file Implemented
/file/stage POST stage_file stage_file stage_file_changes Implemented
/file/decline POST decline_file decline_file decline_staged_file Implemented
/file/dispose POST dispose_file dispose_file dispose_staged_file Implemented
/base/add POST upload_base_file upload_file upload_staged_base + optional stage_file_changes Implemented
/base/stage POST stage_base_file stage_file stage_file_changes Implemented
/attachment/download POST download_attachment empty permission key download_attachment_by_id Implemented with auth gap
/attachment/edit POST update_attachment edit_attachment pass Not implemented
/file/download POST download_file download_file download_file_attachments_by_id Implemented
/attachment/presigned-url POST get_attachment_presigned_url download_attachment get_presigned_url Implemented
/presigned/{token} GET download_presigned_document token-only LocalStorageProvider.validate_and_get_file Implemented
/fileType/fetch POST fetch_file_types fetch_file_types fetch_file_type Implemented
/file/fetch POST fetch_all_files add_file pass Not implemented
/requirement/fetch POST fetch_file_types_by_group empty permission key fetch_file_type_by_group Implemented with auth gap

Encryption and Storage Trace (Code-Verified)

Upload Path

  • upload_staged_file encrypts each uploaded file via encrypt_file_with_private_key and stores encrypted JSON payload using store_encrypted_document.
  • upload_staged_base does the same for base64 uploads.

Download Path

  • download_attachment_by_id retrieves encrypted payload via object storage (or legacy filesystem fallback), then decrypts via decrypt_file_with_private_key before response.
  • download_file_attachments_by_id decrypts each attachment before writing into zip output.

Presigned URL Path

  • get_presigned_url returns provider URL from storage service.
  • Local token download (/presigned/{token}) uses LocalStorageProvider.validate_and_get_file, which decrypts content before returning bytes.

Important Defect

  • LocalStorageProvider.get_presigned_url currently generates /api/v1/documents/presigned/{token} (plural), but document router is mounted under /api/v1/document (singular). This mismatch can break local presigned download links.

Service Function Coverage

Primary functions mapped from controllers: - Lifecycle and staging: upload_staged_file, upload_staged_base, update_staged_file, stage_file_changes, decline_staged_file, dispose_staged_file - Retrieval and download: get_both_file_by_id_response, download_attachment_by_id, download_file_attachments_by_id, get_presigned_url - Identity and list operations: get_active_files_by_identity_id, fetch_documents, delete_files_by_identity_id - Type and requirement lookups: fetch_file_type, fetch_file_type_by_group

Data Model Map

Source: app/models/document.py

  • FileType: Document type metadata and status.
  • Files: Committed document header linked to identity.
  • FilesStaging: Pending document header used in maker-checker flow.
  • Attachment: Committed attachment metadata (storage_path preferred, filepath legacy fallback).
  • AttachmentStaging: Pending attachment linked to staged file.
  • DocumentRequirements: Requirement policy by document group (size limits, extension allow-list, optionality, description item code).

Current Gaps and Risks

  • /attachment/edit is declared but unimplemented (pass).
  • /file/fetch is declared but unimplemented (pass).
  • /attachment/download uses empty permission key.
  • /requirement/fetch uses empty permission key.
  • Crypto implementation uses RSA private key object in both OAEP encrypt and decrypt calls; behavior should be reviewed for standards compliance and key-usage intent.