Frappe Enterprise Procurement App

bench get-app https://github.com/DivyaanshSingh843/frappe-enterprise-procurement-app

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=DivyaanshSingh843%2Ffrappe-enterprise-procurement-app)](https://frappegems.com/gems/apps/DivyaanshSingh843/frappe-enterprise-procurement-app)

# ERPNext Enterprise Module: Smart Procurement & Automated Workflow App > **GitHub Repository:** `frappe-enterprise-procurement-app` > **Tagline:** Production-grade Frappe Framework app extending standard ERPNext with custom DocTypes, automated multi-level approval workflows, department budget enforcement, server hooks, and whitelisted REST APIs. --- ## 🏗️ Architecture & Core Philosophy This application strictly follows **Frappe Framework Enterprise Best Practices**: core ERPNext source code remains completely unmodified. System capabilities are extended non-invasively through `hooks.py`, custom fields, fixtures, and controller overrides. ```mermaid graph TD A[User / Department Request] -->|Creates| B[Purchase Requisition DocType] B -->|Calculates Totals| C{Budget Validation Hook} C -->|Cost > Department Budget| D[Throw Budget Limit Exceeded Error] C -->|Within Budget| E[Workflow Engine] subgraph Multi-Level Approval Workflow E -->|State 1| F[Draft] F -->|Submit for Approval| G[Pending Manager Approval] G -->|Manager Approves| H[Pending Finance Approval] G -->|Manager Rejects| I[Rejected] H -->|Finance Approves| J[Approved - Submitted] H -->|Finance Rejects| I end J -->|Auto-Trigger on Submit| K[Create ERPNext Purchase Order] J -->|Whitelisted REST API| L[External Apps / Mobile Dashboard] K --> M[Linked Purchase Order DocType] ``` --- ## 🚀 Key Features ### 1. Data Modeling & Data Integrity * **Purchase Requisition (Parent DocType):** Submittable document tracking requestor, company, department, cost center, posting date, required-by date, total estimated cost, workflow state, and linked Purchase Order. * **Purchase Requisition Item (Child Table DocType):** Line items capturing item code, name, quantity, estimated unit rate, computed amount, warehouse, and preferred supplier. ### 2. Automated Multi-Level Approval Workflows * **Workflow States:** `Draft` ➔ `Pending Manager Approval` ➔ `Pending Finance Approval` ➔ `Approved` / `Rejected`. * **Role-Based Governance:** Role permissions enforce that only authorized roles (`Procurement User`, `Department Manager`, `Finance Manager`) can execute specific state transitions. * **Auto-Creation of Purchase Order:** Upon final approval submission (`Approved`), the Python controller automatically constructs and links a standard ERPNext `Purchase Order`. ### 3. Server-Side Controllers & Real-Time Budget Enforcement * **Budget Check (`before_submit` / `validate`):** Python controller checks allocated department budget (`Cost Center.custom_allocated_budget`) against committed expenditure plus current request amount using `frappe.db.sql`. * **Server Hooks (`hooks.py`):** Central event registry binding Python hooks to DocType events (`validate`, `on_submit`). ### 4. Whitelisted Enterprise REST APIs (`@frappe.whitelist()`) * **`procurement_app.api.get_department_budget_status`**: Returns allocated budget, committed spent, and remaining balance for a cost center. * **`procurement_app.api.create_po_from_requisition`**: Endpoint allowing external portals or custom buttons to trigger PO creation securely. * **`procurement_app.api.get_pending_approvals`**: Fetches actionable pending approvals filtered by the authenticated user's assigned roles. ### 5. Client-Side Form Enhancements & Jinja Print Formats * Dynamic JavaScript form logic (`public/js/`) for live item total calculation, company-level field filtering, and interactive `"Check Available Budget"` & `"Create Purchase Order"` custom actions. * Professional Jinja2 print format (`templates/print_formats/requisition_print_format.html`) for generating branded PDF purchase requisition reports. --- ## 📂 Repository Structure ```text frappe-enterprise-procurement-app/ ├── .github/ │ └── workflows/ │ └── ci.yml # GitHub Actions CI pipeline for linting & tests ├── procurement_app/ │ ├── __init__.py │ ├── hooks.py # Event hooks, JS/CSS assets injection, fixtures config │ ├── api.py # Whitelisted REST API endpoints (@frappe.whitelist) │ ├── procurement_app/ │ │ ├── __init__.py │ │ └── doctype/ │ │ ├── purchase_requisition/ # Parent Custom DocType │ │ │ ├── __init__.py │ │ │ ├── purchase_requisition.json │ │ │ ├── purchase_requisition.py │ │ │ ├── purchase_requisition.js │ │ │ └── test_purchase_requisition.py │ │ └── purchase_requisition_item/ # Child Table Custom DocType │ │ ├── __init__.py │ │ ├── purchase_requisition_item.json │ │ └── purchase_requisition_item.py │ ├── fixtures/ # Exportable Workflow & Custom Fields JSON │ │ ├── workflow.json │ │ ├── workflow_state.json │ │ ├── workflow_action_master.json │ │ └── custom_field.json │ ├── public/ │ │ ├── css/ # Custom badge & indicator styling │ │ │ └── procurement_app.css │ │ └── js/ # Extended JS logic for standard ERPNext forms │ │ └── purchase_order_extension.js │ └── templates/ │ └── print_formats/ # Jinja2 Print Format templates │ ├── requisition_print_format.html │ └── requisition_print_format.json ├── .gitignore ├── license.txt # MIT License ├── pyproject.toml # Modern Python packaging configuration ├── setup.py # Bench compatibility setup └── README.md ``` --- ## 💻 Code Highlights ### 1. Python Controller & Budget Enforcement (`purchase_requisition.py`) ```python def check_department_budget(self): if not self.cost_center: return allocated_budget = flt(frappe.db.get_value("Cost Center", self.cost_center, "custom_allocated_budget") or 0.0) if allocated_budget <= 0.0: return # No limit set committed_result = frappe.db.sql(""" SELECT SUM(total_estimated_cost) FROM `tabPurchase Requisition` WHERE cost_center = %s AND name != %s AND docstatus = 1 AND workflow_state = 'Approved' """, (self.cost_center, self.name or "")) committed_amount = flt(committed_result[0][0]) if committed_result and committed_result[0][0] else 0.0 projected_total = committed_amount + flt(self.total_estimated_cost) if projected_total > allocated_budget: frappe.throw(f"Estimated cost exceeds allocated budget of ₹{allocated_budget} for {self.cost_center}") ``` ### 2. Client-Side Form Logic (`purchase_requisition.js`) ```javascript frappe.ui.form.on('Purchase Requisition', { refresh: function(frm) { if (frm.doc.docstatus === 1 && frm.doc.workflow_state === 'Approved' && !frm.doc.purchase_order) { frm.add_custom_button(__('Create Purchase Order'), function() { frappe.call({ method: 'procurement_app.api.create_po_from_requisition', args: { requisition_name: frm.doc.name }, callback: function(r) { if (r.message) { frappe.set_route('Form', 'Purchase Order', r.message); } } }); }, __('Actions')).addClass('btn-primary'); } } }); ``` --- ## ⚡ Setup & Bench Installation Guide ### Prerequisites - Frappe Framework v14 or v15 bench instance installed. - ERPNext installed on the target site. ### Step-by-Step Installation ```bash # 1. Navigate to your frappe-bench folder cd ~/frappe-bench # 2. Get the app repository bench get-app https://github.com/divyansh/frappe-enterprise-procurement-app.git # 3. Install the app on your site bench --site site1.local install-app procurement_app # 4. Migrate database schemas and import fixtures bench --site site1.local migrate # 5. Build desk assets bench build --app procurement_app ``` ### Exporting Modified Fixtures ```bash bench --site site1.local export-fixtures ``` --- ## 🧪 Running Unit Tests Execute unit test cases for the procurement app using Frappe Bench: ```bash bench --site site1.local run-tests --app procurement_app ``` --- ## 📄 License Distributed under the **MIT License**. See `license.txt` for details.