create-fullstack-scaffold 0.1.0

package/template/.claude/rules/32-client-state-zustand.md

@@ -0,0 +1,324 @@
+---
+paths: src/client/stores/**/*.ts
+---
+
+# Zustand 状态管理规范
+
+## 📁 目录结构
+
+```
+src/client/stores/
+├── todoStore.ts           # Todo 状态管理
+├── chatWSStore.ts         # Chat WebSocket 状态管理
+├── notificationStore.ts   # Notification 状态管理
+└── __tests__/             # Store 测试
+    └── todoStore.test.ts
+```
+
+## 🎯 Store 设计原则
+
+### 1. 使用共享类型
+
+```typescript
+// ✅ 正确 - 使用共享类型
+import type { Item, CreateItemInput } from '@shared/schemas'
+
+interface ItemState {
+  items: Item[]
+  fetchItems: () => Promise<void>
+  createItem: (input: CreateItemInput) => Promise<void>
+}
+
+// ❌ 错误 - 重复定义类型
+interface ItemState {
+  items: Array<{
+    id: number
+    name: string
+  }>
+}
+```
+
+**ESLint 规则**: `prefer-shared-types`
+
+**路径**: `src/client/stores/**/*.ts`
+
+### 2. Store 结构
+
+```typescript
+import { create } from 'zustand'
+import { apiClient } from '@client/services/apiClient'
+import type { Item, CreateItemInput } from '@shared/schemas'
+
+interface ItemState {
+  items: Item[]
+  loading: boolean
+  error: string | null
+
+  fetchItems: () => Promise<void>
+  createItem: (input: CreateItemInput) => Promise<void>
+  clearError: () => void
+}
+
+export const useItemStore = create<ItemState>((set, get) => ({
+  items: [],
+  loading: false,
+  error: null,
+
+  fetchItems: async () => {
+    set({ loading: true, error: null })
+    try {
+      const response = await apiClient.api.items.$get()
+      const result = await response.json()
+      if (result.success) {
+        set({ items: result.data, loading: false })
+      }
+    } catch (error) {
+      set({ error: 'Failed to fetch items', loading: false })
+    }
+  },
+
+  createItem: async (input: CreateItemInput) => {
+    try {
+      const response = await apiClient.api.items.$post({ json: input })
+      const result = await response.json()
+      if (result.success) {
+        set(state => ({ items: [...state.items, result.data] }))
+      }
+    } catch (error) {
+      set({ error: 'Failed to create item' })
+    }
+  },
+
+  clearError: () => set({ error: null }),
+}))
+```
+
+## 🔌 WebSocket Store 集成
+
+### WebSocket 状态管理
+
+```typescript
+import { create } from 'zustand'
+import { apiClient } from '@client/services/apiClient'
+import type { WSClient, WSStatus, ChatProtocol } from '@shared/schemas'
+
+interface WSMessage {
+  type: string
+  payload: unknown
+  timestamp?: number
+}
+
+interface WSState {
+  status: WSStatus
+  messages: WSMessage[]
+
+  connect: () => void
+  disconnect: () => void
+  echo: (params: { message: string }) => Promise<void>
+  clearMessages: () => void
+}
+
+let wsClient: WSClient<ChatProtocol> | null = null
+
+export const useChatWsStore = create<WSState>((set, get) => ({
+  status: 'closed',
+  messages: [],
+
+  connect: () => {
+    if (wsClient) return
+
+    wsClient = apiClient.api.chat.ws.$ws()
+
+    if (!wsClient) return
+
+    wsClient.onStatusChange((newStatus: WSStatus) => {
+      set({ status: newStatus })
+    })
+
+    wsClient.on('notification', payload => {
+      set(state => ({
+        messages: [...state.messages, { type: 'notification', payload }],
+      }))
+    })
+  },
+
+  disconnect: () => {
+    if (wsClient) {
+      wsClient.close()
+      wsClient = null
+      set({ status: 'closed' })
+    }
+  },
+
+  echo: async params => {
+    if (!wsClient || get().status !== 'open') return
+    try {
+      await wsClient.call('echo', params)
+    } catch (error) {
+      console.error('Echo failed:', error)
+    }
+  },
+
+  clearMessages: () => {
+    set({ messages: [] })
+  },
+}))
+```
+
+## 🎣 组件中使用 Store
+
+### 选择性订阅
+
+```typescript
+// ✅ 正确 - 选择性订阅
+export const ItemList: React.FC = () => {
+  const items = useItemStore(state => state.items)
+  const loading = useItemStore(state => state.loading)
+  const fetchItems = useItemStore(state => state.fetchItems)
+
+  useEffect(() => {
+    fetchItems()
+  }, [fetchItems])
+
+  if (loading) return <div>Loading...</div>
+
+  return (
+    <div>
+      {items.map(item => (
+        <ItemCard key={item.id} item={item} />
+      ))}
+    </div>
+  )
+}
+
+// ❌ 错误 - 订阅整个 Store
+export const ItemList: React.FC = () => {
+  const { items, loading, fetchItems } = useItemStore()  // ❌ 任何状态变化都会重渲染
+
+  // ...
+}
+```
+
+## 🧪 测试规范
+
+### Store 测试
+
+```typescript
+// src/client/stores/__tests__/itemStore.test.ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { useItemStore } from '../itemStore'
+
+describe('itemStore', () => {
+  beforeEach(() => {
+    useItemStore.setState({ items: [], loading: false, error: null })
+  })
+
+  it('should have initial state', () => {
+    const state = useItemStore.getState()
+    expect(state.items).toEqual([])
+    expect(state.loading).toBe(false)
+    expect(state.error).toBeNull()
+  })
+
+  it('should fetch items', async () => {
+    const { fetchItems } = useItemStore.getState()
+    await fetchItems()
+
+    const state = useItemStore.getState()
+    expect(state.items.length).toBeGreaterThan(0)
+  })
+})
+```
+
+## 🚫 禁止事项
+
+### 1. 禁止直接调用 API
+
+```typescript
+// ❌ 错误 - 直接使用 fetch
+fetch('/api/items')
+  .then(res => res.json())
+  .then(data => set({ items: data }))
+
+// ✅ 正确 - 使用 apiClient
+const response = await apiClient.api.items.$get()
+const result = await response.json()
+if (result.success) {
+  set({ items: result.data })
+}
+```
+
+### 2. 禁止使用 any 类型
+
+```typescript
+// ❌ 错误 - 使用 any
+interface State {
+  items: any[]
+  createItem: (input: any) => Promise<void>
+}
+
+// ✅ 正确 - 使用明确类型
+interface State {
+  items: Item[]
+  createItem: (input: CreateItemInput) => Promise<void>
+}
+```
+
+### 3. 禁止在 Store 中定义组件
+
+```typescript
+// ❌ 错误 - 在 Store 中定义组件
+export const useItemStore = create((set) => ({
+  ItemComponent: () => <div>...</div>,  // ❌
+}))
+
+// ✅ 正确 - Store 只管理状态
+export const useItemStore = create((set) => ({
+  items: [],
+  fetchItems: async () => { ... },
+}))
+```
+
+## 📤 导出规范
+
+```typescript
+// ✅ 正确 - 命名导出
+export const useItemStore = create<ItemState>((set, get) => ({ ... }))
+
+// ❌ 错误 - 默认导出
+export default create<ItemState>((set, get) => ({ ... }))
+```
+
+## 🚫 Anti-Patterns
+
+```typescript
+// ❌ 不要订阅整个 Store
+const { items, loading, fetchItems } = useItemStore()
+
+// ✅ 应该选择性订阅
+const items = useItemStore(state => state.items)
+const loading = useItemStore(state => state.loading)
+const fetchItems = useItemStore(state => state.fetchItems)
+
+// ❌ 不要在 Store 中直接使用 fetch
+fetch('/api/items')
+
+// ✅ 应该使用 apiClient
+const response = await apiClient.api.items.$get()
+
+// ❌ 不要使用 any 类型
+interface State {
+  items: any[]
+}
+
+// ✅ 应该使用明确类型
+interface State {
+  items: Item[]
+}
+```
+
+## 📚 相关文档
+
+- [Client Service 规范](./31-client-services.md) - API 客户端使用规范
+- [Client 组件规范](./30-client-components.md) - 组件开发规范
+- [Testing 规范](./60-testing-standards.md) - 测试编写规范

