docs: specify remote configuration memory flow

2026-09-05 21:08:31 +08:00
parent 556c47a1b6
commit 62328b6fd6
2 changed files with 90 additions and 0 deletions
@@ -0,0 +1,47 @@
+# Remote Config Memory Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. Steps use checkbox syntax for tracking.
+
+**Goal:** Both modes read remote JSON, resolve it like the legacy project, and keep it only in memory.
+
+**Architecture:** Existing remote-config.ts owns the hierarchy reader and server selection. Runtime configuration always awaits it; local selection overrides only the final connection targets. Existing local host preserves its lifecycle and loopback guards.
+
+**Tech Stack:** TypeScript, node:test/tsx, Cocos Creator 3.8.8 through funplay MCP.
+
+**Spec:** docs/superpowers/specs/2026-09-05-remote-config-memory-design.md
+
+## Global Constraints
+
+- Use branches in main checkout; never create worktrees. Current branch codex/local-platform-login.
+- No server changes. No .scene/.prefab/.anim/.meta edits or generation.
+- Both debug and release fetch remote data. Memory only: no storage or disk cache.
+- Preserve legacy truthy hierarchy overrides, first loose identity match, whole-object replacement, game_server_tcp then player_server_tcp.
+- Never connect production WebSockets during validation; local preview stays loopback only.
+- Never run npm test, test:framework, or scripts/run-framework-tests.mjs.
+- Do not stage unrelated files. Root controller owns spec/plan/protocol docs and live verification.
+
+### Task 1: Replace the obsolete remote contract and integrate every startup consumer
+
+**Files (all under cocoscreator_projects unless noted):**
+- Modify YouleNexus/assets/framework/config/{remote-config.ts,runtime-config.ts,profiles.ts,local-startup.ts}.
+- Modify existing YouleNexus/assets/scripts/local-platform-login files only if integration or sensitive diagnostic output needs correction.
+- Test framework-tests/config/{remote-config.test.ts,runtime-config.test.ts,profiles.test.ts,local-startup.test.ts}; update dependent typed fixtures in framework-tests and old remote JSON fixture shapes to match new contract.
+- Do not add new assets scripts. New test files outside assets are allowed if useful.
+
+**Interfaces:** Remote config view exposes readonly raw root and getValue(name: string): unknown; export a creator in remote-config.ts taking unknown root and ChannelIdentity. RuntimeConfig exposes the view as remoteConfig and keeps rawConfig as the same raw reference, source always remote and gameserver non-null. parseUrlServers receives the view and resolves game_server_tcp/player_server_tcp. Profiles retain unique servers for local override and all have remote gameserver.
+
+- [ ] Write failing tests first. Use the actual legacy get_paravalue extracted from 12_Logic.js in a node:vm sandbox as differential oracle; fixtures contain synthetic identities only. Assert values across all five scopes, false/0/empty values, object replacement, missing levels and first duplicate. Example: `assert.deepEqual(view.getValue('hall_config'), legacy(wrapper, 'hall_config'))`.
+- [ ] Add startup behavior assertions: for debug local fake fetcher increment calls then return `{player_server_tcp:'remote.example:3088'}`; expect calls=1, source=remote, local servers, raw config retained. release with profile=local must still fetch and use remote candidates. Failed fetch or parse must leave local-host socket calls at zero. No persistence operation is added.
+- [ ] Run exact focused tests from cocoscreator_projects: `node --import tsx --test --test-concurrency=1 framework-tests/config/remote-config.test.ts framework-tests/config/runtime-config.test.ts framework-tests/config/profiles.test.ts framework-tests/config/local-startup.test.ts`. Record expected assertion failures before production edits. If tsx ENOMEM occurs, repeat identical command with require_escalated.
+- [ ] Implement the smallest integrated change. Loop scopes using first identity equality, update inherited value only if truthy, stop when scope is absent. Validate the JSON root and present hierarchy shape; normalize only the chosen server candidates. Runtime always awaits fetch, builds one memory view, parses candidates, then applies profile local servers. Preserve host cancellation guards and stop semantics.
+- [ ] Update dependent tests/fixtures asserting the superseded direct contract; retain all unrelated assertions and add no runtime fallback. All test RuntimeConfig literals must supply the new view via a central test helper where appropriate.
+- [ ] Run focused tests then full explicitly enumerated TS suite: `$testPaths = @(rg --files framework-tests -g '*.test.ts' | Sort-Object); node --import tsx --test --test-concurrency=1 @testPaths`. Run `node node_modules/typescript/bin/tsc -p tsconfig.framework.json --noEmit` and `node scripts/check-import-boundaries.mjs`. Discover and explicitly name the two platform architecture tests; do not invoke aggregate generators.
+- [ ] Self-review, stage exact task files, commit. Report RED/GREEN commands, counts, changed files, and concerns in task-1-report.md. Do not touch root controller docs or existing dirty resources.
+- [ ] Controller dispatches independent spec/quality reviewer; repair findings with failing regressions first, then scoped re-review.
+
+### Task 2: Documentation and real-boundary acceptance (controller)
+
+- [ ] Correct docs/protocol/01-传输层与架构.md remote-entry description to active get_config/getConfig_Succ, local wrapper and scoped server selection. Preserve unrelated protocol text.
+- [ ] Read the live remote response through the production parser and current identity without storing response body or printing sensitive values. Record fetch/parse outcome and selected hierarchy depth only.
+- [ ] Verify actual Cocos preview via funplay MCP, without asset mutations. Observe actual remote request and resolved local target; stop runtime after observation. If browser fetch fails, document status and exact origin/request facts before deciding a fix; do not disable security or proxy silently.
+- [ ] Hash-check initial dirty files unchanged. Write a concise acceptance report with separate pure tests, live HTTP and real Creator evidence. Perform whole-change review before declaring completion.