Mix calculator

MIX-CALCULATOR.MD

@@ -0,0 +1,143 @@
+### Mix Calculator — Clean Feature Spec
+
+# Purpose
+The Mix Calculator allows authorised users to calculate the raw materials required for a client-specific product mix, based on a selected client, product, date, and batch size.
+
+It should also keep a history of each calculation session so users can review previous mixes without storing generated PDFs in the database.
+
+# Core Workflow
+
+- User opens Mix Calculator from the sidebar.
+User enters/selects:
+- Mix date (Defaults to today's date)
+- Client
+- Product - These should be populated from our existing products for that specific client
+- Specify Batch size in kilograms
+Total number of bags
+Staff name / prepared by
+App filters available products based on the selected client.
+User selects a product.
+App calculates:
+Required raw materials
+Required mix quantities
+Total kilograms
+Bag quantity details
+User can save the session.
+User can generate a polished PDF on demand.
+Sidebar
+
+# Add a dedicated sidebar item:
+
+Mix Calculator
+
+This should be separate from costing, product setup, or admin areas.
+
+# Permissions
+Create a dedicated permission area:
+
+mix_calculator:view
+mix_calculator:create
+mix_calculator:edit
+mix_calculator:delete
+mix_calculator:generate_pdf
+mix_calculator:view_all_sessions
+
+# Suggested roles:
+
+Role	Access
+Admin	Full access
+Manager	Create, view all, generate PDFs
+Staff	Create, view own sessions, generate PDFs
+Viewer	View only
+Database Naming
+
+Avoid the table name mix-calculator because hyphens are awkward in SQL and code.
+
+Use:
+
+mix_calculator_sessions
+
+Optional supporting tables:
+
+clients
+products
+product_mixes
+raw_materials
+mix_calculator_session_lines
+Suggested Tables
+mix_calculator_sessions
+
+Stores each calculator run.
+
+id
+session_number
+client_id
+product_id
+mix_date
+batch_size_kg
+total_bags
+total_kg
+prepared_by_user_id
+prepared_by_name
+created_at
+updated_at
+created_by
+status
+notes
+mix_calculator_session_lines
+
+Stores calculated raw material outputs for each session.
+
+id
+session_id
+raw_material_id
+raw_material_name
+required_kg
+mix_percentage
+unit
+sort_order
+
+This allows historical sessions to remain accurate even if the product recipe changes later.
+
+PDF Behaviour
+
+PDFs should not be stored in the database.
+
+Instead:
+
+Generate PDF on demand from the saved session.
+Use the saved session and session lines as the source.
+Allow download as:
+MixCalculator_{Client}_{Product}_{Date}_{SessionNumber}.pdf
+
+PDF should include:
+
+Date
+Client
+Product
+Batch size
+Total kilograms
+Total bags
+Prepared by / staff name
+Raw material table
+Required mix table
+Session number
+Generated timestamp
+Feature Name Options
+
+Recommended:
+
+Mix Calculator
+
+Other options:
+
+Batch Mix Calculator
+Production Mix Calculator
+Client Mix Calculator
+Mix Session Calculator
+
+Best fit: Mix Calculator.
+
+Clean Requirement Summary
+
+Build a dedicated Mix Calculator module that allows authorised users to create client-specific mix calculation sessions. Users select a date, client, product, batch size, total bags, and staff name. The system calculates required raw materials and mix quantities, saves the session history, and allows users to generate a polished PDF on demand. PDFs should not be stored in the database; they should be generated dynamically from the saved session data.