create-fullstack-scaffold 0.1.0

package/template/.claude/hookify.check-duplicate-types.local.md

@@ -0,0 +1,287 @@
+---
+name: check-duplicate-types
+enabled: true
+event: file
+conditions:
+  - field: file_path
+    operator: regex_match
+    pattern: src/.*\.(ts|tsx)$
+  - field: new_text
+    operator: regex_match
+    pattern: ^(export\s+)?(type|interface)\s+\w+
+---
+
+⚠️ **检测到类型定义 - 请检查仓库中是否已存在相同类型**
+
+## 🎯 核心原则
+
+**不要重复定义类型！优先复用项目已有类型！**
+
+## 📦 项目已有类型一览
+
+### 从 `@shared/types` 导入（推荐）
+
+```typescript
+import type {
+  // Common API Types
+  ApiSuccess, // 成功响应包装
+  ApiError, // 错误响应
+  ApiResponse, // 统一响应类型
+
+  // Todo Types
+  TodoStatus, // 'pending' | 'in_progress' | 'completed'
+  Todo, // 完整的 Todo 对象
+  CreateTodoInput, // 创建 Todo 的输入
+  UpdateTodoInput, // 更新 Todo 的输入
+
+  // Notification Types
+  NotificationType, // 'info' | 'warning' | 'success' | 'error'
+  AppNotification, // 完整的通知对象
+  CreateNotificationInput,
+  NotificationListQuery,
+  SSEEvent,
+
+  // WebSocket Types
+  AppWSProtocol, // WebSocket 协议定义
+  WSMessage, // WebSocket 消息
+} from '@shared/types'
+```
+
+### 从 `@shared/schemas` 导入（包含运行时验证）
+
+```typescript
+import {
+  // Schemas（用于运行时验证）
+  TodoSchema,
+  CreateTodoSchema,
+  UpdateTodoSchema,
+  NotificationSchema,
+
+  // Types（自动推断）
+  type Todo,
+  type CreateTodoInput,
+  type UpdateTodoInput,
+} from '@shared/schemas'
+```
+
+### 从数据库 Schema 推断
+
+```typescript
+import { todos, notifications } from '@server/db/schema'
+
+// 从表定义推断类型
+type TodoTable = typeof todos.$inferSelect // 查询结果类型
+type NewTodo = typeof todos.$inferInsert // 插入数据类型
+
+type NotificationTable = typeof notifications.$inferSelect
+type NewNotification = typeof notifications.$inferInsert
+```
+
+## 🔍 如何查找已有类型
+
+### 方法 1：使用 IDE 搜索
+
+在 VS Code 中：
+
+- `Cmd/Ctrl + T` 输入类型名称
+- `Cmd/Ctrl + Shift + F` 全局搜索 `type YourTypeName`
+
+### 方法 2：查看类型定义文件
+
+- **共享类型**：`src/shared/core/` 和 `src/shared/modules/`
+- **Schema 定义**：`src/shared/schemas/*.ts`
+- **数据库 Schema**：`src/server/db/schema/*.ts`
+
+### 方法 3：使用 TypeScript 编译器
+
+```bash
+# 查找所有类型定义
+grep -r "^export type\|^export interface" src/shared/
+```
+
+## ✅ 正确示例
+
+### 示例 1：使用已有类型
+
+```typescript
+// ❌ 错误 - 重复定义
+interface Todo {
+  id: number
+  title: string
+  status: 'pending' | 'completed'
+}
+
+// ✅ 正确 - 导入已有类型
+import type { Todo } from '@shared/types'
+
+async function getTodo(id: number): Promise<Todo> {
+  // ...
+}
+```
+
+### 示例 2：扩展现有类型
+
+```typescript
+// ❌ 错误 - 重复定义相似类型
+interface TodoPreview {
+  id: number
+  title: string
+}
+
+// ✅ 正确 - 使用 Pick 提取需要的字段
+import type { Todo } from '@shared/types'
+type TodoPreview = Pick<Todo, 'id' | 'title'>
+
+// ✅ 正确 - 使用 Omit 排除字段
+type TodoWithoutTimestamps = Omit<Todo, 'createdAt' | 'updatedAt'>
+
+// ✅ 正确 - 使用 Partial 使字段可选
+type PartialTodo = Partial<Todo>
+```
+
+### 示例 3：组件 Props 类型
+
+```typescript
+// ❌ 错误 - 定义重复的 Props 类型
+interface TodoItemProps {
+  todo: {
+    id: number
+    title: string
+    status: string
+  }
+}
+
+// ✅ 正确 - 复用已有类型
+import type { Todo } from '@shared/types'
+
+interface TodoItemProps {
+  todo: Todo
+  onToggle: (id: number) => void
+}
+```
+
+### 示例 4：API 响应类型
+
+```typescript
+// ❌ 错误 - 重新定义响应类型
+interface TodoListResponse {
+  success: boolean
+  data: Todo[]
+}
+
+// ✅ 正确 - 使用通用响应类型
+import type { ApiResponse, Todo } from '@shared/types'
+
+type TodoListResponse = ApiResponse<Todo[]>
+```
+
+## 🛠️ 类型复用工具
+
+### TypeScript 内置工具类型
+
+```typescript
+import type { Todo, CreateTodoInput } from '@shared/types'
+
+// Partial - 所有字段可选
+type UpdateData = Partial<Todo>
+
+// Required - 所有字段必需
+type CompleteTodo = Required<Todo>
+
+// Pick - 选择部分字段
+type TodoPreview = Pick<Todo, 'id' | 'title' | 'status'>
+
+// Omit - 排除部分字段
+type TodoWithoutId = Omit<Todo, 'id'>
+
+// Record - 键值对
+type TodoMap = Record<number, Todo>
+
+// Extract/Exclude - 条件类型
+type PendingTodo = Extract<Todo, { status: 'pending' }>
+```
+
+### 组合使用
+
+```typescript
+import type { Todo, CreateTodoInput } from '@shared/types'
+
+// 创建带时间戳的类型
+type TodoWithTimestamp = Todo & { timestamp: number }
+
+// 创建只读类型
+type ReadonlyTodo = Readonly<Todo>
+
+// 嵌套 Pick
+type TodoStatusInfo = Pick<Todo, 'id' | 'status'>
+```
+
+## 📚 类型定义位置速查
+
+| 类型类别      | 定义位置                                    | 导入路径                          |
+| ------------- | ------------------------------------------- | --------------------------------- |
+| 共享业务类型  | `src/shared/core/` 和 `src/shared/modules/` | `@shared/core`, `@shared/modules` |
+| Schema + 类型 | `src/shared/schemas/*.ts`                   | `@shared/schemas`                 |
+| 数据库表类型  | `src/server/db/schema/*.ts`                 | `@server/db/schema`               |
+| API 路由类型  | `src/server/index.ts`                       | `@server/index` (AppType)         |
+| 组件 Props    | 组件文件内定义                              | -                                 |
+| 页面状态      | Store 文件内定义                            | -                                 |
+
+## 🚫 常见错误
+
+### 错误 1：重复定义枚举类型
+
+```typescript
+// ❌ 错误 - 重复定义
+type Status = 'pending' | 'in_progress' | 'completed'
+
+// ✅ 正确
+import type { TodoStatus } from '@shared/types'
+```
+
+### 错误 2：重复定义 API 响应结构
+
+```typescript
+// ❌ 错误
+interface GetTodosResponse {
+  success: boolean
+  data: Todo[]
+}
+
+// ✅ 正确
+import type { ApiResponse, Todo } from '@shared/types'
+type GetTodosResponse = ApiResponse<Todo[]>
+```
+
+### 错误 3：重复定义数据库模型
+
+```typescript
+// ❌ 错误
+interface TodoModel {
+  id: number
+  title: string
+  // ...
+}
+
+// ✅ 正确 - 从 Schema 推断
+import { todos } from '@server/db/schema'
+type TodoModel = typeof todos.$inferSelect
+```
+
+## 💡 最佳实践
+
+1. **优先导入** - 永远先检查是否已有类型
+2. **使用工具类型** - 用 Pick/Omit/Partial 组合而非重新定义
+3. **Schema First** - 用 Zod Schema 定义类型，自动推断
+4. **单一来源** - 类型定义集中在 `shared/` 目录
+5. **文档化** - 复杂类型添加 JSDoc 注释
+
+## 🔗 相关文档
+
+- [API Type Inference Rules](./rules/10-api-type-inference.md)
+- [Shared Types Rules](./rules/40-shared-types.md)
+- [Server API Validation](./rules/20-server-api.md)
+
+---
+
+**记住：每次定义新类型前，先搜索仓库中是否已存在相同或相似的类型！**

