GSB-Construction/docs/PLAN.md

PLAN: Drawings & Documents Module Implementation

🎯 Goal

Implement a robust Drawings & Documents functionality within the standalone Modules/DocumentManagement module. This module will serve as the central repository for construction documents (CAD drawings, PDFs, BIM models, contracts, specs, schedules). It will feature file upload to local storage/database, version control, categorization, and an approval workflow governed by the Contractor Admin.

🔴 User Review Required

Please review the proposed schema and the plan.

• The documents will be stored using Laravel's local storage for now (as requested), and the metadata in the database.
• Approval workflow will enforce that uploaded documents are set to a "Pending" status and only a user with the Contractor Admin role can change them to "Approved".

🛠️ Proposed Changes

1. 🏗️ Database & Models (database-architect)

• DocumentCategory Model:
  • name (e.g., Site Plans, Floor Plans, MEP Drawings, Contracts, Specs)
  • description
• Document Model:
  • title, description, category_id, project_id, status (Pending, Approved, Rejected)
  • uploaded_by (User ID)
• DocumentVersion Model:
  • document_id
  • version_number (e.g., v1.0, v2.0)
  • file_path (Local storage path)
  • file_size, file_type
  • uploaded_by, uploaded_at
• DocumentApproval Model (Optional but good for audit logs):
  • document_id, approved_by (Contractor Admin ID), status, comments, approved_at

2. ⚙️ Backend (backend-specialist)

• DocumentController:
  • Standard resource methods for listing, creating, and deleting documents.
  • Integration with Laravel's local filesystem to store large files securely.
  • Implement versioning logic (uploading a new file to an existing document creates a new DocumentVersion).
• DocumentApprovalController:
  • Endpoints to approve or reject a document.
• Form Requests:
  • StoreDocumentRequest (validating file sizes, types).
  • ApproveDocumentRequest.
• Policies:
  • Restrict approval actions strictly to the Contractor Admin role.

3. 🎨 Frontend (frontend-specialist)

• Pages:
  • DocumentIndex: Data table/grid view of all documents, filterable by category, status, and project.
  • DocumentShow: Detailed view showing document metadata, history/version list, and a preview/download button.
  • DocumentUpload: Drag-and-drop file upload interface.
• Components:
  • ApprovalWorkflowComponent: UI for the Contractor Admin to review and approve/reject a document.
  • VersionHistoryTable: A sub-table inside the document detail view to track all revisions.

4. 🧪 Testing (test-engineer)

• Feature tests for document uploads and versioning.
• Authorization tests to ensure only Contractor Admins can approve documents.

5. 🔍 Security & Verification (security-auditor)

• Ensure proper file validation (prevent malicious file uploads like .php or .exe).
• Ensure local storage files are protected and served securely via authenticated routes, not public assets.
• Run security_scan.py and lint_runner.py at the end of orchestration.

❓ Open Questions

• None at this moment. The plan covers local storage, standalone module, and the Contractor Admin approval workflow.