Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/debug/hallopetra-settings-500.md
T

109 lines
11 KiB
Markdown

---
status: awaiting_human_verify
trigger: "Investigate and fix the new generic HiveGrid HTTP 500, very likely on the HalloPetra/telephony integration settings path after PR #340 was deployed to staging."
created: 2026-08-01T22:52:09Z
updated: 2026-08-02T00:27:00Z
---
## Current Focus
hypothesis: confirmed; the live catalog backfill removes the staging module-not-found cause, and the status-preserving route boundary prevents its incorrect generic-500 presentation
test: open the tenant HalloPetra settings page once more with the original authenticated browser session
expecting: the page loads with HalloPetra API-key setup; no generic 500 appears, and a genuine unavailable-module state preserves HTTP 404
next_action: user refreshes the original authenticated workflow; all independently executable staging checks are complete
## Symptoms
expected: The tenant telephony integration page should load and allow HalloPetra API-key setup.
actual: The user sees the branded generic HiveGrid error page with HTTP 500.
errors: "HiveGrid / Fehler 500 / Etwas ist schiefgelaufen. Wir konnten deine Anfrage nicht abschließen. Bitte versuche es erneut oder kontaktiere den Support, falls das Problem weiterhin besteht."
reproduction: Exact URL/action was not provided. Recent context strongly suggests /:tenant/settings/integrations/telephony or opening/configuring HalloPetra. First establish the exact failing path from staging logs/Sentry or code evidence, then reproduce with focused tests.
started: First reported 2026-08-02, immediately after HalloPetra feature PR #340 (feature head 1643dd3ac6527621e1e95504505dadc6fdb62ff3; merge e7c6a138a77f82ffa58e768ba242301eaa99b79b) was deployed to staging. Staging health and ready endpoints are green at that revision.
## Eliminated
- hypothesis: the user's role is missing telephony permissions
evidence: all four telephony permission rows exist in staging; failure occurs earlier as module not_found
timestamp: 2026-08-01T23:01:00Z
- hypothesis: tenant RLS hides an existing telephony catalog feature
evidence: read-only staging inspection found zero telephony SubscriptionFeature rows globally, so there is no row for RLS to hide
timestamp: 2026-08-01T23:01:00Z
## Evidence
- timestamp: 2026-08-01T22:54:00Z
checked: assigned worktree, branch, working tree, required workspace paths, and forbidden US-provider imports
found: branch fix/hallopetra-500-20260802 is isolated at b6501b0e; only this debug file is untracked; package.json, apps, packages, and prisma exist; the forbidden-import scan returned no matches
implication: session isolation and structural pre-flight gates are satisfied, so baseline validation can proceed without overwriting unrelated work
- timestamp: 2026-08-01T23:01:00Z
checked: mandatory root typecheck and root test baseline at b6501b0e
found: typecheck passed; all 1,175 executed test files passed with 8,270 executed tests passing and 60 tests skipped
implication: the failure is not reproduced by the broad local baseline and is consistent with staging data/catalog drift plus an uncovered route error-normalization path
- timestamp: 2026-08-01T23:01:00Z
checked: staging web container logs for the reported request
found: the telephony loader repeatedly throws CatalogError foundation.not_found from loadTelephonyContext with status 404, i18nKey foundation.errors.notFound, and details { module: telephony }
implication: the exact failing path is the tenant telephony settings loader; the generic branded 500 is secondary incorrect error rendering, not the primary service status
- timestamp: 2026-08-01T23:01:00Z
checked: read-only staging catalog and permission rows
found: SubscriptionFeature contains zero telephony rows globally while all four telephony permission rows exist; the active public base plans starter, pro, and business each have 34 feature rows and no telephony row
implication: entitlement catalog drift, not role permission absence, makes every tenant resolve the telephony module as unavailable; a guarded forward-only catalog backfill is required
- timestamp: 2026-08-01T23:02:00Z
checked: persistent debug knowledge base and required debug-pattern references
found: no .planning/debug/knowledge-base.md exists; the common-pattern map classifies the local-versus-staging divergence as Environment/Config and the generic-500 mismatch as Error Handling
implication: there is no known-pattern shortcut; investigate catalog data flow and error normalization as two specific falsifiable mechanisms
- timestamp: 2026-08-01T23:14:00Z
checked: focused telephony route regression suite after status normalization
found: apps/web/app/routes/app.$tenant/telephony.routes.test.ts passes 6/6 tests, including loader and action CatalogError-to-404 Response cases
implication: the route boundary no longer promotes the known module-not-found condition to a generic HTTP 500
- timestamp: 2026-08-01T23:14:00Z
checked: generated Prisma client worktree drift after baseline typecheck
found: Prisma generation introduced only trailing-space diffs in Registration.ts and TenantProductConfiguration.ts; both generated files were restored exactly and no generated files remain modified
implication: verification can continue without contaminating the fix with unrelated generated output
- timestamp: 2026-08-01T23:18:00Z
checked: complete migration-history/schema parity verifier
found: the consolidated baseline audit passed and Prisma reported no difference after replaying the forward migration history with the restricted migrator role
implication: the new data migration does not introduce schema drift and is accepted by the production-shaped migration chain
- timestamp: 2026-08-01T23:24:00Z
checked: isolated PostgreSQL execution of the telephony catalog migration
found: canonical starter/pro/business plans received exactly one included telephony row; a second run remained at three rows; duplicate starter products aborted; an empty catalog succeeded with zero rows; SubscriptionProduct and SubscriptionFeature retained FORCE RLS
implication: the migration directly repairs the staging data shape while remaining idempotent, fail-closed on ambiguity, fresh-chain safe, and RLS-preserving
- timestamp: 2026-08-01T23:27:00Z
checked: permanent migration contract test and focused telephony route regression suite
found: 2 migration-contract tests and 6 route tests pass; the contract pins canonical codes, included entitlement shape, ambiguity/idempotency/empty-catalog guards, FORCE RLS preservation, and inverse SQL
implication: both root-cause mechanisms now have focused regression protection in the repository
- timestamp: 2026-08-01T23:28:00Z
checked: final root typecheck and lint after implementation
found: both commands completed successfully; Prisma regeneration produced only the two known comment-whitespace diffs, which were restored exactly
implication: the implementation is type-safe and lint-clean without generated-client contamination
- timestamp: 2026-08-01T23:28:00Z
checked: final Prisma validation, generated tenant-policy contract, and full migration-history/schema parity
found: Prisma schema is valid, the tenant policy contract passes 377/377 definitions, the consolidated migration audit passes, and Prisma reports no schema difference
implication: the bounded data migration is compatible with the production-shaped migration chain and does not alter the RLS policy contract
- timestamp: 2026-08-01T23:28:00Z
checked: final focused regressions and worktree diff hygiene
found: 2 test files pass with 8/8 tests; git diff --check passes; no generated or unrelated files remain modified
implication: self-verification is complete and only staging deployment plus original-workflow confirmation remains
- timestamp: 2026-08-01T23:52:00Z
checked: final complete root test suite after rebasing onto the current main branch
found: all 1,176 executed test files passed with 8,275 executed tests passing and 60 tests skipped
implication: the regression fix introduces no failure in the repository-wide core test surface
- timestamp: 2026-08-02T00:23:00Z
checked: fix PR, protected checks, normal merge, and automatic staging deployment
found: PR #345 merged normally with feature-head ancestry preserved; all 11 required checks passed after one unrelated Traefik filesystem timeout passed on its isolated rerun; staging deploy run 11732 succeeded on merge revision f4b78178a
implication: the reviewed fix, migration, and web boundary are deployed from the exact verified revision
- timestamp: 2026-08-02T00:25:00Z
checked: public staging web/API health and readiness plus the live database migration/catalog/RLS state
found: web and API health/readiness return HTTP 200 on exact revision f4b78178a; the migration is recorded as finished; starter, pro, and business each have exactly one included telephony feature; SubscriptionProduct and SubscriptionFeature both retain enabled and forced RLS
implication: the original missing-entitlement condition is repaired in the live environment without weakening the tenant-isolation contract
- timestamp: 2026-08-02T00:26:00Z
checked: unauthenticated telephony route boundary and post-deploy web logs
found: the protected route returns the expected login redirect rather than HTTP 500; the current web container has no new telephony CatalogError, module-not-found, or HTTP-500 log line
implication: automated staging proof is complete; only the authenticated browser-session confirmation remains
## Resolution
root_cause: PR #340 shipped the telephony gate and provider implementation without a deploy-time SubscriptionFeature row for telephony on the canonical starter, pro, and business base plans. loadTelephonyContext therefore returned foundation.not_found for every tenant. The telephony settings loader/action did not convert that server-only CatalogError into a React Router Response, so production treated it as an unhandled loader error and rendered the generic HTTP 500 page instead of preserving status 404.
fix: Added a guarded forward-only migration that inserts exactly one included telephony feature for each canonical starter/pro/business active public base plan while keeping FORCE RLS enabled and aborting on product/feature ambiguity. Added a settings-route context adapter that converts CatalogError into a status-preserving Response for loader and action paths, with focused 404 regressions.
verification: Root typecheck and lint passed. The complete root suite passed with 1,176 test files and 8,275 tests; 60 tests were skipped. Prisma validate, tenant-policy contract (377/377), and migration/schema parity passed. Focused tests passed 8/8. An isolated PostgreSQL 16 harness verified the canonical backfill, idempotency, ambiguity abort, empty-catalog no-op, and FORCE RLS retention. PR #345 passed all 11 checks and deployed successfully through run 11732. Live web/API health and readiness match revision f4b78178a; the migration, three included entitlements, and forced RLS are present. Post-deploy logs are clean. The original authenticated browser workflow still awaits user confirmation.
files_changed: [prisma/migrations/20260801231000_telephony_entitlement_catalog/migration.sql, packages/db/src/telephony-entitlement-catalog-migration.test.ts, apps/web/app/routes/app.$tenant/settings/integrations/telephony.tsx, apps/web/app/routes/app.$tenant/telephony.routes.test.ts]