# IQC 来料检验任务流程接入工作流开发说明（参照 oa_leave）

> 目标：参照请假流程（`oa_leave`）的实现方式，将 IQC 来料检验任务接入工作流，实现任务与流程实例关联、流程状态落库、发起/详情/列表页面对齐，以及流程结束结果监听与业务状态回写。

---

## 0. 流程节点（已确认）
- 来料检验
- 领导审批
- SQE 处理

---

## 1. 流程实例关联字段设计

### 1.1 业务表字段（已确认）
任务数据当前来自子表：`qms_qcp_insappnentry`（主表：`qms_qcp_inspecapplyn`）。

任务子表使用字段：
- `process_instance_id`：流程实例 ID（用于与工作流关联）
- `flowstate`：流程状态（未发起 / 审批中 / 审批完成 / 已驳回 / 已取消）

> 字段名称已确认使用 `process_instance_id` / `flowstate`。

### 1.2 关联关系
`qms_qcp_insappnentry.process_instance_id` 对应流程引擎历史流程实例表：

- 表：`ACT_HI_PROCINST`
- 字段：`PROC_INST_ID_`

即：
- `qms_qcp_insappnentry.process_instance_id` ↔ `ACT_HI_PROCINST.PROC_INST_ID_`

---

## 2. 流程状态字段与回调更新策略

### 2.1 状态字段
建议使用：
- `flowstate`：流程状态
- `FINSPECTSTATUS`：检验状态（业务状态，列表展示用）

示例状态：
- `flowstate`：未发起 / 审批中 / 审批完成 / 已驳回 / 已取消
- `FINSPECTSTATUS`：待检验 / 检验中 / 检验完成

### 2.2 状态更新方式
通过 Listener 监听流程回调并更新 `flowstate`。  
业务状态 `FINSPECTSTATUS` 可在流程节点触发或流程结束时统一更新。

#### 2.2.1 流程提交后：更新为“审批中”
```sql
update qms_qcp_insappnentry
set flowstate = '审批中'
where id = '{<TaskEntryId>}';
```

#### 2.2.2 流程通过后：更新为“审批完成”
```sql
update qms_qcp_insappnentry
set flowstate = '审批完成',
    FINSPECTSTATUS = '检验完成'
where id = '{<TaskEntryId>}';
```

#### 2.2.3 流程取消：回退为“待检验”
```sql
update qms_qcp_insappnentry
set flowstate = '已取消',
    FINSPECTSTATUS = '待检验'
where id = '{<TaskEntryId>}';
```

#### 2.2.4 流程驳回：更新为“检验中”
```sql
update qms_qcp_insappnentry
set flowstate = '已驳回',
    FINSPECTSTATUS = '检验中'
where id = '{<TaskEntryId>}';
```

---

## 3. 后端业务逻辑开发（参照 oa_leave）

### 3.1 参考类
请假流程后端参考：
- `BpmOALeaveController`
- `BpmOALeaveServiceImpl`

IQC 任务流程需实现类似结构的 Controller + Service，并按“业务表 + 流程”方式接入。

### 3.2 流程模型编号（PROCESS_KEY）
请假：`oa_leave`  
IQC 任务：`qms_iqc_task`

> 该 Key 必须与流程模型实际配置一致。

### 3.3 创建流程实例
使用 `BpmProcessInstanceApi` 创建流程实例：
- `#createProcessInstance(...)`

发起 IQC 任务流程时建议完成：
- 创建流程实例
- 回写 `qms_qcp_insappnentry.process_instance_id`
- 更新 `flowstate = '审批中'`

---

## 4. 前端业务逻辑开发（参照 oa_leave）

### 4.1 参考页面
请假模块前端参考：
- 发起：`leave/create.vue`
- 详情：`leave/detail.vue`
- 列表：`leave/index.vue`

### 4.2 IQC 任务页面对齐建议
可沿用现有 QMS 任务页面逻辑：
- 列表：`TaskList.vue`（已存在）
- 表单：`TaskForm.vue`（已存在）

接入流程后建议实现：
- 列表 “开始检验 / 继续检验” → 发起流程（create）
- 详情查看 → 进入流程详情（detail）

---

## 5. 路由配置（参照 remaining.ts 的请假流程配置）

为 IQC 任务流程新增隐藏路由（create/detail），用于：
- 从任务列表发起流程
- 在流程流转/审批中查看业务详情

示例（路径可按实际模块调整）：
```ts
{
  path: '/qms',
  component: Layout,
  name: 'qms',
  meta: { hidden: true },
  children: [
    {
      path: 'iqc/task/create',
      component: () => import('@/views/qms/TaskForm.vue'),
      name: 'IqcTaskCreate',
      meta: {
        noCache: true,
        hidden: true,
        canTo: true,
        title: '发起 IQC 任务',
        activeMenu: '/qms/iqc/task/list'
      }
    },
    {
      path: 'iqc/task/detail/:id',
      component: () => import('@/views/qms/TaskForm.vue'),
      name: 'IqcTaskDetail',
      meta: {
        noCache: true,
        hidden: true,
        canTo: true,
        title: '查看 IQC 任务',
        activeMenu: '/qms/iqc/task/list'
      }
    }
  ]
}
```

---

## 6. 流程结束回调监听与业务状态更新（必须）

### 6.1 监听器机制
审批结束时（通过 / 不通过 / 取消），后端必须监听最终结果并更新业务表状态。

请假流程实现参考：
- `BpmOALeaveStatusListener`
（继承 `BpmProcessInstanceStatusEventListener`）

### 6.2 IQC 任务监听器要求
需新增监听器（示例命名：`BpmIqcTaskStatusListener`），继承：
- `BpmProcessInstanceStatusEventListener`

监听流程结束结果并更新：
- `qms_qcp_insappnentry.flowstate`
- `qms_qcp_insappnentry.FINSPECTSTATUS`（通过=检验完成；取消=待检验；驳回=检验中）

---

## 7. 交付清单（Checklist）

### 7.1 后端
- [ ] 定义 `PROCESS_KEY = "qms_iqc_task"`
- [ ] Controller（参照 `BpmOALeaveController`）
- [ ] ServiceImpl（参照 `BpmOALeaveServiceImpl`）
- [ ] 调用 `BpmProcessInstanceApi#createProcessInstance(...)` 创建流程实例
- [ ] 回写 `process_instance_id`
- [ ] 提交后/结束后 `flowstate` 更新逻辑（建议走 Listener）
- [ ] 新增流程结束监听器（继承 `BpmProcessInstanceStatusEventListener`）

### 7.2 前端
- [ ] 任务列表 “开始检验/继续检验” 触发流程发起
- [ ] create 页面（复用 `TaskForm.vue` 或新建）
- [ ] detail 页面（复用 `TaskForm.vue` 或新建）
- [ ] `router/modules/remaining.ts` 增加 IQC 任务 create/detail 路由