water/docs/superpowers/plans/2026-07-01-app-version-check.md

App Version Check Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add an app-facing version check endpoint so the mobile app can compare its current version with the latest enabled app version record and prompt updates when they differ.

Architecture: Store version records in the new app_version table. AppController validates the request, asks IAppVersionService for the latest enabled record by platform, and returns whether an update is available.

Tech Stack: Spring Boot MVC, existing R<T> response wrapper, MyBatis Plus BaseMapperPlus, JUnit 5, Mockito, AssertJ.

Global Constraints

• Keep the endpoint under /app/v1.
• Use exact version equality: currentVersion differs from configured latestVersion means update is available.
• Store version data in app_version; do not use sys_config for this feature.
• Do not change unrelated schedule, MQTT, auth, or OSS upload behavior.

---

Task 1: Version Check Contract

Files:

• Modify: water-modules/water-app/src/test/java/org/dromara/app/controller/AppControllerTest.java
• Create: water-modules/water-app/src/main/java/org/dromara/app/domain/AppVersion.java
• Create: water-modules/water-app/src/main/java/org/dromara/app/domain/vo/AppVersionVo.java
• Create: water-modules/water-app/src/main/java/org/dromara/app/mapper/AppVersionMapper.java
• Create: water-modules/water-app/src/main/java/org/dromara/app/service/IAppVersionService.java
• Create: water-modules/water-app/src/main/java/org/dromara/app/service/impl/AppVersionServiceImpl.java
• Modify: water-modules/water-app/src/main/java/org/dromara/app/controller/AppController.java
• Create: script/sql/update/add_app_version.sql

Interfaces:

• Consumes: IAppVersionService.queryLatestByPlatform(String platform)

• Produces: AppController.checkVersion(String platform, String currentVersion): R<AppVersionVo>

• Produces: AppVersionVo fields platform, currentVersion, latestVersion, versionCode, updateAvailable, forceUpdate, downloadUrl, releaseNotes

• Step 1: Write failing tests

Add IAppVersionService as a mocked dependency and add tests for update available, no update, unsupported platform, missing current version, and missing version record.

• Step 2: Run tests and verify RED

Run:

mvn -pl water-modules/water-app -am "-DskipTests=false" "-Dmaven.test.skip=false" "-Dtest=AppControllerTest#checkVersion*" "-Dsurefire.failIfNoSpecifiedTests=false" test

Expected: compilation or test failure because IAppVersionService and table-backed implementation do not exist yet.

• Step 3: Implement minimal production code

Create AppVersion, AppVersionVo, AppVersionMapper, IAppVersionService, AppVersionServiceImpl, inject IAppVersionService into AppController, and keep GET /checkVersion.

• Step 4: Run targeted tests and verify GREEN

Run:

mvn -pl water-modules/water-app -am "-DskipTests=false" "-Dmaven.test.skip=false" "-Dtest=AppControllerTest#checkVersion*" "-Dsurefire.failIfNoSpecifiedTests=false" test

Expected: targeted version check tests pass.

• Step 5: Run compile/package verification

Run:

mvn -pl water-modules/water-app -am "-DskipTests" package

Expected: module and dependencies compile/package successfully.