peptide-repo/peptide-search-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: QA P1 findings on auto-schema-upgrade (v4.4.3)

Browse Source 
Addresses the three P1 findings from QA baseline review of a8a0ce2:

1. uninstall.php: delete psa_db_version option on plugin removal so no
   orphaned data is left behind — satisfies AGENT-OPERATING-STANDARD
   teardown/uninstall DoD.

2. Extract psa_upgrade_needed( $stored, $current ) as a pure function and
   add tests/unit/UpgradeTest.php covering fresh-install, same-version,
   future-version, and older-version scenarios. The impure wrapper
   psa_maybe_run_upgrades() now delegates the decision to the pure helper.

3. Document the psa_db_version option and the admin_init-triggered
   upgrade mechanism in ARCHITECTURE.md (Options section), including
   why admin_init, downgrade behavior, cleanup, and testability.

No behavioral change for end users — same upgrade semantics, just
testable and documented, with proper teardown.

Agent-Session: cowork-qa-p1-fixes-20260414
This commit is contained in:
peptiderepo
2026-04-14 19:09:49 +07:00
parent 3820bdfd28
commit 88a4ae9a4e
4 changed files with 119 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
ARCHITECTURE.md
View File

@@ -356,6 +356,22 @@ $psa_settings = array(
);
```
### Schema versioning & automatic upgrades
The plugin stores the schema version it last migrated to in a separate option, `psa_db_version`. This is distinct from `PSA_VERSION` (the running code's semver), and lets the plugin detect whether the database needs to catch up after an in-place file update.
- **Option name:** `psa_db_version` (string, semver).
- **Default:** `'0.0.0'` when the option has never been written (fresh install observed from the admin side before activation-time migration).
- **Writer:** `psa_maybe_run_upgrades()` in `peptide-search-ai.php`, called on every `admin_init`. The function:
1. Reads `psa_db_version`.
2. Calls the pure helper `psa_upgrade_needed( $stored, PSA_VERSION )`, which is a thin wrapper over `version_compare` (stored < current → upgrade).
3. If an upgrade is needed, re-runs `PSA_Cost_Tracker::create_table()` so `dbDelta` picks up any additive schema changes (new columns, new indexes).
4. Writes `update_option( 'psa_db_version', PSA_VERSION, false )` so the upgrade doesn't re-run on the next request.
- **Why on `admin_init`:** dbDelta is safe-to-repeat but not free. Running it once when an admin visits after an update — rather than on every frontend page load — keeps the cost near zero without requiring users to deactivate/reactivate the plugin.
- **Downgrade / rollback:** if the running code is older than `psa_db_version` (e.g., deploy rolled back), the function is a no-op. The newer schema is left intact; old code continues to work against it as long as changes are additive.
- **Cleanup:** `uninstall.php` deletes `psa_db_version` alongside the other plugin options.
- **Testability:** `psa_upgrade_needed()` is a pure function (no WordPress calls) and is covered by `tests/unit/UpgradeTest.php` across fresh-install, same-version, future-version, and older-version scenarios.
## Frontend Architecture
### JavaScript (jQuery-based)