create-fullstack-scaffold 0.1.0

package/template/README.md

@@ -0,0 +1,154 @@
+# Todo Application Template
+
+A full-stack React + Hono application template with TypeScript, demonstrating best practices for monorepo-style architecture with single-port development.
+
+## Features
+
+- **Frontend**: React with TypeScript, Vite
+- **Backend**: Hono with TypeScript
+- **Database**: SQLite with Drizzle ORM
+- **State Management**: Zustand
+- **Real-time**: WebSocket + SSE support
+- **Testing**: Vitest (unit + integration tests)
+- **Code Quality**: ESLint, Prettier, pre-commit hooks
+- **Type Safety**: End-to-end type safety with Hono RPC
+
+## Architecture
+
+```
+src/
+├── client/          # React frontend
+│   ├── components/  # UI components
+│   ├── stores/     # Zustand state management
+│   ├── services/    # API clients (apiClient)
+│   ├── hooks/      # Custom hooks
+│   ├── pages/      # Page components
+│   └── App.tsx
+├── server/          # Hono backend
+│   ├── module-todos/     # Todo module
+│   ├── module-chat/      # WebSocket chat module
+│   ├── module-notifications/ # SSE notifications module
+│   ├── core/             # Core services (runtime, realtime)
+│   ├── middleware/       # Express middleware
+│   ├── test-utils/       # Test utilities
+│   └── entries/          # Entry points (node.ts, cloudflare.ts)
+└── shared/              # Shared types
+    ├── core/             # Framework layer (ws-client, sse-client)
+    ├── modules/          # Business layer (chat, todos, notifications)
+    └── schemas/          # Unified exports
+```
+
+## Getting Started
+
+### Installation
+
+```bash
+npm install
+```
+
+### Development
+
+```bash
+npm run dev
+```
+
+The application will be available at http://localhost:3010
+
+### Build
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests only
+npm run test:unit
+
+# Run integration tests only
+npm run test:integration
+```
+
+## Key Concepts
+
+### Path Aliases
+
+- `@shared/*` → src/shared/\*
+- `@client/*` → src/client/\*
+- `@server/*` → src/server/\*
+
+### Single-Port Development
+
+Uses "@hono/vite-dev-server" to run both frontend and backend on port 3010.
+
+### Framework Layer vs Business Layer
+
+The project has clear separation between framework and business layers:
+
+- **Framework Layer** (`src/shared/core/`): Generic, reusable infrastructure
+- **Business Layer** (`src/shared/modules/`): Business-specific schemas and protocols
+
+### Hono RPC
+
+Provides type-safe API calls from frontend to backend:
+
+```typescript
+import { apiClient } from '@client/services/apiClient'
+
+// HTTP API
+const response = await apiClient.api.todos.$get()
+const result = await response.json()
+
+// WebSocket
+const ws = apiClient.api.chat.ws.$ws()
+const result = await ws.call('echo', { message: 'hello' })
+
+// SSE
+const conn = await apiClient.api.notifications.stream.$sse()
+conn.on('notification', n => console.log(n))
+```
+
+### Real-time Features
+
+| Feature   | Method              | Type Safety | Testing          |
+| --------- | ------------------- | ----------- | ---------------- |
+| HTTP API  | `$get()`, `$post()` | ✅          | No server needed |
+| WebSocket | `$ws()`             | ✅          | Requires server  |
+| SSE       | `$sse()`            | ✅          | No server needed |
+
+### Module Structure
+
+Backend is organized by feature modules:
+
+- `module-todos/` - Todo CRUD
+- `module-chat/` - WebSocket chat
+- `module-notifications/` - SSE notifications
+
+Each module contains:
+
+- `routes/` - API endpoints
+- `services/` - Business logic
+- `__tests__/` - Unit tests
+
+## Pre-commit Hooks
+
+The project uses Husky for Git hooks:
+
+- **lint-staged** - Format staged files
+- **npm test** - Run test suite
+- **validate-all** - Custom validation script
+
+## Environment Variables
+
+See `.env.example` for required environment variables.
+
+## Documentation
+
+- `QUICKSTART.md` - Quick start guide
+- `DESIGN.md` - Technical architecture
+- `CLAUDE.md` - Development guidelines
+- `.claude/rules/` - Detailed development constraints

package/template/STRUCTURE.txt

@@ -0,0 +1,81 @@
+COMPLETE PROJECT STRUCTURE
+==========================
+
+template/
+├── .claude/
+│   └── rules/
+│       └── project-rules.md              # Development guidelines
+│
+├── .husky/
+│   ├── pre-commit                        # Git pre-commit hook
+│   └── _/
+│       └── husky.sh                      # Husky utilities
+│
+├── .vscode/
+│   └── extensions.json                   # VS Code recommendations
+│
+├── scripts/
+│   └── validate-all.ts                   # Pre-commit validation script
+│
+├── src/
+│   ├── client/                           # React Frontend
+│   │   ├── components/
+│   │   │   └── __tests__/
+│   │   │       └── App.test.tsx          # Component tests
+│   │   ├── stores/
+│   │   │   ├── todoStore.ts              # Zustand store
+│   │   │   └── __tests__/
+│   │   │       └── todoStore.test.ts     # Store tests
+│   │   ├── services/
+│   │   │   └── apiClient.ts              # Hono RPC client
+│   │   ├── test/
+│   │   │   ├── setup.ts                  # Vitest setup
+│   │   │   └── cleanup.ts                # Test utilities
+│   │   ├── App.tsx                       # Main Todo List component
+│   │   ├── main.tsx                      # React entry point
+│   │   └── index.css                     # Global styles
+│   │
+│   ├── server/                           # Hono Backend
+│   │   ├── module-todos/                 # Todo feature module
+│   │   │   ├── routes/
+│   │   │   │   └── todos-routes.ts       # API endpoints (Hono RPC)
+│   │   │   ├── services/
+│   │   │   │   └── todo-service.ts       # Business logic
+│   │   │   └── __tests__/
+│   │   │       └── todo-service.test.ts  # Service unit tests
+│   │   ├── shared/
+│   │   │   ├── db.ts                     # Database connection
+│   │   │   └── schema.ts                 # Drizzle ORM schema
+│   │   ├── integration/
+│   │   │   └── todos-api.test.ts         # API integration tests
+│   │   └── index.ts                      # Server entry point
+│   │
+│   ├── shared/                           # Shared Types
+│   │   ├── types.ts                      # TypeScript interfaces
+│   │   └── schemas.ts                    # Zod validation schemas
+│   │
+│   └── vite-env.d.ts                     # Vite type declarations
+│
+├── Configuration Files
+│   ├── package.json                      # Dependencies and scripts
+│   ├── vite.config.ts                    # Vite + Hono dev server
+│   ├── tsconfig.json                     # TypeScript config
+│   ├── vitest.config.ts                  # Unit test config
+│   ├── vitest.integration.config.ts      # Integration test config
+│   ├── eslint.config.js                  # ESLint rules
+│   ├── .prettierrc                       # Prettier config
+│   ├── .prettierignore                   # Prettier ignore
+│   ├── .gitignore                        # Git ignore patterns
+│   ├── .env.example                      # Environment variables template
+│   └── index.html                        # HTML entry point
+│
+└── Documentation
+    ├── README.md                          # User documentation
+    ├── QUICKSTART.md                      # Quick start guide
+    ├── DESIGN.md                          # Architecture documentation
+    ├── PROJECT_SUMMARY.md                 # Project summary
+    ├── CLAUDE.md                          # Claude Code guidelines
+    └── STRUCTURE.txt                      # This file
+
+TOTAL FILES: 40+
+================================================================================

package/template/admin.html

@@ -0,0 +1,13 @@
+<!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>

package/template/auth-inject.html

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html>
+<head><title>Auth Inject</title></head>
+<body>
+<script>
+localStorage.setItem('ops-storage', JSON.stringify({
+  "state": {
+    "user": {
+      "id": "1",
+      "username": "superadmin",
+      "email": "admin@biomimic.com",
+      "role": "super_admin",
+      "avatar": null,
+      "permissions": [
+        "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",
+        "dispute:view","dispute:create","dispute:edit","dispute:delete","dispute:resolve",
+        "notification:view","notification:create","notification:edit"
+      ]
+    },
+    "token": "fake-test-token-for-ui-testing",
+    "isAuthenticated": true
+  },
+  "version": 0
+}));
+window.location.href = '/ops/dashboard';
+</script>
+</body>
+</html>

package/template/commitlint.config.js

@@ -0,0 +1,12 @@
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2,
+      'always',
+      ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'revert'],
+    ],
+    'subject-max-length': [2, 'always', 80],
+    'body-max-line-length': [2, 'always', 200],
+  },
+}

package/template/docs/PERMISSION_ARCHITECTURE.md

@@ -0,0 +1,279 @@
+# 权限管理系统架构文档
+
+## 系统概述
+
+本权限管理系统采用 RBAC（基于角色的访问控制）模型，实现了细粒度的权限控制，支持按钮级别的显示/隐藏。
+
+## 核心概念
+
+### 1. 角色 (Role)
+
+系统定义了三种角色：
+
+- **超级管理员 (super_admin)**：拥有所有权限，可以管理用户、系统设置等
+- **客服人员 (customer_service)**：拥有订单处理、工单管理等客服相关权限
+- **普通用户 (user)**：只能查看基本内容
+
+### 2. 权限 (Permission)
+
+权限按照功能模块分类：
+
+- **用户管理**：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
+
+### 3. 权限检查模式
+
+- **单个权限检查**：检查用户是否拥有某个特定权限
+- **多权限检查（全部）**：用户必须拥有所有指定权限
+- **多权限检查（任一）**：用户只需拥有其中一个权限
+
+## 架构设计
+
+### 后端架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    API Routes                           │
+│  /api/admin/permissions/roles                          │
+│  /api/admin/permissions                                │
+│  /api/admin/permissions/me                             │
+└─────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│              Permission Service                         │
+│  - getAllRoles()                                        │
+│  - getAllPermissions()                                  │
+│  - getUserPermissions()                                 │
+│  - validatePermissions()                                │
+└─────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│           Auth Middleware                               │
+│  - authMiddleware()                                     │
+│  - requireSuperAdminMiddleware()                        │
+│  - requirePermissionsMiddleware()                       │
+└─────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│          Shared Permission Definitions                  │
+│  - Role enum                                            │
+│  - Permission enum                                      │
+│  - ROLE_PERMISSIONS mapping                             │
+│  - Permission helper functions                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 前端架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              PermissionProvider                         │
+│  - 提供权限上下文                                        │
+│  - 自动获取用户权限                                      │
+│  - 管理权限状态                                          │
+└─────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│              usePermissions Hook                        │
+│  - hasPermission()                                      │
+│  - hasAnyPermission()                                   │
+│  - hasAllPermissions()                                  │
+│  - refreshPermissions()                                 │
+└─────────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│          Permission Components                          │
+│  - PermissionGuard：基础权限控制组件                     │
+│  - Can：声明式权限组件                                   │
+│  - Cannot：反向权限组件                                  │
+│  - PermissionButton：权限按钮组件                        │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 数据流
+
+### 1. 用户登录流程
+
+```
+用户登录
+   ↓
+验证用户名密码
+   ↓
+获取用户角色
+   ↓
+根据角色获取权限列表
+   ↓
+生成 JWT Token（包含用户ID和角色）
+   ↓
+返回用户信息和权限
+```
+
+### 2. 权限检查流程
+
+```
+前端组件渲染
+   ↓
+调用 usePermissions Hook
+   ↓
+从 PermissionProvider 获取权限
+   ↓
+PermissionGuard 组件检查权限
+   ↓
+显示或隐藏组件
+```
+
+### 3. API 请求流程
+
+```
+前端发起请求
+   ↓
+携带 Token 到后端
+   ↓
+Auth Middleware 验证 Token
+   ↓
+提取用户信息和权限
+   ↓
+检查路由权限要求
+   ↓
+允许或拒绝访问
+```
+
+## 文件结构
+
+```
+template/
+├── src/
+│   ├── shared/
+│   │   └── modules/
+│   │       └── admin/
+│   │           ├── permissions.ts          # 权限定义和工具函数
+│   │           ├── schemas.ts              # 权限相关 Schema
+│   │           └── index.ts                # 导出
+│   ├── server/
+│   │   ├── middleware/
+│   │   │   └── auth.ts                     # 认证和权限中间件
+│   │   ├── module-admin/
+│   │   │   ├── routes/
+│   │   │   │   └── admin-routes.ts         # 权限 API 路由
+│   │   │   └── services/
+│   │   │       └── permission-service.ts   # 权限服务
+│   │   └── utils/
+│   │       └── auth.ts                     # 认证工具函数
+│   └── admin/
+│       ├── hooks/
+│       │   └── usePermissions.tsx          # 权限 Hook
+│       ├── components/
+│       │   └── PermissionGuard.tsx         # 权限组件
+│       ├── pages/
+│       │   └── PermissionsPage.tsx         # 权限管理页面
+│       └── config/
+│           └── permissions.ts              # 权限配置
+└── docs/
+    ├── PERMISSION_SYSTEM.md                # 使用文档
+    └── PERMISSION_EXAMPLES.md              # 示例文档
+```
+
+## 安全考虑
+
+### 1. 前后端双重验证
+
+- **前端**：控制UI显示，提升用户体验
+- **后端**：实际权限验证，确保安全
+
+### 2. 权限缓存
+
+- 前端缓存用户权限，减少API调用
+- 用户角色变更时自动刷新权限
+
+### 3. Token 安全
+
+- Token 包含用户ID和角色信息
+- Token 过期时间合理设置
+- 敏感操作需要重新验证
+
+## 扩展性
+
+### 1. 添加新权限
+
+1. 在 `permissions.ts` 中添加新权限枚举
+2. 在 `PERMISSION_LABELS` 中添加权限说明
+3. 在 `PERMISSION_CATEGORIES` 中归类权限
+4. 在 `ROLE_PERMISSIONS` 中为角色分配权限
+
+### 2. 添加新角色
+
+1. 在 `Role` 枚举中添加新角色
+2. 在 `ROLE_LABELS` 中添加角色说明
+3. 在 `ROLE_PERMISSIONS` 中定义角色权限
+
+### 3. 自定义权限检查
+
+```typescript
+// 自定义权限检查逻辑
+function customPermissionCheck(user: User, resource: string): boolean {
+  // 实现自定义逻辑
+  return true
+}
+```
+
+## 性能优化
+
+### 1. 前端优化
+
+- 使用 Context API 避免重复请求
+- 权限数据缓存在本地存储
+- 按需加载权限配置
+
+### 2. 后端优化
+
+- 权限数据缓存在内存中
+- 使用索引优化权限查询
+- 批量权限检查减少数据库查询
+
+## 测试策略
+
+### 1. 单元测试
+
+- 测试权限工具函数
+- 测试权限中间件
+- 测试权限组件
+
+### 2. 集成测试
+
+- 测试完整的权限检查流程
+- 测试不同角色的访问控制
+
+### 3. E2E 测试
+
+- 测试用户登录和权限获取
+- 测试权限控制的UI显示
+
+## 最佳实践
+
+1. **最小权限原则**：只授予必要的权限
+2. **双重验证**：前后端都要进行权限检查
+3. **明确提示**：无权限时提供友好的提示
+4. **定期审计**：定期检查和清理不必要的权限
+5. **文档维护**：及时更新权限文档
+
+## 监控和日志
+
+- 记录权限检查失败的操作
+- 监控权限相关的异常
+- 分析权限使用情况
+
+## 未来规划
+
+1. **动态权限**：支持运行时动态分配权限
+2. **权限组**：支持权限组管理
+3. **数据权限**：支持数据级别的权限控制
+4. **权限继承**：支持角色权限继承