create-fullstack-scaffold 0.1.0

package/template/src/server/utils/logger.ts

@@ -0,0 +1,139 @@
+/* eslint-disable no-console */
+import type { Logger, LoggerOptions } from 'pino'
+import pino from 'pino'
+import { resolve } from 'path'
+import { existsSync, mkdirSync } from 'fs'
+import { getAppConfig } from '../config'
+import { isCloudflare } from '../utils/env'
+
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+
+const _loggers: Map<string, Logger> = new Map()
+
+export interface LogFnFields {
+  [key: string]: unknown
+}
+
+interface SimpleLogger {
+  trace: (obj: LogFnFields, msg: string) => void
+  debug: (obj: LogFnFields, msg: string) => void
+  info: (obj: LogFnFields, msg: string) => void
+  warn: (obj: LogFnFields, msg: string) => void
+  error: (obj: LogFnFields, msg: string) => void
+  fatal: (obj: LogFnFields, msg: string) => void
+  child: (bindings: Record<string, unknown>) => SimpleLogger
+}
+
+function createConsoleLogger(module: string, level: LogLevel = 'info'): SimpleLogger {
+  const levels: LogLevel[] = ['trace', 'debug', 'info', 'warn', 'error', 'fatal']
+  const minLevel = levels.indexOf(level)
+
+  const log = (lvl: LogLevel, obj: LogFnFields, msg: string) => {
+    if (levels.indexOf(lvl) >= minLevel) {
+      const timestamp = new Date().toISOString()
+      const prefix = `[${timestamp}] ${lvl.toUpperCase()}: [${module}]`
+      const formatted = `${prefix} ${msg} ${JSON.stringify(obj)}`
+
+      switch (lvl) {
+        case 'error':
+        case 'fatal':
+          console.error(formatted)
+          break
+        case 'warn':
+          console.warn(formatted)
+          break
+        default:
+          if (process.env.NODE_ENV !== 'production') {
+            console.log(formatted)
+          }
+      }
+    }
+  }
+
+  return {
+    trace: (obj, msg) => log('trace', obj, msg),
+    debug: (obj, msg) => log('debug', obj, msg),
+    info: (obj, msg) => log('info', obj, msg),
+    warn: (obj, msg) => log('warn', obj, msg),
+    error: (obj, msg) => log('error', obj, msg),
+    fatal: (obj, msg) => log('fatal', obj, msg),
+    child: () => createConsoleLogger(module, level),
+  }
+}
+
+function createNodeLogger(module: string, level?: LogLevel): Logger {
+  const config = getAppConfig()
+  const logLevel = level || (config.nodeEnv === 'production' ? 'info' : 'debug')
+  const isDev = config.nodeEnv === 'development'
+  const isTest = config.nodeEnv === 'test'
+
+  if (isTest) {
+    const options: LoggerOptions = {
+      level: logLevel,
+      timestamp: pino.stdTimeFunctions.isoTime,
+      formatters: {
+        level: (label: string) => ({ level: label }),
+        bindings: () => ({}),
+      },
+    }
+    return pino(options).child({ module })
+  }
+
+  const logDir = resolve(process.cwd(), 'logs')
+  if (!existsSync(logDir)) {
+    mkdirSync(logDir, { recursive: true })
+  }
+  const logPath = resolve(logDir, `${module}.log`)
+
+  const streamEntries: pino.StreamEntry[] = []
+
+  if (isDev) {
+    streamEntries.push({
+      level: logLevel,
+      stream: pino.transport({
+        target: 'pino-pretty',
+        options: {
+          colorize: true,
+          translateTime: 'SYS:standard',
+          ignore: 'pid,hostname',
+          messageFormat: `[${module}] {msg}`,
+        },
+      }),
+    })
+  }
+
+  streamEntries.push({
+    level: logLevel,
+    stream: pino.transport({
+      target: 'pino/file',
+      options: { destination: logPath },
+    }),
+  })
+
+  return pino({ level: logLevel }, pino.multistream(streamEntries)).child({ module })
+}
+
+export function createModuleLoggerSync(module: string, level?: LogLevel): Logger | SimpleLogger {
+  if (isCloudflare) {
+    return createConsoleLogger(module, level || 'info')
+  }
+
+  if (_loggers.has(module)) {
+    return _loggers.get(module)!
+  }
+
+  const logger = createNodeLogger(module, level)
+  _loggers.set(module, logger)
+  return logger
+}
+
+export const logger = {
+  app: () => createModuleLoggerSync('app'),
+  db: () => createModuleLoggerSync('db'),
+  api: () => createModuleLoggerSync('api'),
+  ws: () => createModuleLoggerSync('ws'),
+  bootstrap: () => createModuleLoggerSync('bootstrap'),
+  module: (name: string) => createModuleLoggerSync(name),
+}
+
+export type { Logger }

