System → Maintenance - PR review

PR #291 by vsc55 · Issue #263 · Verdict: merge + fix

System → Maintenance is a new catalogue page for the tools that find data left behind and put it right. Each tool is a card with a count of what it has found right now - Found: 3 in amber, or Nothing found - and a search box filters the cards. Orphaned tickets is its first tool. This is the shape agreed on #263. User page: System § Maintenance. In-app help: System → Help → Maintenance.

How it is built

Piece	What it does
system/maintenance/includes/tools.php	The registry: getMaintenanceTools() (url, icon, title / desc / keywords keys, optional count function), maintenanceToolCount(), maintenanceCountOrphanedTickets()
system/maintenance/index.php	The catalogue, like Debug tools: runs each tool's count once as the page opens and draws a card per tool
system/includes/areas.php	The System landing shows Maintenance where Orphaned tickets was. Its area entry carries 'tools' => 'maintenance', and systemAreaKeywords() then adds each tool's title, description and keywords - so searching System for orphaned still finds the card that leads there
system/help/_registry.php, system/help/maintenance.php	A help page for Maintenance; helpCards() keeps each tool's own help card, straight after Maintenance's
system/orphaned-tickets/index.php	Keeps its URL, and gains a ← Maintenance link back
tests/system-maintenance.php	The registry, the counts, the search keywords and the help cards (part 2 only with a test database, in a rolled-back transaction)

What was checked

Question	How	Result
Who can open it?	Read; system/includes/page_gate.php	Admin-only, like Orphaned tickets and every System page except Preferences - the gate asks the database, not the session flag
Does the count agree with the tool?	Compared maintenanceCountOrphanedTickets() with api/system/get_orphaned_tickets.php	Same rule: a department_id with no department behind it, binned tickets left out
What if a count fails?	Read maintenanceToolCount()	It catches the error and returns null; the card then shows no count rather than the page failing (a table Database Verification has not made yet, say)
Do old links still work?	Read	system/orphaned-tickets/ and its help slug are unchanged
Does System search still find Orphaned tickets?	tests/system-settings-search/run.php	358/358
The new page's own test	tests/system-maintenance.php on the test install	22/22
Theming	Grepped every var(--x) in the page against theme.css	All exist; the amber count has its own dark-mode colours
Help language	Convention	System help pages are English-only by convention; the page strings are translated

What was changed

• #2811 - the PR's changelog row used id #2766, which another change had taken since the branch was cut. Renumbered to #2811.
• The page's 10 strings (system.landing.maintenance_*, system.maintenance.*) in the five complete languages (de, el, es, id, pl).

Merged with git merge --no-ff under the contributor's name (de8b16574), then the follow-up commit (d7cdd7f2a).

Worth knowing

• Adding a tool is one registry entry plus a help page keyed by the same slug in _registry.php. The card, the System search and the help card follow from the entry. Next per the PR: Imported people (#261, PR #264) moves under Maintenance.
• Counts run on every page open. A tool's count must be one cheap query. Something that needs a scan belongs on the tool's own page, not the card.
• A count must mean the same as the tool. If the rule in a tool's API changes, change its count function with it, or the card will say Nothing found while the tool lists items (or the reverse).
• Do not give a tool its own System card again. It is found through Maintenance and through the search keywords the 'tools' entry adds.