package/template/.claude/hookify.check-test-assertions.local.md

@@ -0,0 +1,93 @@
+---
+name: check-test-assertions
+enabled: true
+event: file
+conditions:
+  - field: file_path
+    operator: regex_match
+    pattern: __tests__/.*\.test\.tsx?$
+  - field: new_text
+    operator: regex_match
+    pattern: expect\([^)]+\)\.(toBeTruthy|toBeFalsy|toBe)\((true|false|null|undefined)?\)
+---
+
+⚠️ **检测到简单的真值断言**
+
+测试标准要求验证具体数值，而非简单的 true/false/null 检查。
+
+**问题示例：**
+
+```typescript
+// ❌ 避免 - 过于简单，没有验证实际业务逻辑
+expect(result.success).toBe(true)
+expect(data.length).toBeGreaterThan(0)
+expect(todo.completed).toBe(true)
+expect(response).toBeTruthy()
+expect(error).toBeNull()
+```
+
+**推荐做法：**
+
+```typescript
+// ✅ 正确 - 验证具体的业务值
+it('应当创建新 Todo 并设置初始属性', async () => {
+  const todo = await createTodo({
+    title: 'Test Todo',
+    description: 'Test description',
+  })
+
+  // 验证 ID 生成
+  expect(todo.id).toBeGreaterThan(0)
+
+  // 验证所有字段
+  expect(todo.title).toBe('Test Todo')
+  expect(todo.description).toBe('Test description')
+  expect(todo.status).toBe('pending')
+
+  // 验证时间戳
+  expect(todo.createdAt).toBeLessThanOrEqual(Date.now())
+})
+
+// ✅ 正确 - 验证完整的对象结构
+it('应当返回正确的 API 响应', async () => {
+  const response = await request.get('/api/todos/1')
+
+  expect(response.status).toBe(200)
+  expect(response.body).toEqual({
+    success: true,
+    data: {
+      id: 1,
+      title: 'Buy groceries',
+      status: 'pending',
+      completed: false,
+    },
+  })
+})
+
+// ✅ 正确 - 验证数组内容
+it('应当返回 Todo 列表', async () => {
+  const { items, total } = await getTodos()
+
+  expect(items).toHaveLength(3)
+  expect(items[0].title).toBe('Buy groceries')
+  expect(items[1].title).toBe('Clean house')
+  expect(total).toBe(3)
+})
+```
+
+**断言数量要求：**
+
+- 每个测试必须包含 **2-3 个具体数值的断言**
+- 验证关键字段，而非仅验证存在性
+- 覆盖率目标：**>80%**
+
+**好的断言应该验证：**
+
+- 具体的字段值（字符串、数字、枚举）
+- 对象的完整结构
+- 数组的长度和元素内容
+- 时间戳的合理性
+- 业务逻辑的正确性
+
+**参考文档：**
+详细测试规范请查看 [Testing 规范](./rules/60-testing-standards.md)

