12 KiB
质检任务负责人与「我的质检任务」— 设计文档
日期: 2026-06-12
状态: 已实现(2026-06-12)
范围: web-admin + backend(质检工单三 Tab、配置/调整检测、我的质检任务)
1. 背景
质检工单页(入库 / 出库 / 临时三个 Tab)通过「配置检测」「调整检测」生成质检任务,但任务无负责人指派。质检专员无法在独立入口查看「分给自己的任务」并填写结果。
本变更引入任务负责人(单人或多人的集合),并在「质检管理」下新增我的质检任务菜单页。
2. 已确认的产品决策
| 问题 | 决策 |
|---|---|
| 多人负责时,完成语义? | A — 任一负责人可独立完成(开始、填写结果、完成);completed_by 记录实际操作人 |
| 工单页 vs 我的任务页操作权限? | A — 管理覆盖:我的任务页仅 assignee 可操作;工单展开行持有 biz:qcTask:list 可督办全部任务 |
| 负责人数据存储方式? | 关联表 biz_qc_task_assignee(非逗号分隔字段) |
| 负责人指派粒度? | 每个检测项目(对应一条 biz_qc_task)独立指派 |
| 配置时负责人是否必填? | 是 — 每个已勾选的 lab/third 项目至少 1 人 |
3. 现状摘要
| 项 | 现状 |
|---|---|
| 配置 API | POST /web/admin/qc-work-orders/{id}/configure |
| 任务生成 | 每个 lab/third 明细行 → create_task_for_line;保留项不重建 |
| 任务操作 | QcWorkOrderTaskSubList.vue:开始 / 填写结果 / 查看 / 删除 |
| 我的视角参考 | my-qc-material-usage(mine-only + 独立 menuCode) |
| 工作流参考 | wf_task.assignee_user_id + task-pending 过滤模式 |
当前缺失:biz_qc_task 无 assignee;list_tasks 无「我的任务」过滤。
4. 功能清单
4.1 配置检测 / 调整检测弹窗
- 在
qc-work-order/index.vue配置弹窗中,每个已勾选的实验室 / 第三方检测项目旁增加负责人多选(el-select multiple filterable)。 - 用户选项:本租户有效
sys_user(展示nickName(userNo),与流程设计器一致)。 - 首次配置:每个勾选项目必选 ≥1 负责人,否则前端 + 后端校验拒绝。
- 调整检测:
- 回显已配置项目的负责人;
- 新增项目:必选负责人;
- 保留项目:可更新负责人;
- 移除项目:连带软删任务及 assignee(沿用现有
_sync_*逻辑); - 已完成任务(
ywc):若检测项目仍保留,允许改负责人(仅影响「我的任务」可见性,不改completed_by);不建议移除已完成项对应的检测项目(现有逻辑已限制删除进行中/已完成任务的场景,保持后端既有校验)。
- 提交 body 扩展见 §5.2。
4.2 工单展开行任务卡片
QcWorkOrderTaskSubList.vue(或抽取的共用组件)任务卡片 meta 区展示负责人(el-tag或 muted 文本,多人用顿号连接)。- 操作权限:不收紧 — 持有
biz:qcTask:list的用户仍可按现有状态机操作(管理督办)。
4.3 我的质检任务(新页面)
- 路由:
/#/quality-manage/my-qc-task - 组件:
web-admin/src/views/quality-inspection/my-qc-task/index.vue - 菜单:
质检管理→我的质检任务,menuCode:biz:myQcTask:list - UI 模式:P02(状态驱动操作列)+ P21 任务卡片;列表结构参考
order/index.vue,任务卡片与结果弹窗复用QcWorkOrderTaskSubList抽取逻辑。
筛选区(filter-block):
| 字段 | 类型 |
|---|---|
| 关键词 | 任务编号 / 项目名称 / 工单号 / 样本编码 |
| 任务状态 | dzx / jxz / ywc |
| 任务类型 | sysz / dsfjc |
| 工单类型 | inbound / outbound / temporary |
列表列 / 卡片信息:
- 任务编号、检测项目名称、任务类型 Tag、任务状态 Tag、结论 Tag(若有)
- 关联工单号、样本编码(若有)、工单类型
- 负责人(当前用户高亮可选)
- 操作:开始 / 填写结果 / 查看(规则同
QcWorkOrderTaskSubList)
查看详情:
- 任务:
SystemViewDialog或现有任务查看逻辑 - 关联工单:入库/临时 → 工单详情;出库 →
OutboundQcViewDialog
操作权限(严格):
- 仅当
current_user_id ∈ assignee_user_ids时展示「开始」「填写结果」 - 非 assignee 或已完成:主按钮为「查看」
- 后端写接口同步校验 assignee(见 §6)
4.4 菜单与权限注册
三处对齐(参照 2026-06-11-my-qc-material-usage-menu.sql):
web-admin/src/router/modules/sqxp.tsbackend/app/api/menu.pydocs/sql/migrations/2026-06-12-my-qc-task-menu.sql+docs/sql/zkxw.sql
| 菜单 | path | perms | order_num(建议) |
|---|---|---|---|
| 我的质检任务 | my-qc-task |
biz:myQcTask:list |
5(在「我的物料领用记录」之后) |
角色授权:默认给质检相关角色;超管租户管理员在菜单管理中分配。
5. 数据模型
5.1 新表 biz_qc_task_assignee
CREATE TABLE `biz_qc_task_assignee` (
`id` varchar(64) NOT NULL COMMENT '主键',
`task_id` varchar(64) NOT NULL COMMENT '质检任务ID',
`user_id` varchar(64) NOT NULL COMMENT '负责人用户ID',
`tenant_no` varchar(64) NOT NULL COMMENT '租户编号',
`order_num` int DEFAULT 0 COMMENT '展示顺序',
`remark` varchar(512) DEFAULT NULL COMMENT '备注',
`create_by` varchar(64) DEFAULT NULL,
`create_dept_id` varchar(64) DEFAULT NULL,
`create_time` datetime DEFAULT NULL,
`update_by` varchar(64) DEFAULT NULL,
`update_time` datetime DEFAULT NULL,
`del_flag` tinyint DEFAULT 0 COMMENT '删除标志',
PRIMARY KEY (`id`),
KEY `idx_qc_task_assignee_task` (`task_id`, `del_flag`),
KEY `idx_qc_task_assignee_user` (`user_id`, `tenant_no`, `del_flag`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='质检任务负责人';
唯一性在应用层保证:同一
task_id+user_id未删除记录不重复插入。
5.2 配置请求体扩展
WorkOrderConfigureBody 增加:
lab_item_assignees: Dict[str, List[str]] = Field(default_factory=dict, alias="labItemAssignees")
third_party_item_assignees: Dict[str, List[str]] = Field(default_factory=dict, alias="thirdPartyItemAssignees")
- Key:主数据项目 ID(
lab_test_item_id/third_party_item_id) - Value:用户 ID 数组(≥1)
- 校验:
lab_item_ids中每个 id 必须在lab_item_assignees中有非空列表;third 同理
5.3 任务响应字段扩展
_task_to_dict / _task_row_to_dict 增加:
| 字段 | 类型 | 说明 |
|---|---|---|
assigneeUserIds |
string[] |
负责人 ID 列表 |
assigneeUserNames |
string |
负责人姓名,顿号分隔 |
5.4 历史数据
- 已存在、配置时未指派负责人的任务:无 assignee 行。
- 不出现在「我的质检任务」列表。
- 工单展开行仍可通过
biz:qcTask:list操作(管理覆盖)。 - 不做批量回填脚本(v1);若需补录,通过「调整检测」重新指定负责人。
6. API 设计
6.1 扩展 configure
POST /web/admin/qc-work-orders/{work_order_id}/configure
- 权限:
biz:qcWorkOrder:list(不变) - 在
_sync_work_order_lab_items/_sync_work_order_third_party_items任务创建或保留后,调用_sync_task_assignees(task_id, user_ids)。 - 用户校验:所有
user_id须属于当前tenant_no且用户有效。
6.2 我的任务列表(新)
GET /web/admin/qc-tasks/mine
- 权限:
biz:myQcTask:list - Query:
page,pageSize,keyword,taskType,taskStatus,qcBizType(工单类型) - 过滤:
JOIN biz_qc_task_assignee ON task_id AND user_id = 当前用户 AND del_flag=0 - 排序:
create_time DESC(任务) - 响应:与
GET /qc-tasks列表项结构一致,附带工单摘要字段(workOrderNo,workOrderType,qcBizType,sampleCode)
6.3 写操作鉴权(我的任务入口)
对以下端点增加 可选严格模式 参数或根据请求来源/menuCode 区分;推荐实现:新增内部函数 _require_task_assignee_or_qc_admin(task, user, strict=False):
| 端点 | 我的任务页调用 | 工单页调用 |
|---|---|---|
POST /qc-tasks/{id}/start |
strict=True:须 assignee |
strict=False:仅需 biz:qcTask:list |
POST /qc-tasks/{id}/complete-with-result |
同上 | 同上 |
PUT /qc-tasks/{id}/attachments |
同上 | 同上 |
实现方式(推荐):请求头或 query operateScope=mine|manage:
mine:biz:myQcTask:list+ assignee 校验manage(默认):biz:qcTask:list,不校验 assignee
前端:
my-qc-task所有写请求带operateScope=mineQcWorkOrderTaskSubList不带或operateScope=manage
6.4 既有列表 API
GET /web/admin/qc-tasks:不变;可选后续增加 assigneeUserId 筛选(v1 不必须)。
7. 前端实现要点
7.1 组件抽取(建议)
从 QcWorkOrderTaskSubList.vue 抽取:
| 组件 | 职责 |
|---|---|
QcTaskCardList.vue |
任务卡片列表 + 操作按钮显隐 |
QcTaskResultDialog.vue |
填写检测结果弹窗(参数 / 物料 / 结论) |
Props:
tasks: QcTask[]operateScope: 'mine' | 'manage'loading,onRefresh
避免 1500+ 行逻辑双份维护。
7.2 配置弹窗 UI
- 实验室项目:checkbox 与 assignee
el-select同一行或下一行缩进 - 第三方项目:按公司分组内同样结构
- 弹窗
width保持 900px 或略增至 960px 以容纳选人控件 - 校验失败:
ElMessageBox.alert+scroll-to-error(与规范一致)
7.3 状态 Tag
沿用 status-tag-registry.ts 既有 qcTaskStatus、qcTaskType、qcTaskConclusion 映射。
8. 后端实现要点
8.1 CRUD 新增
backend/app/crud/qc_task_assignee.py(或合入 qc_task.py):
sync_assignees_for_task(db, task_id, user_ids, tenant_no, user_id)soft_delete_assignees_by_task_ids(db, task_ids, tenant_no)list_assignees_by_task_ids(db, task_ids) -> Dict[task_id, List[user]]is_user_assignee(db, task_id, user_id) -> bool
8.2 configure 改造
qc_work_order.py → _sync_work_order_lab_items / _sync_work_order_third_party_items:
- 创建/保留任务后,从 body 的 assignees map 取对应 item id 的 user_ids 并 sync。
- 保留项:每次 configure 全量替换该任务 assignee 列表(软删旧 + 插新)。
8.3 字段一致性
_row_to_dict(任务)须含assigneeUserIds(只读)- Create/Update schema:configure body 含
labItemAssignees/thirdPartyItemAssignees - 运行
python scripts/check_field_consistency.py
9. 测试要点
| 场景 | 预期 |
|---|---|
| 配置检测,每项选 1 人 | 生成任务 + assignee;我的任务可见 |
| 配置检测,某项未选人 | 400 校验错误 |
| 调整检测改负责人 | assignee 更新;新负责人可见,旧负责人不可见(未完成时) |
| 调整检测新增项目 | 新任务 + 新 assignee |
| 调整检测移除项目 | 任务与 assignee 软删 |
| 我的任务:assignee 开始/填结果 | 成功 |
| 我的任务:非 assignee 写操作 | 403 |
| 工单展开行:非 assignee 有 qcTask:list | 仍可操作 |
| 多人 assignee,一人完成 | 任务 ywc;他人列表变已完成 |
| 历史无 assignee 任务 | 不出现在我的任务;工单页可操作 |
10. 改动文件清单(预估)
| 层级 | 文件 |
|---|---|
| SQL | docs/sql/migrations/2026-06-12-qc-task-assignee.sql, 2026-06-12-my-qc-task-menu.sql, docs/sql/zkxw.sql |
| Backend | models.py, qc_task.py, qc_work_order.py, qc.py, menu.py |
| Frontend | sqxp.ts, qc-work-order/index.vue, my-qc-task/index.vue, 抽取组件, qc-task.ts, qc-work-order.ts, api.d.ts |
| 图谱 | ./scripts/update-graph.sh backend frontend |
11. 不在 v1 范围
- 消息通知(指派时短信/站内信)
- 负责人按角色/部门自动解析
- 任务转派独立 API(通过调整检测改人即可)
- 小程序端质检任务
12. OpenSpec 跟进(实现阶段)
在 openspec/changes/ 或归档后 openspec/specs/ 补充:
api-conventions:质检任务 assignee 与operateScope鉴权ui-conventions:配置检测负责人选择、我的质检任务参考页登记
请评审本文档。 确认无修改后,进入 writing-plans 生成实现任务分解。