# iota-react-vite-admin

**Repository Path**: coder-farmer/iota-react-vite-admin

## Basic Information

- **Project Name**: iota-react-vite-admin
- **Description**: vite admin  后台管理系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-09
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# React Template 项目结构说明

## 项目概述

这是一个基于 **Vite + React + TypeScript + Ant Design** 的后台管理系统模板，适用于中后台管理系统的快速开发。

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Vite | ^8.0.10 | 构建工具，提供快速的开发体验 |
| React | ^18.3.1 | UI 框架 |
| TypeScript | ~6.0.3 | 类型系统 |
| Ant Design | ^6.3.7 | UI 组件库 |
| React Router | ^7.14.2 | 路由管理 |
| React Intl | ^7.1.11 | 国际化方案 |
| iota-fetch | ^0.1.1 | HTTP 请求封装库 |
| Sass | ^1.99.0 | CSS 预处理器 |
| iota-utools | ^0.1.7 | 工具函数库 |

---

## 目录结构

```
react-template/
├── public/                     # 静态资源目录
│   └── vite.svg               # Vite logo
├── src/                        # 源代码目录
│   ├── fetch/                  # HTTP 请求封装（iota-fetch）
│   │   ├── env.ts             # 环境配置
│   │   └── index.ts           # 请求模块入口
│   ├── i18n/                   # 国际化配置
│   │   ├── locales/           # 语言包
│   │   │   ├── en-US.ts       # 英文语言包
│   │   │   └── zh-CN.ts       # 中文语言包
│   │   └── index.tsx          # i18n Provider 组件
│   ├── pages/                  # 页面组件
│   │   ├── 404/               # 404 页面
│   │   ├── Dashboard/         # 仪表盘页面
│   │   ├── Layout/            # 布局组件
│   │   │   ├── Crumbs/        # 面包屑组件
│   │   │   ├── Header/        # 顶部导航
│   │   │   ├── NavTabs/       # 导航标签页
│   │   │   ├── Sider/         # 侧边栏菜单
│   │   │   ├── context.ts     # 布局状态上下文
│   │   │   └── index.tsx      # 布局主组件
│   │   ├── Login/             # 登录页面
│   │   ├── TablePage/         # 表格示例页面
│   │   │   ├── Table1/        # 表格示例1
│   │   │   └── Table2/        # 表格示例2
│   │   ├── TestPage/          # 测试页面
│   │   └── UserList/          # 用户列表页面
│   ├── router/                 # 路由配置
│   │   ├── index.tsx          # 路由入口
│   │   ├── router.map.ts      # 路由映射
│   │   └── routes.tsx         # 路由定义
│   ├── static/                 # 静态资源
│   │   └── styles/            # 全局样式
│   │       ├── init/          # 初始化样式
│   │       ├── sass/          # Sass 工具
│   │       └── index.scss     # 样式入口
│   ├── theme/                  # 主题配置
│   │   ├── context.tsx        # 主题上下文
│   │   └── index.ts           # 主题配置
│   ├── utils/                  # 工具函数
│   │   ├── index.ts           # 工具函数入口
│   │   ├── tools.doc.md       # 工具文档索引
│   │   └── tools/
│   │       ├── iota-fetch.md  # iota-fetch 文档
│   │       └── iota-utools.md # iota-utools 文档
│   ├── App.tsx                 # 应用根组件
│   ├── main.tsx                # 应用入口
│   └── vite-env.d.ts          # Vite 类型声明
├── .gitignore                  # Git 忽略配置
├── README.md                   # 项目说明
├── eslint.config.js           # ESLint 配置
├── index.html                 # HTML 入口
├── package.json               # 依赖配置
├── tsconfig.json              # TypeScript 配置
├── tsconfig.app.json          # 应用 TS 配置
├── tsconfig.node.json         # Node TS 配置
└── vite.config.ts             # Vite 配置
```

---

## 模块功能说明

### 1. fetch/ - HTTP 请求模块

**位置**: `src/fetch/`

**功能**: 基于 iota-fetch 的 HTTP 请求模块，提供统一请求方法和请求队列能力。

