Initial commit of Descrybe v2 without local scratch artifacts.

Drop one-shot tmp/axe scripts and agent i18n scratch so the Gitea tree is deployable.
2026-08-09 22:47:43 +02:00
commit 8580c996c3
1285 changed files with 325780 additions and 0 deletions
@@ -0,0 +1,45 @@
+# Admin capabilities and diagnostics
+
+Platform admins use /admin/* (session + RequirePlatformAdmin). Support desk staff get ticket routes only (RequireSupportDesk).
+
+## Useful admin APIs
+
+| Path | Purpose |
+|------|---------|
+| GET /api/admin/diagnostics | Health: DB, queue, cache, storage, mail; config sanity (booleans only); recent job/AI failures |
+| GET /api/admin/analytics | Operational metrics dashboard data |
+| GET /api/admin/readiness | Cutover hypercare: must_set_password, companies without admin/plan |
+| GET /api/admin/jobs | Recent processing_jobs |
+| POST /api/admin/jobs/stuck-cleanup | Stuck running jobs cleanup |
+| GET/PUT /api/admin/settings | Platform settings (secrets masked on GET) |
+| GET/POST /api/admin/support/kb/articles | Support Knowledge CRUD |
+| GET/PUT /api/admin/support/auto-config | FAQ + AI auto-reply switchboard |
+| Users / companies / plans / credits | Org + billing admin |
+
+UI: /admin/support/knowledge; diagnostics and analytics under the admin shell.
+
+## Diagnose a stuck process
+
+```mermaid
+flowchart TD
+  A[Job stuck or failed] --> B{Worker running?}
+  B -->|No| C["Start: go run ./cmd/worker"]
+  B -->|Yes| D["GET /api/admin/diagnostics"]
+  D --> E{queue.failed or stuck_running?}
+  E -->|Yes| F["GET /api/admin/jobs + stuck-cleanup"]
+  E -->|No| G["Check /readyz + company credits"]
+  F --> H["Retry job or re-POST /products/process"]
+```
+
+### Checklist
+
+1. GET /healthz (liveness) and GET /readyz (Postgres + maintenance/read_only flags).  
+2. GET /api/admin/diagnostics — overall ok|degraded|fail; never expect secrets in the payload.  
+3. Confirm **worker** process is up (API alone does not drain processing).  
+4. Filter recent failures: ?status=failed&failures_limit=25.  
+5. Support auto AI: ticket auto_reply_status, /admin/support inbox flag=needs_human, AI role support under /admin/settings.  
+6. Cutover: GET /api/admin/readiness before DNS switch.
+
+Diagnostics intentionally excludes marketing charts — use analytics for trends, diagnostics for troubleshooting.
+
+Sources: apps/api/internal/httpapi/admin_diagnostics_handlers.go, server.go admin routes.