create-fullstack-scaffold 0.1.0

package/template/.claude/hookify.warn-any-type.local.md

@@ -0,0 +1,203 @@
+---
+name: warn-any-type
+enabled: true
+event: file
+conditions:
+  - field: file_path
+    operator: regex_match
+    pattern: src/.*\.(ts|tsx)$
+  - field: new_text
+    operator: regex_match
+    pattern: :\s*any\b|as\s+any\b
+---
+
+⚠️ **检测到 any 类型使用**
+
+使用 `any` 类型会绕过 TypeScript 的类型检查，可能导致运行时错误。
+
+**问题示例：**
+
+```typescript
+// ❌ 避免 - 使用 any 类型
+let data: any = fetchData();
+const result = response as any;
+function process(input: any): any { ... }
+```
+
+## 🎯 优先使用项目已有类型
+
+**重要原则：不要随意定义新类型，优先在项目中查找已有类型！**
+
+### 项目已有类型一览
+
+**从 `@shared/types` 导入：**
+
+```typescript
+import type {
+  // Common
+  ApiSuccess,
+  ApiError,
+  ApiResponse,
+  // Todos
+  TodoStatus, // 'pending' | 'in_progress' | 'completed'
+  Todo, // 完整的 Todo 对象
+  CreateTodoInput, // 创建 Todo 的输入
+  UpdateTodoInput, // 更新 Todo 的输入
+  // Notifications
+  NotificationType, // 'info' | 'warning' | 'success' | 'error'
+  AppNotification, // 完整的通知对象
+  CreateNotificationInput,
+  NotificationListQuery,
+  SSEEvent,
+} from '@shared/types'
+```
+
+**从 `@shared/schemas` 导入（推荐）：**
+
+```typescript
+import {
+  // Schemas（用于运行时验证）
+  TodoSchema,
+  CreateTodoSchema,
+  UpdateTodoSchema,
+  NotificationSchema,
+  // Types（自动推断）
+  type Todo,
+  type CreateTodoInput,
+  type UpdateTodoInput,
+} from '@shared/schemas'
+```
+
+### 使用示例
+
+```typescript
+// ❌ 避免 - 使用 any
+async function getTodo(id: number): Promise<any> {
+  const response = await fetch(`/api/todos/${id}`)
+  return response.json()
+}
+
+// ✅ 正确 - 使用项目已有类型
+import type { Todo, ApiResponse } from '@shared/types'
+
+async function getTodo(id: number): Promise<Todo> {
+  const response = await fetch(`/api/todos/${id}`)
+  const data: ApiResponse<Todo> = await response.json()
+
+  if (!data.success) {
+    throw new Error(data.error)
+  }
+
+  return data.data
+}
+
+// ✅ 更好 - 使用 Zod 进行运行时验证
+import { TodoSchema, type Todo } from '@shared/schemas'
+
+async function getTodo(id: number): Promise<Todo> {
+  const response = await fetch(`/api/todos/${id}`)
+  const json = await response.json()
+
+  const result = TodoSchema.safeParse(json)
+  if (!result.success) {
+    throw new Error('Invalid todo data')
+  }
+
+  return result.data
+}
+```
+
+## 🔧 其他替代方案
+
+### 1. 使用 Partial、Pick、Omit（基于已有类型）
+
+```typescript
+import type { Todo, CreateTodoInput } from '@shared/types';
+
+// ❌ 避免
+function updateTodo(id: number, updates: any) { ... }
+
+// ✅ 使用 Partial
+function updateTodo(id: number, updates: Partial<Todo>) { ... }
+
+// ✅ 使用 Pick
+type TodoPreview = Pick<Todo, 'id' | 'title'>;
+
+// ✅ 使用 Omit
+type TodoWithoutTimestamps = Omit<Todo, 'createdAt' | 'updatedAt'>;
+```
+
+### 2. 使用泛型
+
+```typescript
+// ❌ 避免
+function getFirstItem(items: any): any {
+  return items[0]
+}
+
+// ✅ 使用泛型
+function getFirstItem<T>(items: T[]): T | undefined {
+  return items[0]
+}
+
+// 使用项目类型
+import type { Todo } from '@shared/types'
+const firstTodo = getFirstItem<Todo>(todos)
+```
+
+### 3. 使用 unknown（当类型真的未知时）
+
+```typescript
+// ❌ 避免
+function parseJSON(json: string): any {
+  return JSON.parse(json)
+}
+
+// ✅ 使用 unknown + Zod 验证
+import { TodoSchema, type Todo } from '@shared/schemas'
+
+function parseTodo(json: string): Todo {
+  const data: unknown = JSON.parse(json)
+  const result = TodoSchema.safeParse(data)
+
+  if (!result.success) {
+    throw new Error('Invalid todo data')
+  }
+
+  return result.data
+}
+```
+
+### 4. 使用 Record（键值对场景）
+
+```typescript
+import type { Todo } from '@shared/types'
+
+// ❌ 避免
+const todoCache: any = {}
+
+// ✅ 使用 Record
+const todoCache: Record<number, Todo> = {}
+```
+
+## 📚 项目类型定义
+
+- **类型导出**：`src/shared/core/` 和 `src/shared/modules/`
+- **Schema 定义**：`src/shared/schemas/`
+  - `index.ts` - 统一导出
+
+## ⚠️ 特殊情况
+
+如果确实需要使用 `any`（极少数情况）：
+
+```typescript
+// 临时禁用 ESLint 规则（不推荐，但有时必要）
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const legacyData: any = oldApi.getData()
+
+// 或者使用 @ts-expect-error（更好）
+// @ts-expect-error - 第三方库类型定义缺失
+const result = thirdPartyLib.someMethod()
+```
+
+**记住：优先在项目中查找已有类型，不要随意定义新类型！**

