zt-admin-template 1.0.0

package/template/React_Antd_TS_Tutorial.md

@@ -0,0 +1,279 @@
+# React + Ant Design + TypeScript 项目实战教程
+
+本教程基于当前项目，详细讲解如何构建一个基于 React 19、TypeScript、Vite 和 Ant Design 6 的后台管理系统雏形。
+
+## 1. 技术栈
+
+-   **构建工具**: [Vite](https://vitejs.dev/)
+-   **前端框架**: [React](https://react.dev/) (v19)
+-   **编程语言**: [TypeScript](https://www.typescriptlang.org/)
+-   **UI 组件库**: [Ant Design](https://ant.design/) (v6)
+-   **路由管理**: [React Router](https://reactrouter.com/) (v7)
+-   **状态管理**: React Context API
+
+## 2. 项目初始化
+
+如果你是从零开始，可以使用 Vite 快速创建一个 React + TypeScript 项目：
+
+```bash
+# 创建项目
+npm create vite@latest admin-system -- --template react-ts
+
+# 进入项目目录
+cd admin-system
+
+# 安装依赖
+npm install
+```
+
+### 安装项目所需依赖
+
+安装 Ant Design、图标库和路由：
+
+```bash
+npm install antd @ant-design/icons react-router-dom
+```
+
+## 3. 项目结构
+
+建议的目录结构如下：
+
+```
+src/
+├── assets/          # 静态资源
+├── components/      # 公共组件 (Layout, Header, etc.)
+├── contexts/        # 全局上下文 (Context)
+├── pages/           # 页面组件 (Dashboard, Users, etc.)
+├── App.tsx          # 根组件
+├── main.tsx         # 入口文件
+└── vite-env.d.ts    # Vite 类型定义
+```
+
+## 4. 核心功能实现
+
+### 4.1 入口文件配置 (`src/main.tsx`)
+
+配置 `BrowserRouter` 用于路由管理，并使用 `StrictMode` 包裹应用。
+
+```tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </StrictMode>
+)
+```
+
+### 4.2 全局状态管理 - ThemeContext (`src/contexts/ThemeContext.tsx`)
+
+使用 Context API 实现主题切换，并结合 TypeScript 定义类型安全接口。
+
+```tsx
+import { createContext, useContext, useState, ReactNode } from "react";
+
+// 定义 Context 的数据类型
+interface ThemeContextType {
+    theme: string;
+    toggleTheme: () => void;
+}
+
+// 创建 Context 并提供默认值
+const ThemeContext = createContext<ThemeContextType>({
+    theme: "light",
+    toggleTheme: () => { }
+})
+
+interface ThemeProviderProps {
+    children: ReactNode;
+}
+
+// Provider 组件
+export function ThemeProvider({ children }: ThemeProviderProps) {
+    const [theme, setTheme] = useState<string>("light");
+
+    const toggleTheme = () => {
+        setTheme(prev => prev === "light" ? "dark" : "light");
+    }
+
+    return (
+        <ThemeContext.Provider value={{ theme, toggleTheme }}>
+            {children}
+        </ThemeContext.Provider>
+    );
+}
+
+// 自定义 Hook 方便使用
+export function useTheme(){
+    return useContext(ThemeContext)
+}
+```
+
+### 4.3 布局组件 - Ant Design Layout (`src/components/MainLayout.tsx`)
+
+使用 Ant Design 的 `Layout` 和 `Menu` 组件构建侧边栏布局。注意 TypeScript 类型的使用。
+
+```tsx
+import React, { useState } from 'react';
+import { Layout, Menu, theme } from 'antd';
+import { PieChartOutlined, UserOutlined } from '@ant-design/icons';
+import { Outlet, useNavigate, useLocation } from 'react-router-dom';
+import type { MenuProps } from 'antd';
+
+const { Header, Content, Footer, Sider } = Layout;
+
+// 定义菜单项类型助手函数
+type MenuItem = Required<MenuProps>['items'][number];
+
+function getItem(
+  label: React.ReactNode,
+  key: React.Key,
+  icon?: React.ReactNode,
+  children?: MenuItem[],
+): MenuItem {
+  return { key, icon, children, label } as MenuItem;
+}
+
+const items: MenuItem[] = [
+  getItem('Dashboard', '/', <PieChartOutlined />),
+  getItem('Users', '/users', <UserOutlined />),
+];
+
+const MainLayout: React.FC = () => {
+  const [collapsed, setCollapsed] = useState(false);
+  const { token: { colorBgContainer } } = theme.useToken();
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  return (
+    <Layout style={{ minHeight: '100vh' }}>
+      <Sider collapsible collapsed={collapsed} onCollapse={setCollapsed}>
+        <Menu 
+            theme="dark" 
+            defaultSelectedKeys={['/']} 
+            selectedKeys={[location.pathname]}
+            mode="inline" 
+            items={items} 
+            onClick={({ key }) => navigate(key)}
+        />
+      </Sider>
+      <Layout>
+        <Header style={{ padding: 0, background: colorBgContainer }} />
+        <Content style={{ margin: '16px' }}>
+          {/* Outlet 用于渲染子路由 */}
+          <Outlet />
+        </Content>
+      </Layout>
+    </Layout>
+  );
+};
+
+export default MainLayout;
+```
+
+### 4.4 数据展示页面 - Ant Design Table (`src/pages/Users.tsx`)
+
+使用 TypeScript 定义表格列（`ColumnsType`）和数据源（`DataType`）的类型。
+
+```tsx
+import React from 'react';
+import { Table, Tag, Space } from 'antd';
+import type { ColumnsType } from 'antd/es/table';
+
+// 定义数据类型接口
+interface DataType {
+  key: string;
+  name: string;
+  age: number;
+  tags: string[];
+}
+
+// 定义列配置，泛型指定为 DataType
+const columns: ColumnsType<DataType> = [
+  {
+    title: 'Name',
+    dataIndex: 'name',
+    key: 'name',
+    render: (text) => <a>{text}</a>,
+  },
+  // ... 其他列
+];
+
+const data: DataType[] = [
+  { key: '1', name: 'John Brown', age: 32, tags: ['developer'] },
+];
+
+const Users: React.FC = () => {
+  return (
+    <div>
+      <h2>Users Management</h2>
+      <Table columns={columns} dataSource={data} />
+    </div>
+  );
+};
+
+export default Users;
+```
+
+### 4.5 路由配置与组件组合 (`src/App.tsx`)
+
+虽然当前 `App.tsx` 主要是为了演示 Context 的使用，但通常我们会在这里配置路由。
+
+```tsx
+import React from 'react';
+import Child from './components/Child';
+import { ThemeProvider } from './contexts/ThemeContext';
+
+const App: React.FC = () => {
+  return (
+    <ThemeProvider>
+      <Child />
+    </ThemeProvider>
+  );
+};
+
+export default App;
+```
+
+*注意：如果需要启用完整路由，可以将 `App.tsx` 中的 `<ThemeProvider>` 替换为 `<Routes>` 配置，如代码注释所示。*
+
+## 5. 运行与构建
+
+### 开发模式
+
+```bash
+npm run dev
+```
+
+### 构建生产版本
+
+TypeScript 项目构建时会先进行类型检查 (`tsc -b`)。
+
+```bash
+npm run build
+```
+
+## 6. TypeScript 开发技巧
+
+1.  **组件 Props 类型**: 总是为组件 Props 定义接口。
+    ```tsx
+    interface MyComponentProps {
+        title: string;
+        isActive?: boolean; // 可选属性
+    }
+    const MyComponent: React.FC<MyComponentProps> = ({ title, isActive }) => { ... }
+    ```
+
+2.  **事件处理类型**: React 提供了丰富的事件类型。
+    ```tsx
+    const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+        console.log(event.target.value);
+    }
+    ```
+
+3.  **Ant Design 类型**: 从 `antd` 或子路径导入组件特定的类型（如 `ColumnsType`, `MenuProps`），这能提供极好的代码补全和类型检查。

package/template/START_ALL.md

@@ -0,0 +1,163 @@
+# 完整启动指南
+
+## 一键启动所有服务
+
+### 方式一：分别启动（推荐）
+
+#### 1. 启动后端服务器（新终端窗口）
+```bash
+cd koa-server
+npm install
+npm run dev
+```
+
+后端服务器将在 `http://localhost:8080` 启动
+
+#### 2. 启动前端应用（新终端窗口）
+```bash
+npm install
+npm run dev
+```
+
+前端应用将在 `http://localhost:5173` 启动
+
+### 方式二：使用 npm 脚本
+
+在项目根目录创建启动脚本（Windows）：
+
+**start-all.bat**
+```batch
+@echo off
+start cmd /k "cd koa-server && npm install && npm run dev"
+timeout /t 3
+start cmd /k "npm install && npm run dev"
+```
+
+然后运行：
+```bash
+start-all.bat
+```
+
+### 方式三：使用 PowerShell
+
+```powershell
+# 启动后端
+Start-Process powershell -ArgumentList "cd koa-server; npm install; npm run dev"
+
+# 等待3秒
+Start-Sleep -Seconds 3
+
+# 启动前端
+Start-Process powershell -ArgumentList "npm install; npm run dev"
+```
+
+## 验证服务
+
+### 检查后端服务
+```bash
+curl http://localhost:8080/health
+```
+
+应该返回：
+```json
+{"status":"ok"}
+```
+
+### 检查前端应用
+访问 `http://localhost:5173`
+
+## 环境配置
+
+### 开发环境
+- 前端 API 地址：`http://localhost:8080`
+- 配置文件：`.env.development`
+
+### 测试环境
+- 前端 API 地址：`http://localhost:8081`
+- 配置文件：`.env.test`
+- 构建命令：`npm run build:test`
+
+### 生产环境
+- 前端 API 地址：`http://47.113.230.113`
+- 配置文件：`.env.production`
+- 构建命令：`npm run build`
+
+## 常见问题
+
+### 端口被占用
+如果 8080 端口被占用，修改 `koa-server/app.js` 中的端口号：
+```javascript
+const port = 8080; // 改为其他端口，如 8081
+```
+
+### 跨域问题
+后端已配置 CORS，如果仍有问题，检查 `koa-server/app.js` 中的 CORS 配置
+
+### API 请求失败
+1. 确保后端服务已启动
+2. 检查 `.env.development` 中的 API 地址
+3. 查看浏览器控制台的错误信息
+
+## 测试流程
+
+1. **启动后端服务**
+   ```bash
+   cd koa-server && npm run dev
+   ```
+
+2. **启动前端应用**
+   ```bash
+   npm run dev
+   ```
+
+3. **访问应用**
+   - 打开 `http://localhost:5173`
+   - 点击左侧菜单"系统管理"
+   - 选择"用户管理"、"角色管理"或"菜单管理"
+
+4. **测试功能**
+   - 新增：点击"新增"按钮
+   - 编辑：点击编辑图标
+   - 删除：点击删除图标
+   - 搜索：输入搜索条件点击"搜索"
+
+## 生产部署
+
+### 前端构建
+```bash
+npm run build
+```
+
+生成的文件在 `dist` 目录
+
+### 后端部署
+```bash
+cd koa-server
+npm install --production
+npm start
+```
+
+## 监控和日志
+
+### 前端日志
+打开浏览器开发者工具（F12）查看控制台日志
+
+### 后端日志
+后端服务启动时会输出日志信息
+
+## 性能优化
+
+### 前端
+- 使用 `npm run build` 进行生产构建
+- 启用代码分割和懒加载
+
+### 后端
+- 使用 PM2 进行进程管理
+- 配置负载均衡
+
+## 下一步
+
+1. 集成数据库（MongoDB/MySQL）
+2. 实现用户认证和授权
+3. 添加操作日志
+4. 性能监控和优化

package/template/SYSTEM_MANAGEMENT.md

@@ -0,0 +1,247 @@
+# 系统管理模块文档
+
+## 概述
+
+本项目包含三个完整的系统管理模块，基于若依管理系统的设计风格实现：
+
+- **用户管理** (`src/pages/system/user/User.tsx`)
+- **角色管理** (`src/pages/system/role/Role.tsx`)
+- **菜单管理** (`src/pages/system/menu/Menu.tsx`)
+
+## 功能特性
+
+### 1. 用户管理
+
+#### 主要功能
+- 用户列表展示（分页、排序）
+- 新增用户
+- 编辑用户信息
+- 删除用户
+- 搜索和筛选
+
+#### 用户字段
+- 用户编号
+- 用户名称（登录名）
+- 用户昵称
+- 部门
+- 手机号码
+- 邮箱
+- 性别
+- 状态（正常/停用）
+- 创建时间
+- 备注
+
+#### 操作
+- **新增**: 点击"新增"按钮打开表单
+- **编辑**: 点击编辑图标修改用户信息
+- **删除**: 点击删除图标，确认后删除用户
+- **搜索**: 按用户名、手机号、创建时间、状态搜索
+- **导出**: 导出用户列表
+
+### 2. 角色管理
+
+#### 主要功能
+- 角色列表展示
+- 新增角色
+- 编辑角色
+- 删除角色
+- 权限分配
+
+#### 角色字段
+- 角色编号
+- 角色名称
+- 权限字符
+- 显示顺序
+- 状态（正常/停用）
+- 创建时间
+- 备注
+
+#### 权限分配
+- 树形权限选择
+- 支持多级权限
+- 权限包括：
+  - 系统管理
+    - 用户管理（查看、新增、修改、删除）
+    - 角色管理（查看、新增、修改、删除）
+    - 菜单管理（查看、新增、修改、删除）
+  - 业务管理
+    - 订单管理（查看、新增）
+
+#### 操作
+- **新增**: 创建新角色并分配权限
+- **编辑**: 修改角色信息和权限
+- **删除**: 删除角色
+- **权限分配**: 在弹窗中选择权限
+
+### 3. 菜单管理
+
+#### 主要功能
+- 菜单树形展示
+- 新增菜单/子菜单
+- 编辑菜单
+- 删除菜单
+- 展开/折叠菜单树
+
+#### 菜单字段
+- 菜单名称
+- 父菜单
+- 排序
+- 菜单类型（目录/菜单/按钮）
+- 路由地址
+- 组件路径
+- 权限标识
+- 菜单图标
+- 是否外链
+- 是否缓存
+- 是否可见
+- 状态（正常/停用）
+- 创建时间
+- 备注
+
+#### 菜单类型
+- **M (目录)**: 菜单分类
+- **C (菜单)**: 可访问的菜单项
+- **F (按钮)**: 页面内的操作按钮
+
+#### 操作
+- **新增**: 添加顶级菜单
+- **新增子菜单**: 在菜单行点击"+"添加子菜单
+- **编辑**: 修改菜单配置
+- **删除**: 删除菜单及其子菜单
+- **展开/折叠**: 展开或折叠菜单树
+
+## 路由配置
+
+所有管理页面已在 `src/App.tsx` 中配置路由：
+
+```typescript
+<Route path="system/user" element={<User />} />
+<Route path="system/role" element={<Role />} />
+<Route path="system/menu" element={<Menu />} />
+```
+
+## 菜单导航
+
+在左侧菜单栏中，"系统管理"下包含三个子菜单项：
+- 用户管理
+- 角色管理
+- 菜单管理
+
+## 数据管理
+
+### 状态管理
+所有数据使用 React 的 `useState` Hook 进行本地状态管理。
+
+### 示例数据
+每个模块都包含初始示例数据：
+
+**用户管理**:
+- admin (管理员)
+- test (测试员)
+- dev (开发者)
+
+**角色管理**:
+- 超级管理员 (admin)
+- 普通角色 (common)
+- 测试角色 (test)
+
+**菜单管理**:
+- 系统管理 (目录)
+  - 用户管理 (菜单)
+  - 角色管理 (菜单)
+  - 菜单管理 (菜单)
+- 业务管理 (目录)
+  - 订单管理 (菜单)
+
+## 表单验证
+
+### 用户管理
+- 用户名称: 必填
+- 用户昵称: 必填
+- 邮箱: 邮箱格式验证
+- 手机号码: 手机号格式验证 (1[3-9]开头的11位数字)
+
+### 角色管理
+- 角色名称: 必填
+- 权限字符: 必填
+- 显示顺序: 必填
+
+### 菜单管理
+- 菜单名称: 必填
+- 路由地址: 必填
+- 菜单类型: 必填
+- 显示顺序: 必填
+
+## 组件依赖
+
+所有管理页面使用以下 Ant Design 组件：
+- Table: 数据表格
+- Form: 表单
+- Modal: 对话框
+- Button: 按钮
+- Input: 输入框
+- Select: 下拉选择
+- Switch: 开关
+- DatePicker: 日期选择
+- Tree: 树形组件（角色管理权限分配）
+- Card: 卡片
+- Row/Col: 栅格布局
+- Space: 间距
+- Tooltip: 提示
+- Popconfirm: 确认对话框
+
+## 扩展建议
+
+### 后端集成
+1. 将本地状态管理替换为 API 调用
+2. 实现真实的数据持久化
+3. 添加权限验证
+
+### 功能增强
+1. 批量操作（批量删除、批量导出）
+2. 高级搜索和筛选
+3. 数据导入功能
+4. 操作日志记录
+5. 用户头像上传
+6. 角色权限预设模板
+
+### 性能优化
+1. 虚拟滚动处理大数据列表
+2. 分页加载
+3. 缓存优化
+
+## 使用示例
+
+### 添加新用户
+1. 点击"新增"按钮
+2. 填写用户信息
+3. 点击"确定"保存
+
+### 分配角色权限
+1. 在角色管理中点击"新增"
+2. 填写角色基本信息
+3. 在权限分配区域选择需要的权限
+4. 点击"确定"保存
+
+### 管理菜单结构
+1. 在菜单管理中查看菜单树
+2. 点击"+"添加子菜单
+3. 配置菜单路由和权限
+4. 点击"确定"保存
+
+## 技术栈
+
+- React 19.2.4
+- TypeScript 5.9.3
+- Ant Design 6.3.2
+- React Router 7.13.1
+- Dayjs 1.11.10
+- Vite 5.4.0
+
+## 浏览器兼容性
+
+支持所有现代浏览器（Chrome、Firefox、Safari、Edge）
+
+## 许可证
+
+MIT

package/template/eslint.config.js

@@ -0,0 +1,29 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{js,jsx}'],
+    extends: [
+      js.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        ecmaFeatures: { jsx: true },
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]' }],
+    },
+  },
+])