MES UI 前端共享组件库

这是一个 MES 前端共享代码模块项目，提供可复用的组件和页面模板。

功能特性

• 🚀 模板生成: 通过 CLI 工具快速生成组件和页面模板
• 👀 实时预览: 内置预览功能，可视化查看所有模板效果
• 📝 代码查看: 在预览界面中直接查看模板源代码
• 📱 响应式预览: 支持桌面、平板、手机等不同设备尺寸预览
• 🎨 现代化UI: 基于 Ant Design 的美观界面
• ⚡ 自动化配置: 自动扫描模板目录，生成配置文件
• 🔍 文件监听: 自动监听模板文件变化，实时更新配置
• 🤖 AI 集成: 支持 MCP 协议，可与 Cursor 等 AI 工具无缝集成

安装使用

1. 安装依赖

npm install

2. 启动预览服务

# 方式一：带文件监听的开发模式（推荐）
npm run dev:watch

# 方式二：自动生成配置并启动预览
npm run dev

# 方式三：仅启动预览服务
npm run preview

预览服务启动后，访问 http://localhost:3000 即可查看所有模板。

3. 在业务项目中使用模板

在你的业务项目中安装并使用：

# 安装 CLI 工具
npm install mes-ui

# 方式一：交互式选择模板
npx mes-ui add

# 方式二：直接指定模板名称
npx mes-ui add account-settings

# 方式三：批量添加多个模板
npx mes-ui add account-settings user-management login

# 检查模板更新
npx mes-ui check-updates

可用命令

CLI 命令

• mes-ui add - 添加模板到项目（支持交互式选择或直接指定模板）
• mes-ui add <template-name> - 直接添加指定模板（支持模糊匹配）
• mes-ui add <template1> <template2> ... - 批量添加多个模板
• mes-ui list - 列出已生成的模块
• mes-ui remove - 删除已生成的模块
• mes-ui upgrade - 升级已生成的模块
• mes-ui check-updates - 检查模板更新（基于内容哈希）
• mes-ui mcp-server - 启动 MCP 服务器（用于 Cursor 集成）

NPM 脚本

• npm run dev:watch - 启动文件监听 + 预览服务（推荐开发模式）
• npm run dev - 生成配置并启动预览服务
• npm run preview - 启动预览服务（开发模式）
• npm run preview:build - 构建预览站点
• npm run preview:dev - 启动预览服务（支持外部访问）
• npm run generate-config - 手动生成模板配置
• npm run watch-templates - 启动文件监听服务

模板配置系统

自动化配置

本项目采用完全自动化的模板配置系统：

1. 配置文件: 每个模板目录下需要包含 config.json 文件
2. 自动扫描: 脚本会自动扫描 /templates 目录下的所有模板
3. 动态生成: 自动生成多种配置映射供不同模块使用
4. 文件监听: 自动监听模板文件变化，实时更新配置
5. 智能导入: 基于配置自动生成模板内容导入映射

🔧 生成的配置类型

系统会自动生成以下配置对象：

• templateConfigs: 统一的模板配置数组，包含完整信息
• staticImportMap: 静态文件导入映射，用于代码查看
• componentImportMap: 组件导入映射，用于预览渲染
• 工具函数: 提供便捷的配置访问方法

📦 依赖管理系统

每个模板可以在 config.json 中定义自己的依赖：

{
  "id": "YourComponent",
  "name": "组件名称",
  "description": "组件描述",
  "dependencies": {
    "lodash": "^4.17.21",
    "moment": "^2.29.4",
    "@ant-design/pro-components": "^2.4.4"
  }
}

系统会自动合并默认依赖（React + Antd）和自定义依赖，CLI工具会自动安装所有必需的依赖包。

常用依赖说明：

• @ant-design/pro-components: 用于页面模板的 ProComponents 组件
• react-syntax-highlighter: 代码高亮显示
• lodash: 工具函数库
• dayjs: 日期处理库（推荐替代 moment）

🎯 智能路径生成

系统会根据模板类型自动生成默认目标路径：

• 页面模板: app/{templateId}
• 组件模板: components/ui/{templateId}
• 其他类型: ./{templateId}

CLI工具会自动使用这些路径作为默认值，无需手动维护。

添加新模板

1. 创建模板目录

   templates/
   ├── components/          # 组件模板
   │   └── YourComponent/
   │       ├── config.json  # 配置文件
   │       ├── index.tsx    # 组件代码
   │       └── example.tsx  # 预览示例（可选）
   └── pages/              # 页面模板
       └── YourPage/
           ├── config.json  # 配置文件
           ├── page.tsx     # 页面代码
           ├── form.tsx     # 其他文件
           └── example.tsx  # 预览示例（可选）

