MES 制造执行系统 · 开发实战

五层架构

制造业的信息系统按 ISA-95 标准分五层。MES 卡在正中间第三层，这个位置决定了它的全部特质：

MES 的十二个功能模块

一个完整的 MES 通常覆盖这些模块。本教程实现的是一套去掉冗余后的核心集（加粗部分）：

一张工单的一生

车间里所有动作都围着工单转。它有 7 个状态，其中 5 个是主干流程，2 个是岔路：

核心代码：状态机定义

用字典描述"从某个状态出发，允许到达哪些状态"。这是整个 MES 里信息密度最高的一段代码：

/// <summary>
/// 状态机定义 —— 这张表就是"车间管理规则"的代码化。
///
/// 每一项都对应现实中一个审批动作，不是随便连的：
///   · 草稿能下达，也能直接作废（计划没批下来就不做了）
///   · 已下达可以直接进生产，也可以先挂起（等料）
///   · 完工之后只能关闭，不能回退 —— 已经入库的东西不能说改就改
///   · 关闭和作废是终态，没有出口
/// </summary>
private static readonly Dictionary<WorkOrderStatus, WorkOrderStatus[]> AllowedTransitions = new()
{
    [WorkOrderStatus.Draft]      = [WorkOrderStatus.Released, WorkOrderStatus.Cancelled],
    [WorkOrderStatus.Released]   = [WorkOrderStatus.InProgress, WorkOrderStatus.OnHold, WorkOrderStatus.Cancelled],
    [WorkOrderStatus.InProgress] = [WorkOrderStatus.OnHold, WorkOrderStatus.Completed, WorkOrderStatus.Cancelled],
    [WorkOrderStatus.OnHold]     = [WorkOrderStatus.InProgress, WorkOrderStatus.Cancelled],
    [WorkOrderStatus.Completed]  = [WorkOrderStatus.Closed],
    [WorkOrderStatus.Closed]     = [],
    [WorkOrderStatus.Cancelled]  = []
};

/// <summary>判断一次状态流转是否被允许</summary>
public static bool CanTransit(WorkOrderStatus from, WorkOrderStatus to)
    => AllowedTransitions.TryGetValue(from, out var targets) && targets.Contains(to);

/// <summary>返回从当前状态出发，所有合法的下一步</summary>
public static WorkOrderStatus[] NextStates(WorkOrderStatus from)
    => AllowedTransitions.TryGetValue(from, out var targets) ? targets : [];

分三个域组织

不要按"模块"切表，要按数据的生命周期切。基础数据长期不变，执行数据每天猛增，追溯数据只增不改：

实体关系

技术选型说明

第一步 · 新建项目

第二步 · 删掉模板自带的示例

模板会生成一个 WeatherForecast 示例。它在 解决方案资源管理器 （右侧那个树，快捷键 Ctrl+Alt+L）里长这样：

删完 Controllers 文件夹可能一起消失了（空文件夹 VS 不显示）。 没关系，第 7 课新建控制器时它会自动回来。

第三步 · 装 3 个 NuGet 包

用「管理解决方案的 NuGet 程序包」能一次装完，比逐个右键项目省事——它会在一个界面里 反复切换搜索，不用来回点菜单。

第四步 · 改写 Program.cs

模板生成的 Program.cs 里还留着示例接口的映射。整份替换成下面这样：

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();   // 启用控制器（第 7 课才会有第一个控制器）
builder.Services.AddOpenApi();       // 生成 OpenAPI 文档，Scalar 靠它渲染

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();              // 文档数据：/openapi/v1.json
    app.MapScalarApiReference();   // 可视化调试界面：/scalar/v1
}

// 开发阶段先关掉 HTTPS 重定向，方便直接用 http 调接口
// app.UseHttpsRedirection();

app.UseAuthorization();
app.MapControllers();

app.Run();

第五步 · 改 appsettings.json

把连接串加进去。现在还用不上，但下一课就要读它：

{
  "Logging": {
    "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" }
  },
  "AllowedHosts": "*",
  "ConnectionStrings": {
    "Default": "Data Source=mes.db"
  }
}

Data Source=mes.db 是个相对路径，数据库文件会生成在 程序的工作目录里。用 VS 跑就是项目根目录（和 .csproj 同级）， 第 6 课就能看到它出现。

第六步 · 跑起来

到这里代码已经能编译了，先让它跑起来看效果，再回头讲为什么。

此刻你的项目

http://localhost:5100/scalar/v1

# 编译：应该 0 错误
dotnet build

# 命令行启动必须显式带环境变量，否则 /scalar/v1 会 404
ASPNETCORE_ENVIRONMENT=Development dotnet run --no-launch-profile --urls "http://localhost:5100"

第一步 · 建文件夹和实体类

VS 生成的 Material.cs 里已经有 namespace Mes.Api.Entities; （新版 VS 用文件范围命名空间）。把文件内容整体替换成下面这份：

namespace Mes.Api.Entities;

/// <summary>
/// 物料主数据 —— 原材料、半成品、成品的统一抽象。
///
/// MES 里所有东西都是物料：装配用的 M6 螺丝是物料，最终装出来的电机也是物料。
/// 它们共用一套编码、一套库存口径，区别只在 MaterialType。
/// </summary>
public class Material
{
    public int Id { get; set; }

    /// <summary>
    /// 物料编码，全厂唯一。
    /// 这是车间里人和系统对话的"身份证"——报工时扫的码、领料单上写的号，
    /// 指的都是它。所以它必须有唯一索引兜底，不能靠前端保证。
    /// </summary>
    public string Code { get; set; } = string.Empty;

    public string Name { get; set; } = string.Empty;

    /// <summary>规格型号，例如 "M6x20 不锈钢" / "220V 1.5kW"</summary>
    public string? Spec { get; set; }

    /// <summary>计量单位：个 / 件 / kg / 米</summary>
    public string Unit { get; set; } = "个";

    public MaterialType Type { get; set; }

    /// <summary>
    /// 是否启用。停用的物料不能再被新工单引用，但历史单据必须还能查到它。
    /// 这就是为什么 MES 里几乎不做物理删除。
    /// </summary>
    public bool IsActive { get; set; } = true;

    public DateTime CreatedAt { get; set; } = DateTime.Now;
}

public enum MaterialType
{
    /// <summary>原材料 —— 采购进来的，如钢材、标准件</summary>
    RawMaterial = 1,

    /// <summary>半成品 —— 自制的中间件，既是上道工序产出，又是下道投入</summary>
    SemiFinished = 2,

    /// <summary>成品 —— 可以直接入库发货的</summary>
    Finished = 3
}

第二步 · 建 DbContext

同样方式在 Data 文件夹里新建类 MesDbContext。 内容是我们这一课的核心：

using Mes.Api.Entities;
using Microsoft.EntityFrameworkCore;

namespace Mes.Api.Data;

public class MesDbContext : DbContext
{
    public MesDbContext(DbContextOptions<MesDbContext> options) : base(options) { }

    // 每个实体对应一个 DbSet —— 它就是代码里操作这张表的入口。
    // 后面每加一张表，这里就多一行。
    public DbSet<Material> Materials => Set<Material>();

    /// <summary>
    /// 全局约定：所有 decimal 一律按 double 存储。
    ///
    /// 为什么必须这么做？SQLite 没有原生 decimal 类型，EF 默认把它存成 TEXT，
    /// 于是任何 OrderBy / Sum / 比较都会在运行时抛异常 —— 看板里的
    /// "按数量排序"会直接崩掉。改成 double 存储后一切正常，
    /// 而 C# 侧仍然用 decimal 接收，对数量这种量级精度完全够。
    ///
    /// 写在这里而不是逐个属性配置，是为了**不漏**。
    /// 将来新增实体带 decimal 字段时自动生效。
    /// </summary>
    protected override void ConfigureConventions(ModelConfigurationBuilder cb)
    {
        cb.Properties<decimal>().HaveConversion<double>();
    }

    protected override void OnModelCreating(ModelBuilder mb)
    {
        mb.Entity<Material>(e =>
        {
            e.Property(x => x.Code).HasMaxLength(50).IsRequired();
            e.Property(x => x.Name).HasMaxLength(100).IsRequired();
            e.Property(x => x.Spec).HasMaxLength(200);
            e.Property(x => x.Unit).HasMaxLength(20).IsRequired();

            // MES 第一条铁律：物料编码全厂唯一。
            // 放在数据库层，因为并发创建时前端校验必然漏网。
            e.HasIndex(x => x.Code).IsUnique();
        });
    }
}

第三步 · 接进 Program.cs

第 4 课我们故意没写 AddDbContext，因为那时还没有这个类。 现在可以补上了——打开 Program.cs，加两处：

using Mes.Api.Data;                  // ← 加：才能引用 MesDbContext
using Microsoft.EntityFrameworkCore; // ← 加：才能用 UseSqlite
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApi();

// ← 加：注册 EF Core。连接串从 appsettings.json 读，不写死在代码里。
// 换数据库只需把 UseSqlite 换成 UseSqlServer，业务代码一行都不用动。
builder.Services.AddDbContext<MesDbContext>(options =>
    options.UseSqlite(builder.Configuration.GetConnectionString("Default")));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}

app.UseAuthorization();
app.MapControllers();

app.Run();

此刻你的项目

注意：还没有 mes.db，也没有 Migrations/。 AddDbContext 只是"登记"了这个上下文，并不会去连数据库或者建文件。 真正生成数据库是下一课的事。

