risk_control_platform_app

风控品控管理系统 — 移动端（uniapp）

**uniapp 3.x** | **Vue 3.4** | **TypeScript 5** | **Vite 5** 巡检打卡 · 隐患排查 · 风险管控

---

一、项目简介

本仓库是 风控品控管理系统 的移动端（uniapp）项目，基于 DCloud 官方 Vue3 + Vite 模板深度定制。

已实现模块

模块	路由	状态
工作台首页	/pages/index/index	✅
巡检任务列表	/pages/inspection/list/index	✅
巡检打卡	/pages/inspection/check/index	✅
扫码打卡	/pages/inspection/scan/index	✅

仅 H5 端已验证可运行；APP / 微信小程序端需要真机调试。

---

二、技术栈

技术	版本	用途
uniapp	3.x	跨端框架（iOS / Android / H5 / 微信小程序 / 抖音小程序）
Vue	3.4	Composition API
TypeScript	5.x	类型系统
Vite	5.x	构建工具
Sass	1.69	SCSS 预处理器

不使用 uView 等第三方组件库，所有 UI 元素手写 + SCSS 实现，便于定制和体积优化。

---

三、项目结构

uniapp/
├── src/
│   ├── api/                      # API 接口层
│   │   └── inspection.ts         # 巡检相关接口（列表、详情、提交、扫码校验）
│   │
│   ├── types/                    # 全局类型声明
│   │   └── inspection.ts         # InspectionTask / InspectionItem / Payload 等
│   │
│   ├── utils/                    # 工具类
│   │   └── location.ts           # 位置工具（Haversine 距离 / 授权）
│   │
│   ├── static/
│   │   └── styles/
│   │       ├── variables.scss    # 颜色/间距/字号/圆角变量
│   │       └── common.scss       # 通用工具类（flex / tag / btn / 间距）
│   │
│   ├── components/               # 业务组件（easycom 自动注册）
│   │
│   ├── pages/                    # 页面
│   │   ├── index/index.vue       # 首页（入口）
│   │   └── inspection/
│   │       ├── list/index.vue    # 巡检任务列表
│   │       ├── check/index.vue   # 巡检打卡
│   │       └── scan/index.vue    # 扫码中间页
│   │
│   ├── App.vue                   # 根组件
│   ├── main.ts                   # 入口
│   ├── pages.json                # 路由与 tabBar 配置（uniapp 必需）
│   └── manifest.json             # 应用配置（uniapp 必需）
│
├── index.html                    # H5 入口
├── vite.config.ts
├── tsconfig.json
├── package.json
└── README.md

---

四、核心页面

4.1 巡检任务列表

功能：

• 顶部 Tab 切换：全部 / 未打卡 / 已打卡
• 右上角筛选按钮（按巡检类型）
• 卡片列表显示 8 个字段：任务名称、巡检类型、打卡方式、门店、打卡地点、任务完成时间、实际打卡时间（仅已打卡）、打卡结果（仅已打卡）
• 状态标签颜色：已打卡 = 绿色，未打卡 = 橙色，已过期 = 灰色
• 结果标签颜色：正常 = 绿色，异常 = 橙色
• 操作按钮：未打卡 → 「前去打卡」（蓝色），已打卡 → 「查看详情」（默认色）
• 下拉刷新 + 上拉加载更多

跳转逻辑：

if (punchType === 'NORMAL') {
  // 常规打卡：直接跳到打卡页
  navigateTo('/pages/inspection/check/index?taskId=' + id)
} else if (punchType === 'SCAN') {
  // 扫码打卡：先跳到扫码页
  navigateTo('/pages/inspection/scan/index?taskId=' + id)
}

4.2 扫码中间页

功能：

• 拉起摄像头（仅 APP / 微信小程序原生支持，H5 退化为手动输入）
• 调用 uni.scanCode 识别二维码
• 校验顺序：
  1. 二维码与任务绑定关系（/risk/inspectionTask/verifyQr）
  2. 当前位置与点位距离 ≤ X 米（X 取自系统配置 scan_limit_meter，默认 100 米）
  3. 校验通过后跳到打卡页
• 顶部/底部/左右黑色遮罩 + 4 个角的蓝色边框 + 上下扫描动画线

距离计算：utils/location.ts 中 calculateDistance() 使用 Haversine 公式。

4.3 巡检打卡页

功能：

• 顶部只读：巡检名称、巡检位置（含 📍 icon）
• 巡检项目卡片（多个）：
  • 项目大类（蓝色背景小标签）
  • 巡检内容
  • 巡检标准
  • 检查结果：正常 / 异常 按钮（二选一，可取消）
  • 异常时显示异常原因输入框（必填，maxlength=200）
  • 「是否需要拍照」项才显示现场照片上传区（支持多张，可删除）
• 底部「提交打卡」按钮：固定底部，蓝色，高度 88rpx

