From 2ebf9a0ef235099e7914ed78fcf9e8f86aaa9b97 Mon Sep 17 00:00:00 2001 From: Cyd Date: Wed, 1 Jul 2026 14:31:52 -0500 Subject: [PATCH] =?UTF-8?q?Doc:=20record=20the=202026-07-01=20improve-in-p?= =?UTF-8?q?lace=20pass=20(ARCHITECTURE=20=C2=A710)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 --- docs/ARCHITECTURE.md | 50 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index e935f2b..754bcff 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,6 +2,10 @@ Documentation generated from a full read of the codebase (2026-07-01). +> **Note:** §7 (known issues) and §9 (improve-in-place plan) describe the code as +> it was *before* the 2026-07-01 improvement pass. See **§10** for what has since +> been fixed and what remains. + ## 1. What this is PQS is a **player queueing and mission-management system for a pod-based @@ -268,4 +272,48 @@ layout (field order, delimiters) can only be inferred from the PHP. One part of the contract is already known and must be kept: `getFSplayers.php` **always returns exactly 16 lines** in fixed pod order, inactive pods zeroed rather than omitted, because the game console addresses all 16 positions positionally. -``` + +## 10. Improvement work completed (2026-07-01) + +An "improve in place" pass was executed against the plan in §9. All changes were +tested on a local WSL2 Ubuntu stack (PHP 8.3 / MariaDB; see `dev/`). + +**New infrastructure** +- `includes/db.php` — one shared mysqli connection + parameterized query helpers + (`pqs_db`, `pqs_exec`, `pqs_rows`, `pqs_row`, `pqs_val`); also the single + source of truth for `PQS_TIMEZONE`. Targets **PHP 7.4+** (mysqlnd). +- `includes/queue.php` — all seat-taking domain logic, serialized by a + `GET_LOCK` advisory lock and wrapped in transactions: + `pqs_enqueue_player`, `pqs_add_player_to_mission`, `pqs_add_player_to_missions`, + `pqs_enqueue_group`, `pqs_claim_group_slot`, `pqs_remove_player`. +- `dev/` — local test-stack setup + `migrations/` (001: queue+mission → InnoDB; + 002: currentmission+pastmissions → InnoDB). + +**§9 plan status** +1. **Mission-fill races — DONE.** Every writer (kiosk single/group, staff + new/add-multiple, delete, commit) goes through the shared lock + a + transaction; capacity is judged by real `COUNT(*)` and `numplayers` is + rewritten from it, so it can't drift or overfill. Verified with 120–140 + concurrent/mixed writers: zero overfill, zero drift. +2. **Parameterize + strip DEBUG — DONE for all user-input paths.** api.php + (also un-broke the info-panel refresh, whose JSON the DEBUG text was + corrupting), console.php, registration.php, history.php, search.php. +3. **Centralize DB / kill `mysql_*` — DONE.** db.php; 11 `mysql_error()` + landmines fixed; config.php unfetched-`pqs_pods` bug fixed. +4. **Timezone + pod loop — DONE.** Timezone centralized in db.php; the 16 pod + branches in console.php collapsed to loops (fixed 16 kept as the hardware + contract). + +**Deliberately not changed** +- `getFSgame.php` / `getFSplayers.php` — injection-safe already; their output is + the pod/AHK contract (see §4, `ahk/README.md`). Not refactored until the AHK + scripts are recovered and the exact format is confirmed. +- Internal display includes (`getqueue`/`getconsole`/`getcurrent`/`getreg`/ + `getgroup`) — read-only with internally-derived mission IDs; left on their + legacy connection (only `getgroup`'s `$_POST[group]` was int-cast). Converting + them to helpers is consistency-only. + +**Deployment prerequisites** +- Run migrations 001 and 002 against the `pqs` database. +- The new code targets **PHP 7.4+**. If the venue box is still PHP 5.4, upgrading + its PHP is the real prerequisite before deploying these changes.