@realsee/vr-cli 0.1.3

package/templates/base/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "packageManager": "npm@11.19.0",
+  "scripts": {
+    "dev": "npm run check:env && concurrently --kill-others-on-fail --names bff,web \"npm:dev:bff\" \"npm:dev:web\"",
+    "dev:bff": "node --env-file-if-exists=.env.development --watch server/index.ts",
+    "dev:web": "vite",
+    "check:env": "node --env-file-if-exists=.env.development server/check-config.ts",
+    "typecheck": "npm run typecheck:web && npm run typecheck:bff",
+    "typecheck:web": "tsc -p tsconfig.json",
+    "typecheck:bff": "tsc -p tsconfig.server.json",
+    "lint": "eslint . --max-warnings=0",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check:bff": "npm run typecheck:bff",
+    "check": "npm run typecheck && npm run lint && npm run format:check",
+    "deps:relock": "npm install --package-lock-only",
+    "deps:install": "npm ci",
+    "build": "npm run check && vite build",
+    "start": "node --env-file-if-exists=.env.development server/index.ts --serve-frontend",
+    "preview": "npm run start"
+  },
+  "dependencies": {
+    "@fastify/static": ">=10.1.3",
+    "@realsee/dnalogel": ">=3.81.2",
+    "@realsee/five": ">=6.8.9",
+    "@realsee/vapor": ">=0.2.12",
+    "fastify": ">=5.12.1",
+    "react": ">=18.3.1",
+    "react-dom": ">=18.3.1",
+    "three": "0.117.1"
+  },
+  "devDependencies": {
+    "@eslint/js": ">=10.0.1",
+    "@types/node": ">=24.13.3",
+    "@types/react": ">=18.3.12",
+    "@types/react-dom": ">=18.3.1",
+    "@vitejs/plugin-react": ">=4.3.1",
+    "concurrently": ">=10.0.5",
+    "eslint": ">=10.9.1",
+    "eslint-plugin-react-hooks": ">=7.1.1",
+    "globals": ">=17.11.0",
+    "prettier": ">=3.9.6",
+    "typescript": ">=5.9.3",
+    "typescript-eslint": ">=8.68.0",
+    "vite": ">=5.4.14"
+  },
+  "engines": {
+    "node": ">=22.18.0",
+    "npm": ">=11.19.0"
+  }
+}

package/templates/base/prettier.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  semi: false,
+  singleQuote: true,
+  trailingComma: 'all',
+}

package/templates/base/server/app.ts

@@ -0,0 +1,54 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Fastify, { type FastifyInstance } from 'fastify'
+import fastifyStatic from '@fastify/static'
+import { workRoutes } from './work-route.ts'
+import type { WorkService } from './types.ts'
+
+const PROJECT_ROOT = fileURLToPath(new URL('..', import.meta.url))
+
+export interface CreateAppOptions {
+  readonly workService: WorkService
+  readonly logger?: boolean
+  readonly serveFrontend?: boolean
+  readonly frontendRoot?: string
+}
+
+export async function createApp({
+  workService,
+  logger = true,
+  serveFrontend = false,
+  frontendRoot = path.join(PROJECT_ROOT, 'dist'),
+}: CreateAppOptions): Promise<FastifyInstance> {
+  const app = Fastify({ logger })
+
+  app.get('/api/health', () => ({ ok: true }))
+  await app.register(workRoutes, { workService })
+
+  if (serveFrontend) {
+    await app.register(fastifyStatic, {
+      root: frontendRoot,
+      prefix: '/',
+    })
+    app.setNotFoundHandler((request, reply) => {
+      const pathname = new URL(request.raw.url ?? '/', 'http://localhost')
+        .pathname
+      const acceptsHtml = request.headers.accept
+        ?.split(',')
+        .some((value) => value.trim().startsWith('text/html'))
+      const isApiPath = pathname === '/api' || pathname.startsWith('/api/')
+      const hasFileExtension = path.posix.extname(pathname).length > 0
+      if (
+        request.raw.method === 'GET' &&
+        acceptsHtml &&
+        !isApiPath &&
+        !hasFileExtension
+      ) {
+        return reply.sendFile('index.html')
+      }
+      return reply.code(404).send({ error: 'NOT_FOUND', requestId: request.id })
+    })
+  }
+
+  return app
+}

