first commit

2026-07-25 15:42:10 +08:00
commit e302f4dfe4
250 changed files with 24504 additions and 0 deletions
@@ -0,0 +1,109 @@
+# shadcn-admin-template
+
+一个开箱即用的 React 管理后台模板，基于 shadcn/ui、Tailwind CSS v4、TanStack Router、TanStack Query 和 Vite 构建。
+
+本模板保留了通用后台常见页面和交互示例，并补充了一组可复用的后台组件样式，用于快速启动新的管理端项目。
+
+![preview](public/images/shadcn-admin.png)
+
+## 特性
+
+- React 19 + Vite 8 + TypeScript
+- Tailwind CSS v4 + shadcn/ui + Radix UI
+- TanStack Router 文件路由
+- TanStack Query 数据请求状态管理
+- TanStack Table 示例表格
+- Clerk 认证示例
+- 明暗主题、RTL、布局模式配置
+- Dashboard、Tasks、Users、Apps、Chats、Settings、Errors 等示例页面
+- Components 示例页，集中展示后台通用组件和样式 token
+- 可直接用于 SPA 部署，已包含 Netlify fallback 配置
+
+## 新增模板组件
+
+`src/components/admin/` 提供了从实际后台项目中抽象出来的通用组件：
+
+- `StatusBadge`：语义化状态徽章，支持 `success`、`warning`、`info`、`danger`、`neutral`
+- `AdminActionDialog`：带状态色、图标、loading 态的确认弹窗
+- `AdminRowActionsMenu`：表格行操作菜单
+- `BatchOperationsToolbar`：批量操作工具栏
+- `EntityDetailSheet`：实体详情抽屉
+- `SelectableList`：带搜索和勾选状态的列表
+- `EntityRef` / `ResourcePreview`：实体和资源预览展示
+
+对应的状态色 token 和后台布局 class 位于：
+
+- `src/styles/theme.css`
+- `src/styles/index.css`
+
+进入 `/components` 可查看这些组件的使用示例。
+
+## 目录结构
+
+```txt
+src/
+├── assets/          # 图标与静态资源
+├── components/      # 通用组件与 shadcn/ui primitive
+│   ├── admin/       # 后台业务无关组件
+│   ├── data-table/  # 表格组件
+│   ├── layout/      # 应用布局
+│   └── ui/          # shadcn/ui 组件
+├── context/         # 主题、布局、搜索等上下文
+├── features/        # 页面级功能模块
+├── hooks/           # 通用 hooks
+├── lib/             # 工具函数
+├── routes/          # TanStack Router 文件路由
+├── stores/          # Zustand store
+└── styles/          # 全局样式与主题 token
+```
+
+## 本地开发
+
+安装依赖：
+
+```bash
+pnpm install
+```
+
+启动开发服务：
+
+```bash
+pnpm dev
+```
+
+构建生产版本：
+
+```bash
+pnpm build
+```
+
+检查代码：
+
+```bash
+pnpm lint
+```
+
+## 环境变量
+
+复制 `.env.example` 为 `.env.local`，按需配置：
+
+```bash
+VITE_CLERK_PUBLISHABLE_KEY=
+```
+
+如果暂时不用 Clerk，可以保留为空，但 Clerk 相关页面需要有效 key 才能完整运行。
+
+## pnpm 构建脚本说明
+
+`pnpm-workspace.yaml` 中的 `allowBuilds` 用于批准 `@swc/core`、`esbuild`、`@clerk/shared` 的安装脚本，避免 pnpm v10/v11 在非交互环境中因为未批准 build scripts 而中断安装。
+
+## 关于配置文件
+
+- `netlify.toml`：Netlify 部署 SPA 时的 history fallback 配置，保留为可选部署配置。
+- `knip.config.ts`：`pnpm knip` 使用的未使用代码检查配置，保留。
+- `components.json`：shadcn/ui CLI 配置，保留。
+- `.prettierrc` / `eslint.config.js`：格式化和 lint 配置，保留。
+
+## License
+
+本模板基于 MIT 协议项目衍生，保留原始许可证信息。详见 `LICENSE`。