dotnet build          # 期望：0 错误 0 警告
ls Mes.Api/*.db       # 期望：没有输出（数据库文件此时不该存在）

两条路，选一条走

EF Core 的迁移命令有两种执行方式，在 VS 里都能用。建议先用路径 A（PMC）， 它和 VS 集成得最好；路径 B 是等价的命令行写法，你以后在服务器上部署时会用到。

命令执行完，多了什么

文件名前面的时间戳是自动生成的，用于确定迁移顺序——所以同一个迁移名只能出现一次。

为什么用 Migrations 而不是 EnsureCreated

让程序启动时自动应用迁移

开发阶段每次改完都手敲一遍 Update-Database 太啰嗦。 可以在启动时自动做——打开 Program.cs，在 app.Build() 之后、app.Run() 之前插入：

// ---------- 启动时自动应用迁移 ----------
// 用 Migrate() 而不是 EnsureCreated()：前者支持后续 schema 演进，
// 是真实项目该用的方式。
using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<MesDbContext>();
    db.Database.Migrate();
}

Get-Migration          # 应列出 InitialCreate，说明迁移已生成
Get-DbContext          # 应显示 MesDbContext

dotnet ef migrations list      # 应显示 InitialCreate（已应用）
ls Migrations/                 # 应看到 3 个文件
ls mes.db                      # 应看到数据库文件

控制器与服务层的分工

先明确一条纪律：控制器只做三件事——收参数、调服务、返回结果。 物料这种纯主数据没有业务规则，所以直接操作 DbContext 是可以的； 但到了工单、报工，就必须下沉到 Service。

using Mes.Api.Data;
using Mes.Api.Entities;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;

namespace Mes.Api.Controllers;

/// <summary>
/// 物料主数据接口。
///
/// 注意：这里为了先跑通链路，直接拿实体做了入参和出参。
/// 工程化阶段会引入 DTO，把"数据库长什么样"和"接口长什么样"解耦。
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class MaterialsController : ControllerBase
{
    private readonly MesDbContext _db;

    public MaterialsController(MesDbContext db) => _db = db;

    /// <summary>查询物料列表，支持按编码或名称模糊搜索</summary>
    [HttpGet]
    public async Task<ActionResult<List<Material>>> GetAll([FromQuery] string? keyword)
    {
        var query = _db.Materials.AsQueryable();

        if (!string.IsNullOrWhiteSpace(keyword))
        {
            query = query.Where(m => m.Code.Contains(keyword) || m.Name.Contains(keyword));
        }

        return await query.OrderBy(m => m.Code).ToListAsync();
    }

    /// <summary>按 Id 查询单个物料</summary>
    [HttpGet("{id:int}")]
    public async Task<ActionResult<Material>> GetById(int id)
    {
        var material = await _db.Materials.FindAsync(id);
        return material is null
            ? NotFound(new { message = $"物料 {id} 不存在" })
            : material;
    }

    /// <summary>新增物料</summary>
    [HttpPost]
    public async Task<ActionResult<Material>> Create(Material input)
    {
        // 先查一遍是为了给出人话提示；真正兜底的是数据库唯一索引
        if (await _db.Materials.AnyAsync(m => m.Code == input.Code))
        {
            return Conflict(new { message = $"物料编码 {input.Code} 已存在" });
        }

        input.Id = 0;
        input.CreatedAt = DateTime.Now;

        _db.Materials.Add(input);
        await _db.SaveChangesAsync();

        return CreatedAtAction(nameof(GetById), new { id = input.Id }, input);
    }

    /// <summary>修改物料</summary>
    [HttpPut("{id:int}")]
    public async Task<IActionResult> Update(int id, Material input)
    {
        var material = await _db.Materials.FindAsync(id);
        if (material is null)
        {
            return NotFound(new { message = $"物料 {id} 不存在" });
        }

        if (await _db.Materials.AnyAsync(m => m.Code == input.Code && m.Id != id))
        {
            return Conflict(new { message = $"物料编码 {input.Code} 已被其他物料占用" });
        }

        material.Code = input.Code;
        material.Name = input.Name;
        material.Spec = input.Spec;
        material.Unit = input.Unit;
        material.Type = input.Type;
        material.IsActive = input.IsActive;

        await _db.SaveChangesAsync();
        return NoContent();
    }

    /// <summary>停用物料（MES 里不做物理删除）</summary>
    [HttpDelete("{id:int}")]
    public async Task<IActionResult> Delete(int id)
    {
        var material = await _db.Materials.FindAsync(id);
        if (material is null)
        {
            return NotFound(new { message = $"物料 {id} 不存在" });
        }

        // 为什么不真删？—— 三个月前的工单还引用着这个物料，
        // 真删了追溯链就断了。MES 的"删除"永远是停用。
        material.IsActive = false;
        await _db.SaveChangesAsync();
        return NoContent();
    }
}

BASE=http://localhost:5100

# 新增
curl -s -X POST $BASE/api/materials -H "Content-Type: application/json" \
  -d '{"code":"RM-TEST","name":"测试物料","unit":"个","type":1}'

# 重复编码 —— 应该返回 409
curl -s -w " [HTTP %{http_code}]" -X POST $BASE/api/materials \
  -H "Content-Type: application/json" \
  -d '{"code":"RM-TEST","name":"重复","unit":"个","type":1}'

BOM 是什么

BOM（Bill of Materials，物料清单）描述"一个产品由哪些零件、按什么用量组成"。 它是自引用表：父件和子件都是 Material，只是站在不同位置。

DbContext 里的双重外键配置

这是第 3 课预告过的坑。BOM 两次引用 Material，必须显式声明谁是父谁是子：

mb.Entity<BomItem>(e =>
{
    e.Property(x => x.Position).HasMaxLength(100);

    // BomItem 两次引用 Material —— EF 无法自行判断父子，
    // 必须显式指定外键，否则启动时直接报"关系不明确"。
    e.HasOne(x => x.ParentMaterial)
     .WithMany()
     .HasForeignKey(x => x.ParentMaterialId)
     .OnDelete(DeleteBehavior.Restrict);

    e.HasOne(x => x.ChildMaterial)
     .WithMany()
     .HasForeignKey(x => x.ChildMaterialId)
     .OnDelete(DeleteBehavior.Restrict);

    // 同一父件下不允许重复挂同一子件，否则用量会被重复计算
    e.HasIndex(x => new { x.ParentMaterialId, x.ChildMaterialId }).IsUnique();
});

递归展开与循环引用防护

整棵 BOM 树的展开靠递归。但自引用表最危险的是成环—— 一旦 A 的 BOM 里出现 A 自己（数据录错、或经多层绕回来）， 没有防护的递归会直接把服务打挂：

/// <summary>
/// 递归展开整棵 BOM 树。
/// 带 visited 集合防止死循环 —— 自引用表配错数据就会成环，
/// 没有这道防护，一次请求就能把服务打挂。
/// </summary>
[HttpGet("{materialId:int}/tree")]
public async Task<ActionResult<BomNodeDto>> GetTree(int materialId)
{
    var root = await _db.Materials.FindAsync(materialId);
    if (root is null)
        return NotFound(new { message = $"物料 {materialId} 不存在" });

    var visited = new HashSet<int> { root.Id };
    var tree = await BuildNodeAsync(root, 1, 0, visited);
    return Ok(tree);
}

private async Task<BomNodeDto> BuildNodeAsync(
    Material material, decimal quantity, decimal lossRate, HashSet<int> visited)
{
    var children = new List<BomNodeDto>();

    var links = await _db.BomItems
        .Include(b => b.ChildMaterial)
        .Where(b => b.ParentMaterialId == material.Id)
        .ToListAsync();

    foreach (var link in links)
    {
        var child = link.ChildMaterial;

        if (visited.Contains(child.Id))
        {
            // 环：只标记，不再往下钻
            children.Add(new BomNodeDto(
                child.Id, child.Code, child.Name, child.Unit,
                TypeText(child.Type), link.Quantity, link.LossRate, link.Position,
                true, []));
            continue;
        }

        visited.Add(child.Id);
        children.Add(await BuildNodeAsync(child, link.Quantity, link.LossRate, visited));
    }

    return new BomNodeDto(
        material.Id, material.Code, material.Name, material.Unit,
        TypeText(material.Type), quantity, lossRate, null, false, children);
}

含损耗的实际备料量

查询单层子件时，直接算出实际要备多少料，前端不用再算：

return Ok(items.Select(b => new
{
    b.Id,
    b.ChildMaterialId,
    childCode = b.ChildMaterial.Code,
    childName = b.ChildMaterial.Name,
    b.Quantity,
    b.LossRate,
    b.Position,
    // 含损耗的实际备料量：单位用量 × (1 + 损耗率/100)
    requiredQty = Math.Round(b.Quantity * (1 + b.LossRate / 100m), 4)
}));

# 展开成品电机的完整用料（8 是成品物料 Id）
curl -s http://localhost:5100/api/bom/8/tree

工作中心：MES 的产能基本单位

工作中心是"能干活的地方"——一条产线、一台设备、一个手工工位。 它同时是排程的产能单位、派工的落点、报工的归属。

namespace Mes.Api.Entities;

/// <summary>
/// 工作中心 —— "能干活的地方"：一条产线、一台设备、一个手工工位。
///
/// 它同时是排程的产能单位、派工的落点、报工的归属。
/// MES 里说"这道工序在哪儿做"，指的就是它。
/// </summary>
public class WorkCenter
{
    public int Id { get; set; }
    public string Code { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;

    /// <summary>类型：产线 / 单机 / 手工工位</summary>
    public string Type { get; set; } = "产线";

    /// <summary>日可用分钟数，产能测算的基数（默认 480 = 8 小时）</summary>
    public int DailyMinutes { get; set; } = 480;

    public bool IsActive { get; set; } = true;
}

工艺路线：工序模板

namespace Mes.Api.Entities;

/// <summary>
/// 工艺路线工序（模板）—— 挂在产品上，描述"这个产品要依次经过哪几道工序"。
///
/// 它只是模板。工单下达时，会按这张模板实例化出 WorkOrderOperation。
/// 这样改工艺路线不会影响已经在生产的工单 —— 这是 MES 的一个关键设计。
/// </summary>
public class ProcessStep
{
    public int Id { get; set; }

    /// <summary>所属产品</summary>
    public int MaterialId { get; set; }
    public Material Material { get; set; } = null!;

    /// <summary>工序序号，用 10 / 20 / 30 这样留间隔，方便以后往中间插工序</summary>
    public int SequenceNo { get; set; }

    public string Name { get; set; } = string.Empty;

    /// <summary>执行该工序的工作中心</summary>
    public int WorkCenterId { get; set; }
    public WorkCenter WorkCenter { get; set; } = null!;

    /// <summary>单件标准工时（分钟），用于产能测算和实际效率对比</summary>
    public decimal StandardMinutes { get; set; }

    /// <summary>是否关键工序 —— 关键工序必须检验合格才能流转</summary>
    public bool IsKeyProcess { get; set; }
}

预置一组演示数据

给成品电机配 5 道工序，这就是后面工单展开的依据：

curl -s http://localhost:5100/api/work-centers          # 5 个工作中心
curl -s http://localhost:5100/api/process-steps/8       # 成品电机的 5 道工序
curl -s http://localhost:5100/api/bom/8/tree            # 完整 BOM 树

工单实体

namespace Mes.Api.Entities;

/// <summary>
/// 工单 —— MES 的核心单据。
///
/// 它做两件事：
///   1. 确定"做什么" —— 哪个产品、做多少、什么时候要
///   2. 承载"怎么做" —— 下达时按工艺路线展开出 N 道工序任务
///
/// 之后所有的派工、报工、检验、追溯，都挂在它的工序上。
/// </summary>
public class WorkOrder
{
    public int Id { get; set; }

    /// <summary>工单号，全厂唯一，如 WO-20261014-0001</summary>
    public string OrderNo { get; set; } = string.Empty;

    /// <summary>要生产的产品</summary>
    public int MaterialId { get; set; }
    public Material Material { get; set; } = null!;

    public decimal PlannedQty { get; set; }        // 计划数量
    public decimal CompletedQty { get; set; }      // 已产出（良品）
    public decimal ScrapQty { get; set; }          // 已报废

    public WorkOrderStatus Status { get; set; } = WorkOrderStatus.Draft;

    /// <summary>优先级，数字越小越急</summary>
    public int Priority { get; set; } = 5;

    /// <summary>来源：ERP 下发 / 手工创建</summary>
    public string Source { get; set; } = "手工创建";

    public DateTime? PlannedStart { get; set; }
    public DateTime? PlannedEnd { get; set; }
    public DateTime? ActualStart { get; set; }     // 首道工序首次报工时写入
    public DateTime? ActualEnd { get; set; }

    public string? Remark { get; set; }
    public DateTime CreatedAt { get; set; } = DateTime.Now;

    /// <summary>按工艺路线展开出来的工序任务</summary>
    public List<WorkOrderOperation> Operations { get; set; } = new();
}

工序实体：任务的最小单元

工单是"要做什么"，工序是"具体谁在哪做什么"。注意它的状态是派生的—— 由报工累计数量算出来，不是人工改的：

public class WorkOrderOperation
{
    public int Id { get; set; }

    public int WorkOrderId { get; set; }
    public WorkOrder WorkOrder { get; set; } = null!;

    /// <summary>工序序号，与 ProcessStep 保持一致（10 / 20 / 30 ...）</summary>
    public int SequenceNo { get; set; }

    public string Name { get; set; } = string.Empty;

    public int WorkCenterId { get; set; }
    public WorkCenter WorkCenter { get; set; } = null!;

    public decimal PlannedQty { get; set; }
    public decimal CompletedQty { get; set; }      // 累计合格数
    public decimal ScrapQty { get; set; }          // 累计报废数
    public decimal StandardMinutes { get; set; }

    public bool IsKeyProcess { get; set; }
    public OperationStatus Status { get; set; } = OperationStatus.Pending;

    public DateTime? StartedAt { get; set; }
    public DateTime? FinishedAt { get; set; }

    public List<ProductionReport> Reports { get; set; } = new();
}

/// <summary>
/// 工序状态。注意它是"派生"的 —— 不是人手工改的，
/// 而是报工累计数量算出来的。这一点和工单状态不同。
/// </summary>
public enum OperationStatus
{
    Pending = 0,     // 待开工：一般是因为上一道工序还没完工
    InProgress = 1,  // 进行中：已有报工，但还没做够计划数
    Completed = 2    // 已完工：累计合格数达到计划数
}

创建工单

/// <summary>创建工单（初始为草稿）</summary>
public async Task<WorkOrder> CreateAsync(CreateWorkOrderRequest req)
{
    var product = await _db.Materials.FindAsync(req.MaterialId)
        ?? throw new InvalidOperationException($"物料 {req.MaterialId} 不存在");

    // 原材料是买来的，不能作为工单的产出
    if (product.Type == MaterialType.RawMaterial)
        throw new InvalidOperationException($"物料「{product.Name}」是原材料，不能作为工单产出");

    if (req.PlannedQty <= 0)
        throw new InvalidOperationException("计划数量必须大于 0");

    var wo = new WorkOrder
    {
        OrderNo = await NextOrderNoAsync(),
        MaterialId = req.MaterialId,
        PlannedQty = req.PlannedQty,
        Priority = req.Priority,
        PlannedStart = req.PlannedStart,
        PlannedEnd = req.PlannedEnd,
        Remark = req.Remark,
        Source = req.Source,
        Status = WorkOrderStatus.Draft
    };

    _db.WorkOrders.Add(wo);
    await _db.SaveChangesAsync();
    return wo;
}

/// <summary>生成工单号：WO-yyyyMMdd-0001，按天流水</summary>
private async Task<string> NextOrderNoAsync()
{
    var prefix = $"WO-{DateTime.Today:yyyyMMdd}-";

    var last = await _db.WorkOrders
        .Where(w => w.OrderNo.StartsWith(prefix))
        .OrderByDescending(w => w.OrderNo)
        .Select(w => w.OrderNo)
        .FirstOrDefaultAsync();

    var seq = 1;
    if (last is not null && int.TryParse(last[prefix.Length..], out var n))
        seq = n + 1;

    return $"{prefix}{seq:D4}";
}

下达 = 状态机校验 + 工艺路线展开

这是 MES 里最有分量的一个方法。它把"模板"变成"任务"，之后工序就固化了：

/// <summary>
/// 下达工单 —— 一次状态流转 + 一次工艺路线展开。
///
/// 这是 MES 里最有分量的动作：下达之后工序就固化了。
/// 之后即使工艺路线模板被改动，这张工单也不受影响 ——
/// 因为工单存的是"展开后的快照"，不是"指向模板的引用"。
/// 这个设计避免了"改了工艺，历史工单全变样"的灾难。
/// </summary>
public async Task<WorkOrder> ReleaseAsync(int id)
{
    var wo = await _db.WorkOrders
        .Include(w => w.Operations)
        .FirstOrDefaultAsync(w => w.Id == id)
        ?? throw new InvalidOperationException($"工单 {id} 不存在");

    if (!CanTransit(wo.Status, WorkOrderStatus.Released))
        throw new InvalidOperationException(
            $"工单当前为「{StatusText(wo.Status)}」，不允许下达（只能直接作废）");

    if (wo.Operations.Count > 0)
        throw new InvalidOperationException("工单已展开过工序，不能重复下达");

    var steps = await _db.ProcessSteps
        .Where(s => s.MaterialId == wo.MaterialId)
        .OrderBy(s => s.SequenceNo)
        .ToListAsync();

    if (steps.Count == 0)
        throw new InvalidOperationException("该产品没有配置工艺路线，无法下达");

    foreach (var step in steps)
    {
        wo.Operations.Add(new WorkOrderOperation
        {
            SequenceNo = step.SequenceNo,
            Name = step.Name,
            WorkCenterId = step.WorkCenterId,
            PlannedQty = wo.PlannedQty,
            StandardMinutes = step.StandardMinutes,
            IsKeyProcess = step.IsKeyProcess,
            Status = OperationStatus.Pending
        });
    }

    wo.Status = WorkOrderStatus.Released;

    _db.WipTraces.Add(new WipTrace
    {
        WorkOrderId = wo.Id,
        Action = "下达",
        Qty = wo.PlannedQty,
        Detail = $"展开 {steps.Count} 道工序：" + string.Join(" → ", steps.Select(s => s.Name)),
        HappenedAt = DateTime.Now
    });

    await _db.SaveChangesAsync();
    return wo;
}

通用状态流转

除了下达，其余的状态变化（暂停、恢复、关闭、作废）走同一个入口：

/// <summary>通用状态流转：暂停 / 恢复 / 关闭 / 作废</summary>
public async Task<WorkOrder> TransitAsync(int id, WorkOrderStatus target, string? remark = null)
{
    var wo = await _db.WorkOrders.FindAsync(id)
        ?? throw new InvalidOperationException($"工单 {id} 不存在");

    if (!CanTransit(wo.Status, target))
    {
        // 错误信息里带上"当前允许流转到哪些状态"，
        // 用户看提示就知道下一步该干什么，而不是只看到一句"操作失败"
        var allowed = NextStates(wo.Status);
        var hint = allowed.Length == 0
            ? "它是终态，不能再流转"
            : "当前允许流转到：" + string.Join(" / ", allowed.Select(StatusText));

        throw new InvalidOperationException(
            $"不允许从「{StatusText(wo.Status)}」直接跳到「{StatusText(target)}」。{hint}");
    }

    var from = wo.Status;
    wo.Status = target;

    if (target is WorkOrderStatus.Closed)
        wo.ActualEnd ??= DateTime.Now;

    _db.WipTraces.Add(new WipTrace
    {
        WorkOrderId = wo.Id,
        Action = StatusText(target),
        Qty = wo.PlannedQty,
        Detail = $"由「{StatusText(from)}」流转而来" + (remark is null ? "" : $"：{remark}"),
        HappenedAt = DateTime.Now
    });

    await _db.SaveChangesAsync();
    return wo;
}

把合法流转告诉前端

加一个查询接口，前端就能自动生成操作按钮，不用在页面里硬编码状态判断：

/// <summary>查询当前工单可以流转到哪些状态（前端据此生成按钮）</summary>
[HttpGet("{id:int}/next-states")]
public async Task<ActionResult> NextStates(int id)
{
    var wo = await _db.WorkOrders.FindAsync(id);
    if (wo is null)
        return NotFound(new { message = $"工单 {id} 不存在" });

    var options = WorkOrderService.NextStates(wo.Status)
        .Select(s => new TransitionOptionDto((int)s, WorkOrderService.StatusText(s)));

    return Ok(options);
}

BASE=http://localhost:5100

# 建工单
curl -s -X POST $BASE/api/work-orders -H "Content-Type: application/json" \
  -d '{"materialId":8,"plannedQty":10,"priority":1}'

# 下达（假设返回的 id 是 5）
curl -s -X POST $BASE/api/work-orders/5/release

# 看工序展开结果
curl -s $BASE/api/work-orders/5 | grep -o '"name":"[^"]*"'

报工为什么这么重

表面上，报工就是"一线员工点一下提交"。但实际上它要：

完整实现

public async Task<ProductionReport> ReportAsync(ReportProductionRequest req)
{
    if (req.Qty <= 0 && req.ScrapQty <= 0)
        throw new InvalidOperationException("合格数和报废数不能同时为 0");

    // 报废必须写原因，否则质量分析时这些数据就是废的
    if (req.ScrapQty > 0 && string.IsNullOrWhiteSpace(req.ScrapReason))
        throw new InvalidOperationException("有报废数量时必须填写报废原因");

    var op = await _db.WorkOrderOperations
        .Include(o => o.WorkOrder)
        .FirstOrDefaultAsync(o => o.Id == req.OperationId)
        ?? throw new InvalidOperationException($"工序 {req.OperationId} 不存在");

    var wo = op.WorkOrder;

    // ---------- 校验 ① 工单状态允许生产 ----------
    if (wo.Status is not (WorkOrderStatus.Released or WorkOrderStatus.InProgress))
    {
        throw new InvalidOperationException(
            $"工单当前为「{WorkOrderService.StatusText(wo.Status)}」，不允许报工");
    }

    // ---------- 校验 ② 本工序未完工 ----------
    if (op.Status == OperationStatus.Completed)
        throw new InvalidOperationException($"工序「{op.Name}」已完工，不能再报工");

    // ---------- 校验 ③ 前道工序必须已完工（工序顺序不可跳过） ----------
    var prevUnfinished = await _db.WorkOrderOperations
        .Where(o => o.WorkOrderId == wo.Id
                 && o.SequenceNo < op.SequenceNo
                 && o.Status != OperationStatus.Completed)
        .OrderBy(o => o.SequenceNo)
        .Select(o => o.Name)
        .FirstOrDefaultAsync();

    if (prevUnfinished is not null)
        throw new InvalidOperationException($"前道工序「{prevUnfinished}」尚未完工，不能报工");

    // ---------- 校验 ④ 报工数量不能超出计划 ----------
    if (op.CompletedQty + req.Qty > op.PlannedQty)
    {
        throw new InvalidOperationException(
            $"工序「{op.Name}」计划 {op.PlannedQty}，已完工 {op.CompletedQty}，" +
            $"本次报 {req.Qty} 会超出上限");
    }

    // ---------- 校验 ⑤ 报工人必须是在职员工 ----------
    var employee = await _db.Employees.FindAsync(req.EmployeeId)
        ?? throw new InvalidOperationException($"员工 {req.EmployeeId} 不存在");

    if (!employee.IsActive)
        throw new InvalidOperationException($"员工「{employee.Name}」已离职，不能报工");

    var now = DateTime.Now;

    // ---------- 写入报工记录 ----------
    var report = new ProductionReport
    {
        WorkOrderOperationId = op.Id,
        EmployeeId = employee.Id,
        Qty = req.Qty,
        ScrapQty = req.ScrapQty,
        ScrapReason = req.ScrapReason,
        StartedAt = req.StartedAt,
        EndedAt = req.EndedAt,
        ReportedAt = now
    };
    _db.ProductionReports.Add(report);

    // ---------- 更新工序进度 ----------
    op.CompletedQty += req.Qty;
    op.ScrapQty += req.ScrapQty;

    if (op.Status == OperationStatus.Pending)
    {
        op.Status = OperationStatus.InProgress;
        op.StartedAt ??= req.StartedAt ?? now;
        wo.ActualStart ??= op.StartedAt;
    }

    if (op.CompletedQty >= op.PlannedQty)
    {
        op.Status = OperationStatus.Completed;
        op.FinishedAt = now;
    }

    // ---------- 推进工单状态 ----------
    if (wo.Status == WorkOrderStatus.Released)
        wo.Status = WorkOrderStatus.InProgress;

    wo.ScrapQty += req.ScrapQty;

    // 必须重新取全部工序来判断完工。
    // 这里 EF 的"同一实例"特性很关键：op 已经被追踪并修改过，
    // 所以下面读到的 allOps 里，当前工序已经是更新后的状态。
    var allOps = await _db.WorkOrderOperations
        .Where(o => o.WorkOrderId == wo.Id)
        .ToListAsync();

    if (allOps.All(o => o.Status == OperationStatus.Completed))
    {
        wo.Status = WorkOrderStatus.Completed;
        wo.ActualEnd = now;
        // 离散装配里，工单产出取最后一道工序的产出
        wo.CompletedQty = allOps.OrderBy(o => o.SequenceNo).Last().CompletedQty;
    }
    else
    {
        // 未完工时，工单完成数取"最后一道已开工工序"的产出。
        //
        // 为什么不用"最后一道已完工工序"？因为那样在前几道工序完工、
        // 关键工序还没开始时，看板会显示 0，看不出任何进展。
        var lastStarted = allOps
            .Where(o => o.Status != OperationStatus.Pending)
            .OrderBy(o => o.SequenceNo)
            .LastOrDefault();

        wo.CompletedQty = lastStarted?.CompletedQty ?? 0;
    }

    // ---------- 追加追溯记录（只增不改） ----------
    _db.WipTraces.Add(new WipTrace
    {
        WorkOrderId = wo.Id,
        WorkOrderOperationId = op.Id,
        Action = "报工",
        Qty = req.Qty,
        EmployeeId = employee.Id,
        WorkCenterId = op.WorkCenterId,
        Detail = req.ScrapQty > 0
            ? $"{employee.Name} 报工 {req.Qty}，报废 {req.ScrapQty}（{req.ScrapReason}）"
            : $"{employee.Name} 报工 {req.Qty}",
        HappenedAt = now
    });

    if (op.Status == OperationStatus.Completed)
    {
        _db.WipTraces.Add(new WipTrace
        {
            WorkOrderId = wo.Id,
            WorkOrderOperationId = op.Id,
            Action = "工序完工",
            Qty = op.CompletedQty,
            EmployeeId = employee.Id,
            WorkCenterId = op.WorkCenterId,
            Detail = $"「{op.Name}」累计完工 {op.CompletedQty}",
            HappenedAt = now
        });
    }

    // 一次 SaveChanges 就是一个隐式事务：
    // 报工记录、工序更新、工单状态、追溯记录要么全成，要么全不成。
    await _db.SaveChangesAsync();
    return report;
}

BASE=http://localhost:5100

# 越序报工 —— 应返回 400 并提示前道工序名
curl -s -w " [%{http_code}]\n" -X POST $BASE/api/production/report \
  -H "Content-Type: application/json" \
  -d '{"operationId":5,"employeeId":4,"qty":10}'
# 期望：{"message":"前道工序「总装」尚未完工，不能报工"} [400]

# 正常报工
curl -s -w " [%{http_code}]\n" -X POST $BASE/api/production/report \
  -H "Content-Type: application/json" \
  -d '{"operationId":4,"employeeId":1,"qty":15}'

追溯表的设计哲学

WipTrace 是整个 MES 里设计最简单、但要求最严格的一张表：

/// <summary>
/// 在制品流转记录 —— 追溯链的原始凭据。
///
/// 设计要点：**只增不改不删**。
/// 每一次关键动作（开工 / 报工 / 检验 / 完工）都往后追加一条，
/// 永远不回头修改历史。这样任何时候都能回答：
/// "这批货到底经历了什么、谁做的、什么时候做的"。
///
/// 这也是为什么 MES 的数据表会长得很快 —— 一辆车的追溯数据能有上百万行。
/// </summary>
public class WipTrace
{
    public int Id { get; set; }
    public int WorkOrderId { get; set; }
    public int? WorkOrderOperationId { get; set; }

    /// <summary>动作类型：下达 / 开工 / 报工 / 检验 / 完工 / 关闭</summary>
    public string Action { get; set; } = string.Empty;

    public decimal Qty { get; set; }
    public int? EmployeeId { get; set; }
    public int? WorkCenterId { get; set; }
    public string? Detail { get; set; }
    public DateTime HappenedAt { get; set; } = DateTime.Now;
}

查询追溯链

查询本身很简单——按时间排序即可。难点在于要把关联的员工名、工作中心名解析出来：

/// <summary>
/// 追溯链 —— 这张工单从头到尾发生过什么，按时间顺序列出。
/// 这就是客户问"这批货怎么做的"时，你要能立刻拿出来的东西。
/// </summary>
[HttpGet("{id:int}/trace")]
public async Task<ActionResult> Trace(int id)
{
    var exists = await _db.WorkOrders.AnyAsync(w => w.Id == id);
    if (!exists)
        return NotFound(new { message = $"工单 {id} 不存在" });

    var traces = await _db.WipTraces
        .Where(t => t.WorkOrderId == id)
        .OrderBy(t => t.HappenedAt)
        .ThenBy(t => t.Id)
        .ToListAsync();

    // 批量查名称再在内存里拼接 —— 避免在循环里逐条查库（N+1 查询问题）
    var empIds = traces.Where(t => t.EmployeeId.HasValue)
                       .Select(t => t.EmployeeId!.Value).Distinct().ToList();
    var wcIds = traces.Where(t => t.WorkCenterId.HasValue)
                      .Select(t => t.WorkCenterId!.Value).Distinct().ToList();

    var emps = await _db.Employees
        .Where(e => empIds.Contains(e.Id))
        .ToDictionaryAsync(e => e.Id, e => e.Name);
    var wcs = await _db.WorkCenters
        .Where(w => wcIds.Contains(w.Id))
        .ToDictionaryAsync(w => w.Id, w => w.Name);

    return Ok(traces.Select(t => new
    {
        t.Id,
        t.Action,
        t.Qty,
        employee = t.EmployeeId.HasValue && emps.TryGetValue(t.EmployeeId.Value, out var n) ? n : null,
        workCenter = t.WorkCenterId.HasValue && wcs.TryGetValue(t.WorkCenterId.Value, out var w) ? w : null,
        t.Detail,
        t.HappenedAt
    }));
}

// ❌ 错误示范：1000 条追溯 = 1001 次数据库往返
foreach (var t in traces)
{
    var name = (await _db.Employees.FindAsync(t.EmployeeId))?.Name;
}

追溯链长什么样

一张做完 4 道工序的工单，追溯链是这样的（真实输出）：

客户投诉时，把这张表打出来——什么时候、谁、在哪、做了多少、废了多少，一目了然。

curl -s http://localhost:5100/api/work-orders/1/trace

MES 的质量管控逻辑

传统做法是成品出来再检验。问题是：等发现不良时，可能已经废了一整批。 MES 的做法是把检验点前移到工序之间——关键工序不合格，整批不许流转。

检验实体

/// <summary>
/// 质量检验记录 —— 关键工序的"放行凭证"。
///
/// 规则很简单但很硬：关键工序没有一条合格的检验记录，
/// 就不允许往下一道工序流转。这条规则把质量问题拦在工序之间，
/// 而不是等成品出来才发现 —— 这就是 MES 相比事后检验的价值。
/// </summary>
public class QualityInspection
{
    public int Id { get; set; }

    public int WorkOrderOperationId { get; set; }
    public WorkOrderOperation Operation { get; set; } = null!;

    public int InspectorId { get; set; }
    public Employee Inspector { get; set; } = null!;

    public decimal InspectedQty { get; set; }   // 送检数
    public decimal PassedQty { get; set; }      // 合格数
    public decimal FailedQty { get; set; }      // 不合格数

    public InspectionResult Result { get; set; }

    /// <summary>不良类型，如"尺寸超差" / "外观刮伤"，用于后续质量分析</summary>
    public string? DefectType { get; set; }

    public string? Notes { get; set; }
    public DateTime InspectedAt { get; set; } = DateTime.Now;
}

public enum InspectionResult
{
    Passed = 0,      // 合格，允许流转
    Failed = 1,      // 不合格，必须返工或报废
    Concession = 2   // 让步接收（特采）：不合格但工艺同意放行，要留证据
}

检验实现

/// <summary>质量检验 —— 检验不改变工序进度，只留下判定结论</summary>
public async Task<QualityInspection> InspectAsync(InspectionRequest req)
{
    var op = await _db.WorkOrderOperations
        .Include(o => o.WorkOrder)
        .FirstOrDefaultAsync(o => o.Id == req.OperationId)
        ?? throw new InvalidOperationException($"工序 {req.OperationId} 不存在");

    if (op.CompletedQty <= 0)
        throw new InvalidOperationException($"工序「{op.Name}」还没有产出，无法检验");

    // 数量必须对得上，否则统计数据会自相矛盾
    if (req.PassedQty + req.FailedQty != req.InspectedQty)
        throw new InvalidOperationException("合格数 + 不合格数 必须等于送检数");

    var inspector = await _db.Employees.FindAsync(req.InspectorId)
        ?? throw new InvalidOperationException($"检验员 {req.InspectorId} 不存在");

    var inspection = new QualityInspection
    {
        WorkOrderOperationId = op.Id,
        InspectorId = inspector.Id,
        InspectedQty = req.InspectedQty,
        PassedQty = req.PassedQty,
        FailedQty = req.FailedQty,
        Result = req.Result,
        DefectType = req.DefectType,
        Notes = req.Notes,
        InspectedAt = DateTime.Now
    };

    _db.QualityInspections.Add(inspection);

    var resultText = req.Result switch
    {
        InspectionResult.Passed => "合格",
        InspectionResult.Failed => "不合格",
        InspectionResult.Concession => "让步接收",
        _ => "未知"
    };

    _db.WipTraces.Add(new WipTrace
    {
        WorkOrderId = op.WorkOrderId,
        WorkOrderOperationId = op.Id,
        Action = "检验",
        Qty = req.InspectedQty,
        EmployeeId = inspector.Id,
        WorkCenterId = op.WorkCenterId,
        Detail = $"「{op.Name}」{resultText}（合格 {req.PassedQty} / 不合格 {req.FailedQty}）"
                 + (req.DefectType is null ? "" : $"，不良类型：{req.DefectType}"),
        HappenedAt = DateTime.Now
    });

    await _db.SaveChangesAsync();
    return inspection;
}

# 1. 建工单 → 2. 下达（展开 5 道工序）→ 3. 逐道报工
# 4. 关键工序检验 → 5. 全部完工 → 6. 查追溯链
curl -s http://localhost:5100/api/work-orders          # 看状态流转
curl -s http://localhost:5100/api/dashboard/wip        # 看在制品
curl -s http://localhost:5100/api/work-orders/1/trace  # 看履历

OEE 与时间开动率

OEE（设备综合效率）由三个因子相乘：时间开动率 × 性能开动率 × 良品率。 MES 直接负责第一个——它最容易出问题，因为依赖准确的停机记录：

public class Equipment
{
    public int Id { get; set; }
    public string Code { get; set; } = string.Empty;
    public string Name { get; set; } = string.Empty;

    public int? WorkCenterId { get; set; }
    public WorkCenter? WorkCenter { get; set; }

    public EquipmentStatus Status { get; set; } = EquipmentStatus.Running;

    /// <summary>累计运行分钟数（用于算时间开动率）</summary>
    public int RunningMinutes { get; set; }

    /// <summary>累计停机分钟数</summary>
    public int DownMinutes { get; set; }

    /// <summary>最近一次点检时间</summary>
    public DateTime? LastCheckAt { get; set; }
}

public enum EquipmentStatus
{
    Running = 0,      // 运行中
    Idle = 1,         // 空闲待机（有产能但没排活）
    Down = 2,         // 故障停机
    Maintenance = 3   // 保养 / 维修中（计划内）
}

点检：把事故拦在开工之前

/// <summary>
/// 设备点检 —— 不合格会自动把设备置为故障停机。
/// 这条规则把"设备带病运行"挡在开工之前，避免批量质量事故。
/// </summary>
[HttpPost("{id:int}/check")]
public async Task<ActionResult> Check(int id, EquipmentCheckRequest req)
{
    var eq = await _db.Equipments.FindAsync(id);
    if (eq is null)
        return NotFound(new { message = $"设备 {id} 不存在" });

    var checker = await _db.Employees.FindAsync(req.CheckedById);
    if (checker is null)
        return NotFound(new { message = $"员工 {req.CheckedById} 不存在" });

    var now = DateTime.Now;

    _db.EquipmentChecks.Add(new EquipmentCheck
    {
        EquipmentId = eq.Id,
        CheckedById = checker.Id,
        IsPassed = req.IsPassed,
        Result = req.Result,
        CheckedAt = now
    });

    eq.LastCheckAt = now;

    // 点检不合格 —— 直接锁死设备，不等人工处理
    if (!req.IsPassed)
        eq.Status = EquipmentStatus.Down;

    await _db.SaveChangesAsync();

    return Ok(new
    {
        message = req.IsPassed ? "点检通过，设备可正常使用" : "点检不合格，设备已置为故障停机",
        equipmentStatus = StatusText(eq.Status)
    });
}

开动率计算与除零防护

return Ok(list.Select(e =>
{
    var total = e.RunningMinutes + e.DownMinutes;
    return new
    {
        e.Id, e.Code, e.Name,
        workCenter = e.WorkCenter?.Name,
        status = (int)e.Status,
        statusText = StatusText(e.Status),
        e.RunningMinutes,
        e.DownMinutes,
        // 开动率：没有记录时给 100，避免除零 ——
        // 新设备第一天没有任何运行记录，除零会让整个接口 500
        availability = total == 0 ? 100m : Math.Round(e.RunningMinutes * 100m / total, 2),
        e.LastCheckAt
    };
}));

看板要回答的五个问题

总览接口实现

/// <summary>
/// 生产看板接口 —— 把散落的单据聚合成管理者一眼能看懂的数字。
///
/// 实现上有意做了"先取数、再内存计算"：
/// 演示数据量很小，这样做避免 SQLite 的 decimal 聚合坑，
/// 也让计算逻辑能直接在调试器里单步看懂。
/// 真实项目里数据量大，应该改成数据库端聚合 + 预计算。
/// </summary>
[HttpGet("summary")]
public async Task<ActionResult<DashboardSummaryDto>> Summary()
{
    var orders = await _db.WorkOrders
        .Include(w => w.Material)
        .ToListAsync();

    var activeStatuses = new[]
    {
        WorkOrderStatus.Released,
        WorkOrderStatus.InProgress,
        WorkOrderStatus.OnHold
    };

    var active = orders.Where(o => activeStatuses.Contains(o.Status)).ToList();
    var completed = orders.Where(o =>
        o.Status is WorkOrderStatus.Completed or WorkOrderStatus.Closed).ToList();

    var totalPlanned = orders.Sum(o => o.PlannedQty);
    var totalCompleted = orders.Sum(o => o.CompletedQty);
    var totalScrap = orders.Sum(o => o.ScrapQty);

    // 报废率 = 报废 / (完工 + 报废)。注意分母不能只用完工数，
    // 否则"全部报废"的情况下分母为 0，指标会失真
    var scrapBase = totalCompleted + totalScrap;
    var scrapRate = scrapBase == 0 ? 0 : Math.Round(totalScrap * 100m / scrapBase, 2);

    var equipments = await _db.Equipments.ToListAsync();

    var statusDistribution = Enum.GetValues<WorkOrderStatus>()
        .Select(s => new StatusCountDto(
            (int)s,
            WorkOrderService.StatusText(s),
            orders.Count(o => o.Status == s)))
        .Where(x => x.Count > 0)
        .ToList();

    return Ok(new DashboardSummaryDto(
        TotalWorkOrders: orders.Count,
        ActiveWorkOrders: active.Count,
        CompletedWorkOrders: completed.Count,
        TotalPlannedQty: totalPlanned,
        TotalCompletedQty: totalCompleted,
        TotalScrapQty: totalScrap,
        ScrapRate: scrapRate,
        OnTimeRate: CalcOnTimeRate(completed),
        EquipmentTotal: equipments.Count,
        EquipmentRunning: equipments.Count(e => e.Status == EquipmentStatus.Running),
        EquipmentDown: equipments.Count(e => e.Status == EquipmentStatus.Down),
        PendingInspections: await _db.WorkOrderOperations.CountAsync(o =>
            o.IsKeyProcess && o.Status == OperationStatus.Completed),
        StatusDistribution: statusDistribution,
        ActiveList: active.OrderBy(o => o.Priority).Select(ToListItem).ToList()));
}

/// <summary>准时交付率 —— 只有同时有计划交期和实际完工时间的工单才参与统计</summary>
private static decimal CalcOnTimeRate(List<WorkOrder> completed)
{
    var withPlan = completed.Where(o => o.PlannedEnd.HasValue && o.ActualEnd.HasValue).ToList();
    if (withPlan.Count == 0) return 100m;   // 除零防护

    var onTime = withPlan.Count(o => o.ActualEnd!.Value <= o.PlannedEnd!.Value);
    return Math.Round(onTime * 100m / withPlan.Count, 2);
}

质量统计：找到改进的着力点

/// <summary>质量统计 —— 按不良类型汇总，找质量改进的着力点</summary>
[HttpGet("quality")]
public async Task<ActionResult> Quality()
{
    var inspections = await _db.QualityInspections.ToListAsync();

    var inspected = inspections.Sum(i => i.InspectedQty);
    var passed = inspections.Sum(i => i.PassedQty);
    var failed = inspections.Sum(i => i.FailedQty);

    // 按不良类型分组 —— 这一项才是真正能指导改进的：
    // 如果 80% 的不良都是"装配划伤"，那改进装配工装比什么都有效
    var byDefect = inspections
        .Where(i => !string.IsNullOrWhiteSpace(i.DefectType))
        .GroupBy(i => i.DefectType!)
        .Select(g => new { defectType = g.Key, count = g.Count(), qty = g.Sum(i => i.FailedQty) })
        .OrderByDescending(x => x.qty)
        .ToList();

    return Ok(new
    {
        totalInspections = inspections.Count,
        inspectedQty = inspected,
        passedQty = passed,
        failedQty = failed,
        passRate = inspected == 0 ? 100m : Math.Round(passed * 100m / inspected, 2),
        byDefectType = byDefect
    });
}

curl -s http://localhost:5100/api/dashboard/summary
curl -s http://localhost:5100/api/dashboard/wip
curl -s http://localhost:5100/api/dashboard/quality

为什么前端不用框架

本教程的前端是单文件原生 JS，不是偷懒，是有意的选择：

MES 的车间界面通常就是几张表格加几个按钮，原生 JS 完全够用。 等页面超过 10 个再考虑引入框架——那时你已经清楚自己需要什么了。

让 API 托管静态页面

// 托管 wwwroot 下的车间操作界面（index.html）。
// UseDefaultFiles 必须在 UseStaticFiles 之前，否则访问 "/" 不会落到 index.html。
app.UseDefaultFiles();
app.UseStaticFiles();

前端的核心封装

整个前端最关键的是这两个函数——一个统一的请求封装和一个提示条：

/* ---------- 统一请求封装：把后端的 { message } 错误自动抛出来 ---------- */
async function api(path, options) {
  const res = await fetch(API + path, options);
  const text = await res.text();

  let data = null;
  try { data = text ? JSON.parse(text) : null; } catch (e) { data = text; }

  // 关键：后端返回 400 时带的是 { message: "前道工序「总装」尚未完工" }，
  // 这里直接抛出，调用方 catch 之后 toast 出来 ——
  // 业务规则的提示语由后端决定，前端不需要翻译错误码
  if (!res.ok) throw new Error((data && data.message) || ("请求失败 " + res.status));
  return data;
}

