create-fullstack-scaffold 0.1.0

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

@@ -0,0 +1,264 @@
+// @vitest-environment node
+import { describe, it, expect } from 'vitest'
+import { z } from '@hono/zod-openapi'
+import {
+  successResponse,
+  errorResponse,
+  NotFoundResponse,
+  ConflictResponse,
+  BusinessErrorResponse,
+  ValidationResponse,
+  defineResponses,
+  defineCreateResponses,
+  defineDeleteResponses,
+  listResponse,
+  idParam,
+  idRequest,
+  bodyRequest,
+  queryRequest,
+} from '../route-helpers'
+import { success, created, list, deleted } from '../response'
+
+describe('successResponse', () => {
+  it('should create response with schema and description', () => {
+    const schema = z.object({ name: z.string() })
+    const result = successResponse(schema, 'test desc')
+    expect(result.description).toBe('test desc')
+    expect(result.content).toHaveProperty('application/json')
+    expect(result.content['application/json']).toHaveProperty('schema')
+  })
+})
+
+describe('errorResponse', () => {
+  it('should create error response with description', () => {
+    const result = errorResponse('some error')
+    expect(result.description).toBe('some error')
+    expect(result.content).toHaveProperty('application/json')
+    expect(result.content['application/json']).toHaveProperty('schema')
+  })
+})
+
+describe('predefined error responses', () => {
+  it('NotFoundResponse has correct description', () => {
+    expect(NotFoundResponse.description).toBe('Resource not found')
+  })
+
+  it('ConflictResponse has correct description', () => {
+    expect(ConflictResponse.description).toBe('Resource conflict')
+  })
+
+  it('BusinessErrorResponse has correct description', () => {
+    expect(BusinessErrorResponse.description).toBe('Business rule violation')
+  })
+
+  it('ValidationResponse has correct description', () => {
+    expect(ValidationResponse.description).toBe('Invalid input')
+  })
+})
+
+describe('defineResponses', () => {
+  const schema = z.object({ id: z.number() })
+
+  it('should return 200 success response by default', () => {
+    const result = defineResponses(schema, 'Get resource')
+    expect(result[200]).toBeDefined()
+    expect(result[200].description).toBe('Get resource')
+  })
+
+  it('should add 404 when notFound is true', () => {
+    const result = defineResponses(schema, 'Get', { notFound: true })
+    expect(result[404]).toBeDefined()
+    expect(result[404].description).toBe('Resource not found')
+  })
+
+  it('should add 404 with custom message when notFound is string', () => {
+    const result = defineResponses(schema, 'Get', { notFound: 'Item missing' })
+    expect(result[404].description).toBe('Item missing')
+  })
+
+  it('should add 409 when conflict is true', () => {
+    const result = defineResponses(schema, 'Create', { conflict: true })
+    expect(result[409]).toBeDefined()
+    expect(result[409].description).toBe('Resource conflict')
+  })
+
+  it('should add 409 with custom message when conflict is string', () => {
+    const result = defineResponses(schema, 'Create', { conflict: 'Already taken' })
+    expect(result[409].description).toBe('Already taken')
+  })
+
+  it('should add 422 when businessError is true', () => {
+    const result = defineResponses(schema, 'Update', { businessError: true })
+    expect(result[422]).toBeDefined()
+    expect(result[422].description).toBe('Business rule violation')
+  })
+
+  it('should add 422 with custom message when businessError is string', () => {
+    const result = defineResponses(schema, 'Update', { businessError: 'Bad state' })
+    expect(result[422].description).toBe('Bad state')
+  })
+
+  it('should add 400 when validation is true', () => {
+    const result = defineResponses(schema, 'Create', { validation: true })
+    expect(result[400]).toBeDefined()
+    expect(result[400].description).toBe('Invalid input')
+  })
+
+  it('should add 400 with custom message when validation is string', () => {
+    const result = defineResponses(schema, 'Create', { validation: 'Bad format' })
+    expect(result[400].description).toBe('Bad format')
+  })
+
+  it('should combine multiple options', () => {
+    const result = defineResponses(schema, 'Complex', {
+      notFound: true,
+      conflict: 'dup',
+      businessError: true,
+      validation: 'bad',
+    })
+    expect(Object.keys(result)).toEqual(expect.arrayContaining(['200', '404', '409', '422', '400']))
+  })
+
+  it('should only have 200 when no options', () => {
+    const result = defineResponses(schema, 'Simple')
+    expect(Object.keys(result)).toEqual(['200'])
+  })
+})
+
+describe('defineCreateResponses', () => {
+  const schema = z.object({ id: z.number() })
+
+  it('should return 201 success response by default', () => {
+    const result = defineCreateResponses(schema, 'Created')
+    expect(result[201]).toBeDefined()
+    expect(result[201].description).toBe('Created')
+  })
+
+  it('should add 409 when conflict is true', () => {
+    const result = defineCreateResponses(schema, 'Create', { conflict: true })
+    expect(result[409]).toBeDefined()
+  })
+
+  it('should add 409 with custom message', () => {
+    const result = defineCreateResponses(schema, 'Create', { conflict: 'Exists' })
+    expect(result[409].description).toBe('Exists')
+  })
+
+  it('should add 422 when businessError is true', () => {
+    const result = defineCreateResponses(schema, 'Create', { businessError: true })
+    expect(result[422]).toBeDefined()
+  })
+
+  it('should add 422 with custom message', () => {
+    const result = defineCreateResponses(schema, 'Create', { businessError: 'Rule break' })
+    expect(result[422].description).toBe('Rule break')
+  })
+
+  it('should only have 201 when no options', () => {
+    const result = defineCreateResponses(schema, 'Create')
+    expect(Object.keys(result)).toEqual(['201'])
+  })
+})
+
+describe('defineDeleteResponses', () => {
+  it('should return 200 by default', () => {
+    const result = defineDeleteResponses()
+    expect(result[200]).toBeDefined()
+    expect(result[200].description).toBe('Deleted successfully')
+  })
+
+  it('should add 404 when notFound is true', () => {
+    const result = defineDeleteResponses({ notFound: true })
+    expect(result[404]).toBeDefined()
+  })
+
+  it('should add 404 with custom message', () => {
+    const result = defineDeleteResponses({ notFound: 'Already gone' })
+    expect(result[404].description).toBe('Already gone')
+  })
+})
+
+describe('listResponse', () => {
+  it('should create list response with items array and optional cursor', () => {
+    const itemSchema = z.object({ name: z.string() })
+    const result = listResponse(itemSchema, 'List items')
+    expect(result.description).toBe('List items')
+    expect(result.content['application/json']).toHaveProperty('schema')
+  })
+})
+
+describe('idParam', () => {
+  it('should be a zod object with id string', () => {
+    const result = idParam.safeParse({ id: '123' })
+    expect(result.success).toBe(true)
+  })
+
+  it('should reject non-string id', () => {
+    const result = idParam.safeParse({ id: 123 })
+    expect(result.success).toBe(false)
+  })
+})
+
+describe('idRequest', () => {
+  it('should have params with idParam', () => {
+    expect(idRequest).toHaveProperty('params')
+    expect(idRequest.params).toBe(idParam)
+  })
+})
+
+describe('bodyRequest', () => {
+  it('should create request config with json body schema', () => {
+    const schema = z.object({ name: z.string() })
+    const result = bodyRequest(schema)
+    expect(result).toHaveProperty('body')
+    expect(result.body).toHaveProperty('content')
+    expect(result.body.content).toHaveProperty('application/json')
+  })
+})
+
+describe('queryRequest', () => {
+  it('should create request config with query schema', () => {
+    const schema = z.object({ page: z.string().optional() })
+    const result = queryRequest(schema)
+    expect(result).toHaveProperty('query')
+    expect(result.query).toBe(schema)
+  })
+})
+
+describe('response helpers', () => {
+  it('success should wrap data', () => {
+    const result = success({ id: 1 })
+    expect(result.success).toBe(true)
+    expect(result.data).toEqual({ id: 1 })
+    expect(result.timestamp).toBeTruthy()
+  })
+
+  it('created should wrap data', () => {
+    const result = created({ id: 1 })
+    expect(result.success).toBe(true)
+    expect(result.data).toEqual({ id: 1 })
+    expect(result.timestamp).toBeTruthy()
+  })
+
+  it('list with items only', () => {
+    const result = list([1, 2, 3])
+    expect(result.success).toBe(true)
+    expect(result.data).toEqual({ items: [1, 2, 3] })
+  })
+
+  it('list with count', () => {
+    const result = list([1, 2], 5)
+    expect(result.data).toEqual({ items: [1, 2], count: 5 })
+  })
+
+  it('list with count = 0', () => {
+    const result = list([], 0)
+    expect(result.data).toEqual({ items: [], count: 0 })
+  })
+
+  it('deleted should wrap id', () => {
+    const result = deleted('abc')
+    expect(result.success).toBe(true)
+    expect(result.data).toEqual({ id: 'abc' })
+  })
+})

