golem15/summercms
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(14.2.1): create phase plan

Browse Source
This commit is contained in:
Jakub Zych
2026-10-06 11:22:45 +02:00
parent e723c391fb
commit f829d17dca
8 changed files with 1673 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
.planning/ROADMAP.md
View File

@@ -2,7 +2,7 @@
## Overview
v1 ports the Płytarium (fonoteka) headless PHP backend to a single Go binary without vue-fonoteka-app or fonoteka-mcp noticing. The journey starts with the smallest possible kernel plus a day-one parity harness, proves the whole stack on one real endpoint (`GET /_fonoteka/api/v1/genres`) before any further kernel design, then broadens outward: full data-layer fidelity, the three-auth-group HTTP layer, the user plugin, OAuth2.1 for MCP/ChatGPT, the admin schema pipeline and its Vue SPA, jobs/realtime/search infrastructure, the 154-route API surface (split into two delivery slices), domain jobs and external integrations, and finally a cutover phase where the parity harness is green on all 154 routes and both real clients run unchanged against the Go backend.
v1 ports the Płytarium (fonoteka) headless PHP backend to a single Go binary without vue-fonoteka-app or fonoteka-mcp noticing. The journey starts with the smallest possible kernel plus a day-one parity harness, proves the whole stack on one real endpoint (`GET /_fonoteka/api/v1/genres`) before any further kernel design, then broadens outward: full data-layer fidelity, the three-auth-group HTTP layer, the user plugin, OAuth2.1 for MCP/ChatGPT, the admin schema pipeline and its Vue SPA, jobs/realtime/search infrastructure, the 154-route API surface (split into two delivery slices), domain jobs and external integrations, a local Nuxt-on-Go dress rehearsal, the Journal plugin and a first blog (grzybyfunkcjonalne.pl) on reusable views, and finally production cutover of Płytarium where the parity harness is green on every manifest route and both real clients run unchanged against the Go backend.
## Phases
@@ -27,7 +27,10 @@ Decimal phases appear between their surrounding integers in numeric order.
- [x] **Phase 12: Płytarium API — Collections and Albums** - Core content endpoints ported with byte-level parity (completed 2026-10-02)
- [ ] **Phase 13: Płytarium API — wishlist, notifications, CSV, credentials, public routes** - Remaining core API surface
- [ ] **Phase 14: Domain jobs and external integrations** - CSV/Discogs jobs, wishlist digest, reindex, Discogs client, AI recognition, feedback
- [ ] **Phase 15: Cutover** - Parity harness green on all 154 routes, both real clients run unchanged
- [ ] **Phase 14.2: Local Fonoteka frontend on local SummerCMS backend** - vue-fonoteka-app locally against fonoteka.go
- [ ] **Phase 15: Journal plugin** - Port Golem15.Journal to sm-journal-plugin
- [ ] **Phase 16: grzybyfunkcjonalne.pl on reusable blog views** - First blog on SummerCMS
- [ ] **Phase 20: Płytarium cutover** - Parity harness green, both real clients run unchanged in production
## Phase Details
@@ -639,7 +642,7 @@ Plans:
**Requirements**: TBD
**Depends on:** Phase 12 (user groups tables and the `Groups` relation from 12-01)
**Repos:** `sm-user-plugin` (mounted in fonoteka.go at `plugins/golem15/user`); `summercms.go` only if the admin pipeline is missing a feature the screens need
**Ordering:** independent of Phase 13; must land before Phase 15 (cutover)
**Ordering:** independent of Phase 13; must land before Phase 20 (Płytarium cutover)
**Success Criteria** (what must be TRUE):
1. Users, User Groups and Organisations each have a list (columns, search, filters as in the PHP `config_filter.yaml`) and a create/update form ported from the PHP model YAML, reachable from admin navigation and gated by backend permissions.
@@ -808,17 +811,103 @@ Plans:
**Wave 2** *(blocked on Wave 1 completion)*
- [x] 14.1-02-PLAN.md — Unit tests last: OAuthIdentityApiTest port, migration, MeToken null, secret-leak, corpus 175/175/0
### Phase 15: Cutover
### Phase 14.2: Local Fonoteka frontend on local SummerCMS backend (INSERTED)
**Goal**: The parity harness is green on all 154 routes and `vue-fonoteka-app` and `fonoteka-mcp` run unchanged against the Go backend in daily use — the project's definition of done.
**Goal:** A developer runs the existing `vue-fonoteka-app` locally against the local `fonoteka.go` SummerCMS backend (not PHP), logs in, and uses the real Nuxt flows so the port is proven in daily use before production cutover.
**Mode:** mvp
**Depends on**: Phase 2, Phase 8, Phase 9, Phase 10, Phase 12, Phase 13, Phase 14, Phase 14.1
**Depends on:** Phase 14.1
**Repos:** `vue-fonoteka-app`, `fonoteka.go` (local API, CORS, cookies, env); `summercms.go` only if a framework helper is missing
**Requirements**: QA-05
**Success Criteria** (what must be TRUE):
1. Documented local run: Nuxt and the Go backend start together, with API base URL, cookies and CORS matching how the SPA talks to Winter today.
2. A signed-in session against Go covers the core Nuxt flows: browse collections and albums, search, edit, rate, upload a cover, wishlist add/remove.
3. Failures against Go are visible (no silent fall-through to PHP); the local stack does not require the production origin.
4. The new glue (env, proxy, CORS, run docs) has tests or a fail-closed check script, delivered in the phase's last plan.
**Plans:** 0 plans
Plans:
- [ ] TBD (run $gsd-plan-phase 14.2 to break down)
### Phase 14.2.1: Translate plugin (INSERTED)
**Goal:** Golem15.Translate is ported to Go as `sm-translate-plugin` so Journal (Phase 15) can keep translatable fields. Lean core only: Locale model and Locales admin, Translatable API, cabana `mltext`/`mlmarkdown`, and PHP Translator locale resolution (URL prefix / session / cookie / default).
**Requirements**: TBD
**Depends on:** Phase 14.2
**Repos:** `sm-translate-plugin` (new); `sm-grzybyfunkcjonalne-app` (proof host); `summercms.go` for ML field types and the surf locale seam
**Success Criteria** (what must be TRUE):
1. Plugin repo exists with `winter_translate_*` schema (locales, attributes, indexes, empty messages table), Locale model, en/pl seed, and context-safe Translator.
2. Translatable API (`Translatable()`, `WithLocale`, get/set, default-locale fallback) and permissioned Locales admin work; a fixture model saves and reads `en`+`pl`.
3. Cabana `markdown`/`mltext`/`mlmarkdown` compose; nested locale writes are not dropped; docs, OpenAPI, TS types and `boardwalk` `dist/` update in the same change.
4. Proof host `sm-grzybyfunkcjonalne-app` boots with user+translate; unit tests are the last plan.
**Plans:** 4 plans
Plans:
**Wave 1**
- [ ] 14.2.1-01-PLAN.md — Plugin repo, `winter_translate_*` schema, Locale, en/pl seed, Translator, surf Resolver
**Wave 2** *(blocked on Wave 1 completion)*
- [ ] 14.2.1-02-PLAN.md — Translatable API, Locales admin, fixture save/read
**Wave 3** *(blocked on Wave 2 completion)*
- [ ] 14.2.1-03-PLAN.md — Cabana markdown/ML fields, nested save, docs/OpenAPI/dist, proof host boot
**Wave 4** *(blocked on Wave 3 completion)*
- [ ] 14.2.1-04-PLAN.md — Unit/integration tests last, phase gate, security review
### Phase 15: Journal plugin
**Goal:** The Golem15 Journal plugin is ported to Go as `sm-journal-plugin` and mounts in a host application the same way `sm-user-plugin` does, so a blog can run on SummerCMS without the PHP plugin.
**Mode:** mvp
**Depends on:** Phase 7, Phase 10, Phase 12.1
**Repos:** `sm-journal-plugin` (new, under `git.golem15.com/golem15/`); a host application only as needed to boot and test the plugin; `summercms.go` only if a framework feature is missing
**Requirements**: TBD
**Success Criteria** (what must be TRUE):
1. The Journal plugin repo exists with models, migrations and admin screens ported from PHP `Golem15.Journal`, driven by YAML forms/lists, permission-gated in the admin SPA.
2. A host application can mount the plugin as a submodule and serve its public content (posts, categories, the PHP-equivalent routes or a documented successor).
3. Plugin README and docs stay application-neutral (`the application`, example names such as `blog`).
4. The new code has unit tests, delivered in the phase's last plan.
**Plans:** 0 plans
Plans:
- [ ] TBD (run $gsd-plan-phase 15 to break down)
### Phase 16: grzybyfunkcjonalne.pl on reusable blog views
**Goal:** grzybyfunkcjonalne.pl runs on SummerCMS with a new blog views layer that other Golem15 blogs can reuse, instead of a one-off theme.
**Mode:** mvp
**Depends on:** Phase 15
**Repos:** the grzybyfunkcjonalne application (Go host + views/frontend); `sm-journal-plugin`; `sm-sitemap-plugin` if the blog needs it (todo `sitemap-plugin-port.md`); `summercms.go` only if a framework feature is missing
**Requirements**: TBD
**Success Criteria** (what must be TRUE):
1. grzybyfunkcjonalne.pl is served by a SummerCMS binary (Journal content, routing, i18n as the site needs).
2. The blog views (templates/components/layout) live in a reusable place, not a site-only fork, so a later blog can mount them with its own content.
3. Public pages that PHP Journal + the current theme rendered have a named successor on Go; sitemap is in if the site still needs it.
4. The new code has unit tests, delivered in the phase's last plan.
**Plans:** 0 plans
Plans:
- [ ] TBD (run $gsd-plan-phase 16 to break down)
### Phase 20: Płytarium cutover
**Goal**: The parity harness is green on every manifest route and `vue-fonoteka-app` and `fonoteka-mcp` run unchanged against the Go backend in daily use in production — the Płytarium definition of done.
**Mode:** mvp
**Depends on**: Phase 2, Phase 8, Phase 9, Phase 10, Phase 12, Phase 12.1, Phase 13, Phase 14, Phase 14.1, Phase 14.2, Phase 15, Phase 16
**Repos:** fonoteka.go, summercms.go
**Requirements**: API-09, QA-05
**Success Criteria** (what must be TRUE):
1. All 154 routes are registered on the correct auth groups with identical paths, methods and status codes.
2. The parity harness runs green across recorded fixtures for all 154 routes.
1. All manifest routes are registered on the correct auth groups with identical paths, methods and status codes.
2. The parity harness runs green across recorded fixtures for every manifest route (zero `pending`).
3. `vue-fonoteka-app` runs unchanged against the Go backend for a full manual session (browse, edit, upload, invite, OAuth-connect an MCP client).
4. `fonoteka-mcp` completes its install/auth flow and a representative set of tool calls unchanged against the Go backend.
@@ -827,7 +916,7 @@ Plans:
## Progress
**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 15
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 14.1 → 14.2 → 15 → 16 → 20
(Phase 2 depends on Phase 1's command kernel; the two are no longer parallel.)
| Phase | Plans Complete | Status | Completed |
@@ -849,7 +938,10 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
| 13. Płytarium API — wishlist, notifications, CSV, credentials, public routes | 6/6 | In Progress| |
| 14. Domain jobs and external integrations | 6/6 | In Progress| |
| 14.1. OAuth identities and fonoteka me routes (INSERTED) | 2/2 | Complete | 2026-10-05 |
| 15. Cutover | 0/TBD | Not started | - |
| 14.2. Local Fonoteka frontend on local SummerCMS backend (INSERTED) | 0/TBD | Not started | - |
| 15. Journal plugin | 0/TBD | Not started | - |
| 16. grzybyfunkcjonalne.pl on reusable blog views | 0/TBD | Not started | - |
| 20. Płytarium cutover | 0/TBD | Not started | - |
## Backlog
@@ -857,7 +949,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 →
**Goal:** Visitors to summercms.io subscribe for updates through the initial Go version of the Golem15 Newsletter plugin, which confirms each email by double opt-in. The signup widget is added to the Phase 11.2 landing page, and the site gains Polish alongside English.
**Requirements**: TBD
**Deferred:** 2026-10-02, formerly Phase 11.3. It is one more Golem15 plugin port; the Journal plugin and delivering Płytarium come first. Before planning, re-check what 11.2 shipped since: the landing-page design has no signup slot, nginx on rome blocks `/backend` and non-GET methods, and rome has no mail relay configured.
**Deferred:** 2026-10-02, formerly Phase 11.3. It is one more Golem15 plugin port; Journal is Phase 15 and Płytarium cutover is Phase 20. Before planning, re-check what 11.2 shipped since: the landing-page design has no signup slot, nginx on rome blocks `/backend` and non-GET methods, and rome has no mail relay configured.
**Repos:** `sm-newsletter-plugin` (new, under `git.golem15.com/golem15/`, Go package `newsletter`), plus changes to the Phase 11.2 repos (`vue-summercmsio-app` for the widget and Polish locale, `sm-summercmsio-app` to wire the plugin). `summercms.go` changes only if a framework feature is missing.
**Port source:** Golem15.Newsletter, `github.com/golem15com/wn-newsletter-plugin`, checked out at `/media/nvme/dev/golem15/horoskopia.eu/plugins/golem15/newsletter`. The PHP plugin is work in progress. Its audience comes from registered users (it requires `Golem15.User`), and its only public routes are unsubscribe. It has no public subscriber model or signup widget, so this phase adds those in Go. The PHP original is not changed.
**Success Criteria** (what must be TRUE):