create-fullstack-scaffold 0.1.0

package/template/src/server/module-todos/routes/todos-routes.ts

@@ -0,0 +1,260 @@
+import { createRoute, z } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+import * as todoService from '../services/todo-service'
+import {
+  TodoSchema,
+  CreateTodoSchema,
+  UpdateTodoSchema,
+  TodoIdResponseSchema,
+  TodoAttachmentSchema,
+  TodoAttachmentListSchema,
+  TodoWithAttachmentsSchema,
+  UploadFileSchema,
+  AttachmentIdResponseSchema,
+} from '@shared/schemas'
+import { successResponse, errorResponse, success, created } from '@server/utils/route-helpers'
+import { getAuthUser } from '@server/utils/auth'
+import { NotFoundError, ValidationError } from '@server/utils/app-error'
+import { authMiddleware } from '@server/middleware/auth'
+
+const TodoListSchema = z.array(TodoSchema)
+
+const listRoute = createRoute({
+  method: 'get',
+  path: '/todos',
+  tags: ['todos'],
+  security: [{ Bearer: [] }],
+  middleware: [authMiddleware()],
+  responses: {
+    200: successResponse(TodoListSchema, 'List all todos'),
+    500: errorResponse('Internal server error'),
+  },
+})
+
+const getRoute = createRoute({
+  method: 'get',
+  path: '/todos/{id}',
+  tags: ['todos'],
+  security: [{ Bearer: [] }],
+  middleware: [authMiddleware()],
+  request: {
+    params: z.object({ id: z.coerce.number().int().positive() }),
+  },
+  responses: {
+    200: successResponse(TodoSchema, 'Get a todo by ID'),
+    404: errorResponse('Todo not found'),
+  },
+})
+
+const createRouteDef = createRoute({
+  method: 'post',
+  path: '/todos',
+  tags: ['todos'],
+  security: [{ Bearer: [] }],
+  middleware: [authMiddleware()],
+  request: {
+    body: {
+      content: { 'application/json': { schema: CreateTodoSchema } },
+    },
+  },
+  responses: {
+    201: successResponse(TodoSchema, 'Create a new todo'),
+    400: errorResponse('Invalid input'),
+  },
+})
+
+const updateRoute = createRoute({
+  method: 'put',
+  path: '/todos/{id}',
+  tags: ['todos'],
+  security: [{ Bearer: [] }],
+  middleware: [authMiddleware()],
+  request: {
+    params: z.object({ id: z.coerce.number().int().positive() }),
+    body: {
+      content: { 'application/json': { schema: UpdateTodoSchema } },
+    },
+  },
+  responses: {
+    200: successResponse(TodoSchema, 'Update a todo'),
+    404: errorResponse('Todo not found'),
+  },
+})
+
+const deleteRoute = createRoute({
+  method: 'delete',
+  path: '/todos/{id}',
+  tags: ['todos'],
+  security: [{ Bearer: [] }],
+  middleware: [authMiddleware()],
+  request: {
+    params: z.object({ id: z.coerce.number().int().positive() }),
+  },
+  responses: {
+    200: successResponse(TodoIdResponseSchema, 'Delete a todo'),
+    404: errorResponse('Todo not found'),
+  },
+})
+
+const uploadAttachmentRoute = createRoute({
+  method: 'post',
+  path: '/todos/{id}/attachments',
+  tags: ['todos'],
+  security: [{ Bearer: [] }],
+  middleware: [authMiddleware()],
+  request: {
+    params: z.object({ id: z.coerce.number().int().positive() }),
+    body: {
+      required: true,
+      content: {
+        'multipart/form-data': {
+          schema: UploadFileSchema,
+        },
+      },
+    },
+  },
+  responses: {
+    201: successResponse(TodoAttachmentSchema, 'File uploaded successfully'),
+    404: errorResponse('Todo not found'),
+    400: errorResponse('Invalid file or file too large'),
+  },
+})
+
+const listAttachmentsRoute = createRoute({
+  method: 'get',
+  path: '/todos/{id}/attachments',
+  tags: ['todos'],
+  security: [{ Bearer: [] }],
+  middleware: [authMiddleware()],
+  request: {
+    params: z.object({ id: z.coerce.number().int().positive() }),
+  },
+  responses: {
+    200: successResponse(TodoAttachmentListSchema, 'List attachments'),
+    404: errorResponse('Todo not found'),
+  },
+})
+
+const getTodoWithAttachmentsRoute = createRoute({
+  method: 'get',
+  path: '/todos/{id}/with-attachments',
+  tags: ['todos'],
+  security: [{ Bearer: [] }],
+  middleware: [authMiddleware()],
+  request: {
+    params: z.object({ id: z.coerce.number().int().positive() }),
+  },
+  responses: {
+    200: successResponse(TodoWithAttachmentsSchema, 'Get todo with attachments'),
+    404: errorResponse('Todo not found'),
+  },
+})
+
+const deleteAttachmentRoute = createRoute({
+  method: 'delete',
+  path: '/todos/{todoId}/attachments/{attachmentId}',
+  tags: ['todos'],
+  security: [{ Bearer: [] }],
+  middleware: [authMiddleware()],
+  request: {
+    params: z.object({
+      todoId: z.coerce.number().int().positive(),
+      attachmentId: z.coerce.number().int().positive(),
+    }),
+  },
+  responses: {
+    200: successResponse(AttachmentIdResponseSchema, 'Attachment deleted'),
+    404: errorResponse('Attachment not found'),
+  },
+})
+
+export const apiRoutes = new OpenAPIHono()
+  .openapi(listRoute, async c => {
+    const todos = await todoService.listTodos()
+    return c.json(success(todos), 200)
+  })
+  .openapi(getRoute, async c => {
+    const { id } = c.req.valid('param')
+    const todo = await todoService.getTodo(id)
+    if (!todo) throw new NotFoundError('Todo', String(id))
+    return c.json(success(todo), 200)
+  })
+  .openapi(createRouteDef, async c => {
+    const data = c.req.valid('json')
+    const todo = await todoService.createTodo(data)
+    return c.json(created(todo), 201)
+  })
+  .openapi(updateRoute, async c => {
+    const { id } = c.req.valid('param')
+    const data = c.req.valid('json')
+    const todo = await todoService.updateTodo(id, data)
+    if (!todo) throw new NotFoundError('Todo', String(id))
+    return c.json(success(todo), 200)
+  })
+  .openapi(deleteRoute, async c => {
+    const { id } = c.req.valid('param')
+    const result = await todoService.deleteTodo(id)
+    if (!result) throw new NotFoundError('Todo', String(id))
+    return c.json(success({ id }), 200)
+  })
+  .openapi(uploadAttachmentRoute, async c => {
+    const { id } = c.req.valid('param')
+
+    const todo = await todoService.getTodo(id)
+    if (!todo) throw new NotFoundError('Todo', String(id))
+
+    const body = c.req.valid('form')
+    const file = body['file']
+
+    if (!file || !(file instanceof File)) {
+      throw new ValidationError('No file uploaded')
+    }
+
+    const user = getAuthUser(c)
+    const arrayBuffer = await file.arrayBuffer()
+
+    try {
+      const attachment = await todoService.uploadAttachment(
+        id,
+        {
+          name: file.name,
+          type: file.type,
+          size: file.size,
+          data: arrayBuffer,
+        },
+        user?.id
+      )
+
+      return c.json(created(attachment), 201)
+    } catch (error) {
+      throw new ValidationError((error as Error).message)
+    }
+  })
+  .openapi(listAttachmentsRoute, async c => {
+    const { id } = c.req.valid('param')
+
+    const todo = await todoService.getTodo(id)
+    if (!todo) throw new NotFoundError('Todo', String(id))
+
+    const attachments = await todoService.listAttachments(id)
+    return c.json(success(attachments), 200)
+  })
+  .openapi(getTodoWithAttachmentsRoute, async c => {
+    const { id } = c.req.valid('param')
+    const todo = await todoService.getTodoWithAttachments(id)
+    if (!todo) throw new NotFoundError('Todo', String(id))
+    return c.json(success(todo), 200)
+  })
+  .openapi(deleteAttachmentRoute, async c => {
+    const { attachmentId } = c.req.valid('param')
+    const result = await todoService.deleteAttachment(attachmentId)
+    if (!result) throw new NotFoundError('Attachment', String(attachmentId))
+    return c.json(success({ id: attachmentId }), 200)
+  })
+  .doc('/docs', {
+    openapi: '3.0.0',
+    info: {
+      version: '1.0.0',
+      title: 'Todo API',
+    },
+  })

