@goplus123/core-api 1.0.1

package/README.md

@@ -0,0 +1,462 @@
+# @goplus123/core-api
+
+`core-api` 是一个以 `initSDK` 为装配点的单例 SDK，内部统一封装了三种传输层（HTTP / WS / gRPC），并提供：
+
+- spec 驱动的统一调用入口：`requestApi`
+- 类型安全的 service client：`sdk.cms.* / sdk.admin.* / sdk.platform.*`
+- WS 推送订阅与本地事件分发：`notify(type)`
+- 统一错误归一化与中间件：`apiError.use(...)`
+
+入口文件：[`src/index.ts`](file:///d:/working/GX/tsup/packages/api/src/index.ts)
+
+---
+
+## 项目目录结构
+
+```txt
+packages/api
+  src/
+    index.ts              SDK 入口（initSDK / requestApi / notify / apiError）
+    client/               HTTP/WS/gRPC client + unifiedClient + interceptors
+    routing/router.ts     spec registry 构建 + requestApi 路由与兜底逻辑
+    spec/                 spec 驱动路由表（apiMap / endpoints 定义）
+    modules/              legacy 模块式封装（主要用于部分 gRPC 服务兼容）
+    grpcWeb/              生成代码（proto → ts），不要手改
+    utils/                小工具（如 fetchGuid）
+```
+
+建议的扩展方式：
+
+- 新增/调整业务接口路由：改 `src/spec/*`，由 `apiMap` 生效
+- 调整调用链行为（鉴权/日志/错误归一化）：改 `src/client/*` 与 `src/routing/router.ts`
+- 兼容历史“模块式调用”：保留 `src/modules/*`（目前用于 auth/packet/... 等）
+
+## 调用链路概览
+
+从“推荐的 service client”到具体 transport，大致会走：
+
+1. `sdk.<service>.<method>(payload, options?)`
+2. `requestApi({ service, functionName, requestParam, wsOptions/callOptions })`
+3. 路由选择与兜底：[`src/routing/router.ts`](file:///d:/working/GX/tsup/packages/api/src/routing/router.ts)
+   - 先查 spec registry（由 `rebuildEndpointRegistry()` 从 `apiMap` 构建）
+   - 命中后交给 `UnifiedApiClient` 分发到 `grpc/ws/http`
+   - 未命中则尝试 legacy `serviceInstances`
+   - 再未命中则兜底走 raw WS（需要已初始化 `ws`）
+
+## 常见开发场景
+
+- 新增 gRPC endpoint：先确认 `src/grpcWeb/grpc/**` 有对应 service/schema，再在 `src/spec/<service>.ts` 增加 `defineEndpoint`
+- 给同一方法加多协议：使用 `defineEndpointGroup`，同时提供 `grpc/ws/http` 变体
+- 改默认 transport 或自动选择策略：调整 [`pickEndpoint`](file:///d:/working/GX/tsup/packages/api/src/routing/router.ts#L267-L296)
+- 新增全局鉴权/日志：通过 `initSDK({ auth, logger })`，或改 `src/client/interceptors.ts`
+
+---
+
+## 安装与导入
+
+```ts
+import { initSDK, requestApi, notify, apiError, fetchGuid } from '@goplus123/core-api'
+```
+
+---
+
+## 快速开始
+
+### 1) 初始化
+
+`initSDK` 是 SDK 的唯一初始化入口（单例，多次调用会覆盖旧状态）。
+
+```ts
+const sdk = initSDK({
+  ws: {
+    url: 'wss://example.com/websocket',
+    protocols: fetchGuid(),
+    debug: true,
+  },
+  grpc: {
+    baseUrl: 'https://example.com/cms',
+  },
+  http: {
+    baseUrl: 'https://example.com/api',
+  },
+  headerConfig: {
+    version: '1.0.0',
+    platformId: '50',
+    isReload: false,
+    deviceType: 1,
+    deviceId: '',
+    childPlatformId: '50',
+  },
+  defaultTransport: 'auto',
+  auth: {
+    getToken: () => localStorage.getItem('token'),
+    getHeaders: () => ({ 'x-lang': 'zh-CN' }),
+  },
+  onApiError: (error) => {
+    console.error('[onApiError]', error)
+  },
+  logger: console,
+})
+```
+
+初始化后得到：
+
+- `sdk.api`：底层 `RequestApi`（包含 `http/ws/grpc` 三个 client）
+- `sdk.client`：统一路由分发的 `UnifiedApiClient`
+- `sdk.rpc`：对外暴露的 `WsRpcClient`（便于调试 / 订阅）
+- `sdk.cms / sdk.admin / sdk.platform`：类型安全的 service client（由 spec 生成）
+- `sdk.apiError / sdk.notify`：全局错误与通知中心（同名导出也可直接使用）
+
+对应实现：[`initSDK`](file:///d:/working/GX/tsup/packages/api/src/index.ts#L372-L578)
+
+### 2) 直接调用（推荐）
+
+优先使用 service client（类型提示完整，第二参随 transport 自动变化）：
+
+```ts
+await sdk.cms?.getPageResource({
+  resourceId: 'HOME_PAGE',
+})
+```
+
+### 3) 统一调用（更底层、更灵活）
+
+当你想通过 `service + functionName` 动态调用时，使用 `requestApi`：
+
+```ts
+await requestApi({
+  service: 'cms',
+  functionName: 'getPageResource',
+  requestParam: { resourceId: 'HOME_PAGE' },
+})
+```
+
+---
+
+## Transport 选择规则
+
+`requestApi` 的 transport 决策优先级：
+
+1. 调用参数 `args.transport`
+2. spec 上的 `defaultTransport`（仅对 `defineEndpointGroup` 生效）
+3. `initSDK({ defaultTransport })`
+4. `'auto'`（默认）：按当前 SDK 初始化状态优先选择 `grpc → ws → http`
+
+对应逻辑：[`pickEndpoint`](file:///d:/working/GX/tsup/packages/api/src/routing/router.ts#L267-L296)
+
+---
+
+## WS 推送与事件
+
+### 订阅 WS 推送
+
+`notify(type)` 会创建一个 channel，并在初始化了 `ws` 时自动挂载到 `ws.notify`。
+
+```ts
+const off = notify<{ gameId: string }>('notifyGameInfo').subscribe((payload) => {
+  console.log('game info:', payload)
+})
+
+// off()
+```
+
+### 监听 WS 连接状态
+
+SDK 内置了 `ws:status` 通道（初始化时自动绑定到 WS 事件）：
+
+```ts
+notify('ws:status').subscribe((s) => {
+  console.log('ws status:', s.state, s.readyState)
+})
+```
+
+也可以同步读取快照：
+
+```ts
+import { getWsSnapshot } from '@goplus123/core-api'
+
+const { isConnected, readyState, status } = getWsSnapshot()
+```
+
+---
+
+## 错误处理
+
+### 全局错误中间件
+
+```ts
+apiError.use((error, ctx, next) => {
+  console.error('[apiError]', ctx.source, error)
+  return next()
+})
+```
+
+- `initSDK({ onApiError })` 会自动注册一层中间件
+- 未初始化时调用 `apiError.use/emit` 为 no-op（会输出 warn）
+
+---
+
+## API 参考（对外导出）
+
+来自：[`src/index.ts`](file:///d:/working/GX/tsup/packages/api/src/index.ts)
+
+### initSDK(config)
+
+- 作用：初始化（或重置）SDK 单例，并按配置装配 HTTP/WS/gRPC、路由、拦截器与 service clients
+- 入参类型：`RequestApiConfig`（见 [`RequestApiConfig`](file:///d:/working/GX/tsup/packages/api/src/client/requestApi.ts#L7-L36)）
+- 返回：`{ api, rpc?, client?, wsNotify?, apiError, notify, ...services }`
+
+### destroySDK()
+
+- 作用：释放资源（断开 WS、清空全局状态、重置路由与中心）
+
+### getSDK()
+
+- 作用：获取底层 `RequestApi` 实例
+- 注意：未初始化会抛错
+
+### requestApi(args) / callApi(args)
+
+- 作用：统一调用入口（spec 驱动路由；若 spec 未命中，会尝试 legacy serviceInstances，再兜底走 raw WS）
+- 入参：
+  - `service: string`
+  - `functionName: string`
+  - `transport?: 'http' | 'ws' | 'grpc' | 'auto'`
+  - `requestParam?: any`
+  - `wsOptions?: WsRequestOptions`
+  - `callOptions?: CallOptions`
+  - `meta?: Record<string, any>`
+
+### notify(type)
+
+- 作用：获取通知通道（可 `use/subscribe/emit/destroy`）
+- 注意：未初始化会返回 dummy channel（不会报错，但会 warn）
+
+### apiError
+
+- `apiError.use(middleware)`：注册错误中间件
+- `apiError.emit(error, source?)`：手动注入一个归一化后的 `ApiError`
+
+### fetchGuid()
+
+- 作用：生成一个短 id（playground 用于 WS `protocols`）
+
+---
+
+## spec 驱动的 Service 列表
+
+spec 定义入口：[`spec/index.ts`](file:///d:/working/GX/tsup/packages/api/src/spec/index.ts)
+
+按 service 拆分的落点文件：
+
+- cms：[`spec/cms.ts`](file:///d:/working/GX/tsup/packages/api/src/spec/cms.ts)
+- admin：[`spec/admin.ts`](file:///d:/working/GX/tsup/packages/api/src/spec/admin.ts)
+- platform：[`spec/platform.ts`](file:///d:/working/GX/tsup/packages/api/src/spec/platform.ts)
+
+### cms（gRPC 为主，部分接口可多协议）
+
+- `getPageResource`
+- `getPageGameList`（multi：grpc + ws）
+- `getJackpotResources`
+- `readPopup`
+- `readEventPopup`
+- `getAmbassadorConfig`
+- `getAmbassadorConfigDetail`
+- `searchGame`
+- `searchGameV2`
+- `getSportConfig`
+- `getSportTodayMatch`
+- `getGameSuggestions`
+
+### admin（gRPC）
+
+- `signIn`
+- `getAdminProfileByJwt`
+- `validateAdmin`
+- `signUpAdmin`
+- `updatePlatformConfig`
+- `checkHasPermission`
+- `getGameName`
+- `getPlayerCredibilityRemarkId`
+- `getMarketingDepartmentConfig`
+- `createMarketingDepartmentConfig`
+- `updateMarketingDepartmentConfig`
+- `deleteMarketingDepartmentConfig`
+
+### platform（WS）
+
+- `getConfig`
+
+---
+
+## 为接口新增/扩展 transport（spec 写法）
+
+spec 工具位于：[`spec/endpoint.ts`](file:///d:/working/GX/tsup/packages/api/src/spec/endpoint.ts)
+
+## 开发指南：如何补充 spec 路由
+
+spec 的职责是给 `requestApi` 提供“路由表”：
+
+- runtime 上它会被加载进 `apiMap`，并在 `initSDK()` 时构建 registry（见 [`rebuildEndpointRegistry`](file:///d:/working/GX/tsup/packages/api/src/routing/router.ts#L84-L132)）
+- 调用方可以通过 `sdk.<service>.<method>()` 或 `requestApi({ service, functionName })` 走到对应 transport
+- 当调用方显式指定 `transport` 时，如果 spec 中没有对应变体，会在路由选择阶段同步抛错
+
+### 1) 选择落点文件
+
+- cms 的 spec：[`src/spec/cms.ts`](file:///d:/working/GX/tsup/packages/api/src/spec/cms.ts)
+- admin 的 spec：[`src/spec/admin.ts`](file:///d:/working/GX/tsup/packages/api/src/spec/admin.ts)
+- platform（WS）spec：[`src/spec/platform.ts`](file:///d:/working/GX/tsup/packages/api/src/spec/platform.ts)
+- 聚合与 apiMap：[`src/spec/index.ts`](file:///d:/working/GX/tsup/packages/api/src/spec/index.ts)
+
+### 2) 约定：id / service / functionName
+
+- `id` 建议固定为：`<service>.<functionName>`，例如 `cms.getPageGameList`
+- `requestApi` 侧入参使用：`service: '<service>'` + `functionName: '<functionName>'`
+- WS spec 内的 `ws.service / ws.functionName` 是 WS 协议层的 service/functionName（通常与上面一致，但不是强制）
+
+### 3) 新增一个 endpoint（单协议）
+
+#### gRPC（最常见）
+
+在 `src/spec/cms.ts`（或对应 service 的 spec 文件）中追加：
+
+```ts
+import type { MessageInit } from '../client/grpcClient'
+import { defineEndpoint } from './endpoint'
+import { FrontendService as CmsFrontendService } from '../grpcWeb/grpc/cms/FrontendService_pb'
+import type { PageResourceRes } from '../grpcWeb/grpc/cms/GetPageResource_pb'
+import { PageResourceReqSchema } from '../grpcWeb/grpc/cms/GetPageResource_pb'
+
+export const cmsEndpoints = {
+  // ...
+  getPageResource: defineEndpoint<MessageInit<typeof PageResourceReqSchema>, PageResourceRes>({
+    id: 'cms.getPageResource',
+    transport: 'grpc',
+    grpc: {
+      service: CmsFrontendService,
+      methodName: 'getPageResource',
+      requestSchema: PageResourceReqSchema,
+    },
+  }),
+}
+```
+
+调用方式：
+
+```ts
+await requestApi({
+  service: 'cms',
+  functionName: 'getPageResource',
+  requestParam: { resourceId: 'HOME_PAGE' },
+})
+```
+
+或（更推荐）通过 service client：
+
+```ts
+await sdk.cms?.getPageResource({ resourceId: 'HOME_PAGE' })
+```
+
+#### WS
+
+在 `src/spec/platform.ts`（或你新增的 service 对应 spec 文件）追加：
+
+```ts
+import { defineEndpoint } from './endpoint'
+
+export const platformEndpoints = {
+  getConfig: defineEndpoint<any, any>({
+    id: 'platform.getConfig',
+    transport: 'ws',
+    ws: { service: 'platform', functionName: 'getConfig', timeout: 10000 },
+  }),
+}
+```
+
+调用方式：
+
+```ts
+await requestApi({
+  service: 'platform',
+  functionName: 'getConfig',
+  requestParam: { platformId: '50' },
+})
+```
+
+### 4) 给同一个 endpoint 增加新的 transport 变体（多协议）
+
+当你希望同一业务方法同时支持 `grpc/ws/http` 时，用 `defineEndpointGroup`：
+
+- `defaultTransport`：该 endpoint 在未指定 `transport` 时的默认选择
+- `transports`：按 transport 分别提供配置
+
+```ts
+import type { MessageInit } from '../client/grpcClient'
+import { defineEndpointGroup } from './endpoint'
+import { FrontendService as CmsFrontendService } from '../grpcWeb/grpc/cms/FrontendService_pb'
+import type { PageGameListRes } from '../grpcWeb/grpc/cms/GetPageGameList_pb'
+import { PageGameListReqSchema } from '../grpcWeb/grpc/cms/GetPageGameList_pb'
+
+export const cmsEndpoints = {
+  // ...
+  getPageGameList: defineEndpointGroup<MessageInit<typeof PageGameListReqSchema>, PageGameListRes>({
+    id: 'cms.getPageGameList',
+    defaultTransport: 'grpc',
+    transports: {
+      grpc: { service: CmsFrontendService, methodName: 'getPageGameList', requestSchema: PageGameListReqSchema },
+      ws: { service: 'cms', functionName: 'getPageGameList' },
+    },
+  }),
+}
+```
+
+调用时可显式选择：
+
+```ts
+await requestApi({
+  service: 'cms',
+  functionName: 'getPageGameList',
+  transport: 'ws',
+  requestParam: { resourceId: 'GAME_PAGE_ALL_GAMES', pagination: { limit: 10, offset: 0 } },
+})
+```
+
+注意：增加 WS/http 变体不仅是前端 spec 改动，服务端也必须实现对应 handler，否则会在 transport 层报错（但不会再卡在路由校验阶段）。
+
+### 5) 新增一个 service（扩展 apiMap / 返回的 sdk）
+
+如果要新增 `fooEndpoints` 这样的新 service：
+
+1. 新建 `src/spec/foo.ts` 并导出 `fooEndpoints`
+2. 在 `src/spec/index.ts` 里导出 `fooEndpoints`，并把它加入 `apiMap`
+3. 在 `src/index.ts` 的 `initSDK` 返回类型里补充 `foo?: ApiServiceClient<'foo'>`
+4. 在 `initSDK` 里按 transport 条件创建 `sdk.foo = createApiServiceClient('foo')`
+
+`createApiServiceClient` 的实现位置：[`createApiServiceClient`](file:///d:/working/GX/tsup/packages/api/src/index.ts#L592-L683)
+
+### 单协议（defineEndpoint）
+
+```ts
+import { defineEndpoint } from './endpoint'
+
+export const demo = defineEndpoint({
+  id: 'cms.getPageResource',
+  transport: 'grpc',
+  grpc: { service: CmsFrontendService, methodName: 'getPageResource', requestSchema: PageResourceReqSchema },
+})
+```
+
+### 多协议（defineEndpointGroup）
+
+```ts
+import { defineEndpointGroup } from './endpoint'
+
+export const demo = defineEndpointGroup({
+  id: 'cms.getPageGameList',
+  defaultTransport: 'grpc',
+  transports: {
+    grpc: { service: CmsFrontendService, methodName: 'getPageGameList', requestSchema: PageGameListReqSchema },
+    ws: { service: 'cms', functionName: 'getPageGameList' },
+  },
+})
+```