# react-h5-template

**Repository Path**: ashscc/react-h5-template

## Basic Information

- **Project Name**: react-h5-template
- **Description**: react创建web项目的模板
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 CoreLink Template

![React](https://img.shields.io/badge/React-19.x-blue?style=flat&logo=react)
![Vite](https://img.shields.io/badge/Vite-7.x-646CFF?style=flat&logo=vite)
![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat&logo=typescript)
![Zustand](https://img.shields.io/badge/Zustand-5.x-bear?style=flat)
![TanStack Query](https://img.shields.io/badge/TanStack_Query-5.x-FF4154?style=flat)
![TailwindCSS](https://img.shields.io/badge/Tailwind-4.x-38B2AC?style=flat&logo=tailwind-css)

本模板是一套为**中大型 B 端企业级项目（Admin/SaaS/ERP）**量身打造的 React 现代化底层架构。

它摒弃了传统臃肿的样板代码，深度整合了当今 React 生态最前沿的技术栈，内置了**物理级安全的动态路由、极简状态管理、双重异常监控体系与无痕埋点**，让你做到“开箱即战，拔剑即杀”。

## 📦 快速开始

```bash
# 1. 拉取架构模板
git clone --depth 1 git@gitee.com:ashscc/react-h5-template.git my-new-project && rd /s /q my-new-project\.git

# 2. 进入项目并安装依赖 (本项目强制规范使用 pnpm)
cd my-new-project
pnpm install

# 3. 启动起飞！
pnpm dev
```

---

## 🧠 核心架构与原理解析 (Architecture & Principles)

本架构的设计哲学是：**高内聚低耦合、状态驱动 UI、防御性编程。**
以下是本系统中核心模块的工作原理深度剖析：

### 一、 状态管理哲学：客户端与服务端的严格隔离
传统的 React 项目常常陷入“全局状态地狱”（将所有的 API 数据和 Loading 状态全塞进 Redux/Zustand 中）。本架构采用**双引擎模式**：

1. **客户端状态 (Zustand)**：仅用于存储纯前端的 UI 状态和用户鉴权信息（Token、权限标识）。其轻量、基于 Hooks 的特性实现了极低的心智负担，并内置了 `localStorage` 持久化。
2. **服务端状态 (TanStack Query)**：接管所有 HTTP 异步数据。
   * **工作原理**：它在内存中建立了一层强大的异步缓存层。相同 `queryKey` 的接口在设定的 `staleTime` 内不会触发重复的网络请求，实现页面秒开。它同时在底层自动处理了竞态条件（Race Conditions）、自动重试机制与焦点重新获取，彻底消灭了组件内的 `useEffect` 和 `useState(loading)` 胶水代码。

### 二、 路由架构：基于后端的“物理级”动态防线
摒弃了传统的“前端写死所有路由表，靠 `beforeEach` 拦截”的弱安全模式。采用完全**数据驱动的动态路由**：

* **工作原理**：
  1. 系统启动时，React Router 仅注册 `/login` 和 `RootLayout`（空壳布局）。
  2. 登录后，前端获取后端的 JSON 菜单树（Menu Tree）。
  3. 利用 Vite 的构建时宏 `import.meta.glob`，扫描 `src/pages` 目录生成组件映射表。
  4. 遍历菜单树，从映射表中懒加载对应的组件，在内存中“动态捏造”出合法的路由对象，并通过 `useMemo` 注入到 `<RouterProvider>` 中。
* **安全价值**：对于用户没有权限的页面，前端不仅不会显示菜单，甚至**连对应的 JS Chunk 都在路由表中根本不存在**，从物理层面上断绝了越权访问。

### 三、 天眼监控体系：双重防线与行为面包屑
在大型系统中，不能指望用户截图反馈 Bug。本模板内置了一套轻量的、比肩 Sentry 的零侵入式监控底座。

* **第一防线（防白屏）：`react-error-boundary`**
  包裹在路由顶层。当 React 渲染阶段发生崩溃时，立刻卸载崩溃的局部组件并渲染降级 UI，阻断错误向上传递，保证页面侧边栏等框架依然可用。
* **第二防线（兜底追踪）：全局 `initMonitor`**
  利用原生 `window.addEventListener('error' / 'unhandledrejection')`，捕获 ErrorBoundary 抓不到的异步报错（如 `setTimeout`、`Promise`、网络资源加载失败）。
* **行为追踪（Breadcrumbs）**：
  架构底层维护了一个最大长度为 20 的**环形队列（Ring Buffer）**。利用**全局事件委托**和 **Axios 拦截器**，静默记录用户的每一次点击、路由切换和 API 请求。一旦发生报错，将这 20 条案发前的“操作录像”随错误堆栈一并上报，极大降低排障成本。

### 四、 RBAC 权限控制：细粒度按钮级鉴权
提供了声明式的 `<Auth>` 组件与命令式的 `usePermission` Hook。

* **工作原理**：登录时将用户的权限标识集合（如 `['sys:user:add']`）存入 Zustand。页面渲染时，`<Auth value="sys:user:add">` 会自动比对权限。支持 `oneOf`（满足其一）和 `allOf`（全满足）的高级策略，以及无权限时的 `fallback` 降级渲染。

### 五、 YAGNI 国际化架构：以中文为 Key 的占位机制
考虑到业务早期可能不需要多语言，但未来重构代价极高的问题，引入了基于 `react-i18next` 的无痛接入方案。

* **工作原理**：配置 `parseMissingKeyHandler`，开发时直接使用 `t('提交表单')`。在无多语言包时，系统自动 fallback 返回中文 Key 本身。**当前零开发成本，未来需出海时只需注入 JSON 字典即可瞬间完成国际化。**

---

## 📂 目录结构 (Directory Structure)

```text
├── build/                  # Vite 构建相关扩展配置
├── public/                 # 静态资源 (favicon 等)
├── src/
│   ├── api/                # Axios 请求实例与接口定义
│   ├── assets/             # 全局静态资源 (Images/Icons)
│   ├── components/         # 业务无关的全局公共组件 (如 ErrorBoundary, Auth)
│   ├── hooks/              # 自定义 Hooks (如 usePermission)
│   ├── layout/             # 应用整体布局 (侧边栏、顶导，注入 PV 埋点)
│   ├── pages/              # 业务视图页面 (按业务域划分)
│   ├── router/             # 路由动态构建逻辑与工具
│   ├── store/              # Zustand 全局状态管理
│   ├── utils/              # 工具函数 (Http拦截器, Tracker上报, i18n等)
│   ├── App.tsx             # 顶层提供者 (RouterProvider, QueryProvider)
│   └── main.ts             # 魔法入口 (最早时机执行 Monitor 初始化)
├── .eslintrc.cjs           # ESLint 规范配置
├── .prettierrc             # 代码格式化规范
└── vite.config.ts          # 构建提速与别名配置
```

## 🛠 工程化与规范 (Engineering & Linting)

1. **包管理约束**：根目录通过 `preinstall` 脚本，强校验只能使用 `pnpm`，杜绝 `npm`/`yarn` 混用导致的 lock 文件冲突。

---
*Powered by coderwan. 构建稳定、健壮且优美的现代前端应用。*