# 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. 审批详情 + 编辑页联调