package/template/src/server/utils/app-error.ts

@@ -0,0 +1,355 @@
+/**
+ * 统一应用错误类型系统
+ *
+ * 错误分类：
+ * - ValidationError: 输入验证错误 (400)
+ * - AuthenticationError: 认证错误 (401)
+ * - AuthorizationError: 权限错误 (403)
+ * - NotFoundError: 资源不存在 (404)
+ * - ConflictError: 资源冲突 (409)
+ * - BusinessError: 业务逻辑错误 (422)
+ * - RateLimitError: 限流错误 (429)
+ * - SystemError: 系统内部错误 (500)
+ */
+
+export enum ErrorCode {
+  // 验证错误 (400)
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  INVALID_INPUT = 'INVALID_INPUT',
+  INVALID_FORMAT = 'INVALID_FORMAT',
+  MISSING_FIELD = 'MISSING_FIELD',
+
+  // 认证错误 (401)
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  TOKEN_EXPIRED = 'TOKEN_EXPIRED',
+  TOKEN_INVALID = 'TOKEN_INVALID',
+  TOKEN_MISSING = 'TOKEN_MISSING',
+
+  // 权限错误 (403)
+  FORBIDDEN = 'FORBIDDEN',
+  PERMISSION_DENIED = 'PERMISSION_DENIED',
+  INSUFFICIENT_ROLE = 'INSUFFICIENT_ROLE',
+
+  // 资源不存在 (404)
+  NOT_FOUND = 'NOT_FOUND',
+  RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
+  USER_NOT_FOUND = 'USER_NOT_FOUND',
+  ORDER_NOT_FOUND = 'ORDER_NOT_FOUND',
+  DISPUTE_NOT_FOUND = 'DISPUTE_NOT_FOUND',
+
+  // 资源冲突 (409)
+  CONFLICT = 'CONFLICT',
+  DUPLICATE_ENTRY = 'DUPLICATE_ENTRY',
+  ALREADY_EXISTS = 'ALREADY_EXISTS',
+
+  // 业务逻辑错误 (422)
+  BUSINESS_ERROR = 'BUSINESS_ERROR',
+  INVALID_STATE = 'INVALID_STATE',
+  OPERATION_NOT_ALLOWED = 'OPERATION_NOT_ALLOWED',
+  INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE',
+  INVALID_STATUS_TRANSITION = 'INVALID_STATUS_TRANSITION',
+
+  // 限流错误 (429)
+  RATE_LIMIT = 'RATE_LIMIT',
+  TOO_MANY_REQUESTS = 'TOO_MANY_REQUESTS',
+
+  // 系统错误 (500)
+  SYSTEM_ERROR = 'SYSTEM_ERROR',
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  DATABASE_ERROR = 'DATABASE_ERROR',
+  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
+}
+
+export interface ErrorDetail {
+  field?: string
+  message: string
+  code?: string
+}
+
+export interface AppErrorOptions {
+  code: ErrorCode
+  message: string
+  statusCode: number
+  details?: ErrorDetail[]
+  cause?: Error
+  logLevel?: 'debug' | 'info' | 'warn' | 'error'
+}
+
+export class AppError extends Error {
+  readonly code: ErrorCode
+  readonly statusCode: number
+  readonly details?: ErrorDetail[]
+  readonly cause?: Error
+  readonly logLevel: 'debug' | 'info' | 'warn' | 'error'
+  readonly timestamp: string
+
+  constructor(options: AppErrorOptions) {
+    super(options.message)
+    this.name = 'AppError'
+    this.code = options.code
+    this.statusCode = options.statusCode
+    this.details = options.details
+    this.cause = options.cause
+    this.logLevel = options.logLevel ?? 'warn'
+    this.timestamp = new Date().toISOString()
+
+    // 保持堆栈跟踪
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor)
+    }
+  }
+
+  toJSON() {
+    return {
+      success: false as const,
+      error: this.message,
+      code: this.code,
+      status: this.statusCode,
+      details: this.details,
+      timestamp: this.timestamp,
+    }
+  }
+
+  static isAppError(error: unknown): error is AppError {
+    return error instanceof AppError
+  }
+}
+
+// ==================== 具体错误类 ====================
+
+/**
+ * 验证错误 (400)
+ */
+export class ValidationError extends AppError {
+  constructor(message: string, details?: ErrorDetail[]) {
+    super({
+      code: ErrorCode.VALIDATION_ERROR,
+      message,
+      statusCode: 400,
+      details,
+      logLevel: 'info',
+    })
+    this.name = 'ValidationError'
+  }
+}
+
+/**
+ * 认证错误 (401)
+ */
+export class AuthenticationError extends AppError {
+  constructor(message = 'Unauthorized', code: ErrorCode = ErrorCode.UNAUTHORIZED) {
+    super({
+      code,
+      message,
+      statusCode: 401,
+      logLevel: 'warn',
+    })
+    this.name = 'AuthenticationError'
+  }
+
+  static tokenExpired(): AuthenticationError {
+    return new AuthenticationError('Token has expired', ErrorCode.TOKEN_EXPIRED)
+  }
+
+  static tokenInvalid(): AuthenticationError {
+    return new AuthenticationError('Invalid token', ErrorCode.TOKEN_INVALID)
+  }
+
+  static tokenMissing(): AuthenticationError {
+    return new AuthenticationError('Authentication token is required', ErrorCode.TOKEN_MISSING)
+  }
+}
+
+/**
+ * 权限错误 (403)
+ */
+export class AuthorizationError extends AppError {
+  constructor(message = 'Forbidden', details?: ErrorDetail[]) {
+    super({
+      code: ErrorCode.FORBIDDEN,
+      message,
+      statusCode: 403,
+      details,
+      logLevel: 'warn',
+    })
+    this.name = 'AuthorizationError'
+  }
+
+  static permissionDenied(permission?: string): AuthorizationError {
+    return new AuthorizationError(
+      permission ? `Permission denied: ${permission}` : 'Permission denied',
+      permission ? [{ message: `Missing required permission: ${permission}` }] : undefined
+    )
+  }
+
+  static insufficientRole(currentRole?: string, requiredRole?: string): AuthorizationError {
+    return new AuthorizationError(
+      'Insufficient role privileges',
+      currentRole && requiredRole
+        ? [
+            {
+              message: `Role '${currentRole}' does not meet required role '${requiredRole}'`,
+            },
+          ]
+        : undefined
+    )
+  }
+}
+
+/**
+ * 资源不存在错误 (404)
+ */
+export class NotFoundError extends AppError {
+  constructor(resource: string, identifier?: string) {
+    super({
+      code: ErrorCode.NOT_FOUND,
+      message: identifier ? `${resource} not found: ${identifier}` : `${resource} not found`,
+      statusCode: 404,
+      logLevel: 'info',
+    })
+    this.name = 'NotFoundError'
+  }
+
+  static user(id?: string): NotFoundError {
+    return new NotFoundError('User', id)
+  }
+
+  static order(id?: string): NotFoundError {
+    return new NotFoundError('Order', id)
+  }
+
+  static dispute(id?: string): NotFoundError {
+    return new NotFoundError('Dispute', id)
+  }
+
+  static ticket(id?: string): NotFoundError {
+    return new NotFoundError('Ticket', id)
+  }
+}
+
+/**
+ * 资源冲突错误 (409)
+ */
+export class ConflictError extends AppError {
+  constructor(message: string, details?: ErrorDetail[]) {
+    super({
+      code: ErrorCode.CONFLICT,
+      message,
+      statusCode: 409,
+      details,
+      logLevel: 'info',
+    })
+    this.name = 'ConflictError'
+  }
+
+  static duplicateEntry(field: string, value: string): ConflictError {
+    return new ConflictError(`Duplicate entry for ${field}`, [
+      { field, message: `Value '${value}' already exists` },
+    ])
+  }
+}
+
+/**
+ * 业务逻辑错误 (422)
+ */
+export class BusinessError extends AppError {
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCode.BUSINESS_ERROR,
+    details?: ErrorDetail[]
+  ) {
+    super({
+      code,
+      message,
+      statusCode: 422,
+      details,
+      logLevel: 'info',
+    })
+    this.name = 'BusinessError'
+  }
+
+  static invalidState(currentState: string, expectedStates: string[]): BusinessError {
+    return new BusinessError(`Invalid state transition`, ErrorCode.INVALID_STATE, [
+      {
+        message: `Current state '${currentState}' is not valid. Expected one of: ${expectedStates.join(', ')}`,
+      },
+    ])
+  }
+
+  static operationNotAllowed(reason: string): BusinessError {
+    return new BusinessError(`Operation not allowed: ${reason}`, ErrorCode.OPERATION_NOT_ALLOWED)
+  }
+}
+
+/**
+ * 限流错误 (429)
+ */
+export class RateLimitError extends AppError {
+  constructor(
+    message = 'Too many requests',
+    public readonly retryAfter?: number
+  ) {
+    super({
+      code: ErrorCode.RATE_LIMIT,
+      message,
+      statusCode: 429,
+      logLevel: 'warn',
+    })
+    this.name = 'RateLimitError'
+  }
+}
+
+/**
+ * 系统错误 (500)
+ */
+export class SystemError extends AppError {
+  constructor(message = 'Internal server error', cause?: Error) {
+    super({
+      code: ErrorCode.SYSTEM_ERROR,
+      message,
+      statusCode: 500,
+      cause,
+      logLevel: 'error',
+    })
+    this.name = 'SystemError'
+  }
+
+  static databaseError(cause?: Error): SystemError {
+    return new SystemError('Database operation failed', cause)
+  }
+
+  static serviceUnavailable(service: string): SystemError {
+    return new SystemError(`Service '${service}' is unavailable`)
+  }
+}
+
+// ==================== 错误转换工具 ====================
+
+/**
+ * 将未知错误转换为 AppError
+ */
+export function toAppError(error: unknown): AppError {
+  if (AppError.isAppError(error)) {
+    return error
+  }
+
+  if (error instanceof Error) {
+    return new SystemError(error.message, error)
+  }
+
+  return new SystemError(String(error))
+}
+
+/**
+ * 安全地执行异步操作，将错误转换为 AppError
+ */
+export async function tryCatch<T>(
+  fn: () => Promise<T>,
+  errorMapper?: (error: unknown) => AppError
+): Promise<T> {
+  try {
+    return await fn()
+  } catch (error) {
+    throw errorMapper ? errorMapper(error) : toAppError(error)
+  }
+}

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