package/templates/base/server/check-config.ts

@@ -0,0 +1,4 @@
+import { loadServerConfig } from './config.ts'
+
+loadServerConfig()
+console.log('BFF server configuration is valid.')

package/templates/base/server/config.ts

@@ -0,0 +1,54 @@
+import type { ServerConfig } from './types.ts'
+
+const DEFAULT_GATEWAY_ENDPOINT = 'https://app-gateway.realsee.cn'
+
+type ServerEnv = Record<string, string | undefined>
+
+export interface LoadServerConfigOptions {
+  readonly env?: ServerEnv
+  readonly serveFrontend?: boolean
+}
+
+const nonEmptyString = (value: string | undefined): value is string =>
+  typeof value === 'string' && value.trim().length > 0
+
+function requiredCredential(env: ServerEnv, key: string): string {
+  const value = env[key]?.trim()
+  if (!nonEmptyString(value) || value === '*') {
+    throw new Error(
+      `${key} 未配置。请从 .env.example 创建 .env.development，并填写服务端凭据。`,
+    )
+  }
+  return value
+}
+
+function parsePort(value: string | undefined, fallback: number): number {
+  if (!nonEmptyString(value)) return fallback
+  const port = Number(value)
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`BFF_PORT 必须是 1-65535 的整数，当前为：${value}`)
+  }
+  return port
+}
+
+export function loadServerConfig({
+  env = process.env,
+  serveFrontend = false,
+}: LoadServerConfigOptions = {}): ServerConfig {
+  const gatewayEndpoint = new URL(
+    env.REALSEE_GATEWAY_ENDPOINT?.trim() || DEFAULT_GATEWAY_ENDPOINT,
+  )
+  if (gatewayEndpoint.protocol !== 'https:') {
+    throw new Error(
+      'REALSEE_GATEWAY_ENDPOINT 必须使用 HTTPS，避免泄露服务端凭据。',
+    )
+  }
+
+  return Object.freeze({
+    host: env.BFF_HOST?.trim() || '127.0.0.1',
+    port: parsePort(env.BFF_PORT, serveFrontend ? 8087 : 8088),
+    gatewayEndpoint: gatewayEndpoint.href.replace(/\/$/, ''),
+    appKey: requiredCredential(env, 'REALSEE_GATEWAY_APP_KEY'),
+    appSecret: requiredCredential(env, 'REALSEE_GATEWAY_APP_SECRET'),
+  })
+}

package/templates/base/server/index.ts

@@ -0,0 +1,31 @@
+import { createApp } from './app.ts'
+import { loadServerConfig } from './config.ts'
+import { RealseeOpenApiClient } from './realsee-open-api.ts'
+import { createWorkService } from './work-service.ts'
+
+const serveFrontend = process.argv.includes('--serve-frontend')
+const config = loadServerConfig({ serveFrontend })
+const openApiClient = new RealseeOpenApiClient(config)
+const workService = createWorkService({ openApiClient })
+const app = await createApp({ workService, serveFrontend })
+
+let closing = false
+const close = async (signal: string): Promise<void> => {
+  if (closing) return
+  closing = true
+  app.log.info({ signal }, 'Shutting down Fastify BFF')
+  await app.close()
+}
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.once(signal, () => {
+    void close(signal).finally(() => process.exit(0))
+  })
+}
+
+try {
+  await app.listen({ host: config.host, port: config.port })
+} catch (error) {
+  app.log.error(error)
+  process.exitCode = 1
+}

package/templates/base/server/realsee-open-api.ts