package/template/.claude/hookify.remind-add-tests.local.md

@@ -0,0 +1,209 @@
+---
+name: remind-add-tests
+enabled: true
+event: file
+conditions:
+  - field: file_path
+    operator: regex_match
+    pattern: src/(client|server)/.*\.(ts|tsx)$
+  - field: file_path
+    operator: not_contains
+    pattern: __tests__
+  - field: file_path
+    operator: not_contains
+    pattern: .test.
+  - field: file_path
+    operator: not_contains
+    pattern: .spec.
+---
+
+📝 **新文件创建提醒：添加测试**
+
+检测到创建了新的源代码文件，请记得添加对应的测试文件。
+
+## 📂 测试文件位置规则
+
+### 客户端测试
+
+| 源文件位置                    | 测试文件位置                                 | 示例                                                 |
+| ----------------------------- | -------------------------------------------- | ---------------------------------------------------- |
+| `src/client/stores/*.ts`      | `src/client/stores/__tests__/*.test.ts`      | `todoStore.ts` → `__tests__/todoStore.test.ts`       |
+| `src/client/services/*.ts`    | `src/client/services/__tests__/*.test.ts`    | `apiClient.ts` → `__tests__/apiClient.test.ts`       |
+| `src/client/hooks/*.ts`       | `src/client/hooks/__tests__/*.test.ts`       | `useWebSocket.ts` → `__tests__/useWebSocket.test.ts` |
+| `src/client/components/*.tsx` | `src/client/components/__tests__/*.test.tsx` | `App.tsx` → `__tests__/App.test.tsx`                 |
+
+### 服务端测试
+
+| 源文件位置                          | 测试文件位置                              | 示例                                                 |
+| ----------------------------------- | ----------------------------------------- | ---------------------------------------------------- |
+| `src/server/module-*/services/*.ts` | `src/server/module-*/__tests__/*.test.ts` | `todo-service.ts` → `__tests__/todo-service.test.ts` |
+| `src/server/module-*/routes/*.ts`   | `src/server/module-*/__tests__/*.test.ts` | `todos-routes.ts` → `__tests__/todos-route.test.ts`  |
+| `src/server/utils/*.ts`             | `src/server/utils/__tests__/*.test.ts`    | `logger.ts` → `__tests__/logger.test.ts`             |
+
+### 集成测试
+
+| 测试类型     | 文件位置                                     | 用途                     |
+| ------------ | -------------------------------------------- | ------------------------ |
+| API 集成测试 | `src/server/__tests__/integration/*.test.ts` | 测试完整的 API 流程      |
+| E2E 测试     | `e2e/*.spec.ts`                              | 端到端测试（Playwright） |
+
+## 📝 测试文件模板
+
+### Store 测试模板
+
+```typescript
+// src/client/stores/__tests__/xxxStore.test.ts
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { useXxxStore } from '../xxxStore'
+
+describe('XxxStore', () => {
+  beforeEach(() => {
+    // 重置 store 状态
+    useXxxStore.setState({ ...initialState })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('应当正确初始化', () => {
+    const store = useXxxStore.getState()
+    expect(store.items).toEqual([])
+    expect(store.loading).toBe(false)
+  })
+
+  it('应当正确执行操作', async () => {
+    const { action } = useXxxStore.getState()
+    await action({ title: 'Test' })
+
+    const store = useXxxStore.getState()
+    expect(store.items).toHaveLength(1)
+    expect(store.items[0].title).toBe('Test')
+  })
+})
+```
+
+### Service 测试模板
+
+```typescript
+// src/server/module-*/__tests__/xxx-service.test.ts
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { XxxService } from '../services/xxx-service'
+
+describe('XxxService', () => {
+  let service: XxxService
+
+  beforeEach(() => {
+    service = new XxxService()
+  })
+
+  afterEach(() => {
+    // 清理资源
+  })
+
+  it('应当正确执行业务逻辑', async () => {
+    const result = await service.doSomething({ param: 'value' })
+
+    expect(result.id).toBeGreaterThan(0)
+    expect(result.param).toBe('value')
+    expect(result.createdAt).toBeInstanceOf(Date)
+  })
+})
+```
+
+### API Route 测试模板
+
+```typescript
+// src/server/module-*/__tests__/xxx-routes.test.ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import app from '../app'
+
+describe('Xxx Routes', () => {
+  beforeEach(async () => {
+    // 初始化测试数据
+  })
+
+  it('GET /api/xxx 应当返回列表', async () => {
+    const res = await app.request('/api/xxx')
+    const json = await res.json()
+
+    expect(res.status).toBe(200)
+    expect(json.success).toBe(true)
+    expect(json.data).toBeInstanceOf(Array)
+    expect(json.data[0].id).toBeDefined()
+  })
+
+  it('POST /api/xxx 应当创建新记录', async () => {
+    const res = await app.request('/api/xxx', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'Test' }),
+    })
+    const json = await res.json()
+
+    expect(res.status).toBe(201)
+    expect(json.success).toBe(true)
+    expect(json.data.title).toBe('Test')
+  })
+})
+```
+
+### Component 测试模板
+
+```typescript
+// src/client/components/__tests__/Xxx.test.tsx
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Xxx } from '../Xxx';
+
+describe('Xxx Component', () => {
+  it('应当正确渲染', () => {
+    render(<Xxx title="Test" />);
+
+    expect(screen.getByText('Test')).toBeInTheDocument();
+  });
+
+  it('应当响应交互', async () => {
+    const user = userEvent.setup();
+    render(<Xxx />);
+
+    await user.click(screen.getByRole('button'));
+    expect(screen.getByText('Clicked')).toBeInTheDocument();
+  });
+});
+```
+
+## 🧪 运行测试
+
+```bash
+# 运行相关测试（智能测试）
+npm run test:smart:staged
+
+# 运行所有测试
+npm run test:all
+
+# 运行特定文件的测试
+npm run test -- xxxStore.test.ts
+
+# 监听模式
+npm run test
+
+# 查看覆盖率
+npm run test:coverage
+```
+
+## ✅ 测试规范检查清单
+
+- [ ] 测试文件放在正确的 `__tests__/` 目录
+- [ ] 测试文件命名为 `*.test.ts` 或 `*.test.tsx`
+- [ ] 使用 `beforeEach` 和 `afterEach` 管理测试状态
+- [ ] 每个测试包含 2-3 个具体断言
+- [ ] 验证具体的业务值，而非简单的 true/false
+- [ ] 测试覆盖率 > 80%
+
+## 📚 参考文档
+
+详细测试规范请查看：[Testing 规范](./rules/60-testing-standards.md)
+
+**记住：新功能必须有对应的测试！**

