Task App — Materials Catalogue and Job Material Usage¶

Goal¶

Add a lightweight materials system to the existing Task App.

The feature must provide:

• A dedicated materials catalogue.
• Admin and dispatcher management of catalogue materials.
• Material selection from job pages.
• Quantity-used recording by workers.
• A clear list of materials used on each job.

Keep the implementation simple and consistent with the existing application architecture:

• Plain PHP.
• PDO repositories.
• Server-rendered views.
• Existing authentication, role and CSRF helpers.
• Existing CSS and page structure.
• No framework or complex JavaScript dependencies.

---

1. Materials Catalogue¶

Create a dedicated materials catalogue available to:

• Admin users.
• Dispatcher users.

Workers must not have access to catalogue management pages.

Required routes¶

Add routes following the existing routing style:

• GET /materials
• GET /materials/create
• POST /materials/create
• GET /materials/{id}
• GET /materials/{id}/edit
• POST /materials/{id}/edit
• POST /materials/{id}/status

Catalogue fields¶

Each material must contain:

• Name — required.
• SKU or material code — optional.
• Unit — required.
• Description — optional.
• Active/inactive status.
• Created timestamp.
• Updated timestamp.

Example units:

• pcs
• m
• m²
• kg
• l
• pack
• roll

The unit should be entered as a short text value rather than managed through a separate unit catalogue.

Materials list¶

The materials list should show:

• Material name.
• SKU/code.
• Unit.
• Status.
• Actions.

Include:

• Search by material name or SKU/code.
• Filter by active/inactive status.
• Create material button.
• Link to material detail or edit page.

Do not permanently delete catalogue materials.

Materials must be activated or deactivated instead.

Inactive materials:

• Must remain visible in existing job material records.
• Must not be available for new job material selections.

Validation¶

Validate:

• Name is required.
• Unit is required.
• SKU/code may be empty.
• Material name should not consist only of whitespace.
• Quantity and catalogue data must be validated server-side.

Display validation errors using the application’s existing form error style.

---

2. Database Changes¶

Add a materials table.

Suggested structure:

materials
- id
- name
- sku nullable
- unit
- description nullable
- is_active
- created_at
- updated_at

Add a job_materials table for recording material usage.

Suggested structure:

job_materials
- id
- job_id
- material_id
- quantity
- recorded_by_user_id
- created_at
- updated_at

Requirements:

• job_id references jobs.id.
• material_id references materials.id.
• recorded_by_user_id references users.id.
• Quantity must support decimals, for example 1, 1.5, 12.75.
• Do not use database cascade deletion in a way that removes historical usage records.
• Existing job material records must retain their material association even if the catalogue material is inactive.

Update:

• database/schema.sql
• The existing database upgrade process.
• Seed data where appropriate.

Add the required database upgrade logic to:

bin/upgrade-database.php

The upgrade must be repeatable and safe to run on an already upgraded database.

---

3. Repository Layer¶

Create repository functions consistent with the existing repository style.

Suggested file:

app/repositories/materials.php

Include functions for:

• Listing materials with search and status filters.
• Finding a material by ID.
• Creating a material.
• Updating a material.
• Activating or deactivating a material.
• Listing active materials for dropdowns.
• Listing materials used on a job.
• Adding material usage to a job.
• Updating job material quantity where permitted.
• Removing a job material record where permitted.

Avoid putting raw SQL directly inside views.

---

4. Job Material Usage¶

Add a Materials Used section to both job detail pages:

• Admin/dispatcher job detail page.
• Worker job detail page.

Likely existing views:

app/views/jobs/show.php
app/views/work/show.php

The section must display:

• Material name.
• SKU/code when available.
• Quantity used.
• Unit.
• Recorded by.
• Recorded timestamp.
• Available actions.

Example:

Cable ties — 20 pcs
Installation cable — 12.5 m
Mounting bracket — 2 pcs

---

5. Worker Material Recording¶

Workers must be able to record materials on jobs assigned to them.

The form must contain:

• Material dropdown.
• Quantity used field.
• Add material button.

The dropdown must:

• Show active materials only.
• Show the material name.
• Show SKU/code when available.
• Show the material unit.

Example dropdown label:

Installation cable (CAB-001) — m

Worker permissions¶

A worker may add material usage only when:

• The job is assigned to that worker.
• The job is not cancelled.

Workers must not be able to:

• Manage the materials catalogue.
• Add materials to another worker’s job.
• Change catalogue material names, units or SKUs.
• Select inactive materials.

Workers may correct or remove a material usage record only while the job is still open.

Treat the following as closed states according to the current application’s existing status definitions:

• Completed.
• Cancelled.
• Any other existing final/closed status.

After the job is closed:

• Existing material usage remains visible.
• Workers cannot add, edit or remove material usage.

Use the application’s existing job ownership and role checks rather than duplicating authorization logic unnecessarily.

---

6. Admin and Dispatcher Permissions¶

Admins and dispatchers must be able to:

• View the materials catalogue.
• Create materials.
• Edit materials.
• Activate or deactivate materials.
• View materials used on any job.
• Add material usage to any job.
• Correct job material quantities.
• Remove an incorrectly recorded job material entry.

Admin and dispatcher corrections should remain possible after a job is completed, provided this is presented as an administrative correction.

Cancelled jobs should remain read-only for workers.

Keep the implementation straightforward; a separate audit log is not required in this task.

---

7. Job Material Routes¶

Add routes following the existing application routing conventions.

Suggested routes:

POST /jobs/{id}/materials
POST /jobs/{id}/materials/{jobMaterialId}/edit
POST /jobs/{id}/materials/{jobMaterialId}/delete

