zhanghj
232 lines
15 KiB
Markdown
232 lines
15 KiB
Markdown
# SHJ_APP 业务功能框架
|
||
|
||
> 本文档面向业务理解与新人上手，梳理项目的完整功能结构、业务流程、权限体系与接口分布。
|
||
> 技术架构与编码约定见 `AGENTS.md`。
|
||
|
||
## 一、项目定位
|
||
|
||
**管道安装管理系统**（施工管理 App），服务于管道预制与安装现场的两条主线业务：
|
||
|
||
1. **焊接工序质检链**（扫码驱动）：下料 → 组对 → 焊接 → 防腐，逐级填报 + 互检上一工序。
|
||
2. **物流配送链**（状态机驱动）：预制组件 → 包装（组包）→ 车次（装车发货）→ 到场签收 / 验收。
|
||
|
||
辅助业务：点口管理（NDE 委托批次）、试压管理（试压包条件确认）、待办、焊接数据看板。
|
||
|
||
- 运行端：微信小程序为主，兼容 H5 / App。
|
||
- 后端：`https://lygcgs.com.cn:8078/shjapi/api/`（接口）、`https://lygcgs.com.cn:8078/shj/`（附件）。
|
||
- 后端约定：`body.code === 1` 成功；`401` 自动登出；多数"写"操作也是 GET 带参，仅保存类用 POST。
|
||
|
||
## 二、页面与路由总览
|
||
|
||
```
|
||
主包
|
||
├── pages/login/index 登录（非 tab）
|
||
├── pages/index/index 首页工作台（tab）
|
||
├── pages/mine/index 我的（tab）
|
||
└── pages/todo/list 待办（首页进入，非 tab）
|
||
|
||
分包 pipe（管理类业务，共 13 页）
|
||
├── diankou/ list、port_list 点口管理
|
||
├── pressure/ index、pressure_before/list|detail、 试压管理
|
||
│ check_remove/list（空页面）
|
||
├── packaging/ list、add、detail 包装管理
|
||
├── deliver/ list、detail 发货管理（车次）
|
||
└── precast/ list、detail 预制组件管理
|
||
|
||
分包 scanpages（扫码类业务，共 7 页）
|
||
└── hj/ materials_detail 材料详情（扫材料条码）
|
||
material_sampling 下料抽检（工序①）
|
||
make_right 组对抽查（工序②）
|
||
daily_paper 焊接日报（工序③，扫焊接接头码）
|
||
do_anti_rust 防腐处理（工序④）
|
||
daily_audit 日报审核列表（专工批量审核/删除）
|
||
daily_audit_detail 日报审核详情（单条审核/删除）
|
||
```
|
||
|
||
tabBar 仅两个 tab：首页、个人中心。待办从首页图标进入。
|
||
|
||
## 三、登录与权限体系
|
||
|
||
### 3.1 登录
|
||
|
||
- `POST user/postLoginOn` → 返回 `PersonId`（即 token，每请求以 `token` 头携带）、`UserType`、`WorkPostName`（岗位）、默认项目 `LoginProjectId/LoginProjectName`。
|
||
- 登录成功 → 设当前项目 → reLaunch 首页；账号密码持久化记住。
|
||
- user store 中 `watch(currentProject.ProjectId)`：项目变化自动重拉①菜单权限 ②焊接看板数据。
|
||
|
||
### 3.2 菜单权限（双重过滤，`store/modules/menu.js` 的 `appVisible`）
|
||
|
||
| 层 | 来源 | 规则 |
|
||
|---|---|---|
|
||
| 后端权限 | `GET User/getMenuPowerList?userId&projectId` | 返回有权限的菜单 GUID 数组，与 `defaultApps` 中 5 个管理类应用的 `menuId` 匹配 |
|
||
| 岗位权限 | 小程序端硬编码 `utils/constant.js` 的 `postMenuPermissions` | 仅对 `UserType === '3'` 现场人员按 `WorkPostName` 限制 4 个扫码功能；pipe 管理类应用对现场人员一律隐藏；其余用户不限制 |
|
||
|
||
岗位 → 扫码功能对照（`sampling` 下料 / `makeRight` 组对 / `antiRust` 防腐 / `dailyPaper` 日报 / `dailyAudit` 日报审核）：
|
||
|
||
- 全部 4 项 + 日报审核：项目经理、项目总工、控制经理、安环经理、质量经理、材料部长、防腐/费控/物流/管道/包装工程师、项目信息员、材料员、资料员、技术员、质量员、施工员
|
||
- 焊工：下料、组对、日报
|
||
- 管工：全部 4 项（无日报审核）
|
||
- 防腐工：仅防腐
|
||
- 无损检测工：仅日报
|
||
- 未列出岗位：无扫码功能权限
|
||
|
||
扫码跳转页面前统一过 `menuStore.canAccessPath` 校验（首页扫一扫已接入）。
|
||
|
||
### 3.3 操作权限
|
||
|
||
详情页的「到场确认 / 验收」类按钮由 **`from=0`（扫码入口）+ 后端返回 `isPower`** 双重控制（包装到场确认、预制组件验收）。
|
||
|
||
## 四、首页工作台（pages/index/index.vue）
|
||
|
||
- **项目选择**：`nbd-select` 弹窗（可搜索），`GET Project/getProjectsByUserId`；切换项目触发权限与看板数据重拉。
|
||
- **扫一扫**（通用入口，分流规则见 §6）。
|
||
- **待办入口** → `/pages/todo/list`。
|
||
- **焊接数据看板**：`GET HJGLIndex/GetJGLIndexItem?projectId`，展示工厂/现场焊接一次合格率、预制进度、焊接功效、管道实时预制率。
|
||
- **快捷应用 + 业务查询**：8 个应用（5 管理类 + 3 扫码类），底部弹窗编辑勾选（可搜索），选中态按 `path` 持久化；点击进入前若无当前项目先弹项目选择；`isScan` 应用点击即调起扫码。
|
||
|
||
## 五、pipe 分包：管理类业务
|
||
|
||
所有列表页同构：filter-header（`nbd-select`/`u-search`/`u-radio-group`）+ scroll-view（下拉刷新 + 上拉分页）+ 卡片 + 空态。新列表页参照 `pipe/packaging/list.vue`。
|
||
|
||
### 5.1 点口管理 diankou（NDE 委托）
|
||
|
||
| 页面 | 功能 |
|
||
|---|---|
|
||
| `list` | 点口批次列表：单位工程筛选 + 批号搜索；接口 `NDETrust/getNotEndPointBatch` |
|
||
| `port_list` | 批次内焊口明细（管线号/焊口代号/已点未点状态）；接口 `NDETrust/getPointBatchDetail`。⚠️「自动点口/强制关闭/点口调整」三个按钮目前为 TODO 桩 |
|
||
|
||
### 5.2 试压管理 pressure
|
||
|
||
| 页面 | 功能 |
|
||
|---|---|
|
||
| `index` | 导航页：试压前条件确认 / 尾项检查及消项 |
|
||
| `pressure_before/list` | 试压包列表：单位工程（必选）+ 具备/不具备条件 + 包号搜索；接口 `TestPackage/getTestPackageNo` |
|
||
| `pressure_before/detail` | 试压包焊口统计表：按管线号展示焊口完成数、合格/不合格数、实际/应检检测比例，前端按完成度着色（红/黄/紫/绿/青），纯展示；接口 `TestPackage/GetTestPackageDetail` |
|
||
| `check_remove/list` | ⚠️ 空页面（尾项检查及消项未开发） |
|
||
|
||
### 5.3 包装管理 packaging（组包）
|
||
|
||
- **状态机**：0 未到场 → 1 已发货 → 2 已到场。
|
||
- `list`：包装编号搜索 + 车次关联筛选 + 单位筛选；卡片含 `PackagingCode`、`State`、预制工作包、车次、数量、签收信息；FAB 进新增。
|
||
- `add`：先取号（`GetPackagingNumberByProjectId`）→ 填预制工作包、包装分类（字典 `GetPackagingCategories`）→ `POST PackagingManage/SavePackaging` → 跳详情。
|
||
- `detail`：`State==0` 时可**扫码添加预制组件**（扫 `PrePipeline$` 前缀码 → 查详情 → 防重 → `SavePipelineComponentToPackaging`）与删除；`from=0` 且 `isPower` 显示「确定到场」（`GetPackingInfoConfirmArrival`）。
|
||
|
||
### 5.4 发货管理 deliver（车次）
|
||
|
||
- **状态机**：0 待发货 → 1 已发货 → 2 已签收。
|
||
- `list`：单位筛选；卡片含 `TrainNumber`、状态标签、驾驶员/车牌/联系人；接口 `TrainNumberManage/GetTrainNumberList?preapitype=3`。
|
||
- `detail`（新增/编辑/发货/签收一体）：
|
||
- 待发货：必填表单（车次/单位/驾驶员/车牌/联系人）→ `POST SaveTrainNumber`；可**扫码添加包装**（扫 `PackagingManage$` 码 → 弹窗确认 → `SavePackagingToTrain`）；
|
||
- 底部按钮按状态切换：保存/发货 → 签收（`SaveTrainInfoConfirmArrival`）→ 只读。
|
||
- ⚠️ 已知 bug：`handleSign` 按位置参数调 `reqTrainInfoConfirmArrival(userId, id)`，但 api 签名为 `(params={})` 解构，签收参数会错。
|
||
|
||
### 5.5 预制组件管理 precast
|
||
|
||
- **状态机**：0 未验收 / 1 已验收 / 2 已出库 / -2 待整改 / -1 已整改。
|
||
- `list`：`u-tabs` 按五状态切换；卡片含图纸名、组件编号 `PipelineComponentCode`、物流箱号、计划安装日期、验收人。
|
||
- `detail`：组件信息展示；`from=0` + `isPower` + `State==0` 时显示验收区：通过/不通过（不通过须选 5 项硬编码验收意见之一：焊缝外观成形差/未酸洗/标识不全/污迹/未进行成品保护）→ `GetComponentConfirmArrival` 确认后回首页。
|
||
|
||
### 5.6 物流链串联
|
||
|
||
```
|
||
预制组件(扫码 PrePipeline$) → 加入包装(组包) → 包装(扫码 PackagingManage$) → 挂到车次(装车)
|
||
→ 发货 → 现场签收/包装到场确认 → 预制组件验收
|
||
```
|
||
|
||
## 六、scanpages 分包：扫码业务与工序链
|
||
|
||
### 6.1 扫码分流规则（首页 handleScan + utils/scanUtils.js）
|
||
|
||
| 扫码内容 | scanType | 去向 |
|
||
|---|---|---|
|
||
| 焊接接头二维码（URL 含 `weldjoint`，取 `id`） | QR_CODE | `daily_paper?id=`（先过岗位权限校验） |
|
||
| 其他二维码 | QR_CODE | toast「无对应业务」 |
|
||
| 材料条码（原文即材料编码） | 非 QR_CODE | `materials_detail?id=` |
|
||
| 菜单扫码（下料/组对/防腐入口） | 不限 | 取 URL 中 `id` 参数拼到目标页 |
|
||
|
||
### 6.2 工序互检链
|
||
|
||
```
|
||
下料抽检(焊口) → 组对抽查(焊口) → 焊接日报(焊口) → 防腐处理(材料)
|
||
每个页面可查看「上一工序记录」并跳转互检：
|
||
daily_paper → make_right → material_sampling → do_anti_rust
|
||
```
|
||
|
||
### 6.3 各页面要点
|
||
|
||
| 页面 | id 含义 | 核心填报字段 | 提交接口 |
|
||
|---|---|---|---|
|
||
| `materials_detail` 材料详情 | 材料编码 | 只读档案（MaterialCode/炉号/批号/规格等）+ **蓝牙打印标签** | `BaseInfo/GetMaterialInfoByMaterialCode` |
|
||
| `material_sampling` 下料抽检 | WeldJointId | 下料长度、坡口形式/角度、材料编码与数量是否准确、检查结果（不合格填原因+整改）、备注、照片 | `POST PreWeldCuttingCheck/SaveRecord` |
|
||
| `make_right` 组对抽查 | WeldJointId | 坡口加工类型、组对间隙、错边量、检查结果、原因/整改、备注、照片 | `POST PreWeldFitupCheck/SaveRecord` |
|
||
| `daily_paper` 焊接日报 | WeldJointId | 焊口位置（字典）、焊接日期、焊工类型（打底/盖面）、焊工、焊接方法、焊前/焊后拍照；已有日报时可一键「点口」（`NDETrust/getManualPointSave`） | `POST PreWeldingDaily/SaveWeldingDailyByWeldJointId` |
|
||
| `do_anti_rust` 防腐处理 | MaterialCode | 防腐等级（联动带出中间漆/面漆）、漆膜厚度、喷砂/除锈情况、自检结果、备注、照片 | `POST AntiCorrosionCheck/SaveRecord` |
|
||
|
||
- 各工序页进入时拉对应记录列表回填（`GetRecordsByWeldJointId` / `GetRecordsByMaterialCode`），历史记录用 `nbd-record-card` 展示。
|
||
- 照片统一走 `nbd-photo-upload`（仅相机拍照）→ `FileUpload/Post` 上传 → 逗号分隔路径回写。
|
||
|
||
### 6.4 日报审核（daily_audit / daily_audit_detail）
|
||
|
||
焊工填报的日报先进入待审核（Temp）状态，由专工在小程序端审核，与 PC 端一致：
|
||
|
||
- **入口**：首页应用网格「日报审核」（`dailyAudit` 功能 key，见 §3.2）。
|
||
- **列表页**：筛选为单位工程（`nbd-select`）+ 焊接日期 + 管线编号 + 焊工编号；卡片展示焊口编号/管线编号/焊接日期/焊工/焊接方法/提交人/提交时间；支持勾选（含全选）后底部栏**批量审核通过 / 批量删除**；点卡片进详情。不分页，一次拉全部待审核记录。
|
||
- **详情页**：版式参照焊接日报（焊口主标识 + 焊口信息 + 日报信息，照片用 `nbd-photo-view` 只读展示焊前/焊后/附件），底部「审核通过 / 删除」单条操作。
|
||
- 接口（`api/hj.js`）：
|
||
- `GET PreWeldingDaily/GetPendingWeldingDailyTempDetailList`（待审核列表：projectId 必填，unitWorkId/weldingDate/pipelineCode/welderCode/pageIndex 可选）
|
||
- `GET PreWeldingDaily/GetPendingWeldingDailyTempDetail`（单条明细）
|
||
- `POST PreWeldingDaily/AuditPendingWeldingDailyTempDetails`（批量审核：`{TempDetailIds, AuditMan}`）
|
||
- `POST PreWeldingDaily/DeletePendingWeldingDailyTempDetails`（批量删除：`{TempDetailIds}`）
|
||
|
||
### 6.5 标签打印（nbd-print-prop）
|
||
|
||
- 蓝牙热敏标签打印组件：bwip-js 生成 **PDF417** 条码（隐藏 canvas，203dpi 换算），经 `assets/js/js_sdk`（LPAPI 蓝牙打印机 SDK）绘制 50×30mm 标签（上文字 + 条码 + 下文字）并打印；支持打印机搜索、出纸方向、浓度/速度等参数。
|
||
- 微信小程序无原生 `atob`，`main.js` 顶部内联 polyfill（`utils/bwipjs-polyfill.js` 为双保险）。
|
||
- 目前仅材料详情页使用。
|
||
|
||
## 七、其他主包页面
|
||
|
||
- **我的 mine**：用户信息卡（姓名/账号/单位）、当前项目卡、退出登录；不调接口；个人设置/改密/关于已注释预留。
|
||
- **待办 todo**：按 `MenuName` 着色的待办卡片列表，点击按 `UrlStr` 拼参跳转。⚠️ 当前 `USE_MOCK = true` 用 mock 数据；真实接口 `ToDoItem/getToDoItemByProjectIdUserId` 代码已预留但未 import，切换前需补导入。
|
||
|
||
## 八、接口层分布（api/）
|
||
|
||
| 文件 | 职责 | 代表接口 |
|
||
|---|---|---|
|
||
| `auth.js` | 登录与菜单权限 | `user/postLoginOn`、`User/getMenuPowerList` |
|
||
| `user.js` | 用户相关 | `Project/getProjectsByUserId` |
|
||
| `base.js` | 基础数据字典 + 附件上传 | `BaseInfo/getProjectWorkArea`（单位工程）、`getWeldingLocation`（焊口位置）、`GetGrooveType`（坡口类型）、`Unit/getUnitByProjectIdUnitType`（单位）、`FileUpload/Post`（`uploadAttach`） |
|
||
| `hj.js` | 全业务接口合集（焊接/点口/包装/车次/预制/试压/扫码质检，30+ 个） | 见 §5、§6 各模块 |
|
||
|
||
请求封装 `utils/request.js`：自动带 token 头、GET 参数对象自动编码（兼容 URL 拼接旧风格）、默认 loading、`code!==1` 自动 toast + reject、`401` 自动登出；`parseAttachUrls` 解析逗号分隔附件为可展示列表。
|
||
|
||
## 九、状态管理（Pinia，组合式）
|
||
|
||
| Store | 状态 | 持久化 |
|
||
|---|---|---|
|
||
| `user` | `token`（=PersonId）、`userInfo`、`loginForm`、`projectList`、`currentProject`；watch 项目变化联动拉权限+看板 | `loginForm/userInfo/token/currentProject` |
|
||
| `menu` | `appsList`、`quickAppIds`、`editCache`、`menuProwerList`；`appVisible` 双重权限过滤；`hasPostPermission`/`canAccessPath` | 仅 `quickAppIds` |
|
||
| `large` | `hjIndexData`（焊接看板） | 否 |
|
||
|
||
## 十、公共组件（components/，easycom 自动注册）
|
||
|
||
| 组件 | 用途 |
|
||
|---|---|
|
||
| `nbd-select` | 底部弹窗选择器（单/多选、搜索），项目/单位/字典选择统一用它 |
|
||
| `nbd-record-card` | 通用记录卡片（text/tag/photo 字段、条件显示、合格状态着色），扫码工序页展示历史记录 |
|
||
| `nbd-check-btn` | 通过/不通过二选一按钮组 |
|
||
| `nbd-photo-upload` | 拍照上传（仅相机、最多 6 张、逗号分隔回写） |
|
||
| `nbd-photo-view` | 附件照片只读网格 + 预览 |
|
||
| `nbd-submit-bar` | 底部渐变提交按钮（带 loading 拦截） |
|
||
| `nbd-print-prop` | 蓝牙标签打印弹窗（scanpages 分包组件） |
|
||
|
||
## 十一、已知未完成项与问题清单
|
||
|
||
| 位置 | 问题 |
|
||
|---|---|
|
||
| `pipe/diankou/port_list.vue` | 自动点口/强制关闭/点口调整三个按钮为 TODO 桩 |
|
||
| `pipe/pressure/check_remove/list.vue` | 空页面，尾项检查及消项未开发 |
|
||
| `pipe/deliver/detail.vue` | 签收接口参数签名不匹配（位置参数 vs 对象解构），疑似 bug |
|
||
| `pages/todo/list.vue` | 使用 mock 数据，真实接口已预留未启用（且缺 import） |
|
||
| `pipe/deliver/list.vue` | 用 `onMounted` 而非页面级生命周期，与项目约定不符 |
|
||
| `make_right.vue` | 坡口类型下拉已写好但模板中仍是手输 input |
|