校验逻辑（提交前）：

1. 每个项目必须选择正常/异常
2. 选择异常时必须填写原因
3. 「是否需要拍照」项必须上传至少 1 张照片
4. 获取当前位置（用于考勤记录）

成功弹窗：

• 半透明遮罩 + 居中卡片
• 绿色 ✓ 图标 + "提交成功"标题 + "巡检结果已成功保存"副标题
• 蓝色 "返回巡检列表"按钮，点击后回退并强制刷新列表

4.4 只读模式

点击「查看详情」进入打卡页时携带 ?readonly=1：

• 所有选择按钮 disabled
• 照片区不显示删除 ×
• 底部无「提交打卡」按钮
• 用户只能查看，不可修改

---

五、跨端适配

平台	支持情况	备注
H5	✅ 完整	浏览器 + 移动端 H5
Android	✅	需自定义基座 / 真机调试
iOS	✅	需 Apple 证书
微信小程序	✅	需在 manifest.json 填入 appid
抖音/支付宝小程序	⚠️	可能需调整 API

扫码 API 限制：

• uni.scanCode 在 H5 端无法直接拉起摄像头
• 解决方案：H5 端点击「前去打卡」扫码任务时，自动跳到「手动输入」弹窗

---

六、本地开发

环境要求

• Node.js 18+（推荐 20 LTS）
• npm 9+ 或 pnpm 8+
• HBuilderX（推荐，IDE 自带真机调试）或 VSCode + 命令行

安装与运行

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

# 2. 启动 H5 开发服务器（默认 :9000）
npm run dev:h5

# 3. 启动微信小程序（需在 manifest.json 填入 appid）
npm run dev:mp-weixin

# 4. 生产构建
npm run build:h5           # H5 静态资源输出到 dist/
npm run build:mp-weixin    # 微信小程序输出到 dist/dev/mp-weixin

浏览器访问

启动后访问 http://127.0.0.1:9000/，按 F12 切到移动端模拟器（iPhone 14 Pro 390×844）体验。

后端联调

vite.config.ts 中已配置代理：

proxy: {
  '/dev-api': {
    target: 'http://127.0.0.1:8080',  // RuoYi-Vue-Plus 后端
    changeOrigin: true
  }
}

确保后端 http://127.0.0.1:8080 已启动且：

• 已实现 GET /risk/inspectionTask/mobileList
• 已实现 GET /risk/inspectionTask/{id}
• 已实现 POST /risk/inspectionRecord/punch
• 已实现 POST /risk/inspectionTask/verifyQr

演示模式：未连接后端时，loadDetail() 与 listInspectionTasks() 会自动 fallback 到 mock 数据（消防设备、电气安全、通道畅通 3 个示例项目）。

---

七、API 对接规范

所有接口统一走 RuoYi-Vue-Plus 后端，基础路径 /dev-api（开发）/ /prod-api（生产）：

// 列表
GET /risk/inspectionTask/mobileList?status=ALL&pageNo=1&pageSize=10
Response: {
  code: 200,
  msg: 'ok',
  data: {
    total: 3,
    rows: InspectionTask[],
    pageNum: 1,
    pageSize: 10
  }
}

// 详情
GET /risk/inspectionTask/{id}
Response: { code: 200, data: InspectionTask }

// 校验二维码
POST /risk/inspectionTask/verifyQr
Body: { taskId: number, qrContent: string }
Response: { code: 200, data: { valid: boolean } }

// 提交打卡
POST /risk/inspectionRecord/punch
Body: {
  taskId: number,
  longitude: number,
  latitude: number,
  punchType: 'NORMAL' | 'SCAN',
  items: Array<{ itemId, result, reason?, photos? }>
}
Response: { code: 200, data: { punchId: number } }

---

八、构建与部署

H5 部署

npm run build:h5
# 输出至 dist/ 目录

Nginx 配置示例：

server {
    listen 80;
    server_name m.example.com;
    root /var/www/risk-mobile/dist/build/h5;
    index index.html;
    location / { try_files $uri $uri/ /index.html; }
    location /prod-api/ {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
    }
}

APP 打包

使用 HBuilderX 打开项目 → 发行 → 原生 APP-云打包，上传证书后生成 apk / ipa。

微信小程序

npm run build:mp-weixin
# 用微信开发者工具导入 dist/dev/mp-weixin

---

九、配套仓库

端	仓库
后端	http://134.175.81.27:3000/yangjingjing/risk_control_platform.git
PC Web 前端	http://134.175.81.27:3000/yangjingjing/risk_control_platform_ui.git
移动端（本仓）	http://134.175.81.27:3000/yangjingjing/risk_control_platform_app.git

---

十、版本历史

版本	日期	说明
v1.0.0	2026-06	巡检模块首版上线（列表 + 打卡 + 扫码）