qilincloud168/ERPTurbo_Admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
ERPTurbo_Admin/.lingma/rules/design.md
shenyifei cc15943d44 feat(biz): 添加Biz组件库设计规则和技术文档 
- 创建.biz.md文件定义Biz组件库设计规则
- 创建design.md文件编写ERPTurbo_Admin项目技术文档
- 定义组件架构模式、类型系统和统一属性模式
- 添加权限控制机制和数据交互模式说明
- 完善项目核心技术栈和架构说明
2025-11-10 15:52:34 +08:00

4.4 KiB
Raw Permalink Blame History

trigger
manual

ERPTurbo_Admin 项目技术文档

1. 项目概述

ERPTurbo_Admin 是一个基于 React 生态系统的管理后台系统，采用 Monorepo 架构，包含多个子应用和共享组件库。

2. 核心技术栈

2.1 主要框架和库

技术 版本 用途
React ^18.0.0 前端核心框架
UmiJS Max ^4.4.9 应用框架和构建工具
Ant Design ^5.25.2 UI 组件库
Ant Design Pro Components ^2.8.6 高级业务组件
TypeScript ^5.6.3 类型检查和开发支持
TailwindCSS ^3.4.17 CSS 框架

2.2 状态管理和数据流

  • UmiJS 内置状态管理：包括 initialState、model、valtio 插件
  • React Query：服务端状态管理
  • Dva：轻量级的数据流方案

2.3 构建和开发工具

  • PNPM：包管理器
  • Prettier：代码格式化
  • ESLint：代码质量检查
  • Husky：Git Hooks 工具
  • Lint-staged：增量代码检查

3. 项目架构

3.1 Monorepo 结构

ERPTurbo_Admin/
├── packages/
│   ├── app-operation/         # 运营管理系统主应用
│   ├── app-sso-server/        # SSO 单点登录系统
├── shared/
│   ├── components/            # 共享组件库
├── pnpm-workspace.yaml        # PNPM 工作区配置

3.2 主要应用介绍

app-operation (运营管理系统)

这是主要的管理后台应用，具有完整的后台管理功能：

  • 使用 UmiJS Max 框架
  • 实现了动态路由和菜单
  • 包含权限控制和用户认证
  • 支持国际化 (i18n)

shared/components (共享组件库)

这是一个独立的组件库，使用 Dumi 进行开发和文档展示：

  • 可复用的业务组件
  • 支持按需引入
  • 具备完整的类型定义

4. 核心特性实现

4.1 权限控制系统

项目实现了细粒度的权限控制：

  • 基于角色的访问控制 (RBAC)
  • 页面级别权限控制 (access 插件)
  • 按钮级别权限控制 (通过 ButtonAccess 组件)

4.2 动态路由和菜单

  • 从服务端获取路由配置
  • 自动注册和渲染页面组件
  • 支持嵌套路由和面包屑导航

4.3 国际化支持

  • 使用 locale 插件实现多语言
  • 支持中文等语言切换
  • 统一的国际化消息管理

4.4 BizContainer 封装模式

项目采用了独特的 BizContainer 组件封装业务逻辑：

  • 统一封装增删改查操作
  • 支持列表、详情、创建、更新、删除等标准操作
  • 集成导入导出、树形结构、日历视图等功能
  • 内置权限验证和操作引导

5. 样式和主题

5.1 样式解决方案

  • TailwindCSS：实用优先的 CSS 框架
  • Ant Design 主题定制：通过配置 token 自定义主题
  • styled-components：CSS-in-JS 解决方案

5.2 响应式设计

  • 支持移动端适配
  • 响应式布局组件
  • 可折叠侧边栏

6. 数据交互

6.1 API 请求

  • 使用 UmiJS 的 request 插件统一管理 HTTP 请求
  • 全局错误处理和拦截器
  • 请求和响应拦截器支持
  • 与后端服务集成

6.2 数据模拟和调试

  • 集成 Swagger UI 文档
  • 支持 OpenAPI 规范自动生成服务层代码

7. 开发规范

7.1 代码风格

  • 使用 Prettier 统一代码格式
  • ESLint 进行代码质量检查
  • Git Hooks 保证提交代码质量

7.2 组件开发规范

  • 组件封装遵循单一职责原则
  • 使用 TypeScript 强类型约束
  • 统一的组件接口设计

8. 部署和构建

8.1 构建命令

# 开发环境启动
pnpm dev

# 生产环境构建
pnpm build

# 代码格式化
pnpm format

8.2 构建优化

  • 使用 MFSU (Module Federation Speed Up) 提升编译速度
  • 支持代码分割和懒加载
  • 静态资源压缩和优化

9. 项目扩展性考虑

  1. 插件化架构：UmiJS 插件机制便于功能扩展
  2. 组件复用：共享组件库提升开发效率
  3. 微前端支持：可扩展至微前端架构
  4. 多应用管理：Monorepo 结构便于多系统协同开发