86 lines
6.6 KiB
Markdown
86 lines
6.6 KiB
Markdown
## Context
|
|
|
|
The architecture queue now needs a proof-oriented checkpoint. Earlier changes added platform APIs, durable storage, run control/job/log/artifact channels, platform_web pages, plugin registry/bridge contracts, and AI-provider management, but individual completion evidence does not answer whether the current integrated platform is operational or still relying on local fallback/demo behavior.
|
|
|
|
This change is intentionally verification-only. It should run the current system, inspect the exposed behavior, and produce a clear proof report that classifies each required flow as:
|
|
|
|
- `real`: backed by platform/run/plugin behavior with executable evidence and no demo fallback needed.
|
|
- `partial`: some real behavior exists, but a documented missing piece prevents full operational proof.
|
|
- `demo-only`: the visible behavior is static seed/local fallback data or simulated behavior that cannot prove real platform operation.
|
|
- `blocked`: verification cannot run because of a reproducible environment, tooling, credential, or dependency blocker.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
|
|
- Verify the required first-party frontend areas: 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
|
|
- Verify platform APIs are backed by current storage and service behavior rather than only frontend seed data.
|
|
- Verify run-mediated lifecycle behavior for create/install, start, stop, job ack/result, and state projection.
|
|
- Verify durable log history survives through the current log ingest/query path and remains independent from artifact/file transfer work.
|
|
- Verify artifact download/upload and file dispatch use platform-mediated contracts with bounded transfer evidence.
|
|
- Verify game management plugin manifests, SDK bridge requests, AI requests, and file/config/log/run capabilities do not bypass platform authorization.
|
|
- Produce a proof report with command output references, browser walkthrough notes, and gap classifications.
|
|
|
|
**Non-Goals:**
|
|
|
|
- No implementation of missing product behavior.
|
|
- No redesign of platform_web pages or visual style.
|
|
- No new game plugin lifecycle implementation beyond verifying current behavior.
|
|
- No billing, cloud host sales, agent-provider/cloud-provider workflows, unrelated SaaS marketplace features, or provider marketplace behavior.
|
|
- No direct plugin-to-run, browser-to-run, raw host path, raw socket, raw credential, or raw AI-key exposure.
|
|
|
|
## Decisions
|
|
|
|
### Decision 1: Verification produces an explicit proof report
|
|
|
|
The implementation should create or update a baseline proof report inside the change that lists every required flow, its classification, the evidence command or browser step, and any follow-up OpenSpec recommendation.
|
|
|
|
Alternative considered: rely only on test pass/fail output. Rejected because a passing unit suite does not show whether user-visible workflows are real, partial, demo-only, or blocked.
|
|
|
|
### Decision 2: Browser walkthrough is required for visible first-party areas
|
|
|
|
The proof must open the frontend in a browser and walk through 首页、服务器管理、插件市场、用户管理、AI 提供商管理 plus the plugin/server detail surfaces needed to prove lifecycle, logs, artifacts, config, AI, and bridge behavior. If the walkthrough cannot run, the report must classify the affected flows as blocked with exact commands and errors.
|
|
|
|
Alternative considered: use server-side rendered tests only. Rejected because the queue requires browser acceptance for frontend-facing proof.
|
|
|
|
### Decision 3: Real-vs-demo classification is based on backing behavior
|
|
|
|
Frontend pages that render local seed data, local fallback state, or simulated completion without platform/run evidence should be classified as `demo-only` or `partial`, even if they look complete. Real classification requires platform API responses, run/job/log/artifact evidence, and plugin boundary checks where applicable.
|
|
|
|
Alternative considered: classify by UI completeness. Rejected because the user specifically needs to know whether functionality is real or demo-only.
|
|
|
|
### Decision 4: Channel isolation is verified through concurrent or adjacent operations
|
|
|
|
The log/artifact/file proof should include evidence that durable log ingest/control/job behavior remains independent from artifact or file operations. The baseline may use existing tests or a local smoke script if they demonstrate the isolation requirement without adding product behavior.
|
|
|
|
Alternative considered: document channel isolation from architecture alone. Rejected because this change is about current executable reality.
|
|
|
|
### Decision 5: Follow-up gaps become backlog recommendations, not fixes
|
|
|
|
When a flow is partial, demo-only, or blocked, the report should identify the smallest follow-up OpenSpec needed to make it real. This change stops at proof and recommendations unless the user explicitly asks to implement a follow-up.
|
|
|
|
Alternative considered: fix discovered gaps immediately. Rejected because the prompt requires stopping after this OpenSpec is ready and the implementation scope should remain verification-only.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Risk] Environment blockers can hide real behavior. Mitigation: record exact blocker commands and classify only affected flows as blocked.
|
|
- [Risk] Existing local fallback data may make pages appear operational. Mitigation: require API/run evidence before assigning `real`.
|
|
- [Risk] End-to-end setup may be slower than unit tests. Mitigation: tasks define a repeatable command sequence and allow narrower proof scripts when they cover the same contracts.
|
|
- [Risk] Verification may discover many gaps. Mitigation: prioritize follow-up recommendations by required first-party area and channel boundary risk.
|
|
|
|
## Migration Plan
|
|
|
|
1. Add the proof report structure and any small verification scripts or fixtures required to run the baseline.
|
|
2. Run platform, run, plugin, and frontend verification commands.
|
|
3. Start the local stack needed for platform_web browser walkthrough and platform/run integration checks.
|
|
4. Walk through required frontend areas and record whether data/actions are API-backed, run-backed, local fallback, or blocked.
|
|
5. Classify every required flow and list follow-up OpenSpec recommendations for non-real flows.
|
|
|
|
Rollback is simple before implementation closes: remove the proof report and any verification-only scripts added by this change.
|
|
|
|
## Open Questions
|
|
|
|
- Whether the implementation should use docker-compose services or in-process test servers as the primary local stack for proof.
|
|
- Whether the final proof report should live only under this change or be promoted into persistent project documentation after acceptance.
|
|
- Whether blocked browser tooling should be resolved by in-app browser automation, Chrome automation, or a project-owned Playwright acceptance suite.
|