52 lines
4.3 KiB
Markdown
52 lines
4.3 KiB
Markdown
## Context
|
|
|
|
The platform already supports file and MySQL-backed metadata stores behind `repo.Store`. MySQL initialization is selected by `PLATFORM_STORAGE_BACKEND=mysql` and uses `PLATFORM_MYSQL_DSN`, but `platform/cmd/platform` calls `config.Load()` directly and `config.Load()` only reads process environment variables. A developer who edits `platform/.env` and starts the binary without sourcing that file still gets the default file-backed store.
|
|
|
|
The platform web shell currently embeds profile editing, theme palette selection, background presets, upload background, and logout inside the sidebar account popover. Those controls already call the current-user profile and theme APIs, but the interaction is cramped and visually hard to use.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Load repository-local `.env` values into platform configuration before storage initialization.
|
|
- Preserve process environment precedence over `.env` values so deployment systems can override local files.
|
|
- Keep profile and theme persistence backed by existing user APIs and the configured metadata repository.
|
|
- Replace the account popover editor with a dedicated personal settings page that is available to all authenticated users.
|
|
- Preserve the current magical crystal-moonlight shell style and shared surface classes.
|
|
|
|
**Non-Goals:**
|
|
- Add a normalized relational user schema or migrations beyond the existing MySQL metadata snapshot table.
|
|
- Add external account providers, billing, cloud host provisioning, or plugin marketplace workflows.
|
|
- Expose raw credentials, host paths, or direct run/plugin internals to the web UI.
|
|
|
|
## Decisions
|
|
|
|
1. **Load `.env` inside `platform/config`**
|
|
- `config.Load()` will call a small local dotenv loader before reading values.
|
|
- The loader will check common local paths such as `.env` and `platform/.env` relative to the current working directory.
|
|
- Existing process environment values win over file values.
|
|
- Alternative considered: requiring users to `source .env`. Rejected because the observed failure is that local `.env` exists but platform startup does not consume it.
|
|
|
|
2. **Keep MySQL persistence through the existing snapshot repository**
|
|
- The fix only makes backend selection reliable; it does not introduce normalized SQL tables for users.
|
|
- Profile and theme updates already flow through `UpdateUser`, which persists through `repo.Store`; this remains the single write path.
|
|
- Alternative considered: adding user-specific SQL tables now. Rejected because it is broader than the current bug and would duplicate the existing store abstraction.
|
|
|
|
3. **Move personal settings to a route instead of a popover**
|
|
- Add a `profileSettings` page id, route, registry entry, and page component.
|
|
- The sidebar account control becomes a navigation entry point to that page, with logout remaining available from the settings page.
|
|
- Theme controls move into the page but continue to use `theme/tokens.ts` helpers and the session store API methods.
|
|
- Alternative considered: converting the popover into a larger drawer. Rejected because the user specifically wants a normal personal configuration interface, and a page is more ergonomic for forms and preview grids.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Risk] `.env` parsing can accidentally override production environment values. → Mitigation: only set variables that are not already present in `os.Environ`.
|
|
- [Risk] Multiple working directories make `.env` discovery ambiguous. → Mitigation: try root `.env` and `platform/.env` from the process working directory, and use deterministic later-file fallback only for missing keys.
|
|
- [Risk] Uploaded background data URLs can be large. → Mitigation: preserve the existing client-side behavior and persistence API contract rather than expanding backend payload rules in this change.
|
|
- [Risk] Removing the popover editor changes a familiar access point. → Mitigation: keep the sidebar account button visible and route it directly to the new personal settings page.
|
|
|
|
## Migration Plan
|
|
|
|
1. Add dotenv loading tests that prove `platform/.env` selects MySQL settings and explicit process env overrides file values.
|
|
2. Add the personal settings route/page and update existing shell/session wiring to keep API-backed persistence.
|
|
3. Validate OpenSpec, backend config tests, frontend tests/typecheck/build, structure checks, and a browser walkthrough for the personal settings page.
|