# react19-admin **Repository Path**: jalogs/react19-admin ## Basic Information - **Project Name**: react19-admin - **Description**: React 19 企业级后台模板 · DDD 四层架构 · 领域层 100% 测试覆盖 · Vite 8 + TS + antd 6 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-30 - **Last Updated**: 2026-10-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # react19-modern-admin > 基于 **React 19 + Vite 8 + TypeScript + Ant Design 6** 的现代后台管理模板。 > 核心不是"堆组件"，而是**用 DDD 四层架构约束依赖方向，用 TDD 把领域层覆盖率拉满**。 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE) [![React](https://img.shields.io/badge/React-19-61dafb.svg)](https://react.dev/) [![Vite](https://img.shields.io/badge/Vite-8-blueviolet.svg)](https://vite.dev/) [![oxlint](https://img.shields.io/badge/lint-oxlint-1f6feb.svg)](https://oxc.rs/) [![Vitest](https://img.shields.io/badge/test-vitest-6e9f18.svg)](https://vitest.dev/) --- ## 为什么又是一个后台模板？ GitHub 上的 admin 模板绝大多数是"**页面集合**"：路由写死、请求逻辑散落在组件里、表单校验复制粘贴、没有任何测试。 本模板试图回答一个不同的问题：**当业务复杂度上升时，UI 层如何不被业务逻辑拖垮？** 答案是两件事： 1. **DDD 四层架构**——表现层 / 应用层 / 领域层 / 基础设施层，依赖严格单向向下，领域层不认识 React。 2. **TDD 质量门禁**——领域层 100% 行覆盖，全局 ≥80%，用 `vitest` + `v8 coverage` 强制卡口。 领域层是**纯 TypeScript**，你可以把它整体搬到 Node 后端或 React Native 里而不需要改一行。 --- ## 特性亮点 | 亮点 | 说明 | | --- | --- | | **DDD 四层架构** | `presentation` → `application` → `domain` ← `infrastructure`，依赖倒置 | | **领域层零 React 依赖** | 纯 TS 实体 / 值对象 / `Result`，可跨端复用 | | **TDD 门禁** | 领域层 100% 覆盖目标，仓储实现用 `vi.mock('@infra/http')` 隔离 | | **服务端状态分离** | TanStack Query 管服务端状态，Zustand 管客户端状态，职责清晰 | | **类型安全表单** | React Hook Form + Zod，schema 即类型即校验 | | **oxlint 极速 Lint** | 替代 ESLint，毫秒级；`--deny-warnings` 让警告也失败 | | **仓储模式** | 接口在 `domain/`，实现在 `infrastructure/`，换后端只改实现 | | **MSW 接口mock** | 前后端并行开发不阻塞 | --- ## 技术栈 | 分类 | 选型 | 版本 | | --- | --- | --- | | 框架 | React | ^19 | | 构建 | Vite | ^8.1 | | 语言 | TypeScript | ^5.9（非 7.x，原因见「版本说明」） | | UI | antd + @ant-design/icons | ^6 | | 客户端状态 | Zustand | ^4.5 | | 服务端状态 | TanStack Query / Table | ^5 / ^8.20 | | 表单 | React Hook Form + Zod | ^7.53 / ^3.23 | | 路由 | React Router | ^6.28 | | Lint | oxlint | ^1 | | 测试 | Vitest + Testing Library + jsdom + MSW | ^3 / ^16 / ^25 / ^2.4 | --- ## 架构：四层与依赖方向 ``` ┌─────────────────────────────────────────────┐ │ presentation 页面 / 组件 / 布局 / 路由 │ │ pages · components · layouts · router │ └──────────────────┬──────────────────────────┘ ↓ 依赖 ┌─────────────────────────────────────────────┐ │ application 用例编排（hooks + dto） │ │ hooks · dto │ └──────────────────┬──────────────────────────┘ ↓ 依赖 ┌─────────────────────────────────────────────┐ │ domain 领域模型（零 React 依赖） │ │ entities · value objects · repository 接口 │ └──────────────────▲──────────────────────────┘ │ 实现接口 ┌──────────────────┴──────────────────────────┐ │ infrastructure HTTP / Query / 缓存 / 存储 │ │ http · repositories · query · cache │ └─────────────────────────────────────────────┘ ``` **依赖规则**：箭头只能向下。领域层**禁止** import 任何 `react` / `antd` / `axios`。 --- ## 目录结构 ``` src/ ├── application/ # 应用层：用例编排 │ ├── dto/user.dto.ts │ └── hooks/ # useUser 等（TanStack Query 封装） ├── domain/ # 领域层：业务核心（零 React 依赖） │ ├── shared/ # BaseEntity / BaseValueObject / Result │ ├── user/ # 用户聚合（entity + value object + 仓储接口） │ ├── role/ dept/ resource/ dict/ # 角色 / 部门 / 资源(菜单) / 字典 │ └── */__tests__/ # 领域层单测 ├── infrastructure/ # 基础设施层 │ ├── http/ # Axios 封装 │ ├── repositories/ # 仓储实现 │ ├── query/ stores/ # QueryClient / Zustand │ └── cache/ storage/ logger/ ├── presentation/ # 表现层 │ ├── pages/ # 页面（dashboard / login / system/user …） │ ├── components/ # ProTable / PageContainer / AccessControl / ErrorBoundary │ ├── layouts/ router/ styles/ ├── utils/ # 通用工具 └── test/setup.ts ``` --- ## 快速开始 **环境要求**：Node.js >= 22（Vite 8 要求），包管理器推荐 pnpm 9+。 ```bash # 安装依赖 pnpm install # 启动开发服务器 pnpm dev # 类型检查 pnpm typecheck # Lint（含 --deny-warnings） pnpm lint # 运行测试 pnpm test # 覆盖率报告 pnpm test:coverage # 生产构建 pnpm build ``` --- ## 测试策略与门禁 | 层次 | 覆盖目标 | 手段 | | --- | --- | --- | | `domain/` | **100% 行覆盖** | 纯函数式单测，无框架依赖，最快最稳 | | `infrastructure/repositories/` | ≥80% | `vi.mock('@infra/http')` 隔离，只测映射与分支 | | 全局 | ≥80% | `vitest run --coverage`（v8 provider） | 仓储实现测试范式： ```ts vi.mock('@infra/http', () => ({ default: { get: vi.fn(), post: vi.fn(), put: vi.fn(), delete: vi.fn() }, })) ``` > **说明**：本模板先写测试再写实现（TDD）。领域层测试随实体一同提交，不事后补。 --- ## 版本说明（重要） `docs/` 中的原始规格文档按"最新预发布版本"编写，实际落地时按**可安装稳定版**做了如下调整，请以本 README 与 `package.json` 为准： | 规格文档写法 | 实际落地 | 原因 | | --- | --- | --- | | `typescript@^7` | `typescript@^5.9` | TS 7.0 为 Go 原生重写（Project Corsa），无稳定 programmatic API，vue-tsc/Volar 等模板类型检查生态暂不支持（vuejs/language-tools #5381），需等 7.1（计划 2026-11-10）；即便 React 端用 `tsc` 直检，同受该版本约束，故锁定 5.9 | | `oxlint@^4` | `oxlint@^1` | oxlint 最新稳定为 1.x | | `@oxlint/vite-plugin-react` | **已移除** | 该包在 npm 上不存在，保留会导致配置加载崩溃 | ### TypeScript 7 说明 > 常被误判为「项目落后」，实际是**工具链兼容性**选择，与项目业务代码无关。 - `typescript@^7` 是 `docs/` 原始规格文档按「最新版本」写的。实际落地锁定 `^5.9`。 - **TypeScript 7.0 已于 2026-07-08 发布**，Go 原生重写（Project Corsa），主打 8–12x 提速。 - **关键阻塞**：TS 7.0 **没有提供稳定的 programmatic API**，而 `vue-tsc` / Volar 的 SFC 模板类型检查**强依赖**该 API（vuejs/language-tools issue #5381），导致 `vue-tsc`、`typescript-eslint`、`ts-jest` 等同链路工具被阻塞。 - TS 7.1（计划 2026-11-10）才会补齐稳定 programmatic API。 - React 端虽使用 `tsc` 直接做类型检查而非 `vue-tsc`，但同样受该版本生态约束，故统一锁定 `^5.9`，待 7.1 稳定后再评估升级。 --- ## 当前完成度与路线图 | 模块 | 状态 | 说明 | | --- | --- | --- | | 用户管理 | ✅ 完整 | 实体 + 值对象 + 仓储接口/实现 + hook + 列表页 | | 角色管理 | ✅ 完整 | 仓储接口/实现 + hooks（增删改查）+ 页面 | | 部门管理 | ✅ 完整 | 仓储接口/实现 + hooks（增删改查）+ 页面 | | 资源管理 | ✅ 完整 | 仓储接口/实现 + hooks（增删改查）+ 页面 | | 字典管理 | ✅ 完整 | 字典类型 + 字典项双表 CRUD（仓储/hooks/页面/动态路由白名单） | | 动态路由 | ✅ 已实现 | 后端资源驱动，启动期注入；失败自动降级静态路由 | | 权限控制 | ✅ 已建 | `AccessControl` 组件 + `utils/permission.ts` | 路线图： - [x] 角色 / 部门 / 资源 CRUD 全量落地 - [x] 后端资源驱动的动态路由 - [x] 字典管理 CRUD（字典类型 + 字典项双表） - [ ] E2E（Playwright）补充 - [ ] 文档站 --- ## 许可证 [MIT](./LICENSE) © 2026 react19-modern-admin contributors