package/template/.claude/hookify.warn-console-log.local.md

@@ -0,0 +1,73 @@
+---
+name: warn-console-log
+enabled: true
+event: file
+conditions:
+  - field: file_path
+    operator: regex_match
+    pattern: src/.*\.(ts|tsx)$
+  - field: new_text
+    operator: regex_match
+    pattern: console\.log\(
+---
+
+⚠️ **检测到 console.log**
+
+项目规则禁止在生产代码中使用 console.log。
+
+**请使用项目提供的 logger 工具：**
+
+```typescript
+// ❌ 避免
+console.log('User created:', userId)
+
+// ✅ 推荐 - 服务端使用
+import { logger } from '@server/utils/logger'
+
+const log = logger.api() // 或 logger.db(), logger.ws(), logger.app()
+log.info({ userId }, 'User created successfully')
+
+// ✅ 推荐 - 不同模块使用不同的 logger
+const dbLog = logger.db()
+dbLog.debug({ query, params }, 'Executing database query')
+
+const wsLog = logger.ws()
+wsLog.info({ clientId, message }, 'WebSocket message received')
+
+// ✅ 推荐 - 自定义模块
+const customLog = logger.module('my-module')
+customLog.warn({ error }, 'Operation failed')
+```
+
+**Logger API：**
+
+```typescript
+// 可用的 logger 实例
+logger.app() // 应用级别日志
+logger.db() // 数据库日志
+logger.api() // API 日志
+logger.ws() // WebSocket 日志
+logger.bootstrap() // 启动日志
+logger.module(name) // 自定义模块日志
+
+// 日志级别（按严重程度）
+log.trace({ data }, 'message') // 最详细
+log.debug({ data }, 'message') // 调试信息
+log.info({ data }, 'message') // 一般信息
+log.warn({ data }, 'message') // 警告
+log.error({ data }, 'message') // 错误
+log.fatal({ data }, 'message') // 致命错误
+```
+
+**参数说明：**
+
+- 第一个参数：对象，包含要记录的结构化数据
+- 第二个参数：字符串，描述性消息
+
+**优势：**
+
+- 结构化日志，便于搜索和分析
+- 自动添加时间戳和模块标识
+- 支持日志文件输出（生产环境）
+- 支持日志级别过滤
+- 支持 Cloudflare Workers 环境

package/template/.claude/rules/00-project-config.md

@@ -0,0 +1,147 @@
+---
+paths: package.json, tsconfig.json, vite.config.ts, vitest.config.ts, .eslintrc*, .prettierrc*, eslint.config.js
+---
+
+# Project Rules
+
+## 📦 项目配置
+
+### TypeScript 配置
+
+**路径**: `tsconfig.json`
+
+**关键配置**:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "baseUrl": ".",
+    "paths": {
+      "@shared/*": ["src/shared/*"],
+      "@client/*": ["src/client/*"],
+      "@server/*": ["src/server/*"]
+    }
+  }
+}
+```
+
+### ESLint 配置
+
+**路径**: `eslint.config.js`
+
+**ESLint 版本**: 9.x (Flat Config)
+
+**关联的 ESLint 规则**:
+
+| 规则                                 | 类型  | 说明               |
+| ------------------------------------ | ----- | ------------------ |
+| `@typescript-eslint/no-unused-vars`  | error | 未使用的变量       |
+| `@typescript-eslint/no-explicit-any` | warn  | 禁止 any 类型      |
+| `no-console`                         | error | 禁止 console.log   |
+| `no-restricted-globals`              | error | 禁止直接使用 fetch |
+
+### 自定义 ESLint 规则
+
+项目包含 17 个自定义 ESLint 规则，详见各模块规则文档。
+
+## 📦 稡块结构
+
+### 后端模块结构
+
+```
+src/server/
+├── core/                    # 框架层（不可修改）
+│   ├── runtime.ts
+│   └── realtime-scanner.ts
+├── middleware/              # 中间件
+│   ├── auth.ts
+│   ├── cors.ts
+│   └── logger.ts
+├── module-{feature}/       # 业务模块
+│   ├── routes/
+│   │   └── {feature}-routes.ts
+│   ├── services/
+│   │   └── {feature}-service.ts
+│   └── __tests__/
+│       └── *.test.ts
+└── utils/                   # 工具函数
+    ├── route-helpers.ts
+    └── logger.ts
+```
+
+### 前端模块结构
+
+```
+src/client/
+├── components/               # React 组件
+│   └── __tests__/
+├── hooks/                   # 自定义 Hooks
+├── pages/                   # 页面组件
+├── services/               # API 客户端
+│   └── apiClient.ts
+└── stores/                  # Zustand Store
+    └── __tests__/
+```
+
+### 共享模块结构
+
+```
+src/shared/
+├── core/                    # 框架层
+│   ├── api-schemas.ts
+│   ├── ws-client.ts
+│   └── sse-client.ts
+├── modules/                 # 业务层
+│   ├── todos/
+│   ├── notifications/
+│   └── chat/
+└── schemas/                 # 统一导出
+    └── index.ts
+```
+
+## 🔗 路径别名
+
+使用路径别名代替相对导入:
+
+```typescript
+// ✅ 正确
+import { User } from '@shared/types'
+import { useUserStore } from '@client/stores/userStore'
+
+// ❌ 错误
+import { User } from '../../../shared/types'
+import { useUserStore } from '../../stores/userStore'
+```
+
+**ESLint 规则**: 无（建议添加）
+
+**建议**: 添加 `no-restricted-imports` 规则禁止多级相对路径。
+
+## 🧪 测试
+
+详细测试规范请参考 [Testing 规范](./60-testing-standards.md)
+
+快速参考:
+
+- 单元测试: `__tests__/*.test.ts`
+- 集成测试: `src/server/__tests__/integration/*.test.ts`
+- E2E 测试: `e2e/*.spec.ts`
+- 覆盖率目标: >80%
+
+## 🎨 代码风格
+
+- 使用 Prettier 进行格式化
+- 遵循 ESLint 规则
+- ❌ 生产代码禁止 `console.log`
+- ✅ 允许 `console.error` 和 `console.warn` 用于错误日志
+- 使用 TypeScript strict mode
+
+## 📚 相关文档
+
+- [Server API 规范](./20-server-api.md) - 服务端开发规范
+- [Client 组件规范](./30-client-components.md) - 前端组件开发规范
+- [Shared Types 规范](./40-shared-types.md) - 共享类型定义规范
+- [Testing 规范](./60-testing-standards.md) - 测试编写规范

package/template/.claude/rules/01-file-types.md

@@ -0,0 +1,127 @@
+---
+paths: src/**/*
+---
+
+# 文件类型规范
+
+## 📋 原则
+
+**项目统一使用 TypeScript，除非有特殊理由使用其他语言。**
+
+## ✅ TypeScript (.ts/.tsx)
+
+### 必须使用 TypeScript 的场景
+
+| 场景       | 文件类型 | 示例                                   |
+| ---------- | -------- | -------------------------------------- |
+| 源代码     | `.ts`    | `src/client/services/apiClient.ts`     |
+| React 组件 | `.tsx`   | `src/client/components/Navigation.tsx` |
+| 脚本工具   | `.ts`    | `scripts/validate-all.ts`              |
+| 配置文件   | `.ts`    | `vite.config.ts`, `vitest.config.ts`   |
+
+### TypeScript 特性要求
+
+```typescript
+// ✅ 启用严格类型检查
+function process(data: TodoInput): Todo {
+  // ...
+}
+
+// ✅ 使用类型导入（性能更好）
+import type { Todo, CreateTodoInput } from '@shared/types'
+import { Todo } from '@shared/types' // 值导入
+
+// ✅ 使用 Node.js 协议前缀
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+// ❌ 避免使用 any
+const data: any = getData()
+
+// ✅ 使用 unknown 代替
+const data: unknown = getData()
+```
+
+## ⚠️ JavaScript (.js/.mjs/.cjs)
+
+### 允许使用 JavaScript 的场景
+
+| 场景        | 理由     | 示例                |
+| ----------- | -------- | ------------------- |
+| ESLint 配置 | 工具限制 | `eslint.config.js`  |
+| 第三方钩子  | 工具要求 | `.husky/pre-commit` |
+
+### JavaScript 代码规范
+
+即使使用 JavaScript，也应遵循 TypeScript 风格：
+
+```javascript
+// eslint.config.js
+// ✅ 使用 JSDoc 提供类型信息
+/**
+ * @param {string} filePath - 文件路径
+ * @returns {Promise<string>} 文件内容
+ */
+async function readFile(filePath) {
+  // ...
+}
+```
+
+## 📝 配置文件类型映射
+
+| 文件               | 类型       | 理由                     |
+| ------------------ | ---------- | ------------------------ |
+| `vite.config.ts`   | TypeScript | ✅ Vite 原生支持         |
+| `vitest.config.ts` | TypeScript | ✅ Vitest 原生支持       |
+| `eslint.config.js` | JavaScript | ⚠️ ESLint 9 扁平配置要求 |
+| `package.json`     | JSON       | ✅ npm 标准              |
+| `tsconfig.json`    | JSON       | ✅ TypeScript 标准       |
+
+## 🚫 禁止的文件类型
+
+| 文件类型                    | 原因                    |
+| --------------------------- | ----------------------- |
+| `.jsx`                      | 项目使用 React + `.tsx` |
+| CoffeeScript, LiveScript 等 | 非主流语言              |
+| 未配置类型的 `.js`          | 无法获得类型安全        |
+
+## 📂 目录结构
+
+```
+project-root/
+├── src/
+│   ├── client/          # .ts, .tsx
+│   ├── server/          # .ts
+│   └── shared/          # .ts
+├── scripts/             # .ts (工具脚本)
+├── eslint.config.js     # .js (工具要求)
+├── vite.config.ts       # .ts
+└── tsconfig.json        # JSON
+```
+
+## 📝 创建新文件时的决策树
+
+```
+需要创建文件？
+    │
+    ├─ 是配置文件？
+    │   ├─ 是 ── 工具支持 TypeScript？
+    │   │   ├─ 是 ── 使用 .ts
+    │   │   └─ 否 ── 使用 .js + JSDoc
+    │   │
+    │   └─ 否 ── 使用 TypeScript (.ts)
+    │
+    └─ 是源代码？
+        └─ 使用 .ts (React 组件使用 .tsx)
+```
+
+## 🎯 总结
+
+| 场景        | 文件类型       | 是否必须    |
+| ----------- | -------------- | ----------- |
+| 源代码      | `.ts` / `.tsx` | ✅ 必须     |
+| 脚本工具    | `.ts`          | ✅ 必须     |
+| 配置文件    | `.ts` / `.js`  | 视工具支持  |
+| ESLint 配置 | `.js`          | ⚠️ 工具限制 |
+
+**原则：TypeScript 优先，JavaScript 仅作为工具要求的最后选择。**

