质量管理

本页是一篇完整方案指南:以 quality 插件(com.auraboot.quality,命名空间 qc)为例,从用户场景一路讲到开发实施和典型错误。它声明为 config 型,但带一个后端 jar(backend/build/libs/quality-plugin-1.0.0.jar)放置量化计算类逻辑——所以它是一个 hybrid 插件:16 个 model、64 条命令、34 个页面靠 DSL JSON 声明,SPC 控制限计算、不合格品自动建成本与 CAPA 等这类要算的活由 PF4J handler 承担。下面每个标识符你都能在插件里 grep 到、对运行实例调得通。

它依赖 com.auraboot.product-catalog、com.auraboot.inventory、com.auraboot.org-management,装它前这三个先装好,否则解析器会拒绝。

1. 用户场景

一家电子元器件制造商,来料、生产、出货三段都要管质量。日常:

• 采购到货 → 触发 IQC(来料检验) → 抽样判定 pass / fail / 让步接收 → 不合格转入隔离;
• 生产线上 PQC(过程检验) 采集测量数据,关键尺寸写入 SPC 控制图,超出 UCL/LCL 即报警;
• 成品入库前 FQC(成品检验) 终判;
• 任何环节出不合格 → 开 NCR(不合格品) → 决定处置(退货 / 返工 / 报废 / 让步)→ 执行 → 关闭;严重缺陷自动建 CAPA(纠正预防措施);
• 每个批次要能追溯到它的检验记录、缺陷、返工与处置历史。

检验员、质量工程师、生产、采购看到的视图和能做的操作各不相同;签字关闭不合格品的人,不能是当初开单的人。

📷 截图位 —— 不合格单 / CAPA 闭环页(待 host-first 起栈抓真实页面截图,见 backlog)

2. 需求痛点

• 检验结果断链:检验合格与否填在 Excel 里,下游(隔离、返工、报废)靠人盯着转单,漏转、错转频发。
• SPC 靠人算:控制限手工套公式,产线漂移后没人重算,超限点发现得晚。
• 不合格品无闭环:谁开的单、怎么处置、根因是什么、有没有验证关闭,事后查不到;签字闭环没有职责分离。
• 操作无授权无审计:改检验结论、改处置方式没有权限边界,也没有谁在什么时候改了什么的记录。

这些都不是「再加一张表」能解决的,而是受控状态变更的问题。

3. 常规解法 vs AuraBoot 的设计哲学

3.1 常规解法是怎样的

如果让一个团队从零做 QMS,通常是这条路:

1. 领域建模:画实体和关系——检验单、缺陷、不合格品、处置、CAPA、SPC 控制图、质量成本、批次追溯……
2. 建表:把实体翻译成一堆 CREATE TABLE,加外键、索引、状态字段。
3. 写 CRUD:每个实体一套 Repository / Service / Controller,增删改查全手写。
4. 把业务规则 hard-code 进 service:检验判定(pass/fail/让步)、不合格品状态流转(open→decided→executed→closed)、「处置为报废就自动建质量成本和 CAPA」、SPC 控制限的 UCL/LCL 套公式重算——全写死在 Java 里。
5. 各处补横切关注点:权限判断散落在每个 controller;「关闭 NCR 的人不能是开单人」这种职责分离要自己写;审计靠手动插日志;想把不合格联动到隔离/返工/复检,再搭一套触发器或 MQ。
6. 前端:每个页面手写表单、列表、检验录单、SPC 图、NCR/CAPA 处理台。
7. 想接 AI / 自动化:对不起,得再包一层 API、再定义一遍权限和风险边界。

结果就是现实里那套断链:检验合格与否填在 Excel,不合格靠邮件追着转单,CAPA 闭环靠人手工跟,SPC 控制限没人重算、超限点发现得晚,质量数据又和生产、库存各管各的不通。业务规则散落在代码各处,改一条判定规则要同时动 service + controller + 前端;并发、审计、事件、AI 入口每一样都得自己扛。三个月起步,而且越改越脆。

3.2 AuraBoot 的设计哲学

AuraBoot 把这件事反过来:业务的「是什么」用声明描述,「怎么执行」由运行时统一兜底。三条核心理念:

