create-fullstack-scaffold 0.1.0

package/template/src/shared/core/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @framework-baseline f51621ebf8da3453
+ *
+ * 此文件属于框架层代码。如需修改，请添加以下说明：
+ *
+ * @framework-modify
+ * @reason [必填] 修改原因
+ * @impact [必填] 影响范围
+ */
+
+// API Schemas
+export {
+  ApiSuccessSchema,
+  ApiErrorSchema,
+  ApiResponseSchema,
+  type ApiSuccess,
+  type ApiError,
+  type ApiResponse,
+} from './api-schemas'
+
+// Protocol Types
+export type { RpcMethod, EventName, RpcInput, RpcOutput, EventPayload } from './protocol-types'
+
+// WS Client
+export {
+  WSClientImpl,
+  createWSClient,
+  type WSClient,
+  type WSProtocol,
+  type WSStatus,
+} from './ws-client'
+
+// SSE Client
+export { SSEClientImpl, createSSEClient, type SSEClient, type SSEProtocol } from './sse-client'
+
+// Module Manifest
+export type { ModuleManifest, ModuleRegistry, TemplatePreset } from './module-manifest'

package/template/src/shared/core/module-manifest.ts

@@ -0,0 +1,120 @@
+/**
+ * @framework-baseline f51621ebf8da3453
+ *
+ * 此文件属于框架层代码。如需修改，请添加以下说明：
+ *
+ * @framework-modify
+ * @reason [必填] 修改原因
+ * @impact [必填] 影响范围
+ */
+
+/**
+ * Module manifest — declarative description of a module's capabilities and dependencies.
+ * Each module-xxx directory should have a module.ts that exports a ModuleManifest.
+ */
+export interface ModuleManifest {
+  /** Unique module identifier (e.g., 'todos', 'chat', 'admin') */
+  name: string
+
+  /** Human-readable description */
+  description: string
+
+  /** Category for grouping in templates */
+  category: 'core' | 'communication' | 'business' | 'system'
+
+  /** Other module names this module depends on */
+  dependsOn: string[]
+
+  /** Route registration info */
+  routes: {
+    /** Routes mounted under client API (/api) */
+    client?: {
+      /** Import path to the route variable (relative to module dir) */
+      importPath: string
+      /** Exported variable name from the route file */
+      exportName: string
+    }
+    /** Routes mounted under admin API (/api/admin) */
+    admin?: {
+      importPath: string
+      exportName: string
+    }[]
+    /** Standalone routes (e.g., /files) */
+    standalone?: {
+      importPath: string
+      exportName: string
+      mountPath: string
+    }
+  }
+
+  /** Shared schemas exported by this module */
+  sharedSchemas?: {
+    /** Directory path under shared/modules/ */
+    path: string
+    /** Additional shared module paths owned by this module (e.g., 'role', 'audit' for permission) */
+    additionalPaths?: string[]
+  }
+
+  /** Client-facing pages (React) */
+  clientPages?: {
+    /** Page component name (also filename) */
+    name: string
+    /** Route path in the client router */
+    route: string
+  }[]
+
+  /** Admin panel pages (React + Ant Design) */
+  adminPages?: {
+    name: string
+    route: string
+    /** Whether the page is public (no auth required) */
+    isPublic?: boolean
+    /** Required permission to access this page */
+    requiredPermission?: string
+  }[]
+
+  /** Database schema files (Drizzle table definitions) */
+  dbSchemas?: {
+    /** Filename in server/db/schema/ (without .ts extension) */
+    files: string[]
+    /** Whether the module has seed data */
+    hasSeed: boolean
+  }
+
+  /** Required npm dependencies (beyond what core provides) */
+  dependencies?: Record<string, string>
+
+  /** Client stores */
+  clientStores?: string[]
+
+  /** Middleware that this module provides (used by app.ts) */
+  providesMiddleware?: {
+    /** Middleware name */
+    name: string
+    /** Import path (from server/middleware/) */
+    importPath: string
+    /** Which routes it applies to */
+    appliesTo: 'client-api' | 'admin-api' | 'all-api' | 'standalone'
+  }[]
+
+  /** Whether this module has SSE (Server-Sent Events) routes */
+  hasSSE?: boolean
+
+  /** Whether this module has WebSocket routes */
+  hasWebSocket?: boolean
+}
+
+/** Type-safe module registry — maps module name to its manifest */
+export type ModuleRegistry = Record<string, ModuleManifest>
+
+/** Template preset — defines which modules a template includes */
+export interface TemplatePreset {
+  /** Preset identifier */
+  id: string
+  /** Human-readable name */
+  name: string
+  /** Description shown in CLI */
+  description: string
+  /** Module names to include (order matters for registration) */
+  modules: string[]
+}