package/template/src/server/utils/permission-utils.ts

@@ -0,0 +1,6 @@
+import { Permission } from '@shared/modules/permission'
+
+export function validatePermissions(permissions: Permission[]): boolean {
+  const allPermissions = Object.values(Permission)
+  return permissions.every(p => allPermissions.includes(p))
+}

package/template/src/server/utils/response.ts

@@ -0,0 +1,40 @@
+/**
+ * 统一 API 响应辅助函数
+ *
+ * 设计原则：
+ * 1. 错误统一走 AppError + 全局处理器
+ * 2. 成功响应由路由层用辅助函数包装，确保格式一致
+ * 3. 业务层只返回业务数据，不包装响应
+ */
+
+export function success<T>(data: T) {
+  return {
+    success: true as const,
+    data,
+    timestamp: new Date().toISOString(),
+  }
+}
+
+export function created<T>(data: T) {
+  return {
+    success: true as const,
+    data,
+    timestamp: new Date().toISOString(),
+  }
+}
+
+export function list<T>(items: T[], count?: number) {
+  return {
+    success: true as const,
+    data: count !== undefined ? { items, count } : { items },
+    timestamp: new Date().toISOString(),
+  }
+}
+
+export function deleted(id: string) {
+  return {
+    success: true as const,
+    data: { id },
+    timestamp: new Date().toISOString(),
+  }
+}

package/template/src/server/utils/route-helpers.ts