package/template/.claude/rules/33-client-app-entry.md

@@ -0,0 +1,276 @@
+---
+paths: src/client/App.tsx
+---
+
+# App 入口规范
+
+## 🎯 核心原则
+
+`App.tsx` 是应用的**路由入口**，应该保持**极简**，只负责路由配置。
+
+## 📁 文件职责
+
+### App.tsx 的职责
+
+- ✅ 配置路由（BrowserRouter, Routes, Route）
+- ✅ 引用 Layout 组件
+- ✅ 定义路由映射
+
+### App.tsx 不应该做的事
+
+- ❌ 定义布局组件（Navigation, Footer 等）
+- ❌ 定义业务逻辑
+- ❌ 包含复杂的 JSX 结构
+- ❌ 定义样式
+
+## 🏗️ 推荐结构
+
+### 标准结构
+
+```
+src/client/
+├── App.tsx              # 路由入口（极简）
+├── Layout.tsx           # 布局组件
+├── components/          # 共享组件
+│   ├── Navigation.tsx
+│   └── Footer.tsx
+└── pages/               # 页面组件
+    ├── TodoPage.tsx
+    └── NotificationPage.tsx
+```
+
+### App.tsx 示例
+
+```typescript
+// ✅ 正确 - 极简的路由入口
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
+import { Layout } from './Layout'
+import { TodoPage } from './pages/TodoPage'
+import { NotificationPage } from './pages/NotificationPage'
+import { WebSocketPage } from './pages/WebSocketPage'
+
+export const App: React.FC = () => {
+  return (
+    <BrowserRouter>
+      <Layout>
+        <Routes>
+          <Route path="/" element={<Navigate to="/todos" replace />} />
+          <Route path="/todos" element={<TodoPage />} />
+          <Route path="/notifications" element={<NotificationPage />} />
+          <Route path="/websocket" element={<WebSocketPage />} />
+        </Routes>
+      </Layout>
+    </BrowserRouter>
+  )
+}
+```
+
+## 📦 Layout 组件规范
+
+### Layout.tsx 示例
+
+```typescript
+// src/client/Layout.tsx
+import { ReactNode } from 'react'
+import { Navigation } from './components/Navigation'
+import { Footer } from './components/Footer'
+
+interface LayoutProps {
+  children: ReactNode
+}
+
+export const Layout: React.FC<LayoutProps> = ({ children }) => {
+  return (
+    <div className="min-h-screen bg-gray-50" data-testid="app-container">
+      <Navigation />
+      <main className="py-8" data-testid="app-main">
+        {children}
+      </main>
+      <Footer />
+    </div>
+  )
+}
+```
+
+## 🚫 Anti-Patterns
+
+```typescript
+// ❌ 错误 - App.tsx 包含布局逻辑
+export const App: React.FC = () => {
+  return (
+    <BrowserRouter>
+      <div className="min-h-screen bg-gray-50">
+        <nav className="bg-white border-b">
+          {/* 导航逻辑 */}
+        </nav>
+        <main className="py-8">
+          <Routes>
+            {/* 路由配置 */}
+          </Routes>
+        </main>
+        <footer className="py-8">
+          {/* 页脚逻辑 */}
+        </footer>
+      </div>
+    </BrowserRouter>
+  )
+}
+
+// ✅ 正确 - App.tsx 只负责路由
+export const App: React.FC = () => {
+  return (
+    <BrowserRouter>
+      <Layout>
+        <Routes>
+          <Route path="/" element={<Navigate to="/todos" replace />} />
+          <Route path="/todos" element={<TodoPage />} />
+        </Routes>
+      </Layout>
+    </BrowserRouter>
+  )
+}
+
+// ❌ 错误 - App.tsx 定义组件
+const Navigation: React.FC = () => {
+  return <nav>...</nav>
+}
+
+const Footer: React.FC = () => {
+  return <footer>...</footer>
+}
+
+export const App: React.FC = () => {
+  return (
+    <BrowserRouter>
+      <Navigation />
+      <Routes>...</Routes>
+      <Footer />
+    </BrowserRouter>
+  )
+}
+
+// ✅ 正确 - 组件放在独立文件中
+// src/client/components/Navigation.tsx
+export const Navigation: React.FC = () => {
+  return <nav>...</nav>
+}
+
+// src/client/components/Footer.tsx
+export const Footer: React.FC = () => {
+  return <footer>...</footer>
+}
+
+// src/client/Layout.tsx
+import { Navigation } from './components/Navigation'
+import { Footer } from './components/Footer'
+
+export const Layout: React.FC<LayoutProps> = ({ children }) => {
+  return (
+    <div>
+      <Navigation />
+      <main>{children}</main>
+      <Footer />
+    </div>
+  )
+}
+```
+
+## 📝 路由配置规范
+
+### 路由映射
+
+```typescript
+// ✅ 正确 - 使用路由映射
+type RouteKey = 'todos' | 'notifications' | 'websocket'
+
+const routes: Record<RouteKey, { path: string; element: React.ReactNode }> = {
+  todos: { path: '/todos', element: <TodoPage /> },
+  notifications: { path: '/notifications', element: <NotificationPage /> },
+  websocket: { path: '/websocket', element: <WebSocketPage /> },
+}
+
+export const App: React.FC = () => {
+  return (
+    <BrowserRouter>
+      <Layout>
+        <Routes>
+          <Route path="/" element={<Navigate to="/todos" replace />} />
+          {Object.values(routes).map(route => (
+            <Route key={route.path} path={route.path} element={route.element} />
+          ))}
+        </Routes>
+      </Layout>
+    </BrowserRouter>
+  )
+}
+```
+
+### 默认路由
+
+```typescript
+// ✅ 正确 - 使用 Navigate 重定向
+<Route path="/" element={<Navigate to="/todos" replace />} />
+
+// ❌ 错误 - 使用组件作为默认路由
+<Route path="/" element={<TodoPage />} />
+```
+
+## 🎨 布局灵活性
+
+### 可调整的布局
+
+Layout 组件应该支持灵活调整：
+
+```typescript
+// src/client/Layout.tsx
+interface LayoutProps {
+  children: ReactNode
+  className?: string
+  showNavigation?: boolean
+  showFooter?: boolean
+}
+
+export const Layout: React.FC<LayoutProps> = ({
+  children,
+  className = '',
+  showNavigation = true,
+  showFooter = true,
+}) => {
+  return (
+    <div className={`min-h-screen bg-gray-50 ${className}`}>
+      {showNavigation && <Navigation />}
+      <main className="py-8">{children}</main>
+      {showFooter && <Footer />}
+    </div>
+  )
+}
+```
+
+### 使用示例
+
+```typescript
+// 默认布局
+<Layout>
+  <Routes>...</Routes>
+</Layout>
+
+// 自定义布局
+<Layout className="bg-white" showFooter={false}>
+  <Routes>...</Routes>
+</Layout>
+```
+
+## 📤 导出规范
+
+```typescript
+// ✅ 正确 - 命名导出
+export const App: React.FC = () => { ... }
+
+// ❌ 错误 - 默认导出
+export default function App() { ... }
+```
+
+## 📚 相关文档
+
+- [Client 组件规范](./30-client-components.md) - 组件开发规范
+- [Client 服务规范](./31-client-services.md) - API 客户端使用规范