Codex Task — Manual Task Management Panel¶

Objective¶

Implement manual Task management in the existing lightweight Task App.

A Task represents an incoming customer request or overall piece of work that needs planning.

A Job represents one concrete scheduled field action, such as a visit, delivery, installation, inspection, or follow-up.

One Task may contain one or several Jobs.

Keep the implementation simple and consistent with the existing application:

• Plain PHP
• PDO
• MariaDB
• Server-rendered PHP views
• Existing CSS and application shell
• Existing authentication, role checks, CSRF protection, validation, flash messages, repository patterns, and routing style
• No framework or frontend dependency changes
• No API integration in this task
• No file uploads, photos, signatures, materials, calendar view, or other unrelated features

Before changing anything, inspect the existing repository, database schema, routes, repositories, helpers, and views. Reuse existing structures wherever practical.

---

1. Task Data Model¶

Review the existing tasks table and safely update it only where required.

A Task should contain:

• id
• task_number
• customer_id
• location_id, nullable
• title
• description, nullable
• status
• priority
• requested_date, nullable
• due_date, nullable
• created_by_user_id
• created_at
• updated_at

Use the existing timestamp conventions in the project.

Task number¶

Task numbers must be unique and generated automatically in this format:

TASK-000001
TASK-000002
TASK-000003

Use the same safe numbering approach already used for Job numbers.

Status values¶

Support these Task statuses:

• new
• planned
• in_progress
• completed
• cancelled

Default status:

new

Priority values¶

Support:

• low
• normal
• high
• urgent

Default priority:

normal

Relationships¶

• A Task belongs to one Customer.
• A Task may optionally belong to one Customer Location.
• A Task may have multiple Jobs.
• A Location selected for the Task must belong to the selected Customer.
• Existing Jobs should be capable of referencing a Task through task_id.

Do not use cascading deletion for Tasks, Jobs, Customers, Locations, or Users.

Do not add Task deletion. Tasks should remain as historical business records.

---

2. Database Compatibility¶

The application may already contain a tasks table or partial Task-related schema.

Do not blindly replace the database schema.

Update:

• database/schema.sql
• database/seed.sql
• any repeatable setup or migration-style logic currently used by the project

The database setup must continue to work for:

1. a clean database;
2. an existing development database where earlier tables already exist.

Where the project has no formal migration system, follow its existing lightweight upgrade approach.

Add appropriate indexes for:

• task_number
• customer_id
• location_id
• status
• priority
• due_date
• created_by_user_id

Add or update foreign keys consistently with the rest of the project.

---

3. Permissions¶

Admin¶

May:

• view all Tasks;
• create Tasks;
• edit Tasks;
• change Task status;
• create Jobs linked to Tasks;
• associate existing Jobs with Tasks where appropriate.

Dispatcher¶

Has the same Task permissions as Admin.

Worker¶

Workers must not have access to the administrative Task management panel.

Workers continue using the existing /work Job workflow.

Direct worker access to administrative Task routes must return the project’s existing 403 or safe access-denied response.

Do not expose Task data to unauthorised users.

---

4. Routes¶

Implement routes consistent with the existing router style.

Required routes:

GET  /tasks
GET  /tasks/create
POST /tasks
GET  /tasks/{id}
GET  /tasks/{id}/edit
POST /tasks/{id}/edit
POST /tasks/{id}/status

Also add a convenient Job creation route from a Task, either:

GET /tasks/{id}/jobs/create

or reuse the existing Job creation page with a query parameter such as:

GET /jobs/create?task_id={id}

Prefer whichever approach requires less duplicate code.

All state-changing routes must:

• use POST;
• require a valid CSRF token;
• validate permissions;
• validate the submitted Task;
• redirect using the existing flash-message pattern.

Invalid or missing Task IDs must use the existing 404 handling.

---

5. Task List Page¶

Create an Admin/Dispatcher Task list at:

/tasks

Use the existing application shell and table styling.

Display:

• Task number
• Title
• Customer
• Location
• Status
• Priority
• Requested date
• Due date
• Number of linked Jobs
• Last updated
• Action or detail link

Default ordering¶

Order Tasks so that operationally important items appear first:

1. overdue, non-completed and non-cancelled Tasks;
2. Tasks due today;
3. other Tasks with a due date, ordered by nearest due date;
4. Tasks without a due date;
5. completed and cancelled Tasks later in the list.

Within equivalent groups, use the most recently updated Task first.

Filters¶

Add simple server-side filters for:

• search;
• status;
• priority;
• customer;
• due state.

Search should match at least:

• Task number;
• title;
• customer name;
• location name or address where practical.

Due-state options:

• overdue;
• due today;
• upcoming;
• no due date.

Keep filters simple and use standard GET parameters.