@@ -0,0 +1,200 @@
+/**
+ * 路由响应配置 - 简化版
+ *
+ * 设计理念：
+ * 1. 路由只定义业务成功响应
+ * 2. 框架级错误（401, 403, 500）由全局处理器自动添加
+ * 3. 业务错误（404, 409, 422）在路由中声明需要哪些
+ */
+
+import { z } from '@hono/zod-openapi'
+import { ApiSuccessSchema, ApiErrorSchema } from '@shared/schemas'
+
+// ==================== 基础响应 ====================
+
+export function successResponse<T extends z.ZodTypeAny>(schema: T, description: string) {
+  return {
+    content: {
+      'application/json': { schema: ApiSuccessSchema(schema) },
+    },
+    description,
+  }
+}
+
+export function errorResponse(description: string) {
+  return {
+    content: {
+      'application/json': { schema: ApiErrorSchema },
+    },
+    description,
+  }
+}
+
+// ==================== 业务错误响应（按需使用） ====================
+
+export const NotFoundResponse = errorResponse('Resource not found')
+export const ConflictResponse = errorResponse('Resource conflict')
+export const BusinessErrorResponse = errorResponse('Business rule violation')
+export const ValidationResponse = errorResponse('Invalid input')
+
+// ==================== 简化的路由响应构建器 ====================
+
+/**
+ * 路由响应选项
+ */
+export interface RouteResponseOptions {
+  /** 资源不存在 (404) - 用于 get/update/delete */
+  notFound?: boolean | string
+  /** 资源冲突 (409) - 用于 create/update 有唯一约束时 */
+  conflict?: boolean | string
+  /** 业务逻辑错误 (422) - 用于复杂业务规则 */
+  businessError?: boolean | string
+  /** 验证错误 (400) - 用于自定义验证消息 */
+  validation?: boolean | string
+}
+
+/**
+ * 定义路由响应 - 只关注业务
+ *
+ * @example
+ * // 简单的获取路由
+ * responses: defineResponses(DisputeSchema, 'Get dispute', {
+ *   notFound: true,  // 可能返回 404
+ * })
+ *
+ * // 创建路由
+ * responses: defineResponses(DisputeSchema, 'Create dispute', {
+ *   conflict: 'Dispute already exists',  // 可能返回 409
+ * })
+ *
+ * // 复杂业务路由
+ * responses: defineResponses(DisputeSchema, 'Resolve dispute', {
+ *   notFound: true,
+ *   businessError: 'Cannot resolve in current state',
+ * })
+ */
+export function defineResponses<T extends z.ZodTypeAny>(
+  schema: T,
+  description: string,
+  options: RouteResponseOptions = {}
+): Record<number, ReturnType<typeof successResponse> | ReturnType<typeof errorResponse>> {
+  const responses: Record<
+    number,
+    ReturnType<typeof successResponse> | ReturnType<typeof errorResponse>
+  > = {
+    200: successResponse(schema, description),
+  }
+
+  // 业务错误 - 按需添加
+  if (options.notFound) {
+    responses[404] = errorResponse(
+      typeof options.notFound === 'string' ? options.notFound : 'Resource not found'
+    )
+  }
+
+  if (options.conflict) {
+    responses[409] = errorResponse(
+      typeof options.conflict === 'string' ? options.conflict : 'Resource conflict'
+    )
+  }
+
+  if (options.businessError) {
+    responses[422] = errorResponse(
+      typeof options.businessError === 'string' ? options.businessError : 'Business rule violation'
+    )
+  }
+
+  if (options.validation) {
+    responses[400] = errorResponse(
+      typeof options.validation === 'string' ? options.validation : 'Invalid input'
+    )
+  }
+
+  return responses
+}
+
+/**
+ * 定义创建路由响应 - 自动添加 201
+ */
+export function defineCreateResponses<T extends z.ZodTypeAny>(
+  schema: T,
+  description: string,
+  options: RouteResponseOptions = {}
+): Record<number, ReturnType<typeof successResponse> | ReturnType<typeof errorResponse>> {
+  const responses: Record<
+    number,
+    ReturnType<typeof successResponse> | ReturnType<typeof errorResponse>
+  > = {
+    201: successResponse(schema, description),
+  }
+
+  if (options.conflict) {
+    responses[409] = errorResponse(
+      typeof options.conflict === 'string' ? options.conflict : 'Resource conflict'
+    )
+  }
+
+  if (options.businessError) {
+    responses[422] = errorResponse(
+      typeof options.businessError === 'string' ? options.businessError : 'Business rule violation'
+    )
+  }
+
+  return responses
+}
+
+/**
+ * 定义删除路由响应
+ */
+export function defineDeleteResponses(
+  options: { notFound?: boolean | string } = {}
+): Record<number, ReturnType<typeof successResponse> | ReturnType<typeof errorResponse>> {
+  const responses: Record<
+    number,
+    ReturnType<typeof successResponse> | ReturnType<typeof errorResponse>
+  > = {
+    200: successResponse(z.object({ id: z.string() }), 'Deleted successfully'),
+  }
+
+  if (options.notFound) {
+    responses[404] = errorResponse(
+      typeof options.notFound === 'string' ? options.notFound : 'Resource not found'
+    )
+  }
+
+  return responses
+}
+
+// ==================== 列表响应 ====================
+
+export function listResponse<T extends z.ZodTypeAny>(itemSchema: T, description: string) {
+  return successResponse(
+    z.object({
+      items: z.array(itemSchema),
+      nextCursor: z.string().optional(),
+    }),
+    description
+  )
+}
+
+// ==================== 请求配置快捷函数 ====================
+
+export const idParam = z.object({ id: z.string() })
+
+export const idRequest = { params: idParam }
+
+export function bodyRequest<T extends z.ZodTypeAny>(schema: T) {
+  return {
+    body: {
+      content: { 'application/json': { schema } },
+    },
+  }
+}
+
+export function queryRequest<T extends z.ZodObject<Record<string, z.ZodTypeAny>>>(schema: T) {
+  return { query: schema }
+}
+
+// ==================== 统一响应辅助函数 ====================
+
+export { success, created, list, deleted } from './response'

package/template/src/server/utils/uuid.ts

@@ -0,0 +1,8 @@
+import { randomUUID } from 'crypto';
+
+export function generateUUID(): string {
+  if (typeof globalThis !== 'undefined' && globalThis.crypto?.randomUUID) {
+    return globalThis.crypto.randomUUID();
+  }
+  return randomUUID();
+}

package/template/src/server/utils/ws-helper.ts

