National PF - Frappe/ERPNext Custom App

A comprehensive manufacturing and cost estimation system built on Frappe/ERPNext framework for National Paper Factory.

🚀 Features

📊 Estimate BOM (Bill of Materials)

Complete manufacturing cost estimation system with dynamic calculations, item creation, and comprehensive workflow management.

Core Functionality:

• Dynamic Cost Calculation: Real-time calculation of paper costs, consumables, operations, and overheads
• Automatic Item Creation: Creates finished goods items upon BOM submission
• Quotation Generation: Direct quotation creation from approved BOMs
• Multi-level Calculations: Cascading calculations across all cost components
• Status Management: Automated status tracking through complete workflow lifecycle
• Opportunity Integration: Bi-directional status updates with linked Opportunities

Calculation Components:

📄 Paper Details

• Weight Per PLY Calculation: (Size 1 × Size 2 ÷ 10000) × GSM
• Amount Calculation: Math.round(Weight Per PLY × Rate)
• Total Board GSM: Sum of all GSM values
• Total Weight Per PLY: Sum of all weight calculations
• Total Amount: Sum of all paper costs
• Rate Fetching: Automatic rate retrieval from Stock Settings → Item valuation

🔧 Consumables Details

• Item Group Filtering: Filters items by 'Consumable' group
• Minimum Quantity Control: Enforces qty ≥ 1
• Rate Auto-fetch: Stock Settings warehouse → Item valuation rate
• Amount Calculation: Qty × Rate
• Total Consumables: Sum of all consumable costs

⚙️ Operations Details

• Workstation Integration: Auto-fetches hour rates from Operation → Workstation
• Operating Cost Calculation: (Operation Time ÷ 60) × Hour Rate
• Total Operating Cost: Sum of all operation costs
• Time-based Costing: Supports minute-based time entry

💰 Over Head Details

Specific calculation formulas for different overhead types:

• Cost Of Paper: Total Amount (from Paper table)
• Consumables: Total Consumables Amount
• Direct Labour: Total Operating Cost
• Factory Overhead: Cost Of Paper × 3%
• Indirect Labour: Quantity Required × Total Weight Per PLY ÷ 1000 × 0.006
• Prime Cost: Sum of all overheads (excluding General Overhead)
• General Overhead: General Overhead Percentage × Prime Cost
• Total Cost: Prime Cost + General Overhead

Smart Features:

• Case-insensitive Overhead Matching: Handles "Labour" vs "Labor" spellings
• Cascading Updates: Changes trigger dependent recalculations
• Field Validation: Comprehensive error checking and user guidance
• Dynamic Field Visibility: Item code fields show/hide based on creation status
• Automated Status Workflow: Complete status lifecycle management
• Dashboard Message Management: Clear, non-duplicate status displays

🔄 Estimate BOM Workflow & Status Management

Complete Automated Workflow:

1. Draft → Initial state before submission
2. Submit Estimate BOM → Automatically:
   • Creates finished goods item (if not exists)
   • Creates and submits BOM automatically ✨
   • Sets status to "To Quotation"
   • Updates Opportunity status to "Quotation"
3. Create Quotation → Status stays "To Quotation" (BOM already exists)
4. Submit Quotation → Status changes to "To Sales Order" + Opportunity → "Converted"
5. Submit Sales Order → Status changes to "Completed"
6. Cancellation → Reverts appropriate statuses

Status Flow:

Draft → To Quotation → To Sales Order → Completed
         ↑              ↑
         |              |
    Estimate BOM    Quotation
     Submit         Submitted
     (BOM Auto-
      Created)

Opportunity Integration:

• On Estimate BOM Submit: Opportunity status → "Quotation"
• On Quotation Submit: Estimate BOM → "To Sales Order", Opportunity → "Converted"
• On Sales Order Submit: Estimate BOM → "Completed"
• On Estimate BOM Cancel: Opportunity status → "Open"
• Button Visibility: "Create Estimate BOM" button hidden when Opportunity is "Converted"

Automatic BOM Creation:

• Trigger: on_submit() - Automatically creates BOM after item creation
• Contents: All paper items, consumables, and operations from Estimate BOM
• Submission: BOM is automatically submitted
• Status Behavior: BOM submission does NOT change Estimate BOM status (hooks disabled)
• Status Changes: Only Quotation/Sales Order submissions trigger status updates
• Error Handling: Comprehensive logging; failures don't block Estimate BOM submission
• Validation: Ensures item exists before BOM creation

Critical Implementation Details:

