CellularManagement/src/X1.WebUI/README.md

# X1 WebUI

基于 Vite + React + TypeScript + Tailwind CSS + Shadcn UI 的现代化管理系统前端。

## 特性

- 🚀 基于 Vite 构建，开发体验极佳
- ⚛️ 使用 React 18 和 TypeScript 开发
- 🎨 使用 Tailwind CSS 和 Shadcn UI 构建美观的界面
- 📱 响应式设计，支持移动端和桌面端
- 🌙 支持暗黑模式
- 🔒 内置登录认证
- 📊 完整的布局系统
- 🔔 通知系统
- 🔍 搜索功能
- 👤 用户管理
- 👥 角色权限管理

## 技术栈

- 前端：React + TypeScript + Vite
- UI 组件库：Radix UI + Tailwind CSS
- 状态管理：React Query
- HTTP 客户端：Axios
- 路由：React Router
- 表单处理：React Hook Form

## 组件库

项目使用 Radix UI 作为基础组件库，结合 Tailwind CSS 进行样式定制。主要组件包括：

### 基础组件

- `Button` - 按钮组件
  ```tsx
  <Button variant="default" size="default">按钮</Button>
  ```

- `Input` - 输入框组件
  ```tsx
  <Input type="text" placeholder="请输入" />
  ```

- `Select` - 下拉选择组件
  ```tsx
  <Select>
    <SelectTrigger>
      <SelectValue placeholder="请选择" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="1">选项 1</SelectItem>
      <SelectItem value="2">选项 2</SelectItem>
    </SelectContent>
  </Select>
  ```

- `Form` - 表单组件
  ```tsx
  <Form>
    <FormField>
      <FormLabel>标签</FormLabel>
      <FormControl>
        <Input />
      </FormControl>
      <FormMessage />
    </FormField>
  </Form>
  ```

- `Table` - 表格组件
  ```tsx
  <Table>
    <TableHeader>
      <TableRow>
        <TableHead>标题</TableHead>
      </TableRow>
    </TableHeader>
    <TableBody>
      <TableRow>
        <TableCell>内容</TableCell>
      </TableRow>
    </TableBody>
  </Table>
  ```

- `Dialog` - 对话框组件
  ```tsx
  <Dialog>
    <DialogTrigger>打开</DialogTrigger>
    <DialogContent>
      <DialogHeader>
        <DialogTitle>标题</DialogTitle>
      </DialogHeader>
      <DialogDescription>描述</DialogDescription>
    </DialogContent>
  </Dialog>
  ```

## 角色管理功能

### 功能概述
- 角色列表展示
- 角色创建、编辑、删除
- 角色权限管理
- 角色用户关联

### 技术实现
- 使用 React + TypeScript 开发
- 采用 Ant Design 组件库构建 UI
- 使用 React Hooks 进行状态管理
- 遵循 Clean Architecture 架构设计
- 使用 Axios 进行 API 请求
- 使用 React Query 进行数据缓存和状态管理
- 使用 React Hook Form 进行表单管理
- 使用 Zod 进行数据验证

### 目录结构
```
src/
├── pages/
│   └── roles/
│       ├── RolesView.tsx      # 角色管理页面
│       ├── RoleForm.tsx       # 角色表单组件
│       └── RolePermissions.tsx # 角色权限管理
├── components/
│   └── roles/
│       ├── RoleList.tsx       # 角色列表组件
│       ├── RoleCard.tsx       # 角色卡片组件
│       └── PermissionTree.tsx # 权限树组件
├── services/
│   └── roleService.ts        # 角色服务
├── hooks/
│   ├── useRoles.ts           # 角色相关 Hook
│   └── usePermissions.ts     # 权限相关 Hook
├── types/
│   ├── role.ts               # 角色类型定义
│   └── permission.ts         # 权限类型定义
└── utils/
    └── roleUtils.ts          # 角色相关工具函数
```

### 使用说明
1. 角色列表页面
   - 展示所有角色信息
   - 支持分页、排序和筛选
   - 显示角色名称、描述、创建时间等信息
   - 提供快速操作按钮

2. 新建角色
   - 点击"新建角色"按钮
   - 填写角色基本信息
   - 配置角色权限
   - 提交表单创建角色

3. 编辑角色
   - 点击角色列表中的"编辑"按钮
   - 修改角色信息
   - 更新权限配置
   - 保存更改

4. 删除角色
   - 点击角色列表中的"删除"按钮
   - 确认删除操作
   - 系统自动更新角色列表

### API 接口
- GET /api/roles
  - 获取角色列表
  - 支持分页、排序和筛选
  - 返回角色数组

- GET /api/roles/{id}
  - 获取单个角色详情
  - 包含角色基本信息和权限配置
  - 返回角色对象

- POST /api/roles
  - 创建新角色
  - 请求体：角色信息对象
  - 返回创建的角色对象

- PUT /api/roles/{id}
  - 更新角色信息
  - 请求体：更新的角色信息
  - 返回更新后的角色对象

- DELETE /api/roles/{id}
  - 删除指定角色
  - 返回删除成功状态

### 数据模型
```typescript
interface Role {
  id: string;
  name: string;
  description: string;
  permissions: Permission[];
  createdAt: string;
  updatedAt: string;
}

interface Permission {
  id: string;
  name: string;
  code: string;
  description: string;
  type: 'menu' | 'operation';
  parentId?: string;
}
```

### 开发指南
1. 环境要求
   - Node.js >= 16
   - npm >= 7
   - Git

2. 开发流程
   ```bash
   # 克隆项目
   git clone https://github.com/yourusername/cellular-management-webui.git
   
   # 安装依赖
   npm install
   
   # 启动开发服务器
   npm run dev
   
   # 运行测试
   npm test
   
   # 构建生产版本
   npm run build
   ```

3. 代码规范
   - 使用 ESLint 进行代码检查
   - 使用 Prettier 进行代码格式化
   - 遵循 TypeScript 严格模式
   - 使用 Git Flow 工作流

4. 测试规范
   - 单元测试覆盖率 > 80%
   - 使用 Jest 和 React Testing Library
   - 编写集成测试和端到端测试

### 部署说明
1. 构建项目
   ```bash
   npm run build
   ```

2. 部署步骤
   - 将构建产物部署到 Web 服务器
   - 配置 Nginx 反向代理
   - 设置环境变量
   - 配置 SSL 证书

3. 环境变量
   ```env
   VITE_API_BASE_URL=https://api.example.com
   VITE_APP_TITLE=Cellular Management
   ```

### 性能优化
- 使用 React.lazy 进行代码分割
- 实现组件级别的缓存
- 优化图片和静态资源
- 使用 Service Worker 实现离线功能

### 安全措施
- 实现 CSRF 防护
- 使用 HTTPS
- 实现请求限流
- 数据加密传输
- XSS 防护

## 贡献指南
1. Fork 项目
2. 创建特性分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

## 版本历史
- v1.0.0 (2024-03-xx)
  - 初始版本发布
  - 实现基础功能
  - 添加角色管理模块

## 许可证
MIT