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
- [ ] 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
- [ ] Feedback submissions and sitemap output as in the PHP stack plugins
- [ ] Feedback submissions as in the PHP stack feedback plugin
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
- **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
- **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
- **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

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-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
- [ ] **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
### Background jobs (JOBS)
@@ -102,8 +102,8 @@ Requirements for v1 (the Płytarium port). Each maps to roadmap phases. "User" b
### 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-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-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 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)

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
- [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, 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 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.
**Mode:** mvp
**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
**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.
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.
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.
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.
6. Feedback submissions and sitemap output work; the ported `oauth-client`/`prune-notifications`/`reindex` commands all run correctly.
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, 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, 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