stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

docs(integrations): archive startup migration recovery sprint

Browse Source
This commit is contained in:
master
2026-03-08 15:32:17 +02:00
parent 72c0613e74
commit f4b507b021
1 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
docs/implplan/SPRINT_20260307_007_Integrations_live_startup_migration_recovery.md
View File

@@ -1,80 +0,0 @@
# Sprint 20260307-007 - Integrations Live Startup Migration Recovery
## Topic & Scope
- Restore the live Integrations API used by Setup/Ops integration pages after Playwright QA exposed persistent `500` failures on `/api/v1/integrations*`.
- Replace the fragile startup schema bootstrap with the repo-standard startup migration host so fresh databases and reset volumes converge automatically.
- Verify the recovered service from the real Web UI on `https://stella-ops.local`, then hand the result back into the active Web QA loop.
- Working directory: `src/Integrations`.
- Expected evidence: targeted service build/restart, container log evidence, and live Playwright route checks for Setup integration pages.
## Dependencies & Concurrency
- Upstream Web QA evidence is tracked in `docs/implplan/SPRINT_20260306_003_FE_playwright_setup_reset_iteration_loop.md`.
- Safe parallelism: this sprint is limited to `src/Integrations` plus sprint documentation. Do not edit unrelated Web files from this sprint.
- Runtime dependency: `stellaops-integrations-web` must be rebuildable independently from the rest of the compose stack.
## Documentation Prerequisites
- `docs/modules/ui/architecture.md`
- `docs/code-of-conduct/CODE_OF_CONDUCT.md`
- `src/Integrations/AGENTS.md`
## Delivery Tracker
### INT-MIG-001 - Reproduce live integrations API failure
Status: DONE
Dependency: none
Owners: QA, Developer
Task description:
- Use authenticated Playwright against `https://stella-ops.local` to reproduce the failing Setup integrations list/detail routes.
- Capture the live API behavior and the matching container exception before changing service code.
Completion criteria:
- [x] Live reproduction exists for `/setup/integrations/secrets` and the underlying `/api/v1/integrations*` failure.
- [x] The service-side exception is captured with file/line evidence.
### INT-MIG-002 - Restore startup migrations for integrations schema
Status: DONE
Dependency: INT-MIG-001
Owners: Developer
Task description:
- Wire `AddStartupMigrations(...)` into the Integrations service using the persistence assembly that already embeds SQL migrations.
- Remove the ineffective schema bootstrap path so fresh installs rely on the canonical migration host.
Completion criteria:
- [x] Startup migrations are registered from the Integrations persistence assembly.
- [x] The service no longer relies on `EnsureCreatedAsync()` for schema convergence.
- [x] Service builds successfully with the new migration wiring.
### INT-MIG-003 - Rebuild, retest, and hand back to Web QA
Status: DONE
Dependency: INT-MIG-002
Owners: QA, Developer
Task description:
- Rebuild only the integrations service, restart it in the running compose stack, and confirm the missing table failure is gone.
- Replay the affected Setup integration routes in the real UI and record the post-fix state for the Web sprint.
Completion criteria:
- [x] `stellaops-integrations-web` restarts with successful startup migration logs.
- [x] Live Setup integration pages no longer fail because `integrations.integrations` is missing.
- [x] Findings are logged back into the Web sprint for continued route/action QA.
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-07 | Sprint created after Playwright QA on `https://stella-ops.local` proved Setup integration routes were failing outside Web scope. Live repro showed `/setup/integrations/secrets` and `/setup/integrations/int-secret-1` stuck on loading states while `stellaops-integrations-web` logged `42P01 relation "integrations.integrations" does not exist` from `PostgresIntegrationRepository` / `IntegrationService.ListAsync`. | QA |
| 2026-03-07 | Wired `AddStartupMigrations(...)` into `StellaOps.Integrations.WebService`, removed the host-level `EnsureCreatedAsync()` bootstrap, built the service, rebuilt `stellaops/integrations-web:dev`, and recreated only `stellaops-integrations-web`. Startup logs now show `Migration: Applied 1 migration(s) for Integrations.Persistence` on the first rebuilt container and `Database is up to date` on subsequent restarts. | Developer |
| 2026-03-07 | A second live failure surfaced immediately after the schema fix: authenticated Playwright still hit `500` with `42883: operator does not exist: text = integer` on `/api/v1/integrations`. Root cause was enum-backed `type/provider/status/last_health_status` EF mappings still comparing integer values against `text` columns. | QA |
| 2026-03-07 | Fixed the persistence model to store all enum-backed columns as `text`, regenerated the EF compiled model, and added focused persistence-model guard tests in `src/Integrations/__Tests/StellaOps.Integrations.Tests/IntegrationPersistenceModelTests.cs`. Targeted xUnit-v3 runner verification passed (`Total: 6, Errors: 0, Failed: 0, Skipped: 0`). | Developer |
| 2026-03-07 | Live retest against the rebuilt service confirmed the Integrations host now returns immediate `200` responses directly for `type=1`, `type=4`, and `type=5` queries when called on `integrations.stella-ops.local` with tenant context. Remaining spinner behavior was handed back to the Web sprint because the direct service was healthy and the stall only persisted on the authenticated `stella-ops.local` path. | QA |
## Decisions & Risks
- Decision: this sprint is limited to the Integrations service startup/migration failure and the minimum documentation needed to hand results back to Web QA.
- Decision: the proper fix must align with the repo-wide auto-migration requirement instead of patching databases manually.
- Decision: enum-backed persistence columns must use explicit string conversions because the canonical migration schema stores `type`, `provider`, `status`, and `last_health_status` as `text`.
- Risk: other agents may be editing unrelated Web sprint files in parallel.
- Mitigation: keep this sprint inside `src/Integrations` and record only cross-sprint evidence handoff.
- Risk: the authenticated `https://stella-ops.local/api/v1/integrations*` path can still stall even though the Integrations host answers immediately on its direct service alias.
- Mitigation: treat that as a frontdoor/Web-path defect and continue triage in `SPRINT_20260306_003_FE_playwright_setup_reset_iteration_loop.md`; do not expand this sprint into gateway/frontdoor changes.
## Next Checkpoints
- 2026-03-07: Land startup migration fix and rebuild only `stellaops-integrations-web`.
- 2026-03-07: Re-run live Playwright checks on Setup integration routes after the service restart.