package/template/.claude/rules/02-git-workflow.md

@@ -0,0 +1,167 @@
+---
+paths: .git/**/*, .github/**/*
+---
+
+# Git 工作流规范
+
+## 🚫 禁止跳过 Hooks
+
+**严格禁止**: 使用 `--no-verify` 跳过 pre-commit hooks 提交代码
+
+```bash
+# ❌ 禁止这样做
+git commit --no-verify -m "message"
+
+# ✅ 正确做法 - 让 hooks 运行
+git commit -m "message"
+```
+
+**理由**:
+
+- Pre-commit hooks 确保代码质量（格式检查、测试运行）
+- 跳过 hooks 会将低质量代码提交到仓库
+- 影响团队协作和代码审查
+
+### 如果 Hooks 失败怎么办？
+
+1. **运行测试失败** → 修复测试后再提交
+2. **格式检查失败** → 运行 `npm run format` 修复
+3. **验证器失败** → 修复验证问题
+4. **临时文件** → 使用 `.gitignore` 排除
+
+### 紧急情况
+
+如果确实需要绕过 hooks（极少情况）:
+
+```bash
+# 1. 先确认原因
+npm run test      # 检查测试状态
+npm run format     # 检查格式
+
+# 2. 记录原因
+# 在 commit message 中说明为什么要跳过 hooks
+git commit --no-verify -m "fix: emergency fix
+
+[SKIP-HOOKS] Reason: CI is down, will run tests manually"
+```
+
+## 📝 Commit Message 规范
+
+### 格式
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Type 类型
+
+| Type       | 说明      | 示例                                        |
+| ---------- | --------- | ------------------------------------------- |
+| `feat`     | 新功能    | `feat(todos): add search functionality`     |
+| `fix`      | Bug 修复  | `fix: handle null pointer exception`        |
+| `docs`     | 文档更新  | `docs(readme): update installation steps`   |
+| `style`    | 代码格式  | `style: indent code with 2 spaces`          |
+| `refactor` | 重构      | `refactor(api): simplify response handling` |
+| `test`     | 测试      | `test: add unit tests for TodoService`      |
+| `chore`    | 构建/工具 | `chore: update dependencies`                |
+
+### Subject 主题
+
+- 使用中文或英文
+- 简洁描述做了什么
+- 不超过 50 字符
+- 不以句号结尾
+
+### Body 正文
+
+- 详细描述做了什么
+- 说明为什么这么做
+- 列出相关 Issue
+
+### 示例
+
+```
+feat(todos): 添加搜索功能
+
+- 新增搜索框组件
+- 添加标题和描述搜索
+- 实现搜索结果高亮
+
+Closes #123
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## 🔄 工作流程
+
+### 分支策略
+
+```bash
+# 1. 从 main 创建功能分支
+git checkout -b feat/new-feature
+
+# 2. 开发和提交
+git add .
+git commit -m "feat: add implementation"
+
+# 3. 推送到远程
+git push origin feat/new-feature
+
+# 4. 创建 Pull Request
+# 在 GitHub 上创建 PR，请求合并到 main
+
+# 5. Code Review 和修改
+# 根据反馈修改代码，重复 2-3
+
+# 6. 合并到 main
+# PR 审查通过后合并
+```
+
+### 提交频率
+
+- 小步快跑：频繁提交，每次提交一个完整的逻辑单元
+- 不要堆积大量修改在一个 commit
+- 每个 commit 应该能通过测试和构建
+
+## 🔍 Pre-commit Hooks
+
+当前配置的 hooks (`.husky/pre-commit`):
+
+1. **npm run typecheck** - TypeScript 类型检查
+2. **npx lint-staged** - 对暂存文件运行格式化和检查
+3. **npm run test:smart:staged** - 智能测试（只测试相关文件）
+
+### Hooks 检查内容
+
+```bash
+# 1. TypeScript 类型检查
+npm run typecheck
+
+# 2. lint-staged - 对暂存文件运行格式化和检查
+npx lint-staged
+
+# 3. 智能测试 - 只测试与改动相关的文件
+npm run test:smart:staged
+```
+
+**注意**:
+
+- lint-staged 的具体配置在 `package.json` 中定义
+- 智能测试会分析文件依赖，只运行相关的测试，提升效率
+
+## 📋 检查清单
+
+提交前确认：
+
+- [ ] 代码已通过本地测试
+- [ ] 代码已格式化 (`npm run format`)
+- [ ] 没有 `console.log` 调试代码
+- [ ] 没有 `.only` 或 `.skip` 测试
+- [ ] Commit message 符合规范
+- [ ] 没有 `--no-verify`