| 文件 | 功能说明 |
|------|----------|
| `index.ts` | 请求模块入口，导出配置好的 fetch 实例 |
| `env.ts` | 环境配置，定义 baseUrl 等环境变量 |

**使用示例**:
```typescript
import fetch from '@/fetch';

// GET 请求
const data = await fetch.get('/api/users');

// POST 请求
const result = await fetch.post('/api/users', { name: 'John' });
```

---

### 2. i18n/ - 国际化模块

**位置**: `src/i18n/`

**功能**: 基于 react-intl 的国际化方案，支持中英文切换。

| 文件 | 功能说明 |
|------|----------|
| `index.tsx` | I18nProvider 组件，提供国际化上下文 |
| `locales/zh-CN.ts` | 中文语言包 |
| `locales/en-US.ts` | 英文语言包 |

**API**:
- `getCurrentLocale()`: 获取当前语言
- `changeLocale(locale)`: 切换语言
- `getAntdLocale(locale)`: 获取 Ant Design 语言包

**使用示例**:
```typescript
import { useIntl } from 'react-intl';

const Component = () => {
  const intl = useIntl();
  return <div>{intl.formatMessage({ id: 'app.title' })}</div>;
};
```

---

### 3. router/ - 路由模块

**位置**: `src/router/`

**功能**: 基于 React Router v7 的路由配置。

| 文件 | 功能说明 |
|------|----------|
| `index.tsx` | 路由入口组件 |
| `routes.tsx` | 路由定义配置 |
| `router.map.ts` | 路由映射表 |

**路由结构**:
```
/login          - 登录页
/               - 布局页（包含侧边栏、头部等）
  ├── /dashboard - 仪表盘
  ├── /users     - 用户管理
  ├── /userList  - 用户列表
  ├── /test      - 测试页面
  └── /table     - 表格示例
       ├── /table/table1
       └── /table/table2
*               - 404 页面
```

---

### 4. theme/ - 主题模块

**位置**: `src/theme/`

**功能**: Ant Design 6.x 主题配置，支持亮色/暗色主题切换。

| 文件 | 功能说明 |
|------|----------|
| `index.ts` | 主题配置定义（lightTheme/darkTheme） |
| `context.tsx` | ThemeProvider 组件，提供主题上下文 |

**主题配置**:
- `lightTheme`: 亮色主题
- `darkTheme`: 暗色主题

---

### 5. static/styles/ - 样式模块

**位置**: `src/static/styles/`

**功能**: 全局样式和 Sass 工具函数。

| 文件/目录 | 功能说明 |
|-----------|----------|
| `index.scss` | 样式入口文件 |
| `init/reset.scss` | CSS Reset |
| `init/theme.scss` | 主题变量 |
| `sass/_index.scss` | Sass 工具入口 |
| `sass/_variables.scss` | Sass 变量 |
| `sass/_mixins.scss` | Sass Mixins |
| `sass/_functions.scss` | Sass 函数 |

---

### 6. pages/ - 页面模块

**位置**: `src/pages/`

**功能**: 应用的所有页面组件。

#### 6.1 Layout/ - 布局组件

**位置**: `src/pages/Layout/`

**功能**: 后台管理系统的主布局，包含侧边栏、顶部导航、内容区域。

| 组件 | 功能说明 |
|------|----------|
| `Layout` | 主布局组件 |
| `Sider` | 侧边栏菜单 |
| `Header` | 顶部导航栏 |
| `NavTabs` | 导航标签页 |
| `Crumbs` | 面包屑导航 |
| `context` | 布局状态上下文 |

**上下文状态**:
- `isFlod`: 侧边栏折叠状态
- `activeKey`: 当前激活的菜单项
- `openKeys`: 展开的菜单项

#### 6.2 其他页面

| 页面 | 路径 | 功能说明 |
|------|------|----------|
| `Login` | `/login` | 用户登录页面 |
| `Dashboard` | `/dashboard` | 数据仪表盘 |
| `UserList` | `/users`, `/userList` | 用户列表管理 |
| `TestPage` | `/test` | 测试页面 |
| `TablePage` | `/table` | 表格示例页面 |
| `404` | `*` | 404 错误页面 |

