first commit

2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
@@ -0,0 +1,60 @@
+## Context
+
+The platform can validate and register game plugin manifests, and the frontend already has the first-party Plugin Marketplace area. The remaining gap is that the page is not yet an authoritative view over platform registry data. This change makes the marketplace page API-driven while keeping commerce concepts out of scope.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Expose marketplace list and detail data from platform registry metadata.
+- Let operators filter installed game management plugins by status, server type, keyword, and capability.
+- Allow safe install/enable/disable state changes without exposing implementation internals.
+- Centralize frontend API types and client methods outside page-local hidden types.
+- Add tests and browser walkthrough evidence for loading, errors, filtering, install/state actions, and no-secret rendering.
+
+**Non-Goals:**
+
+- No billing, pricing, cloud host sales, provider marketplace, ratings, reviews, checkout, or subscription behavior.
+- No plugin page execution, bridge transport, run-side action execution, or AI invocation implementation.
+- No raw host paths, direct run sockets, raw credentials, or raw AI provider keys in responses.
+- No new visual system that replaces the platform_web theme.
+
+## Decisions
+
+### Decision 1: Marketplace data is a view over installed registry metadata
+
+Marketplace APIs will project installed plugin metadata into list/detail DTOs. The response includes identity, version, server type, status, description, pages, capabilities, permissions, and AI purposes, but not commerce data or backend internals.
+
+Alternative considered: create a separate catalog model with publish/store metadata. Rejected because this repository is a game server management platform, and current needs are covered by installed registry data.
+
+### Decision 2: Install and state actions remain metadata-only
+
+Install/enable/disable actions update platform plugin registry state and return the updated marketplace DTO. They do not download external packages or execute run jobs in this change.
+
+Alternative considered: trigger package download and runtime deployment from the marketplace page. Rejected because package acquisition and run execution require separate explicit changes.
+
+### Decision 3: Frontend fallback is isolated to development
+
+The page may keep a clearly isolated local fallback for standalone frontend development, but production flow prefers API data and shows API errors. Tests assert fallback does not leak into successful API flows.
+
+Alternative considered: remove all fallback state immediately. Rejected because local frontend demos still need useful data when the backend is absent.
+
+## Risks / Trade-offs
+
+- [Risk] Marketplace APIs duplicate some game plugin list/detail behavior. Mitigation: implement them as service projections over the same registry metadata.
+- [Risk] Install state can be confused with package acquisition. Mitigation: name docs and DTO fields around installed/active registry state only.
+- [Risk] Frontend state can drift from backend after actions. Mitigation: action methods return updated DTOs and tests cover refresh/update behavior.
+
+## Migration Plan
+
+1. Add platform marketplace DTOs, validators, service projection, routes, and docs.
+2. Update frontend API contracts and marketplace page to consume API data.
+3. Add backend and frontend tests.
+4. Run browser walkthrough, structure check, and strict OpenSpec validation.
+
+Rollback before dependent changes is removal of marketplace projection routes/page API integration and this change's artifacts.
+
+## Open Questions
+
+- Whether future plugin package publication should use signed artifacts or an internal admin upload flow.
+- Whether marketplace sorting should later incorporate operational health or compatibility scores.