ray-template/harness/fullstack-acceptance.md
XiaoDaiGua-Ray 0e688a34bf
feat(fullstack): complete account and session integration
Enforce live session grants for runtime routes and support profile and
credential updates in both the backend and demo modes.

Add the account settings workspace and document fullstack setup and PC
acceptance.
2026-11-06 21:39:36 +08:00

12 KiB

Fullstack PC acceptance plan

Scope: the optional backend, its Admin integration, the frontend-only Mock contract, and independent source setup. Acceptance uses one desktop Chrome session and disposable PostgreSQL, Redis, and Compose resources.

Baseline finding Implementation and acceptance
A clean install and external setup start the existing Admin and Nest app. Anonymous /admin/route-config returns nine root entries; only the editor view is protected. Local browser route preferences can bypass the server's runtime configuration. Authenticate the runtime snapshot and prune by live grants, inherited roles, view permissions, and demo policy. Drop empty groups and unusable redirects. Preserve the separate authorized editor snapshot. Inject only the current account's routes. Denied injected paths resolve as absent (404); reserved protected pages and API permissions still return 403.
Baseline login returns an opaque token to local storage. There is no self-service profile or password endpoint; the avatar entry is a placeholder. Account credentials require CLI access. Sign and verify bounded JWT sessions while keeping the PostgreSQL revocation boundary. Use an HttpOnly cookie for the bundled same-origin Admin and preserve explicit Bearer access for API clients and Mock. Add self profile, current-password verification, all-session revocation, and a separately authorized administrator credential action.
Setup is repeatable by username, so a renamed bootstrap account can cause a second privileged account to be created. Readiness only checks connections. Container startup requires a separate local setup command. Bootstrap once using the existing audit marker; preserve accounts, grants and route configuration across setup. Report uninitialized databases as unready. Provide a single Compose launch command and a runbook with external service, upgrade, secret, and troubleshooting instructions.
The local screen lock accepts a browser-stored password while the real API session remains active. Keep the local privacy screen for Mock. In real mode, locking revokes the current session and keeps the current address for reauthentication.

Plan review: The menu is not an authorization boundary. Protected data stays behind live endpoint checks, including writes inside transactions. The router must distinguish an intentionally empty snapshot from failed loading, and neither should select the packaged route list in server mode. The editor must still receive routes hidden by role or demo policy. Cookie transport requires a same-origin browser request and must not return the token in JSON. Credential changes must not permit self-promotion, target substitution, or use of the previous session. Upgrades may require a new login and signing secret, but must preserve database data and the frontend-only distribution.

Verification gates: full Harness; HTTP integration with real PostgreSQL and Redis (including denied requests and session races); desktop browser against real API with admin and limited accounts; extracted fullstack and frontend archives; actual Compose build, fresh start and smoke checks.

Acceptance results — 2026-11-06

Surface Observed result
Clean baseline Frozen install, external database migration and login passed. The anonymous runtime route request returned nine root records; self profile and password APIs were absent. The profile menu produced a placeholder in Chrome.
Full Harness 105 Vitest files, 546 tests, 13 server unit/platform tests with real Redis, types, lint, format, API/package boundaries, both site builds, and both distribution projections passed on Node.js 26.13.0 and pnpm 12.16.1.
Real HTTP 13 integration tests passed against temporary PostgreSQL and Redis. They cover bootstrap readiness, cookie attributes and CSRF, JWT signature and revocation boundaries, self-only profile fields, concurrent password changes, user CRUD and grants, pruned route trees, and enabled/disabled demos.
Desktop Chrome The production container preserved a protected deep link through sign-in. Admin updated profile data and saved routes; both persisted after reload and container rebuild. The read-only account could read users without write controls. With every child denied, the API returned routes: [] and the workspace showed no entries, while self profile remained usable. Removed routes, aliases, and redirects resolved to 404; fixed route management resolved to 403. Account disabling rejected the already-open session on its next protected navigation. Locking ended the session and kept the return path. The final console inspection returned no warnings or errors.
Credential UI Chrome displayed the self-service change form and the administrator credential dialog. Actual password changes, reset, concurrent writes and old-session invalidation were exercised by real HTTP tests; form submission, mismatch, error and retry behavior were exercised by frontend tests.
Fullstack archive and Compose A clean extraction built Linux arm64 images, generated private settings, migrated empty volumes, initialized an administrator, and served the production Admin. A second unparameterized launch reused the project and non-default port. The Compose smoke verified readiness, auth cookie transport, the protected route snapshot, profile, logout, demo gating, CORS and forwarded-IP rate limits.
Existing external services The extracted fullstack source upgraded the baseline database. Two setup runs preserved the renamed administrator and configured a signing key; the updated dev proxy authenticated the same account, rejected its old opaque token, and served enabled demos.
Frontend-only archive Frozen install and its full check passed outside the repository, without server dependencies. Chrome signed in through Mock and displayed the demo routes.

The browser scope was desktop Chrome only. Production HTTPS ingress, additional devices and themes, remote CI and public deployment were outside this run. Local logs are under .harness-local/fullstack-pc-acceptance/; full Harness report: .harness-local/runs/all-W6KuPc/report.json.