MRPeasy 集成指南：使用 SkyPlanner APS 进行生产排程

MRPeasy 是一款纯云端产品，没有本地部署版本，因此所有客户使用的 API 都相同。目前有两个版本：

1. REST API v1（OpenAPI 1.0，服务器地址为 https://api.mrpeasy.com/rest/v1）是用于生产环境的 API。它涵盖 /items、/boms、/routings、/manufacturing-orders、/work-centers、/work-center-types、/customer-orders、/purchase-orders、/stock/inventory、/lots、/units，以及 /report/production/operations 等生产报表端点。
2. REST API v2（OpenAPI 2.0.0，服务器地址为 https://api.mrpeasy.com/rest/v2）仍处于开发初期。它新增了带有 work_hours 和 holidays 的 /workstation-groups、带有 productivity 和 idle 的 /workstations，以及 /inventory、/stock-movement 和 PATCH。生产订单仍使用 v1。

请注意界面与 API 的命名差异。MRPeasy 界面中的 Workstation group（工作中心组）对应 v1 的 work-center-types（type_id），Workstation（工作中心）对应 work-centers（center_id）。工艺路线中的工序通过 type_id 关联到组，而非某台机器。

MRPeasy 的 Unlimited 套餐为付费账户提供 API。MRPeasy 同时声明：”Our Support Department cannot help you using the API.”（我们的支持部门无法协助您使用 API。）因此，集成必须有明确的负责人：SkyPlanner、您的 MRPeasy 顾问或开发人员。SkyPlanner 团队在实施阶段承担的正是这项工作。

MRPeasy 的定价页面列有 “API, webhooks (for paid accounts)”（API、webhook，仅供付费账户使用），但 v1 和 v2 规范均未记录生产订单的 webhook 事件。因此，集成通过增量轮询从 MRPeasy 获取数据：

• 筛选状态为 Not scheduled（15）、Scheduled（20）、In progress（30）和 Paused（35）的生产订单。
• 按设定周期或在每次运行排程前获取采购订单和库存。
• 在主数据变更时或每晚同步主数据。

按顺序执行并带筛选条件的轮询，请求量远低于每 10 秒 100 次的上限。在反向同步中，SkyPlanner 自身的 webhook 会即时推送排程变更，因此回写采用事件驱动机制。

1. 首次导入主数据。从 v1 获取物料、单位、BOM 和工艺路线，从 v1 或 v2 获取工作中心组和工作中心。日历可从 v2 的 /workstation-groups（work_hours、holidays）获取，也可直接在 SkyPlanner 中设置班次。将每个处于 Active 状态的加工组映射到 SkyPlanner 工作中心组，并将其工作中心设为组内成员。

2. 订单同步。读取未结生产订单及其工序，以及未结采购订单和库存。SkyPlanner 将已订购材料视为在采购订单交付日期可用，并在采购订单标记为 Delivered 时更新库存。每次重新排程时，都会检查现有库存和待到货采购物料。

3. 排程回写。PUT /manufacturing-orders/{id} 支持 code、quantity、due_date 和 assigned_id，以及采用 custom_<id> 格式的自定义字段。经双方约定后，SkyPlanner 会将计划完成时间写入 due_date，并将计划开始时间、计划完成时间和进度写入 MRPeasy 自定义字段。这样，在 MRPeasy 中工作的销售和采购人员就能看到实际排程。详细的工序顺序及各工序分配的工作中心保留在 SkyPlanner 中，车间以 SkyPlanner 作为派工视图。

4. 在 MRPeasy 之外创建订单。如果需要通过 API 创建订单，POST /manufacturing-orders 支持 no_scheduling 和 no_bookings。使用这两个参数，可避免 MRPeasy 占用已由 SkyPlanner 排程的工作中心。

5. 车间报工。操作员通过 SkyPlanner Mobile Confirmations、Production Timer 或 Quick Log Mode 记录作业，工时记录会让排程保持最新。报工渠道只选一个。同一批工序若同时使用 MRPeasy 的 Internet-kiosk 和 SkyPlanner 报工，就会产生两套不一致的记录。

6. 数据归属与冲突处理规则。上线前应书面明确以下规则：

按订单设计流程。在一个已交付的 MRPeasy 项目中，每个客户项目都对应一个主产品和一至三个半成品。每项产品在 MRPeasy 中都有各自的 BOM 和工艺路线，生产订单则同时存在于两个系统中。每张订单都应保留稳定的共用标识符，确保更新时不会创建重复订单。

• 界面与 API 的时间字段不同。界面中的 Setup time、Cycle time 和 Capacity 在 API 中分别对应 fixed_time、variable_time 和 variable_quantity。Capacity 大于 1 表示批量处理，例如烘箱作业。应将其映射为批量生产任务，而不是更长的加工周期。
• 被动加工组。干燥和冷却组 24/7 持续运行，没有产能限制。应将其映射为等待时间，而不是产能有限的工作中心。
• v1 不提供日历。work-centers 仅返回 center_id、type_id、code 和 title。请使用 v2，或在 SkyPlanner 中维护班次。
• 停工时段。工作中心的停工时段记录了维护和停机安排。务必同步这些数据，否则 SkyPlanner 会向已停机的设备安排生产任务。
• 工艺路线关联到工作中心组。MRPeasy 会选择可用性最佳的设备。在 SkyPlanner 中，组内的各个工作中心都是实际可选的资源，由排程引擎从中选择。