create-fullstack-scaffold 0.1.0

package/template/docs/PERMISSION_EXAMPLES.md

@@ -0,0 +1,230 @@
+# 权限系统使用示例
+
+## 示例1：在页面中控制按钮显示
+
+```tsx
+import { PermissionGuard } from '@/admin/components/PermissionGuard'
+import { Permission } from '@shared/modules/admin'
+
+export const UserListPage = () => {
+  return (
+    <div>
+      <h1>用户列表</h1>
+
+      {/* 只有有创建用户权限的用户才能看到这个按钮 */}
+      <PermissionGuard permission={Permission.USER_CREATE}>
+        <button onClick={handleCreateUser}>创建用户</button>
+      </PermissionGuard>
+
+      <table>
+        <tbody>
+          {users.map(user => (
+            <tr key={user.id}>
+              <td>{user.name}</td>
+              <td>
+                {/* 只有有编辑权限的用户才能看到编辑按钮 */}
+                <PermissionGuard permission={Permission.USER_EDIT}>
+                  <button onClick={() => handleEdit(user)}>编辑</button>
+                </PermissionGuard>
+
+                {/* 只有有删除权限的用户才能看到删除按钮 */}
+                <PermissionGuard permission={Permission.USER_DELETE}>
+                  <button onClick={() => handleDelete(user)}>删除</button>
+                </PermissionGuard>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+```
+
+## 示例2：使用 Can 组件（声明式）
+
+```tsx
+import { Can, Cannot } from '@/admin/components/PermissionGuard'
+import { Permission } from '@shared/modules/admin'
+
+export const OrderDetailPage = () => {
+  return (
+    <div>
+      <h1>订单详情</h1>
+
+      {/* 有处理订单权限的用户可以看到操作按钮 */}
+      <Can I={Permission.ORDER_PROCESS}>
+        <button onClick={handleProcess}>处理订单</button>
+      </Can>
+
+      {/* 没有权限的用户看到提示 */}
+      <Cannot I={Permission.ORDER_PROCESS}>
+        <span className="text-gray-500">您没有处理订单的权限</span>
+      </Cannot>
+    </div>
+  )
+}
+```
+
+## 示例3：使用 Hooks 进行权限检查
+
+```tsx
+import { usePermissions, useHasPermission } from '@/admin/hooks/usePermissions'
+import { Permission } from '@shared/modules/admin'
+
+export const TicketPage = () => {
+  const { hasPermission, hasAnyPermission, role } = usePermissions()
+  const canReply = useHasPermission(Permission.TICKET_REPLY)
+  const canClose = useHasPermission(Permission.TICKET_CLOSE)
+
+  return (
+    <div>
+      <h1>工单详情</h1>
+
+      {/* 使用 hook 检查权限 */}
+      {canReply && <button onClick={handleReply}>回复工单</button>}
+
+      {canClose && <button onClick={handleClose}>关闭工单</button>}
+
+      {/* 显示当前用户角色 */}
+      <div className="text-sm text-gray-500">当前角色：{role}</div>
+    </div>
+  )
+}
+```
+
+## 示例4：多个权限检查
+
+```tsx
+import { PermissionGuard } from '@/admin/components/PermissionGuard'
+import { Permission } from '@shared/modules/admin'
+
+export const DataManagementPage = () => {
+  return (
+    <div>
+      <h1>数据管理</h1>
+
+      {/* 需要同时拥有导入和导出权限 */}
+      <PermissionGuard permissions={[Permission.DATA_IMPORT, Permission.DATA_EXPORT]} mode="all">
+        <div className="data-actions">
+          <button onClick={handleImport}>导入数据</button>
+          <button onClick={handleExport}>导出数据</button>
+        </div>
+      </PermissionGuard>
+
+      {/* 只要有任一权限就可以看到 */}
+      <PermissionGuard permissions={[Permission.DATA_IMPORT, Permission.DATA_EXPORT]} mode="any">
+        <div className="partial-actions">
+          {/* 根据具体权限显示不同按钮 */}
+          <PermissionGuard permission={Permission.DATA_IMPORT}>
+            <button onClick={handleImport}>导入</button>
+          </PermissionGuard>
+          <PermissionGuard permission={Permission.DATA_EXPORT}>
+            <button onClick={handleExport}>导出</button>
+          </PermissionGuard>
+        </div>
+      </PermissionGuard>
+    </div>
+  )
+}
+```
+
+## 示例5：后端路由权限保护
+
+```typescript
+import {
+  authMiddleware,
+  requireSuperAdminMiddleware,
+  requirePermissionsMiddleware,
+} from '../middleware/auth'
+import { Permission } from '@shared/modules/admin'
+
+// 只有超级管理员可以访问
+app.get('/api/admin/users', requireSuperAdminMiddleware(), async c => {
+  const users = await getUsers()
+  return c.json({ success: true, data: users })
+})
+
+// 需要特定权限
+app.post('/api/admin/users', requirePermissionsMiddleware(Permission.USER_CREATE), async c => {
+  const userData = await c.req.json()
+  const user = await createUser(userData)
+  return c.json({ success: true, data: user })
+})
+
+// 需要登录但不需要特定权限
+app.get('/api/admin/profile', authMiddleware(), async c => {
+  const user = getAuthUser(c)
+  return c.json({ success: true, data: user })
+})
+```
+
+## 示例6：根据角色显示不同内容
+
+```tsx
+import { usePermissions } from '@/admin/hooks/usePermissions'
+import { Role } from '@shared/modules/admin'
+
+export const DashboardPage = () => {
+  const { role, permissions } = usePermissions()
+
+  return (
+    <div>
+      <h1>仪表盘</h1>
+
+      {/* 根据角色显示不同内容 */}
+      {role === Role.SUPER_ADMIN && (
+        <div className="admin-panel">
+          <h2>管理员面板</h2>
+          {/* 管理员专属功能 */}
+        </div>
+      )}
+
+      {role === Role.CUSTOMER_SERVICE && (
+        <div className="customer-service-panel">
+          <h2>客服面板</h2>
+          {/* 客服专属功能 */}
+        </div>
+      )}
+
+      {role === Role.USER && (
+        <div className="user-panel">
+          <h2>用户面板</h2>
+          {/* 普通用户功能 */}
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+## 示例7：权限检查工具函数
+
+```typescript
+import { hasPermission, hasAllPermissions } from '@shared/modules/admin'
+import { Permission } from '@shared/modules/admin'
+
+// 在组件外部使用
+function canUserPerformAction(userPermissions: Permission[], action: string): boolean {
+  const permissionMap: Record<string, Permission[]> = {
+    'create-user': [Permission.USER_CREATE],
+    'delete-user': [Permission.USER_DELETE],
+    'manage-orders': [Permission.ORDER_VIEW, Permission.ORDER_PROCESS],
+  }
+
+  const requiredPermissions = permissionMap[action]
+  if (!requiredPermissions) return false
+
+  return hasAllPermissions(userPermissions, requiredPermissions)
+}
+```
+
+## 测试账号
+
+为了测试权限系统，可以使用以下测试账号：
+
+- **超级管理员**：用户名 `superadmin`，密码 `123456`
+- **客服人员**：用户名 `customerservice`，密码 `123456`
+- **普通用户**：用户名 `user1`，密码 `123456`
+
+登录后访问 `/admin/permissions` 页面可以查看当前用户的权限信息。

package/template/docs/PERMISSION_SYSTEM.md

@@ -0,0 +1,301 @@
+# 权限管理系统使用指南
+
+## 概述
+
+本系统实现了完整的RBAC（基于角色的访问控制）权限管理，支持三种角色：超级管理员、客服人员和普通用户。
+
+## 角色定义
+
+### 1. 超级管理员 (super_admin)
+
+- 拥有所有权限
+- 可以管理用户、内容、系统设置等
+- 可以查看系统日志和监控
+
+### 2. 客服人员 (customer_service)
+
+- 查看用户信息
+- 查看和处理订单
+- 查看和回复工单
+- 导出数据
+- 查看系统日志
+
+### 3. 普通用户 (user)
+
+- 查看基本内容
+- 查看自己的订单
+
+## 权限分类
+
+### 用户管理权限
+
+- `user:view` - 查看用户
+- `user:create` - 创建用户
+- `user:edit` - 编辑用户
+- `user:delete` - 删除用户
+
+### 内容管理权限
+
+- `content:view` - 查看内容
+- `content:create` - 创建内容
+- `content:edit` - 编辑内容
+- `content:delete` - 删除内容
+
+### 系统管理权限
+
+- `system:settings` - 系统设置
+- `system:logs` - 查看日志
+- `system:monitor` - 系统监控
+
+### 数据管理权限
+
+- `data:export` - 数据导出
+- `data:import` - 数据导入
+
+### 订单管理权限
+
+- `order:view` - 查看订单
+- `order:process` - 处理订单
+
+### 工单管理权限
+
+- `ticket:view` - 查看工单
+- `ticket:reply` - 回复工单
+- `ticket:close` - 关闭工单
+
+## 前端使用方法
+
+### 1. 使用 PermissionGuard 组件
+
+```tsx
+import { PermissionGuard } from '@/admin/components/PermissionGuard'
+import { Permission } from '@shared/modules/admin'
+
+// 单个权限检查
+<PermissionGuard permission={Permission.USER_CREATE}>
+  <button>创建用户</button>
+</PermissionGuard>
+
+// 多个权限检查（需要全部权限）
+<PermissionGuard permissions={[Permission.USER_EDIT, Permission.USER_DELETE]}>
+  <div>
+    <button>编辑</button>
+    <button>删除</button>
+  </div>
+</PermissionGuard>
+
+// 多个权限检查（满足任一权限）
+<PermissionGuard
+  permissions={[Permission.USER_EDIT, Permission.USER_DELETE]}
+  mode="any"
+>
+  <div>操作区域</div>
+</PermissionGuard>
+
+// 设置无权限时的回退内容
+<PermissionGuard
+  permission={Permission.USER_DELETE}
+  fallback={<span>无权限</span>}
+>
+  <button>删除用户</button>
+</PermissionGuard>
+```
+
+### 2.使用 Can 组件（声明式）
+
+```tsx
+import { Can, Cannot } from '@/admin/components/PermissionGuard'
+import { Permission } from '@shared/modules/admin'
+
+// 有权限时显示
+<Can I={Permission.USER_CREATE}>
+  <button>创建用户</button>
+</Can>
+
+// 无权限时显示
+<Cannot I={Permission.USER_DELETE}>
+  <span>您没有删除权限</span>
+</Cannot>
+
+// 多个权限
+<Can I={[Permission.USER_EDIT, Permission.USER_DELETE]} mode="all">
+  <div>操作区域</div>
+</Can>
+```
+
+### 3. 使用 Hooks
+
+```tsx
+import { usePermissions, useHasPermission } from '@/admin/hooks/usePermissions'
+import { Permission } from '@shared/modules/admin'
+
+function MyComponent() {
+  const {
+    permissions, // 当前用户所有权限
+    role, // 当前用户角色
+    hasPermission, // 检查单个权限
+    hasAnyPermission, // 检查任一权限
+    hasAllPermissions, // 检查全部权限
+  } = usePermissions()
+
+  // 方式1：直接使用函数
+  if (hasPermission(Permission.USER_CREATE)) {
+    // 有权限
+  }
+
+  // 方式2：使用 hook
+  const canCreate = useHasPermission(Permission.USER_CREATE)
+
+  return <div>{canCreate && <button>创建用户</button>}</div>
+}
+```
+
+### 4. 在页面中使用
+
+```tsx
+import { PermissionGuard } from '@/admin/components/PermissionGuard'
+import { Permission } from '@shared/modules/admin'
+
+export const UsersPage: React.FC = () => {
+  return (
+    <div>
+      <div className="flex justify-between items-center mb-6">
+        <h1>用户管理</h1>
+        <PermissionGuard permission={Permission.USER_CREATE}>
+          <button>添加用户</button>
+        </PermissionGuard>
+      </div>
+
+      <table>
+        <tbody>
+          {users.map(user => (
+            <tr key={user.id}>
+              <td>{user.name}</td>
+              <td>
+                <PermissionGuard permission={Permission.USER_EDIT}>
+                  <button>编辑</button>
+                </PermissionGuard>
+                <PermissionGuard permission={Permission.USER_DELETE}>
+                  <button>删除</button>
+                </PermissionGuard>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+```
+
+## 后端使用方法
+
+### 1. 在路由中使用权限中间件
+
+```typescript
+import {
+  authMiddleware,
+  requireSuperAdminMiddleware,
+  requirePermissionsMiddleware,
+} from '../middleware/auth'
+import { Permission } from '@shared/modules/admin'
+
+// 要求超级管理员权限
+app.get('/admin/users', requireSuperAdminMiddleware(), async c => {
+  // 只有超级管理员可以访问
+})
+
+// 要求特定权限
+app.post('/admin/users', requirePermissionsMiddleware(Permission.USER_CREATE), async c => {
+  // 只有有 user:create 权限的用户可以访问
+})
+
+// 要求多个权限（全部）
+app.delete('/admin/users/:id', requirePermissionsMiddleware(Permission.USER_DELETE), async c => {
+  // 只有有 user:delete 权限的用户可以访问
+})
+```
+
+### 2. 获取当前用户权限
+
+```typescript
+import { getAuthUser } from '../utils/auth'
+
+app.get('/admin/some-route', authMiddleware(), async c => {
+  const user = getAuthUser(c)
+  // user.permissions 包含用户所有权限
+  // user.role 是用户角色
+
+  if (user.permissions.includes(Permission.USER_DELETE)) {
+    // 有删除权限
+  }
+})
+```
+
+## API 接口
+
+### 获取所有角色
+
+```
+GET /api/admin/permissions/roles
+```
+
+### 获取所有权限
+
+```
+GET /api/admin/permissions
+```
+
+### 获取当前用户权限
+
+```
+GET /api/admin/permissions/me
+```
+
+## 测试账号
+
+- 超级管理员：用户名 `superadmin`，密码 `123456`
+- 客服人员：用户名 `customerservice`，密码 `123456`
+- 普通用户：用户名 `user1`，密码 `123456`
+
+## 权限配置文件
+
+权限配置位于 `src/admin/config/permissions.ts`，可以配置每个页面和操作所需的权限。
+
+```typescript
+export const PAGE_PERMISSIONS: PagePermissionConfig[] = [
+  {
+    path: '/admin/users',
+    label: '用户管理',
+    requiredPermissions: [Permission.USER_VIEW],
+    actions: [
+      {
+        key: 'create',
+        label: '创建用户',
+        permissions: [Permission.USER_CREATE],
+        mode: 'all',
+      },
+      // ...
+    ],
+  },
+  // ...
+]
+```
+
+## 最佳实践
+
+1. **最小权限原则**：只授予用户完成工作所需的最小权限
+2. **权限检查**：在前端和后端都要进行权限检查
+3. **用户体验**：无权限时提供友好的提示信息
+4. **权限分组**：按功能模块组织权限
+5. **定期审计**：定期检查和清理不必要的权限
+
+## 扩展权限
+
+如果需要添加新的权限：
+
+1. 在 `src/shared/modules/admin/permissions.ts` 中添加新的权限枚举
+2. 在 `PERMISSION_LABELS` 中添加权限说明
+3. 在 `PERMISSION_CATEGORIES` 中将权限归类
+4. 在 `ROLE_PERMISSIONS` 中为各角色分配权限
+5. 更新相关页面和路由的权限检查

package/template/docs/SMART_TEST.md

@@ -0,0 +1,171 @@
+# Smart Test Runner
+
+智能测试运行器，只运行与改动文件相关的测试。
+
+## 功能特性
+
+- 🔍 **智能依赖分析**：自动分析文件依赖关系，找到相关的测试
+- 🏗️ **架构测试过滤**：支持只运行底层架构测试
+- 📦 **业务测试隔离**：避免运行业务逻辑测试
+- ⚡ **快速反馈**：只运行必要的测试，节省时间
+
+## 使用方法
+
+### 1. 智能测试（推荐）
+
+自动检测改动文件，只运行相关测试：
+
+```bash
+npm run test:smart
+```
+
+### 2. 只测试已暂存的文件
+
+在 commit 前运行，只测试已 `git add` 的文件：
+
+```bash
+npm run test:smart:staged
+```
+
+### 3. 只运行架构测试
+
+只运行数据库、配置等底层架构测试：
+
+```bash
+npm run test:infrastructure
+```
+
+### 4. 运行所有测试
+
+```bash
+npm run test:all
+```
+
+## 工作原理
+
+### 依赖图构建
+
+```
+源文件 A → 导入 → 模块 B → 导入 → 模块 C
+                                    ↓
+                              测试文件 X
+```
+
+当修改 `模块 B` 时，脚本会：
+1. 分析 `模块 B` 被哪些文件导入
+2. 找到依赖 `模块 B` 的测试文件
+3. 只运行这些相关测试
+
+### 架构测试识别
+
+以下文件会被识别为架构测试：
+- `/db/` - 数据库相关
+- `/config` - 配置文件
+- `/driver` - 数据库驱动
+- `/test-setup` - 测试设置
+- `vitest.setup` - Vitest 配置
+
+## Pre-commit Hook
+
+已集成到 `.husky/pre-commit`，每次 commit 前自动运行：
+
+```bash
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+echo "Running TypeScript type check..."
+npm run typecheck
+
+npx lint-staged
+
+echo "Running smart tests for changed files..."
+npm run test:smart:staged
+```
+
+## 示例场景
+
+### 场景 1：修改数据库配置
+
+```bash
+# 修改了 src/server/db/driver.ts
+npm run test:smart
+
+# 输出：
+🔍 Analyzing changes...
+📝 Changed files:
+  - src/server/db/driver.ts
+
+🎯 Running related tests:
+  🏗️  [Infrastructure] src/server/module-todos/__tests__/todo-service.test.ts
+  🏗️  [Infrastructure] src/server/module-todos/__tests__/todos-route.test.ts
+  🏗️  [Infrastructure] src/server/integration/todos-api.test.ts
+```
+
+### 场景 2：修改业务组件
+
+```bash
+# 修改了 src/client/components/App.tsx
+npm run test:smart
+
+# 输出：
+🔍 Analyzing changes...
+📝 Changed files:
+  - src/client/components/App.tsx
+
+🎯 Running related tests:
+  📦 [Business] src/client/components/__tests__/App.test.tsx
+```
+
+### 场景 3：修改共享类型
+
+```bash
+# 修改了 src/shared/schemas/todos.ts
+npm run test:smart
+
+# 输出：
+🔍 Analyzing changes...
+📝 Changed files:
+  - src/shared/schemas/todos.ts
+
+🎯 Running related tests:
+  📦 [Business] src/client/stores/__tests__/todoStore.test.ts
+  🏗️  [Infrastructure] src/server/module-todos/__tests__/todo-service.test.ts
+  🏗️  [Infrastructure] src/server/module-todos/__tests__/todos-route.test.ts
+```
+
+## 性能对比
+
+| 场景 | 全量测试 | 智能测试 | 提升 |
+|------|---------|---------|------|
+| 修改单个组件 | 33 tests | 1-3 tests | 90%+ |
+| 修改数据库配置 | 33 tests | 3-5 tests | 85%+ |
+| 修改共享类型 | 33 tests | 5-10 tests | 70%+ |
+
+## 注意事项
+
+1. **首次运行**：如果没有改动文件，会提示 "No changes detected"
+2. **新增文件**：新增的文件需要先 `git add` 才会被检测到
+3. **删除文件**：删除的文件不会触发测试
+4. **依赖分析**：只分析相对路径导入和 `@shared/`、`@client/`、`@server/` 别名
+
+## 故障排查
+
+### 问题：没有检测到相关测试
+
+**原因**：可能是导入路径使用了绝对路径或其他别名
+
+**解决**：检查导入语句，确保使用相对路径或已配置的别名
+
+### 问题：运行了不相关的测试
+
+**原因**：依赖链中存在间接引用
+
+**解决**：这是正常的，确保了代码改动的安全性
+
+## 扩展配置
+
+可以在 `scripts/smart-test.ts` 中自定义：
+
+- 添加新的架构测试模式
+- 调整依赖分析逻辑
+- 添加更多测试文件匹配规则