package/template/src/shared/core/protocol-types.ts

@@ -0,0 +1,26 @@
+/**
+ * @framework-baseline ab15d84c70311810
+ *
+ * 此文件属于框架层代码。如需修改，请添加以下说明：
+ *
+ * @framework-modify
+ * @reason [必填] 修改原因
+ * @impact [必填] 影响范围
+ */
+
+export type RpcMethod<T extends { rpc: unknown }> = keyof T['rpc']
+export type EventName<T extends { events: unknown }> = keyof T['events']
+
+export type RpcInput<T extends { rpc: unknown }, M extends RpcMethod<T>> = T['rpc'][M] extends {
+  in: infer I
+}
+  ? I
+  : never
+
+export type RpcOutput<T extends { rpc: unknown }, M extends RpcMethod<T>> = T['rpc'][M] extends {
+  out: infer O
+}
+  ? O
+  : never
+
+export type EventPayload<T extends { events: unknown }, E extends EventName<T>> = T['events'][E]

package/template/src/shared/core/sse-client.ts

@@ -0,0 +1,185 @@
+/**
+ * @framework-baseline 0a1efed4372dadaa
+ *
+ * 此文件属于框架层代码。如需修改，请添加以下说明：
+ *
+ * @framework-modify
+ * @reason 使用 fetch API 替代 EventSource，支持自定义 headers（认证）
+ * @impact SSE 客户端现在支持 Authorization header
+ */
+
+export interface SSEProtocol {
+  events: Record<string, unknown>
+}
+
+export interface SSEClient<P extends SSEProtocol = SSEProtocol> {
+  readonly status: 'connecting' | 'open' | 'closed'
+  on<K extends keyof P['events']>(type: K, handler: (payload: P['events'][K]) => void): () => void
+  onStatusChange(handler: (status: 'connecting' | 'open' | 'closed') => void): () => void
+  onError(handler: (error: Error) => void): () => void
+  abort(): void
+}
+
+export class SSEClientImpl<P extends SSEProtocol = SSEProtocol> implements SSEClient<P> {
+  private abortController: AbortController | null = null
+  private handlers = new Map<string, ((payload: unknown) => void)[]>()
+  private statusHandlers: ((status: 'connecting' | 'open' | 'closed') => void)[] = []
+  private errorHandlers: ((error: Error) => void)[] = []
+  private _status: 'connecting' | 'open' | 'closed' = 'connecting'
+  private reconnectAttempts = 0
+  private maxReconnectAttempts = 5
+  private reconnectDelay = 1000
+  private url: string | URL
+  private headers: Record<string, string>
+
+  constructor(url: string | URL, headers: Record<string, string> = {}) {
+    this.url = url
+    this.headers = headers
+    this.connect()
+  }
+
+  get status() {
+    return this._status
+  }
+
+  private async connect() {
+    this._status = 'connecting'
+    this.abortController = new AbortController()
+
+    try {
+      const response = await fetch(this.url.toString(), {
+        headers: {
+          Accept: 'text/event-stream',
+          ...this.headers,
+        },
+        signal: this.abortController.signal,
+      })
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+      }
+
+      this._status = 'open'
+      this.reconnectAttempts = 0
+      this.statusHandlers.forEach(h => h('open'))
+
+      const reader = response.body?.getReader()
+      if (!reader) {
+        throw new Error('No response body')
+      }
+
+      const decoder = new TextDecoder()
+      let buffer = ''
+      let eventType = 'message'
+      let dataBuffer = ''
+
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+
+        buffer += decoder.decode(value, { stream: true })
+
+        // Process complete messages (separated by \n\n)
+        const messages = buffer.split('\n\n')
+        // Keep the last incomplete message in buffer
+        buffer = messages.pop() || ''
+
+        for (const message of messages) {
+          const lines = message.split('\n')
+          eventType = 'message'
+          dataBuffer = ''
+
+          for (const line of lines) {
+            if (line.startsWith('event:')) {
+              eventType = line.slice(6).trim()
+            } else if (line.startsWith('data:')) {
+              dataBuffer = line.slice(5).trim()
+            }
+          }
+
+          if (dataBuffer) {
+            this.handleMessage(eventType, dataBuffer)
+          }
+        }
+      }
+
+      this._status = 'closed'
+      this.statusHandlers.forEach(h => h('closed'))
+    } catch (error) {
+      if ((error as Error).name === 'AbortError') {
+        this._status = 'closed'
+        this.statusHandlers.forEach(h => h('closed'))
+        return
+      }
+
+      this.errorHandlers.forEach(h => h(error as Error))
+      this.attemptReconnect()
+    }
+  }
+
+  private attemptReconnect() {
+    if (this.reconnectAttempts < this.maxReconnectAttempts) {
+      this.reconnectAttempts++
+      setTimeout(() => {
+        this.connect()
+      }, this.reconnectDelay * this.reconnectAttempts)
+    } else {
+      this._status = 'closed'
+      this.statusHandlers.forEach(h => h('closed'))
+    }
+  }
+
+  private handleMessage(eventType: string, data: string) {
+    try {
+      const parsed = JSON.parse(data)
+      const handlers = this.handlers.get(eventType)
+      handlers?.forEach(h => h(parsed))
+    } catch {
+      const handlers = this.handlers.get(eventType)
+      handlers?.forEach(h => h(data))
+    }
+  }
+
+  on<K extends keyof P['events']>(type: K, handler: (payload: P['events'][K]) => void): () => void {
+    const eventName = type as string
+    const list = this.handlers.get(eventName) || []
+    list.push(handler as (payload: unknown) => void)
+    this.handlers.set(eventName, list)
+
+    return () => {
+      const filtered = (this.handlers.get(eventName) || []).filter(h => h !== handler)
+      this.handlers.set(eventName, filtered)
+    }
+  }
+
+  onStatusChange(handler: (status: 'connecting' | 'open' | 'closed') => void): () => void {
+    this.statusHandlers.push(handler)
+    handler(this._status)
+    return () => {
+      this.statusHandlers = this.statusHandlers.filter(h => h !== handler)
+    }
+  }
+
+  onError(handler: (error: Error) => void): () => void {
+    this.errorHandlers.push(handler)
+    return () => {
+      this.errorHandlers = this.errorHandlers.filter(h => h !== handler)
+    }
+  }
+
+  abort(): void {
+    if (this.abortController) {
+      this.abortController.abort()
+      this.abortController = null
+    }
+    this._status = 'closed'
+    this.statusHandlers.forEach(h => h('closed'))
+  }
+}
+
+export function createSSEClient<P extends SSEProtocol>(
+  url: string | URL,
+  headers: Record<string, string> = {}
+): SSEClient<P> {
+  return new SSEClientImpl<P>(url, headers)
+}