@@ -0,0 +1,30 @@
+import { upgradeWebSocket } from 'hono/cloudflare-workers';
+import { isCloudflare } from './env';
+
+export { isCloudflare };
+
+export function createCloudflareWSHandler(
+  onMessage: (data: string, send: (msg: string) => void, close: () => void) => void,
+  _onOpen?: () => void,
+  onClose?: () => void
+) {
+  return upgradeWebSocket(() => ({
+    onMessage(event: MessageEvent) {
+      const ws = event.target as WebSocket;
+      onMessage(
+        event.data as string,
+        (msg) => ws.send(msg),
+        () => ws.close()
+      );
+    },
+    onClose() {
+      onClose?.();
+    },
+    onOpen(_event: Event, ws: WebSocket) {
+      ws.send(JSON.stringify({
+        type: 'connected',
+        payload: { timestamp: Date.now() },
+      }));
+    },
+  }));
+}

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

@@ -0,0 +1 @@
+export * from './resource-types'

package/template/src/shared/constants/resource-types.ts

@@ -0,0 +1,72 @@
+export const RESOURCE_TYPES = {
+  USER: 'user',
+  ROLE: 'role',
+  PERMISSION: 'permission',
+  CONTENT: 'content',
+  ROUTE: 'route',
+  ORDER: 'order',
+  TICKET: 'ticket',
+  DISPUTE: 'dispute',
+  FILE: 'file',
+  CHAT: 'chat',
+  NOTIFICATION: 'notification',
+  CAPTCHA: 'captcha',
+} as const
+
+export type ResourceType = (typeof RESOURCE_TYPES)[keyof typeof RESOURCE_TYPES]
+
+export const PATH_TO_RESOURCE_TYPE: Record<string, ResourceType> = {
+  users: RESOURCE_TYPES.USER,
+  roles: RESOURCE_TYPES.ROLE,
+  permissions: RESOURCE_TYPES.PERMISSION,
+  contents: RESOURCE_TYPES.CONTENT,
+  routes: RESOURCE_TYPES.ROUTE,
+  orders: RESOURCE_TYPES.ORDER,
+  tickets: RESOURCE_TYPES.TICKET,
+  disputes: RESOURCE_TYPES.DISPUTE,
+  files: RESOURCE_TYPES.FILE,
+  chats: RESOURCE_TYPES.CHAT,
+  notifications: RESOURCE_TYPES.NOTIFICATION,
+  captchas: RESOURCE_TYPES.CAPTCHA,
+}
+
+export const RESOURCE_LABELS: Record<ResourceType, string> = {
+  [RESOURCE_TYPES.USER]: '用户',
+  [RESOURCE_TYPES.ROLE]: '角色',
+  [RESOURCE_TYPES.PERMISSION]: '权限',
+  [RESOURCE_TYPES.CONTENT]: '内容',
+  [RESOURCE_TYPES.ROUTE]: '路由',
+  [RESOURCE_TYPES.ORDER]: '订单',
+  [RESOURCE_TYPES.TICKET]: '工单',
+  [RESOURCE_TYPES.DISPUTE]: '争议',
+  [RESOURCE_TYPES.FILE]: '文件',
+  [RESOURCE_TYPES.CHAT]: '聊天',
+  [RESOURCE_TYPES.NOTIFICATION]: '通知',
+  [RESOURCE_TYPES.CAPTCHA]: '验证码',
+}
+
+export const ACTION_TYPES = {
+  CREATE: 'create',
+  UPDATE: 'update',
+  DELETE: 'delete',
+  ASSIGN: 'assign',
+  REVOKE: 'revoke',
+} as const
+
+export type ActionType = (typeof ACTION_TYPES)[keyof typeof ACTION_TYPES]
+
+export const ACTION_LABELS: Record<ActionType, string> = {
+  [ACTION_TYPES.CREATE]: '创建',
+  [ACTION_TYPES.UPDATE]: '更新',
+  [ACTION_TYPES.DELETE]: '删除',
+  [ACTION_TYPES.ASSIGN]: '分配',
+  [ACTION_TYPES.REVOKE]: '撤销',
+}
+
+export const ACTION_COLORS: Record<ActionType, string> = {
+  [ACTION_TYPES.CREATE]: 'green',
+  [ACTION_TYPES.UPDATE]: 'blue',
+  [ACTION_TYPES.DELETE]: 'red',
+  [ACTION_TYPES.ASSIGN]: 'cyan',
+  [ACTION_TYPES.REVOKE]: 'orange',
+}