create-fullstack-scaffold 0.1.0

package/template/.claude/rules/34-client-admin-module.md

@@ -0,0 +1,445 @@
+---
+paths: src/admin/**/*.tsx, src/admin/**/*.ts
+---
+
+# Admin 模块开发规范
+
+## 🎯 核心原则
+
+Admin 模块是一个**独立的管理后台**，与主应用完全分离，有自己的入口、布局和路由。
+
+**重要**: Admin 模块位于 `src/admin/`，与 `src/client/`（用户前台）平级，实现用户端与管理端的完全隔离。
+
+**技术栈**: Admin 模块使用 **Ant Design** 作为 UI 组件库。
+
+## 📁 目录结构
+
+```
+src/admin/
+├── components/                 # Admin 专用组件
+│   └── ...                     # 业务组件
+│
+├── layouts/                    # 布局组件
+│   ├── AdminLayout.tsx         # 主布局
+│   ├── AdminSidebar.tsx        # 侧边栏
+│   └── AdminHeader.tsx         # 顶部导航
+│
+├── pages/                      # Admin 页面
+│   ├── DashboardPage.tsx       # 仪表盘（首页）
+│   ├── LoginPage.tsx           # 登录页
+│   ├── RegisterPage.tsx        # 注册页
+│   ├── SettingsPage.tsx        # 系统设置
+│   └── ...                     # 其他页面
+│
+├── stores/                     # Admin 状态管理
+│   └── adminStore.ts           # Admin 状态
+│
+├── AdminApp.tsx                # Admin 入口（路由配置）
+└── main.tsx                    # Admin 启动文件
+```
+
+## 🏗️ 多入口架构
+
+### 入口文件
+
+项目支持**两个独立入口**：
+
+| 入口     | 文件                  | HTML         | 访问路径   | 用途     |
+| -------- | --------------------- | ------------ | ---------- | -------- |
+| 用户前台 | `src/client/main.tsx` | `index.html` | `/`        | 用户前台 |
+| 管理后台 | `src/admin/main.tsx`  | `admin.html` | `/admin/*` | 管理后台 |
+
+### Vite 配置
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      input: {
+        main: path.resolve(__dirname, 'index.html'),
+        admin: path.resolve(__dirname, 'admin.html'),
+      },
+    },
+  },
+  resolve: {
+    alias: {
+      '@shared': path.resolve(__dirname, 'src/shared'),
+      '@client': path.resolve(__dirname, 'src/client'),
+      '@server': path.resolve(__dirname, 'src/server'),
+      '@admin': path.resolve(__dirname, 'src/admin'),
+    },
+  },
+})
+```
+
+## 🎨 UI 组件库
+
+### Ant Design
+
+Admin 模块使用 **Ant Design** 作为 UI 组件库。
+
+**依赖**: `"antd": "^5.24.0"`
+
+### 全局配置
+
+```typescript
+// src/admin/AdminApp.tsx
+import { ConfigProvider } from 'antd'
+
+export const AdminApp: React.FC = () => {
+  return (
+    <ConfigProvider
+      theme={{
+        token: {
+          colorPrimary: '#1890ff',
+        },
+      }}
+    >
+      {/* ... */}
+    </ConfigProvider>
+  )
+}
+```
+
+### 常用组件
+
+| 组件      | 用途     |
+| --------- | -------- |
+| `Layout`  | 页面布局 |
+| `Menu`    | 导航菜单 |
+| `Form`    | 表单     |
+| `Table`   | 数据表格 |
+| `Card`    | 卡片容器 |
+| `Button`  | 按钮     |
+| `Input`   | 输入框   |
+| `Modal`   | 弹窗     |
+| `message` | 全局提示 |
+
+## 🔧 Admin 入口配置
+
+### AdminApp.tsx
+
+```typescript
+// src/admin/AdminApp.tsx
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
+import { ConfigProvider } from 'antd'
+import { AdminLayout } from './layouts/AdminLayout'
+import { DashboardPage } from './pages/DashboardPage'
+import { LoginPage } from './pages/LoginPage'
+import { RegisterPage } from './pages/RegisterPage'
+import { SettingsPage } from './pages/SettingsPage'
+
+export const AdminApp: React.FC = () => {
+  return (
+    <ConfigProvider theme={{ token: { colorPrimary: '#1890ff' } }}>
+      <BrowserRouter basename="/admin">
+        <Routes>
+          <Route path="/login" element={<LoginPage />} />
+          <Route path="/register" element={<RegisterPage />} />
+          <Route
+            path="/*"
+            element={
+              <AdminLayout>
+                <Routes>
+                  <Route path="/" element={<Navigate to="/dashboard" replace />} />
+                  <Route path="/dashboard" element={<DashboardPage />} />
+                  <Route path="/settings" element={<SettingsPage />} />
+                </Routes>
+              </AdminLayout>
+            }
+          />
+        </Routes>
+      </BrowserRouter>
+    </ConfigProvider>
+  )
+}
+```
+
+### main.tsx
+
+```typescript
+// src/admin/main.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { AdminApp } from './AdminApp'
+import '../client/index.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <AdminApp />
+  </React.StrictMode>
+)
+```
+
+## 📦 布局组件规范
+
+### 目录结构
+
+```
+layouts/
+├── AdminLayout.tsx     # 主布局（包含侧边栏和顶部导航）
+├── AdminSidebar.tsx    # 侧边栏组件
+└── AdminHeader.tsx     # 顶部导航组件
+```
+
+### AdminLayout.tsx
+
+```typescript
+// src/admin/layouts/AdminLayout.tsx
+import { ReactNode, useState } from 'react'
+import { AdminSidebar } from './AdminSidebar'
+import { AdminHeader } from './AdminHeader'
+
+interface AdminLayoutProps {
+  children: ReactNode
+}
+
+export const AdminLayout: React.FC<AdminLayoutProps> = ({ children }) => {
+  const [sidebarOpen, setSidebarOpen] = useState(true)
+
+  return (
+    <div className="flex h-screen bg-gray-100">
+      <AdminSidebar isOpen={sidebarOpen} />
+      <div className="flex-1 flex flex-col overflow-hidden">
+        <AdminHeader onToggleSidebar={() => setSidebarOpen(!sidebarOpen)} />
+        <main className="flex-1 overflow-y-auto p-6">
+          {children}
+        </main>
+      </div>
+    </div>
+  )
+}
+```
+
+## 📄 页面规范
+
+### 页面类型
+
+| 页面 | 路径         | 文件                | 说明       |
+| ---- | ------------ | ------------------- | ---------- |
+| 登录 | `/login`     | `LoginPage.tsx`     | 管理员登录 |
+| 注册 | `/register`  | `RegisterPage.tsx`  | 管理员注册 |
+| 首页 | `/dashboard` | `DashboardPage.tsx` | 仪表盘     |
+| 设置 | `/settings`  | `SettingsPage.tsx`  | 系统设置   |
+
+### 登录页面示例
+
+```typescript
+// src/admin/pages/LoginPage.tsx
+import { Form, Input, Button, Card, message } from 'antd'
+import { UserOutlined, LockOutlined } from '@ant-design/icons'
+import { useNavigate } from 'react-router-dom'
+
+export const LoginPage: React.FC = () => {
+  const navigate = useNavigate()
+  const [form] = Form.useForm()
+
+  const handleSubmit = async (values: any) => {
+    try {
+      console.log('Login:', values)
+      message.success('Login successful!')
+      navigate('/dashboard')
+    } catch (error) {
+      message.error('Login failed!')
+    }
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-100">
+      <Card className="w-full max-w-md" title="Admin Login">
+        <Form form={form} onFinish={handleSubmit} layout="vertical">
+          <Form.Item name="username" rules={[{ required: true }]}>
+            <Input prefix={<UserOutlined />} placeholder="Username" size="large" />
+          </Form.Item>
+          <Form.Item name="password" rules={[{ required: true }]}>
+            <Input.Password prefix={<LockOutlined />} placeholder="Password" size="large" />
+          </Form.Item>
+          <Form.Item>
+            <Button type="primary" htmlType="submit" size="large" block>
+              Login
+            </Button>
+          </Form.Item>
+        </Form>
+      </Card>
+    </div>
+  )
+}
+```
+
+## 🔐 权限控制
+
+### 路由守卫
+
+```typescript
+// src/admin/components/AuthGuard.tsx
+import { Navigate } from 'react-router-dom'
+import { useAdminStore } from '../stores/adminStore'
+
+interface AuthGuardProps {
+  children: React.ReactNode
+}
+
+export const AuthGuard: React.FC<AuthGuardProps> = ({ children }) => {
+  const { isAuthenticated, user } = useAdminStore()
+
+  if (!isAuthenticated) {
+    return <Navigate to="/admin/login" replace />
+  }
+
+  if (user?.role !== 'admin') {
+    return <Navigate to="/admin/unauthorized" replace />
+  }
+
+  return <>{children}</>
+}
+```
+
+### 使用守卫
+
+```typescript
+// src/admin/AdminApp.tsx
+export const AdminApp: React.FC = () => {
+  return (
+    <BrowserRouter basename="/admin">
+      <Routes>
+        <Route path="/login" element={<LoginPage />} />
+        <Route
+          path="/*"
+          element={
+            <AuthGuard>
+              <AdminLayout>
+                <Routes>...</Routes>
+              </AdminLayout>
+            </AuthGuard>
+          }
+        />
+      </Routes>
+    </BrowserRouter>
+  )
+}
+```
+
+## 📊 API 调用
+
+### 使用 admin API
+
+```typescript
+// src/admin/stores/adminStore.ts
+import { create } from 'zustand'
+import { apiClient } from '@client/services/apiClient'
+import type { SystemStats } from '@shared/schemas'
+
+interface AdminState {
+  stats: SystemStats | null
+  fetchStats: () => Promise<void>
+}
+
+export const useAdminStore = create<AdminState>(set => ({
+  stats: null,
+
+  fetchStats: async () => {
+    const response = await apiClient.api.admin.stats.$get()
+    const result = await response.json()
+    if (result.success) {
+      set({ stats: result.data })
+    }
+  },
+}))
+```
+
+## 🚫 禁止事项
+
+### 1. 禁止混用用户前台组件
+
+```typescript
+// ❌ 错误 - Admin 使用用户前台组件
+import { Navigation } from '@client/components/Navigation'
+
+// ✅ 正确 - Admin 使用自己的组件
+import { AdminSidebar } from './layouts/AdminSidebar'
+```
+
+### 2. 禁止共享状态
+
+```typescript
+// ❌ 错误 - Admin 使用用户前台 Store
+import { useTodoStore } from '@client/stores/todoStore'
+
+// ✅ 正确 - Admin 使用自己的 Store
+import { useAdminStore } from './stores/adminStore'
+```
+
+### 3. 禁止在 AdminApp 中定义布局
+
+```typescript
+// ❌ 错误 - AdminApp 包含布局逻辑
+export const AdminApp: React.FC = () => {
+  return (
+    <BrowserRouter>
+      <div className="flex h-screen">
+        <AdminSidebar />
+        <main>
+          <Routes>...</Routes>
+        </main>
+      </div>
+    </BrowserRouter>
+  )
+}
+
+// ✅ 正确 - AdminApp 只负责路由
+export const AdminApp: React.FC = () => {
+  return (
+    <BrowserRouter basename="/admin">
+      <AdminLayout>
+        <Routes>...</Routes>
+      </AdminLayout>
+    </BrowserRouter>
+  )
+}
+```
+
+## 📝 HTML 入口文件
+
+### admin.html
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Admin Dashboard</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/admin/main.tsx"></script>
+  </body>
+</html>
+```
+
+## 🎨 样式规范
+
+Admin 模块可以共享用户前台的样式：
+
+```typescript
+// src/admin/main.tsx
+import '../client/index.css' // 共享样式
+```
+
+也可以使用独立的样式：
+
+```typescript
+// src/admin/styles/admin.css
+.admin-sidebar {
+  width: 250px;
+  background: #1f2937;
+}
+```
+
+## 📚 相关文档
+
+- [App 入口规范](./33-client-app-entry.md) - 用户前台入口规范
+- [Client 组件规范](./30-client-components.md) - 用户前台组件规范
+- [Server Admin API](./20-server-api.md) - 服务端 Admin API

