marwan/HH

ismail 97de5919f2 add reference and standard

2026-01-08 09:50:46 +03:00

12 KiB

Raw Permalink Blame History

References Section - Reference Documentation

Overview

The References Section is a file server system for managing reference documents with folder categorization. It provides a simple and straightforward way to store files and group them by folders, accessible by employees at any time.

Features

1. Folder Management

Hierarchical Structure: Create nested folders (folders within folders)
Bilingual Support: Names and descriptions in both English and Arabic
Customization: Icons and colors for visual organization
Access Control: Role-based access control per folder
Soft Delete: Folders can be marked as deleted without actual removal
Ordering: Custom display order for folders

2. Document Management

Multiple File Types: Support for PDF, Word, Excel, PowerPoint, Images, and more
Version Control: Track multiple versions of the same document
Bilingual Titles: Document titles and descriptions in both languages
Tags: Comma-separated tags for easy searching
Access Control: Role-based access control per document
Download Tracking: Track how many times documents are downloaded
Publication Control: Documents can be published/unpublished

3. Search & Discovery

Full-text search across titles, descriptions, and tags
Filter by folder
Filter by file type
Filter by tags
Pagination for large result sets

4. Audit Trail

Track all document accesses (view, download, preview)
Log user actions with IP addresses
Track download counts and last accessed dates

Models

ReferenceFolder

Main folder model with the following fields:

name: English folder name (required)
name_ar: Arabic folder name (optional)
description: English description (optional)
description_ar: Arabic description (optional)
parent: Parent folder for nested structure
icon: FontAwesome icon class (e.g., 'fa-folder')
color: Hex color code (e.g., '#007bff')
order: Display order
access_roles: Groups that can access this folder
is_active: Active status
is_deleted: Soft delete flag
hospital: Hospital tenant (via TenantModel)

Key Methods:

get_full_path(): Get full folder path as breadcrumb
has_access(user): Check if user has access
get_subfolders(): Get immediate subfolders
get_documents(): Get documents in this folder
get_document_count(): Count documents including subfolders

ReferenceDocument

Document model with the following fields:

folder: Associated folder
title: English title (required)
title_ar: Arabic title (optional)
file: File upload
filename: Original filename
file_type: File extension (e.g., pdf, docx)
file_size: File size in bytes
description: English description (optional)
description_ar: Arabic description (optional)
version: Version string (e.g., '1.0', '1.1')
is_latest_version: Is this the latest version?
parent_document: Previous version reference
uploaded_by: User who uploaded
download_count: Number of downloads
last_accessed_at: Last access timestamp
is_published: Visibility status
access_roles: Groups that can access this document
tags: Comma-separated tags
metadata: Additional metadata (JSON)

Key Methods:

has_access(user): Check if user has access
increment_download_count(): Track downloads
get_tags_list(): Get tags as list
get_file_icon(): Get appropriate icon class
get_file_size_display(): Human-readable file size
get_version_history(): Get all versions

ReferenceDocumentAccess

Access log model for tracking:

document: Referenced document
user: User who accessed
action: Action type (view, download, preview)
ip_address: User's IP address
user_agent: Browser user agent

Views

UI Views (Server-Rendered)

reference_dashboard - Main entry point showing:
- Root folders
- Recent documents
- Statistics (total folders, total documents)
folder_view - Browse folder contents:
- Shows subfolders
- Shows documents
- Breadcrumb navigation
folder_create - Create new folder:
- Form with all folder fields
- Parent folder option
- Access control configuration
folder_edit - Edit existing folder:
- Update folder details
- Change parent folder
- Modify access control
folder_delete - Soft delete folder (AJAX):
- Mark folder as deleted
- Documents in folder remain
document_view - Document details:
- Document information
- Version history
- Related documents
- Download button
document_create - Upload new document:
- File upload
- Metadata input
- Folder selection
- New version option
document_edit - Edit document:
- Update metadata
- Upload new file (optional)
- Create new version option
document_delete - Soft delete document (AJAX)
search - Search documents:
- Full-text search
- Multiple filters
- Pagination

URLs

# Dashboard
/references/                    # Main dashboard

# Folders
/references/folder/<pk>/        # View folder
/references/folder/create/      # Create folder
/references/folder/<pk>/create/ # Create subfolder
/references/folder/<pk>/edit/   # Edit folder
/references/folder/<pk>/delete/ # Delete folder

# Documents
/references/document/<pk>/      # View document
/references/document/create/    # Upload document
/references/document/<pk>/create/ # Upload to folder
/references/document/<pk>/edit/ # Edit document
/references/document/<pk>/delete/ # Delete document

