create-fullstack-scaffold 0.1.0

package/template/.claude/rules/20-server-api.md

@@ -0,0 +1,349 @@
+---
+paths: src/server/**/*.ts
+---
+
+# Server API 开发规范
+
+## 📁 目录结构
+
+```
+src/server/
+├── core/                    # 框架层（不可修改）
+│   ├── runtime.ts
+│   ├── realtime-core.ts
+│   └── realtime-scanner.ts
+├── middleware/              # 中间件
+│   ├── auth.ts
+│   ├── cors.ts
+│   ├── logger.ts
+│   └── error-handler.ts
+├── module-{feature}/       # 业务模块
+│   ├── routes/
+│   │   └── {feature}-routes.ts
+│   ├── services/
+│   │   └── {feature}-service.ts
+│   └── __tests__/
+└── utils/                   # 工具函数
+    ├── route-helpers.ts
+    ├── logger.ts
+    └── auth.ts
+```
+
+## 🔧 中间件规范
+
+### 中间件位置约束
+
+中间件**必须**放在 `src/server/middleware/` 目录。
+
+```typescript
+// ✅ 正确 - 中间件放在 middleware 目录
+// src/server/middleware/auth.ts
+export function authMiddleware(options?: AuthMiddlewareOptions): MiddlewareHandler {
+  return async (c, next) => {
+    // 中间件逻辑
+    await next()
+  }
+}
+
+// ❌ 错误 - 中间件放在其他目录
+// src/server/module-todos/middleware/auth.ts
+export function authMiddleware() { ... }
+```
+
+**ESLint 规则**: `middleware-location`, `no-middleware-outside-dir`
+
+**路径**: `src/server/middleware/**/*.ts`
+
+### ⚠️ 中间件应用位置（重要）
+
+**中间件只能在 `app.ts` 中应用，不能在路由文件中应用！**
+
+```typescript
+// ✅ 正确 - 在 app.ts 中应用中间件
+// src/server/app.ts
+export function createApp<T extends AppBindings = AppBindings>() {
+  const app = new OpenAPIHono<{ Bindings: T }>()
+    .use('*', errorHandlerMiddleware())
+    .use('*', loggerMiddleware())
+    .use('*', corsMiddleware())
+    .use('/api/admin/*', captchaMiddleware({ ... }))
+    .route('/api', apiRoutes)
+    .route('/api', adminRoutes)
+
+  return app
+}
+
+// ❌ 错误 - 在路由文件中应用中间件
+// src/server/module-admin/routes/admin-routes.ts
+export const adminRoutes = new OpenAPIHono()
+  .use('*', captchaMiddleware())  // ❌ 会导致类型推导丢失
+  .openapi(getStatsRoute, async c => { ... })  // ❌ 类型错误
+```
+
+**为什么不能在路由文件中应用中间件？**
+
+| 操作                       | 返回类型      | 是否支持 .openapi() |
+| -------------------------- | ------------- | ------------------- |
+| `new OpenAPIHono()`        | `OpenAPIHono` | ✅ 支持             |
+| `.use(middleware)`         | `Hono`        | ❌ 不支持           |
+| `.openapi(route, handler)` | `OpenAPIHono` | ✅ 支持             |
+
+**类型推导链**：
+
+```
+OpenAPIHono
+  ↓ .use()
+Hono (丢失 OpenAPI 类型)
+  ↓ .openapi() ❌ 类型错误
+```
+
+### 中间件导出规范
+
+```typescript
+// src/server/middleware/index.ts
+export { corsMiddleware, createCorsMiddleware, type CorsOptions } from './cors'
+export { loggerMiddleware, createLoggerMiddleware, type LoggerOptions } from './logger'
+export {
+  authMiddleware,
+  requireAdminMiddleware,
+  requirePermissionsMiddleware,
+  type AuthUser,
+  type AuthMiddlewareOptions,
+} from './auth'
+export {
+  captchaMiddleware,
+  markCaptchaVerifiedMiddleware,
+  clearCaptchaSessionMiddleware,
+  type CaptchaConfig,
+} from './captcha'
+```
+
+## 🛣️ 路由规范
+
+### 路由位置约束
+
+路由文件**必须**放在 `src/server/module-*/routes/` 目录。
+
+```typescript
+// ✅ 正确 - 路由放在模块目录
+// src/server/module-todos/routes/todos-routes.ts
+export const apiRoutes = new OpenAPIHono()
+  .openapi(listRoute, async c => { ... })
+  .openapi(createRoute, async c => { ... })
+
+// ❌ 错误 - 路由放在其他目录
+// src/server/routes/todos.ts
+export const todoRoutes = new OpenAPIHono()...
+```
+
+**ESLint 规则**: `route-location`
+
+**路径**: `src/server/module-*/routes/**/*.ts`
+
+### 路由定义规范
+
+```typescript
+// ✅ 正确 - 使用链式语法
+import { createRoute } from '@hono/zod-openapi'
+import { ItemSchema, CreateItemSchema } from '@shared/schemas'
+import { successResponse, errorResponse } from '@server/utils/route-helpers'
+
+const listRoute = createRoute({
+  method: 'get',
+  path: '/items',
+  responses: {
+    200: successResponse(z.array(ItemSchema), '获取列表'),
+  },
+})
+
+const createRoute = createRoute({
+  method: 'post',
+  path: '/items',
+  request: {
+    body: {
+      content: {
+        'application/json': { schema: CreateItemSchema },
+      },
+    },
+  },
+  responses: {
+    201: successResponse(ItemSchema, '创建成功'),
+    400: errorResponse('参数错误'),
+  },
+})
+
+export const apiRoutes = new OpenAPIHono()
+  .openapi(listRoute, async c => { ... })
+  .openapi(createRoute, async c => { ... })
+```
+
+**ESLint 规则**: `require-hono-chain-syntax`, `no-inline-schema`, `require-response-helpers`
+
+## 🏢 Service 层规范
+
+### Service 职责
+
+Service 层负责业务逻辑实现，不包含路由定义。
+
+```typescript
+// ✅ 正确 - Service 只包含业务逻辑
+// src/server/module-todos/services/todo-service.ts
+import type { Item, CreateItemInput } from '@shared/schemas'
+import { getDb } from '../../db'
+
+export async function listItems(): Promise<Item[]> {
+  const db = await getDb()
+  const rows = await db.select().from(items)
+  return rows
+}
+
+export async function createItem(input: CreateItemInput): Promise<Item> {
+  const db = await getDb()
+  const result = await db.insert(items).values(input).returning()
+  return result[0]
+}
+```
+
+### 禁止工具函数
+
+Service 文件应专注于业务逻辑，不应包含工具函数。
+
+```typescript
+// ❌ 错误 - Service 中定义工具函数
+export async function createItem(input: CreateItemInput) {
+  const normalizedTitle = normalizeText(input.title) // ❌ 工具函数
+  // ...
+}
+
+function normalizeText(text: string) {
+  // ❌ 应移至 utils/
+  return text.trim().toLowerCase()
+}
+
+// ✅ 正确 - 工具函数放在 utils/
+import { normalizeText } from '@server/utils/text'
+
+export async function createItem(input: CreateItemInput) {
+  const normalizedTitle = normalizeText(input.title) // ✅
+  // ...
+}
+```
+
+**ESLint 规则**: `no-util-functions-in-service`
+
+**路径**: `src/server/module-*/services/**/*.ts`
+
+## 🏗️ 架构边界规范
+
+### 层级边界约束
+
+项目分为**框架层**和**业务层**，边界必须清晰。
+
+| 层级   | 目录                                                             | 职责                     |
+| ------ | ---------------------------------------------------------------- | ------------------------ |
+| 框架层 | `src/shared/core/`<br>`src/server/core/`                         | 通用基础设施，不感知业务 |
+| 业务层 | `src/shared/modules/`<br>`src/server/module-*/`<br>`src/client/` | 业务逻辑实现             |
+
+### 禁止事项
+
+```typescript
+// ❌ 禁止：业务层直接修改框架层
+// src/server/module-todos/services/todo-service.ts
+import { runtime } from '@server/core/runtime'
+
+runtime.registerRPC('customMethod', handler) // ❌ 禁止修改框架层
+
+// ✅ 正确：通过框架提供的扩展点
+import { createRPCHandler } from '@server/core/runtime'
+
+export const customHandler = createRPCHandler('customMethod', handler)
+```
+
+**ESLint 规则**: `layer-boundary`
+
+**路径**: `src/server/**/*.ts`
+
+## 🛡️ 框架保护
+
+框架层文件带有 `@framework-baseline` 注释：
+
+```typescript
+/**
+ * @framework-baseline ab16e97716a7556e
+ *
+ * 此文件属于框架层代码。如需修改，请添加以下说明：
+ * @framework-modify
+ * @reason [必填] 修改原因
+ * @impact [必填] 影响范围
+ */
+```
+
+**框架层文件**:
+
+- `src/server/core/**/*.ts`
+- `src/server/entries/**/*.ts`
+- `src/server/test-utils/**/*.ts`
+- `src/shared/core/**/*.ts`
+
+**ESLint 规则**: `framework-protect`
+
+## 📤 导出规范
+
+### 模块导出
+
+```typescript
+// src/server/module-todos/index.ts
+export { apiRoutes } from './routes/todos-routes'
+export { listTodos, createTodo } from './services/todo-service'
+```
+
+### 全局导出
+
+```typescript
+// src/server/index.ts
+export { createApp, type AppType } from './app'
+export { apiRoutes } from './module-todos/routes/todos-routes'
+```
+
+## 🚫 Anti-Patterns
+
+```typescript
+// ❌ 不要在 Service 中定义路由
+export const apiRoutes = new OpenAPIHono()...
+
+// ❌ 不要在路由中直接实现业务逻辑
+.openapi(createRoute, async c => {
+  const db = await getDb()  // ❌ 应在 Service 中
+  const result = await db.insert(items).values(data)
+  return c.json({ success: true, data: result[0] })
+})
+
+// ✅ 正确 - 调用 Service
+.openapi(createRoute, async c => {
+  const data = c.req.valid('json')
+  const item = await createItem(data)  // ✅ 调用 Service
+  return c.json({ success: true, data: item })
+})
+
+// ❌ 不要在路由文件中应用中间件
+export const adminRoutes = new OpenAPIHono()
+  .use('*', captchaMiddleware())  // ❌ 会导致类型错误
+  .openapi(getStatsRoute, async c => { ... })
+
+// ✅ 正确 - 在 app.ts 中应用中间件
+// src/server/app.ts
+.use('/api/admin/*', captchaMiddleware())
+.route('/api', adminRoutes)
+
+// ❌ 不要使用 any 类型
+export async function createItem(input: any) { ... }
+
+// ✅ 正确 - 使用类型
+export async function createItem(input: CreateItemInput): Promise<Item> { ... }
+```
+
+## 📚 相关文档
+
+- [API 类型推导规范](./10-api-type-inference.md) - Hono RPC 类型推导
+- [Server 入口规范](./21-server-entrypoint.md) - 应用创建规范
+- [Testing 规范](./60-testing-standards.md) - 测试编写规范

