# 西西弗 (Sisyphus) React 组件库项目指导

## 项目概述

**西西弗 (Sisyphus) React 组件库** 是一个基于 Ant Design 4.x 的企业级 React UI 组件库，专为业务系统快速开发而设计。项目名称源自希腊神话中的西西弗斯，象征着持续不断的努力和迭代优化。

- **项目名称**: @zat-design/sisyphus-react
- **官方文档**: https://procomponents.zhongan.tech
- **许可证**: MIT

## 技术栈架构

### 核心技术栈
- **前端框架**: React 17/18
- **UI 基础库**: Ant Design 4.24.16
- **开发语言**: TypeScript 4.9.5
- **构建工具**: Father Build + Dumi
- **测试框架**: Jest + React Testing Library
- **样式方案**: Less + CSS Modules

### 开发工具链
- **文档生成**: Dumi 1.x
- **代码规范**: ESLint + Prettier + Stylelint
- **提交规范**: Husky + Commitlint
- **包管理**: npm/yarn
- **CI/CD**: GitHub Actions

### 关键依赖
- **状态管理**: React Hooks (ahooks 3.8.4)
- **拖拽排序**: @dnd-kit 系列
- **工具库**: lodash, moment, big.js
- **图标**: @ant-design/icons
- **水印**: @pansy/react-watermark

## 项目架构

### 目录结构
```
xk-sisyphus-web/
├── src/                    # 源代码目录
│   ├── ProForm/           # 表单组件
│   ├── ProTable/          # 表格组件
│   ├── ProLayout/         # 布局组件
│   ├── ProSelect/         # 选择器组件
│   ├── ProEnum/           # 枚举组件
│   ├── ProUpload/         # 上传组件
│   ├── ProDrawerForm/     # 抽屉表单
│   ├── ProEditTable/      # 可编辑表格
│   ├── ProIcon/           # 图标组件
│   ├── ProWaterMark/      # 水印组件
│   ├── ProThemeTools/     # 主题工具
│   ├── locale/            # 国际化文件
│   ├── utils/             # 工具函数
│   └── index.ts           # 主入口文件
├── docs/                  # 文档目录
│   ├── 组件/              # 组件文档
│   ├── 文档/              # 使用文档
│   ├── 官方模板/          # 模板示例
│   ├── 登录组件/          # 登录组件文档
│   ├── 通用函数/          # 工具函数文档
│   └── 更新日志/          # 版本更新记录
├── tests/                 # 测试文件
├── lib/                   # ES5 构建输出
├── es/                    # ES6 构建输出
└── dist/                  # UMD 构建输出
```

### 组件分类

#### 1. 布局组件
- **ProLayout**: 页面布局框架
- **ProStep**: 步骤条组件
- **ProTabs**: 标签页组件

#### 2. 数据展示
- **ProTable**: 高级表格（支持搜索、分页、排序等）
- **ProTooltip**: 文字提示
- **ProViewer**: 文件预览器

#### 3. 数据录入
- **ProForm**: 高级表单（配置化表单生成）
- **ProEditTable**: 可编辑表格
- **ProDrawerForm**: 抽屉表单
- **ProEditLabel**: 可编辑标签
- **ProSelect**: 高级选择器
- **ProEnum**: 枚举选择器
- **ProUpload**: 文件上传

#### 4. 通用组件
- **ProIcon**: 图标组件
- **ProDownload**: 文件下载
- **ProWaterMark**: 水印组件
- **ProConfigProvider**: 全局配置
- **FormsProvider**: 表单提供者
- **ProThemeTools**: 主题定制工具
- **ProAction**: 操作按钮组

## 功能特性

### 核心特性
1. **配置化开发**: 通过 JSON 配置即可生成复杂的表单和表格
2. **类型安全**: 完整的 TypeScript 类型定义
3. **主题定制**: 支持动态主题切换和自定义主题
4. **国际化**: 支持中英文双语
5. **按需加载**: 支持 babel-plugin-import 按需引入
6. **响应式设计**: 适配不同屏幕尺寸