@@ -0,0 +1,316 @@
+import { asModelFloorplanServerData } from '../shared/model-floorplan.ts'
+import type { ModelFloorplanServerData } from '../shared/model-floorplan.ts'
+import type {
+  RawRecord,
+  RealseeSpatialClient,
+  RequestOptions,
+  ServerConfig,
+  UpstreamEnvelope,
+} from './types.ts'
+
+// Official contracts: POST /auth/access_token, GET /open/v3/vr/info,
+// and GET /open/v3/floorplan/plugins. Authorization carries the raw access token.
+const ACCESS_TOKEN_PATH = '/auth/access_token'
+const WORK_INFO_PATH = '/open/v3/vr/info'
+const FLOORPLAN_PLUGINS_PATH = '/open/v3/floorplan/plugins'
+const TOKEN_REFRESH_SKEW_MS = 30_000
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000
+
+const isRecord = (value: unknown): value is RawRecord =>
+  Boolean(value && typeof value === 'object' && !Array.isArray(value))
+const asRecord = (value: unknown): RawRecord => (isRecord(value) ? value : {})
+const firstString = (...values: unknown[]): string | undefined =>
+  values.find(
+    (value): value is string => typeof value === 'string' && value.length > 0,
+  )
+const upstreamCode = (payload: UpstreamEnvelope): number => Number(payload.code)
+// The gateway reports auth failures as HTTP 200 with a negative business code
+// (for example `-3 authorization parse fail`), so HTTP 401 alone is not enough.
+const UNAUTHORIZED_UPSTREAM_CODES = new Set([401, -3])
+const isUnauthorized = (
+  response: Response,
+  payload: UpstreamEnvelope,
+): boolean =>
+  response.status === 401 ||
+  UNAUTHORIZED_UPSTREAM_CODES.has(upstreamCode(payload))
+
+function expirationTime(value: unknown): number {
+  const numeric = Number(value)
+  if (!Number.isFinite(numeric) || numeric <= 0) return 0
+  return numeric < 1_000_000_000_000 ? numeric * 1000 : numeric
+}
+
+export interface RealseeOpenApiErrorOptions {
+  readonly responseStatus?: number
+  readonly responseCode?: unknown
+  readonly statusCode?: number
+}
+
+export class RealseeOpenApiError extends Error {
+  readonly responseStatus: number
+  readonly responseCode: unknown
+  readonly statusCode: number
+
+  constructor(message: string, options: RealseeOpenApiErrorOptions = {}) {
+    super(message)
+    const { responseStatus = 0, responseCode, statusCode } = options
+    this.name = 'RealseeOpenApiError'
+    this.responseStatus = responseStatus
+    this.responseCode = responseCode
+    this.statusCode =
+      statusCode ??
+      (responseStatus === 404 || Number(responseCode) === 404 ? 404 : 502)
+  }
+}
+
+type FetchImpl = typeof globalThis.fetch
+
+export interface RealseeOpenApiClientOptions extends Pick<
+  ServerConfig,
+  'gatewayEndpoint' | 'appKey' | 'appSecret'
+> {
+  readonly fetchImpl?: FetchImpl
+  readonly now?: () => number
+  readonly requestTimeoutMs?: number
+}
+
+interface UpstreamResult {
+  readonly response: Response
+  readonly payload: UpstreamEnvelope
+}
+
+export class RealseeOpenApiClient implements RealseeSpatialClient {
+  readonly gatewayEndpoint: string
+  readonly appKey: string
+  readonly appSecret: string
+  readonly fetchImpl: FetchImpl
+  readonly now: () => number
+  readonly requestTimeoutMs: number
+
+  #accessToken = ''
+  #expiresAt = 0
+  #tokenPromise: Promise<string> | null = null
+
+  constructor({
+    gatewayEndpoint,
+    appKey,
+    appSecret,
+    fetchImpl = globalThis.fetch,
+    now = Date.now,
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+  }: RealseeOpenApiClientOptions) {
+    if (typeof fetchImpl !== 'function')
+      throw new Error('RealseeOpenApiClient 需要 fetch 实现。')
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0)
+      throw new Error('requestTimeoutMs 必须是正数。')
+    this.gatewayEndpoint = gatewayEndpoint.replace(/\/$/, '')
+    this.appKey = appKey
+    this.appSecret = appSecret
+    this.fetchImpl = fetchImpl
+    this.now = now
+    this.requestTimeoutMs = requestTimeoutMs
+  }
+
+  #requestSignal(signal: AbortSignal | undefined): AbortSignal {
+    const timeoutSignal = AbortSignal.timeout(this.requestTimeoutMs)
+    return signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal
+  }
+
+  async #fetchJson(
+    requestUrl: string,
+    init: RequestInit,
+  ): Promise<UpstreamResult> {
+    let response: Response
+    try {
+      response = await this.fetchImpl(requestUrl, init)
+    } catch (error) {
+      const timedOut = error instanceof Error && error.name === 'TimeoutError'
+      throw new RealseeOpenApiError(
+        timedOut
+          ? `Realsee OpenAPI 请求超过 ${this.requestTimeoutMs}ms。`
+          : `Realsee OpenAPI 网络请求失败：${error instanceof Error ? error.message : String(error)}`,
+        { statusCode: timedOut ? 504 : 502 },
+      )
+    }
+
+    let payload: UpstreamEnvelope
+    try {
+      payload = asRecord(await response.json())
+    } catch {
+      throw new RealseeOpenApiError('Realsee OpenAPI 返回了无效 JSON。', {
+        responseStatus: response.status,
+      })
+    }
+    return { response, payload }
+  }
+
+  #assertSuccess(
+    response: Response,
+    payload: UpstreamEnvelope,
+    operation: string,
+  ): void {
+    const code = upstreamCode(payload)
+    if (!response.ok || code !== 0) {
+      const message =
+        firstString(payload.status, payload.msg, payload.message) ||
+        `HTTP ${response.status}`
+      throw new RealseeOpenApiError(`${operation}失败：${message}`, {
+        responseStatus: response.status,
+        responseCode: payload.code,
+      })
+    }
+  }
+
+  async #exchangeAccessToken(): Promise<string> {
+    const body = new URLSearchParams({
+      app_key: this.appKey,
+      app_secret: this.appSecret,
+    })
+    const { response, payload } = await this.#fetchJson(
+      `${this.gatewayEndpoint}${ACCESS_TOKEN_PATH}`,
+      {
+        method: 'POST',
+        headers: {
+          Accept: 'application/json',
+          'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body,
+        signal: this.#requestSignal(undefined),
+      },
+    )
+    this.#assertSuccess(response, payload, '获取 access token')
+
+    const data = asRecord(payload.data)
+    const accessToken = firstString(data.access_token, payload.access_token)
+    const expiresAt = expirationTime(data.expire_at ?? payload.expire_at)
+    if (!accessToken || expiresAt <= this.now()) {
+      throw new RealseeOpenApiError(
+        'access token 响应缺少有效的 access_token 或 expire_at。',
+      )
+    }
+
+    this.#accessToken = accessToken
+    this.#expiresAt = expiresAt
+    return accessToken
+  }
+
+  async #getAccessToken(): Promise<string> {
+    if (
+      this.#accessToken &&
+      this.now() < this.#expiresAt - TOKEN_REFRESH_SKEW_MS
+    ) {
+      return this.#accessToken
+    }
+    if (this.#tokenPromise) return this.#tokenPromise
+
+    const promise = this.#exchangeAccessToken()
+    this.#tokenPromise = promise
+    try {
+      return await promise
+    } finally {
+      if (this.#tokenPromise === promise) this.#tokenPromise = null
+    }
+  }
+
+  #invalidateAccessToken(rejectedToken: string): void {
+    if (this.#accessToken !== rejectedToken) return
+    this.#accessToken = ''
+    this.#expiresAt = 0
+  }
+
+  async #requestAuthenticated(
+    pathname: string,
+    operation: string,
+    signal: AbortSignal | undefined,
+  ): Promise<UpstreamEnvelope> {
+    const request = (accessToken: string) =>
+      this.#fetchJson(`${this.gatewayEndpoint}${pathname}`, {
+        method: 'GET',
+        headers: {
+          Accept: 'application/json',
+          Authorization: accessToken,
+        },
+        signal: this.#requestSignal(signal),
+      })
+
+    let accessToken = await this.#getAccessToken()
+    let result = await request(accessToken)
+    if (isUnauthorized(result.response, result.payload)) {
+      this.#invalidateAccessToken(accessToken)
+      accessToken = await this.#getAccessToken()
+      result = await request(accessToken)
+    }
+
+    this.#assertSuccess(result.response, result.payload, operation)
+    return result.payload
+  }
+
+  async getWorkDetail(
+    resourceCode: string,
+    { signal }: RequestOptions = {},
+  ): Promise<RawRecord> {
+    const query = new URLSearchParams({ resource_code: resourceCode })
+    const payload = await this.#requestAuthenticated(
+      `${WORK_INFO_PATH}?${query.toString()}`,
+      '获取 Work',
+      signal,
+    )
+    const work = asRecord(payload.data)
+    if (!Object.keys(work).length)
+      throw new RealseeOpenApiError('Work 响应缺少有效的 data 对象。')
+    return work
+  }
+
+  async getModelFloorplan(
+    resourceCode: string,
+    { signal }: RequestOptions = {},
+  ): Promise<ModelFloorplanServerData | undefined> {
+    const query = new URLSearchParams({ resource_code: resourceCode })
+    const descriptor = await this.#requestAuthenticated(
+      `${FLOORPLAN_PLUGINS_PATH}?${query.toString()}`,
+      '获取平面图插件描述',
+      signal,
+    )
+    const formatFloorplanUrl = firstString(
+      asRecord(descriptor.data).format_floorplan_url,
+    )
+    if (!formatFloorplanUrl) return undefined
+
+    let floorplanUrl: URL
+    try {
+      floorplanUrl = new URL(formatFloorplanUrl)
+    } catch {
+      throw new RealseeOpenApiError('format_floorplan_url 不是有效 URL。')
+    }
+    if (
+      floorplanUrl.protocol !== 'https:' ||
+      floorplanUrl.username ||
+      floorplanUrl.password
+    ) {
+      throw new RealseeOpenApiError(
+        'format_floorplan_url 必须是无内嵌凭据的 HTTPS URL。',
+      )
+    }
+
+    const { response, payload } = await this.#fetchJson(floorplanUrl.href, {
+      method: 'GET',
+      headers: { Accept: 'application/json' },
+      redirect: 'error',
+      signal: this.#requestSignal(signal),
+    })
+    if (!response.ok) {
+      throw new RealseeOpenApiError(
+        `获取 format_floorplan_url 失败：HTTP ${response.status}`,
+        { responseStatus: response.status },
+      )
+    }
+
+    const floorplan = asModelFloorplanServerData(payload)
+    if (!floorplan) {
+      throw new RealseeOpenApiError(
+        'format_floorplan_url 未返回有效的 { version, data: FloorplanServerData }。',
+      )
+    }
+    return floorplan
+  }
+}