POST /work/jobs/{id}/materials
POST /work/jobs/{id}/materials/{jobMaterialId}/edit
POST /work/jobs/{id}/materials/{jobMaterialId}/delete

Alternative route names are acceptable when they fit the existing router better.

All create, edit, status and delete actions must:

• Use POST requests.
• Validate CSRF tokens.
• Check the current user’s role.
• Verify job access.
• Verify that the material usage record belongs to the specified job.
• Redirect back to the relevant job detail page.
• Display a success or error flash message.

---

8. Quantity Handling¶

Quantity must:

• Be required.
• Be greater than zero.
• Support decimal values.
• Reject invalid values.
• Be stored using an appropriate decimal database type rather than floating point.

Display quantities cleanly:

• 2.000 should display as 2.
• 2.500 should display as 2.5.
• 12.750 should display as 12.75.

Do not allow negative or zero quantities.

---

9. Duplicate Material Entries¶

When the same material is added more than once to the same job, use one consistent approach:

• Combine it into the existing job material entry by increasing the quantity.

Example:

Existing: Cable ties — 10 pcs
New entry: Cable ties — 5 pcs
Result: Cable ties — 15 pcs

Do not create multiple duplicate rows for the same material on the same job.

Add an appropriate unique database constraint where practical:

job_id + material_id

When combining quantities, update:

• Quantity.
• Recorded-by user.
• Updated timestamp.

---

10. Navigation¶

Add a Materials navigation item for:

• Admin users.
• Dispatcher users.

Do not show the catalogue navigation item to workers.

Workers access material recording through their assigned job detail pages only.

---

11. User Interface¶

Use the existing application styles and responsive behaviour.

Requirements:

• Catalogue pages should match existing Customers, Locations, Jobs and Users pages.
• The job material form should be compact.
• Material and quantity controls should appear side by side on wider screens.
• Controls may stack on mobile.
• Edit and remove buttons should appear inline where space allows.
• Empty state text:

No materials have been recorded for this job.

When no active catalogue materials exist, show an appropriate message instead of an empty dropdown.

Example:

No active materials are available.

Do not add a JavaScript framework.

Small vanilla JavaScript enhancements are acceptable only when genuinely necessary.

---

12. Security and Data Integrity¶

Ensure:

• All write actions require valid CSRF tokens.
• Catalogue management is restricted to admin and dispatcher roles.
• Worker access is restricted to assigned jobs.
• IDs from request paths and forms are validated.
• A job material entry cannot be edited through another job’s URL.
• Inactive materials cannot be added through manually crafted requests.
• Quantity validation is performed server-side.
• Output is escaped using the existing application helpers.
• Database operations use prepared PDO statements.

---

13. Files Likely to Change¶

Expected areas include:

public/index.php
app/repositories/materials.php
app/views/materials/
app/views/jobs/show.php
app/views/work/show.php
app/views/layouts/ or shared navigation files
public/assets/css/app.css
database/schema.sql
database/seed.sql
bin/upgrade-database.php
README.md

Use the actual project structure and naming conventions already present in the repository.

Do not restructure unrelated parts of the application.

---

14. Acceptance Criteria¶

The task is complete when:

1. Admins and dispatchers can open a dedicated materials catalogue.
2. Admins and dispatchers can create and edit materials.
3. Materials can be activated and deactivated.
4. Workers cannot access catalogue management.
5. Active materials appear in a dropdown on assigned worker jobs.
6. Workers can record a positive decimal quantity used.
7. Workers cannot record materials on jobs assigned to someone else.
8. Workers cannot add, edit or remove materials after the job is closed.
9. Admins and dispatchers can view and correct job material usage.
10. Inactive materials remain visible in historical job usage.
11. Inactive materials cannot be selected for new usage.
12. Adding the same material again increases the existing quantity.
13. Material quantities and units display clearly on both job detail pages.
14. All write actions use CSRF protection and role checks.
15. Database upgrades work on an existing installation.
16. Existing customers, locations, jobs, tasks, attachments, photos and authentication continue to work.

---

15. Testing¶

At minimum, manually test:

Catalogue¶

• Admin can create a material.
• Dispatcher can create a material.
• Worker receives 403 or the existing access-denied response.
• Required field validation works.
• Search works by name.
• Search works by SKU.
• Active/inactive filtering works.
• Deactivated material disappears from new job dropdowns.

Worker flow¶

• Assigned worker can add a material.
• Quantity 1 works.
• Quantity 1.5 works.
• Quantity 0 is rejected.
• Negative quantity is rejected.
• Invalid text quantity is rejected.
• Worker cannot add material to another worker’s job.
• Worker cannot add material to a completed job.
• Worker cannot edit or remove usage after job completion.
• Duplicate material selection increases the existing quantity.

Admin/dispatcher flow¶

• Admin can add material usage to any job.
• Dispatcher can add material usage to any job.
• Admin can correct a quantity.
• Dispatcher can remove an incorrect entry.
• Existing inactive materials remain visible on old jobs.

Regression checks¶

Verify that these still work:

• Login and logout.
• Dashboard.
• Tasks.
• Jobs.
• Calendar.
• Customers.
• Locations.
• Users.
• Worker job list.
• Attachments and photos.
• Database upgrade script.

---

16. Deployment Notes¶

Include any necessary production upgrade commands in the final implementation summary.

The expected server-side database upgrade command is:

cd /var/www/task-app
php bin/upgrade-database.php

Codex must provide:

• A concise implementation summary.
• Changed files.
• Database changes.
• New routes.
• Permission rules.
• Validation performed.
• Testing commands and results.
• Any deployment steps required.