# Developer Guide

## Configuration first

`columns.json` is the source of truth for reportable Fidelity fields. Each reportable entry should include a column `name`, `category`, `title`, `description`, `reportable: true`, and optional `defaultSelected: true`.

Only selected names filtered through the JSON allowlist are inserted into SQL. Do not insert unvalidated request values into SQL identifiers.

## Reusable boundaries

- Keep `dbconn.php` focused on connection setup and `$pdo`; it should not emit HTML.
- Put generic PHP helpers in `report-functions.php`.
- Put UI behavior in `report-ui.js` and presentation in `report-ui.css`.
- Keep Fidelity table/date/id assumptions inside `fid.perf.php`.

## Date selection rules

- Standard ranges end at the newest available `fidCurDate` row.
- Custom dates choose the newest row on or before each requested date.
- The one-day option uses the immediately previous actual snapshot, allowing Monday to compare to Friday naturally.
- If a requested beginning date predates stored history, the oldest available record is used.

## Adding a field

1. Add the MySQL field to `columns.json` with `reportable: true`.
2. Reload Customize Report and select it.
3. Confirm the field exists and is numeric in `fidelity`.
4. Add it to defaults only if it should appear in a fresh report.

## Testing

- `php -l fid.perf.php`
- Open Report and Customize Report tabs.
- Test each range, particularly 1 day and custom dates.
- Test category Select all/Clear and global Select All/Clear.
- Test sort, expand/collapse, and narrow browser widths.