# Search
/references/search/             # Search documents

Access Control

The system implements role-based access control:

Folder Access: A folder can have specific access roles assigned
- If no roles assigned → Accessible to all users
- If roles assigned → Only users in those roles can access
Document Access: Similar to folder access
- Inherits folder access if not restricted
- Can have its own access restrictions
Cascade Effect: When accessing documents through folder navigation:
- User must have access to both folder AND document
- Document-specific access overrides folder access

File Storage

Files are stored with the following path structure:

references/<hospital_id>/YYYY/MM/DD/<uuid>.<ext>

Example:

references/1/2026/01/07/a1b2c3d4-e5f6-7890-abcd-ef1234567890.pdf

Usage Examples

Creating a Folder

Navigate to /references/
Click "New Folder" button
Fill in folder information:
- Name (English) - Required
- Name (Arabic) - Optional
- Description (English) - Optional
- Description (Arabic) - Optional
- Parent Folder - Optional (for nested folders)
- Icon - Optional (e.g., 'fa-folder')
- Color - Optional (e.g., '#007bff')
- Order - Optional (default: 0)
- Access Roles - Optional (leave empty for public)
Click "Create Folder"

Uploading a Document

Navigate to folder where you want to upload
Click "Upload Document" button
Fill in document information:
- Title (English) - Required
- Title (Arabic) - Optional
- File - Required
- Description (English) - Optional
- Description (Arabic) - Optional
- Version - Optional (default: '1.0')
- Access Roles - Optional
- Tags - Optional (comma-separated)
Click "Upload Document"

Searching Documents

Navigate to /references/search/
Use search/filter options:
- Search by text
- Filter by folder
- Filter by file type
- Filter by tags
Results are paginated

Creating Document Versions

Go to document detail page
Click "Edit Document"
Check "Upload as new version"
Select new file
Click "Update Document"
Old version is marked as not latest
New version becomes the current version

Templates

All templates are in templates/references/:

dashboard.html - Main dashboard
folder_view.html - Folder contents
folder_form.html - Create/edit folder
document_view.html - Document details
document_form.html - Upload/edit document
search.html - Search results

Forms

ReferenceFolderForm - Folder creation/editing
ReferenceDocumentForm - Document upload/editing
ReferenceDocumentSearchForm - Document search

Admin Integration

All models are registered with Django Admin:

ReferenceFolder - Full CRUD with inline actions
ReferenceDocument - Full CRUD with file preview
ReferenceDocumentAccess - Read-only access logs

File Upload Configuration

The system supports the following file types:

PDF (.pdf)
Word (.doc, .docx)
Excel (.xls, .xlsx)
PowerPoint (.ppt, .pptx)
Text (.txt, .rtf)
CSV (.csv)
Images (.jpg, .jpeg, .png, .gif)

Best Practices

Folder Organization
- Use meaningful names in both languages
- Keep structure simple and logical
- Limit nesting depth (3-4 levels max)
Document Management
- Use clear, descriptive titles
- Add meaningful tags for searchability
- Keep document versions organized
- Archive old versions, don't delete
Access Control
- Assign access roles at folder level for broad control
- Use document-level access for sensitive files
- Regularly review access permissions
File Uploads
- Keep file sizes reasonable (under 50MB recommended)
- Use PDF format for documents when possible
- Optimize images before uploading

Integration with Hospital System

The References section is fully integrated with the hospital tenant system:

Each hospital has its own set of folders and documents
Files are segregated by hospital ID
Users can only access their assigned hospital's references
Context processors ensure hospital context is always available

The References section is accessible from the sidebar:

Sidebar → References (icon: bi-folder)

This link navigates to /references/ (dashboard).

Future Enhancements

Potential improvements for future versions:

Bulk Operations
- Bulk upload documents
- Bulk move/copy folders
- Bulk delete
Advanced Search
- Full-text indexing with search engine
- Document content search (PDF text extraction)
- Saved search queries
Integration
- Email documents directly from system
- Generate document download reports
- Integrate with external document storage (S3, etc.)
Collaboration
- Document comments/annotations
- Document sharing links
- Workflow approvals for documents

Troubleshooting

Issue: Folder creation not refreshing

Solution: The folder_form template has been fixed to use correct field names:

name (not name_en)
description (not description_en)
Removed non-existent fields: visibility, tags

Issue: Can't see folders/documents

Possible causes:

User doesn't have hospital assigned → Check user.hospital
Access roles not configured → Check folder/document access_roles
Folder/document is inactive → Check is_active/is_published flags
Soft deleted → Check is_deleted flag

Issue: File upload fails