Preserve relevant filter values after submission.

Visual indicators¶

Use the existing badge styles where possible.

Clearly indicate:

• urgent priority;
• overdue Tasks;
• due-today Tasks;
• completed Tasks;
• cancelled Tasks.

Do not add JavaScript-heavy table libraries.

---

6. Create Task Page¶

Create a Task form containing:

• Customer — required
• Location — optional
• Title — required
• Description — optional
• Status
• Priority
• Requested date — optional
• Due date — optional

Customer and Location behaviour¶

The selected Location must belong to the selected Customer.

Use the simplest pattern compatible with the existing application.

It is acceptable to:

• display all locations grouped or labelled by Customer; or
• use the same lightweight customer/location selection behaviour already used by the Job form.

Do not introduce a frontend framework.

On validation failure:

• show clear field errors;
• preserve submitted values;
• escape all output.

When creating the Task:

• generate the next Task number;
• save the logged-in Admin or Dispatcher as created_by_user_id;
• redirect to the new Task detail page;
• show a success message.

---

7. Edit Task Page¶

Allow Admins and Dispatchers to edit:

• Customer
• Location
• Title
• Description
• Priority
• Requested date
• Due date

Status may either be editable in the form or handled through the dedicated status action, depending on which is most consistent with the existing application.

Changing the Customer must invalidate a Location that does not belong to the newly selected Customer.

Do not allow editing the Task number.

Do not allow editing the creator or creation timestamp.

---

8. Task Status Handling¶

Support changing status through a POST action.

Valid statuses:

new
planned
in_progress
completed
cancelled

At minimum, prevent invalid or unknown status values.

Use practical status behaviour:

• a newly created Task starts as new, unless another valid status is explicitly selected;
• when the first active Job is created for a Task, the Task may remain new or be moved to planned;
• provide an explicit action for changing Task status;
• cancelled Tasks remain visible and read-only where appropriate;
• completed Tasks remain visible as historical records.

Do not automatically mark a Task completed merely because one linked Job is completed. A Task may contain several Jobs.

Do not implement complex workflow engines.

---

9. Task Detail Page¶

Create:

/tasks/{id}

Display the Task as the parent business record.

Task summary¶

Show:

• Task number
• Title
• Customer
• Location
• Status
• Priority
• Requested date
• Due date
• Description
• Created by
• Created timestamp
• Last updated timestamp

Customer and Location names should link to their existing detail pages where those pages exist.

Actions¶

For Admin and Dispatcher, include:

• Edit Task
• Change status
• Create Job for this Task

Do not show destructive deletion actions.

Linked Jobs section¶

Display every Job linked to the Task.

Show at least:

• Job number
• Job type
• Assigned worker
• Scheduled date and time
• Status
• Completion state
• Link to Job detail

Order linked Jobs by:

1. upcoming scheduled date;
2. unscheduled active Jobs;
3. completed or cancelled Jobs.

Show a clear empty state when no Jobs exist:

No jobs have been created for this task yet.

Include a prominent action:

Create first job

---

10. Link Jobs to Tasks¶

Update Job management so Jobs can be linked to a Task.

Job form¶

Add an optional or required Task selector according to the safest compatibility approach.

Preferred behaviour:

• New Jobs created from a Task detail page have the Task preselected.
• The Task’s Customer is preselected.
• The Task’s Location is preselected where available.
• The user may adjust the Job Location only to another Location belonging to the same Customer.
• The Job must not be linked to a Task belonging to a different Customer.

For existing standalone Jobs, preserve compatibility.

Do not break current Job creation, editing, worker workflow, dashboard, or existing data.

If task_id must remain nullable temporarily for existing Jobs, document this clearly in the README. New Jobs created through the Task flow should always receive a task_id.

Job detail page¶

Where a Job is linked to a Task, show:

Task: TASK-000001 — Task title

Link it to the Task detail page.

Add this to both the Admin/Dispatcher Job detail page and, where appropriate, the worker Job detail page.

Workers may see the Task number and basic Task context required to perform their assigned Job, but must not gain access to the administrative Task panel.

---

11. Navigation and Dashboard Integration¶

Replace the existing Tasks placeholder in the Admin/Dispatcher navigation with a working link to:

/tasks

Add a visible “New Task” action where appropriate.

Update the Admin/Dispatcher dashboard with a small operational Task panel.

Keep it compact and consistent with the existing dashboard.

The panel should show a limited number of Tasks requiring attention, such as:

• overdue Tasks;
• urgent open Tasks;
• Tasks due today;
• new Tasks without Jobs.

Each row should link to the Task detail page.

Do not redesign the complete dashboard in this task.

Do not fix unrelated visual-polish items, including the existing dashboard counter alignment issue.

---

12. Repository Layer¶