2. 创建配置文件 (config.json)

   {
     "id": "YourComponent",
     "name": "组件显示名称",
     "description": "组件的详细描述"
   }

3. 创建预览示例文件 (example.tsx) - 可选

   对于 Modal、Drawer、Popover 等需要特殊交互的组件，建议创建 example.tsx 文件：

   import React, { useState } from 'react';
   import { Button, Card, Typography } from 'antd';
   import YourComponent from './index';
   
   const { Title, Paragraph } = Typography;
   
   const Example: React.FC = () => {
       const [visible, setVisible] = useState(false);
   
       return (
           <div style={{ padding: '24px' }}>
               <Card>
                   <Title level={3}>组件名称</Title>
                   <Paragraph>组件功能说明</Paragraph>
                      
                   <Button onClick={() => setVisible(true)}>
                       打开组件
                   </Button>
               </Card>
   
               <YourComponent
                   visible={visible}
                   onCancel={() => setVisible(false)}
               />
           </div>
       );
   };
   
   export default Example;

4. 自动更新 (如果使用 dev:watch 模式)

   • 保存文件后配置会自动更新
   • 预览界面会自动刷新

5. 手动更新 (如果需要)

   npm run generate-config

配置文件格式

每个模板的 config.json 文件包含以下字段：

{
  "id": "模板唯一标识符",
  "name": "模板显示名称", 
  "description": "模板的详细描述"
}

其他信息（category、path、files、language）由脚本自动生成。

自动化特性

🔍 文件监听

• 自动监听 templates/ 目录下的所有文件变化
• 支持 .tsx、.ts、.json 文件类型
• 防抖处理，避免频繁触发
• 实时更新配置文件

📦 智能导入

• 基于生成的配置自动创建导入映射
• 支持精确路径匹配和模糊匹配
• 错误处理和调试信息
• 无需手动维护导入代码

🎭 示例文件系统 (example.tsx)

本项目支持为模板创建专门的预览示例文件，特别适用于需要特殊交互的组件：

工作机制：

• 有示例文件时: 预览系统优先使用 example.tsx 进行渲染
• 无示例文件时: 预览系统直接渲染主组件文件 (index.tsx 或 page.tsx)
• CLI 工具: example.tsx 文件不会被复制到业务项目中
• 配置生成: example.tsx 文件不会出现在 staticTemplateConfigs 中

适用场景：

• Modal、Drawer、Popover 等弹窗组件
• 需要特定状态或数据的组件
• 需要展示多种用法的组件
• 需要提供使用说明的复杂组件

文件结构示例：

templates/components/ChangePasswordModal/
├── config.json      # 组件配置
├── index.tsx        # 主组件文件（会被复制到业务项目）
└── example.tsx      # 预览示例（仅用于预览，不会被复制）

示例文件模板：

import React, { useState } from 'react';
import { Button, Card, Typography } from 'antd';
import YourModal from './index';

const Example: React.FC = () => {
    const [visible, setVisible] = useState(false);

    return (
        <div style={{ padding: '24px' }}>
            <Card>
                <Typography.Title level={3}>组件演示</Typography.Title>
                <Typography.Paragraph>
                    组件功能说明和使用指南
                </Typography.Paragraph>
                
                <Button onClick={() => setVisible(true)}>
                    打开模态框
                </Button>
            </Card>

            <YourModal
                visible={visible}
                onCancel={() => setVisible(false)}
            />
        </div>
    );
};

export default Example;

目前可用的模板

页面模板

• login: 完整的登录页面，包含账号密码和手机号登录
• account-settings: 用户账户设置页面，包含基本信息展示和头像上传功能（有示例文件）
• user-management: 用户管理页面，包含用户列表、添加、编辑、删除等功能
• role-management: 角色管理页面，包含角色权限配置
• organization-structure: 组织架构管理页面
• position-management: 岗位管理页面

组件模板

• MyButton: 基于 Ant Design 的自定义按钮组件
• ChangePasswordModal: 修改密码弹窗组件，包含完整的密码验证逻辑（有示例文件）

CLI 高级功能

智能模板匹配

CLI 工具支持智能模板匹配，可以通过以下方式使用：

# 精确匹配
npx mes-ui add account-settings

# 模糊匹配（支持部分名称）
npx mes-ui add account    # 匹配 account-settings
npx mes-ui add user       # 匹配 user-management

