DOPJAVA/docs/qms/IQC开发流程与注意事项.md

IQC 开发流程与注意事项（AI 友好版）

目标：让 AI/新人能够快速定位 IQC 功能的页面、接口、数据库字段映射和流程联动。

---

1. 模块范围

• IQC 来料检验申请：创建/编辑/查看申请单（主表 + 子表）。
• IQC 来料检验任务：基于申请子表生成任务列表，触发流程。
• IQC 检验单编辑：在流程中编辑检验明细（新页面）。
• 流程引擎：Flowable（流程实例、任务、历史）。

---

2. 前端页面与路由

2.1 申请相关

• 列表：/qms/iqc/apply/list
  • 页面：yudao-ui/yudao-ui-admin-vue3/src/views/qms/ApplicationList.vue
• 表单：/qms/iqc/apply/new | /edit/:id | /view/:id
  • 页面：yudao-ui/yudao-ui-admin-vue3/src/views/qms/ApplicationForm.vue

2.2 任务与流程相关

• 任务列表：/qms/iqc/task/list
  • 页面：yudao-ui/yudao-ui-admin-vue3/src/views/qms/TaskList.vue
• 流程详情（审批详情页）：
  • 页面：yudao-ui/yudao-ui-admin-vue3/src/views/qms/iqc/task/ProcessDetailForm.vue
  • 当前只展示 申请信息 + 备注，并提供“打开编辑页面”按钮。

2.3 检验单编辑页（新页面）

• /qms/iqc/task/edit/:taskId
• /s5/iqc/iqc/task/edit/:taskId
• 页面：yudao-ui/yudao-ui-admin-vue3/src/views/qms/iqc/task/InspectBillEdit.vue

---

3. 关键接口清单

3.1 申请（IQC Apply）

• GET /qms/iqc-apply/page 申请列表
• GET /qms/iqc-apply/get?id=... 申请详情
• POST /qms/iqc-apply/create 新建
• PUT /qms/iqc-apply/update 更新
• DELETE /qms/iqc-apply/delete?id=... 删除

3.2 任务（IQC Task）

• GET /qms/iqc-task/page 任务列表
• GET /qms/iqc-task/get?id=... 任务详情
• POST /qms/iqc-task/start 开始检验（创建流程实例）

3.3 检验单编辑（Inspect Bill）

• GET /qms/iqc-task/inspect-bill/main?taskId=... 主表信息
• GET /qms/iqc-task/detail-list?taskId=... 明细列表
• POST /qms/iqc-task/inspect-bill/save 保存主表+明细

---

4. 数据表与字段映射

4.1 申请主表（qms_qcp_inspecapplyn）

• id：主键
• FBILLNO：申请单号（前端 id）
• FAPPLYUSER：申请人 ID
• FAPPLYTIME：申请时间
• FBILLTYPE：业务类型
• FCOMMENT：总体备注（申请列表显示）

4.2 申请子表 / 任务来源表（qms_qcp_insappnentry）

• glid：关联主表 id
• FSRCORDERNUM：物料编码（前端 materialCode）
• FSRCORDERTYPE：物料名称（前端 materialName）
• FLOTNUMBER：批次（前端 batch）
• FAPPLYQTY：数量（前端 quantity）
• FUNIT：单位（前端 unit）
• FINSPECTSTATUS：检验状态（待检验/检验中/检验完成）
• FSUPPLIER：供应商编码（前端 supplierCode）
• process_instance_id：流程实例
• flowstate：流程状态

4.3 检验单主表（qms_qcp_inspbill）

• hid：关联任务 ID（qms_qcp_insappnentry.id）
• FCOMMENT：临时存 JSON：{"A":"...","B":"...","C":"...","D":"..."}

4.4 检验单明细表（qms_qcp_inspbilllist）

• billid：主表 ID
• jyxm/bz/sx/xx：A/B/C/D 的临时字段映射

---

5. 字段映射表（前端 ↔ DB）

5.1 申请明细（ApplicationForm.detail）

