# 风控品控管理系统 — 前端

<div align="center">

**Vue 3.5** | **TypeScript 5** | **Element Plus 2.x** | **Vite 5** | **Pinia 2** | **ECharts 5**

企业级安全风险管控与质量管控平台前端项目

</div>

---

## 一、项目简介

本仓库是 **风控品控管理系统** 的前端项目，基于开源框架 [plus-ui](https://gitee.com/JavaLionLi/plus-ui)（Vue 3 + TS + Element Plus + Vite）深度定制开发，覆盖 10 大风控业务场景，统一对接后端 RuoYi-Vue-Plus 微服务。

### 核心特性

- 🚀 **现代化** — Vue 3 Composition API + Vite 5 热更新，开发体验流畅
- 🎨 **主题统一** — Element Plus 二次封装，1080P 分辨率 UI 规范
- 🔐 **安全** — 登录 AES 加密、动态 RSA 秘钥交换、Sa-Token 鉴权
- 📱 **响应式** — el-row/el-col 自适应，支持 xs/sm/md/lg/xl 多断点
- 📊 **数据可视化** — ECharts 折线图、饼图、仪表盘
- 🗂️ **文件存储** — MinIO 分片上传/下载/预览
- 📐 **滚动规范** — 长页面统一 `.xxx-page { height: 100%; overflow-y: auto }`

---

## 二、业务模块

| 业务域 | 路径 | 功能 |
|---|---|---|
| 工作台首页 | `/index` | 4 张数据卡片 + 2 张图表 + 三段式（最新隐患 + 培训 + 公告） |
| 安全隐患 | `/risk/hiddenDanger` | 隐患上报、整改、复查、销项闭环 |
| 危险源上报 | `/risk/dangerSource` | 危险源登记、风险等级评估、防控措施 |
| 风险警示 | `/risk/warning` | 风险预警信息发布跟踪 |
| 特种设备 | `/risk/specialEquipment` | 设备台账、检验日期、维护记录 |
| 人员信息 | `/risk/personnel` | 员工档案、岗位、工种 |
| 人员变更 | `/risk/personnelChange` | 岗位/部门/工种变动履历 |
| 人员证书 | `/risk/personnelCert` | 特种作业证、健康证等 |
| 作业上报 | `/risk/workReport` | 高危作业申报、审批、监护 |
| 事故上报 | `/risk/accident` | 事故登记、调查、考核、闭环 |
| 巡检任务 | `/risk/inspectionTask` | 巡检计划、打卡、巡检项/记录/详情 |
| 舆情推送 | `/risk/publicOpinion` | 重大舆情监测、影响范围、定级处置 |

> 所有页面均遵循 `风险模块 1080P 分辨率 UI 统一规范`，搜索框前必须有"关键词"标签，筛选项不折行。

---

## 三、技术栈

| 技术 | 版本 | 用途 |
|---|---|---|
| Vue | 3.5.x | 主框架 |
| TypeScript | 5.x | 类型系统 |
| Vite | 5.x | 构建工具 |
| Element Plus | 2.x | UI 组件库 |
| Pinia | 2.x | 状态管理 |
| Vue Router | 4.x | 路由 |
| ECharts | 5.x | 图表（仪表盘趋势/饼图） |
| Axios | 1.x | HTTP 客户端（含加密拦截器） |
| VueUse | 10.x | 组合式工具集 |
| @vueup/vue-quill | 1.x | 富文本编辑器 |
| @element-plus/icons-vue | 2.x | 图标 |

---

## 四、项目结构

```
plus-ui/
├── public/                          # 静态资源
│   └── favicon.ico
│
├── src/
│   ├── api/                         # API 接口层
│   │   ├── system/                  # 系统模块接口
│   │   ├── monitor/
│   │   ├── tool/
│   │   ├── workflow/
│   │   └── risk/                    # ★ 风控业务接口（14 个 ts）
│   │       ├── types.ts
│   │       ├── dashboard.ts
│   │       ├── hiddenDanger.ts
│   │       ├── dangerSource.ts
│   │       ├── warning.ts
│   │       ├── specialEquipment.ts
│   │       ├── personnel.ts
│   │       ├── personnelChange.ts
│   │       ├── personnelCert.ts
│   │       ├── workReport.ts
│   │       ├── accident.ts
│   │       ├── inspectionTask.ts
│   │       ├── inspectionItem.ts
│   │       ├── publicOpinion.ts
│   │       ├── auditFile.ts
│   │       ├── file.ts
│   │       └── equipmentMaintenance.ts
│   │
│   ├── assets/                      # 资源（图片、样式）
│   ├── components/                  # 通用组件
│   │   ├── FileUpload/              # 文件上传（MinIO）
│   │   ├── ImageUpload/             # 图片上传
│   │   └── ... (20+ 个)
│   │
│   ├── directive/                   # 自定义指令
│   ├── enums/                       # 枚举
│   ├── hooks/                       # 组合式函数
│   ├── lang/                        # 国际化
│   ├── layout/                      # 布局（侧边栏、头部、面包屑）
│   ├── plugins/                     # 插件
│   ├── router/                      # 路由 + 动态菜单
│   ├── store/                       # Pinia 状态
│   │   └── modules/
│   │       ├── user.ts              # 用户/登录/Token
│   │       ├── permission.ts        # 动态路由权限
│   │       ├── dict.ts              # 字典缓存
│   │       └── ...
│   │
│   ├── types/                       # 全局类型声明
│   ├── utils/                       # 工具类
│   │   ├── request.ts               # axios 封装（含加密）
│   │   ├── auth.ts                  # Token 工具
│   │   ├── minio.ts                 # ★ MinIO 文件工具
│   │   └── ... (19 个)
│   │
│   ├── views/                       # 页面
│   │   ├── index.vue                # 工作台首页
│   │   ├── login.vue                # 登录页
│   │   ├── system/                  # 系统管理页面
│   │   └── risk/                    # ★ 风控业务页面（10 个）
│   │       ├── hiddenDanger/
│   │       ├── dangerSource/
│   │       ├── warning/
│   │       ├── specialEquipment/
│   │       ├── personnel/
│   │       ├── personnelChange/
│   │       ├── workReport/
│   │       ├── accident/
│   │       ├── inspectionTask/
│   │       └── publicOpinion/
│   │
│   ├── App.vue                      # 根组件
│   ├── main.ts                      # 入口
│   ├── permission.ts                # 路由守卫
│   └── settings.ts                  # 全局配置
│
├── vite/
│   └── plugins/                     # Vite 自定义插件
│       ├── auto-import.ts
│       ├── components.ts
│       ├── compression.ts
│       ├── icons.ts
│       ├── unocss.ts
│       └── ...
│
├── .env.development                 # 开发环境配置
├── .env.production                  # 生产环境配置
├── index.html
├── vite.config.ts
├── tsconfig.json
├── uno.config.ts                    # UnoCSS 原子化样式
├── eslint.config.ts
├── package.json
└── README.md
```

---

## 五、本地开发

### 环境要求

- Node.js 18+（推荐 20+）
- npm 9+ 或 pnpm 8+

### 启动

```bash
# 1. 安装依赖
npm install --registry=https://registry.npmmirror.com

# 2. 启动开发服务器（默认 :80，代理后端 :8080）
npm run dev

# 3. 构建生产环境
npm run build:prod       # 输出至 dist/

# 4. 本地预览构建产物
npm run preview
```

### 脚本命令

| 命令 | 说明 |
|---|---|
| `npm run dev` | 开发模式（热更新） |
| `npm run build:prod` | 生产环境构建 |
| `npm run preview` | 预览 dist 产物 |
| `npm run lint` | ESLint 检查 |
| `npm run lint:fix` | ESLint 自动修复 |

---

## 六、环境变量

### `.env.development`（开发环境）

```bash
# API 基础路径（开发时通过 Vite proxy 代理到后端 :8080）
VITE_APP_BASE_API = '/dev-api'

# 登录加密（开发环境关闭以便调试）
VITE_APP_ENCRYPT = 'false'

# 应用标题
VITE_APP_TITLE = '风控品控管理系统'
```

### `.env.production`（生产环境）

```bash
# 生产 API 基础路径（Nginx 反代 /prod-api → 后端 :8080）
VITE_APP_BASE_API = '/prod-api'

# 登录加密（生产必须开启）
VITE_APP_ENCRYPT = 'true'

# 应用标题
VITE_APP_TITLE = '风控品控管理系统'
```

---

## 七、路由与菜单

### 路由结构

- **静态路由**：`src/router/staticRoutes.ts` 定义无需权限的路由（login、404、index）
- **动态路由**：登录后根据 `sys_menu` 表查询用户的菜单权限，动态注入到 `src/router/index.ts`

### 新增业务页面流程

1. 在 `src/api/risk/` 添加 API 接口（参考 `hiddenDanger.ts`）
2. 在 `src/views/risk/<module>/index.vue` 实现页面
3. 在 `src/router/index.ts` 注册路由（meta 中配置 title / icon / affix / noCache）
4. 在系统管理 → 菜单管理 新增菜单数据（参考 `sql/risk_menu.sql`）
5. 重新登录，前端按角色拉取菜单权限

### 滚动规范

所有 RuoYi 路由页面（被 `AppMain` 容器 `overflow: hidden` 裁切的）根容器需使用：

```scss
.xxx-page {
  padding: 16px;
  height: 100%;        // 继承父级 .app-main 高度
  overflow-y: auto;    // 内容超出时出现滚动条
  box-sizing: border-box;
}
```

已应用：hiddenDanger / dangerSource / warning / specialEquipment / personnel / personnelChange / workReport / accident / inspectionTask / publicOpinion

---

## 八、HTTP 请求与加密

### 拦截器

`src/utils/request.ts` 统一处理：

- **请求加密**：登录/register 接口 body 使用 `jsencrypt + crypto-js` 进行 AES+RSA 加密
- **响应解密**：根据 `isEncrypt` 配置决定是否解密
- **Token 注入**：自动添加 `Authorization: Bearer xxx` 请求头
- **错误统一处理**：401 → 跳登录；500 → 弹消息

### 加密开关

| 环境 | 加密状态 | 原因 |
|---|---|---|
| 开发 | 关闭 | 便于在浏览器 DevTools 中查看请求体 |
| 生产 | 开启 | 防止中间人攻击、降低可破解性 |

> 前后端配套：`api-decrypt.enabled=true` 必须与前端 `VITE_APP_ENCRYPT=true` 一致。

---

## 九、组件库约定

### 表格（el-table）

- 行点击通过 `row-click` 事件跳转详情页
- 列定义在 `columns` 数组中，状态/等级字段用 `el-tag` 配合 `type` 颜色
- 操作列固定右侧，使用 `<el-button size="small" link>` 风格

### 表单（el-form）

- 1080P 适配：`label-width="84px"`（hiddenDanger）或 `label-width="90px"`（其他风险模块）
- 搜索框前必须有"关键词"标签
- 必填项用 `<el-form-item label="xxx" required>` 标识

### 弹窗（el-dialog）

- 宽度按内容分档：新增/编辑 `600px`，详情 `800px`，富文本 `900px`
- 提交前 `await formRef.value.validate()`
- 关闭时 `formRef.value.resetFields()`

---

## 十、构建与部署

### 构建

```bash
npm run build:prod
# 输出至 dist/
#  - dist/index.html
#  - dist/assets/*.js
#  - dist/assets/*.css
#  - dist/assets/*.svg
```

### Nginx 部署示例

```nginx
server {
    listen 80;
    server_name risk.example.com;
    root /var/www/risk-ui/dist;
    index index.html;

    # 前端 SPA fallback
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 反向代理后端 API
    location /prod-api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        client_max_body_size 100m;
    }
}
```

---

## 十一、配套后端

- **后端仓库**: http://134.175.81.27:3000/yangjingjing/risk_control_platform.git
- **后端框架**: RuoYi-Vue-Plus 5.6.2
- **数据库**: MySQL 8.0（库名 `risk_control_platform`）
- **缓存**: Redis 6.0+
- **对象存储**: MinIO
- **鉴权**: Sa-Token

---

## 十二、版本历史

| 版本 | 日期 | 说明 |
|---|---|---|
| v1.0.0 | 2026-06 | 整合 10 大风控业务模块，首版上线 |

---

## 十三、致谢

基于开源框架 [plus-ui](https://gitee.com/JavaLionLi/plus-ui) 开发，遵循 MIT 协议开源。