create-fullstack-scaffold 0.1.1 → 0.2.0

package/template/src/server/module-content/routes/public-content-routes.ts

@@ -3,7 +3,7 @@ import { OpenAPIHono } from '@hono/zod-openapi'
 import * as contentService from '../services/content-service'
 import { successResponse, errorResponse } from '@server/utils/route-helpers'
 import { NotFoundError } from '@server/utils/app-error'
-import { success, list } from '@server/utils/response'
+import { success } from '@server/utils/response'
 import { z } from '@hono/zod-openapi'
 import { ContentSchema, ContentCategorySchema } from '@shared/modules/content'
 
@@ -46,7 +46,7 @@ export const publicContentRoutes = new OpenAPIHono()
       search,
     })
     const items = result.slice(offset, offset + limit)
-    return c.json(list(items, result.length), 200)
+    return c.json(success(items), 200)
   })
   .openapi(getPublicRoute, async c => {
     const { id } = c.req.valid('param')

package/template/src/server/module-content/routes/topics-routes.ts

@@ -0,0 +1,205 @@
+import { createRoute } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+import { successResponse } from '@server/utils/route-helpers'
+import { TopicsResponseSchema, ProfileResponseSchema } from '@shared/schemas'
+
+const MOCK_TOPICS = [
+  {
+    id: '1',
+    title: 'How to implement real-time notifications with SSE?',
+    excerpt:
+      'I am trying to set up server-sent events for my community app. The connection keeps dropping after a few minutes. Has anyone dealt with this issue before?',
+    votes: 24,
+    replyCount: 8,
+    viewCount: 342,
+    status: 'solved' as const,
+    tags: [
+      { label: 'SSE', color: 'bg-emerald-100 text-emerald-700' },
+      { label: 'Real-time', color: 'bg-blue-100 text-blue-700' },
+    ],
+    author: { name: 'Sarah Chen', initials: 'SC' },
+    createdAt: '1h ago',
+  },
+  {
+    id: '2',
+    title: 'Best practices for WebSocket reconnection logic',
+    excerpt:
+      'My WebSocket client disconnects when the user switches tabs. What reconnection strategies do you recommend for a production environment?',
+    votes: 18,
+    replyCount: 0,
+    viewCount: 156,
+    status: 'unanswered' as const,
+    tags: [
+      { label: 'WebSocket', color: 'bg-purple-100 text-purple-700' },
+      { label: 'Architecture', color: 'bg-orange-100 text-orange-700' },
+    ],
+    author: { name: 'Alex Rivera', initials: 'AR' },
+    createdAt: '2h ago',
+  },
+  {
+    id: '3',
+    title: 'Type-safe API routes with Hono RPC — a complete guide',
+    excerpt:
+      'After months of using Hono RPC in production, here is my comprehensive guide to achieving full end-to-end type safety across your stack.',
+    votes: 56,
+    replyCount: 12,
+    viewCount: 891,
+    status: 'hot' as const,
+    tags: [
+      { label: 'Hono', color: 'bg-sky-100 text-sky-700' },
+      { label: 'TypeScript', color: 'bg-blue-100 text-blue-700' },
+      { label: 'Guide', color: 'bg-emerald-100 text-emerald-700' },
+    ],
+    author: { name: 'Jordan Park', initials: 'JP' },
+    createdAt: '3h ago',
+  },
+  {
+    id: '4',
+    title: 'Deploying Hono apps to Cloudflare Workers with D1',
+    excerpt:
+      'Step-by-step walkthrough of deploying a full-stack Hono application to Cloudflare Workers, including database setup with D1 and R2 storage.',
+    votes: 31,
+    replyCount: 5,
+    viewCount: 478,
+    status: 'solved' as const,
+    tags: [
+      { label: 'Cloudflare', color: 'bg-amber-100 text-amber-700' },
+      { label: 'Deployment', color: 'bg-rose-100 text-rose-700' },
+    ],
+    author: { name: 'Mika Tanaka', initials: 'MT' },
+    createdAt: '5h ago',
+  },
+  {
+    id: '5',
+    title: 'Zustand vs Jotai — which state manager for community apps?',
+    excerpt:
+      'Comparing Zustand and Jotai for a medium-complexity community application. Performance benchmarks and developer experience included.',
+    votes: 42,
+    replyCount: 0,
+    viewCount: 267,
+    status: 'unanswered' as const,
+    tags: [
+      { label: 'React', color: 'bg-cyan-100 text-cyan-700' },
+      { label: 'State Management', color: 'bg-violet-100 text-violet-700' },
+    ],
+    author: { name: 'Liam Nguyen', initials: 'LN' },
+    createdAt: '8h ago',
+  },
+  {
+    id: '6',
+    title: 'Building a plugin system with module manifests',
+    excerpt:
+      'How we designed a declarative module manifest system that lets users scaffold apps with only the features they need. Patterns and lessons learned.',
+    votes: 67,
+    replyCount: 19,
+    viewCount: 1204,
+    status: 'hot' as const,
+    tags: [
+      { label: 'Architecture', color: 'bg-orange-100 text-orange-700' },
+      { label: 'Plugins', color: 'bg-pink-100 text-pink-700' },
+    ],
+    author: { name: 'Emma Wilson', initials: 'EW' },
+    createdAt: '12h ago',
+  },
+]
+
+const MOCK_PROFILE_ACTIVITY = [
+  {
+    id: '1',
+    type: 'reply' as const,
+    text: 'Replied to',
+    target: 'How to implement real-time notifications with SSE?',
+    time: '2h ago',
+  },
+  {
+    id: '2',
+    type: 'topic' as const,
+    text: 'Created topic',
+    target: 'Best practices for WebSocket reconnection logic',
+    time: '5h ago',
+  },
+  {
+    id: '3',
+    type: 'like' as const,
+    text: 'Liked',
+    target: 'Type-safe API routes with Hono RPC — a complete guide',
+    time: '8h ago',
+  },
+  {
+    id: '4',
+    type: 'reply' as const,
+    text: 'Replied to',
+    target: 'Deploying Hono apps to Cloudflare Workers with D1',
+    time: '1d ago',
+  },
+  {
+    id: '5',
+    type: 'topic' as const,
+    text: 'Created topic',
+    target: 'Zustand vs Jotai — which state manager for community apps?',
+    time: '2d ago',
+  },
+  {
+    id: '6',
+    type: 'like' as const,
+    text: 'Liked',
+    target: 'Building a plugin system with module manifests',
+    time: '3d ago',
+  },
+  {
+    id: '7',
+    type: 'reply' as const,
+    text: 'Replied to',
+    target: 'How to set up CI/CD for monorepo projects',
+    time: '4d ago',
+  },
+  {
+    id: '8',
+    type: 'topic' as const,
+    text: 'Created topic',
+    target: 'Tailwind CSS v4 migration guide and tips',
+    time: '5d ago',
+  },
+]
+
+const getTopicsRoute = createRoute({
+  method: 'get',
+  path: '/topics',
+  responses: {
+    200: successResponse(TopicsResponseSchema, 'List community topics'),
+  },
+})
+
+const getPopularTopicsRoute = createRoute({
+  method: 'get',
+  path: '/topics/popular',
+  responses: {
+    200: successResponse(TopicsResponseSchema, 'Popular topics'),
+  },
+})
+
+const getProfileRoute = createRoute({
+  method: 'get',
+  path: '/profile',
+  responses: {
+    200: successResponse(ProfileResponseSchema, 'User profile'),
+  },
+})
+
+export const topicsRoutes = new OpenAPIHono()
+  .openapi(getTopicsRoute, async c => {
+    return c.json({ success: true as const, data: MOCK_TOPICS })
+  })
+  .openapi(getPopularTopicsRoute, async c => {
+    const popular = [...MOCK_TOPICS].sort((a, b) => b.votes - a.votes)
+    return c.json({ success: true as const, data: popular })
+  })
+  .openapi(getProfileRoute, async c => {
+    return c.json({
+      success: true as const,
+      data: {
+        stats: { topics: 12, replies: 48, likes: 156 },
+        activity: MOCK_PROFILE_ACTIVITY,
+      },
+    })
+  })

package/template/src/server/module-content/services/content-service.ts

@@ -11,10 +11,12 @@ import { contents, type ContentTable } from '@server/db/schema'
 import { toISOString } from '@server/utils/date'
 import { randomDate, randomElement } from '@server/utils/generate'
 import { parseModuleId } from '@server/utils/id-helpers'
+// @framework-import ISR 缓存失效，内容变更时清除页面缓存
+import { purgeContentPages } from '@server/core/isr-invalidation'
 
 export async function seedContentsIfEmpty(): Promise<void> {
   const db = await getDb()
-  const existing = await db.select().from(contents).all()
+  const existing = await db.select().from(contents)
   if (existing.length === 0) {
     const CATEGORIES: ContentCategory[] = ['article', 'announcement', 'tutorial', 'news', 'policy']
     const STATUSES: ContentStatus[] = ['draft', 'published', 'archived']
@@ -48,7 +50,9 @@ export async function seedContentsIfEmpty(): Promise<void> {
 
       await db.insert(contents).values({
         title: TITLES[i % TITLES.length],
-        body: `这是${TITLES[i % TITLES.length]}的详细内容。这里包含了完整的文章内容，用户可以阅读和学习相关知识。`,
+        body: `这是${
+          TITLES[i % TITLES.length]
+        }的详细内容。这里包含了完整的文章内容，用户可以阅读和学习相关知识。`,
         category,
         status,
         author: randomElement(AUTHORS),
@@ -173,6 +177,9 @@ export async function updateContent(id: string, data: UpdateContentInput): Promi
   const result = await db.update(contents).set(updateData).where(eq(contents.id, numId)).returning()
 
   if (result.length === 0) return null
+  purgeContentPages().catch(e => {
+    console.warn('ISR content pages purge failed after update:', e)
+  })
   return mapContentRow(result[0])
 }
 
@@ -183,6 +190,9 @@ export async function deleteContent(id: string): Promise<{ success: boolean; mes
 
   const result = await db.delete(contents).where(eq(contents.id, numId)).returning()
   if (result.length === 0) return { success: false, message: '内容不存在' }
+  purgeContentPages().catch(e => {
+    console.warn('ISR content pages purge failed after delete:', e)
+  })
   return { success: true, message: '内容已删除' }
 }
 
@@ -202,6 +212,9 @@ export async function publishContent(id: string): Promise<Content | null> {
     .where(eq(contents.id, numId))
     .returning()
 
+  purgeContentPages().catch(e => {
+    console.warn('ISR content pages purge failed after publish:', e)
+  })
   return mapContentRow(result[0])
 }
 
@@ -220,5 +233,8 @@ export async function archiveContent(id: string): Promise<Content | null> {
     .where(eq(contents.id, numId))
     .returning()
 
+  purgeContentPages().catch(e => {
+    console.warn('ISR content pages purge failed after archive:', e)
+  })
   return mapContentRow(result[0])
 }

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

@@ -17,6 +17,7 @@ import {
   UpdateDisputeSchema,
   DisputeListSchema,
   ResolveDisputeSchema,
+  DeleteResultSchema,
 } from '@shared/modules/dispute'
 import { NotFoundError, BusinessError } from '@server/utils/app-error'
 
@@ -91,7 +92,7 @@ const deleteRoute = createRoute({
   middleware: [authMiddleware({ requiredPermissions: [Permission.DISPUTE_DELETE] })],
   request: idRequest,
   responses: {
-    200: successResponse(DisputeSchema, 'Delete dispute'),
+    200: successResponse(DeleteResultSchema, 'Delete dispute'),
     401: errorResponse('Unauthorized'),
     403: errorResponse('Forbidden'),
     404: errorResponse('Dispute not found'),

package/template/src/server/module-dispute/services/dispute-service.ts

@@ -15,7 +15,7 @@ import { parseModuleId } from '@server/utils/id-helpers'
 
 export async function seedDisputesIfEmpty(): Promise<void> {
   const db = await getDb()
-  const existing = await db.select().from(disputes).all()
+  const existing = await db.select().from(disputes)
   if (existing.length === 0) {
     const DISPUTE_TYPES: DisputeType[] = [
       'refund',

package/template/src/server/module-notifications/__tests__/sse-rpc.test.ts

@@ -13,8 +13,8 @@ setRuntimeAdapter(getNodeRuntimeAdapter())
 let sseTestContext: { port: number; close: () => Promise<void> }
 let client: ReturnType<typeof createTestClient>
 
-function connectSSE() {
-  const conn = client.api.notifications.stream.$sse()
+async function connectSSE() {
+  const conn = await client.api.notifications.stream.$sse()
   return conn as unknown as SSEClientImpl<AppSSEProtocol>
 }
 
@@ -44,7 +44,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
 
   describe('GET /api/notifications/stream via $sse()', () => {
     it('should use patched $sse() method for type-safe SSE connection', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       expect(['connecting', 'open', 'closed']).toContain(conn.status)
 
@@ -83,7 +83,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
     })
 
     it('should receive typed notification events', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       const receivedNotifications: AppSSEProtocol['events']['notification'][] = []
 
@@ -110,7 +110,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
     })
 
     it('should receive typed ping events', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       const receivedPings: AppSSEProtocol['events']['ping'][] = []
 
@@ -130,7 +130,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
     })
 
     it('should receive typed connected events', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       const receivedConnected: AppSSEProtocol['events']['connected'][] = []
 
@@ -150,7 +150,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
     })
 
     it('should handle connection status changes', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       const statusHistory: ('connecting' | 'open' | 'closed')[] = []
 
@@ -170,7 +170,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
     })
 
     it('should handle errors gracefully', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       const unsubscribe = conn.onError((error: Error) => {
         console.error('SSE error:', error)
@@ -187,7 +187,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
 
   describe('Error Scenarios', () => {
     it('should handle connection abort during event reception', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       const receivedEvents: unknown[] = []
       const unsubscribe = conn.on('notification', (event: unknown) => {
@@ -206,7 +206,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
     })
 
     it('should handle multiple abort calls gracefully', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       await new Promise(resolve => setTimeout(resolve, 500))
 
@@ -218,7 +218,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
     })
 
     it('should handle unsubscribe before connection close', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       const unsubscribe = conn.on('notification', () => {})
 
@@ -232,7 +232,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
     })
 
     it('should handle error events', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       let errorReceived = false
       const unsubscribe = conn.onError((error: Error) => {
@@ -253,7 +253,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
     })
 
     it('should handle non-existent event type gracefully', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       let received = false
       const unsubscribe = conn.on('nonExistentEvent' as 'notification', () => {
@@ -273,7 +273,7 @@ describe('SSE Routes with Patched $sse() RPC Method', () => {
     })
 
     it('should test error assertion pattern', async () => {
-      const conn = connectSSE()
+      const conn = await connectSSE()
 
       await new Promise(resolve => setTimeout(resolve, 500))
 

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

@@ -18,6 +18,30 @@ import {
 import { NotFoundError } from '@server/utils/app-error'
 import { getRuntimeAdapter } from '@server/core/runtime'
 
+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 streamRoute = createRoute({
   method: 'get',
   path: '/notifications/stream',
@@ -126,12 +150,10 @@ const deleteRoute = createRoute({
 
 export const notificationRoutes = new OpenAPIHono()
   .openapi(streamRoute, async c => {
-    // In Cloudflare environment, route SSE to Durable Object for proper broadcast support
     const env = c.env as { REALTIME_DO?: DurableObjectNamespace } | undefined
     if (env?.REALTIME_DO) {
       const id = env.REALTIME_DO.idFromName('global')
       const stub = env.REALTIME_DO.get(id)
-      // Forward the SSE request to the Durable Object
       const doRequest = new Request(c.req.url, {
         method: c.req.method,
         headers: c.req.raw.headers,
@@ -139,13 +161,17 @@ export const notificationRoutes = new OpenAPIHono()
       return stub.fetch(doRequest)
     }
 
-    // Fallback for Node environment
-    const adapter = getRuntimeAdapter()
-    if (adapter.handleSSERequest) {
-      const response = await adapter.handleSSERequest()
-      return response
+    try {
+      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()
   })
   .openapi(listRoute, async c => {
     const query = c.req.valid('query')

package/template/src/server/module-order/__tests__/order-route.test.ts

@@ -65,8 +65,18 @@ describe('Order Routes', () => {
     it('should filter orders by both status and customerName', async () => {
       const client = createTestClient(undefined, { headers: authHeaders })
 
+      const createRes = await client.api['orders'].$post({
+        json: {
+          customerName: 'Filter Test',
+          customerEmail: 'filter@example.com',
+          productName: 'Filter Product',
+          amount: 100,
+        },
+      })
+      expect(createRes.status).toBe(201)
+
       const res = await client.api['orders'].$get({
-        query: { status: 'pending', customerName: '李四' },
+        query: { status: 'pending', customerName: 'Filter Test' },
       })
       expect(res.status).toBe(200)
 
@@ -76,7 +86,7 @@ describe('Order Routes', () => {
         expect(Array.isArray(data.data)).toBe(true)
         data.data.forEach((order: { status: string; customerName: string }) => {
           expect(order.status).toBe('pending')
-          expect(order.customerName).toContain('李四')
+          expect(order.customerName).toContain('Filter Test')
         })
       }
     })
@@ -84,6 +94,16 @@ describe('Order Routes', () => {
     it('should return empty array when no orders match filter', async () => {
       const client = createTestClient(undefined, { headers: authHeaders })
 
+      const createRes = await client.api['orders'].$post({
+        json: {
+          customerName: 'Exists Test',
+          customerEmail: 'exists@example.com',
+          productName: 'Exists Product',
+          amount: 100,
+        },
+      })
+      expect(createRes.status).toBe(201)
+
       const res = await client.api['orders'].$get({
         query: { customerName: 'NonExistentCustomer12345' },
       })

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

@@ -7,6 +7,16 @@ const orderManifest: ModuleManifest = {
   dependsOn: ['permission'],
 
   routes: {
+    client: [
+      {
+        importPath: './routes/cart-routes',
+        exportName: 'cartRoutes',
+      },
+      {
+        importPath: './routes/orders-mock-routes',
+        exportName: 'ordersMockRoutes',
+      },
+    ],
     admin: [
       {
         importPath: './routes/order-routes',
@@ -19,6 +29,11 @@ const orderManifest: ModuleManifest = {
     path: 'order',
   },
 
+  clientPages: [
+    { name: 'CartPage', route: '/cart' },
+    { name: 'OrdersPage', route: '/orders' },
+  ],
+
   adminPages: [{ name: 'OrdersPage', route: '/orders', requiredPermission: 'ORDER_VIEW' }],
 
   dbSchemas: {

package/template/src/server/module-order/routes/cart-routes.ts

@@ -0,0 +1,103 @@
+import { createRoute } from '@hono/zod-openapi'
+import { OpenAPIHono } from '@hono/zod-openapi'
+import { successResponse, errorResponse } from '@server/utils/route-helpers'
+import { z } from '@hono/zod-openapi'
+import {
+  CartItemSchema,
+  CartResponseSchema,
+  AddCartItemSchema,
+  RemoveCartItemResponseSchema,
+} from '@shared/schemas'
+
+const SHIPPING_THRESHOLD = 50
+const TAX_RATE = 0.08
+
+const MOCK_CART_ITEMS = [
+  {
+    id: 1,
+    name: 'Wireless Headphones',
+    variant: 'Black',
+    price: 79.99,
+    quantity: 1,
+    color: '#374151',
+  },
+  {
+    id: 2,
+    name: 'Organic Cotton T-Shirt',
+    variant: 'Medium / Sage',
+    price: 34.99,
+    quantity: 2,
+    color: '#6ee7b7',
+  },
+  {
+    id: 3,
+    name: 'Ceramic Travel Mug',
+    variant: 'Amber / 350ml',
+    price: 24.99,
+    quantity: 1,
+    color: '#f59e0b',
+  },
+]
+
+function computeSummary(items: typeof MOCK_CART_ITEMS) {
+  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+  const shipping = subtotal >= SHIPPING_THRESHOLD ? 0 : 5.99
+  const tax = subtotal * TAX_RATE
+  const total = subtotal + shipping + tax
+  const totalItems = items.reduce((sum, item) => sum + item.quantity, 0)
+  return { subtotal, shipping, tax, total, totalItems }
+}
+
+const getCartRoute = createRoute({
+  method: 'get',
+  path: '/cart',
+  responses: {
+    200: successResponse(CartResponseSchema, 'Get cart'),
+  },
+})
+
+const addCartItemRoute = createRoute({
+  method: 'post',
+  path: '/cart/items',
+  request: {
+    body: {
+      content: {
+        'application/json': { schema: AddCartItemSchema },
+      },
+    },
+  },
+  responses: {
+    201: successResponse(CartItemSchema, 'Item added to cart'),
+    400: errorResponse('Invalid input'),
+  },
+})
+
+const removeCartItemRoute = createRoute({
+  method: 'delete',
+  path: '/cart/items/{id}',
+  request: {
+    params: z.object({ id: z.string() }),
+  },
+  responses: {
+    200: successResponse(RemoveCartItemResponseSchema, 'Item removed'),
+    404: errorResponse('Item not found'),
+  },
+})
+
+export const cartRoutes = new OpenAPIHono()
+  .openapi(getCartRoute, async c => {
+    const summary = computeSummary(MOCK_CART_ITEMS)
+    return c.json({ success: true as const, data: { items: MOCK_CART_ITEMS, summary } })
+  })
+  .openapi(addCartItemRoute, async c => {
+    const body = c.req.valid('json')
+    return c.json({ success: true as const, data: body }, 201)
+  })
+  .openapi(removeCartItemRoute, async c => {
+    const { id } = c.req.valid('param')
+    const exists = MOCK_CART_ITEMS.some(item => String(item.id) === id)
+    if (!exists) {
+      return c.json({ success: false as const, error: 'Item not found' }, 404)
+    }
+    return c.json({ success: true as const, data: { removedId: id } })
+  })