• 元数据驱动:model / field / command / page / permission 都是声明(DSL JSON),不是手写代码。检验单、不合格品、CAPA、SPC 图都是可配置 model,平台据此自动建表、生成接口、渲染页面——上面第 2、3、6 步基本消失。
• 单一命令管道:所有写入都是一条命令,走同一条 命令管道。鉴权、校验、事务、审计这些横切关注点由管道统一处理,不写进每个业务里——你声明 qc:handle_nonconformance 时只关心「open→decided + 落处置 + 派生质量成本/CAPA」,鉴权和留痕是白送的;「关闭 NCR 的人不能是开单人」用五层权限的 ABAC 表达,不再手写 if(第 4、5 步从「自己扛」变成「平台默认」)。
• 命令即契约:同一条命令同时服务 UI 按钮、自动化规则、BPM 节点、AI agent。带 agent_hint + cmd_risk_level 的命令(如 qc:create_capa,标 L2、需人工确认)就是为 agent 安全调用而声明的;AI 原生不是事后包 API,而是天生的(第 7 步免了)。

3.3 同一个功能,两种活法

于是普通做法里那些「自己扛」的事,在 AuraBoot 变成平台契约的默认能力。每一格的 AuraBoot 列都是下面能 grep 到的真实命令/模型,不是宣传话术:

一句话:手写要三个月、还得自己扛 SPC 重算和 CAPA 闭环;打包 ERP 快但改不动判定规则;AuraBoot 用声明式配置就拿到一套 production 级的质量内核,要算的活交给 hybrid handler,而且每个动作都能被 AI 安全驱动、被你自由扩展。 下面看它具体怎么搭。

4. 功能设计

4.1 数据模型(16 个)

NCR 的处置类型 qc_nc_type 取 return / rework / scrap / concession(退货 / 返工 / 报废 / 让步),来源 qc_nc_source_type 取 iqc / fqc / pqc。

4.2 命令与状态机

命令命名 qc:<动词>_<名词>,共 64 条。代表性命令:

每条命令都是一段声明。例如 qc:handle_nonconformance(config/commands/qc_handle_nonconformance.json)的真实定义:

{
  "code": "qc:handle_nonconformance",
  "displayName:zh-CN": "处置不合格品",
  "displayName:en": "Handle Nonconformance",
  "description": "Handle nonconformance: decide disposition (RETURN/REWORK/SCRAP/CONCESSION), auto-create quality cost and CAPA",
  "type": "state_transition",
  "modelCode": "qc_ncr",
  "stateField": "qc_nc_status",
  "fromStates": ["open"],
  "toState": "decided",
  "handler": "qc:handle_nonconformance",
  "permissions": ["qc.quality.manage"],
  "extension": {
    "confirmMessage:zh-CN": "确认处置此不合格品？",
    "confirmMessage:en": "Handle this nonconformance?"
  }
}

读出来的设计信息:这是一条 state_transition(open → decided),要求 qc.quality.manage 权限,操作前弹确认框。handler 字段指向后端 jar 里 HandleNonconformanceHandler——它在状态迁移之外,按 payload 里的处置类型(return/rework/scrap/concession)落处置字段,并对 scrap/return/rework 自动建一条质量成本,对 scrap 或数量 > 100 自动建一条 CAPA。这正是 hybrid 插件的价值:声明负责状态机和鉴权,handler 负责「要算 / 要派生记录」的那部分。

4.3 权限与角色

10 个权限码(<模块>.<资源>.<动作>):

qc.quality.manage     qc.quality.read       qc.quality.spc
qc.quality.capa       qc.quality.cost       qc.quality.rework
qc.quality.rework.read                      qc.dashboard.quality
qc.test.manage        qc.test.read

插件自带 1 个角色 qc_quality_engineer(质量工程师),持有上面全部 10 个权限码。检验员 / 生产 / 采购等更细的角色按你厂区的职责切分另建——平台的五层权限模型(RBAC / ReBAC / 组织域 / ABAC / 字段级)能表达「检验员不能关闭自己开的 NCR」「只能处置本厂区的不合格品」这类规则,见 权限。

4.4 页面

34 个页面:各 model 的 list / detail、检验录单、SPC 图、NCR / CAPA 处理台、返工作业、批次追溯等;另有 1 个 dashboard(config/dashboards/qc_quality_dashboard.json)。