前端字段	表字段	说明
materialCode	FSRCORDERNUM	物料编码
materialName	FSRCORDERTYPE	物料名称
specification	(暂无)	当前未映射
batch	FLOTNUMBER	批次
inspectStatus	FINSPECTSTATUS	检验状态
quantity	FAPPLYQTY	数量
unit	FUNIT	单位
supplierCode	FSUPPLIER	供应商编码

5.2 申请列表（ApplicationList）

• remark ← qms_qcp_inspecapplyn.FCOMMENT（总体备注）
• status：由子表汇总计算（见 6.1）

5.3 任务列表（TaskList）

• supplierCode ← qms_qcp_insappnentry.FSUPPLIER
• applicationId ← qms_qcp_inspecapplyn.FBILLNO
• status：由 FINSPECTSTATUS/FBILLSTATUS 映射

---

6. 流程联动（BPM）

6.1 流程 Key

• PROCESS_KEY = qms_iqc_task
• 定义在：yudao-module-qms/src/main/java/cn/iocoder/yudao/module/qms/service/iqc/IqcTaskServiceImpl.java

6.2 启动流程

• 入口：POST /qms/iqc-task/start
• 行为：
  • 创建流程实例
  • 回写 process_instance_id
  • 更新 flowstate = 审批中
  • 更新 FINSPECTSTATUS = 检验中

6.3 流程结束回写

• 通过：flowstate = 审批完成，FINSPECTSTATUS = 检验完成
• 取消：flowstate = 已取消，FINSPECTSTATUS = 待检验
• 驳回：flowstate = 已驳回，FINSPECTSTATUS = 检验中

---

7. 前端配置关键点（AI 容易踩坑）

1) 申请列表 vs 任务列表

• 申请列表显示 总体备注（FCOMMENT）
• 任务列表显示 供应商编码（FSUPPLIER）

2) 状态角标

• ApplicationForm.vue 已移除状态角标（不显示“待检验/检验中/检验完成”）。

3) 检验明细编辑入口

• 审批详情页（流程详情）不再内嵌明细表。
• 通过“打开编辑页面”进入 InspectBillEdit.vue。

4) 通过前强制保存

• ProcessInstanceOperationButton.vue 对 qms_iqc_task 做了保存拦截：
  • “通过”前会调用检验单保存接口
  • 保存失败会阻止通过

---

8. 常见问题与排查

• 列表字段不显示：检查 前端字段 key、后端 VO 字段名、Mapper SQL 字段别名 是否一致。
• 明细更新不生效：当前是“先删后插”，ID 会重新生成；确认 update 逻辑是否走到。
• 流程未发起：process_instance_id 为空时会提示“请先开始检验”。
• 申请时间格式：前端使用时间戳（value-format: 'x'），后端用 LocalDateTime 接收。

---

9. 关键代码位置索引

• 前端配置：yudao-ui/yudao-ui-admin-vue3/src/config/qmsModules.ts
• 申请表单：yudao-ui/yudao-ui-admin-vue3/src/views/qms/ApplicationForm.vue
• 任务列表：yudao-ui/yudao-ui-admin-vue3/src/views/qms/TaskList.vue
• 审批详情：yudao-ui/yudao-ui-admin-vue3/src/views/qms/iqc/task/ProcessDetailForm.vue

• 检验单编辑：yudao-ui/yudao-ui-admin-vue3/src/views/qms/iqc/task/InspectBillEdit.vue

• 申请 Mapper：yudao-module-qms/src/main/resources/mapper/iqc/IqcApplyMapper.xml

• 任务 Mapper：yudao-module-qms/src/main/resources/mapper/iqc/IqcTaskMapper.xml

• 任务 Service：yudao-module-qms/src/main/java/cn/iocoder/yudao/module/qms/service/iqc/IqcTaskServiceImpl.java

---

10. 建议的开发顺序（可复用）

1. 先确定 DB 字段映射（主/子表）
2. 后端 VO + Mapper SQL + Service
3. 前端 API 类型对齐
4. 列表字段 key 与后端字段别名一致
5. 流程 start/回写字段校验
6. 审批详情 + 编辑页联调