# 如果匹配到多个结果，会显示选择列表
npx mes-ui add management # 显示所有包含 management 的模板

批量操作

支持一次性添加多个模板：

# 批量添加多个模板
npx mes-ui add account-settings user-management role-management

# 自动合并依赖，避免重复安装
# 显示进度信息和操作状态

智能默认命名

CLI 工具会根据模板 ID 自动生成有意义的默认名称：

• account-settings → AccountSettings
• user-management → UserManagement
• organization-structure → OrganizationStructure
• login → Login

版本控制系统

基于内容哈希的可靠版本控制：

# 检查模板更新
npx mes-ui check-updates

# 提供四种处理方式：
# 1. 查看详细差异
# 2. 批量更新所有模板
# 3. 更新版本记录（不修改代码）
# 4. 取消操作

版本控制特点：

• 使用 SHA-256 算法计算模板内容哈希
• 基于实际内容变化，不受文件修改时间影响
• 精确比较，避免误判
• 支持批量更新和选择性更新

预览功能

预览界面提供以下功能：

1. 模板列表: 左侧显示所有可用模板，按组件/页面分类
2. 实时预览: 右侧实时渲染选中的模板效果
3. 代码查看: 可以切换到代码视图查看模板源码，支持语法高亮
4. 设备切换: 支持桌面、平板、手机三种预览尺寸
5. 响应式设计: 界面自适应不同屏幕尺寸
6. 热更新: 支持模板文件修改后自动刷新
7. 搜索功能: 支持模板名称和描述搜索，带防抖优化
8. 懒加载: 模板内容按需加载，提升首屏性能

开发指南

目录结构

mes-frontend-shared-modules/
├── bin/                    # CLI 工具
├── templates/              # 模板文件
│   ├── components/         # 组件模板
│   │   └── MyButton/
│   │       ├── config.json
│   │       └── index.tsx
│   └── pages/             # 页面模板
│       └── login-page/
│           ├── config.json
│           ├── page.tsx
│           └── form.tsx
├── preview-app/           # 预览应用
│   ├── src/
│   │   ├── components/    # 预览组件
│   │   └── utils/         # 工具函数
├── scripts/               # 构建脚本
│   ├── generate-template-config.js
│   └── watch-templates.js
└── utils/                 # 通用工具

推荐工作流程

1. 开发模式启动

   npm run dev:watch

2. 创建新模板

   • 在 templates/ 下创建模板目录和文件
   • 添加 config.json 配置文件
   • 保存后自动更新配置

3. 实时预览

   • 在浏览器中查看模板效果
   • 修改模板文件后自动刷新

4. 发布使用

   • 在业务项目中使用 mes-ui add 添加模板

高级功能

自定义监听

如果需要自定义监听规则，可以修改 scripts/watch-templates.js：

// 自定义文件过滤规则
if (filename && 
    !filename.startsWith('.') && 
    !filename.includes('node_modules') &&
    (filename.endsWith('.tsx') || 
     filename.endsWith('.ts') || 
     filename.endsWith('.json'))) {
  // 处理文件变化
}

自定义导入逻辑

如果需要特殊的导入处理，可以修改 preview-app/src/utils/templateLoader.ts 中的 createImportMap 函数。

MCP 集成 (AI 工具支持)

MES UI 现在支持作为 MCP (Model Context Protocol) 服务器运行，让 Cursor 等 AI 工具可以直接调用模板生成功能。

快速配置

在 Cursor 的 ~/.cursor/mcp.json 中添加：

{
  "mcpServers": {
    "mes-ui": {
      "command": "npx",
      "args": ["mes-ui", "mcp-server"],
      "timeout": 600
    }
  }
}

可用功能

• 智能模板推荐: AI 根据需求推荐合适的模板
• 批量生成: 一次性生成多个相关模板
• 自动依赖管理: 智能处理依赖关系
• 版本更新检查: AI 协助维护模板版本

详细配置和使用说明请参考 MCP_INTEGRATION.md

技术栈

• 构建工具: Vite
• UI框架: React + Ant Design + Ant Design Pro Components
• 语言: TypeScript
• CLI 工具: Node.js + Inquirer
• 配置管理: 自动化脚本生成
• 文件监听: Node.js fs.watch API
• 并发执行: concurrently
• 代码高亮: react-syntax-highlighter
• 版本控制: SHA-256 内容哈希
• 性能优化: 懒加载、防抖、缓存
• AI 集成: MCP (Model Context Protocol)

许可证

MIT