[根目录](../CLAUDE.md) > **nflg-qms-admin**

# nflg-qms-admin - QMS 质量管理后台

## 模块职责

QMS（质量管理系统）管理后台服务，是一个功能丰富的独立业务服务，覆盖：
- **来料检验** -- 来料检验任务管理、AQL 抽样规则、不合格处理
- **检验标准** -- 检验项目、检验标准、检验标准项目管理
- **抽样计划** -- 抽样方案管理
- **质量通知** -- 质量通知单管理
- **问题工单** -- 问题工单(Issue Ticket)、工单流程、整改措施、待办事项
- **COA 证书** -- COA 审核任务管理
- **PDI 整车检测** -- 整车检测任务记录、检测规则、检测结果、交付项、组件、状态项
- **免检管理** -- 免检物料、免检类别
- **质检物料** -- 质检物料分类、质检物料管理
- **质量检验员** -- 质量检验员管理
- **供应商 SQE** -- 供应商 SQE 管理
- **标准缺陷** -- 标准缺陷管理
- **质量报表** -- 质量报表
- **文件管理** -- QMS 文件管理（文件分类/文件/版本/成员/OnlyOffice 集成）
- **广告管理** -- 广告管理
- **PDF 尺寸提取** -- 集成 nflg-qms-pdf-extract，从工程图纸提取尺寸数据
- **外部接口** -- 为 WMS 等系统提供来料检验回调、PDI 任务记录、物料查询等外部接口
- **消息通知** -- 邮件/RTX/待办事项三种消息渠道

## 入口与启动

| 项 | 值 |
|----|-----|
| 入口类 | `com.nflg.qms.admin.QmsApplication` |
| 端口 | 8105 |
| 服务名 | qms-local |
| ComponentScan | `com.nflg.qms.admin`, `com.nflg.wms.starter`, `com.nflg.wms.repository` |

## 关键依赖

- nflg-wms-common
- nflg-wms-starter
- **nflg-qms-pdf-extract** (PDF 数据提取)
- Spring Boot Web / AOP / Validation / Mail / Thymeleaf / LDAP / MongoDB
- ZXing (二维码)
- EasyExcel (Excel 处理)
- iText7 / Flying Saucer PDF (PDF 生成)
- PowerJob Client (任务调度)
- Redisson (分布式锁)
- OpenTelemetry (链路追踪)
- Hypersistence TSID (ID 生成)
- **MinIO** 8.5.17 (对象存储)
- **AWS S3 SDK** 2.39.5 (对象存储)
- **JJWT** 0.12.6 (OnlyOffice JWT 签名)
- Apache Commons IO / Lang3
- TinyPinyin (拼音转换)
- Spring Retry

## 对外接口 (Controller)

### 业务 Controller (34 个)

| Controller | 路由前缀 | 说明 |
|-----------|---------|------|
| `QmsIncomingInspectionTaskController` | `/incoming-inspection-task` | 来料检验任务 |
| `QmsIncomingInspectionTaskAqlRuleController` | `/incoming-inspection-task-aql-rule` | 来料检验 AQL 抽样规则 |
| `QmsIncomingInspectionTaskNonconformanceController` | `/incoming-inspection-task-nonconformance` | 来料检验不合格处理 |
| `QmsInspectionItemController` | `/inspectionItem` | 检验项目管理 |
| `QmsInspectionStandardController` | `/inspection-standard` | 检验标准管理 |
| `QmsInspectionStandardItemController` | `/inspection-standard-item` | 检验标准项目 |
| `QmsSamplingPlanController` | `/sampling-plan` | 抽样计划 |
| `QualityNotificationController` | `/quality-notification` | 质量通知 |
| `QmsIssueTicketController` | `/issueTicket` | 问题工单 |
| `QmsIssueTicketProcessController` | `/issueTicketProcess` | 工单流程 |
| `QmsIssueTicketProcessMeasureController` | `/issueTicketProcessMeasure` | 工单整改措施 |
| `QmsIssueTicketTodoController` | `/ticket-todo-item` | 工单待办事项 |
| `QmsCoaTaskController` | `/coaTask` | COA 证书任务 |
| `QmsCoaReviewController` | `/coaReview` | COA 审核 |
| `QmsPdiTaskRecordController` | `/pdiTaskRecord` | PDI 检测任务记录 |
| `QmsPdiComponentController` | `/pdiComponent` | PDI 组件 |
| `QmsPdiDeliveryItemController` | `/pdiDeliveryItem` | PDI 交付项 |
| `QmsPdiDetectionRulesController` | `/pdiDetectionRules` | PDI 检测规则 |
| `QmsPdiInspectionResultsController` | `/pdiInspectionResults` | PDI 检测结果 |
| `QmsPdiStatusItemController` | `/pdiStatusItem` | PDI 状态项 |
| `QmsExemptCategoryController` | `/exemptCategory` | 免检类别 |
| `QmsExemptMaterialController` | `/exemptMaterial` | 免检物料 |
| `QmsQcMaterialCategoryController` | `/qcMaterialCategory` | 质检物料分类 |
| `QmsQcMaterialController` | `/qcMaterial` | 质检物料 |
| `QmsQualityInspectorController` | `/qualityInspector` | 质量检验员 |
| `QmsSupplierSqeController` | `/supplierSqe` | 供应商 SQE |
| `QmsStandardDefectController` | `/standardDefect` | 标准缺陷 |
| `QmsReportController` | `/report` | 质量报表 |
| `QmsFileCategoryController` | `/fileCategory` | 文件分类 |
| `QmsFileController` | `/file` | 文件管理 |
| `QmsFileMemberController` | `/fileMember` | 文件成员 |
| `FileUpLoadController` | `/fileUpload` | 文件上传 |
| `AdvertisementController` | `/ad` | 广告管理 |
| `TestController` | `/test` | 测试接口 |