function toast(msg, ok) {
  const t = document.getElementById("toast");
  t.textContent = msg;
  t.className = "toast show " + (ok ? "ok" : "err");
  clearTimeout(t._tid);
  t._tid = setTimeout(() => t.className = "toast", 3600);
}

界面功能一览

curl -s -o /dev/null -w '首页 %{http_code}\n' http://localhost:5100/
curl -s -o /dev/null -w 'Scalar %{http_code}\n' http://localhost:5100/scalar/v1

为什么不能到处 try-catch

第 12 课的报工方法里有 5 处 throw new InvalidOperationException(...)。 如果每个控制器都要捕获再转成 400，代码会变成这样：

// ❌ 每个方法都要写一遍，重复且容易漏
try { await _service.ReportAsync(req); }
catch (InvalidOperationException ex) { return BadRequest(new { message = ex.Message }); }
catch (Exception ex) { return StatusCode(500, new { message = ex.Message }); }

更好的做法是在管道上装一个全局处理器，一次性解决：

// ---------- 全局异常处理 ----------
// 业务规则冲突（比如"前道工序没完工不能报工"）抛的是 InvalidOperationException，
// 这类应该返回 400 并带上人话提示；其他异常返回 500。
// 有了这层，Controller 里就不用到处写 try-catch。
app.UseExceptionHandler(handler =>
{
    handler.Run(async context =>
    {
        var feature = context.Features.Get<IExceptionHandlerFeature>();
        var ex = feature?.Error;

        var isBusinessError = ex is InvalidOperationException;

        context.Response.StatusCode = isBusinessError
            ? StatusCodes.Status400BadRequest
            : StatusCodes.Status500InternalServerError;
        context.Response.ContentType = "application/json; charset=utf-8";

        await context.Response.WriteAsJsonAsync(new
        {
            message = isBusinessError
                ? ex!.Message
                : "服务器内部错误：" + ex?.Message
        });
    });
});

