HH/docs/REFERENCES_IMPLEMENTATION.md

# 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)

1. **`reference_dashboard`** - Main entry point showing:
   - Root folders
   - Recent documents
   - Statistics (total folders, total documents)

2. **`folder_view`** - Browse folder contents:
   - Shows subfolders
   - Shows documents
   - Breadcrumb navigation

3. **`folder_create`** - Create new folder:
   - Form with all folder fields
   - Parent folder option
   - Access control configuration

4. **`folder_edit`** - Edit existing folder:
   - Update folder details
   - Change parent folder
   - Modify access control

5. **`folder_delete`** - Soft delete folder (AJAX):
   - Mark folder as deleted
   - Documents in folder remain

6. **`document_view`** - Document details:
   - Document information
   - Version history
   - Related documents
   - Download button

7. **`document_create`** - Upload new document:
   - File upload
   - Metadata input
   - Folder selection
   - New version option

8. **`document_edit`** - Edit document:
   - Update metadata
   - Upload new file (optional)
   - Create new version option

9. **`document_delete`** - Soft delete document (AJAX)

10. **`search`** - Search documents:
    - Full-text search
    - Multiple filters
    - Pagination

## URLs

```python
# 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:

1. **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

2. **Document Access**: Similar to folder access
   - Inherits folder access if not restricted
   - Can have its own access restrictions

3. **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

1. Navigate to `/references/`
2. Click "New Folder" button
3. 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)
4. Click "Create Folder"

### Uploading a Document

1. Navigate to folder where you want to upload
2. Click "Upload Document" button
3. 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)
4. Click "Upload Document"

### Searching Documents

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

### Creating Document Versions

1. Go to document detail page
2. Click "Edit Document"
3. Check "Upload as new version"
4. Select new file
5. Click "Update Document"
6. Old version is marked as not latest
7. 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

1. **Folder Organization**
   - Use meaningful names in both languages
   - Keep structure simple and logical
   - Limit nesting depth (3-4 levels max)

2. **Document Management**
   - Use clear, descriptive titles
   - Add meaningful tags for searchability
   - Keep document versions organized
   - Archive old versions, don't delete

3. **Access Control**
   - Assign access roles at folder level for broad control
   - Use document-level access for sensitive files
   - Regularly review access permissions

4. **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

## Sidebar Navigation

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:

1. **Bulk Operations**
   - Bulk upload documents
   - Bulk move/copy folders
   - Bulk delete

2. **Advanced Search**
   - Full-text indexing with search engine
   - Document content search (PDF text extraction)
   - Saved search queries

3. **Integration**
   - Email documents directly from system
   - Generate document download reports
   - Integrate with external document storage (S3, etc.)

4. **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:**
1. User doesn't have hospital assigned → Check user.hospital
2. Access roles not configured → Check folder/document access_roles
3. Folder/document is inactive → Check is_active/is_published flags
4. Soft deleted → Check is_deleted flag

### Issue: File upload fails

**Possible causes:**
1. File type not supported → Check allowed_types in model.clean()
2. File size too large → Check Django settings for FILE_UPLOAD_MAX_MEMORY_SIZE
3. Insufficient permissions → Check media directory write permissions

## Technical Implementation

### File Upload Handling

Files are handled via Django's FileField with custom upload path function:
- Path includes hospital ID for segregation
- Date-based organization (YYYY/MM/DD)
- UUID-based filename for uniqueness

### Soft Delete

Both folders and documents use soft delete:
- `is_deleted` flag instead of actual deletion
- Maintains audit trail
- Allows recovery if needed

### Version Control

Documents support versioning:
- `parent_document` links to previous version
- `is_latest_version` indicates current version
- `version` string for semantic versioning

## Conclusion

The References section provides a comprehensive document management system with folder-based organization, role-based access control, version tracking, and full audit capabilities. It's simple and straightforward to use while providing powerful features for managing organizational documents.