需求分析与详细设计文档

一、项目总体概述

image-e1faa25f

二、需求分析

2.1 业务背景与痛点分析

diagram-1772432596596-e05b2ff6

2.2 用户角色分析

角色 职责 核心需求
质检员 查看瑕疵检测结果，确认/修正AI判定 直观的瑕疵标注界面，快速复核
生产调度员 制定/调整生产排程 智能排产建议，一键调整，甘特图展示
车间主任 监控生产与质量全局 综合看板，异常告警
设备管理员 管理织机设备状态 设备状态监控，维护提醒
系统管理员 平台配置与维护 用户权限管理，系统参数配置

2.3 功能性需求

2.3.1 瑕疵检测子系统（Python）

diagram-1772432707910-e7631a0b

详细功能需求清单：

编号 功能模块 功能描述 优先级
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

详细功能需求清单：

编号 功能模块 功能描述 优先级
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

三、详细设计

3.1 系统总体架构

diagram-1772432886202-ac963124

3.2 瑕疵检测子系统详细设计（Python）

3.2.1 模块划分

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

3.2.3 核心流程设计

实时检测流程：

diagram-1772433110959-e352e8d0

3.2.4 关键算法设计

瑕疵检测模型架构：

diagram-1772433000836-8d1d2dfa

质量分级规则引擎：

# 分级规则配置示例(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} 实时检测结果推送

核心接口详细定义：

# 单图检测接口
# 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 模块划分

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

3.3.3 排产引擎核心算法设计

diagram-1772433499591-0e391e0f

染色体编码设计：

/**
 * 染色体编码：双层编码
 * 第一层(工序排列)：工序的执行顺序排列 [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<ScheduleTask> 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

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 看板实时数据推送

排产生成请求体示例：

{
    "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
    }
}

甘特图响应体示例：

{
    "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

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排产服务 监控大屏

消息体格式示例：

// 质量事件消息 (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

项目分区导航：⬅️ 02-性能优化 | 01-需求分析与详细设计文档 | ➡️ 00-企业级项目深读