create-fullstack-scaffold 0.1.1 → 0.2.0

package/template/src/server/entries/node.ts

@@ -16,6 +16,9 @@ import { getAppConfig } from '../config'
 import { logger } from '../utils/logger'
 import { createApp } from '../app'
 import { getDb, runMigrations } from '../db'
+import { createISRCache, isISRRoute } from '@server/core/isr-cache'
+import { renderPage } from '@server/core/ssr-renderer'
+import { setISRCache } from '@server/core/isr-invalidation'
 import { setRuntimeAdapter } from '@server/core/runtime'
 import { getNodeRuntimeAdapter } from '@server/core/runtime-node'
 
@@ -41,9 +44,16 @@ const adminHtml = existsSync(adminHtmlPath)
 
 const log = logger.api()
 
+const isrCache = createISRCache()
+setISRCache(isrCache)
+
 const runtimeAdapter = getNodeRuntimeAdapter()
 setRuntimeAdapter(runtimeAdapter)
 
+runtimeAdapter.handleWS('/api/chat/ws')
+runtimeAdapter.handleSSE('/api/notifications/stream')
+runtimeAdapter.handleSSE('/api/admin/notifications/stream')
+
 // 先创建基础应用
 const baseApp = createApp()
 
@@ -104,12 +114,41 @@ app.get('/admin/*', c => {
   return c.html(adminHtml)
 })
 