package/template/.claude/rules/35-cli-module.md

@@ -0,0 +1,259 @@
+---
+paths: src/cli/**/*
+---
+
+# CLI 模块规范
+
+## 📋 原则
+
+**CLI 是服务端的 RPC 客户端，通过命令行方式调用服务端 API。**
+
+## 📂 目录结构
+
+```
+src/cli/
+├── modules/                    # 业务模块（约定：一个模块一个目录）
+│   ├── todo/
+│   │   └── index.ts           # todo list/get/create/update/delete
+│   ├── notification/
+│   │   └── index.ts           # notification list/create/mark-read/delete
+│   ├── config/
+│   │   └── index.ts           # 配置管理
+│   └── index.ts               # 模块注册入口
+├── utils/
+│   ├── api.ts                 # baseUrl 管理 + getClient
+│   ├── logger.ts              # 日志模块（支持 verbose）
+│   ├── auto-command.ts        # 自动命令生成器
+│   └── index.ts
+├── rpc/
+│   ├── client.ts              # hc RPC 客户端
+│   └── index.ts
+└── index.ts                   # CLI 入口
+```
+
+## ✅ 命令结构
+
+### 嵌套命令格式
+
+```bash
+biomimic --help                    # 查看所有模块
+biomimic todo --help               # 查看 todo 模块命令
+biomimic todo create --help        # 查看 create 命令详情
+biomimic todo create --title "x"   # 执行命令
+```
+
+### 模块注册
+
+```typescript
+// src/cli/modules/todo/index.ts
+import { Command } from 'commander'
+import { registerAutoCommand, type RouteConfig } from '../../utils/auto-command'
+import { z } from '@hono/zod-openapi'
+
+const todoRoutes: RouteConfig[] = [
+  {
+    method: 'get',
+    path: '/todos',
+    command: 'list',
+    description: 'List all todos',
+  },
+  {
+    method: 'post',
+    path: '/todos',
+    command: 'create',
+    description: 'Create a new todo',
+    body: z.object({
+      title: z.string().min(1),
+      description: z.string().optional(),
+    }),
+  },
+]
+
+export function registerTodoCommands(program: Command) {
+  const todo = program.command('todo').description('Todo management commands')
+  for (const route of todoRoutes) {
+    registerAutoCommand(todo, route)
+  }
+}
+```
+
+## 🔧 RPC 客户端
+
+### 使用 hc 客户端
+
+```typescript
+// src/cli/rpc/client.ts
+import { hc } from 'hono/client'
+import type { AppType } from '@server/index'
+import { WSClientImpl } from '@shared/core/ws-client'
+import { SSEClientImpl } from '@shared/core/sse-client'
+
+export function createRPCClient(baseUrl: string) {
+  return hc<AppType>(baseUrl, {
+    webSocket: url => new WSClientImpl(url),
+    sse: url => new SSEClientImpl(url),
+  })
+}
+```
+
+### 调用 API
+
+```typescript
+// ✅ 正确：直接使用 hc 客户端
+const client = getClient()
+const res = await client.api.todos.$get()
+const data = await res.json()
+
+// ❌ 错误：不要使用 fetch
+const res = await fetch('http://localhost:3000/api/todos')
+```
+
+## 📝 自动命令生成
+
+### RouteConfig 定义
+
+```typescript
+type RouteConfig = {
+  method: 'get' | 'post' | 'put' | 'delete' | 'patch'
+  path: string
+  command: string
+  description: string
+  params?: ZodObject<Record<string, ZodType>> // 路径参数 -> arguments
+  body?: ZodType // 请求体 -> options
+  query?: ZodObject<Record<string, ZodType>> // 查询参数 -> options
+}
+```
+
+### 自动生成效果
+
+```bash
+$ biomimic todo create --help
+Usage: biomimic todo create [options]
+
+Create a new todo
+
+Options:
+  --title <value>        string (required)
+  --description <value>  string
+  -h, --help             display help for command
+```
+
+## 📊 日志规范
+
+```typescript
+import { getLogger } from '../utils/logger'
+
+const logger = getLogger()
+
+logger.info('普通信息') // 总是显示
+logger.debug('调试信息') // 需要 --verbose
+logger.warn('警告信息') // 总是显示
+logger.error('错误信息') // 总是显示
+logger.success('操作成功') // 带 ✓ 前缀
+```
+
+### 开启详细日志
+
+```bash
+# 通过 --verbose
+biomimic --verbose todo list
+
+# 通过环境变量
+BIOMIMIC_VERBOSE=true biomimic todo list
+```
+
+## ⚙️ 配置管理
+
+### 配置文件路径
+
+```
+~/.biomimic/config.json
+```
+
+### 配置结构
+
+```json
+{
+  "baseUrl": "http://localhost:3000",
+  "stats": {
+    "totalCalls": 10,
+    "lastCallAt": "2024-01-01T00:00:00Z",
+    "commands": {
+      "todo:list": 5,
+      "notification:create": 3
+    }
+  }
+}
+```
+
+### 配置命令
+
+```bash
+biomimic config get              # 查看配置
+biomimic config url              # 查看当前 URL
+biomimic config url http://...   # 设置 URL
+biomimic config status           # 检查服务状态
+biomimic config path             # 查看配置文件路径
+```
+
+## 🚫 禁止事项
+
+| 禁止             | 原因         | 替代方案         |
+| ---------------- | ------------ | ---------------- |
+| 使用 fetch       | 不走类型安全 | 使用 hc 客户端   |
+| 直接导入 Service | 绕过 RPC     | 通过 API 调用    |
+| 硬编码 URL       | 不可配置     | 使用 config 模块 |
+| 使用 console.log | 无法控制     | 使用 logger      |
+
+## 📝 新增模块步骤
+
+1. 在 `src/cli/modules/` 下创建目录
+2. 定义 `RouteConfig[]` 数组
+3. 实现 `registerXxxCommands(program: Command)` 函数
+4. 在 `modules/index.ts` 中注册
+
+## 🎯 最佳实践
+
+### 命令命名
+
+```typescript
+// ✅ 正确：动词作为子命令
+todo list, todo create, todo update, todo delete
+
+// ❌ 错误：名词作为子命令
+todo list-todo, create-todo
+```
+
+### 参数设计
+
+```typescript
+// ✅ 正确：必填参数用 argument
+.argument('<id>', 'Todo ID')
+
+// ✅ 正确：可选参数用 option
+.option('--title <value>', 'Todo title')
+
+// ✅ 正确：必填选项用 requiredOption
+.requiredOption('--title <value>', 'Todo title')
+```
+
+### 错误处理
+
+```typescript
+// ✅ 正确：使用 logger 并退出
+if (!id) {
+  logger.error('Error: --id is required')
+  process.exit(1)
+}
+
+// ❌ 错误：抛出异常
+if (!id) {
+  throw new Error('--id is required')
+}
+```
+
+## 🔗 相关文档
+
+- [20-server-api.md](./20-server-api.md) - 服务端 API 规范
+- [40-shared-types.md](./40-shared-types.md) - 共享类型规范
+- [10-api-type-inference.md](./10-api-type-inference.md) - API 类型推断