package/template/src/server/module-todos/services/todo-service.ts

@@ -0,0 +1,202 @@
+import { eq, desc } from 'drizzle-orm'
+import type {
+  Todo,
+  CreateTodoInput,
+  UpdateTodoInput,
+  TodoAttachment,
+  TodoWithAttachments,
+} from '@shared/schemas'
+import { getDb } from '@server/db'
+import { todos, todoAttachments, type TodoTable, type TodoAttachmentTable } from '@server/db/schema'
+import { toISOString } from '@server/utils/date'
+import { saveFile, deleteFile, validateFile, getUploadConfig } from '@server/utils/file-storage'
+
+const TODO_NAMESPACE = 'todos'
+
+export async function listTodos(): Promise<Todo[]> {
+  const db = await getDb()
+  const rows = await db.select().from(todos).orderBy(desc(todos.createdAt))
+  return rows.map((row: TodoTable) => ({
+    id: row.id,
+    title: row.title,
+    description: row.description ?? undefined,
+    status: row.status,
+    createdAt: toISOString(row.createdAt),
+    updatedAt: toISOString(row.updatedAt),
+  }))
+}
+
+export async function getTodo(id: number): Promise<Todo | null> {
+  const db = await getDb()
+  const rows = await db.select().from(todos).where(eq(todos.id, id))
+  const row = rows[0]
+
+  if (!row) return null
+
+  return {
+    id: row.id,
+    title: row.title,
+    description: row.description ?? undefined,
+    status: row.status,
+    createdAt: toISOString(row.createdAt),
+    updatedAt: toISOString(row.updatedAt),
+  }
+}
+
+export async function createTodo(input: CreateTodoInput): Promise<Todo> {
+  const db = await getDb()
+  const now = new Date()
+  const result = await db
+    .insert(todos)
+    .values({
+      title: input.title,
+      description: input.description ?? null,
+      status: 'pending',
+      createdAt: now,
+      updatedAt: now,
+    })
+    .returning()
+
+  const row = result[0]
+  return {
+    id: row.id,
+    title: row.title,
+    description: row.description ?? undefined,
+    status: row.status,
+    createdAt: toISOString(row.createdAt),
+    updatedAt: toISOString(row.updatedAt),
+  }
+}
+
+export async function updateTodo(id: number, input: UpdateTodoInput): Promise<Todo | null> {
+  const db = await getDb()
+  const now = new Date()
+  const updateData: Partial<TodoTable> = {
+    updatedAt: now,
+  }
+
+  if (input.title !== undefined && input.title !== null) {
+    updateData.title = input.title
+  }
+  if (input.description !== undefined && input.description !== null) {
+    updateData.description = input.description
+  }
+  if (input.status !== undefined && input.status !== null) {
+    updateData.status = input.status
+  }
+
+  const result = await db.update(todos).set(updateData).where(eq(todos.id, id)).returning()
+
+  if (result.length === 0) return null
+
+  const row = result[0]
+  return {
+    id: row.id,
+    title: row.title,
+    description: row.description ?? undefined,
+    status: row.status,
+    createdAt: toISOString(row.createdAt),
+    updatedAt: toISOString(row.updatedAt),
+  }
+}
+
+export async function deleteTodo(id: number): Promise<boolean> {
+  const db = await getDb()
+
+  const attachments = await db.select().from(todoAttachments).where(eq(todoAttachments.todoId, id))
+
+  for (const attachment of attachments) {
+    await deleteFile(attachment.path)
+  }
+
+  const result = await db.delete(todos).where(eq(todos.id, id)).returning()
+  return result.length > 0
+}
+
+export async function uploadAttachment(
+  todoId: number,
+  file: { name: string; type: string; size: number; data: ArrayBuffer },
+  uploadedBy?: string
+): Promise<TodoAttachment> {
+  const db = await getDb()
+
+  const config = getUploadConfig(TODO_NAMESPACE)
+  const validation = validateFile(file, config)
+  if (!validation.valid) {
+    throw new Error(validation.error)
+  }
+
+  const uploadedFile = await saveFile(TODO_NAMESPACE, file)
+
+  const now = new Date()
+  const result = await db
+    .insert(todoAttachments)
+    .values({
+      todoId,
+      fileName: uploadedFile.filename,
+      originalName: uploadedFile.originalName,
+      mimeType: uploadedFile.mimeType,
+      size: uploadedFile.size,
+      path: uploadedFile.path,
+      uploadedBy: uploadedBy ?? null,
+      createdAt: now,
+    })
+    .returning()
+
+  const row = result[0]
+  return {
+    id: row.id,
+    todoId: row.todoId,
+    fileName: row.fileName,
+    originalName: row.originalName,
+    mimeType: row.mimeType,
+    size: row.size,
+    path: row.path,
+    uploadedBy: row.uploadedBy ?? undefined,
+    createdAt: toISOString(row.createdAt),
+  }
+}
+
+export async function listAttachments(todoId: number): Promise<TodoAttachment[]> {
+  const db = await getDb()
+  const rows = await db
+    .select()
+    .from(todoAttachments)
+    .where(eq(todoAttachments.todoId, todoId))
+    .orderBy(desc(todoAttachments.createdAt))
+
+  return rows.map((row: TodoAttachmentTable) => ({
+    id: row.id,
+    todoId: row.todoId,
+    fileName: row.fileName,
+    originalName: row.originalName,
+    mimeType: row.mimeType,
+    size: row.size,
+    path: row.path,
+    uploadedBy: row.uploadedBy ?? undefined,
+    createdAt: toISOString(row.createdAt),
+  }))
+}
+
+export async function getTodoWithAttachments(id: number): Promise<TodoWithAttachments | null> {
+  const todo = await getTodo(id)
+  if (!todo) return null
+
+  const attachments = await listAttachments(id)
+  return { ...todo, attachments }
+}
+
+export async function deleteAttachment(attachmentId: number): Promise<boolean> {
+  const db = await getDb()
+
+  const rows = await db.select().from(todoAttachments).where(eq(todoAttachments.id, attachmentId))
+
+  if (rows.length === 0) return false
+
+  const attachment = rows[0]
+
+  await deleteFile(attachment.path)
+
+  await db.delete(todoAttachments).where(eq(todoAttachments.id, attachmentId))
+  return true
+}