package/template/.claude/rules/21-server-entrypoint.md

@@ -0,0 +1,257 @@
+---
+paths: src/server/app.ts
+---
+
+# Server App Factory 规范
+
+## 🎯 Primary Purpose
+
+`src/server/app.ts` 是服务端应用的**工厂函数**，负责创建和配置 Hono 应用实例。
+
+**重要**: 此文件使用 `createApp()` 函数创建应用，而不是直接导出 `app` 实例。
+
+## 🔗 链式语法（强制）
+
+**必须使用链式语法**创建应用实例，确保 Hono RPC 类型推断正确。
+
+```typescript
+// ✅ 正确 - 链式语法
+export function createApp<T extends AppBindings = AppBindings>() {
+  const app = new OpenAPIHono<{ Bindings: T }>()
+    .use('*', errorHandlerMiddleware())
+    .use('*', loggerMiddleware())
+    .use('*', corsMiddleware())
+    .route('/api', apiRoutes)
+    .route('/api', notificationRoutes)
+    .get('/health', async c => { ... })
+
+  return app
+}
+
+// ❌ 错误 - 非链式语法会导致类型推断丢失
+const app = new OpenAPIHono();
+app.use('*', errorHandlerMiddleware());
+app.route('/api', apiRoutes);
+```
+
+**为什么必须使用链式语法？**
+
+| 方式     | 类型推断 | Hono RPC 支持 | IDE 补全 |
+| -------- | -------- | ------------- | -------- |
+| 链式语法 | ✅ 完整  | ✅ 支持       | ✅ 完整  |
+| 非链式   | ❌ 丢失  | ❌ 不支持     | ❌ 部分  |
+
+## 📁 文件职责
+
+### createApp 函数职责
+
+1. **创建应用实例** - 使用 `OpenAPIHono`
+2. **配置全局中间件** - 错误处理、日志、CORS 等
+3. **挂载业务路由** - 通过 `.route()` 挂载模块路由
+4. **定义全局路由** - 健康检查、测试辅助路由
+5. **自动注册实时通信** - WebSocket/SSE 自动扫描
+
+### 禁止事项
+
+```typescript
+// ❌ 禁止定义业务路由
+.post('/api/todos', async c => {  // ❌ 应在 module-todos/routes/
+  // 业务逻辑
+})
+
+// ❌ 禁止直接调用 Service
+import { createTodo } from './module-todos/services/todo-service';
+const todo = await createTodo(data);  // ❌ 应通过路由调用
+
+// ❌ 禁止实现工具函数
+function formatDate(date: Date) {  // ❌ 应在 utils/
+  return date.toISOString();
+}
+```
+
+## ✅ 允许的路由定义
+
+### 全局路由（允许）
+
+```typescript
+export function createApp<T extends AppBindings = AppBindings>() {
+  const app = new OpenAPIHono<{ Bindings: T }>()
+    // ... 中间件和业务路由
+    // ✅ 允许 - 健康检查路由
+    .get('/health', async c => {
+      try {
+        const { getDb } = await import('./db')
+        await getDb()
+        return c.json({ status: 'ok', db: 'connected' })
+      } catch {
+        return c.json({ status: 'ok', db: 'not configured' })
+      }
+    })
+
+    // ✅ 允许 - 测试辅助路由（仅测试环境）
+    .post('/api/__test__/cleanup', async c => {
+      const { cleanupTestDatabase } = await import('./db/test-setup')
+      await cleanupTestDatabase()
+      return c.json({ success: true })
+    })
+
+  return app
+}
+```
+
+### 业务路由（禁止）
+
+```typescript
+// ❌ 禁止 - 业务路由应在 module-*/routes/ 中定义
+.post('/api/todos', async c => {
+  const data = await c.req.json()
+  // 业务逻辑
+})
+```
+
+## 🏗 标准结构
+
+```typescript
+// 1. Imports
+import { OpenAPIHono } from '@hono/zod-openapi'
+import { apiRoutes } from './module-todos/routes/todos-routes'
+import { notificationRoutes } from './module-notifications/routes/notification-routes'
+import type { AppBindings, CreateAppOptions } from './types/bindings'
+import { autoRegisterRealtime } from './core/realtime-scanner'
+import { corsMiddleware, loggerMiddleware, errorHandlerMiddleware } from './middleware'
+
+// 2. 导出类型
+export { type AppBindings, type CreateAppOptions } from './types/bindings'
+
+// 3. createApp 函数
+export function createApp<T extends AppBindings = AppBindings>(_options: CreateAppOptions = {}) {
+  const app = new OpenAPIHono<{ Bindings: T }>()
+    // 3.1 全局中间件
+    .use('*', errorHandlerMiddleware())
+    .use('*', loggerMiddleware())
+    .use('*', corsMiddleware())
+
+    // 3.2 业务路由挂载
+    .route('/api', apiRoutes)
+    .route('/api', notificationRoutes)
+
+    // 3.3 全局路由
+    .get('/health', async c => { ... })
+
+  // 3.4 自动注册实时通信
+  autoRegisterRealtime(app)
+
+  return app
+}
+
+// 4. 导出类型
+export type AppType = ReturnType<typeof createApp>
+
+// 5. 导出路由模块（供其他模块使用）
+export { apiRoutes, notificationRoutes }
+```
+
+## 🔄 与其他文件的关系
+
+### 入口文件层级
+
+```
+src/server/
+├── index.ts              # 导出模块，设置 runtime adapter
+│   └── 导出 createApp, AppType 等
+│
+├── app.ts                # 创建应用实例（本文件）
+│   └── createApp() 函数
+│
+└── entries/
+    ├── node.ts           # Node.js 启动服务器
+    │   └── startServer() 函数
+    │
+    └── cloudflare.ts     # Cloudflare Workers 入口
+        └── export default app
+```
+
+### 调用流程
+
+```
+1. entries/node.ts
+   ↓ 调用 createApp()
+2. app.ts
+   ↓ 创建应用实例
+3. 返回 OpenAPIHono 实例
+   ↓ 导出 AppType
+4. 客户端使用 AppType 进行类型安全调用
+```
+
+## 🧪 测试辅助路由
+
+测试辅助路由**必须**使用 `/api/__test__/` 前缀：
+
+```typescript
+// ✅ 正确 - 测试路由前缀
+.post('/api/__test__/cleanup', async c => { ... })
+.post('/api/__test__/seed', async c => { ... })
+.get('/api/__test__/status', async c => { ... })
+
+// ❌ 错误 - 没有前缀
+.post('/api/test/cleanup', async c => { ... })  // ❌ 缺少 __test__ 前缀
+```
+
+## 📝 类型导出
+
+**必须导出以下类型**：
+
+```typescript
+// 1. AppType - 供客户端 Hono RPC 使用
+export type AppType = ReturnType<typeof createApp>
+
+// 2. AppBindings - 供环境变量类型
+export type AppBindings = { ... }
+
+// 3. CreateAppOptions - 供创建应用时的选项
+export type CreateAppOptions = { ... }
+```
+
+## 🔒 框架保护
+
+此文件属于**框架层代码**，修改需要特殊审批：
+
+```typescript
+/**
+ * @framework-baseline [hash]
+ *
+ * 如需修改，请添加以下说明：
+ * @framework-modify
+ * @reason [必填] 修改原因
+ * @impact [必填] 影响范围
+ */
+```
+
+## 🚫 Anti-Patterns
+
+```typescript
+// ❌ 不要使用非链式语法
+const app = new OpenAPIHono();
+app.use('*', cors());
+app.route('/api', apiRoutes);
+
+// ❌ 不要定义业务路由
+.post('/api/users', async c => { ... })
+
+// ❌ 不要直接调用 Service
+import { createUser } from './module-users/services/user-service';
+const user = await createUser(data);
+
+// ❌ 不要忘记导出 AppType
+export default app  // ❌ 缺少 AppType 导出
+
+// ✅ 正确
+export type AppType = ReturnType<typeof createApp>
+export default app
+```
+
+## 📚 相关文档
+
+- [Server API 规范](./20-server-api.md) - 路由定义规范
+- [API 类型推导规范](./10-api-type-inference.md) - Hono RPC 类型推导
+- [架构规范](./00-project-config.md) - 模块化架构