### 高级功能
1. **ProEnum**: 支持频繁枚举请求优化，提供缓存机制
2. **ProTable**: 内置搜索、分页、排序、导出等功能
3. **ProForm**: 支持动态表单项、联动校验、自定义组件
4. **ProEditTable**: 支持行内编辑、批量操作
5. **ProThemeTools**: 可视化主题编辑器
6. **ProWaterMark**: 自定义水印保护

## 构建配置

### 构建输出
- **lib/**: ES5 + CommonJS 格式，用于服务端渲染和旧版本兼容
- **es/**: ES6 + ES Modules 格式，用于现代构建工具的 tree-shaking
- **dist/**: UMD 格式，用于直接在浏览器中引用

### 构建脚本
```bash
# 完整构建
npm run build

# 分别构建
npm run build-lib    # ES5 + CJS
npm run build-es     # ES6 + ESM  
npm run build-dist   # UMD

# 开发调试
npm start            # 启动文档开发服务器

# 代码检查
npm run lint         # 运行所有检查
npm run tsc          # TypeScript 类型检查
```

### 测试配置
- **测试框架**: Jest + @testing-library/react
- **覆盖率要求**: 80% (branches, functions, lines, statements)
- **测试环境**: jsdom
- **Mock 配置**: 样式文件、图片资源、外部依赖

## 开发规范

### 代码规范
- **ESLint**: 基于 za/typescript-react 规范
- **Prettier**: 统一代码格式化
- **Stylelint**: Less/CSS 代码规范
- **Commitlint**: 提交信息规范 (Conventional Commits)

### 组件开发规范
1. **目录结构**: 每个组件独立目录，包含 index.tsx、propsType.ts、demos/、__tests__/
2. **类型定义**: 完整的 TypeScript 接口定义
3. **文档编写**: 使用 Dumi 编写组件文档和示例
4. **测试覆盖**: 每个组件需要单元测试
5. **样式隔离**: 使用 Less 模块化开发

### 版本发布
```bash
# Beta 版本发布
npm run release:beta

# 正式版本发布  
npm run release

# 内网发布
npm publish --registry https://npm.zhonganinfo.com
```

## 浏览器兼容性
- **现代浏览器**: Chrome, Firefox, Safari, Edge (最新两个版本)

## 业务集成

### 安装使用
```bash
npm install @zat-design/sisyphus-react --save
```

### 按需加载配置
```javascript
// babel.config.js
[
  'babel-plugin-import',
  {
    libraryName: '@zat-design/sisyphus-react',
    camel2DashComponentName: false,
    libraryDirectory: 'es',
    style: false,
  },
  '@zat-design/sisyphus-react'
]
```

### 基础使用
```tsx
import React from 'react';
import { ProForm, ProTable } from '@zat-design/sisyphus-react';

const App = () => {
  return (
    <ProForm
      columns={[
        {
          type: 'Input',
          label: '姓名',
          name: 'name',
          rules: [{ required: true, message: '请输入姓名！' }],
        }
      ]}
    />
  );
};
```

## 扩展和定制

### 主题定制
通过 ProThemeTools 组件或 Less 变量覆盖实现主题定制：
```less
@ant-prefix: ant;
@border-radius-base: 4px;
```

### 组件扩展
如果现有组件无法满足业务需求，可以：
1. 联系组件库维护团队进行功能扩展
2. 基于现有组件进行二次封装
3. 复制源码进行本地化修改

## 维护和支持

### 开发团队
- 基于中安科技内部需求开发
- 遵循企业级组件库最佳实践
- 持续迭代优化，保持技术先进性

### 技术支持
- 官方文档：完整的 API 文档和使用示例
- 在线预览：实时查看组件效果和代码
- 版本管理：详细的更新日志和迁移指南

这个组件库为企业级 React 应用提供了完整的 UI 组件解决方案，通过配置化的方式大大提升了开发效率，同时保持了良好的可维护性和扩展性。