docs(14-01): reword INTG-02, API-08 and the Phase 14 scope (D-06, D-07, D-13, D-14)

- INTG-02 names hand-rolled Anthropic and OpenAI-compatible adapters over the guarded client
- API-08 is feedback only; sitemap dropped for this application
- Phase 14 criteria list the album Discogs and recognize routes; Repos names the new core-plugin repos
- PROJECT moves golem and feedback to sm-*-plugin submodules
This commit is contained in:
Jakub Zych
2026-10-03 20:02:04 +02:00
parent 58e6324da8
commit 7700c6da28
3 changed files with 11 additions and 10 deletions

View File

@@ -79,7 +79,7 @@ Background and integrations
- [ ] Typesense indexing and search for albums with the same query semantics as the Scout-based PHP version - [ ] Typesense indexing and search for albums with the same query semantics as the Scout-based PHP version
- [ ] File uploads and cover images through gocloud.dev/blob with the same public URL shape - [ ] File uploads and cover images through gocloud.dev/blob with the same public URL shape
- [ ] Discogs client and AI cover recognition (Anthropic and OpenAI) with per-user and per-org credentials - [ ] Discogs client and AI cover recognition (Anthropic and OpenAI) with per-user and per-org credentials
- [ ] Feedback submissions and sitemap output as in the PHP stack plugins - [ ] Feedback submissions as in the PHP stack feedback plugin
Admin Admin
@@ -134,7 +134,7 @@ Quality
- **Compatibility**: `vue-fonoteka-app` and `fonoteka-mcp` must run unchanged; the Nuxt app's requests define the contract and response shapes are not improved during the port - **Compatibility**: `vue-fonoteka-app` and `fonoteka-mcp` must run unchanged; the Nuxt app's requests define the contract and response shapes are not improved during the port
- **Realtime**: keep the Centrifugo server and port only the publisher and token issuing — the Nuxt client connects to Centrifugo directly - **Realtime**: keep the Centrifugo server and port only the publisher and token issuing — the Nuxt client connects to Centrifugo directly
- **Plugins**: compiled at build time; no runtime plugin loading without a decision note - **Plugins**: compiled at build time; no runtime plugin loading without a decision note
- **Two repositories**: `summercms.go` is the framework only (the `summer` packages, the CLI, the admin SPA shell, the parity harness tooling) and knows nothing about Płytarium; `fonoteka.go`, a sibling directory in the meta repo, is the application: a go.work workspace holding the application plugins (fonoteka, translate, feedback, sitemap) and the app binary, and mounting shared core plugins from their own `sm-<name>-plugin` repos as git submodules (the user plugin is `sm-user-plugin`, module `git.golem15.com/golem15/sm-user-plugin`, at `plugins/golem15/user`; see `.planning/notes/core-plugins-own-repos.md`); websockets is not a separate app plugin (D-16, Phase 11): the framework realtime package `lighthouse` plus fonoteka's `config/realtime.yaml`, channel authorizers, `lighthouse.Mount` call and `ws-api` bucket replace it, requiring the framework by module path with a local replace during development. Roadmap phases name which repo each plan writes to; planning docs stay in `summercms.go/.planning` - **Two repositories**: `summercms.go` is the framework only (the `summer` packages, the CLI, the admin SPA shell, the parity harness tooling) and knows nothing about Płytarium; `fonoteka.go`, a sibling directory in the meta repo, is the application: a go.work workspace holding the application plugins (fonoteka, translate) and the app binary, and mounting shared core plugins from their own `sm-<name>-plugin` repos as git submodules: `sm-user-plugin` (module `git.golem15.com/golem15/sm-user-plugin`, at `plugins/golem15/user`), `sm-golem-plugin` (at `plugins/golem15/golem`) and `sm-feedback-plugin` (at `plugins/golem15/feedback`), see `.planning/notes/core-plugins-own-repos.md`; sitemap is not ported for this application (D-14); websockets is not a separate app plugin (D-16, Phase 11): the framework realtime package `lighthouse` plus fonoteka's `config/realtime.yaml`, channel authorizers, `lighthouse.Mount` call and `ws-api` bucket replace it, requiring the framework by module path with a local replace during development. Roadmap phases name which repo each plan writes to; planning docs stay in `summercms.go/.planning`
- **Workflow**: lean planning (few, large plans per phase), a plan-count checkpoint before PLAN.md files are written, unit tests as the last plan of every phase, `go vet` and `go test ./...` green at every commit - **Workflow**: lean planning (few, large plans per phase), a plan-count checkpoint before PLAN.md files are written, unit tests as the last plan of every phase, `go vet` and `go test ./...` green at every commit
- **Commits**: no co-author tags; one logical change per commit; planning docs and code in separate commits - **Commits**: no co-author tags; one logical change per commit; planning docs and code in separate commits
- **Core plugin contracts**: the PHP user, blog, pages and payment plugins are shared across many projects; the Go ports must preserve their contracts and the PHP originals are not changed as part of this project - **Core plugin contracts**: the PHP user, blog, pages and payment plugins are shared across many projects; the Go ports must preserve their contracts and the PHP originals are not changed as part of this project