-// 其他非 API 路由返回 index.html
-app.get('*', c => {
-  // 如果路径以 /api/ 或 /files/ 开头，让 Hono 继续处理（可能会返回 404）
+// 其他非 API 路由返回 index.html（ISR 路由尝试缓存）
+app.get('*', async c => {
   if (c.req.path.startsWith('/api/') || c.req.path.startsWith('/files/')) {
     return c.notFound()
   }
+
+  const pathname = c.req.path
+
+  if (hasDist && isISRRoute(pathname)) {
+    const result = await isrCache.lookup(pathname)
+
+    if (result.status === 'fresh' && result.html) {
+      return c.html(result.html)
+    }
+
+    if (result.status === 'stale' && result.html) {
+      renderPage(pathname)
+        .then(rendered => {
+          isrCache.store(pathname, rendered.html).catch(e => {
+            console.warn('ISR cache store (background revalidation) failed:', e)
+          })
+        })
+        .catch(e => {
+          console.warn('ISR background render failed:', e)
+        })
+      return c.html(result.html)
+    }
+
+    const rendered = await renderPage(pathname)
+    isrCache.store(pathname, rendered.html).catch(e => {
+      console.warn('ISR cache store failed:', e)
+    })
+    return c.html(rendered.html)
+  }
+
   return c.html(indexHtml)
 })
 
@@ -118,10 +157,14 @@ app.get('*', c => {
 app.onError((err, c) => {
   log.error({ err, path: c.req.path }, 'server error')
   c.res.headers.set('Content-Type', 'application/json')
-  const statusCode = err instanceof Error && 'status' in err ? (err as { status: number }).status : 500
+  const statusCode =
+    err instanceof Error && 'status' in err ? (err as { status: number }).status : 500
   const message = err.message || 'Internal server error'
   const responseStatus = statusCode || 500
-  return c.json({ success: false as const, error: message, status: responseStatus }, responseStatus as 500)
+  return c.json(
+    { success: false as const, error: message, status: responseStatus },
+    responseStatus as 500
+  )
 })
 
 export default app

package/template/src/server/middleware/__tests__/captcha.test.ts

@@ -8,9 +8,7 @@ import {
 } from '../captcha'
 
 describe('captchaMiddleware', () => {
-  beforeEach(() => {
-    vi.stubEnv('NODE_ENV', 'development')
-  })
+  beforeEach(() => {})
 
   afterEach(() => {
     vi.unstubAllEnvs()
@@ -28,10 +26,22 @@ describe('captchaMiddleware', () => {
     expect(handler).toHaveBeenCalled()
   })
 
-  it('should skip configured skip paths', async () => {
+  it('should skip in development environment', async () => {
+    vi.stubEnv('NODE_ENV', 'development')
     const app = new Hono()
     const handler = vi.fn().mockResolvedValue(new Response('ok'))
     app.use('*', captchaMiddleware())
+    app.get('/api/dev', handler)
+
+    const res = await app.request('/api/dev')
+    expect(res.status).toBe(200)
+    expect(handler).toHaveBeenCalled()
+  })
+
+  it('should skip configured skip paths', async () => {
+    const app = new Hono()
+    const handler = vi.fn().mockResolvedValue(new Response('ok'))
+    app.use('*', captchaMiddleware({ forceEnabled: true }))
     app.get('/api/captcha', handler)
     app.post('/api/verify-captcha', handler)
     app.post('/api/admin/login', handler)
@@ -54,7 +64,7 @@ describe('captchaMiddleware', () => {
   it('should skip custom skip paths', async () => {
     const app = new Hono()
     const handler = vi.fn().mockResolvedValue(new Response('ok'))
-    app.use('*', captchaMiddleware({ skipPaths: ['/api/custom'] }))
+    app.use('*', captchaMiddleware({ forceEnabled: true, skipPaths: ['/api/custom'] }))
     app.get('/api/custom', handler)
 
     const res = await app.request('/api/custom')
@@ -65,7 +75,7 @@ describe('captchaMiddleware', () => {
   it('should allow requests within rate limit', async () => {
     const app = new Hono()
     let callCount = 0
-    app.use('*', captchaMiddleware({ maxRequests: 10, windowMs: 60000 }))
+    app.use('*', captchaMiddleware({ forceEnabled: true, maxRequests: 10, windowMs: 60000 }))
     app.get('/api/data', c => {
       callCount++
       return c.json({ ok: true })
@@ -82,7 +92,7 @@ describe('captchaMiddleware', () => {
 
   it('should block requests exceeding rate limit', async () => {
     const app = new Hono()
-    app.use('*', captchaMiddleware({ maxRequests: 3, windowMs: 60000 }))
+    app.use('*', captchaMiddleware({ forceEnabled: true, maxRequests: 3, windowMs: 60000 }))
     app.get('/api/data', c => c.json({ ok: true }))
 
     const ua = 'Mozilla/5.0 Test Browser For Rate Limit Testing'
@@ -109,7 +119,7 @@ describe('captchaMiddleware', () => {
 
   it('should block suspicious requests with short User-Agent', async () => {
     const app = new Hono()
-    app.use('*', captchaMiddleware())
+    app.use('*', captchaMiddleware({ forceEnabled: true }))
     app.get('/api/data', c => c.json({ ok: true }))
 
     const res = await app.request('/api/data', {
@@ -122,7 +132,7 @@ describe('captchaMiddleware', () => {
 
   it('should block requests with bot in User-Agent', async () => {
     const app = new Hono()
-    app.use('*', captchaMiddleware())
+    app.use('*', captchaMiddleware({ forceEnabled: true }))
     app.get('/api/data', c => c.json({ ok: true }))
 
     const res = await app.request('/api/data', {
@@ -133,7 +143,7 @@ describe('captchaMiddleware', () => {
 
   it('should block requests with crawler in User-Agent', async () => {
     const app = new Hono()
-    app.use('*', captchaMiddleware())
+    app.use('*', captchaMiddleware({ forceEnabled: true }))
     app.get('/api/data', c => c.json({ ok: true }))
 
     const res = await app.request('/api/data', {
@@ -144,7 +154,7 @@ describe('captchaMiddleware', () => {
 
   it('should block requests with empty User-Agent', async () => {
     const app = new Hono()
-    app.use('*', captchaMiddleware())
+    app.use('*', captchaMiddleware({ forceEnabled: true }))
     app.get('/api/data', c => c.json({ ok: true }))
 
     const res = await app.request('/api/data')
@@ -154,7 +164,7 @@ describe('captchaMiddleware', () => {
   it('should reset rate limit after window expires', async () => {
     vi.useFakeTimers()
     const app = new Hono()
-    app.use('*', captchaMiddleware({ maxRequests: 2, windowMs: 1000 }))
+    app.use('*', captchaMiddleware({ forceEnabled: true, maxRequests: 2, windowMs: 1000 }))
     app.get('/api/data', c => c.json({ ok: true }))
 
     const ua = 'Mozilla/5.0 Window Reset Test Browser'
@@ -191,7 +201,7 @@ describe('captchaMiddleware', () => {
     markCaptchaVerifiedMiddleware(sessionId)
 
     const app = new Hono()
-    app.use('*', captchaMiddleware({ maxRequests: 1, windowMs: 60000 }))
+    app.use('*', captchaMiddleware({ forceEnabled: true, maxRequests: 1, windowMs: 60000 }))
     app.get('/api/data', c => c.json({ ok: true }))
 
     const res = await app.request('/api/data', {

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

@@ -40,7 +40,14 @@ if (secretKey === defaultSecretKey && process.env.NODE_ENV === 'production') {
 }
 
 const isDevTokensEnabled = (): boolean => {
-  return process.env.ENABLE_DEV_TOKENS === 'true' && process.env.NODE_ENV !== 'production'
+  // 显式启用 dev tokens（优先级最高，即使 production 也能用）
+  if (process.env.ENABLE_DEV_TOKENS === 'true') return true
+  // 显式禁用
+  if (process.env.ENABLE_DEV_TOKENS === 'false') return false
+  // production 默认禁用
+  if (process.env.NODE_ENV === 'production') return false
+  // 开发环境默认启用
+  return true
 }
 
 if (isDevTokensEnabled()) {

package/template/src/server/middleware/captcha.ts

@@ -6,6 +6,7 @@ export interface CaptchaConfig {
   skipPaths?: string[]
   maxRequests?: number
   windowMs?: number
+  forceEnabled?: boolean
 }
 
 interface CaptchaSession {
@@ -40,10 +41,12 @@ export function captchaMiddleware(config: CaptchaConfig = {}) {
     skipPaths = ['/api/captcha', '/api/verify-captcha', '/api/admin/login', '/api/admin/register'],
     maxRequests = 10,
     windowMs = 60000,
+    forceEnabled = false,
   } = config
 
   return async (c: Context, next: Next) => {
-    if (process.env.NODE_ENV === 'test') {
+    const skipEnvCheck = !forceEnabled && process.env.NODE_ENV === 'test'
+    if (skipEnvCheck) {
       return next()
     }
 
@@ -97,7 +100,7 @@ export function captchaMiddleware(config: CaptchaConfig = {}) {
       )
     }
 
-    if (isSuspiciousRequest(c)) {
+    if (isSuspiciousRequest(c, forceEnabled)) {
       return c.json(
         {
           success: false as const,
@@ -136,14 +139,21 @@ function generateSessionId(): string {
   return randomUUID()
 }
 
-function isSuspiciousRequest(c: Context): boolean {
+function isSuspiciousRequest(c: Context, forceEnabled = false): boolean {
+  if (
+    !forceEnabled &&
+    (process.env.NODE_ENV === 'test' || process.env.NODE_ENV === 'development')
+  ) {
+    return false
+  }
+
   const userAgent = c.req.header('User-Agent') || ''
 
   if (!userAgent || userAgent.length < 10) {
     return true
   }
 
-  if (userAgent.includes('bot') || userAgent.includes('crawler')) {
+  if (userAgent.toLowerCase().includes('bot') || userAgent.toLowerCase().includes('crawler')) {
     return true
   }
 

package/template/src/server/middleware/rate-limit.ts

@@ -4,14 +4,18 @@ type RateLimitEntry = { count: number; resetAt: number }
 
 const rateLimitStore = new Map<string, RateLimitEntry>()
 
-setInterval(() => {
+let lastCleanup = Date.now()
+
+function cleanupExpired() {
   const now = Date.now()
+  if (now - lastCleanup < 60_000) return
+  lastCleanup = now
   for (const [key, entry] of rateLimitStore) {
     if (entry.resetAt <= now) {
       rateLimitStore.delete(key)
     }
   }
-}, 60_000)
+}
 
 export type RateLimitOptions = {
   windowMs?: number
@@ -29,6 +33,7 @@ export function rateLimitMiddleware(options: RateLimitOptions = {}) {
       return next()
     }
 
+    cleanupExpired()
     const ip =
       c.req.header('x-forwarded-for')?.split(',')[0]?.trim() ||
       c.req.header('x-real-ip') ||

package/template/src/server/module-admin/module.ts

@@ -8,21 +8,27 @@ const adminManifest: ModuleManifest = {
   dependsOn: ['permission', 'notifications'],
 
   routes: {
+    client: {
+      importPath: './routes/client-auth-routes',
+      exportName: 'clientAuthRoutes',
+    },
     admin: [
       {
         importPath: './routes/admin-routes',
         exportName: 'adminRoutes',
       },
     ],
-    // Note: admin-routes.ts is an aggregator that composes sub-routes:
-    // auth-routes (login/register/me), user-management-routes, admin-notification-routes,
-    // media-routes (avatar/svg), export-routes (CSV), system-routes (stats/health/activity)
   },
 
   sharedSchemas: {
     path: 'admin',
   },
 
+  clientPages: [
+    { name: 'DashboardPage', route: '/dashboard' },
+    { name: 'SettingsPage', route: '/settings' },
+  ],
+
   adminPages: [
     { name: 'LoginPage', route: '/login', isPublic: true },
     { name: 'RegisterPage', route: '/register', isPublic: true },
@@ -32,8 +38,6 @@ const adminManifest: ModuleManifest = {
     { name: 'MediaTestPage', route: '/test/media' },
   ],
 
-  clientStores: ['authStore'],
-
   hasSSE: true,
 }
 

package/template/src/server/module-admin/routes/admin-notification-routes.ts

@@ -17,6 +17,30 @@ import {
 } from '@shared/modules/notifications'
 import { SuccessSchema } from '@shared/modules/admin'
 
+function createFallbackSSEResponse(): Response {
+  const stream = new ReadableStream({
+    start(controller) {
+      const encoder = new TextEncoder()
+      const sendPing = () => {
+        controller.enqueue(encoder.encode(`event: ping\ndata: {"timestamp":${Date.now()}}\n\n`))
+      }
+      sendPing()
+      const interval = setInterval(sendPing, 30000)
+      setTimeout(() => {
+        clearInterval(interval)
+        controller.close()
+      }, 300000)
+    },
+  })
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  })
+}
+
 const getNotificationsRoute = createRoute({
   method: 'get',
   path: '/admin/notifications',
@@ -160,18 +184,18 @@ export const adminNotificationRoutes = new OpenAPIHono<{ Variables: { authUser:
         type === 'warning'
           ? '警告通知'
           : type === 'error'
-            ? '错误通知'
-            : type === 'success'
-              ? '成功通知'
-              : '系统通知',
+          ? '错误通知'
+          : type === 'success'
+          ? '成功通知'
+          : '系统通知',
       message:
         type === 'warning'
           ? '这是一条警告通知，请注意！'
           : type === 'error'
-            ? '这是一条错误通知，请立即处理！'
-            : type === 'success'
-              ? '操作成功完成！'
-              : '这是一条普通信息通知',
+          ? '这是一条错误通知，请立即处理！'
+          : type === 'success'
+          ? '操作成功完成！'
+          : '这是一条普通信息通知',
     })
     return c.json(success(notification), 200)
   })
@@ -187,11 +211,16 @@ export const adminNotificationRoutes = new OpenAPIHono<{ Variables: { authUser:
       return stub.fetch(doRequest)
     }
 
-    const { getRuntimeAdapter } = await import('@server/core/runtime')
-    const adapter = getRuntimeAdapter()
-    if (adapter.handleSSERequest) {
-      const response = await adapter.handleSSERequest()
-      return response
+    try {
+      const { getRuntimeAdapter } = await import('@server/core/runtime')
+      const adapter = getRuntimeAdapter()
+      if (adapter.handleSSERequest) {
+        const response = await adapter.handleSSERequest()
+        return response
+      }
+    } catch {
+      return createFallbackSSEResponse()
     }
-    return c.json({ success: false as const, error: 'SSE not supported' }, 500)
+
+    return createFallbackSSEResponse()
   })

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

@@ -16,5 +16,3 @@ const adminBase2 = adminBase1.route('/', adminNotificationRoutes).route('/', med
 const adminBase3 = adminBase2.route('/', exportRoutes).route('/', systemRoutes)
 
 export const adminRoutes = adminBase3
-
-export default adminRoutes

package/template/src/server/module-admin/routes/client-auth-routes.ts

@@ -0,0 +1,90 @@
+import { createRoute } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+import { authMiddleware, type AuthUser } from '@server/middleware/auth'
+import { strictRateLimitMiddleware } from '@server/middleware/rate-limit'
+import { getAuthUser } from '@server/utils/auth'
+import * as adminService from '../services/admin-service'
+import { successResponse, errorResponse, success } from '@server/utils/route-helpers'
+import {
+  AuthUserSchema,
+  LoginRequestSchema,
+  LoginResponseSchema,
+  RegisterRequestSchema,
+  UserSchema,
+} from '@shared/modules/admin'
+
+const loginRoute = createRoute({
+  method: 'post',
+  path: '/auth/login',
+  tags: ['auth'],
+  middleware: [strictRateLimitMiddleware] as const,
+  request: {
+    body: {
+      content: {
+        'application/json': {
+          schema: LoginRequestSchema,
+        },
+      },
+    },
+  },
+  responses: {
+    200: successResponse(LoginResponseSchema, 'Login successful'),
+    401: errorResponse('Invalid credentials'),
+  },
+})
+
+const registerRoute = createRoute({
+  method: 'post',
+  path: '/auth/register',
+  tags: ['auth'],
+  middleware: [strictRateLimitMiddleware] as const,
+  request: {
+    body: {
+      content: {
+        'application/json': {
+          schema: RegisterRequestSchema,
+        },
+      },
+    },
+  },
+  responses: {
+    201: successResponse(UserSchema, 'User registered'),
+    400: errorResponse('User already exists'),
+  },
+})
+
+const meRoute = createRoute({
+  method: 'get',
+  path: '/auth/me',
+  tags: ['auth'],
+  security: [{ Bearer: [] }],
+  middleware: [authMiddleware()],
+  responses: {
+    200: successResponse(AuthUserSchema, 'Get current authenticated user'),
+    401: errorResponse('Unauthorized'),
+  },
+})
+
+export const clientAuthRoutes = new OpenAPIHono<{ Variables: { authUser: AuthUser } }>()
+  .openapi(loginRoute, async c => {
+    try {
+      const data = c.req.valid('json')
+      const result = await adminService.login(data)
+      return c.json(success(result), 200)
+    } catch {
+      return c.json({ success: false as const, error: 'Invalid credentials' }, 401)
+    }
+  })
+  .openapi(registerRoute, async c => {
+    try {
+      const data = c.req.valid('json')
+      const user = await adminService.register(data)
+      return c.json(success(user), 201)
+    } catch {
+      return c.json({ success: false as const, error: 'User already exists' }, 400)
+    }
+  })
+  .openapi(meRoute, async c => {
+    const user = getAuthUser(c)
+    return c.json(success(user), 200)
+  })

package/template/src/server/module-admin/routes/dashboard-routes.ts

@@ -0,0 +1,79 @@
+import { createRoute } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+import { successResponse } from '@server/utils/route-helpers'
+import { DashboardResponseSchema } from '@shared/schemas'
+
+const getDashboardStatsRoute = createRoute({
+  method: 'get',
+  path: '/admin/dashboard/stats',
+  responses: {
+    200: successResponse(DashboardResponseSchema, 'Dashboard stats'),
+  },
+})
+
+export const dashboardRoutes = new OpenAPIHono().openapi(getDashboardStatsRoute, async c => {
+  return c.json({
+    success: true as const,
+    data: {
+      stats: [
+        { label: 'Total Users', value: '12,847', trend: 12.5 },
+        { label: 'Active Users', value: '8,234', trend: 8.2 },
+        { label: 'Revenue', value: '$48,293', trend: -2.4 },
+        { label: 'Conversion', value: '3.2%', trend: 4.1 },
+      ],
+      revenue: [
+        { month: 'Jan', value: 65 },
+        { month: 'Feb', value: 45 },
+        { month: 'Mar', value: 78 },
+        { month: 'Apr', value: 52 },
+        { month: 'May', value: 90 },
+        { month: 'Jun', value: 70 },
+      ],
+      userGrowth: [
+        { month: 'Jan', value: 30 },
+        { month: 'Feb', value: 45 },
+        { month: 'Mar', value: 55 },
+        { month: 'Apr', value: 60 },
+        { month: 'May', value: 72 },
+        { month: 'Jun', value: 85 },
+      ],
+      activity: [
+        {
+          id: 1,
+          user: 'Sarah Chen',
+          action: 'Upgraded to Pro plan',
+          date: '2024-01-15',
+          status: 'Active' as const,
+        },
+        {
+          id: 2,
+          user: 'Mike Johnson',
+          action: 'Submitted support ticket',
+          date: '2024-01-14',
+          status: 'Pending' as const,
+        },
+        {
+          id: 3,
+          user: 'Emily Davis',
+          action: 'Cancelled subscription',
+          date: '2024-01-13',
+          status: 'Inactive' as const,
+        },
+        {
+          id: 4,
+          user: 'Alex Turner',
+          action: 'Registered new account',
+          date: '2024-01-12',
+          status: 'Active' as const,
+        },
+        {
+          id: 5,
+          user: 'Lisa Park',
+          action: 'Updated billing info',
+          date: '2024-01-11',
+          status: 'Active' as const,
+        },
+      ],
+    },
+  })
+})