From 8f81db0c5e12a9e3321a432af559d16d2f162cdf Mon Sep 17 00:00:00 2001
From: nano <nano@onefortheroadgit.local>
Date: Tue, 19 May 2026 12:05:24 +0000
Subject: [PATCH] Add user guide for the app

---
 docs/USAGE.md | 326 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 326 insertions(+)
 create mode 100644 docs/USAGE.md

diff --git a/docs/USAGE.md b/docs/USAGE.md
new file mode 100644
index 0000000..bb72ef9
--- /dev/null
+++ b/docs/USAGE.md
@@ -0,0 +1,326 @@
+# KCI Campaign Tracker — User Guide
+
+This guide explains how to use the Campaign Tracker application day to day.
+
+## What the app does
+
+Campaign Tracker helps you manage:
+
+- **Campaign Types** — templates or categories for campaigns
+- **Campaigns** — the main records you create and manage
+- **Job Types** — templates or categories for jobs
+- **Jobs** — work items connected to campaigns
+- **Customer Types** — templates or categories for customers
+- **Customers** — people or accounts tied to your workflow
+
+The dashboard gives you a quick overview of totals, recent items, and counts by type.
+
+---
+
+## Getting started
+
+### Open the app
+
+In the default Docker setup, open:
+
+- `http://localhost:8801`
+
+### Sign in
+
+If authentication is enabled, click **Login** and sign in through the configured **Keycloak** server.
+
+If you are running locally outside Docker, make sure your Keycloak values are set in your environment first.
+
+---
+
+## Main navigation
+
+The top navigation takes you to the main areas of the app:
+
+- **Home** — dashboard and quick stats
+- **Campaigns** — manage campaigns
+- **Campaign Types** — manage campaign definitions
+- **Jobs** — manage all jobs
+- **Job Types** — manage job definitions
+- **Customers** — manage customer records
+- **Customer Types** — manage customer definitions
+
+---
+
+## Typical workflow
+
+A common setup flow looks like this:
+
+1. Create **Campaign Types**
+2. Create **Job Types**
+3. Create **Customer Types**
+4. Create **Campaigns**
+5. Add **Jobs** to campaigns
+6. Create or update **Customers**
+
+You can work in a different order, but the type records usually come first because they define the available attributes for the main records.
+
+---
+
+## Dashboard
+
+The home page shows:
+
+- totals for each entity type
+- recent campaigns
+- recent customers
+- count breakdowns by type
+
+Use the dashboard to quickly jump into the area you need.
+
+---
+
+## Campaign Types
+
+Use **Campaign Types** when you want to define reusable campaign templates.
+
+### What you can do
+
+- view all campaign types
+- create a new campaign type
+- edit an existing campaign type
+- delete a campaign type
+
+### Why it matters
+
+Campaign types define the attributes that campaigns can use. For example, a campaign type might include fields like budget, owner, region, or status.
+
+---
+
+## Campaigns
+
+Use **Campaigns** to create and manage the main campaign records.
+
+### What you can do
+
+- view the campaign directory
+- create a new campaign
+- edit campaign details
+- delete a campaign
+- open the campaign’s job list
+- refresh the table
+
+### Campaign jobs
+
+Each campaign can have jobs attached to it. From the campaign view, you can:
+
+- see jobs for that campaign
+- import jobs from Google Sheets
+- import jobs from a file
+- filter jobs by the selected campaign
+
+---
+
+## Job Types
+
+Use **Job Types** to define reusable job templates.
+
+### What you can do
+
+- create a job type
+- edit a job type
+- delete a job type
+
+### Why it matters
+
+Job types define the attributes used when creating jobs. This makes it easier to keep job records consistent.
+
+---
+
+## Jobs
+
+Use **Jobs** to track work items across campaigns.
+
+### What you can do
+
+- view all jobs in the directory
+- create a new job
+- edit a job
+- delete a job
+- refresh the jobs table
+
+### Campaign-specific jobs
+
+You can also open the job list for a single campaign to focus on just that campaign’s work.
+
+---
+
+## Customer Types
+
+Use **Customer Types** to define reusable customer templates.
+
+### What you can do
+
+- create a customer type
+- edit a customer type
+- delete a customer type
+
+### Why it matters
+
+Customer types define the attributes available when you create customer records.
+
+---
+
+## Customers
+
+Use **Customers** to manage customer or account records.
+
+### What you can do
+
+- view all customers in the directory
+- create a new customer
+- edit a customer
+- delete a customer
+- refresh the table
+
+---
+
+## Data tables
+
+The list pages use interactive tables.
+
+Common table features include:
+
+- sorting
+- searching
+- row selection
+- drill-down into related records
+- refresh buttons
+
+If a table looks empty, try refreshing the page or the table itself.
+
+---
+
+## Importing jobs from Google Sheets
+
+The app includes import tools for campaign jobs.
+
+### Basic flow
+
+1. Open a campaign
+2. Open the campaign’s jobs page
+3. Provide a Google Sheets URL
+4. Choose the sheet and job type
+5. Run the import
+
+### What the importer does
+
+The importer looks for sheet columns that match the attribute names on the selected job type.
+
+If the headers do not match, the import can fail or skip rows.
+
+### Tips
+
+- Make sure the Google Sheet is accessible
+- Make sure the columns match the job type attributes
+- Use consistent header names
+
+---
+
+## Importing jobs from a file
+
+The campaign job page also supports file-based import.
+
+Typical steps:
+
+1. Open the campaign jobs page
+2. Choose a file source
+3. Pick the sheet or tab if needed
+4. Choose the job type
+5. Import the rows
+
+This is useful when the data already exists in a spreadsheet file instead of a published Google Sheet.
+
+---
+
+## Public API endpoints
+
+The app exposes a few public JSON endpoints:
+
+- `GET /api/customers`
+- `GET /api/customers/{id}`
+- `GET /api/customer-types`
+
+There is also an authenticated proxy endpoint:
+
+- `GET /api/proxy?url=https://example.com/data.json`
+
+The proxy requires login and only accepts valid `http` or `https` URLs.
+
+---
+
+## Health check
+
+You can verify the app is running with:
+
+- `GET /health`
+
+In the default Docker setup, that is:
+
+- `http://localhost:8801/health`
+
+---
+
+## Common troubleshooting
+
+### Login does not work
+
+Check the Keycloak settings in your environment:
+
+- `KEYCLOAK_BASE_URL`
+- `KEYCLOAK_REALM`
+- `KEYCLOAK_CLIENT_ID`
+- `KEYCLOAK_CLIENT_SECRET`
+- `KEYCLOAK_REDIRECT_URI`
+- `KEYCLOAK_LOGOUT_REDIRECT_URI`
+
+### Database errors on startup
+
+If migrations fail, wait a few seconds and try again. SQL Server may still be starting.
+
+### Empty or missing table data
+
+Run migrations and make sure the database is initialized:
+
+```bash
+docker compose exec campaign-tracker-app php scripts/migrate.php up
+```
+
+### Import errors
+
+If an import fails, check:
+
+- campaign exists
+- job type exists
+- sheet URL is valid
+- sheet headers match the selected type’s attributes
+
+---
+
+## Setup summary for local development
+
+```bash
+docker compose up -d --build
+docker compose exec campaign-tracker-app composer install
+docker compose exec campaign-tracker-app php scripts/migrate.php up
+```
+
+Then open:
+
+- `http://localhost:8801`
+
+---
+
+## Where to look in the code
+
+- `routes/web.php` — route definitions
+- `app/Controllers/` — request handling
+- `app/Repositories/` — database access
+- `app/Views/` — templates
+- `database/migrations/` — schema setup
+- `scripts/migrate.php` — migration CLI