package/templates/base/server/types.ts

@@ -0,0 +1,64 @@
+import type { ModelFloorplanServerData } from '../shared/model-floorplan.ts'
+
+// Shared server-side contracts. The browser only depends on the HTTP shape of
+// WorkEnvelope, so a Go or other backend can replace this module entirely.
+
+export type RawRecord = Record<string, unknown>
+
+export interface ServerConfig {
+  readonly host: string
+  readonly port: number
+  readonly gatewayEndpoint: string
+  readonly appKey: string
+  readonly appSecret: string
+}
+
+export interface RequestOptions {
+  readonly signal?: AbortSignal | undefined
+}
+
+export interface WorkCapabilities {
+  readonly modelFloorplan?: ModelFloorplanServerData
+}
+
+/** Browser-safe response envelope for `GET /api/work/{resourceCode}`. */
+export interface WorkEnvelope {
+  readonly work: RawRecord
+  readonly workCode: string
+  readonly baseURL?: string
+  readonly capabilities?: WorkCapabilities
+}
+
+/** Upstream adapter boundary: returns the raw Work payload for a resource code. */
+export interface WorkDetailClient {
+  getWorkDetail(
+    resourceCode: string,
+    options?: RequestOptions,
+  ): Promise<RawRecord>
+}
+
+/** Optional plugin-data boundary. Absence means the capability is unavailable. */
+export interface ModelFloorplanClient {
+  getModelFloorplan(
+    resourceCode: string,
+    options?: RequestOptions,
+  ): Promise<ModelFloorplanServerData | undefined>
+}
+
+export interface RealseeSpatialClient
+  extends WorkDetailClient, ModelFloorplanClient {}
+
+/** Framework-neutral service boundary consumed by the HTTP layer. */
+export interface WorkService {
+  getWorkByResourceCode(
+    resourceCode: string,
+    options?: RequestOptions,
+  ): Promise<WorkEnvelope>
+}
+
+/** Standard Realsee OpenAPI response envelope. */
+export interface UpstreamEnvelope extends RawRecord {
+  readonly code?: unknown
+  readonly status?: unknown
+  readonly data?: unknown
+}