5. 具体开发与实施

先掌握基础。本插件的声明部分(model / 命令 / 权限 / 页面)全靠平台的几个核心契约,要算的部分才落到后端 handler。动手前请先读:Model 与 Field · Command · 命令管道 · Permission · 插件清单 · 纯配置 Plugin · Page Designer。

落地一个像 quality 这样的 hybrid 插件,步骤是:

1. 定义 model 与字段 —— config/models.json + config/fields/,字段类型用平台 dataType,枚举(检验结论、NCR 状态、SPC 图型等)在 config/dicts.json 集中声明。详见 Model 与 Field。
2. 声明命令 —— 每条放一个 config/commands/<code>.json。纯状态流转用 type: state_transition + fromStates/toState;要派生计算的(SPC 控制限、质量成本)再加 handler 字段并在后端 jar 里实现对应 CommandHandlerExtension。详见 Command。
3. 配 model-field binding —— config/bindings/<model>.json(每个 model 一个数组,列字段顺序、required、visible、searchable),并在 resourceDirs.modelFieldBindings 注册(见「典型错误」)。
4. 设计页面 —— config/pages/,列表/表单/详情/处理台用 Page Designer 出 DSL。
5. 权限、角色、字典、菜单、dashboard —— config/permissions.json / roles.json / dicts.json / menus.json / dashboards/。
6. 构建后端 jar —— backend/ 下 ./gradlew build 产出 quality-plugin-1.0.0.jar,plugin.json 的 backend.jarPath / entryClass 指向它;PF4J 真加载这个 jar 才能注册 handler。
7. 打包导入 —— 用 aura CLI 的 import-directory-sync(参数是目录 path)或平台导入接口;校验返回 success:true 才算导入成功。详见 插件清单。

6. 常见配置

• 来料检验联动:IQC 不合格(qc:complete_iqc 改判 fail)时,用自动化规则发 qc:create_nonconformance 自动开 NCR,qc_nc_source_type 标 iqc、qc_nc_source_id 指回检验单。
• SPC 超限报警:qc:record_spc_data 写点后,qc:calculate_spc_limits 重算 UCL/LCL;图型 qc_spc_chart_type 选 x_bar / r_chart / p_chart / c_chart,超限点配规则发通知。
• 不合格品处置:qc:handle_nonconformance 的 payload 给 qc_nc_disposition(return/rework/scrap/concession),handler 自动建质量成本,scrap 或数量 > 100 时自动建 CAPA;再 qc:close_nonconformance(executed → closed)收口。
• 返工闭环:qc:create_rework_order → qc:start_rework → qc:complete_rework,状态走 qc_rework_status;返工后 qc:submit_retest / qc:pass_retest / qc:fail_retest 复检。

7. 典型错误

• 命令码用点号:写成 qc.ncr.handle 或 qms.ncr.open 跑不通——真实是冒号 + 动词_名词,命名空间是 qc 不是 qms:qc:handle_nonconformance。
• 绕过命令直接改检验/NCR 表:直接 UPDATE qc_ncr 会跳过状态机、handler 的派生逻辑(自动建质量成本 / CAPA)和审计。一切质量状态变更都走命令。
• bindingRules 写进 commands.json 内联:不会被导入;必须独立 config/bindings/<model>.json 并在 resourceDirs 注册,否则报 [S-EXT-HANDLER] references unregistered handler。详见 纯配置 Plugin。
• 命令执行 payload 结构:字段放在 { "payload": { ... }, "operationType": ... },目标记录用 targetRecordId(不是 recordId)——放错位会出现「执行成功却字段为空」的迷惑性报错。
• 把 hybrid 当纯 config 导:quality 声明 pluginType: config 但带 backend jar。只导 config、不让 PF4J 加载 jar,带 handler 的命令(如 qc:handle_nonconformance、qc:calculate_spc_limits)会因引用了未注册的 handler 报 [S-EXT-HANDLER]。装它前还要先装好它依赖的 product-catalog / inventory / org-management。

下一步

• 系统总览 —— 插件、命令与运行时如何拼到一起
• 命令管道 —— 上面每条命令都走的执行契约
• 权限 —— 上面角色背后的五层模型
• 插件清单 —— 方案包如何声明依赖与后端 jar