feat: refine ISAC design and prepare production deployment
Validate and deploy production / validate (push) Successful in 18s
Validate and deploy staging / validate (push) Successful in 18s
Validate and deploy production / deploy (push) Successful in 1m1s
Validate and deploy staging / deploy (push) Successful in 28s

This commit is contained in:
JB
2026-07-26 12:25:47 -04:00
parent 75faef50b8
commit 2e868d86ff
153 changed files with 64660 additions and 264 deletions
+19 -54
View File
@@ -144,60 +144,25 @@ Use `npm run db:restore -- <backup-file>` only with an empty, migrated target
database. The restore script intentionally refuses to merge into a populated
database.
## Low-downtime database migration windows
## Development database maintenance
Friends and contributors may be actively entering game data in ISAC while
development continues. Treat dev-server availability and unsaved contributor
work as operational concerns whenever a schema change requires stopping the
embedded database.
The development server is no longer a shared contributor-facing service, so
development database work does not need to optimize for minimum downtime.
Database safety remains mandatory:
Use this sequence for every planned migration window:
1. Prefer additive, repeatable migrations and finish the migration logic before
operating on persistent data.
2. Identify the exact environment and database path, then inspect running
processes and stop only this project's development-server process tree.
3. Run and verify `npm run db:backup` before migration, export, restore, or
destructive schema work. Retain and report the backup path.
4. Apply the migration or maintenance operation and verify schema state, record
counts, and critical entities before restarting the server.
5. If an operation fails, preserve logs and the verified backup rather than
repeatedly improvising against the database.
6. Restart the development server when maintenance and useful verification are
complete, then confirm a basic health or page check.
### Prepare while the server remains online
1. Implement the application changes and the complete repeatable migration
before stopping the server.
2. Prefer additive, backward-compatible changes: new tables, new indexes, and
nullable or safely defaulted columns. Avoid table copies, column removal,
database recreation, or migrations that require the new application code to
become active before the schema is ready.
3. Make migrations idempotent by inspecting current schema state before each
alteration. The migration must be safe to rerun after interruption.
4. Batch related schema changes into one window instead of repeatedly stopping
the server during the same task.
5. Run `npm run check` and `npm run build` before the outage. Do not spend the
offline interval editing code, resolving type errors, building assets, or
performing ordinary UI review.
6. Identify the exact environment, database path, migration steps, verification
queries, and rollback/restore backup before stopping anything.
### Keep the offline window short
1. Do not start the window while a known contributor is in the middle of an
unsaved form or submission. When contributor activity is known, allow them
to finish or explicitly coordinate the interruption.
2. Inspect processes and stop only this project's dev-server process tree.
3. Run `npm run db:backup` immediately, verify that it completed, and retain the
reported backup path.
4. Run the already-prepared migration immediately after the backup.
5. Perform only critical database checks while offline: migration success,
expected columns/tables, record counts, and critical entity availability.
6. Restart the dev server as soon as the database is safe for application use.
Browser testing, extended regression checks, formatting, documentation
review, and noncritical diagnostics happen after service is restored.
### Failure and high-risk handling
1. If backup, migration, or critical verification fails, do not repeatedly
improvise against the live database. Preserve logs and the verified backup,
determine whether the existing schema is still safe, and either restart the
previous compatible application or follow the documented empty-database
restore procedure.
2. Separate destructive, data-rewriting, or predictably long migrations from
routine additive windows. Report that a maintenance window is required
before beginning one.
3. Do not claim the service is available until the restarted dev server passes
a basic health/page check.
4. In the handoff, report the backup path, migration result, server restart,
critical verification performed, and approximate offline interval when it
can be determined.
Production and staging remain persistent shared environments. Their deployment,
backup, synchronization, and maintenance safeguards are defined separately in
`docs/DEPLOYMENT.md`.