---

### 7. utils/ - 工具函数

**位置**: `src/utils/`

**功能**: 工具函数入口，目前主要导出 `iota-utools` 库的功能。

**iota-utools 功能**:
- 类型判断（isArray, isObject, isString 等）
- Storage 操作（localStorage/sessionStorage）
- Storage 监听
- 其他实用工具函数

---

## 配置文件说明

### vite.config.ts

Vite 构建配置，包含：
- React 插件
- Sass 预处理器配置
- 路径别名 `@` 指向 `src`
- 开发服务器端口 8081

### tsconfig.json

TypeScript 配置，包含：
- 应用配置（tsconfig.app.json）
- Node 配置（tsconfig.node.json）

### eslint.config.js

ESLint 配置，用于代码规范检查。

---

## 开发命令

```bash
# 启动开发服务器
yarn dev
# 或
yarn start

# 构建生产版本
yarn build

# 代码检查
yarn lint

# 预览生产构建
yarn preview

# 依赖检查（当前范围）
yarn deps:check

# 依赖全量检查（含 major）
yarn deps:check:full

# 一键升级依赖并安装
yarn deps:update

# 安全审计
yarn deps:audit
```

---

## 快速开始

1. **安装依赖**
   ```bash
   yarn install
   ```

2. **启动开发服务器**
   ```bash
   yarn dev
   ```

3. **访问应用**
   打开浏览器访问 http://localhost:8081

---

## 依赖使用方法

### 日常安装与运行

```bash
# 安装依赖
yarn install

# 本地开发
yarn dev

# 生产构建
yarn build
```

### 依赖巡检与升级

```bash
# 查看当前可升级依赖
yarn deps:check

# 查看全量升级建议（含 major）
yarn deps:check:full

# 执行升级并重装
yarn deps:update

# 安全审计
yarn deps:audit
```

### 业务依赖接入说明

- iota-fetch: 统一请求层，入口在 src/fetch/index.ts
- iota-utools: 通用工具库，通过 src/utils/index.ts 统一导出
- antd: UI 组件库，主题在 src/theme/index.ts 中集中配置

---

## Sass 使用方法

Sass 工具集中在 src/static/styles/sass 下，入口为 _index.scss。

在 vite.config.ts 中通过 additionalData 全局注入：

```scss
@use "@/static/styles/sass/_index" as *;
```

因此页面或组件的 scss 文件可以直接使用变量、mixin、函数。

### 常用变量

- $primary-color
- $success-color
- $warning-color
- $error-color
- $font-size-base
- $border-radius-base

### 常用 mixin

- @include flex-center
- @include text-ellipsis
- @include multi-ellipsis(2)
- @include responsive(mobile|tablet|desktop)
- @include flexbox(space-between, center)
- @include ellipsis(1|2|3)
- @include scroll(6px, #c6cfd3, #f5f5f5)

### 常用函数

- rem(16px)
- em(18px, 16px)
- strip-unit(16px)
- color-opacity(#000, 0.12)

滚动条样式注意：@include scroll 仅定义外观，需要配合 overflow: auto 或 overflow-y: auto 以及高度约束才会生效。

---

## 扩展建议

1. **状态管理**: 可集成 Zustand、Redux Toolkit 或 Jotai
2. **表单处理**: 可集成 React Hook Form + Zod
3. **数据获取**: 可集成 React Query (TanStack Query)
4. **测试**: 可添加 Vitest + React Testing Library

---

## 依赖治理策略

为保证 admin 解决方案持续可用且不过时，项目采用以下策略：

1. 每半年做一次全量依赖检查（含 major）
2. 每次升级后至少执行 lint + build 验证
3. 版本升级优先遵循生态兼容（React 主版本不随意跨代）

已内置自动巡检工作流：

- 文件位置：.github/workflows/dependency-review.yml
- 执行频率：每年 1 月和 7 月（半年一次）
- 执行内容：outdated、npm-check-updates、audit