View File

@@ -80,7 +80,7 @@ Requirements for v1 (the Płytarium port). Each maps to roadmap phases. "User" b
- [x] **API-05**: CSV import as a multi-step session (store, show/poll, mapping patch, per-row edit, commit, cancel) and CSV export on both authenticated groups - [x] **API-05**: CSV import as a multi-step session (store, show/poll, mapping patch, per-row edit, commit, cancel) and CSV export on both authenticated groups
- [x] **API-06**: Per-user and per-org Discogs and AI credentials CRUD with encrypted storage, org-lock flag, and env-to-org-to-user resolution (the live ai-credential/test and discogs-credential/test routes are Phase 14, with INTG-01 and INTG-02) - [x] **API-06**: Per-user and per-org Discogs and AI credentials CRUD with encrypted storage, org-lock flag, and env-to-org-to-user resolution (the live ai-credential/test and discogs-credential/test routes are Phase 14, with INTG-01 and INTG-02)
- [x] **API-07**: Onboarding, public and invitation inspection routes, including the anonymous collection public-token views (public/{token}, its albums and album detail), with their public rate-limit buckets - [x] **API-07**: Onboarding, public and invitation inspection routes, including the anonymous collection public-token views (public/{token}, its albums and album detail), with their public rate-limit buckets
- [ ] **API-08**: Feedback submissions and sitemap output from the stack plugins - [ ] **API-08**: Feedback submissions, widget config and the per-user hide preference from the stack feedback plugin (sitemap dropped for this application, D-14)
- [ ] **API-09**: All 154 routes are registered on the correct groups with identical paths, methods, status codes and bodies - [ ] **API-09**: All 154 routes are registered on the correct groups with identical paths, methods, status codes and bodies
### Background jobs (JOBS) ### Background jobs (JOBS)
@@ -102,8 +102,8 @@ Requirements for v1 (the Płytarium port). Each maps to roadmap phases. "User" b
### Integrations (INTG) ### Integrations (INTG)
- [ ] **INTG-01**: Discogs client with proactive rate threshold, bounded in-request wait budget, retry-after fallback, and host-locked cover fetch, plus the albums/{id}/cover-price/discogs route, the wishlist/albums/{id}/match and apply-release routes, discogs-credential/test and the CSV row-edit Discogs pick (selected_discogs_id) - [ ] **INTG-01**: Discogs client with proactive rate threshold, bounded in-request wait budget, retry-after fallback, and host-locked cover fetch, plus the albums/{id}/cover-price/discogs route, the wishlist/albums/{id}/match and apply-release routes, the album routes albums/match, albums/{id}/match, albums/{id}/apply-release and albums/import/discogs (D-07), discogs-credential/test and the CSV row-edit Discogs pick (selected_discogs_id)
- [ ] **INTG-02**: AI cover recognition through provider adapters (Anthropic Go SDK, OpenAI-compatible) with per-credential model and base URL overrides, plus the ai-credential/test route and the backend global vision model behind the AI resolver's admin tier - [ ] **INTG-02**: AI cover recognition through Anthropic and OpenAI-compatible adapters over the guarded client, with per-credential model and base URL overrides, plus the ai-credential/test route and the backend global vision model behind the AI resolver's admin tier
### Admin (ADMIN) ### Admin (ADMIN)

View File

