--- title: "01-需求分析与详细设计文档" created: 2026-03-02 tags: - 项目 aliases: - 需求分析与详细设计文档 --- # 需求分析与详细设计文档 ## **一、项目总体概述** ![[image-e1faa25f.png]] ## **二、需求分析** ### **2.1 业务背景与痛点分析** ![[diagram-1772432596596-e05b2ff6.png]] ### **2.2 用户角色分析** | **角色** | **职责** | **核心需求** | | --- | --- | --- | | **质检员** | 查看瑕疵检测结果，确认/修正AI判定 | 直观的瑕疵标注界面，快速复核 | | **生产调度员** | 制定/调整生产排程 | 智能排产建议，一键调整，甘特图展示 | | **车间主任** | 监控生产与质量全局 | 综合看板，异常告警 | | **设备管理员** | 管理织机设备状态 | 设备状态监控，维护提醒 | | **系统管理员** | 平台配置与维护 | 用户权限管理，系统参数配置 | ### **2.3 功能性需求** #### **2.3.1 瑕疵检测子系统（Python）** ![[diagram-1772432707910-e7631a0b.png]] **详细功能需求清单：** | **编号** | **功能模块** | **功能描述** | **优先级** | | --- | --- | --- | --- | | D-001 | 图像采集管理 | 支持多路工业相机接入，配置采集参数（分辨率、帧率、触发模式） | P0 | | D-002 | 图像预处理 | 灰度转换、直方图均衡化、高斯去噪、自适应阈值处理 | P0 | | D-003 | 瑕疵检测模型 | 基于YOLOv8/RT-DETR的实时目标检测，支持多类瑕疵同时识别 | P0 | | D-004 | 瑕疵分类 | 识别≥8类常见纺织瑕疵（断经、断纬、跳纱、油污、破洞、稀密路、筘痕、错花） | P0 | | D-005 | 瑕疵分级 | 根据瑕疵类型、面积、密度自动判定质量等级（A/B/C/废品） | P0 | | D-006 | 模型管理 | 模型版本管理、在线更新、A/B测试、回滚 | P1 | | D-007 | 标注工具 | 内置标注工具支持新样本标注，支持主动学习 | P1 | | D-008 | 统计报表 | 瑕疵类型分布、趋势分析、设备瑕疵关联分析 | P1 | | D-009 | 边缘部署 | 支持TensorRT/ONNX Runtime边缘端推理加速 | P2 | | D-010 | 模型训练 | 增量训练、迁移学习，支持小样本场景 | P2 | #### **2.3.2 柔性排产子系统（Java）** ![[diagram-1772432758591-2e390eb2.png]] **详细功能需求清单：** | **编号** | **功能模块** | **功能描述** | **优先级** | | --- | --- | --- | --- | | S-001 | 订单管理 | 订单CRUD、Excel/CSV批量导入、订单状态跟踪（待排/已排/生产中/完成） | P0 | | S-002 | 工序管理 | 纺织工艺流程定义（整经→穿综→织造→检验→整理），工序依赖关系 | P0 | | S-003 | 设备管理 | 织机台账（型号、能力、状态）、设备日历、维护计划 | P0 | | S-004 | 排产引擎 | 基于多目标优化算法（交期满足率、设备利用率、换产成本最小化） | P0 | | S-005 | 排产约束 | 硬约束（设备能力、工序依赖、交期）+软约束（换纱时间、批次合并） | P0 | | S-006 | 甘特图展示 | 交互式甘特图，支持拖拽调整、冲突检测、关键路径高亮 | P0 | | S-007 | 动态重排 | 基于瑕疵质量反馈/设备故障触发局部重排，最小扰动原则 | P1 | | S-008 | 产能分析 | 设备负荷率分析、瓶颈识别、产能预测 | P1 | | S-009 | 生产看板 | 实时生产进度、质量指标、设备状态大屏展示 | P1 | | S-010 | 排产模拟 | What-if分析，模拟不同策略下的排产效果 | P2 | ### **2.4 非功能性需求** | **类别** | **需求描述** | **指标** | | --- | --- | --- | | **性能** | 瑕疵检测单张图像推理时间 | ≤50ms（GPU）/ ≤200ms（CPU） | | **性能** | 排产引擎1000道订单求解时间 | ≤30s | | **性能** | 平台页面响应时间 | ≤2s（P95） | | **可用性** | 系统可用性 | ≥99.5% | | **可用性** | 检测服务支持无缝重启 | 支持热更新 | | **可扩展性** | 相机接入数量 | 单节点支持≥8路 | | **可扩展性** | 排产算法可插拔 | 策略模式支持多种算法切换 | | **安全性** | 访问控制 | RBAC权限模型 | | **安全性** | 数据传输 | HTTPS + JWT认证 | | **兼容性** | 浏览器 | Chrome/Edge/Firefox最新2个版本 | ### **2.5 系统上下文** ![[diagram-1772432918746-d2fc51c1.png]] ## **三、详细设计** ### **3.1 系统总体架构** ![[diagram-1772432886202-ac963124.png]] ### **3.2 瑕疵检测子系统详细设计（Python）** #### **3.2.1 模块划分** ```text defect-detection-service/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI应用入口 │ ├── config/ │ │ ├── settings.py # 全局配置(Pydantic BaseSettings) │ │ └── logging_config.py # 日志配置 │ ├── api/ │ │ ├── v1/ │ │ │ ├── detection.py # 检测接口 │ │ │ ├── model_mgmt.py # 模型管理接口 │ │ │ ├── statistics.py # 统计分析接口 │ │ │ └── health.py # 健康检查 │ │ └── deps.py # 依赖注入 │ ├── core/ │ │ ├── camera/ │ │ │ ├── base.py # 相机抽象基类 │ │ │ ├── industrial.py # 工业相机驱动(GigE/USB3) │ │ │ ├── simulator.py # 模拟相机(开发测试) │ │ │ └── manager.py # 多相机管理器 │ │ ├── preprocessing/ │ │ │ ├── pipeline.py # 预处理流水线 │ │ │ ├── transforms.py # 图像变换操作集 │ │ │ └── augmentation.py # 数据增强 │ │ ├── inference/ │ │ │ ├── base_detector.py # 检测器抽象基类 │ │ │ ├── yolo_detector.py # YOLOv8检测器 │ │ │ ├── rtdetr_detector.py # RT-DETR检测器 │ │ │ ├── segmentor.py # 语义分割器 │ │ │ ├── model_loader.py # 模型加载器(支持ONNX/TRT/PT) │ │ │ └── engine.py # 推理引擎(批处理/流式) │ │ ├── postprocessing/ │ │ │ ├── nms.py # 非极大值抑制 │ │ │ ├── classifier.py # 瑕疵分类后处理 │ │ │ ├── grading.py # 质量分级规则引擎 │ │ │ └── tracker.py # 布匹连续帧瑕疵跟踪 │ │ └── training/ │ │ ├── trainer.py # 模型训练器 │ │ ├── dataset.py # 数据集管理 │ │ └── active_learning.py # 主动学习策略 │ ├── models/ │ │ ├── detection_result.py # 检测结果数据模型 │ │ ├── defect.py # 瑕疵实体 │ │ ├── quality_grade.py # 质量等级 │ │ └── camera_config.py # 相机配置 │ ├── services/ │ │ ├── detection_service.py # 检测业务服务 │ │ ├── alert_service.py # 告警服务 │ │ ├── storage_service.py # 图像存储服务 │ │ └── message_service.py # 消息发布服务 │ ├── db/ │ │ ├── database.py # 数据库连接 │ │ ├── models.py # SQLAlchemy ORM模型 │ │ └── repositories/ # 数据访问层 │ └── utils/ │ ├── image_utils.py │ └── metrics.py # 性能指标收集 ├── models/ # 预训练模型文件 ├── tests/ ├── Dockerfile ├── requirements.txt └── pyproject.toml ``` #### **3.2.2 核心类设计** ![[image-d4be2e38.png]] #### **3.2.3 核心流程设计** **实时检测流程：** ![[diagram-1772433110959-e352e8d0.png]] #### **3.2.4 关键算法设计** **瑕疵检测模型架构：** ![[diagram-1772433000836-8d1d2dfa.png]] **质量分级规则引擎：** ```python # 分级规则配置示例(grading_rules.yaml对应的处理逻辑) """ 分级规则设计： - A级(优等品): 无重大瑕疵，轻微瑕疵≤2处/10米 - B级(一等品): 无破洞，其他瑕疵≤5处/10米，单处面积<2cm² - C级(二等品): 无破洞，其他瑕疵≤10处/10米，单处面积<5cm² - 废品: 超出C级标准，或存在连续性严重缺陷 """ class GradingRule: """质量分级规则""" def __init__(self, grade, max_defect_count, max_single_area, forbidden_types, max_total_area_ratio): self.grade = grade self.max_defect_count = max_defect_count # 每10米最大瑕疵数 self.max_single_area = max_single_area # 单处最大面积(cm²) self.forbidden_types = forbidden_types # 禁止出现的瑕疵类型 self.max_total_area_ratio = max_total_area_ratio # 总瑕疵面积占比 GRADING_RULES = [ GradingRule("A", max_defect_count=2, max_single_area=1.0, forbidden_types=["HOLE", "BROKEN_WARP"], max_total_area_ratio=0.001), GradingRule("B", max_defect_count=5, max_single_area=2.0, forbidden_types=["HOLE"], max_total_area_ratio=0.005), GradingRule("C", max_defect_count=10, max_single_area=5.0, forbidden_types=["HOLE"], max_total_area_ratio=0.01), # 超出C级 → 废品 ] ``` #### **3.2.5 API接口设计** | **接口** | **方法** | **路径** | **描述** | | --- | --- | --- | --- | | 单图检测 | POST | `/api/v1/detection/image` | 上传单张图片进行检测 | | 批量检测 | POST | `/api/v1/detection/batch` | 批量图片检测 | | 启动流式检测 | POST | `/api/v1/detection/stream/start` | 启动指定相机的实时检测 | | 停止流式检测 | POST | `/api/v1/detection/stream/stop` | 停止指定相机的实时检测 | | 检测记录查询 | GET | `/api/v1/detection/records` | 分页查询历史检测记录 | | 瑕疵统计 | GET | `/api/v1/statistics/defects` | 获取瑕疵分布统计 | | 趋势分析 | GET | `/api/v1/statistics/trends` | 获取瑕疵趋势数据 | | 模型列表 | GET | `/api/v1/models` | 获取已注册模型列表 | | 切换模型 | PUT | `/api/v1/models/{id}/activate` | 激活指定模型版本 | | 实时WebSocket | WS | `/ws/v1/detection/{camera_id}` | 实时检测结果推送 | **核心接口详细定义：** ```java # 单图检测接口 # POST /api/v1/detection/image # Request: multipart/form-data # - file: 图片文件 (JPEG/PNG/BMP) # - camera_id: 可选，关联相机ID # - fabric_type: 可选，面料类型 # Response 200: { "request_id": "uuid-string", "image_id": "img_20260302_001", "detection_time_ms": 42.5, "defects": [ { "defect_id": "def_001", "type": "BROKEN_WARP", "type_name": "断经", "confidence": 0.96, "bbox": {"x1": 120, "y1": 350, "x2": 185, "y2": 420}, "area_px": 4550, "area_cm2": 1.82, "severity": "MAJOR" } ], "defect_count": 1, "quality_grade": "B", "annotated_image_url": "/storage/annotated/img_20260302_001.jpg", "original_image_url": "/storage/original/img_20260302_001.jpg" } ``` #### ### **3.3 柔性排产子系统详细设计（Java）** #### **3.3.1 模块划分** ```text flexible-scheduling-service/ ├── pom.xml ├── src/main/java/com/zhihuitong/scheduling/ │ ├── SchedulingApplication.java │ ├── config/ │ │ ├── SecurityConfig.java # Spring Security配置 │ │ ├── RedisConfig.java │ │ ├── RabbitMQConfig.java │ │ ├── SwaggerConfig.java │ │ └── WebSocketConfig.java │ ├── controller/ │ │ ├── OrderController.java # 订单管理API │ │ ├── ResourceController.java # 资源管理API │ │ ├── ScheduleController.java # 排产管理API │ │ ├── DashboardController.java # 看板数据API │ │ └── SystemController.java # 系统管理API │ ├── service/ │ │ ├── order/ │ │ │ ├── OrderService.java │ │ │ └── OrderDecomposeService.java # 订单工序分解 │ │ ├── resource/ │ │ │ ├── LoomService.java # 织机设备管理 │ │ │ ├── WorkerService.java # 人员班次 │ │ │ └── CapacityService.java # 产能计算 │ │ ├── scheduling/ │ │ │ ├── SchedulingService.java # 排产主服务 │ │ │ ├── SchedulingContext.java # 排产上下文 │ │ │ └── SchedulingEvaluator.java # 方案评估 │ │ ├── engine/ │ │ │ ├── SchedulingEngine.java # 排产引擎接口 │ │ │ ├── GeneticAlgorithmEngine.java # 遗传算法实现 │ │ │ ├── SimulatedAnnealingEngine.java # 模拟退火实现 │ │ │ └── OptaPlannerEngine.java # OptaPlanner实现 │ │ ├── quality/ │ │ │ ├── QualityFeedbackService.java # 质量反馈处理 │ │ │ └── DynamicRescheduleService.java # 动态重排 │ │ └── monitor/ │ │ ├── ProductionMonitorService.java # 生产监控 │ │ └── AlertService.java # 告警服务 │ ├── domain/ │ │ ├── entity/ │ │ │ ├── Order.java │ │ │ ├── OrderItem.java │ │ │ ├── ProcessStep.java # 工序 │ │ │ ├── Loom.java # 织机 │ │ │ ├── Worker.java │ │ │ ├── SchedulePlan.java # 排产计划 │ │ │ ├── ScheduleTask.java # 排产任务(最小排程单元) │ │ │ └── QualityEvent.java # 质量事件 │ │ ├── enums/ │ │ │ ├── OrderStatus.java │ │ │ ├── LoomStatus.java │ │ │ ├── TaskStatus.java │ │ │ └── DefectType.java │ │ └── vo/ │ │ ├── GanttChartVO.java │ │ ├── ScheduleResultVO.java │ │ └── DashboardVO.java │ ├── repository/ │ │ ├── OrderRepository.java │ │ ├── LoomRepository.java │ │ ├── SchedulePlanRepository.java │ │ └── ScheduleTaskRepository.java │ ├── mq/ │ │ ├── QualityEventConsumer.java # 消费瑕疵检测事件 │ │ └── ScheduleEventProducer.java # 发布排产事件 │ └── util/ │ ├── GanttChartBuilder.java │ └── TimeWindowCalculator.java └── src/main/resources/ ├── application.yml ├── application-dev.yml └── mapper/ # MyBatis XML(使用) ``` #### **3.3.2 核心类设计** ![[image-3da98469.png]] #### **3.3.3 排产引擎核心算法设计** ![[diagram-1772433499591-0e391e0f.png]] **染色体编码设计：** ```java /** * 染色体编码：双层编码 * 第一层(工序排列)：工序的执行顺序排列 [P3, P1, P5, P2, P4, ...] * 第二层(设备分配)：每个工序对应的设备ID [L2, L1, L3, L1, L4, ...] * * 解码规则： * 1. 按工序排列顺序，依次将工序安排到对应设备上 * 2. 考虑工序依赖(同一订单内工序必须按sequence顺序) * 3. 同一设备上的任务不能时间重叠 * 4. 连续不同品种间加入换产时间 */ public class Chromosome { private int[] processSequence; // 工序排列编码 private int[] loomAssignment; // 设备分配编码 private double fitness; // 适应度值 // 适应度计算 public double calculateFitness(SchedulingContext context) { // 解码得到排程方案 List tasks = decode(context); // 计算各子目标 double deliveryRate = calcDeliveryRate(tasks, context); double utilization = calcUtilization(tasks, context); double changeover = calcChangeoverCost(tasks, context); double balance = calcLoadBalance(tasks, context); // 加权求和 this.fitness = 0.4 * deliveryRate + 0.3 * utilization - 0.2 * changeover + 0.1 * balance; return this.fitness; } } ``` #### **3.3.4 质量反馈驱动的动态重排流程** ![[diagram-1772433248130-e9628e6b.png]] #### **3.3.5 API接口设计** **订单管理接口：** | **接口** | **方法** | **路径** | **描述** | | --- | --- | --- | --- | | 创建订单 | POST | `/api/v1/orders` | 新建生产订单 | | 查询订单列表 | GET | `/api/v1/orders` | 分页查询，支持多条件筛选 | | 查询订单详情 | GET | `/api/v1/orders/{id}` | 包含工序分解详情 | | 更新订单 | PUT | `/api/v1/orders/{id}` | 修改订单信息 | | 删除订单 | DELETE | `/api/v1/orders/{id}` | 逻辑删除(仅待排状态) | | 批量导入 | POST | `/api/v1/orders/import` | Excel批量导入 | | 工序分解 | POST | `/api/v1/orders/{id}/decompose` | 按工艺路线分解工序 | **排产管理接口：** | **接口** | **方法** | **路径** | **描述** | | --- | --- | --- | --- | | 执行排产 | POST | `/api/v1/schedules/generate` | 根据参数执行排产 | | 查询排产计划 | GET | `/api/v1/schedules` | 获取排产计划列表 | | 获取甘特图数据 | GET | `/api/v1/schedules/{id}/gantt` | 获取甘特图渲染数据 | | 手动调整任务 | PUT | `/api/v1/schedules/{id}/tasks/{taskId}` | 拖拽调整后保存 | | 冲突检测 | POST | `/api/v1/schedules/{id}/check-conflicts` | 检测排产冲突 | | 方案对比 | POST | `/api/v1/schedules/compare` | 多方案对比分析 | | 确认发布 | POST | `/api/v1/schedules/{id}/publish` | 确认排产计划 | | 动态重排 | POST | `/api/v1/schedules/{id}/reschedule` | 触发动态重排 | **资源管理接口：** | **接口** | **方法** | **路径** | **描述** | | --- | --- | --- | --- | | 织机列表 | GET | `/api/v1/looms` | 获取织机列表 | | 织机详情 | GET | `/api/v1/looms/{id}` | 设备详情含能力矩阵 | | 更新织机状态 | PUT | `/api/v1/looms/{id}/status` | 更新设备状态 | | 产能日历 | GET | `/api/v1/looms/{id}/calendar` | 获取设备产能日历 | | 产能分析 | GET | `/api/v1/capacity/analysis` | 获取产能分析报告 | **看板接口：** | **接口** | **方法** | **路径** | **描述** | | --- | --- | --- | --- | | 综合看板数据 | GET | `/api/v1/dashboard/overview` | 获取综合看板数据 | | 生产进度 | GET | `/api/v1/dashboard/progress` | 实时生产进度 | | 质量指标 | GET | `/api/v1/dashboard/quality` | 质量指标汇总 | | 设备状态 | GET | `/api/v1/dashboard/loom-status` | 设备实时状态 | | WebSocket推送 | WS | `/ws/v1/dashboard` | 看板实时数据推送 | **排产生成请求体示例：** ```json { "planName": "2026年3月第1周排产", "planStartDate": "2026-03-02", "planEndDate": "2026-03-08", "orderIds": [1001, 1002, 1003, 1005], "algorithmType": "GENETIC_ALGORITHM", "algorithmParams": { "populationSize": 200, "maxGenerations": 500, "crossoverRate": 0.8, "mutationRate": 0.15 }, "objectiveWeights": { "deliveryRate": 0.4, "utilization": 0.3, "changeoverCost": 0.2, "loadBalance": 0.1 }, "constraints": { "respectDeadline": true, "maxOvertimeHoursPerDay": 2, "minChangeoverMinutes": 30 } } ``` **甘特图响应体示例：** ```json { "planId": 2001, "planName": "2026年3月第1周排产", "metrics": { "deliveryRate": 0.95, "avgUtilization": 0.87, "totalChangeoverHours": 12.5, "loadBalanceIndex": 0.82 }, "looms": [ { "loomId": 1, "loomCode": "L-001", "loomType": "喷气织机", "tasks": [ { "taskId": 5001, "orderNo": "ORD-2026-0301", "processName": "织造", "fabricType": "涤纶平纹", "startTime": "2026-03-02T08:00:00", "endTime": "2026-03-02T16:30:00", "changeoverBefore": 30, "status": "PLANNED", "color": "#4CAF50" } ] } ], "criticalPath": [5001, 5003, 5007], "conflicts": [] } ``` #### ### **3.4 系统集成设计** #### **3.4.1 Python-Java跨语言通信** ![[diagram-1772433591858-2b41b559.png]] #### **3.4.2 消息队列设计** | **Exchange** | **Routing Key** | **消息内容** | **生产者** | **消费者** | | --- | --- | --- | --- | --- | | `quality.events` | `defect.alert.{severity}` | 瑕疵告警事件 | Python检测服务 | Java排产服务 | | `quality.events` | `grade.change.{loomId}` | 布匹质量等级变更 | Python检测服务 | Java排产服务 | | `quality.events` | `device.fault.{loomId}` | 设备异常(检测端发现) | Python检测服务 | Java排产服务 | | `schedule.events` | `plan.updated` | 排产计划变更通知 | Java排产服务 | 前端WebSocket | | `schedule.events` | `task.status.change` | 任务状态变更 | Java排产服务 | 监控大屏 | **消息体格式示例：** ```java // 质量事件消息 (Python → RabbitMQ → Java) { "eventId": "evt_20260302_001", "eventType": "DEFECT_ALERT", "timestamp": "2026-03-02T13:45:00Z", "source": { "cameraId": "CAM-003", "loomId": "L-005", "fabricRollId": "ROLL-20260302-003" }, "data": { "defectType": "BROKEN_WARP", "defectCount": 5, "timeWindow": "10min", "currentGrade": "C", "previousGrade": "B", "severity": "HIGH" }, "recommendation": "RESCHEDULE_SUGGESTED" } ``` ### **3.5 部署架构设计** ![[diagram-1772433658460-1790cb63.png]] --- **项目分区导航**：⬅️ [[02-性能优化|02-性能优化]] | 01-需求分析与详细设计文档 | ➡️ [[00-企业级项目深读|00-企业级项目深读]]