refactor(client): unify web and desktop release workflow

2026-06-30 20:25:07 +08:00
parent d1a6c957f7
commit 7c721d4e5c
21 changed files with 1016 additions and 14 deletions
@@ -0,0 +1,89 @@
+# CTMS Web and Desktop Release Guide
+
+## Release Unit
+
+CTMS uses one repository, one promotion path, and one product version. Web and
+Desktop are build targets from the same source commit, not separately versioned
+products.
+
+The release identity consists of:
+
+- semantic version, for example `1.8.0`
+- Git tag, for example `v1.8.0`
+- full Git commit SHA
+- build channel: `dev`, `main`, or `release`
+- client type: `web` or `desktop`
+
+## Runtime Boundary
+
+Shared Vue business code lives under `frontend/src/`. Platform decisions are
+exposed through `frontend/src/runtime/index.ts`.
+
+The runtime contract currently provides:
+
+- API base URL resolution
+- Web, macOS, Windows, and Linux runtime identification
+- app version, source commit, build channel, and client type metadata
+- explicit capability flags
+- Desktop server address configuration
+
+Business modules must use this public runtime entry point. They must not inspect
+Tauri globals or import Tauri packages directly. Native files, notifications,
+secure session storage, and automatic updates remain disabled until their
+second-phase adapters are implemented and reviewed.
+
+## Version Change
+
+Update every client manifest with one command:
+
+```bash
+cd frontend
+npm run version:set -- 1.8.0
+npm run version:check
+```
+
+This synchronizes:
+
+- `frontend/package.json`
+- `frontend/package-lock.json`
+- `frontend/src-tauri/tauri.conf.json`
+- `frontend/src-tauri/Cargo.toml`
+- `frontend/src-tauri/Cargo.lock`
+
+Manual edits that leave these files inconsistent fail CI.
+
+## Promotion
+
+1. Merge feature branches into `dev`.
+2. Require the shared client/Web and macOS Desktop CI jobs to pass.
+3. Promote the accepted scope from `dev` to `main`.
+4. Set the release version and complete regression testing on `main`.
+5. Promote `main` to `release`.
+6. Create the matching `vX.Y.Z` tag on the accepted `release` commit.
+7. Build both Web and Desktop artifacts from that exact tag.
+
+Build metadata is injected by CI:
+
+```bash
+VITE_BUILD_CHANNEL=release
+VITE_BUILD_COMMIT="$(git rev-parse HEAD)"
+```
+
+These values support diagnostics but do not replace the semantic version.
+
+## Required Checks
+
+```bash
+cd frontend
+npm ci
+npm run version:check
+npm run runtime:check
+npm run type-check
+npm run test:unit
+npm run build
+npm run desktop:build -- --bundles app
+```
+
+The Desktop build must run on macOS for the current first-phase target. A signed
+or notarized public release additionally requires the Apple credentials defined
+by the release owner; an unsigned internal build is not a formal distribution.