@@ -0,0 +1,65 @@
+import type { Context } from 'hono'
+import type { AuthUser } from '../middleware/auth'
+import type { User } from '@shared/modules/admin'
+import { Role } from '@shared/modules/permission'
+
+const mockUsers: User[] = [
+  {
+    id: '1',
+    username: 'superadmin',
+    email: 'superadmin@example.com',
+    role: Role.SUPER_ADMIN,
+    status: 'active',
+    avatar: 'https://api.dicebear.com/7.x/avataaars/svg?seed=superadmin',
+    createdAt: '2024-01-01T00:00:00Z',
+    updatedAt: '2024-01-01T00:00:00Z',
+  },
+  {
+    id: '2',
+    username: 'customerservice',
+    email: 'customerservice@example.com',
+    role: Role.CUSTOMER_SERVICE,
+    status: 'active',
+    avatar: 'https://api.dicebear.com/7.x/avataaars/svg?seed=customerservice',
+    createdAt: '2024-01-02T00:00:00Z',
+    updatedAt: '2024-01-02T00:00:00Z',
+  },
+  {
+    id: '3',
+    username: 'user1',
+    email: 'user1@example.com',
+    role: Role.USER,
+    status: 'active',
+    avatar: 'https://api.dicebear.com/7.x/avataaars/svg?seed=user1',
+    createdAt: '2024-01-03T00:00:00Z',
+    updatedAt: '2024-01-03T00:00:00Z',
+  },
+]
+
+const mockTokens: Map<string, string> = new Map([
+  ['super-admin-token', '1'],
+  ['customer-service-token', '2'],
+  ['user-token', '3'],
+])
+
+export function getAuthUser(c: Context): AuthUser {
+  return c.get('authUser')
+}
+
+export function verifyToken(token: string): User | null {
+  const userId = mockTokens.get(token)
+
+  if (!userId) {
+    return null
+  }
+
+  return mockUsers.find(u => u.id === userId) || null
+}
+
+export function getMockUsers(): User[] {
+  return mockUsers
+}
+
+export function getMockTokens(): Map<string, string> {
+  return mockTokens
+}