种子数据：让系统一启动就能看

空的 MES 什么都验证不了。种子数据要造出一条完整链路：

public static class SeedData
{
    public static void Initialize(MesDbContext db)
    {
        // 幂等：已经有物料说明灌过了，直接返回。
        // 少了这一句，每次重启服务数据都会翻倍。
        if (db.Materials.Any()) return;

        var today = DateTime.Today;

        // ==================== 工作中心 ====================
        var wcCut  = new WorkCenter { Code = "WC-CUT",  Name = "下料区",       Type = "手工工位", DailyMinutes = 480 };
        var wcCnc  = new WorkCenter { Code = "WC-CNC",  Name = "数控加工中心", Type = "单机",     DailyMinutes = 720 };
        var wcWind = new WorkCenter { Code = "WC-WIND", Name = "绕线工位",     Type = "手工工位", DailyMinutes = 480 };
        var wcAsm  = new WorkCenter { Code = "WC-ASM",  Name = "总装线 A",     Type = "产线",     DailyMinutes = 480 };
        var wcQc   = new WorkCenter { Code = "WC-QC",   Name = "检验站",       Type = "手工工位", DailyMinutes = 480 };
        db.WorkCenters.AddRange(wcCut, wcCnc, wcWind, wcAsm, wcQc);

        // ==================== 员工 ====================
        var eZhang = new Employee { Code = "E001", Name = "张伟", Team = "一班",   Skill = "钳工" };
        var eLi    = new Employee { Code = "E002", Name = "李娜", Team = "一班",   Skill = "数控操作" };
        var eWang  = new Employee { Code = "E003", Name = "王强", Team = "二班",   Skill = "绕线" };
        var eZhao  = new Employee { Code = "E004", Name = "赵敏", Team = "检验组", Skill = "质检" };
        var eChen  = new Employee { Code = "E005", Name = "陈军", Team = "设备组", Skill = "设备维护" };
        db.Employees.AddRange(eZhang, eLi, eWang, eZhao, eChen);

        db.SaveChanges();   // 先落库拿到 Id，后面要用

        // ==================== 物料（三层结构） ====================
        // 原材料
        var mSteel   = new Material { Code = "RM-STEEL",   Name = "冷轧钢板",   Spec = "1.5mm SPCC",  Unit = "kg", Type = MaterialType.RawMaterial };
        var mWire    = new Material { Code = "RM-WIRE",    Name = "漆包铜线",   Spec = "Φ0.5mm",      Unit = "米", Type = MaterialType.RawMaterial };
        var mBearing = new Material { Code = "RM-BEARING", Name = "深沟球轴承", Spec = "6203-2RS",    Unit = "个", Type = MaterialType.RawMaterial };
        var mScrew   = new Material { Code = "RM-M6X20",   Name = "内六角螺栓", Spec = "M6x20 不锈钢", Unit = "个", Type = MaterialType.RawMaterial };

        // 半成品
        var mHousing = new Material { Code = "SF-HOUSING", Name = "电机壳体", Spec = "LG-220 铝壳", Unit = "个", Type = MaterialType.SemiFinished };
        var mStator  = new Material { Code = "SF-STATOR",  Name = "定子总成", Spec = "220V 绕组",   Unit = "个", Type = MaterialType.SemiFinished };
        var mRotor   = new Material { Code = "SF-ROTOR",   Name = "转子总成", Spec = "Φ48 轴芯",    Unit = "个", Type = MaterialType.SemiFinished };

        // 成品
        var mProduct = new Material { Code = "FG-MOTOR-A", Name = "直流电机 A 型", Spec = "220V / 1.5kW", Unit = "台", Type = MaterialType.Finished };

        db.Materials.AddRange(mSteel, mWire, mBearing, mScrew, mHousing, mStator, mRotor, mProduct);
        db.SaveChanges();

        // ==================== BOM（注意损耗率） ====================
        db.BomItems.AddRange(
            new BomItem { ParentMaterialId = mHousing.Id, ChildMaterialId = mSteel.Id,   Quantity = 1.2m, Position = "壳体主体", LossRate = 5 },
            new BomItem { ParentMaterialId = mStator.Id,  ChildMaterialId = mWire.Id,    Quantity = 85m,  Position = "绕组",     LossRate = 3 },
            new BomItem { ParentMaterialId = mStator.Id,  ChildMaterialId = mSteel.Id,   Quantity = 0.3m, Position = "铁芯",     LossRate = 5 },
            new BomItem { ParentMaterialId = mRotor.Id,   ChildMaterialId = mSteel.Id,   Quantity = 0.5m, Position = "轴芯",     LossRate = 5 },
            new BomItem { ParentMaterialId = mRotor.Id,   ChildMaterialId = mBearing.Id, Quantity = 1m,   Position = "后端轴承", LossRate = 0 },
            new BomItem { ParentMaterialId = mProduct.Id, ChildMaterialId = mHousing.Id, Quantity = 1m,   Position = "外壳",     LossRate = 0 },
            new BomItem { ParentMaterialId = mProduct.Id, ChildMaterialId = mStator.Id,  Quantity = 1m,   Position = "内芯",     LossRate = 0 },
            new BomItem { ParentMaterialId = mProduct.Id, ChildMaterialId = mRotor.Id,   Quantity = 1m,   Position = "内芯",     LossRate = 0 },
            new BomItem { ParentMaterialId = mProduct.Id, ChildMaterialId = mBearing.Id, Quantity = 1m,   Position = "前端盖",   LossRate = 0 },
            new BomItem { ParentMaterialId = mProduct.Id, ChildMaterialId = mScrew.Id,   Quantity = 8m,   Position = "端盖固定", LossRate = 2 }
        );
        db.SaveChanges();

        // ==================== 工艺路线 ====================
        db.ProcessSteps.AddRange(
            new ProcessStep { MaterialId = mProduct.Id, SequenceNo = 10, Name = "下料",     WorkCenterId = wcCut.Id,  StandardMinutes = 5 },
            new ProcessStep { MaterialId = mProduct.Id, SequenceNo = 20, Name = "机加工",   WorkCenterId = wcCnc.Id,  StandardMinutes = 20 },
            new ProcessStep { MaterialId = mProduct.Id, SequenceNo = 30, Name = "绕线",     WorkCenterId = wcWind.Id, StandardMinutes = 15 },
            new ProcessStep { MaterialId = mProduct.Id, SequenceNo = 40, Name = "总装",     WorkCenterId = wcAsm.Id,  StandardMinutes = 25, IsKeyProcess = true },
            new ProcessStep { MaterialId = mProduct.Id, SequenceNo = 50, Name = "成品检验", WorkCenterId = wcQc.Id,   StandardMinutes = 10, IsKeyProcess = true }
        );
        db.SaveChanges();

        // ==================== 造 4 张不同状态的工单 ====================
        // 工单 1：生产中（下料/机加工/绕线已完工，总装做到 35 台废 3）
        // 工单 2：已下达未开工
        // 工单 3：已完工（含检验记录，用于看板和追溯演示）
        // 工单 4：草稿（还没展开工序）
        //
        // 这样一启动，看板上四种状态都有数据，所有接口都能验出东西来。
        // ...（完整代码见源码文件 Data/SeedData.cs）
    }
}