@@ -26,7 +26,7 @@ Decimal phases appear between their surrounding integers in numeric order.
- [ ] **Phase 11: Jobs, realtime and search infrastructure** - River, Centrifugo and Typesense sync brought up before the API phases that need them - [ ] **Phase 11: Jobs, realtime and search infrastructure** - River, Centrifugo and Typesense sync brought up before the API phases that need them
- [x] **Phase 12: Płytarium API — Collections and Albums** - Core content endpoints ported with byte-level parity (completed 2026-10-02) - [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 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, sitemap - [ ] **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 15: Cutover** - Parity harness green on all 154 routes, both real clients run unchanged
## Phase Details ## Phase Details
@@ -736,16 +736,17 @@ Plans:
**Goal**: The domain-specific River jobs (CSV import write, Discogs match, wishlist digest), the reindex command, the Discogs client and AI cover recognition are ported on top of the Phase 11 jobs/realtime/search infrastructure and the Phase 13 API surface they serve. **Goal**: The domain-specific River jobs (CSV import write, Discogs match, wishlist digest), the reindex command, the Discogs client and AI cover recognition are ported on top of the Phase 11 jobs/realtime/search infrastructure and the Phase 13 API surface they serve.
**Mode:** mvp **Mode:** mvp
**Depends on**: Phase 11, Phase 13 **Depends on**: Phase 11, Phase 13
**Repos:** fonoteka.go (plus summercms.go only if a framework helper is needed) **Repos:** fonoteka.go; summercms.go (14-01 framework helpers); sm-golem-plugin and sm-feedback-plugin (new core-plugin repos mounted as submodules)
**Requirements**: JOBS-02, JOBS-03, SRCH-02, INTG-01, INTG-02, API-08, CLI-05 **Requirements**: JOBS-02, JOBS-03, SRCH-02, INTG-01, INTG-02, API-08, CLI-05
**Success Criteria** (what must be TRUE): **Success Criteria** (what must be TRUE):
1. The CSV import write job and the self-redispatching Discogs match job (240s timeout, self-redispatching with a delay on a Discogs rate-limit error) both complete correctly. 1. The CSV import write job and the self-redispatching Discogs match job (240s timeout, self-redispatching with a delay on a Discogs rate-limit error) both complete correctly.
2. The wishlist digest job coalesces a 30-minute window and deletes its queue row on completion. 2. The wishlist digest job coalesces a 30-minute window and deletes its queue row on completion.
3. The `reindex` command asserts zero `collection_id`-0 documents before and after and can drop the legacy index. 3. The `reindex` command asserts zero `collection_id`-0 documents before and after and can drop the legacy index.
4. The Discogs client enforces its proactive rate threshold, bounded wait budget, retry-after fallback and host-locked cover fetch, and the `albums/{id}/cover-price/discogs` route, the wishlist `wishlist/albums/{id}/match` and `apply-release` routes, `discogs-credential/test` and the CSV row-edit Discogs pick (`selected_discogs_id`) pass the parity diff. 4. The Discogs client enforces its proactive rate threshold, bounded wait budget, retry-after fallback and host-locked cover fetch, and the `albums/{id}/cover-price/discogs` route, the wishlist `wishlist/albums/{id}/match` and `apply-release` routes, the album `albums/match`, `albums/{id}/match`, `albums/{id}/apply-release` and `albums/import/discogs` routes, `discogs-credential/test` and the CSV row-edit Discogs pick (`selected_discogs_id`) pass the parity diff.
5. AI cover recognition works through both Anthropic and OpenAI-compatible adapters with per-credential model/base-URL overrides; `ai-credential/test` passes the parity diff, and the AI resolver's admin tier uses the backend global vision model. 5. AI cover recognition works through both Anthropic and OpenAI-compatible adapters, hand-rolled over the guarded client, with per-credential model/base-URL overrides; `albums/recognize` on the JWT and personal-token groups and `ai-credential/test` pass the parity diff, and the AI resolver's admin tier uses the backend global vision model.
6. Feedback submissions and sitemap output work; the ported `oauth-client`/`prune-notifications`/`reindex` commands all run correctly. 6. Feedback submissions, widget config and the hide preference work (sitemap dropped for this application, D-14); the oauth-client, prune-notifications and reindex commands all run correctly.
`oauth-identities` GET/DELETE and token `GET /api/v1/fonoteka/me` stay pending in this phase (D-09, todo orphan-pending-routes).
**Plans:** 6 plans **Plans:** 6 plans