package/template/src/server/route-registry.ts

@@ -0,0 +1,47 @@
+import { OpenAPIHono } from '@hono/zod-openapi'
+import { rateLimitMiddleware } from './middleware/rate-limit'
+import { apiRoutes } from './module-todos/routes/todos-routes'
+import { permissionRoutes } from './module-permission/routes/permission-routes'
+import { roleRoutes } from './module-permission/routes/role-routes'
+import { auditLogRoutes } from './module-permission/routes/audit-log-routes'
+import { notificationRoutes } from './module-notifications/routes/notification-routes'
+import { chatRoutes } from './module-chat/routes/chat-routes'
+import { adminRoutes } from './module-admin/routes/admin-routes'
+import { captchaRoutes } from './module-captcha/routes/captcha-routes'
+import { orderRoutes } from './module-order/routes/order-routes'
+import { ticketRoutes } from './module-ticket/routes/ticket-routes'
+import { disputeRoutes } from './module-dispute/routes/dispute-routes'
+import { contentRoutes } from './module-content/routes/content-routes'
+import { publicContentRoutes } from './module-content/routes/public-content-routes'
+import { fileRoutes } from './module-file/routes/file-routes'
+
+const apiRateLimit = rateLimitMiddleware({
+  windowMs: 60_000,
+  max: 100,
+  message: 'Too many requests',
+})
+
+// 客户端路由 - 普通用户使用的 API
+export const clientApiRoutes = new OpenAPIHono()
+  .use('*', apiRateLimit)
+  .route('/api', chatRoutes)
+  .route('/api', notificationRoutes)
+  .route('/api', apiRoutes)
+  .route('/api', publicContentRoutes)
+
+// 管理后台路由 - 普通用户使用的 API + 管理功能
+export const adminApiRoutes = new OpenAPIHono()
+  .route('/api', orderRoutes)
+  .route('/api', ticketRoutes)
+  .route('/api', disputeRoutes)
+  .route('/api', contentRoutes)
+  .route('/api', fileRoutes)
+  .route('/api', captchaRoutes)
+  .route('/api', permissionRoutes)
+  .route('/api', roleRoutes)
+  .route('/api', auditLogRoutes)
+  .route('/api', adminRoutes)
+
+// 导出类型
+export type ClientApiRoutes = typeof clientApiRoutes
+export type AdminApiRoutes = typeof adminApiRoutes

