joywayerandClaude Opus 4.8
f66771b6b1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
838 lines
34 KiB
Markdown
838 lines
34 KiB
Markdown
# 配置 / 渠道子系统（framework/config）Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 实现 `framework/config/` 子系统——把「渠道身份解析（含原生同步读取）+ 调试 profiles + 远程配置抓取与分层取参 + 服务器地址解析」收敛为可注入、可在 Node 下测试的纯逻辑 + IO 分离模块，最终由 `resolveBootstrap()` 产出可直接喂给 `NetClient` 的 `{ identity, servers }`。
|
||
|
||
**Architecture:** 严格分纯逻辑（`resolveIdentity`/`getParam`/`resolveServers`/`profiles`）与异步 IO（`ConfigFetcher`），原生读取收敛为单一 source。依赖方向 `config → core`。身份按优先级合并：`defaults < (native|query) < profile < 显式 URL query`。服务器优先用 profile 显式 `server`，否则远程配置 `getParam` → `resolveServers`。外部契约字符串（协议字段名 / 原生接口名 / 远程配置键名）逐字不变，内部命名现代化。
|
||
|
||
**Tech Stack:** TypeScript（Cocos 3.8.8）；测试用 Node 20 + `tsx` 跑 `node:test`，置于 `framework-tests/`（Cocos `assets/` 之外）。沿用 Plan 2 已建的 `npm run test:framework` / `npm run typecheck:framework`。
|
||
|
||
> 依据 spec `docs/superpowers/specs/2026-06-28-config-channel-design.md`。原工程事实依据：`projects/Game_Surface_3/js/00_Surface/12_Logic.js`（`get_paravalue` 1345 / `getConfig_Succ` 1392 / `get_config` 1332 / `setAgentId` 1234 / `setChannelId` 1217）、`js/00_Surface/05_Func.js`（`getothername` 2467 / `getchannelName` 1961 / `getmarketname` 2429）、`version.js`（构建期默认）、`js/01_SubGame/00_SubGame_Config.js:11`（`gameserver`）。
|
||
|
||
**所有 npm 命令工作目录为 `cocoscreator_projects/`（monorepo 根）；git 命令工作目录为 `G:/Works/YouleGamesCocosCreator`。**
|
||
|
||
---
|
||
|
||
## 文件结构（本计划建立）
|
||
|
||
```
|
||
cocoscreator_projects/
|
||
├─ framework-tests/config/
|
||
│ ├─ identity.test.ts
|
||
│ ├─ sources/query-string.test.ts
|
||
│ ├─ sources/native-settings.test.ts
|
||
│ ├─ profiles.test.ts
|
||
│ ├─ remote-config.test.ts
|
||
│ └─ bootstrap.test.ts
|
||
└─ YouleNexus/assets/framework/config/
|
||
├─ identity.ts # ChannelIdentity + IdentitySource + resolveIdentity()
|
||
├─ profiles.ts # DebugProfile + PROFILES + resolveActiveProfile()
|
||
├─ remote-config.ts # RemoteConfig 类型 + ConfigFetcher + getParam() + resolveServers() + 错误类型
|
||
├─ remote-config-fetcher.ts # 生产用 HttpConfigFetcher（typecheck-only）
|
||
├─ bootstrap.ts # resolveBootstrap()
|
||
└─ sources/
|
||
├─ defaults.ts # BUILD_IDENTITY 构建期默认
|
||
├─ query-string.ts # queryStringSource()
|
||
└─ native-settings.ts # nativeSettingsSource()
|
||
```
|
||
|
||
---
|
||
|
||
### Task 1: identity.ts + sources/defaults.ts — 身份类型与纯合并
|
||
|
||
**Files:**
|
||
- Create: `cocoscreator_projects/YouleNexus/assets/framework/config/identity.ts`
|
||
- Create: `cocoscreator_projects/YouleNexus/assets/framework/config/sources/defaults.ts`
|
||
- Create: `cocoscreator_projects/framework-tests/config/identity.test.ts`
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
创建 `framework-tests/config/identity.test.ts`：
|
||
|
||
```ts
|
||
import { test } from 'node:test';
|
||
import assert from 'node:assert/strict';
|
||
import { resolveIdentity } from '../../YouleNexus/assets/framework/config/identity.ts';
|
||
import { BUILD_IDENTITY } from '../../YouleNexus/assets/framework/config/sources/defaults.ts';
|
||
|
||
test('BUILD_IDENTITY 含全部字段且 gameid 为固定 token', () => {
|
||
assert.ok(BUILD_IDENTITY.gameid.length > 0);
|
||
assert.ok('agentid' in BUILD_IDENTITY);
|
||
assert.ok('channelid' in BUILD_IDENTITY);
|
||
assert.ok('marketid' in BUILD_IDENTITY);
|
||
assert.equal(typeof BUILD_IDENTITY.version, 'string');
|
||
assert.equal(typeof BUILD_IDENTITY.versionCode, 'number');
|
||
});
|
||
|
||
test('resolveIdentity：后面的 source 覆盖前面的', () => {
|
||
const id = resolveIdentity([
|
||
() => BUILD_IDENTITY,
|
||
() => ({ agentid: 'A2' }),
|
||
() => ({ agentid: 'A3', channelid: 'C3' }),
|
||
]);
|
||
assert.equal(id.agentid, 'A3');
|
||
assert.equal(id.channelid, 'C3');
|
||
assert.equal(id.gameid, BUILD_IDENTITY.gameid); // 未被覆盖
|
||
});
|
||
|
||
test('resolveIdentity：undefined / null / 空串 不覆盖', () => {
|
||
const id = resolveIdentity([
|
||
() => BUILD_IDENTITY,
|
||
() => ({ agentid: undefined as any, channelid: '' , marketid: null as any }),
|
||
]);
|
||
assert.equal(id.agentid, BUILD_IDENTITY.agentid);
|
||
assert.equal(id.channelid, BUILD_IDENTITY.channelid);
|
||
assert.equal(id.marketid, BUILD_IDENTITY.marketid);
|
||
});
|
||
|
||
test('resolveIdentity：marketid=0 是有效值，应覆盖', () => {
|
||
const id = resolveIdentity([() => BUILD_IDENTITY, () => ({ marketid: 0 })]);
|
||
assert.equal(id.marketid, 0);
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败**
|
||
|
||
Run: `npm run test:framework`
|
||
Expected: FAIL — 找不到 identity.ts / defaults.ts
|
||
|
||
- [ ] **Step 3: 实现 identity.ts**
|
||
|
||
创建 `config/identity.ts`：
|
||
|
||
```ts
|
||
/** 渠道身份（属性名沿用协议字段，序列化进 player_login，逐字不变）。 */
|
||
export interface ChannelIdentity {
|
||
agentid: string | number;
|
||
channelid: string | number;
|
||
gameid: string;
|
||
marketid: string | number;
|
||
version: string; // 旧 GameData.Version
|
||
versionCode: number; // 旧 GameData.versionCode
|
||
}
|
||
|
||
/** 身份来源：返回部分字段覆盖。 */
|
||
export type IdentitySource = () => Partial<ChannelIdentity>;
|
||
|
||
function hasValue(v: unknown): boolean {
|
||
return v !== undefined && v !== null && v !== '';
|
||
}
|
||
|
||
/**
|
||
* 按数组顺序合并身份，后者覆盖前者（仅覆盖有效值字段）。
|
||
* 约定首个 source 为完整 defaults，故返回视为完整 ChannelIdentity。
|
||
*/
|
||
export function resolveIdentity(sources: IdentitySource[]): ChannelIdentity {
|
||
const out: Partial<ChannelIdentity> = {};
|
||
for (const src of sources) {
|
||
const part = src();
|
||
for (const k of Object.keys(part) as (keyof ChannelIdentity)[]) {
|
||
const v = part[k];
|
||
if (hasValue(v)) (out as Record<string, unknown>)[k] = v;
|
||
}
|
||
}
|
||
return out as ChannelIdentity;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 实现 sources/defaults.ts**
|
||
|
||
创建 `config/sources/defaults.ts`（默认值取自 `projects/Game_Surface_3/version.js` 模板默认 + H5 marketid 默认 4）：
|
||
|
||
```ts
|
||
import type { ChannelIdentity } from '../identity.ts';
|
||
|
||
/**
|
||
* 构建期默认渠道身份（旧 version.js 等价物）。
|
||
* gameid 每子游戏固定写死；agentid/channelid/marketid/version 为默认，运行期由 query/native/profile 覆盖。
|
||
*/
|
||
export const BUILD_IDENTITY: ChannelIdentity = {
|
||
agentid: '00bA05haB0d9ZC0fwGD09Q2OA30insbQ',
|
||
channelid: 'frdt0C1GG0t91P0McFo0rbA1he5yurbS',
|
||
gameid: '8x4l0rGjf026f60c48h0mbUAhK5vV16f',
|
||
marketid: 4,
|
||
version: '1.1',
|
||
versionCode: 10000,
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 5: 跑测试 + 类型检查**
|
||
|
||
Run: `npm run test:framework`
|
||
Expected: PASS（含 identity 4 用例）
|
||
Run: `npm run typecheck:framework`
|
||
Expected: exit 0
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
cd G:/Works/YouleGamesCocosCreator
|
||
git add cocoscreator_projects/YouleNexus/assets/framework/config/identity.ts cocoscreator_projects/YouleNexus/assets/framework/config/sources/defaults.ts cocoscreator_projects/framework-tests/config/identity.test.ts
|
||
git commit -m "feat(framework): config 身份类型 + 纯合并 resolveIdentity + 构建期默认
|
||
|
||
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: sources/query-string.ts — H5 URL query 身份来源
|
||
|
||
**Files:**
|
||
- Create: `cocoscreator_projects/YouleNexus/assets/framework/config/sources/query-string.ts`
|
||
- Create: `cocoscreator_projects/framework-tests/config/sources/query-string.test.ts`
|
||
|
||
> 对应原 `Logic.setChannelId`/`setAgentId` 的 H5 分支（`fGetQuery`）。gameid 固定不从 query 取。
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
创建 `framework-tests/config/sources/query-string.test.ts`：
|
||
|
||
```ts
|
||
import { test } from 'node:test';
|
||
import assert from 'node:assert/strict';
|
||
import { queryStringSource } from '../../../YouleNexus/assets/framework/config/sources/query-string.ts';
|
||
|
||
test('解析 agentid/channelid/marketid/version', () => {
|
||
const src = queryStringSource('?agentid=A1&channelid=C1&marketid=2&version=9.9');
|
||
assert.deepEqual(src(), { agentid: 'A1', channelid: 'C1', marketid: '2', version: '9.9' });
|
||
});
|
||
|
||
test('缺省键不出现在结果里', () => {
|
||
const src = queryStringSource('?agentid=A1');
|
||
assert.deepEqual(src(), { agentid: 'A1' });
|
||
});
|
||
|
||
test('空 query → 空对象', () => {
|
||
assert.deepEqual(queryStringSource('')(), {});
|
||
});
|
||
|
||
test('不含前导 ? 也能解析', () => {
|
||
assert.deepEqual(queryStringSource('agentid=A1')(), { agentid: 'A1' });
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败** — `npm run test:framework` → FAIL（找不到 query-string.ts）
|
||
|
||
- [ ] **Step 3: 实现 query-string.ts**
|
||
|
||
创建 `config/sources/query-string.ts`：
|
||
|
||
```ts
|
||
import type { ChannelIdentity, IdentitySource } from '../identity.ts';
|
||
|
||
/** H5 模式：从 location.search 解析渠道身份覆盖。URLSearchParams 在浏览器/Cocos/Node 均可用。 */
|
||
export function queryStringSource(search: string): IdentitySource {
|
||
return () => {
|
||
const q = new URLSearchParams(search);
|
||
const out: Partial<ChannelIdentity> = {};
|
||
const agentid = q.get('agentid'); if (agentid) out.agentid = agentid;
|
||
const channelid = q.get('channelid'); if (channelid) out.channelid = channelid;
|
||
const marketid = q.get('marketid'); if (marketid) out.marketid = marketid;
|
||
const version = q.get('version'); if (version) out.version = version;
|
||
return out;
|
||
};
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试确认通过** — `npm run test:framework`（含 query-string 4 用例）+ `npm run typecheck:framework`
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
cd G:/Works/YouleGamesCocosCreator
|
||
git add cocoscreator_projects/YouleNexus/assets/framework/config/sources/query-string.ts cocoscreator_projects/framework-tests/config/sources/query-string.test.ts
|
||
git commit -m "feat(framework): config H5 URL query 身份来源
|
||
|
||
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: sources/native-settings.ts — 原生同步身份来源
|
||
|
||
**Files:**
|
||
- Create: `cocoscreator_projects/YouleNexus/assets/framework/config/sources/native-settings.ts`
|
||
- Create: `cocoscreator_projects/framework-tests/config/sources/native-settings.test.ts`
|
||
|
||
> 对应原 `Func.getothername("agent")`（→`window.settings.getothername` 或全局 `app_agent`）、`Func.getchannelName()`（→`window.settings.getchannelName`）、`Func.getmarketname()`（→`window.settings.getmarketname` 或全局 `app_market`）。接口名/全局名逐字一致（红线）。
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
创建 `framework-tests/config/sources/native-settings.test.ts`：
|
||
|
||
```ts
|
||
import { test } from 'node:test';
|
||
import assert from 'node:assert/strict';
|
||
import { nativeSettingsSource } from '../../../YouleNexus/assets/framework/config/sources/native-settings.ts';
|
||
|
||
test('优先从 window.settings 读取 agentid/channelid/marketid', () => {
|
||
const win = {
|
||
settings: {
|
||
getothername: (name: string) => (name === 'agent' ? 'NA' : ''),
|
||
getchannelName: () => 'NC',
|
||
getmarketname: () => 7,
|
||
},
|
||
};
|
||
assert.deepEqual(nativeSettingsSource(win)(), { agentid: 'NA', channelid: 'NC', marketid: 7 });
|
||
});
|
||
|
||
test('settings 抛错时回退到全局 app_agent / app_market', () => {
|
||
const win: any = {
|
||
settings: { getothername: () => { throw new Error('no bridge'); },
|
||
getchannelName: () => { throw new Error('no bridge'); },
|
||
getmarketname: () => { throw new Error('no bridge'); } },
|
||
app_agent: 'GA',
|
||
app_market: 5,
|
||
};
|
||
assert.deepEqual(nativeSettingsSource(win)(), { agentid: 'GA', marketid: 5 });
|
||
});
|
||
|
||
test('完全无原生注入 → 空对象', () => {
|
||
assert.deepEqual(nativeSettingsSource({})(), {});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败** — `npm run test:framework` → FAIL（找不到 native-settings.ts）
|
||
|
||
- [ ] **Step 3: 实现 native-settings.ts**
|
||
|
||
创建 `config/sources/native-settings.ts`：
|
||
|
||
```ts
|
||
import type { ChannelIdentity, IdentitySource } from '../identity.ts';
|
||
|
||
/** 原生注入宿主（≈ window）。settings 由原生注入；全局 app_* 为 uAgent_3 路径回退。 */
|
||
export interface NativeHost {
|
||
settings?: {
|
||
getothername?(name: string): string | number;
|
||
getchannelName?(): string | number;
|
||
getmarketname?(): string | number;
|
||
};
|
||
[global: string]: unknown; // app_agent / app_market 等
|
||
}
|
||
|
||
function tryRead(primary: () => unknown, fallback: () => unknown): unknown {
|
||
try {
|
||
const v = primary();
|
||
if (v !== undefined && v !== null && v !== '') return v;
|
||
} catch { /* 原生桥不存在，走回退 */ }
|
||
try { return fallback(); } catch { return undefined; }
|
||
}
|
||
|
||
function has(v: unknown): boolean { return v !== undefined && v !== null && v !== ''; }
|
||
|
||
/**
|
||
* 原生模式：同步读取渠道身份。逐字对齐原 05_Func.js：
|
||
* agent → window.settings.getothername('agent') | window.app_agent
|
||
* channel → window.settings.getchannelName()
|
||
* market → window.settings.getmarketname() | window.app_market
|
||
*/
|
||
export function nativeSettingsSource(win: NativeHost): IdentitySource {
|
||
return () => {
|
||
const out: Partial<ChannelIdentity> = {};
|
||
const agentid = tryRead(() => win.settings?.getothername?.('agent'), () => win['app_agent']);
|
||
if (has(agentid)) out.agentid = agentid as string | number;
|
||
const channelid = tryRead(() => win.settings?.getchannelName?.(), () => undefined);
|
||
if (has(channelid)) out.channelid = channelid as string | number;
|
||
const marketid = tryRead(() => win.settings?.getmarketname?.(), () => win['app_market']);
|
||
if (has(marketid)) out.marketid = marketid as string | number;
|
||
return out;
|
||
};
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试确认通过** — `npm run test:framework`（含 native-settings 3 用例）+ `npm run typecheck:framework`
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
cd G:/Works/YouleGamesCocosCreator
|
||
git add cocoscreator_projects/YouleNexus/assets/framework/config/sources/native-settings.ts cocoscreator_projects/framework-tests/config/sources/native-settings.test.ts
|
||
git commit -m "feat(framework): config 原生同步身份来源(window.settings/app_* 逐字对齐)
|
||
|
||
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: profiles.ts — 调试 profiles + URL 切换
|
||
|
||
**Files:**
|
||
- Create: `cocoscreator_projects/YouleNexus/assets/framework/config/profiles.ts`
|
||
- Create: `cocoscreator_projects/framework-tests/config/profiles.test.ts`
|
||
|
||
> 替代原 `Game_Config.Debugger`。`prod` 等价正式发布；`local`/`staging` 提供调试服地址与 gameserver。`ACTIVE_PROFILE` 发布只需保持 `prod`，`?profile=<name>` 可临时切换。地址取自原工程真实值（`00_SubGame_Config.js:11` 正式 gameserver、注释里的测试 gameserver、`12_Logic.js:573` 本地 `127.0.0.1:3088`）。
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
创建 `framework-tests/config/profiles.test.ts`：
|
||
|
||
```ts
|
||
import { test } from 'node:test';
|
||
import assert from 'node:assert/strict';
|
||
import { resolveActiveProfile, PROFILES, ACTIVE_PROFILE } from '../../YouleNexus/assets/framework/config/profiles.ts';
|
||
|
||
test('默认返回 ACTIVE_PROFILE', () => {
|
||
const p = resolveActiveProfile('');
|
||
assert.equal(p.name, ACTIVE_PROFILE);
|
||
});
|
||
|
||
test('prod profile 无调试覆盖、isDebugger=false', () => {
|
||
const prod = PROFILES['prod'];
|
||
assert.equal(prod.isDebugger, false);
|
||
assert.equal(prod.server, undefined);
|
||
assert.equal(prod.identity, undefined);
|
||
assert.ok(prod.gameserver && prod.gameserver.length > 0);
|
||
});
|
||
|
||
test('?profile=local 切到 local，含调试服地址', () => {
|
||
const p = resolveActiveProfile('?profile=local');
|
||
assert.equal(p.name, 'local');
|
||
assert.ok(p.server && p.server.startsWith('ws://'));
|
||
});
|
||
|
||
test('未知 profile 回退到 ACTIVE_PROFILE', () => {
|
||
const p = resolveActiveProfile('?profile=nope');
|
||
assert.equal(p.name, ACTIVE_PROFILE);
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败** — `npm run test:framework` → FAIL（找不到 profiles.ts）
|
||
|
||
- [ ] **Step 3: 实现 profiles.ts**
|
||
|
||
创建 `config/profiles.ts`：
|
||
|
||
```ts
|
||
import type { ChannelIdentity } from './identity.ts';
|
||
|
||
export interface DebugProfile {
|
||
name: string;
|
||
server?: string; // 显式 ws 调试服地址（给定则跳过远程抓取）
|
||
gameserver?: string; // 远程配置 txt URL（不含防缓存串）
|
||
identity?: Partial<ChannelIdentity>; // 调试用渠道身份覆盖
|
||
isDebugger?: boolean; // 收发包日志开关（替代旧 Game_Config.Debugger.isDebugger）
|
||
}
|
||
|
||
/** 正式 gameserver：原 00_SubGame_Config.js:11。 */
|
||
export const DEFAULT_GAMESERVER = 'http://ylyxservice1.0791ts.cn/config/update_json.txt';
|
||
/** 测试 gameserver：原 00_SubGame_Config.js:9 注释。 */
|
||
const STAGING_GAMESERVER = 'http://testgame.youlehdyx.com/update_json/ceshi_json.txt';
|
||
|
||
export const PROFILES: Record<string, DebugProfile> = {
|
||
prod: { name: 'prod', gameserver: DEFAULT_GAMESERVER, isDebugger: false },
|
||
staging: { name: 'staging', gameserver: STAGING_GAMESERVER, isDebugger: true },
|
||
local: { name: 'local', server: 'ws://127.0.0.1:3088', isDebugger: true },
|
||
};
|
||
|
||
/** 发布只需保持 'prod'。 */
|
||
export const ACTIVE_PROFILE = 'prod';
|
||
|
||
/** 解析当前 profile：ACTIVE_PROFILE 为基线，?profile=<name> 临时切换；未知名回退 ACTIVE_PROFILE。 */
|
||
export function resolveActiveProfile(search: string): DebugProfile {
|
||
const name = new URLSearchParams(search).get('profile') || ACTIVE_PROFILE;
|
||
return PROFILES[name] ?? PROFILES[ACTIVE_PROFILE];
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试确认通过** — `npm run test:framework`（含 profiles 4 用例）+ `npm run typecheck:framework`
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
cd G:/Works/YouleGamesCocosCreator
|
||
git add cocoscreator_projects/YouleNexus/assets/framework/config/profiles.ts cocoscreator_projects/framework-tests/config/profiles.test.ts
|
||
git commit -m "feat(framework): config 调试 profiles + ?profile= 切换
|
||
|
||
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: remote-config.ts — 分层取参 getParam + 服务器解析 resolveServers
|
||
|
||
**Files:**
|
||
- Create: `cocoscreator_projects/YouleNexus/assets/framework/config/remote-config.ts`
|
||
- Create: `cocoscreator_projects/framework-tests/config/remote-config.test.ts`
|
||
|
||
> `getParam` 忠实原 `get_paravalue`（12_Logic.js:1345）：`data[key]` 顶层默认，逐层进入匹配的 `agentlist→gamelist→channellist→marketlist`，越具体越优先；匹配键宽松比较 `==`（id 可能 string/number）。连接键名（`*_server_tcp`）逐字一致（getConfig_Succ 1404-1409）。
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
创建 `framework-tests/config/remote-config.test.ts`：
|
||
|
||
```ts
|
||
import { test } from 'node:test';
|
||
import assert from 'node:assert/strict';
|
||
import { getParam, resolveServers, type RemoteConfig } from '../../YouleNexus/assets/framework/config/remote-config.ts';
|
||
import type { ChannelIdentity } from '../../YouleNexus/assets/framework/config/identity.ts';
|
||
|
||
const ID: ChannelIdentity = { agentid: 'A', channelid: 'C', gameid: 'G', marketid: 2, version: '1', versionCode: 1 };
|
||
|
||
const CONFIG: RemoteConfig = {
|
||
data: {
|
||
player_server_tcp: '1.1.1.1:1000', // 顶层默认
|
||
agentlist: [{
|
||
agentid: 'A',
|
||
player_server_tcp: '2.2.2.2:2000', // agent 级覆盖
|
||
gamelist: [{
|
||
gameid: 'G',
|
||
channellist: [{
|
||
channelid: 'C',
|
||
player_server_tcp: '3.3.3.3:3000', // channel 级覆盖（最具体）
|
||
visitor_server_tcp: '4.4.4.4:4000',
|
||
marketlist: [{ marketid: 2 }],
|
||
}],
|
||
}],
|
||
}],
|
||
},
|
||
};
|
||
|
||
test('getParam：最具体层级胜出', () => {
|
||
assert.equal(getParam(CONFIG, 'player_server_tcp', ID), '3.3.3.3:3000');
|
||
});
|
||
|
||
test('getParam：channel 未匹配时回退到 agent 级值', () => {
|
||
const id2 = { ...ID, channelid: 'OTHER' };
|
||
assert.equal(getParam(CONFIG, 'player_server_tcp', id2), '2.2.2.2:2000');
|
||
});
|
||
|
||
test('getParam：agent 未匹配时回退到顶层默认', () => {
|
||
const id3 = { ...ID, agentid: 'NONE' };
|
||
assert.equal(getParam(CONFIG, 'player_server_tcp', id3), '1.1.1.1:1000');
|
||
});
|
||
|
||
test('getParam：键不存在 → null', () => {
|
||
assert.equal(getParam(CONFIG, 'not_a_key', ID), null);
|
||
});
|
||
|
||
test('getParam：无 data → null', () => {
|
||
assert.equal(getParam({}, 'player_server_tcp', ID), null);
|
||
});
|
||
|
||
test('resolveServers：player 优先、visitor 回退，前缀 ws://', () => {
|
||
assert.deepEqual(resolveServers(CONFIG, ID), ['ws://3.3.3.3:3000', 'ws://4.4.4.4:4000']);
|
||
});
|
||
|
||
test('resolveServers：已带 ws:// 不重复前缀；无地址 → 空数组', () => {
|
||
const cfg: RemoteConfig = { data: { player_server_tcp: 'ws://9.9.9.9:9' } };
|
||
assert.deepEqual(resolveServers(cfg, ID), ['ws://9.9.9.9:9']);
|
||
assert.deepEqual(resolveServers({ data: {} }, ID), []);
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败** — `npm run test:framework` → FAIL（找不到 remote-config.ts）
|
||
|
||
- [ ] **Step 3: 实现 remote-config.ts**
|
||
|
||
创建 `config/remote-config.ts`：
|
||
|
||
```ts
|
||
import type { ChannelIdentity } from './identity.ts';
|
||
|
||
/** 远程配置内层数据（键名逐字一致原 get_paravalue / getConfig_Succ）。 */
|
||
export interface MarketEntry { marketid: string | number; [k: string]: unknown; }
|
||
export interface ChannelEntry { channelid: string | number; marketlist?: MarketEntry[]; [k: string]: unknown; }
|
||
export interface GameEntry { gameid: string | number; channellist?: ChannelEntry[]; [k: string]: unknown; }
|
||
export interface AgentEntry { agentid: string | number; gamelist?: GameEntry[]; [k: string]: unknown; }
|
||
export interface RemoteConfigData { agentlist?: AgentEntry[]; [k: string]: unknown; }
|
||
export interface RemoteConfig { data?: RemoteConfigData; }
|
||
|
||
/** 远程配置抓取抽象（生产注入 HttpConfigFetcher，测试注入 fake）。 */
|
||
export interface ConfigFetcher { fetch(url: string): Promise<RemoteConfig>; }
|
||
|
||
export class ConfigFetchError extends Error {}
|
||
export class ConfigParseError extends Error {}
|
||
|
||
/**
|
||
* 分层取参，忠实原 get_paravalue：顶层 data[key] 为默认，逐层进入匹配项；
|
||
* 某层有该 key（truthy）则更新返回值；匹配链中断则返回当前最具体值。
|
||
*/
|
||
export function getParam(config: RemoteConfig, key: string, id: ChannelIdentity): unknown {
|
||
const data = config.data;
|
||
if (!data) return null;
|
||
let value: unknown = data[key] ? data[key] : null;
|
||
|
||
const descend = <T extends Record<string, unknown>>(
|
||
list: T[] | undefined, idKey: string, idVal: unknown,
|
||
): T | null => {
|
||
if (!list) return null;
|
||
for (const item of list) {
|
||
if (item[idKey] == idVal) { // 宽松比较，id 可能 string/number
|
||
if (item[key]) value = item[key];
|
||
return item;
|
||
}
|
||
}
|
||
return null;
|
||
};
|
||
|
||
const agent = descend(data.agentlist, 'agentid', id.agentid);
|
||
if (!agent) return value;
|
||
const game = descend(agent.gamelist, 'gameid', id.gameid);
|
||
if (!game) return value;
|
||
const channel = descend(game.channellist, 'channelid', id.channelid);
|
||
if (!channel) return value;
|
||
descend(channel.marketlist, 'marketid', id.marketid);
|
||
return value;
|
||
}
|
||
|
||
/** 连接相关参数键（逐字一致）。优先级即数组顺序。 */
|
||
const SERVER_KEYS = ['player_server_tcp', 'visitor_server_tcp', 'game_server_tcp'] as const;
|
||
|
||
function toWs(addr: string): string {
|
||
return (addr.startsWith('ws://') || addr.startsWith('wss://')) ? addr : 'ws://' + addr;
|
||
}
|
||
|
||
/** 解析 ws 候选服务器列表（按 SERVER_KEYS 优先级，去重）。 */
|
||
export function resolveServers(config: RemoteConfig, id: ChannelIdentity): string[] {
|
||
const out: string[] = [];
|
||
for (const key of SERVER_KEYS) {
|
||
const v = getParam(config, key, id);
|
||
if (typeof v === 'string' && v) {
|
||
const ws = toWs(v);
|
||
if (!out.includes(ws)) out.push(ws);
|
||
}
|
||
}
|
||
return out;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试确认通过** — `npm run test:framework`（含 remote-config 8 用例）+ `npm run typecheck:framework`
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
cd G:/Works/YouleGamesCocosCreator
|
||
git add cocoscreator_projects/YouleNexus/assets/framework/config/remote-config.ts cocoscreator_projects/framework-tests/config/remote-config.test.ts
|
||
git commit -m "feat(framework): config 远程配置分层取参 getParam + 服务器解析 resolveServers
|
||
|
||
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 6: bootstrap.ts — 启动编排 resolveBootstrap
|
||
|
||
**Files:**
|
||
- Create: `cocoscreator_projects/YouleNexus/assets/framework/config/bootstrap.ts`
|
||
- Create: `cocoscreator_projects/framework-tests/config/bootstrap.test.ts`
|
||
|
||
> 编排身份合并 + 服务器决策（profile 直连捷径 / 远程配置 / 失败降级），产出可直接喂 NetClient 的 `{ identity, servers }`。优先级：`defaults < (native|query) < profile.identity < 显式 query 覆盖`。
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
创建 `framework-tests/config/bootstrap.test.ts`：
|
||
|
||
```ts
|
||
import { test } from 'node:test';
|
||
import assert from 'node:assert/strict';
|
||
import { resolveBootstrap } from '../../YouleNexus/assets/framework/config/bootstrap.ts';
|
||
import { BUILD_IDENTITY } from '../../YouleNexus/assets/framework/config/sources/defaults.ts';
|
||
import type { ConfigFetcher, RemoteConfig } from '../../YouleNexus/assets/framework/config/remote-config.ts';
|
||
|
||
function fetcherReturning(config: RemoteConfig): ConfigFetcher & { calls: string[] } {
|
||
const calls: string[] = [];
|
||
return { calls, fetch: async (url: string) => { calls.push(url); return config; } };
|
||
}
|
||
const throwingFetcher: ConfigFetcher = {
|
||
fetch: async () => { throw new Error('net down'); },
|
||
};
|
||
|
||
const REMOTE: RemoteConfig = { data: { player_server_tcp: '5.5.5.5:5000' } };
|
||
|
||
test('profile=local：用 profile.server 直连，不抓远程', async () => {
|
||
const fetcher = fetcherReturning(REMOTE);
|
||
const r = await resolveBootstrap({ win: {}, search: '?profile=local', fetcher, isNative: false });
|
||
assert.deepEqual(r.servers, ['ws://127.0.0.1:3088']);
|
||
assert.equal(r.rawConfig, null);
|
||
assert.equal(fetcher.calls.length, 0);
|
||
});
|
||
|
||
test('prod + H5：抓远程配置产出 servers，identity 来自 defaults', async () => {
|
||
const fetcher = fetcherReturning(REMOTE);
|
||
const r = await resolveBootstrap({ win: {}, search: '', fetcher, isNative: false });
|
||
assert.deepEqual(r.servers, ['ws://5.5.5.5:5000']);
|
||
assert.equal(r.identity.agentid, BUILD_IDENTITY.agentid);
|
||
assert.equal(r.identity.gameid, BUILD_IDENTITY.gameid);
|
||
assert.equal(fetcher.calls.length, 1);
|
||
});
|
||
|
||
test('H5 显式 URL query 覆盖身份（最高优先级）', async () => {
|
||
const fetcher = fetcherReturning(REMOTE);
|
||
const r = await resolveBootstrap({ win: {}, search: '?agentid=999&channelid=C9', fetcher, isNative: false });
|
||
assert.equal(r.identity.agentid, '999');
|
||
assert.equal(r.identity.channelid, 'C9');
|
||
});
|
||
|
||
test('原生模式：identity 来自 window.settings', async () => {
|
||
const fetcher = fetcherReturning(REMOTE);
|
||
const win = { settings: { getothername: () => 'NA', getchannelName: () => 'NC', getmarketname: () => 3 } };
|
||
const r = await resolveBootstrap({ win, search: '', fetcher, isNative: true });
|
||
assert.equal(r.identity.agentid, 'NA');
|
||
assert.equal(r.identity.channelid, 'NC');
|
||
assert.equal(r.identity.marketid, 3);
|
||
});
|
||
|
||
test('远程失败 + 有 fallbackServers → 降级使用', async () => {
|
||
const r = await resolveBootstrap({ win: {}, search: '', fetcher: throwingFetcher, isNative: false, fallbackServers: ['ws://fb:1'] });
|
||
assert.deepEqual(r.servers, ['ws://fb:1']);
|
||
});
|
||
|
||
test('远程失败 + 无 fallback → 抛 ConfigFetchError', async () => {
|
||
await assert.rejects(
|
||
resolveBootstrap({ win: {}, search: '', fetcher: throwingFetcher, isNative: false }),
|
||
/远程配置抓取失败/,
|
||
);
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 2: 跑测试确认失败** — `npm run test:framework` → FAIL（找不到 bootstrap.ts）
|
||
|
||
- [ ] **Step 3: 实现 bootstrap.ts**
|
||
|
||
创建 `config/bootstrap.ts`：
|
||
|
||
```ts
|
||
import type { ChannelIdentity } from './identity.ts';
|
||
import { resolveIdentity } from './identity.ts';
|
||
import { BUILD_IDENTITY } from './sources/defaults.ts';
|
||
import { queryStringSource } from './sources/query-string.ts';
|
||
import { nativeSettingsSource, type NativeHost } from './sources/native-settings.ts';
|
||
import { resolveActiveProfile, DEFAULT_GAMESERVER, type DebugProfile } from './profiles.ts';
|
||
import { resolveServers, type ConfigFetcher, type RemoteConfig, ConfigFetchError } from './remote-config.ts';
|
||
|
||
export interface BootstrapOptions {
|
||
win: NativeHost; // 原生注入宿主（≈ window）
|
||
search: string; // location.search
|
||
fetcher: ConfigFetcher; // 远程配置抓取
|
||
isNative: boolean; // 环境判定（URL 含 index.html → true，由调用方算）
|
||
fallbackServers?: string[]; // 远程失败/无地址时降级
|
||
cacheBust?: () => string; // 防缓存串注入（默认 Date.now）
|
||
}
|
||
|
||
export interface BootstrapResult {
|
||
identity: ChannelIdentity;
|
||
servers: string[];
|
||
rawConfig: RemoteConfig | null;
|
||
profile: DebugProfile;
|
||
}
|
||
|
||
/** 启动编排：解析身份 + 决定服务器，产出可喂 NetClient 的结果。 */
|
||
export async function resolveBootstrap(opts: BootstrapOptions): Promise<BootstrapResult> {
|
||
const profile = resolveActiveProfile(opts.search);
|
||
const runtime = opts.isNative ? nativeSettingsSource(opts.win) : queryStringSource(opts.search);
|
||
const identity = resolveIdentity([
|
||
() => BUILD_IDENTITY,
|
||
runtime,
|
||
() => profile.identity ?? {},
|
||
queryStringSource(opts.search), // 显式 URL 覆盖（最高）
|
||
]);
|
||
|
||
// 服务器决策：profile 显式 server 直连捷径
|
||
if (profile.server) {
|
||
return { identity, servers: [profile.server], rawConfig: null, profile };
|
||
}
|
||
|
||
// 否则远程配置
|
||
const base = profile.gameserver ?? DEFAULT_GAMESERVER;
|
||
const bust = opts.cacheBust ? opts.cacheBust() : String(Date.now());
|
||
const url = base + '?' + bust; // 防缓存，等价原 min_timestamp/ifast_random
|
||
|
||
let config: RemoteConfig;
|
||
try {
|
||
config = await opts.fetcher.fetch(url);
|
||
} catch {
|
||
if (opts.fallbackServers && opts.fallbackServers.length) {
|
||
return { identity, servers: opts.fallbackServers, rawConfig: null, profile };
|
||
}
|
||
throw new ConfigFetchError(`远程配置抓取失败: ${url}`);
|
||
}
|
||
|
||
let servers = resolveServers(config, identity);
|
||
if (!servers.length && opts.fallbackServers && opts.fallbackServers.length) {
|
||
servers = opts.fallbackServers;
|
||
}
|
||
return { identity, servers, rawConfig: config, profile };
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 跑测试确认通过** — `npm run test:framework`（含 bootstrap 6 用例）+ `npm run typecheck:framework`
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
cd G:/Works/YouleGamesCocosCreator
|
||
git add cocoscreator_projects/YouleNexus/assets/framework/config/bootstrap.ts cocoscreator_projects/framework-tests/config/bootstrap.test.ts
|
||
git commit -m "feat(framework): config 启动编排 resolveBootstrap(身份合并+服务器决策+降级)
|
||
|
||
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 7: remote-config-fetcher.ts — 生产用 HTTP 抓取（typecheck-only）
|
||
|
||
**Files:**
|
||
- Create: `cocoscreator_projects/YouleNexus/assets/framework/config/remote-config-fetcher.ts`
|
||
|
||
> 生产实现，依赖运行时全局 `fetch`（浏览器/Cocos 均提供）。无单测（同 `cocos-transport.ts` 处理），仅 typecheck。方法用 GET 抓取静态配置 txt（原 `get_config` 用 POST 抓静态文件；静态文件服务器 GET/POST 均返回同一文件，此处用语义更正确的 GET，不需要服务器改动）。
|
||
|
||
- [ ] **Step 1: 实现 remote-config-fetcher.ts**
|
||
|
||
创建 `config/remote-config-fetcher.ts`：
|
||
|
||
```ts
|
||
import type { ConfigFetcher, RemoteConfig } from './remote-config.ts';
|
||
import { ConfigParseError } from './remote-config.ts';
|
||
|
||
/** 生产用 ConfigFetcher：全局 fetch 抓取远程配置 txt 并 JSON.parse。 */
|
||
export class HttpConfigFetcher implements ConfigFetcher {
|
||
async fetch(url: string): Promise<RemoteConfig> {
|
||
const resp = await fetch(url, { method: 'GET' });
|
||
const text = await resp.text();
|
||
try {
|
||
return JSON.parse(text) as RemoteConfig;
|
||
} catch {
|
||
throw new ConfigParseError(`远程配置 JSON 解析失败: ${url}`);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 类型检查**
|
||
|
||
Run: `npm run typecheck:framework`
|
||
Expected: exit 0（`fetch`/`Response` 由 tsconfig `lib:["DOM"]` 提供）
|
||
|
||
- [ ] **Step 3: 跑全部框架测试（回归）**
|
||
|
||
Run: `npm run test:framework`
|
||
Expected: PASS（全部用例，含本计划新增 config 用例 + Plan 2 原有用例）
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
cd G:/Works/YouleGamesCocosCreator
|
||
git add cocoscreator_projects/YouleNexus/assets/framework/config/remote-config-fetcher.ts
|
||
git commit -m "feat(framework): config 生产用 HttpConfigFetcher(全局 fetch)
|
||
|
||
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
## 验收标准（完成定义）
|
||
|
||
1. `npm run test:framework` 全绿；`npm run typecheck:framework` exit 0。
|
||
2. config 层：身份类型 + 纯合并、构建期默认、H5/原生两个身份来源、调试 profiles + URL 切换、远程配置 `getParam`（忠实 get_paravalue）+ `resolveServers`、启动编排 `resolveBootstrap`、生产 fetcher 齐备。
|
||
3. `resolveBootstrap` 在 mock（fake fetcher + fake 环境）下，能产出可直接喂给 `NetClient` 的 `{ identity, servers }`，覆盖：profile 直连捷径 / 远程配置 / 失败降级 / 身份四级优先级 / 原生与 H5 两模式。
|
||
4. 外部契约字符串（协议字段名、原生接口名 `getothername/getchannelName/getmarketname`、远程配置键 `agentlist/.../player_server_tcp` 等）逐字保留。
|
||
|
||
## 后续衔接
|
||
|
||
- platform Plan：复用同一 `getParam` 提取平台/UI 类远程参数（`menunotice`/`scrollmsg`/`service_*`/`logimage`/`rankList`…）。
|
||
- 端到端联调（Plan 2 Task 12 Step 4-5）：`resolveBootstrap` + `HttpConfigFetcher` 接真实配置服与 `NetClient`，跑真实 login 往返。
|
||
- sdk Plan：完整异步 WVJB 桥（分享/视频/语音等），本计划只做了身份相关的同步原生读取。
|
||
```
|