package/template/.claude/hookify.remind-db-migration.local.md

@@ -0,0 +1,58 @@
+---
+name: remind-db-migration
+enabled: true
+event: file
+conditions:
+  - field: file_path
+    operator: regex_match
+    pattern: src/server/db/schema/.*\.ts$
+---
+
+💾 **数据库 Schema 已修改**
+
+检测到数据库 schema 文件的更改，请记得执行数据库迁移。
+
+**执行步骤：**
+
+```bash
+# 1. 生成迁移文件
+npm run db:generate
+
+# 2. 检查生成的迁移文件（在 drizzle/ 目录下）
+cat drizzle/0001_*.sql
+
+# 3. 执行迁移
+npm run db:migrate
+
+# 4. 验证迁移结果（可选）
+npm run db:studio
+```
+
+**Schema 文件位置：**
+
+- `src/server/db/schema/todos.ts` - Todo 表定义
+- `src/server/db/schema/notifications.ts` - Notification 表定义
+- `src/server/db/schema/index.ts` - Schema 导出
+
+**常见操作：**
+
+```typescript
+// 添加新字段
+export const todos = sqliteTable('todos', {
+  id: integer('id').primaryKey(),
+  title: text('title').notNull(),
+  // 新增字段
+  priority: text('priority', { enum: ['low', 'medium', 'high'] }).default('medium'),
+  createdAt: integer('created_at').notNull(),
+})
+
+// 添加索引
+export const todosIndex = index('todos_created_at_idx').on(todos.createdAt)
+```
+
+**注意事项：**
+
+- 生产环境迁移前先备份数据库
+- 检查迁移 SQL 是否符合预期
+- 团队协作时，迁移文件需要提交到版本控制
+- 使用 `db:studio` 可视化查看数据库结构