Follow the project’s existing repository structure.

Create or extend a Task repository with functions for:

• listing Tasks with filters;
• counting linked Jobs;
• finding a Task by ID;
• creating a Task;
• updating a Task;
• updating Task status;
• retrieving Jobs linked to a Task;
• generating the next Task number;
• retrieving dashboard attention Tasks;
• validating that a Location belongs to a Customer;
• retrieving Customers and Locations required by forms.

Use prepared PDO statements.

Avoid placing large SQL queries directly inside view files.

Avoid unnecessary abstraction or class hierarchies.

---

13. Validation and Security¶

Apply the same protections already used elsewhere in the application.

Required validation:

• Customer is required and must exist.
• Location is optional but must exist and belong to the selected Customer.
• Title is required, trimmed, and length-limited.
• Description is trimmed and length-limited.
• Status must be one of the allowed values.
• Priority must be one of the allowed values.
• Dates must be valid dates when supplied.
• Due date should not be earlier than requested date when both are supplied.
• Task number must be generated server-side.
• Creator must come from the authenticated session.
• All database writes require CSRF validation.
• All rendered content must be escaped.
• Workers must not access administrative Task routes.
• Invalid IDs must not expose database errors.

Use transactions where a multi-step write requires them.

---

14. Seed Data¶

Add useful Task seed data connected to existing Customers, Locations, Users, and Jobs.

Include examples of:

• a new Task with no Jobs;
• a planned Task with one scheduled Job;
• a Task with multiple Jobs;
• an urgent Task;
• an overdue Task;
• a completed Task;
• a cancelled Task.

Ensure the seed remains repeatable according to the existing project setup.

Do not create unrealistic volumes of test data.

---

15. README¶

Update the README to explain:

Business structure¶

Customer
└── Location
    └── Task
        └── Jobs
            └── Job notes

Also explain that a Task may belong directly to a Customer without a Location.

Definitions¶

Task = an incoming request or overall piece of work requiring planning.

Job = one concrete scheduled field visit or action assigned to a worker.

Relationship¶

One Task may create one or several Jobs.

Document:

• Task routes;
• Task statuses;
• Task priorities;
• permissions;
• how Jobs are linked to Tasks;
• any database upgrade command required;
• validation and testing commands.

Mention that API-created Tasks and Redmine integration are planned for a later task and are not implemented here.

---

16. Acceptance Criteria¶

The task is complete when:

1. Admins and Dispatchers can open /tasks.
2. Workers cannot access administrative Task routes.
3. Admins and Dispatchers can manually create Tasks.
4. Task numbers are generated in the TASK-000001 format.
5. Tasks can be searched and filtered.
6. Overdue and due-today Tasks are clearly identifiable.
7. A Task detail page displays its complete information.
8. A Task detail page displays all linked Jobs.
9. One Task can contain multiple Jobs.
10. A Job can be created directly from a Task.
11. The Task’s Customer and Location are prefilled during Job creation.
12. A Job cannot be connected to a Task belonging to another Customer.
13. Linked Job pages show their parent Task.
14. Existing Jobs and worker workflows continue to work.
15. The dashboard contains a compact Task attention panel.
16. All writes use POST and CSRF protection.
17. Invalid Task IDs return the existing safe 404 response.
18. Database setup works on a clean installation.
19. Existing development databases can be upgraded without manually dropping all tables.
20. The README accurately documents the Task → Jobs model.

---

17. Required Validation¶

Run all relevant project checks.

At minimum:

php -l public/index.php

Run php -l against every new or changed PHP file.

Also test manually:

Admin:
- Open Task list
- Search and filter Tasks
- Create a Task
- Edit a Task
- Change Task status
- Create a Job from the Task
- Open the linked Job
- Return to the parent Task

Dispatcher:
- Complete the same operational flow

Worker:
- Confirm /tasks is denied
- Confirm assigned Jobs still open normally
- Confirm linked Task context is visible without exposing admin Task controls

Validation:
- Submit missing title
- Submit invalid status
- Submit invalid priority
- Submit Location from another Customer
- Submit due date earlier than requested date
- Submit invalid CSRF token
- Open a missing Task ID

Confirm that existing pages still work:

/login
/dashboard
/customers
/locations
/jobs
/work
/users

---

18. Completion Report¶

When finished, provide:

1. A concise implementation summary.
2. Every changed or newly created file.
3. Database/schema changes.
4. Routes added or changed.
5. Task statuses and priorities implemented.
6. How Task-to-Job linking works.
7. Compatibility decisions for existing Jobs without a Task.
8. Validation commands executed and their results.
9. Manual tests performed.
10. Any limitations or follow-up items.

Do not report the task as complete unless the PHP syntax checks pass and the main Task → Job workflow has been tested.