package/template/src/shared/core/ws-client.ts

@@ -0,0 +1,236 @@
+/**
+ * @framework-baseline 4437e01c1b0bcabb
+ *
+ * 此文件属于框架层代码。如需修改，请添加以下说明：
+ *
+ * @framework-modify
+ * @reason WSClientImpl 不再 extends WebSocket，改为动态基类模式兼容 browser/node 环境
+ * @impact 所有使用 WSClientImpl 的地方不再需要 WebSocket 类型断言
+ */
+
+export type WSStatus = 'connecting' | 'open' | 'closed' | 'reconnecting'
+
+export interface WSProtocol {
+  rpc: Record<string, { in: unknown; out: unknown }>
+  events: Record<string, unknown>
+}
+
+export interface WSClient<T extends WSProtocol = WSProtocol> {
+  readonly status: WSStatus
+  getSocket(): WebSocket | null
+  call<K extends keyof T['rpc']>(
+    method: K,
+    params: T['rpc'][K] extends { in: infer I } ? I : never,
+    timeout?: number
+  ): Promise<T['rpc'][K] extends { out: infer O } ? O : never>
+  emit<K extends keyof T['events']>(type: K, payload: T['events'][K]): void
+  on<K extends keyof T['events']>(type: K, handler: (payload: T['events'][K]) => void): () => void
+  onStatusChange(handler: (status: WSStatus) => void): () => void
+  close(): void
+}
+
+type PendingRequest = {
+  resolve: (val: unknown) => void
+  reject: (err: unknown) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+interface WSMessageBase {
+  id?: string
+  method?: string
+  type?: string
+  payload?: unknown
+  result?: unknown
+  error?: string
+}
+
+const _hasWebSocket = typeof globalThis !== 'undefined' && 'WebSocket' in globalThis
+
+const WS_OPEN = _hasWebSocket ? (globalThis.WebSocket as typeof WebSocket).OPEN : 1
+const WS_CONNECTING = _hasWebSocket ? (globalThis.WebSocket as typeof WebSocket).CONNECTING : 0
+
+const WebSocketClass: typeof WebSocket | null = _hasWebSocket
+  ? (globalThis.WebSocket as typeof WebSocket)
+  : null
+
+class StubWebSocket {
+  binaryType: BinaryType = 'blob'
+  bufferedAmount = 0
+  extensions = ''
+  onclose: ((ev: CloseEvent) => void) | null = null
+  onerror: ((ev: Event) => void) | null = null
+  onmessage: ((ev: MessageEvent) => void) | null = null
+  onopen: ((ev: Event) => void) | null = null
+  protocol = ''
+  readyState = 0
+  url = ''
+  send(_data: string | ArrayBufferLike | Blob | ArrayBufferView) {
+    return 0 as never
+  }
+  close(_code?: number, _reason?: string) {}
+  addEventListener() {}
+  removeEventListener() {}
+  dispatchEvent() {
+    return true
+  }
+  static readonly CONNECTING = 0
+  static readonly OPEN = 1
+  static readonly CLOSING = 2
+  static readonly CLOSED = 3
+}
+
+type WSBase = WebSocket | StubWebSocket
+
+function createWSBase(url: string): WSBase {
+  if (WebSocketClass) {
+    return new WebSocketClass(url)
+  }
+  return new StubWebSocket()
+}
+
+export class WSClientImpl<P extends WSProtocol = WSProtocol> implements WSClient<P> {
+  private ws: WSBase
+  private handlers = new Map<string, ((payload: unknown) => void)[]>()
+  private pendingRequests = new Map<string, PendingRequest>()
+  private statusHandlers: ((status: WSStatus) => void)[] = []
+  private messageBuffer: string[] = []
+  private _status: WSStatus = 'closed'
+
+  get status(): WSStatus {
+    return this._status
+  }
+
+  getSocket(): WebSocket | null {
+    return (this.ws instanceof StubWebSocket ? null : this.ws) as WebSocket | null
+  }
+
+  constructor(url: string | URL) {
+    this.ws = createWSBase(url.toString())
+    this.attachSocket()
+  }
+
+  private attachSocket() {
+    const ws = this.ws
+    if (ws.readyState === WS_OPEN) {
+      this._status = 'open'
+    } else if (ws.readyState === WS_CONNECTING) {
+      this._status = 'connecting'
+    } else {
+      this._status = 'closed'
+    }
+    ws.onmessage = msg => this.handleMessage(msg)
+    ws.onclose = () => {
+      if (this._status !== 'closed') {
+        this.handleClose()
+      }
+    }
+    ws.onerror = () => {
+      if (this._status !== 'closed') {
+        this.updateStatus('closed')
+      }
+    }
+    ws.onopen = () => {
+      if (this._status !== 'open') {
+        this.handleOpen()
+      }
+    }
+  }
+
+  private handleOpen() {
+    this.updateStatus('open')
+    while (this.messageBuffer.length > 0) {
+      const msg = this.messageBuffer.shift()
+      if (msg) this.ws.send(msg)
+    }
+  }
+
+  private handleClose() {
+    this.updateStatus('closed')
+  }
+
+  private handleMessage(event: MessageEvent) {
+    try {
+      const data: WSMessageBase = JSON.parse(event.data)
+
+      if ('id' in data && !('method' in data)) {
+        const pending = this.pendingRequests.get(data.id!)
+        if (pending) {
+          clearTimeout(pending.timer)
+          this.pendingRequests.delete(data.id!)
+          if (data.error) pending.reject(new Error(data.error))
+          else pending.resolve(data.result)
+        }
+      } else if ('type' in data) {
+        const callbacks = this.handlers.get(data.type!)
+        callbacks?.forEach(cb => cb(data.payload))
+      }
+    } catch (e) {
+      console.error('Failed to parse WS message', e)
+    }
+  }
+
+  private updateStatus(status: WSStatus) {
+    this._status = status
+    this.statusHandlers.forEach(h => h(status))
+  }
+
+  async call<K extends keyof P['rpc']>(
+    method: K,
+    params: P['rpc'][K] extends { in: infer I } ? I : never,
+    timeout = 10000
+  ): Promise<P['rpc'][K] extends { out: infer O } ? O : never> {
+    return new Promise((resolve, reject) => {
+      const id = Math.random().toString(36).slice(2)
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id)
+        reject(new Error(`RPC Timeout: ${String(method)}`))
+      }, timeout)
+
+      this.pendingRequests.set(id, {
+        resolve: resolve as (val: unknown) => void,
+        reject,
+        timer,
+      })
+
+      this.sendRaw({ id, method, params })
+    })
+  }
+
+  emit<K extends keyof P['events']>(type: K, payload: P['events'][K]) {
+    this.sendRaw({ type, payload })
+  }
+
+  on<K extends keyof P['events']>(type: K, handler: (payload: P['events'][K]) => void) {
+    const list = this.handlers.get(type as string) || []
+    list.push(handler as (payload: unknown) => void)
+    this.handlers.set(type as string, list)
+    return () => {
+      const filtered = (this.handlers.get(type as string) || []).filter(h => h !== handler)
+      this.handlers.set(type as string, filtered)
+    }
+  }
+
+  onStatusChange(handler: (status: WSStatus) => void) {
+    this.statusHandlers.push(handler)
+    return () => {
+      this.statusHandlers = this.statusHandlers.filter(h => h !== handler)
+    }
+  }
+
+  close(): void {
+    this.ws.close()
+  }
+
+  private sendRaw(data: unknown) {
+    const msg = JSON.stringify(data)
+    if (this.ws.readyState === WS_OPEN) {
+      this.ws.send(msg)
+    } else {
+      this.messageBuffer.push(msg)
+    }
+  }
+}
+
+export function createWSClient<P extends WSProtocol>(url: string | URL): WSClient<P> {
+  return new WSClientImpl<P>(url)
+}