package/template/.claude/hookify.remind-run-tests.local.md

@@ -0,0 +1,52 @@
+---
+name: remind-run-tests
+enabled: true
+event: stop
+pattern: .*
+---
+
+✅ **完成前检查清单**
+
+在结束任务前，请确保完成以下检查：
+
+**代码质量检查：**
+
+- [ ] 类型检查通过：`npm run typecheck`
+- [ ] 代码格式化：`npm run lint`
+- [ ] 验证通过：`npm run validate:all`
+
+**测试检查：**
+
+- [ ] 运行智能测试：`npm run test:smart:staged`
+- [ ] 或运行完整测试：`npm run test:all`
+- [ ] 测试覆盖率：`npm run test:coverage` (目标 >80%)
+
+**数据库相关（如果修改了 schema）：**
+
+- [ ] 生成迁移文件：`npm run db:generate`
+- [ ] 执行迁移：`npm run db:migrate`
+
+**提交前检查：**
+
+- [ ] 检查暂存区：`git status`
+- [ ] 查看变更：`git diff --staged`
+- [ ] 提交信息符合规范（使用 Conventional Commits）
+
+**快速命令：**
+
+```bash
+# 一键验证
+npm run validate:all
+
+# 智能测试（仅运行相关测试）
+npm run test:smart:staged
+
+# 完整验证流程
+npm run typecheck && npm run lint && npm run test:smart:staged
+```
+
+**注意：**
+
+- E2E 测试不会在 pre-commit 中运行
+- 如需运行 E2E 测试：`npm run test:e2e`
+- 监听模式运行测试：`npm run test`