### 外部接口 Controller (3 个)

| Controller | 路由前缀 | 说明 |
|-----------|---------|------|
| `ExternalIncomingInspectionTaskController` | `/external/incoming-inspection-task` | 外部来料检验任务接口（供 WMS 回调） |
| `ExternalPdiTaskRecordController` | `/external/pdi-task-record` | 外部 PDI 任务记录接口 |
| `MaterialController` | `/external/material` | 外部物料查询接口 |

## 关键业务 Service

| Service | 说明 |
|---------|------|
| `IncomingInspectionTaskControllerService` | 来料检验任务业务逻辑 |
| `QmsInspectionStandardControllerService` | 检验标准业务逻辑 |
| `QmsInspectionStandardItemControllerService` | 检验标准项目业务逻辑 |
| `QmsSamplingPlanControllerService` | 抽样计划业务逻辑 |
| `QualityNotificationControllerService` | 质量通知业务逻辑 |
| `QmsIssueTicketControllerService` | 问题工单业务逻辑 |
| `QmsIssueTicketProcessControllerService` | 工单流程业务逻辑 |
| `QmsIssueTicketProcessMeasureControllerService` | 工单整改措施业务逻辑 |
| `QmsIssueTicketTodoControllerService` | 工单待办事项业务逻辑 |
| `QmsPdiTaskRecordControllerService` | PDI 任务记录业务逻辑 |
| `QmsPdiComponentControllerService` | PDI 组件业务逻辑 |
| `QmsPdiDeliveryItemControllerService` | PDI 交付项业务逻辑 |
| `QmsPdiDetectionRulesControllerService` | PDI 检测规则业务逻辑 |
| `QmsPdiInspectionResultsControllerService` | PDI 检测结果业务逻辑 |
| `QmsPdiStatusItemControllerService` | PDI 状态项业务逻辑 |
| `QmsFileCategoryControllerService` | 文件分类业务逻辑 |
| `QmsFileControllerService` | 文件管理业务逻辑 |
| `QmsFileMemberControllerService` | 文件成员业务逻辑 |
| `FileControllerService` | 文件上传业务逻辑 |
| `QmsQcMaterialControllerService` | 质检物料业务逻辑 |
| `QmsStandardDefectControllerService` | 标准缺陷业务逻辑 |
| `QmsReportControllerService` | 质量报表业务逻辑 |
| `ExternalPdiTaskRecordControllerService` | 外部 PDI 任务业务逻辑 |
| `WmsApiService` | WMS 系统 API 调用服务 |
| `WmsIncomingInspectionTaskCallbackService` | WMS 来料检验回调服务 |
| `BasdeSerialNumberControllerService` | 流水号生成 |
| `ISendMessageService` | 消息发送接口 |
| `EmailMessageImpl` | 邮件消息实现 |
| `RtxMessageImpl` | RTX 消息实现 |
| `TodoItemMessageImpl` | 待办事项消息实现 |
| `RtxSendService` | RTX 发送服务 |

## 事件驱动

| 类 | 说明 |
|----|------|
| `IncomingInspectionTaskFinishEvent` | 来料检验完成事件 |
| `TicketEventPublisher` | 工单事件发布器 |
| `TicketEventListener` | 工单事件监听器 |

## 配置

| 类 | 说明 |
|----|------|
| `PdfExtractConfig` | PDF 提取服务 Bean 配置（注册 PdfExtractionService/TextGrouper/DimensionIdentifier/RegionFilterService） |
| `AsyncConfig` | 异步线程池配置：`ticketTaskExecutor`(5-10)、`wmsCallbackExecutor`(5-20) |

## 测试

- `DeploySitTest.java` - SIT 环境部署测试

## 相关文件清单

- `src/main/java/com/nflg/qms/admin/controller/` - 34 个 Controller
- `src/main/java/com/nflg/qms/admin/controller/external/` - 3 个外部接口 Controller
- `src/main/java/com/nflg/qms/admin/service/` - 约 31 个 Service
- `src/main/java/com/nflg/qms/admin/service/impl/` - 消息发送实现
- `src/main/java/com/nflg/qms/admin/config/` - 配置类
- `src/main/java/com/nflg/qms/admin/event/` - 事件定义
- `src/main/java/com/nflg/qms/admin/listener/` - 事件监听器
- `src/main/java/com/nflg/qms/admin/publisher/` - 事件发布器
- `src/main/java/com/nflg/qms/admin/pojo/` - QO/VO 对象
- `src/main/java/com/nflg/qms/admin/util/` - 工具类
- `src/main/resources/application*.yml` - 配置文件
- `pom.xml` - 模块依赖定义

## 变更记录 (Changelog)

| 时间 | 操作 | 说明 |
|------|------|------|
| 2026-05-23 14:28:57 | 重写 | 首次扫描严重低估模块规模（记录 3 文件，实际约 80 文件），本次全面重写：补充全部 37 个 Controller、31 个 Service、事件驱动架构、MinIO/OnlyOffice/PDF 提取等依赖，修正入口类名 |
| 2026-05-23 14:16:58 | 初始化 | 首次生成模块文档（内容不完整） |