package/template/src/server/test-utils/test-client.ts

@@ -0,0 +1,66 @@
+/**
+ * @framework-baseline b18502d5cc33f07d
+ *
+ * @framework-modify
+ * @reason 添加 headers 参数支持，以便在测试中传递认证头
+ * @impact 测试客户端现在支持自定义 headers，用于认证测试
+ */
+
+import { hc } from 'hono/client'
+import type { AppType } from '@server/index'
+import { createApp } from '@server/app'
+import { SSEClientImpl } from '@shared/core/sse-client'
+import { setRuntimeAdapter } from '@server/core/runtime'
+import { getNodeRuntimeAdapter } from '@server/core/runtime-node'
+
+setRuntimeAdapter(getNodeRuntimeAdapter())
+
+/**
+ * 测试客户端类型
+ *
+ * 注意：TypeScript 在推导 Hono Client 类型时可能触发 TS2589，
+ * 该警告不影响运行时行为，测试客户端可正常工作。
+ */
+export type TestClient = ReturnType<typeof hc<AppType>>
+
+export interface TestClientOptions {
+  webSocket?: (url: string | URL) => WebSocket
+  sse?: (url: string | URL) => unknown
+  headers?: Record<string, string>
+}
+
+/**
+ * 创建测试客户端
+ */
+export function createTestClient(baseUrl?: string, options?: TestClientOptions) {
+  const app = createApp()
+  const defaultHeaders = {
+    'User-Agent': 'TestClient/1.0 (Unit Test)',
+    ...options?.headers,
+  }
+
+  const sseFactory = options?.sse
+    ? (url: string | URL) => options.sse!(url)
+    : (url: string | URL) => new SSEClientImpl(url, defaultHeaders)
+
+  if (baseUrl) {
+    return hc<AppType>(baseUrl, {
+      headers: defaultHeaders,
+      webSocket: options?.webSocket ? (url: string | URL) => options.webSocket!(url) : undefined,
+      sse: sseFactory as (url: string) => unknown,
+    })
+  }
+  return hc<AppType>('http://localhost', {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    fetch: (input: any, init?: any) => {
+      const request = new Request(input, init)
+      Object.entries(defaultHeaders).forEach(([key, value]) => {
+        if (!request.headers.has(key)) {
+          request.headers.set(key, value)
+        }
+      })
+      return app.fetch(request)
+    },
+    sse: sseFactory as (url: string) => unknown,
+  })
+}

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

