add all files

shared-endpoint/.github/copilot-instructions.md

@@ -0,0 +1,29 @@
+# LASUCA Shared Endpoint – AI Guide
+
+## Architecture
+- Single PHP micro-endpoint; every request enters `public/index.php`, loads config, calls `Lasuca\SharedEndpoint\fetchLatestItems()` from `src/Database.php`, then JSON-encodes the payload.
+- No frameworks or Composer setup; stick to core PHP 8+ features already in use (`strict_types`, namespaced functions, `mysqli`).
+- Output contract is the canonical data feed for multiple dashboards; preserve field names (`status`, `metadata`, `items`) and the nested keys consumed by clients.
+
+## Data access
+- `fetchLatestItems()` opens a short-lived `mysqli` connection using the array returned by `config.php`; closes connections explicitly after the query.
+- Query targets the `items` table ordered by `ID`; schema is assumed to expose `ID`, `Name`, `Value`, and `Timestamp`. Add columns by extending both the `SELECT` statement and the array mapping.
+- Values are normalised before returning: `tagId` → int, `value`/`rounded1`/`rounded2` → float, `timestamp` stays as the DB-provided string. Keep these conversions when expanding the payload.
+
+## Configuration & caching
+- `config.php` reads environment variables (`LASUCA_DB_*`, `LASUCA_CACHE_TTL`) with sensible on-prem defaults; prefer overriding via env vars rather than editing the file.
+- `LASUCA_CACHE_TTL` controls both the config cache and the HTTP `Cache-Control` header (currently hard-coded to `1` second in `public/index.php`). Align these when making caching changes.
+
+## Response handling
+- Success responses include `metadata.generatedAt` as an ISO 8601 (UTC) timestamp via `gmdate(DATE_ATOM)` and `metadata.count` from `count($items)`.
+- Errors are caught in `public/index.php`: respond with HTTP 500 and a JSON body `{ "status": "error", "message": ... }`. Preserve this shape so clients can detect failure without parsing HTML.
+- Use `JSON_PRETTY_PRINT` when changing serialization to keep human-readable outputs during troubleshooting.
+
+## Local workflows
+- Serve locally from the parent directory with `php -S localhost:8081 shared-endpoint/public/index.php`; this mimics production routing without extra tooling.
+- Database connectivity is the only external dependency; mock or stub calls by swapping `fetchLatestItems()` for a fixture in tests or by wrapping the function in a seam.
+
+## Extension tips
+- When adding new endpoints, follow the same pattern: thin public script, shared logic in `src/` under the `Lasuca\SharedEndpoint` namespace, and configuration driven by env-aware arrays.
+- Keep new helpers free of side effects beyond DB reads so downstream caching remains predictable.
+- Document any new environment variables in both `config.php` comments and the top-level `README.md` so operators stay in sync.