package/template/src/shared/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useWebSocket } from './useWebSocket'
+export { useSSE } from './useSSE'

package/template/src/shared/hooks/useSSE.ts

@@ -0,0 +1,57 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { SSEClient, SSEProtocol } from '@shared/schemas'
+
+type SSEStatus = 'connecting' | 'open' | 'closed'
+
+interface UseSSEReturn<T extends SSEProtocol> {
+  status: SSEStatus
+  connect: () => Promise<void>
+  disconnect: () => void
+  client: SSEClient<T> | null
+}
+
+export function useSSE<T extends SSEProtocol>(route: () => Promise<SSEClient<T>>): UseSSEReturn<T> {
+  const [status, setStatus] = useState<SSEStatus>('closed')
+  const clientRef = useRef<SSEClient<T> | null>(null)
+
+  const connect = useCallback(async () => {
+    if (clientRef.current) return
+
+    setStatus('connecting')
+
+    try {
+      const client = await route()
+      clientRef.current = client
+
+      client.onStatusChange((newStatus: 'connecting' | 'open' | 'closed') => {
+        setStatus(newStatus)
+      })
+
+      setStatus(client.status)
+    } catch (error) {
+      console.error('Failed to connect SSE:', error)
+      setStatus('closed')
+    }
+  }, [route])
+
+  const disconnect = useCallback(() => {
+    if (clientRef.current) {
+      clientRef.current.abort()
+      clientRef.current = null
+      setStatus('closed')
+    }
+  }, [])
+
+  useEffect(() => {
+    return () => {
+      disconnect()
+    }
+  }, [disconnect])
+
+  return {
+    status,
+    connect,
+    disconnect,
+    client: clientRef.current,
+  }
+}