@@ -0,0 +1,131 @@
+/**
+ * @framework-baseline ecef67ddd440f5b9
+ * @framework-modify
+ * @reason 修复 ReadableStream 类型检查，添加 null 检查以避免类型错误
+ * @impact 测试工具中的流式响应处理更加健壮，避免运行时错误
+ */
+
+import { createServer, type Server } from 'http'
+import { WebSocketServer } from 'ws'
+import type { Hono, Env, Schema } from 'hono'
+import { getNodeRuntimeAdapter } from '@server/core/runtime-node'
+import type { ReadableStream } from 'stream/web'
+
+export interface TestServer {
+  server: Server
+  port: number
+  wsUrl: string
+  close: () => Promise<void>
+}
+
+interface AddressInfo {
+  address: string
+  family: string
+  port: number
+}
+
+export function createTestServer<E extends Env, S extends Schema, BasePath extends string>(
+  app: Hono<E, S, BasePath>,
+  wsPaths: string[] = []
+): Promise<TestServer> {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    const runtimeAdapter = getNodeRuntimeAdapter()
+    const wss = new WebSocketServer({ noServer: true })
+
+    server.on('upgrade', (req, socket, head) => {
+      const url = new URL(req.url || '', `http://localhost`)
+
+      if (runtimeAdapter.hasWSPath(url.pathname)) {
+        wss.handleUpgrade(req, socket, head, ws => {
+          runtimeAdapter.handleConnection(ws)
+        })
+      } else {
+        socket.destroy()
+      }
+    })
+
+    server.on('request', (req, res) => {
+      const chunks: Buffer[] = []
+      req.on('data', chunk => chunks.push(chunk))
+      req.on('end', () => {
+        const body = Buffer.concat(chunks)
+        const address = server.address() as AddressInfo | null
+        const port = address?.port ?? 0
+        const url = new URL(req.url || '/', `http://localhost:${port}`)
+        const headers = new Headers()
+        for (const [key, value] of Object.entries(req.headers)) {
+          if (value) {
+            headers.set(key, Array.isArray(value) ? value.join(', ') : value)
+          }
+        }
+        const request = new Request(url, {
+          method: req.method,
+          headers,
+          body: body.length > 0 ? body : undefined,
+        })
+        Promise.resolve(app.fetch(request))
+          .then((response: Response) => {
+            res.statusCode = response.status
+            response.headers.forEach((value: string, key: string) => {
+              res.setHeader(key, value)
+            })
+
+            const contentType = response.headers.get('content-type') || ''
+            if (contentType.includes('text/event-stream')) {
+              const reader = (response.body as ReadableStream<Uint8Array> | null)?.getReader()
+              if (!reader) {
+                res.end()
+                return
+              }
+              const pump = (): Promise<void> =>
+                reader.read().then(({ done, value }) => {
+                  if (done) {
+                    res.end()
+                    return
+                  }
+                  res.write(Buffer.from(value))
+                  return pump()
+                })
+              pump().catch((err: Error) => {
+                console.error('SSE stream error:', err)
+                res.end()
+              })
+            } else {
+              response.arrayBuffer().then((buffer: ArrayBuffer) => {
+                res.end(Buffer.from(buffer))
+              })
+            }
+          })
+          .catch((err: Error) => {
+            res.statusCode = 500
+            res.end(err.message)
+          })
+      })
+    })
+
+    server.listen(0, () => {
+      const address = server.address()
+      if (address && typeof address === 'object') {
+        const port = address.port
+        const wsUrl =
+          wsPaths.length > 0 ? `ws://localhost:${port}${wsPaths[0]}` : `ws://localhost:${port}`
+
+        resolve({
+          server,
+          port,
+          wsUrl,
+          close: () =>
+            new Promise<void>(res => {
+              wss.close(() => {
+                server.closeAllConnections()
+                server.close(() => res())
+              })
+            }),
+        })
+      } else {
+        reject(new Error('Failed to get server address'))
+      }
+    })
+  })
+}