• Execution Order:
  1. before_submit() → Creates item
  2. on_submit() → Sets status to "To Quotation" & auto-creates/submits BOM
  3. BOM hooks disabled → Status stays "To Quotation"
  4. Quotation submit → Triggers status → "To Sales Order"
• Status Persistence: Direct database updates with commit
• Override Class: Disabled in hooks.py - uses main doctype class
• Cache Management: Proper cache clearing ensures updates take effect
• Lifecycle Hooks:
  • before_submit(): Creates item and updates Opportunity
  • on_submit(): Sets status to "To Quotation" & auto-creates BOM
  • on_cancel(): Reverts Opportunity status to "Open"
  • on_update(): Only updates status for draft documents (docstatus == 0)

Active Hooks Configuration:

• BOM Hooks: ❌ Disabled (BOM auto-created but doesn't change status)
• Quotation Hooks: ✅ Enabled
  • on_submit: Estimate BOM → "To Sales Order", Opportunity → "Converted"
  • on_cancel: Estimate BOM → "To Quotation", Opportunity → "Quotation"
• Sales Order Hooks: ✅ Enabled
  • on_submit: Estimate BOM → "Completed"
  • on_cancel: Estimate BOM → "To Sales Order"

Workflow Logic: BOM is auto-created for manufacturing but doesn't affect sales workflow. Status changes only when Quotation/Sales Order are created, maintaining proper sales process tracking.

🔧 Production Planning & Work Order Integration

Production Plan Enhancements:

• Sales Order Reference Display: Shows linked Sales Order information in Production Plan list view
• Estimate BOM Linking: Maintains Estimate BOM references through production workflow
• Work Order Creation: Enhanced Work Order creation with automatic Estimate BOM transfer

Work Order Features:

• Header-level Estimate BOM: Custom field at Work Order header (not item level)
• Automatic Population: Estimate BOM automatically transferred from Production Plan during Work Order creation
• Estimate BOM Viewing: Direct link to view associated Estimate BOM from Work Order
• Dashboard Information: Shows linked Estimate BOM and source Production Plan details

Workflow Integration:

• Estimate BOM → Production Plan: References maintained during planning
• Production Plan → Work Order: Automatic Estimate BOM field population
• Multi-hook System: Multiple validation points ensure reliable data transfer
• Traceability: Complete audit trail from estimation to production execution

🎯 Item Management

Custom Item Fields:

• GSM (Grams per Square Meter): For paper specifications
• Size of CTN: Carton size specifications
• Weight/CTN: Carton weight specifications
• Custom Specifications: Detailed product specifications

Item Creation from BOM:

• Automatic Item Generation: Creates finished goods from BOM data
• Field Mapping: Maps BOM specifications to Item fields
• NPF Settings Integration: Uses default item groups from configuration
• Dual Field System: Separate input and link fields for better UX

📋 Quotation Integration

Server-side Quotation Creation:

• Complete Data Transfer: All customer, item, and pricing data
• Estimate BOM Linking: custom_estimate_bom field for traceability
• Read-only Field Handling: Force-sets fields using database operations
• Error Handling: Comprehensive validation and user feedback

Quotation Features:

• Customer Mapping: Proper party_name and customer_name fields
• Item Details: Complete item code, quantity, and specifications
• Pricing: Uses unit price from BOM as quotation rate
• Traceability: Direct link back to source Estimate BOM

⚙️ Configuration

NPF Settings

• Default Item Groups: Configurable item group assignments
• Paper Item Group: Filter for raw material items
• Finished Goods Group: Default for created items
• Warehouse Settings: Default warehouse for rate fetching

🛠️ Installation

cd $PATH_TO_YOUR_BENCH
bench get-app natinal_pf https://github.com/exvas/natinal_pf.git --branch main
bench install-app natinal_pf

Configuration:

1. Setup NPF Settings: Configure default item groups and warehouse settings
2. Create Item Groups: 'RAW MATERIAL', 'Consumable', and finished goods groups
3. Configure Overheads: Set up overhead types and calculation parameters
4. Setup Production Planning: Configure warehouses and production workflow settings

📖 Usage

Creating an Estimate BOM:

1. Basic Information: Customer, item code, specifications, quantity, paper dimensions
2. Paper Details: Add paper items with automatic rate fetching and weight calculations
3. Consumables: Add consumable items with quantity controls and rate auto-fetch
4. Operations: Add operations with workstation integration and cost calculations
5. Overheads: Add overhead types with automatic formula-based calculations
6. Submit: Automatically:
   • Creates finished goods item
   • Sets status to "To Quotation"
   • Creates and submits BOM (includes all paper, consumables, operations)
   • BOM submission updates status to "To Sales Order"
   • Updates linked Opportunity status

Automated Workflow:

The system now handles everything automatically when you submit an Estimate BOM:

1. ✅ Item Creation: Finished goods item created automatically
2. ✅ Status Update: Status set to "To Quotation"
3. ✅ BOM Creation: Complete BOM with all materials and operations
4. ✅ BOM Submission: BOM automatically submitted
5. ✅ Status Progression: Status updated to "To Sales Order"
6. ✅ Opportunity Sync: Opportunity status updated to "Quotation"

No manual BOM creation needed! Everything happens in one click when you submit the Estimate BOM.

Workflow & Status Management:

1. Estimate BOM Submission:

   • Item auto-created (if not exists)
   • Status → "To Quotation"
   • BOM auto-created and submitted
   • Status → "To Sales Order"
   • Opportunity → "Quotation" (if linked)

2. Quotation Creation: Use "Create → Quotation" button from submitted Estimate BOM

3. Estimate BOM Cancellation:

   • Status → "Cancelled"
   • Opportunity → "Open" (if linked)
   • BOM remains (can be cancelled separately)

4. Recovery Functions (if needed):

   • fix_estimate_bom_status_after_submit(): Fix all submitted BOMs with wrong status
   • fix_missing_item_for_estimate_bom(name): Create missing item for specific BOM
   • create_bom_from_estimate(name): Manually create BOM if auto-creation failed

Production Workflow:

1. Create Production Plan: Link to Sales Order and include Estimate BOM references
2. Generate Work Orders: Estimate BOM automatically transferred to Work Orders
3. Track Progress: Full traceability from estimation through production execution

Creating Quotations:

Use "Create → Quotation" button from submitted Estimate BOM for automatic data transfer and traceability.

🚀 Key Features Summary

• ✅ Complete Manufacturing Cost Estimation with dynamic calculations
• ✅ Automatic Item Creation from Estimate BOMs with custom specifications
• ✅ Automatic BOM Creation & Submission - fully automated on Estimate BOM submit
• ✅ Quotation Generation with full data transfer and traceability
• ✅ Production Planning Integration with Sales Order references
• ✅ Work Order Management with Estimate BOM linking at header level
• ✅ Multi-level Overhead Calculations with formula-based automation
• ✅ Real-time Rate Fetching from stock settings and item valuations
• ✅ Comprehensive Automated Workflow from estimation to BOM to production
• ✅ Automated Status Management with BOM and Opportunity integration
• ✅ Dashboard Message Control with duplicate prevention
• ✅ Error Recovery Functions for status and item creation issues
• ✅ One-Click Submission - Item, BOM, and status updates all automated

🔧 Troubleshooting

BOM Not Creating Automatically:

Cause: Cache not cleared after code changes
Solution:

cd /path/to/frappe-bench
bench --site your-site clear-cache
bench restart

Items Not Auto-Creating:

Cause: Error in item creation or validation failure
Solution: Check error logs and use fix function

bench --site your-site execute "natinal_pf.natinal_pf.doctype.estimate_bom.estimate_bom.fix_missing_item_for_estimate_bom" --args "['BOM-ID']"

BOM Creation Failed:

Cause: Missing materials or validation error
Solution: Manually create BOM using recovery function

bench --site your-site execute "natinal_pf.natinal_pf.doctype.estimate_bom.estimate_bom.create_bom_from_estimate" --args "['ESTIMATE-BOM-ID']"

Status Not Updating After Submit:

Cause: Cache issue or hook not triggered
Solution: Clear cache, restart, and check error logs

bench --site your-site execute "natinal_pf.natinal_pf.doctype.estimate_bom.estimate_bom.fix_missing_item_for_estimate_bom" --args "['BOM-ID']"

Override Class Issues:

Cause: Override class in /overrides/estimate_bom.py lacks methods
Solution: Override class is disabled in hooks.py (line 149 commented out). Main doctype class is used instead.

Quotation/Sales Order Hooks Not Working:

Cause: Hooks are disabled in hooks.py for stability
Solution: Uncomment lines 164-170 in hooks.py to enable, then clear cache and restart

🤝 Contributing

This app uses pre-commit for code formatting and linting:

cd apps/natinal_pf
pre-commit install

Pre-commit tools: ruff, eslint, prettier, pyupgrade

📄 License

MIT

🏢 About

Developed for National Paper Factory to streamline manufacturing cost estimation and quotation processes in Frappe/ERPNext environment.

---

System Requirements

• Frappe Framework v14+
• ERPNext v14+
• Python 3.8+
• MariaDB/MySQL