发布与部署

# 发布（框架依赖模式，服务器需装 .NET 10 运行时）
dotnet publish -c Release -o ./publish

# 上传到服务器
scp -r ./publish/* root@your-server:/var/www/mes/api/

# 服务端创建 systemd 服务
cat > /etc/systemd/system/mes-api.service <<'EOF'
[Unit]
Description=MES API
After=network.target

[Service]
WorkingDirectory=/var/www/mes/api
ExecStart=/usr/bin/dotnet /var/www/mes/api/Mes.Api.dll
Restart=always
RestartSec=10
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=ASPNETCORE_URLS=http://127.0.0.1:5100

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now mes-api

Nginx 反向代理

server {
    listen 443 ssl http2;
    server_name mes.your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/mes.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mes.your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:5100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

接下来做什么

到这里，你手上是一个能完整跑通执行闭环的 MES 内核： 工单能下达、工序能展开、报工能推进状态、追溯能查到源头。 但它还只是一台"记录仪"——它不告诉你该怎么排产、料够不够、设备好不好、这个决定是谁做的。

下面 11 课就是把这台记录仪变成决策系统。这不是"以后再说"的清单， 而是紧接着就要动手做的：

这 19 课你已经掌握的东西

走完前 19 课，你手上不只是一套代码，而是这些可以迁移到任何制造业项目的能力：

• 状态机建模——把业务规则集中成一份定义，而不是散落在各处的 if-else
• 模板与实例分离——历史数据不被规则变更追溯性改写
• 事务边界的直觉——一次 SaveChanges 就是一个原子操作，不多不少
• 追溯系统的设计——只增不改的表、不建外键的账本
• 指标口径的敏感性——算错的分母比没有指标更危险
• 分层纪律——Controller 管 HTTP，Service 管业务，DbContext 管表结构

这些东西换一个行业（电子、汽车、医药）依然成立，因为它们是制造执行这件事本身的规律， 不是某个框架的用法。

排 = 决定什么时候做；派 = 决定谁来做

这两个字经常被混用，但它们是两件事：

我们先做排产——因为不知道"什么时候"，就没法判断"派给谁合不合适"。

三种策略，差别在"承不承认产能上限"

真实的 APS（高级排程）会复杂得多：换型时间、模具共享、班次轮换、多目标优化。 但有限产能顺排是所有这些算法的地基——先把这一层吃透， 以后加约束只是在同一个骨架上挂东西。

核心代码

/// <summary>上班时间：早 8 点。真实的班次表应该是配置，这里先固定</summary>
private static readonly TimeSpan ShiftStart = TimeSpan.FromHours(8);

/// <summary>
/// 顺排：把这个工作中心最后一个任务的结束时间当作起算点，再往后排本次任务。
/// 如果起算点已经过去（比如夜里），就从现在开始。
/// </summary>
private async Task<(DateTime Start, DateTime End)> PlanAsync(int workCenterId, decimal minutes)
{
    var lastEnd = await _db.OperationAssignments
        .Include(a => a.Operation)
        .Where(a => a.Operation.WorkCenterId == workCenterId
                    && a.Status != AssignmentStatus.Cancelled)
        .OrderByDescending(a => a.PlannedEnd)
        .Select(a => (DateTime?)a.PlannedEnd)
        .FirstOrDefaultAsync();

    var daily = await DailyMinutesAsync(workCenterId);

    // 起算点：已有任务的终点，但不能早于现在（不能排到过去）
    var baseline = lastEnd is null || lastEnd < DateTime.Now ? DateTime.Now : lastEnd.Value;

    var start = AlignToShift(baseline, daily);
    var end = AddWorkingMinutes(start, minutes, daily);

    return (start, end);
}

/// <summary>把时间对齐到上班时间：太早就推到 8 点，下班后就推到次日 8 点</summary>
private static DateTime AlignToShift(DateTime t, int dailyMinutes)
{
    var shiftStart = t.Date + ShiftStart;
    var shiftEnd = shiftStart.AddMinutes(dailyMinutes);

    if (t < shiftStart) return shiftStart;      // 还没上班
    if (t >= shiftEnd) return shiftStart.AddDays(1);   // 已经下班
    return t;                                   // 正在上班
}

/// <summary>
/// 从 start 开始累加工作时长，跳过下班时间逐日顺延。
/// 这是"有限产能"的核心：一天只有 DailyMinutes 分钟，排满了就得等明天。
/// </summary>
private static DateTime AddWorkingMinutes(DateTime start, decimal minutes, int dailyMinutes)
{
    var remaining = minutes;
    var cursor = start;

    while (true)
    {
        var shiftEnd = cursor.Date + ShiftStart + TimeSpan.FromMinutes(dailyMinutes);

        // 已经过了下班时间，直接跳到明天上班
        if (cursor >= shiftEnd)
        {
            cursor = cursor.Date.AddDays(1) + ShiftStart;
            continue;
        }

        var available = (decimal)(shiftEnd - cursor).TotalMinutes;

        // 今天剩下的时间够用，直接算完
        if (remaining <= available)
            return cursor.AddMinutes((double)remaining);

        // 今天不够，扣掉今天的产能，明天接着做
        remaining -= available;
        cursor = cursor.Date.AddDays(1) + ShiftStart;
    }
}

三个必须注意的细节

1. 不能排到过去。当某个工作中心的任务都已完成（lastEnd 是三天前）， 起算点必须回落到 DateTime.Now，否则会生成一张"从上周开始干"的派工单。
2. 下班时间的边界要一致。AlignToShift 用 >= 判断下班，AddWorkingMinutes 也用 >= 判断。两个地方不一致就会出现在 17:00 整被排进今天、 然后瞬间跳到明天的诡异结果。
3. 算法必须能终止。这个 while(true) 靠 "每天都往前推一天"来保证终止。如果 dailyMinutes 为 0 或负数， 就会无限循环——所以 DailyMinutesAsync 里兜了一层默认值 480。

# 1. 看某个工作中心当前的排产情况
curl -s "http://localhost:5100/api/scheduling/gantt?from=2026-10-14T08:00:00&to=2026-10-21T08:00:00"

# 2. 新派一个任务，观察返回的计划时间
curl -s -X POST http://localhost:5100/api/scheduling/assignments \
  -H "Content-Type: application/json" \
  -d '{"operationId":7,"employeeId":2,"qty":5}'

为什么派工必须是一张独立的表

最省事的做法是在 WorkOrderOperation 上加两个字段： AssignedEmployeeId、AssignedQty。小作坊确实这么干。

但现实里，50 台电机的总装经常拆给 3 个人并行做。一对一的字段装不下， 你就得加 AssignedEmployeeId2、AssignedEmployeeId3…… 到第四个人的时候这段代码就该重写了。

判据很简单：当"一个 X 可以对应多个 Y"时，Y 就该有自己的表。

public class OperationAssignment
{
    public int Id { get; set; }
    public string AssignmentNo { get; set; } = string.Empty;   // AS-20261014-0001

    public int WorkOrderOperationId { get; set; }
    public WorkOrderOperation Operation { get; set; } = null!;

    public int EmployeeId { get; set; }
    public Employee Employee { get; set; } = null!;

    public int? EquipmentId { get; set; }          // 手工工位可以为空
    public Equipment? Equipment { get; set; }

    public decimal AssignedQty { get; set; }        // 可以小于工序计划数，余量另派

    public DateTime PlannedStart { get; set; }      // 排产算出来的
    public DateTime PlannedEnd { get; set; }

    public DateTime? ActualStart { get; set; }      // 第一次报工时写入
    public DateTime? ActualEnd { get; set; }

    public AssignmentStatus Status { get; set; } = AssignmentStatus.Assigned;

    public string? Remark { get; set; }
    public DateTime CreatedAt { get; set; } = DateTime.Now;

    /// <summary>是否超期未完成 —— 计划完工时间已过、但还没完工</summary>
    public bool IsOverdue =>
        Status != AssignmentStatus.Finished && DateTime.Now > PlannedEnd;
}

public enum AssignmentStatus
{
    Assigned = 0,   // 已派工，还没开工
    Started = 1,    // 已开工
    Finished = 2,   // 已完工
    Cancelled = 9   // 已撤回（派错了）
}

派工的三条硬校验

// ① 不能超派。已派数量 + 本次 > 工序计划数，会让车间出现
//    "两个人都以为这 10 件是自己的"这种最典型的现场混乱。
var alreadyAssigned = op.Assignments
    .Where(a => a.Status != AssignmentStatus.Cancelled)
    .Sum(a => a.AssignedQty);

if (alreadyAssigned + req.Qty > op.PlannedQty)
    throw new InvalidOperationException(
        $"超派：工序计划 {op.PlannedQty} 件，已派 {alreadyAssigned} 件，" +
        $"本次最多还能派 {op.PlannedQty - alreadyAssigned} 件");

// ② 员工必须在职。离职员工的名字出现在今天的派工单上，
//    说明这个系统还没有真的被当回事。
if (!employee.IsActive)
    throw new InvalidOperationException($"员工「{employee.Name}」已离职（停用），不能派工");

// ③ 故障停机的设备不能派工 —— 排了也干不了。
//    这条规则把"设备维修"和"生产安排"两个模块真正连了起来：
//    点检不合格 → 设备状态置 Down → 派工被拒 → 排产员不得不改计划。
if (eq.Status == EquipmentStatus.Down)
    throw new InvalidOperationException($"设备「{eq.Name}」处于故障停机状态，不能派工");

工作中心负荷：排产员每天看的第一张表

负荷率的算法很朴素，但要选对分母：

// 负荷率 = 已派工未完工的产能 ÷ 单日可用产能
var minutes = mine.Sum(a => a.Operation.StandardMinutes * a.AssignedQty);
var load = wc.DailyMinutes <= 0 ? 0 : Math.Round(minutes / wc.DailyMinutes * 100, 1);

// 判定分档 —— 分档的意义是让数字能直接触发动作
// 超负荷   → 今天做不完，要么加班要么调走
// 接近饱和 → 还有余量，但别再往里塞急单
// 正常     → 可以接活
// 空闲     → 产能浪费，或者排产有盲区
static string LevelOf(decimal load) => load switch
{
    >= 100 => "超负荷",
    >= 80 => "接近饱和",
    >= 40 => "正常",
    _ => "空闲"
};

注意只统计"已派但还没完工"的任务。已经做完的活不占未来产能—— 如果把历史任务也算进去，负荷率会随着生产推进一路涨到几百，这个指标就废了。

BASE=http://localhost:5100

# ① 超派 —— 工序 4（总装）已派满 50 件，再派 10 件应被拒绝
curl -s -X POST $BASE/api/scheduling/assignments -H "Content-Type: application/json" \
  -d '{"operationId":4,"employeeId":1,"qty":10}'
# 期望：{"message":"超派：工序计划 50 件，已派 50 件，本次最多还能派 0 件"}

# ② 故障设备 —— 综合测试台点检不合格已置为 Down
curl -s -X POST $BASE/api/scheduling/assignments -H "Content-Type: application/json" \
  -d '{"operationId":26,"employeeId":2,"equipmentId":4,"qty":5}'
# 期望：{"message":"设备「综合测试台」处于故障停机状态，不能派工"}

# ③ 看负荷 —— 总装线应该是最高的
curl -s $BASE/api/scheduling/load

MRP 的难点不在算法，在细节

展开 BOM 的递归逻辑只有十几行，但真做起来会踩到四类坑。先看正确的算法：

/// <summary>BOM 最大展开层级 —— 超过这个深度基本可以断定是配置错误</summary>
private const int MaxLevel = 12;

// 累计器：物料 Id → 汇总需求
var accumulated = new Dictionary<int, Accum>();

// 从产品开始展开。path 记录"当前这条路径上已经走过哪些物料"，
// 里面预置了产品本身，防止 A 用 B、B 又用回 A 的死循环。
Explore(wo.MaterialId, 1, wo.PlannedQty, new HashSet<int> { wo.MaterialId });

void Explore(int parentMaterialId, int level, decimal parentQty, HashSet<int> path)
{
    if (level > MaxLevel) return;
    if (!byParent.TryGetValue(parentMaterialId, out var children)) return;

    foreach (var line in children)
    {
        // 环路保护：这个子件已经在当前路径上，再展开就是死循环
        if (path.Contains(line.ChildMaterialId)) continue;

        // 毛需求 = 上层数量 × 本行单位用量 × (1 + 损耗率)
        var gross = parentQty * line.Quantity * (1 + line.LossRate / 100m);

        if (accumulated.TryGetValue(line.ChildMaterialId, out var exist))
        {
            // 同一个料被多个父件用到（比如钢板既在壳体又在定子），需求要相加
            exist.Gross += gross;
            exist.Level = Math.Min(exist.Level, level);
        }
        else
        {
            accumulated[line.ChildMaterialId] = new Accum
            {
                Gross = gross, Level = level, Material = line.ChildMaterial
            };
        }

        // 递归到下一层，把当前物料加进路径
        var childPath = new HashSet<int>(path) { line.ChildMaterialId };
        Explore(line.ChildMaterialId, level + 1, gross, childPath);
    }
}

四个坑，一个比一个隐蔽

壳体路径  30 × 1.2 × 1.05 = 37.80
定子路径  30 × 0.3 × 1.05 =  9.45
转子路径  30 × 0.5 × 1.05 = 15.75
                       合计 = 63.00 kg

净需求：从"要多少"到"还差多少"

// 毛需求 = 累计用量（含损耗）
// 净需求 = max(0, 毛需求 - 可用库存)
var net = Math.Max(0, acc.Gross - m.OnHandQty);

# 对工单 2（30 台电机）做 MRP 展开
curl -s -X POST http://localhost:5100/api/mrp/2/calculate | python -m json.tool

curl -s -X POST http://localhost:5100/api/mrp/batch \
  -H "Content-Type: application/json" -d '[1,2,3,4]'

检验和不良品，是两件事

把它们合成一张表的后果是：检验员判完"不合格"就走了， "谁来处理、怎么处理、原因是什么"永远没人填—— 因为那条记录在检验员眼里已经完结了。

public class DefectRecord
{
    public int Id { get; set; }
    public string DefectNo { get; set; } = string.Empty;      // DF-20261014-0001

    public int WorkOrderId { get; set; }
    public WorkOrder WorkOrder { get; set; } = null!;
    public int WorkOrderOperationId { get; set; }
    public WorkOrderOperation Operation { get; set; } = null!;
    public int MaterialId { get; set; }
    public Material Material { get; set; } = null!;

    public decimal Qty { get; set; }
    public string DefectType { get; set; } = string.Empty;

    public DefectDisposition Disposition { get; set; }        // 返工/返修/报废/让步接收
    public DefectStatus Status { get; set; } = DefectStatus.Open;

    public int ReportedById { get; set; }                     // 发现人
    public Employee ReportedBy { get; set; } = null!;
    public int? HandlerId { get; set; }                       // 处置人
    public Employee? Handler { get; set; }

    public string? RootCause { get; set; }                    // 根因（5Why 的结论）
    public string? CounterMeasure { get; set; }               // 纠正措施

    public DateTime FoundAt { get; set; } = DateTime.Now;
    public DateTime? ClosedAt { get; set; }
}

/// <summary>处置方式 —— 决定这批不良品的去向，也决定它算不算报废</summary>
public enum DefectDisposition
{
    Rework = 0,       // 返工：拆开重做，回原工序
    Repair = 1,       // 返修：修补后可用，不必回原工序
    Scrap = 2,        // 报废：彻底损失，计入报废率
    Concession = 3    // 让步接收：不合格但放行，必须留下审批证据
}

public enum DefectStatus { Open = 0, Handling = 1, Closed = 2 }

关闭的硬闸：不填根因就不许关

if (d.Status == DefectStatus.Closed)
    throw new InvalidOperationException($"{d.DefectNo} 已关闭，不能重复关闭");

if (string.IsNullOrWhiteSpace(req.RootCause))
    throw new InvalidOperationException("关闭前必须填写根因分析（RootCause）");

if (string.IsNullOrWhiteSpace(req.CounterMeasure))
    throw new InvalidOperationException("关闭前必须填写纠正措施（CounterMeasure）");

不良品登记必须进追溯链

// 不良品登记必须进追溯链 —— 客户投诉时这条记录是关键证据
_db.WipTraces.Add(new WipTrace
{
    WorkOrderId = op.WorkOrderId,
    WorkOrderOperationId = op.Id,
    Action = "不良登记",
    Qty = req.Qty,
    EmployeeId = reporterId,
    WorkCenterId = op.WorkCenterId,
    Detail = $"「{op.Name}」{req.DefectType} × {req.Qty}，" +
             $"处置方式：{DispositionText(req.Disposition)}",
    HappenedAt = DateTime.Now
});

注意这里写的是 WipTrace 而不是只写 DefectRecord。 两者服务的场景不同：追溯链是"按时间顺序看这批货经历了什么"， 不良品表是"按流程状态看待办事项"。同一件事在两边都留痕，才能既回答客户又驱动内部处理。

BASE=http://localhost:5100

# ① 登记一条不良品（工序 1 下料，板材划伤 2 件，处置=返工）
curl -s -X POST $BASE/api/defects -H "Content-Type: application/json" \
  -d '{"operationId":1,"qty":2,"defectType":"板材划伤","disposition":0,
       "notes":"来料表面有划痕","reportedById":4}'
# 期望：{"message":"不良品已登记","defectNo":"DF-...(新单号)"}

# ② 不填根因就关闭 —— 应被拒绝
curl -s -X POST $BASE/api/defects/2/close -H "Content-Type: application/json" \
  -d '{"rootCause":"","counterMeasure":"加强巡检"}'
# 期望：{"message":"关闭前必须填写根因分析（RootCause）"}

# ③ 填完整再关闭 —— 应成功
curl -s -X POST $BASE/api/defects/2/close -H "Content-Type: application/json" \
  -d '{"rootCause":"螺栓来料批次螺纹公差偏大","counterMeasure":"更换供应商批次并加严来料抽检"}'

# ④ 确认它进了追溯链
curl -s $BASE/api/work-orders/1/trace | grep -o '"action":"[^"]*"' | sort -u

合格率和 SPC，差在"早一步"

假设你这周每天的合格率是：99.5%、99.3%、99.4%、98.1%、99.2%。 合格率指标告诉你"还不错"。

但 SPC 会告诉你：98.1% 那一天是异常的。 它落在正常波动范围之外，说明有特殊原因介入了（换了料？设备参数漂了？新人上手？）。

这就是 SPC 的价值：它管的是趋势，比合格率这种"结果指标"早一步报警。 等合格率跌破目标再动手，通常已经废了一批。

算法本身很简单

var rates = valid.Select(d => d.PassRate).ToList();
var mean = rates.Average();

// 样本标准差（除以 n-1），比总体标准差更适合小样本
var variance = rates.Sum(r => (r - mean) * (r - mean)) / (rates.Count - 1);
var sigma = (decimal)Math.Sqrt((double)variance);

var ucl = Math.Round(mean + 3 * sigma, 2);          // 上控制限
var lcl = Math.Round(Math.Max(0, mean - 3 * sigma), 2);  // 下控制限

var points = valid.Select(d =>
{
    var outOfControl = d.PassRate > ucl || d.PassRate < lcl;
    return new SpcPointDto(d.Date, d.PassRate, Math.Round(mean, 2), ucl, lcl,
        outOfControl,
        outOfControl ? (d.PassRate < lcl ? "低于下控制限：过程异常，需查原因" : "高于上控制限：检查数据口径") : null);
}).ToList();

三个实现细节

1. 只取有产出的天参与计算。没开工的天合格率是 0， 如果算进去，均值会被拉低一大截，控制限完全失效。 代码里是这句 var valid = daily.Where(d => d.TotalQty > 0)。
2. 用样本标准差（除以 n-1）而不是总体标准差（除以 n）。 在统计上，样本标准差是对总体标准差的无偏估计。样本量小的时候差别很明显， 而且工业界的 SPC 规范用的就是 n-1。
3. 下控制限不能小于 0。合格率不可能为负， Math.Max(0, ...) 是为了避免画出一条在 0 以下的无意义控制线。 上控制限同理——超过 100% 的 UCL 说明数据波动太小或者样本不足，要提示用户。

curl -s "http://localhost:5100/api/reports/spc?days=30" | python -m json.tool

OEE = 时间开动率 × 性能开动率 × 合格率

核心代码

// ---------- 1. 时间开动率 ----------
var totalMinutes = eq.RunningMinutes + eq.DownMinutes;
var availability = totalMinutes <= 0
    ? 0m
    : Math.Round((decimal)eq.RunningMinutes / totalMinutes, 4);

// ---------- 2. 性能开动率 ----------
// 处理数量含报废 —— 报废品也是"做出来的"，占用的是加工时间
var processed = wcReports.Sum(r => r.Qty + r.ScrapQty);

var theoryMinutes = wcReports.Sum(r => (r.Qty + r.ScrapQty) * r.Operation.StandardMinutes);
var actualMinutes = wcReports
    .Sum(r => (decimal)(r.EndedAt!.Value - r.StartedAt!.Value).TotalMinutes);

var rawPerformance = actualMinutes <= 0
    ? 0m
    : Math.Round(theoryMinutes / actualMinutes, 4);

// 封顶 100% 用于 OEE 合成 —— OEE 是三个"率"的乘积，超过 100% 在数学上不成立。
// 但原始值要保留：它 >105% 通常说明标准工时定得太松。
var performance = Math.Min(rawPerformance, 1m);
var suspicious = rawPerformance > 1.05m;

// ---------- 3. 合格率 ----------
var scrap = wcReports.Sum(r => r.ScrapQty);
var good = wcReports.Sum(r => r.Qty);
var totalOutput = good + scrap;
var quality = totalOutput <= 0 ? 0m : Math.Round(good / totalOutput, 4);

// ---------- 4. 合成 ----------
var oee = Math.Round(availability * performance * quality, 4);

比数字更重要的：告诉人先改哪一项

// 三项各损失多少。数值最大的那一项就是改善优先级最高的方向
var losses = new (string Name, decimal Loss, string Advice)[]
{
    ("时间损失", Math.Round((1 - oee.Availability) * 100, 1), "查故障停机与换型等待，减少非计划停机"),
    ("速度损失", Math.Round((1 - oee.Performance) * 100, 1), "查小停顿与降速运行；若原始性能率超 105%，核对标准工时是否偏松"),
    ("质量损失", Math.Round((1 - oee.Quality) * 100, 1), "查废品与返工，从不良类型找根因")
};

var worst = losses.OrderByDescending(l => l.Loss).First();

一个 67% 的 OEE 本身不构成行动。但如果系统告诉你 "时间损失 22% 是最大的一项，优先查非计划停机"， 这就变成了排产员和设备主管第二天可以去干的事。

报表的终点不是数字，是动作。每个指标都应该能回答"所以我该做什么"。

# 全部设备的 OEE 拆解
curl -s http://localhost:5100/api/oee

# 车间汇总
curl -s http://localhost:5100/api/oee/summary

# 单台设备，带"最大损失在哪"
curl -s http://localhost:5100/api/oee/3

第一件事：员工 ≠ 账号

如果合成一张表，你就得给 300 个操作工每人建一个账号， 然后面对"这些人从来没登录过"的困惑，还要为每个人编密码。

public class AppUser
{
    public int Id { get; set; }
    public string UserName { get; set; } = string.Empty;      // 登录名
    public string DisplayName { get; set; } = string.Empty;   // 中文名

    /// <summary>PBKDF2 哈希，格式：迭代次数.盐(Base64).哈希(Base64)</summary>
    public string PasswordHash { get; set; } = string.Empty;

    public UserRole Role { get; set; } = UserRole.Operator;

    /// <summary>关联的员工，用于把报工记录落到真人身上</summary>
    public int? EmployeeId { get; set; }
    public Employee? Employee { get; set; }

    public bool IsActive { get; set; } = true;
    public DateTime? LastLoginAt { get; set; }

    // 权限判断集中在这里，不要散到各个 Controller
    public bool CanReleaseWorkOrder => Role is UserRole.Planner or UserRole.Leader or UserRole.Admin;
    public bool CanReportProduction => Role is UserRole.Operator or UserRole.Leader or UserRole.Admin;
    public bool CanInspect          => Role is UserRole.Inspector or UserRole.Leader or UserRole.Admin;
    public bool CanAssign           => Role is UserRole.Leader or UserRole.Planner or UserRole.Admin;
    public bool CanViewAudit        => Role is UserRole.Admin;
}

public enum UserRole
{
    Operator = 0,    // 操作工：只能报工
    Inspector = 1,   // 质检员：检验、判不良
    Leader = 2,      // 班组长：派工、报工、检验
    Planner = 3,     // 计划员：建单、下达、排产
    Admin = 9        // 管理员：全部 + 审计
}

密码：三条不能妥协的底线

private const int Iterations = 100_000;

/// <summary>PBKDF2-SHA256 加盐哈希，格式：迭代次数.盐(Base64).哈希(Base64)</summary>
public static string HashPassword(string password)
{
    var salt = RandomNumberGenerator.GetBytes(16);
    var hash = Rfc2898DeriveBytes.Pbkdf2(
        password, salt, Iterations, HashAlgorithmName.SHA256, 32);

    return $"{Iterations}.{Convert.ToBase64String(salt)}.{Convert.ToBase64String(hash)}";
}

/// <summary>
/// 校验密码。用固定时间比较（FixedTimeEquals）而不是 ==，
/// 避免通过响应时间差反推密码 —— 这类细节是安全编码的基本功。
/// </summary>
public static bool VerifyPassword(string password, string stored)
{
    var parts = stored.Split('.');
    if (parts.Length != 3) return false;
    if (!int.TryParse(parts[0], out var iterations)) return false;

    try
    {
        var salt = Convert.FromBase64String(parts[1]);
        var expected = Convert.FromBase64String(parts[2]);

        var actual = Rfc2898DeriveBytes.Pbkdf2(
            password, salt, iterations, HashAlgorithmName.SHA256, expected.Length);

        return CryptographicOperations.FixedTimeEquals(actual, expected);
    }
    catch { return false; }
}

令牌：手写一遍，是为了以后知道该看哪一层

真实的项目请直接用 ASP.NET Core 官方的 JWT 中间件。这里手写一遍， 是为了让你看清"令牌到底是什么"：

/// <summary>签发令牌</summary>
public string Create(AppUser user)
{
    var exp = DateTimeOffset.UtcNow.Add(Lifetime).ToUnixTimeSeconds();
    var payload = $"{user.Id}|{exp}";        // ① 载荷：用户 Id + 过期时间
    var sig = Sign(payload);                 // ② 签名：HMAC-SHA256 取前 16 字节
    var raw = $"{payload}|{sig}";
    return Convert.ToBase64String(Encoding.UTF8.GetBytes(raw))
        .Replace('+', '-').Replace('/', '_').TrimEnd('=');   // ③ Base64Url 编码
}

三部分：载荷 + 签名 + 编码。 签名的作用是防篡改——用户改不了自己的 Id，因为改完签名就对不上。

令牌里不放密码、不放敏感权限，只放一个能查到用户的 Id。 权限每次都从数据库读，这样管理员改了角色，下一次请求就立刻生效， 而不用等令牌过期。

权限校验：一处定义，处处调用

public class AccessControl
{
    private readonly bool _enforce;
    private readonly AuditService _audit;

    public AccessControl(IConfiguration cfg, AuditService audit)
    {
        _enforce = cfg.GetValue("Mes:EnforcePermission", false);
        _audit = audit;
    }

    public AppUser? User => _audit.CurrentUser;

    /// <summary>
    /// 要求当前用户满足某个权限条件。
    /// 演示模式（enforce=false）下直接放行，但仍会把操作人记成匿名。
    /// </summary>
    public void Require(Func<AppUser, bool> predicate, string what)
    {
        if (!_enforce) return;
        AuthService.Require(User, predicate, what);
    }
}

// Controller 里的用法 —— 意图一眼可见
[HttpPost("assignments")]
public async Task<ActionResult> Assign(AssignRequest req)
{
    _access.Require(u => u.CanAssign, "派工");
    var a = await _service.AssignAsync(req);
    return Ok(new { message = "派工成功", assignmentNo = a.AssignmentNo });
}

前端别写死后端的状态

后端有 EnforcePermission 这个开关，前端就得跟着它走。 /api/auth/me 除了返回 authenticated， 还返回 enforcePermission —— 它回答的是另一个问题： "这个后端到底开没开强制鉴权"。

let ENFORCED = false;   // 后端是否强制鉴权 —— 由接口决定，绝不写死

// 启动时探测一次。即使本地没有令牌也要探：
// 不知道后端开没开鉴权，就不知道该不该提示"未登录只能查看"。
async function restoreSession() {
  try {
    const me = await api("/api/auth/me");
    ENFORCED = !!me.enforcePermission;
    if (me.authenticated) { CURRENT_USER = me.user; }
    else if (TOKEN) { TOKEN = ""; localStorage.removeItem("mes_token"); }
  } catch (e) { TOKEN = ""; localStorage.removeItem("mes_token"); }
  renderUserChip();
  renderLoginHint();      // 登录弹窗底部的说明也跟着变
}

// 界面上所有跟鉴权有关的文案，都从 ENFORCED 派生
box.innerHTML = ENFORCED ? "未登录 · 只能查看" : "未登录";

BASE=http://localhost:5100

# ① 登录（种子数据预设了 5 个账号，密码统一 mes@2026）
curl -s -X POST $BASE/api/auth/login -H "Content-Type: application/json" \
  -d '{"userName":"planner","password":"mes@2026"}'
# 期望：返回 token + roleText="计划员" + permissions 数组

# ② 错误密码 —— 提示必须和"账号不存在"完全一样
curl -s -X POST $BASE/api/auth/login -H "Content-Type: application/json" \
  -d '{"userName":"planner","password":"wrong"}'
curl -s -X POST $BASE/api/auth/login -H "Content-Type: application/json" \
  -d '{"userName":"nobody","password":"wrong"}'
# 两条返回的 message 都必须是"用户名或密码错误"

# ③ 带令牌查自己
TOKEN=$(curl -s -X POST $BASE/api/auth/login -H "Content-Type: application/json" \
  -d '{"userName":"planner","password":"mes@2026"}' | python -c "import sys,json;print(json.load(sys.stdin)['token'])")
curl -s $BASE/api/auth/me -H "Authorization: Bearer $TOKEN"

两本账，各管一半

关键设计：审计不单独提交

/// <summary>
/// 追加一条审计记录（不提交，由调用方决定事务边界）
/// </summary>
public void Write(
    string action, string targetType, string targetId,
    string? before = null, string? after = null,
    bool succeeded = true, string? message = null)
{
    var user = CurrentUser;
    var ctx = _http.HttpContext;

    _db.AuditLogs.Add(new AuditLog
    {
        UserName = user?.UserName ?? "anonymous",
        Role = user is null ? "匿名" : TokenService.RoleText(user.Role),
        Action = action,
        TargetType = targetType,
        TargetId = targetId,
        BeforeValue = Truncate(before),
        AfterValue = Truncate(after),
        IpAddress = ctx?.Connection.RemoteIpAddress?.ToString(),
        Succeeded = succeeded,
        Message = Truncate(message),
        HappenedAt = DateTime.Now
    });
}

它不调用 SaveChanges。业务代码这样用：

_audit.Write("状态流转", "WorkOrder", wo.OrderNo,
    before: StatusText(from), after: StatusText(target), message: remark);

await _db.SaveChangesAsync();   // 业务数据 + 审计日志一起提交

从日志里看异常信号

日志本身不是目的，能从中发现问题才是。三个值得盯的信号：

// 夜间操作（22:00 ~ 06:00）：生产车间不该有系统操作，值得看一眼
var nightOps = logs.Count(a => a.HappenedAt.Hour >= 22 || a.HappenedAt.Hour < 6);

BASE=http://localhost:5100

# ① 先做一次会被拒绝的操作，制造一条"失败"日志
curl -s -X POST $BASE/api/work-orders/1/transit -H "Content-Type: application/json" \
  -d '{"target":5}'
# 期望：{"message":"不允许从「生产中」直接跳到「关闭」..."}

# ② 看审计汇总
curl -s "$BASE/api/audit/summary?days=7"

# ③ 只看失败记录
curl -s "$BASE/api/audit?onlyFailed=true"

# ④ 看某张工单的完整操作历史
curl -s "$BASE/api/audit/trace/WorkOrder/$(curl -s $BASE/api/work-orders/1 | python -c "import sys,json;print(json.load(sys.stdin)['orderNo'])")"

细节一：日期必须补齐

最直接的写法是 GROUP BY 日期，只返回有数据的天。这会带来一个隐蔽的坑：

有数据的天：10-01, 10-02, 10-04, 10-05
图表的 X 轴：10-01, 10-02, 10-04, 10-05   ← 10-03 消失了

看起来产量很平稳，实际是 10-03 那天停产了。 数据可视化里最容易犯、也最难被发现的错误，就是让"没有数据"变成"看不见"。

var byDay = reports
    .GroupBy(r => r.ReportedAt.Date)
    .ToDictionary(g => g.Key, g => g.ToList());

var list = new List<DailyOutputDto>(span);

// 强制遍历区间内的每一天 —— 没有数据的天补 0，而不是跳过
for (var i = 0; i < span; i++)
{
    var day = from.AddDays(i);
    var rs = byDay.TryGetValue(day, out var v) ? v : [];

    var passed = rs.Sum(r => r.Qty);
    var scrap = rs.Sum(r => r.ScrapQty);
    var total = passed + scrap;

    list.Add(new DailyOutputDto(
        day.ToString("yyyy-MM-dd"), passed, scrap, total,
        total <= 0 ? 0m : Math.Round(passed / total * 100, 2),
        rs.Count));
}

细节二：单件工时的分母是什么

// 只有记录了开始/结束时间、且数量大于 0 的报工才能算节拍
var timed = sample
    .Where(r => r.StartedAt.HasValue && r.EndedAt.HasValue && r.Qty > 0)
    .Select(r => new
    {
        PerPiece = (decimal)(r.EndedAt!.Value - r.StartedAt!.Value).TotalMinutes / r.Qty,
        Std = r.Operation.StandardMinutes
    })
    .Where(x => x.PerPiece > 0)
    .ToList();

var actualAvg = Math.Round(timed.Average(x => x.PerPiece), 2);

// 效率 = 标准 / 实际。大于 100% 表示比标准快
var efficiency = Math.Round(std / actualAvg * 100, 1);

细节三：CSV 的三个实用要点

/// <summary>CSV 字段转义：含逗号、引号、换行时用双引号包裹并翻倍内部引号</summary>
private static string Esc(string? v)
{
    if (string.IsNullOrEmpty(v)) return "";
    return v.Contains(',') || v.Contains('"') || v.Contains('\n') || v.Contains('\r')
        ? "\"" + v.Replace("\"", "\"\"") + "\""
        : v;
}

/// <summary>转成带 BOM 的 UTF-8 字节 —— 少这个 BOM，Excel 打开就是乱码</summary>
private static byte[] ToBytes(StringBuilder sb)
    => new UTF8Encoding(encoderShouldEmitUTF8Identifier: true).GetBytes(sb.ToString());

1. UTF-8 BOM 必须有。没有它，中文 Excel 用系统默认编码（GBK）打开， 整张表就是一堆方块。这是中文 CSV 导出最经典的坑，几乎人人踩过一次。
2. 字段要转义。报废原因里写个逗号，整行的列就全部错位—— 而且错得很隐蔽，因为数据看起来"好像还在"。
3. 用 \r\n 换行（StringBuilder.AppendLine 在 Windows 上就是）， 保证 Excel 各版本都能正确分行。

BASE=http://localhost:5100

# 产量趋势（会自动补齐没开工的天）
curl -s "$BASE/api/reports/output-trend?days=14"

# 工序节拍：标准 vs 实际单件工时
curl -s $BASE/api/reports/operation-cycle

# 员工绩效（产出 / 质量 / 工时三个维度）
curl -s "$BASE/api/reports/employee-performance?days=30"

# 导出 5 种 CSV，验证 BOM 头
for t in workorders reports inspections output assignments; do
  echo -n "$t: "
  curl -s "$BASE/api/reports/export/$t" | head -c 3 | xxd | head -1
done

MES 的测试重点和普通 CRUD 不一样

一个物料 CRUD 写错了，大不了数据不对，人一眼能看出来。 但 MES 的规则是埋在流程里的：

• 前道工序没完工，报工必须被拒绝
• 工单不能从"生产中"直接跳到"关闭"
• 派工数量不能超过工序计划数
• 关键工序没有检验记录，不能流转

这些规则的特点：正常路径下永远不会被触发。 你每天正常用系统，可能半年都碰不到它们。 但只要有一条失效，车间的后果是真实的——所以它们恰恰是最该被自动验证的部分。

第一层：API 业务规则测试

#!/usr/bin/env bash
# MES 业务规则回归测试 —— 每次改完代码跑一遍
#
# 两种后端配置下都能跑：
#   Mes:EnforcePermission = false  → 免登录演示模式（本地开发用）
#   Mes:EnforcePermission = true   → 生产强制鉴权模式
# 做法：先用 admin 登录拿令牌，所有写操作统一带上；
#       再根据探测到的模式，追加一组鉴权专项断言。
#
# 用 admin 而不是 planner 跑业务用例，是因为业务断言要测的是
# 「业务规则本身」（超派、故障设备、报废原因…），不该被角色权限先拦掉。
# 角色权限由后面那组专项断言单独覆盖。

BASE=${BASE:-http://localhost:5100}
PASS=0; FAIL=0

# 断言某个请求返回指定的 HTTP 状态码
expect_status() {
  local name="$1" want="$2"; shift 2
  local got
  got=$(curl -s -o /dev/null -w '%{http_code}' -m 10 "$@")
  if [ "$got" = "$want" ]; then
    echo "  [OK]   $name"; PASS=$((PASS+1))
  else
    echo "  [FAIL] $name（期望 $want，实际 $got）"; FAIL=$((FAIL+1))
  fi
}

# 断言响应体里包含某段文字
expect_contains() {
  local name="$1" want="$2"; shift 2
  local body
  body=$(curl -s -m 10 "$@")
  if echo "$body" | grep -q "$want"; then
    echo "  [OK]   $name"; PASS=$((PASS+1))
  else
    echo "  [FAIL] $name（响应里没有「$want」）"; FAIL=$((FAIL+1))
    echo "         实际： $(echo "$body" | head -c 200)"
  fi
}

# 从 JSON 里抠一个字符串字段（不依赖 jq）
json_field() { grep -o "\"$1\":\"[^\"]*\"" | head -1 | cut -d'"' -f4; }

# ---------- 0. 探测鉴权模式 + 取令牌 ----------
MODE=$(curl -s -m 10 "$BASE/api/auth/me" | grep -o '"enforcePermission":[a-z]*' | cut -d: -f2)
MODE=${MODE:-unknown}
echo "== 环境：enforcePermission=$MODE =="

TOKEN=$(curl -s -m 10 -X POST "$BASE/api/auth/login" \
        -H "Content-Type: application/json" \
        -d '{"userName":"admin","password":"mes@2026"}' | json_field token)

if [ -z "$TOKEN" ]; then
  echo "  [FAIL] 取不到 admin 令牌，后面所有写操作都会失败"
  FAIL=$((FAIL+1))
fi
AUTH=(-H "Authorization: Bearer $TOKEN")

# 操作工令牌：只用来验证"越权会被拒"，它的权限最低（只能报工）
OP_TOKEN=$(curl -s -m 10 -X POST "$BASE/api/auth/login" \
           -H "Content-Type: application/json" \
           -d '{"userName":"zhangwei","password":"mes@2026"}' | json_field token)

echo "== 工单状态机 =="
# 生产中 -> 关闭 必须被拒绝（合法出口只有 暂停/完工/作废）
expect_status   "生产中不能直接关闭" 400 "${AUTH[@]}" -X POST $BASE/api/work-orders/1/transit \
  -H "Content-Type: application/json" -d '{"target":5}'
expect_contains "错误信息要给出合法出口" "当前允许流转到" "${AUTH[@]}" -X POST $BASE/api/work-orders/1/transit \
  -H "Content-Type: application/json" -d '{"target":5}'
# 已完工的工序不能再派工
expect_contains "已完工工序不能派工" "已完工" "${AUTH[@]}" -X POST $BASE/api/scheduling/assignments \
  -H "Content-Type: application/json" -d '{"operationId":1,"employeeId":1,"qty":1}'

echo "== 报工校验 =="
# 有报废但没写原因，必须被拒绝
expect_contains "报废必须填原因" "报废原因" "${AUTH[@]}" -X POST $BASE/api/production/report \
  -H "Content-Type: application/json" \
  -d '{"operationId":4,"employeeId":1,"qty":1,"scrapQty":1}'

echo "== 派工校验 =="
# 工序 4「总装」计划 50，已派 30+20=50，再派必须被拒
expect_contains "超派要被拒绝" "超派" "${AUTH[@]}" -X POST $BASE/api/scheduling/assignments \
  -H "Content-Type: application/json" -d '{"operationId":4,"employeeId":1,"qty":10}'
# 工序 7 还有余量，但设备 4「综合测试台」处于故障停机
expect_contains "故障设备不能派工" "故障停机" "${AUTH[@]}" -X POST $BASE/api/scheduling/assignments \
  -H "Content-Type: application/json" -d '{"operationId":7,"employeeId":2,"equipmentId":4,"qty":5}'

echo "== 不良品流程 =="
# 3 号不良品是「待处理」，关闭时必须填根因；1 号已关闭，拿它测会撞到"不能重复关闭"
expect_contains "关闭不良品必须填根因" "根因" "${AUTH[@]}" -X POST $BASE/api/defects/3/close \
  -H "Content-Type: application/json" -d '{"rootCause":"","counterMeasure":"x"}'

echo "== 认证 =="
expect_status   "错误密码返回 400" 400 -X POST $BASE/api/auth/login \
  -H "Content-Type: application/json" -d '{"userName":"planner","password":"wrong"}'
expect_contains "不泄露账号是否存在" "用户名或密码错误" -X POST $BASE/api/auth/login \
  -H "Content-Type: application/json" -d '{"userName":"nobody","password":"wrong"}'
# 匿名访问 /me 不走 401，而是如实回 authenticated=false（前端据此显示"未登录"）
expect_contains "匿名身份如实返回" '"authenticated":false' $BASE/api/auth/me

echo "== 鉴权（enforcePermission=$MODE） =="
if [ "$MODE" = "true" ]; then
  # 未登录的写操作必须被拦，且提示是人话
  expect_contains "无令牌写操作被拒" "请先登录" -X POST $BASE/api/scheduling/assignments \
    -H "Content-Type: application/json" -d '{"operationId":4,"employeeId":1,"qty":1}'
  # 登录了但角色不够，也要被拦
  expect_contains "操作工无权派工" "无权派工" -X POST $BASE/api/scheduling/assignments \
    -H "Authorization: Bearer $OP_TOKEN" -H "Content-Type: application/json" \
    -d '{"operationId":4,"employeeId":1,"qty":1}'
  expect_contains "操作工无权看审计" "无权查看审计" "$BASE/api/audit" \
    -H "Authorization: Bearer $OP_TOKEN"
  # 读接口对所有人开放（演示站的数据本来就是公开的），别把前端首屏也锁了
  expect_status "未登录仍能看板" 200 "$BASE/api/dashboard/summary"
else
  echo "  [SKIP] 强制鉴权已关闭，跳过拦截断言"
  echo "         （本地开发方便，但生产环境 Mes:EnforcePermission 必须为 true）"
fi

echo "== 报表导出 =="
for t in workorders reports inspections output assignments; do
  expect_status "CSV 导出 $t" 200 $BASE/api/reports/export/$t
done

echo ""
echo "==== $PASS 通过 / $FAIL 失败 ===="
[ "$FAIL" -eq 0 ]

第二层：前端渲染测试

单文件前端最容易出的问题是：改了一处模板字符串，另一个页签渲染时崩了， 而且只有点到那个页签才会发现。

用 jsdom 把页面加载起来、逐个页签点一遍，就能把这类问题堵在提交之前：

const { JSDOM } = require("jsdom");
const API = "http://localhost:5100";

// 先确认后端活着 —— 前端测试依赖真实接口，服务没起就没意义
const r = await fetch(API + "/");
if (!r.ok) { console.log("后端不可达，先 dotnet run"); process.exit(1); }

const dom = new JSDOM(fs.readFileSync("Mes.Api/wwwroot/index.html", "utf-8"), {
  url: API + "/",
  runScripts: "dangerously",          // 必须：让内联 script 真的执行
  beforeParse(window) {
    // 把页面里的相对路径 fetch 代理到真实服务
    window.fetch = (input, init) =>
      fetch(typeof input === "string" ? new URL(input, API).toString() : input, init);
    window.scrollTo = () => {};
    window.addEventListener("unhandledrejection", e =>
      errors.push(String(e.reason && e.reason.message || e.reason)));
  }
});

const doc = dom.window.document;
await sleep(2500);   // 等首屏的异步加载完成

// 静态一致性：导航按钮数 = 页面容器数，且不能有孤立的按钮
const navBtns = [...doc.querySelectorAll("nav button[data-page]")];
const orphan = navBtns.map(b => b.dataset.page)
                      .filter(p => !doc.getElementById("page-" + p));
assert(navBtns.length === 10, "导航按钮应为 10 个");
assert(orphan.length === 0, "有按钮指向了不存在的页面：" + orphan);

// 逐个页签点击，断言容器里真的渲染出了内容
for (const [page, container] of [
  ["dashboard", "kpis"],   ["orders", "orderList"],  ["schedule", "loadBox"],
  ["mrp", "mrpBox"],       ["report", "rpOrder"],    ["quality", "qcKpis"],
  ["defect", "defectBox"], ["equipment", "oeeBox"],
  ["analytics", "outputChart"], ["audit", "auditBox"],
]) {
  doc.querySelector(`nav button[data-page="${page}"]`).click();
  await sleep(2200);

  const html = doc.getElementById(container).innerHTML.trim();
  assert(html.length > 20, `${page} 的关键容器 ${container} 没渲染出内容`);
  assert(!/undefined|NaN/.test(html), `${page} 页面出现了 undefined / NaN`);
}

// 还要测"点了才有内容"的交互路径：追溯链、算料
const sel = doc.getElementById("traceOrder");
sel.value = [...sel.options].find(o => o.value).value;
dom.window.loadTrace();          // 模拟 onchange
await sleep(2000);
assert(doc.getElementById("traceBox").innerHTML.length > 60, "追溯链没渲染");

cd mes
node ui-test.js

=== MES 前端渲染测试 ===
服务地址: http://localhost:5100
  [OK]   后端服务可达

-- 静态结构 --
  [OK]   导航按钮 10 个
  [OK]   页面容器 10 个
  [OK]   导航按钮都有对应容器
  [OK]   无重复 id

-- 逐页签渲染 --
  [OK]   页签 dashboard 整页有内容
  [OK]   页签 dashboard 无 undefined/NaN
  [OK]   页签 dashboard 关键容器 kpis 非空
  ...（10 个页签 × 4 项断言，全部通过）
  [OK]   页签 audit 关键容器无 undefined/NaN

-- 交互：追溯链 --
  [OK]   追溯工单下拉已填充
  [OK]   选工单后追溯链渲染出内容
  [OK]   追溯链无 undefined/NaN

-- 交互：算料 --
  [OK]   算料工单下拉已填充
  [OK]   算料结果渲染出内容
  [OK]   算料结果无 undefined/NaN

-- 全局 --
  [OK]   无未捕获异常

==== 通过 52 项 / 失败 0 项 ====

什么时候跑这些测试

不到 1 分钟的反馈循环，才有人愿意真的每次都跑。 测试跑得慢，等于没有测试。

chmod +x test-api.sh
./test-api.sh

== 环境：enforcePermission=false ==
== 工单状态机 ==
  [OK]   生产中不能直接关闭
  [OK]   错误信息要给出合法出口
  [OK]   已完工工序不能派工
== 报工校验 ==
  [OK]   报废必须填原因
== 派工校验 ==
  [OK]   超派要被拒绝
  [OK]   故障设备不能派工
== 不良品流程 ==
  [OK]   关闭不良品必须填根因
== 认证 ==
  [OK]   错误密码返回 400
  [OK]   不泄露账号是否存在
  [OK]   匿名身份如实返回
== 鉴权（enforcePermission=false） ==
  [SKIP] 强制鉴权已关闭，跳过拦截断言
         （本地开发方便，但生产环境 Mes:EnforcePermission 必须为 true）
== 报表导出 ==
  [OK]   CSV 导出 workorders
  [OK]   CSV 导出 reports
  [OK]   CSV 导出 inspections
  [OK]   CSV 导出 output
  [OK]   CSV 导出 assignments

==== 15 通过 / 0 失败 ====

== 环境：enforcePermission=true ==
（工单状态机 / 报工 / 派工 / 不良品 / 认证 —— 12 条业务断言输出完全相同，此处略）

== 鉴权（enforcePermission=true） ==
  [OK]   无令牌写操作被拒          ← 未登录打写接口，回「请先登录后再派工」
  [OK]   操作工无权派工            ← 登录了但角色不够，回「无权派工」
  [OK]   操作工无权看审计          ← 回「无权查看审计」
  [OK]   未登录仍能看板            ← 读接口不锁，否则前端首屏就白了

== 报表导出 ==
  [OK]   CSV 导出 workorders
  [OK]   CSV 导出 reports
  [OK]   CSV 导出 inspections
  [OK]   CSV 导出 output
  [OK]   CSV 导出 assignments

==== 19 通过 / 0 失败 ====

上线前必须改的四件事

// 开发环境：SQLite（零配置，数据库就是一个文件）
builder.Services.AddDbContext<MesDbContext>(options =>
    options.UseSqlite(builder.Configuration.GetConnectionString("Default")));

// 生产环境：换成 SQL Server（或 PostgreSQL）—— 业务代码一行都不用动
// builder.Services.AddDbContext<MesDbContext>(options =>
//     options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));

上线实录：真的部署一次会踩到什么

上面那张表说的是"应该怎么做"。这一节记录的是实际部署这套系统时踩到的坑—— 它们不在任何文档里，只有真上手部署一次才会遇到。

以下是四个坑。共同点是：报错信息都不指向真正的原因。

性能：先把索引和口径做对，再谈别的

MES 的性能问题几乎从不需要"上缓存"或"加机器"来解决， 因为 90% 的慢查询是这两个原因：

1. 看板接口在扫全表。首页要"按状态列工单"， 如果 Status 上没索引，工单涨到 10 万条时首屏就要几秒。
2. 聚合在内存里做。本项目为了演示清晰，很多统计是 ToListAsync() 之后在内存里 Sum/Average。 数据量小的时候没问题，几十万条报工记录之后就会出问题。

// 已经建好的关键索引（MesDbContext 里）
e.HasIndex(x => x.Status);                              // 看板首屏：按状态查工单
e.HasIndex(x => new { x.EmployeeId, x.PlannedStart });  // 排产 / 我的任务
e.HasIndex(x => x.HappenedAt);                          // 追溯链按时间翻页
e.HasIndex(x => new { x.TargetType, x.TargetId });      // 审计按对象查历史

演进路线图

按投入产出比排序。做完前两项，这套系统就足以支撑一个真实的中小型车间：

你已经完整掌握的东西

走完 30 课，你手上不只是一套能跑的代码，而是这些可以迁移到任何制造业项目的能力：

• 状态机建模——把业务规则集中成一份定义，改一处规则全系统生效
• 模板与实例分离——历史数据不被规则变更追溯性改写
• 事务边界的直觉——一次 SaveChanges 就是一个原子操作， 业务数据和审计日志必须同进同出
• 追溯系统的设计——只增不改的表、不建外键的账本、 产品履历与人的履历要分开记
• 指标口径的敏感性——算错的分母比没有指标更危险； "全是一个值"通常意味着公式错了
• 有限产能思维——承认资源有上限，是排产算法的分水岭
• 递归的两个安全阀——深度上限 + 按路径判环
• 分层纪律——Controller 管 HTTP，Service 管业务，DbContext 管表结构
• 用流程逼出信息——把"填原因"和"关闭"绑成一件事
• 测试的重点在失败路径——规则的力量在于它拒绝了什么

这些东西换一个行业（电子、汽车、医药、食品）依然成立， 因为它们是制造执行这件事本身的规律，不是某个框架的用法。

1 · 架构与标准

2 · 生产执行

3 · 计划与排产

4 · 质量

5 · 设备与效率

6 · 工程实践

基础地址 http://localhost:5100；「需登录」指请求要带 Authorization: Bearer <token>。

认证与用户 · AuthController

工单 · WorkOrdersController

看板 · DashboardController

基础数据 · Materials / Bom / ProcessSteps / WorkCenters / Employees / Equipments

执行：报工与检验 · ProductionController

派工与排产 · SchedulingController

物料需求 · MrpController

不良品 · DefectsController

设备效率 · OeeController

报表 · ReportsController

type 可选且仅可为这 5 个值（写错了返回 400）： workorders（工单台账） · reports（报工明细） · inspections（检验记录） · output（日产量） · assignments（派工单）。

审计 · AuditController

域一 · 基础数据（5 张）

长期稳定、被大量引用、几乎不做物理删除。

域二 · 执行数据（5 张）

每天猛增、有明确状态、是业务规则的战场。

域三 · 追溯与质量账本（2 张）

只增不改、不建外键、永远查得到。

域四 · 设备与效率（2 张）

域五 · 计划结果与系统支撑（3 张）

关键约定（改表前必读）

一 · 编译与启动

二 · 数据库与迁移

三 · 业务规则被拒（这是好事，说明规则生效了）

四 · 数据与指标异常

五 · 前端与接口调用

六 · 调试三件套

阶段 0 · 认知与建模（第 1–3 课）

阶段 1–2 · 地基与基础数据（第 4–8 课）

阶段 3 · 执行闭环（第 9–13 课）

阶段 4–5 · 质量与设备（第 14–18 课）

阶段 6–8 · 计划、质量、效率进阶（第 20–25 课）

阶段 9–10 · 系统化与落地（第 26–30 课）