package/templates/base/server/work-route.ts

@@ -0,0 +1,80 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+import type { WorkEnvelope, WorkService } from './types.ts'
+
+const RESOURCE_CODE_PATTERN = '^[A-Za-z0-9_-]{1,128}$'
+
+export interface WorkRoutesOptions {
+  readonly workService: WorkService
+}
+
+interface WorkRouteParams {
+  readonly resourceCode: string
+}
+
+const upstreamStatusCode = (error: unknown): number => {
+  const statusCode =
+    error && typeof error === 'object' && 'statusCode' in error
+      ? Number((error as { statusCode?: unknown }).statusCode)
+      : undefined
+  if (statusCode === 404) return 404
+  if (statusCode === 504) return 504
+  return 502
+}
+
+export function workRoutes(
+  app: FastifyInstance,
+  { workService }: WorkRoutesOptions,
+  done: (error?: Error) => void,
+): void {
+  app.get(
+    '/api/work/:resourceCode',
+    {
+      schema: {
+        params: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['resourceCode'],
+          properties: {
+            resourceCode: { type: 'string', pattern: RESOURCE_CODE_PATTERN },
+          },
+        },
+      },
+    },
+    async (
+      request: FastifyRequest<{ Params: WorkRouteParams }>,
+      reply: FastifyReply,
+    ): Promise<WorkEnvelope | FastifyReply> => {
+      const { resourceCode } = request.params
+      const requestAbort = new AbortController()
+      const abortDisconnectedRequest = (): void => {
+        if (request.raw.aborted || !request.raw.complete) requestAbort.abort()
+      }
+      request.raw.once('close', abortDisconnectedRequest)
+
+      try {
+        return await workService.getWorkByResourceCode(resourceCode, {
+          signal: requestAbort.signal,
+        })
+      } catch (error) {
+        const statusCode = upstreamStatusCode(error)
+        request.log.error(
+          { err: error, resourceCode },
+          'Work BFF request failed',
+        )
+        return reply.code(statusCode).send({
+          error:
+            statusCode === 404
+              ? 'WORK_NOT_FOUND'
+              : statusCode === 504
+                ? 'WORK_UPSTREAM_TIMEOUT'
+                : 'WORK_UPSTREAM_FAILED',
+          requestId: request.id,
+        })
+      } finally {
+        request.raw.off('close', abortDisconnectedRequest)
+      }
+    },
+  )
+
+  done()
+}