MES 调用 SAP B1 与 TM 接口说明

1. 概述与边界

本项目存在三类 SAP/TM 集成方式，必须按各自的数据方向和调用边界实施：

2. 调用架构

2.1 运行时配置

当前部署配置位于 static/config.js：baseURLB1 指向 B1 网关 /b1s，baseURLtm 指向 TM 网关 /openapi。地址由运行环境配置提供，前端源码不应硬编码 SAP 地址、账号、密码、SessionId 或 TM Token。

开发环境代理将 /api/b1s 转至 SAP Service Layer 的 /b1s/v1，将 /api/tm 转至条码系统的 /openapi/v1。生产调用实际以运行时 baseURLB1 与 baseURLtm 为准。

2.2 认证与会话

前端封装未在每个业务调用中传递 SAP 用户名和密码，认证与 SAP 会话应由 B1 网关统一管理。登录信息、会话 Cookie、证书及跨域策略均不得写入页面代码、接口参数、浏览器日志或本说明文档。

3. B1 登录与会话

对接方案规定：每次直接调用 SAP Service Layer 前，先登录取得响应体中的 SessionId；后续请求在 Header 中携带 Cookie: B1SESSION=<SessionId>;。方案样例的会话有效期为 30 分钟，具体以登录响应的 SessionTimeout 为准。

3.1 直接登录 B1 Service Layer

POST https://{b1-host}:50000/b1s/v1/Login
Content-Type: application/json

{
  "CompanyDB": "TEST_YL 或 SBO_YL",
  "UserName": "${B1_USER}",
  "Password": "${B1_PASSWORD}",
  "Language": "15"
}

// 成功响应必须读取并安全保存 SessionId；不要写入浏览器 localStorage。
{
  "SessionId": "...",
  "Version": "...",
  "SessionTimeout": 30
}

3.2 后续查询/更新 Header

GET https://{b1-host}:50000/b1s/v1/ProductionOrders?$filter=AbsoluteEntry eq 1234
Cookie: B1SESSION=${SESSION_ID};
Accept: application/json

收到 401、会话过期或 “not connected to a company” 类错误时，网关应只重登录一次后重试原请求；仍失败则返回失败给 MES。禁止在前端静默无限重试，避免重复创建采购申请、生产发料单等外部单据。

4. MES 网关报文协议

b1s.js 与 tm.js 均向各自网关根路径发送 HTTP POST。网关请求体为 JSON，实际下游动词由 func 指定；B1 或 TM 的认证 Header 由网关维护。

// 读取：getB1('/ProductionOrders', { "$filter": "AbsoluteEntry eq 1234" })
POST {baseURLB1}
Content-Type: application/json

{
  "func": "GET",
  "cmd": "ProductionOrders",
  "content": "{\"$filter\":\"AbsoluteEntry eq 1234\"}"
}

// 禁止调用（func=PATCH）：patchB1('/ProductionOrders(1234)', { ProductionOrderStatus: 'boposClosed' })
{
  "func": "PATCH",
  "cmd": "ProductionOrders(1234)",
  "content": "{\"ProductionOrderStatus\":\"boposClosed\"}"
}

封装默认超时为 100 秒。调用结果统一为 { success: true, data } 或 { success: false, message }；页面必须检查 success 后再提示用户或更新本地状态。

5. B1 查询、更新与生产反馈

5.1 生产订单 ProductionOrders

生产订单是 MES 与 SAP 的主关联对象。以 AbsoluteEntry（MES 中的订单号/计划号）查询；订单状态使用 boposPlanned、boposReleased、boposClosed、boposCancelled。更新 ProductionOrderLines 或 ProductionOrdersStages 后，SAP 不保证返回完整订单，必须立即按 AbsoluteEntry 重查，并将实际的 LineNumber、StgEntry、StgSeqNum 回写到 MES 的关联记录。

// 当前项目可直接使用的查询方式：由 B1 网关持有会话
const orderResult = await getB1('/ProductionOrders', {
  '$filter': 'AbsoluteEntry eq ' + orderNo,
  '$select': 'AbsoluteEntry,ProductionOrderStatus,ItemNo,PlannedQuantity,Project'
});
if (!orderResult.success || !orderResult.data?.value?.length) {
  throw new Error(orderResult.message || '未找到 SAP 生产订单');
}
const order = orderResult.data.value[0];

5.2 工位资源 Resources

5.3 工艺阶段 RouteStages

5.4 采购申请 PurchaseRequests

采购申请创建成功后，必须从返回数据取得并保存 SAP DocEntry 及 DocNum。表头至少维护 ReqType、Requester、DocDate、DocDueDate、TaxDate、RequriedDate；每个 DocumentLines 行至少维护 ItemCode、Quantity、WarehouseCode。日期按 YYYY-MM-DD 传递，数量按业务精度处理。

5.5 生产报工反馈 InventoryGenExits

项目的工时校验页面会先同步生产订单工序/资源，再创建 SAP 生产发料单，以回传设备或人工报工。单据头使用 DocDate、DocDueDate、Comments；行项目基于生产订单使用 BaseType: 202、BaseEntry（生产订单号）、BaseLine（SAP 生产订单行号），并携带资源/物料行、数量、仓库及工序阶段关联。

const feedback = await postB1('/InventoryGenExits', {
  DocDate: '2026-08-03',
  DocDueDate: '2026-08-03',
  Comments: 'MES报工 AID:12345; 项目:HT-0001',
  DocumentLines: [{
    BaseType: 202,
    BaseEntry: 1234,
    BaseLine: 2,
    LineType: 'dlt_Resource',
    WarehouseCode: '',
    U_ResName: '数控车床A',
    Quantity: 1.5
  }]
});
if (!feedback.success) throw new Error(feedback.message || 'SAP 生产反馈失败');
// 保存返回的 DocEntry，作为 MES 报工与 SAP 发料单的追溯键。

6. TM 条码任务：认证、创建与反馈

6.1 当前可调用链路

项目使用 src/api/tm.js，运行时入口为 window.dt_Config.baseURLtm。现有页面已实际调用以下路径：posttm('/stocktask/task/issueordertask', payload) 创建领料出库任务；posttm('/stocktask/task/receiptordertask', payload) 创建收货/退库入库任务。网关把 func、cmd、content 转发至 TM OpenAPI。

6.2 TM 怎么登录

要使 TM 调用可用，必须由条码系统供应方提供并确认以下五项，再由网关实现，前端不保存 Token：登录/换取 Token 地址与方法、账号认证字段、Header 格式、有效期与刷新方式、401 后的重试规则。网关应将 Token 写入服务端安全存储，并在转发 TM 请求时增加 Authorization: <AccessToken> 和需要时的 Accept-Language: zh_CN。

6.3 实际任务报文与成功判定

const payload = {
  doc_date: '2026-08-03',
  doc_type: '202-60',       // 现有领料页面使用的业务类型；变更前需与 TM 数据字典核对
  external_num: '1234',     // MES/SAP 关联单据号
  task_items: [{
    base_type: '202',
    base_entry: '1234',
    base_line_num: 2,
    external_num: '1234',
    item_code: 'ITEM-001',
    item_name: '物料名称',
    line_memo: 'MES领料任务',
    whs_code: 'W03',
    manage_type: 'B',
    price: 0,
    quantity: 2
  }]
};

const tmResult = await posttm('/stocktask/task/issueordertask', payload);
if (!tmResult.success) throw new Error(tmResult.message || 'TM 网关请求失败');
// TM 接口返回结构为 { code, data, message }。
// 必须按供应方确认的成功 code 判断，并保存 data 中的任务标识；不能仅凭 HTTP 2xx 提示“请求成功”。
if (!isTmBusinessSuccess(tmResult.data)) throw new Error(tmResult.data?.message || 'TM 创建任务失败');

TM 入库任务同样使用 receiptordertask；入库明细必须至少包含物料编码与数量，涉及批次时还需传 batch_number。条码接口文档定义的返回结构为 { code, data, message }，HTTP 200/201 才代表传输成功，401 表示 Token 无效，403 表示无权限，404 表示路径/资源不存在。业务成功码需由 TM 供应方确认后配置到网关。

7. SAP 只读数据查询

以下数据通过 SQL Server 链接服务器 [SAP] 读取，不属于 Service Layer 写接口。存储过程只能使用最小字段集，避免无条件跨库大范围查询。

-- 只读示例：以参数限定、显式转换数据类型
SELECT TOP (100)
    CAST([物料编码] AS nvarchar(100)) AS [物料编码],
    CAST([物料名称] AS nvarchar(200)) AS [物料名称]
FROM [SAP].[SBO_YL].[dbo].[UBT_OITM]
WHERE CAST([物料编码] AS nvarchar(100)) LIKE N'%' + @过滤 + N'%'
ORDER BY CAST([物料编码] AS nvarchar(100));

8. 定时同步存储过程 dbo.update_MyTask

该过程运行在 YL_MESDB，不接收参数。它通过 SQL Server 链接服务器 [SAP].[SBO_YL].[dbo] 读取 SAP 视图，再更新 MES 本地表；过程本身不调用 Service Layer，也不向 SAP 写入数据。

8.1 SQL Agent 定时作业

8.2 实际同步内容

8.3 执行方式

-- SQL Agent 当前每分钟执行一次的命令
USE [YL_MESDB];
GO
EXEC [dbo].[update_MyTask];
GO

过程将同步分为三个独立事务块，每个块使用 TRY...CATCH：发生错误即回滚当前事务并重新抛出错误。所有同步结果以 MES 本地表更新为准，页面查询应读取相应 MES 字段，不应把此过程误认为直接更新 SAP 单据的接口。

9. 页面 SAP / TM 接口调用清单

本节按当前 src/views 中的有效调用整理，未计入注释代码和“副本”页面。所有前端调用均是向 MES 网关发送 HTTP POST；以下 func 才是网关转发给 B1/TM 的实际方法。

9.1 Postman 网关环境

POST {{mes_b1_gateway}}
Content-Type: application/json

{
  "func": "GET",
  "cmd": "ProductionOrders",
  "content": "{\"$filter\":\"AbsoluteEntry eq 7316\"}"
}

这是页面 getB1('/ProductionOrders', { '$filter': 'AbsoluteEntry eq 7316' }) 发出的实际网关格式。将 cmd 填为下表对象路径，content 必须是 JSON 字符串而不是 JSON 对象。

9.2 页面与功能映射、操作与截图

9.2.1 页面实际操作与系统截图

以下为 MES 页面中的实际操作入口。截图来自系统操作手册中的真实页面；请先在 MES 页面完成业务操作。涉及 POST 或 PATCH 的接口均由系统受控流程触发，禁止在 Postman 中直接调用。

1. 工位资源维护

页面入口：系统管理 > 工位管理。

1. 按工位名称输入查询条件，点击“查询”确认现有记录。
2. 点击“新增”维护工位号、工位名称及资源属性；已有工位点击所在行“编辑”。
3. 核对工位号无重复后，在 MES 页面提交保存。

接口触发：B1 POST Resources（新增）或 PATCH Resources('工位号')（编辑）。禁止直接调用。

2. 工艺阶段维护

页面入口：工艺管理 > 工序管理。

1. 输入工艺名称，点击“查询”定位工序。
2. 点击“新增”录入工序编码、工序名称；修改时点击对应行“编辑”。
3. 提交前确认工序编码与 SAP B1 的 RouteStages.Code 对应。

接口触发：查询为 B1 GET RouteStages；新增/编辑为 POST/PATCH RouteStages。禁止直接调用写请求。

3. 工位排产与日期回写

页面入口：计划排产 > 工位任务汇总。

1. 使用生产订单、销售订单、物料和工序等条件筛选任务。
2. 切换至“日程”视图，选择待排产任务并调整计划开始、计划完成日期。
3. 在 MES 完成排产；关闭订单时须进入计划排产的订单关闭页面执行确认。

接口触发：排产和订单关闭均使用 B1 PATCH ProductionOrders(订单号)。禁止直接调用。

4. 外协派工

页面入口：生产管理 > 外协管理，或采购外协管理。

1. 按生产订单、供应商或工序查询待派工记录。
2. 选择待派工行，填写或确认派工数量、仓库和计划日期。
3. 在页面点击“派工并同步 SAP”，由 MES 创建对应采购申请。

接口触发：B1 POST PurchaseRequests，行项目含物料、数量、仓库、订单号和工序。禁止直接调用。

5. 加工/装配领料条码任务

页面入口：生产管理 > 加工中心或装配中心。

1. 按生产订单筛选并选中当前加工或装配任务。
2. 点击“领料”，在弹窗中核对生产订单物料明细、批次、仓库和数量。
3. 确认后由 MES 创建条码出库任务；在 TM 端按条码任务继续执行。

接口触发：明细读取为 B1 GET ProductionOrders；TM 出库任务为 POST stocktask/task/issueordertask。禁止直接调用写请求。

6. 工时校验与 SAP 生产反馈

页面入口：生产管理 > 工时校验。

1. 按任务 ID、生产订单、操作人、时间范围和校验状态查询报工记录。
2. 选中待处理记录后使用“一键校验”；仅在业务授权的情况下使用“直接校验”。
3. 由 MES 根据校验结果更新订单工序并提交资源报工反馈，不在 Postman 重放请求。

接口触发：B1 GET ProductionOrders，以及 PATCH ProductionOrders、POST InventoryGenExits。禁止直接调用写请求。

7. 序检收检与采购收货

页面入口：质量管理 > 序检收检。

1. 切换至“序检收检”页签，按生产订单、物料、检验结果或状态查询。
2. 选择待收检任务，点击该行“收检”，在收检界面填写合格数量等结果。
3. 提交后由系统匹配采购订单行并生成采购收货单。

接口触发：B1 POST QueryService_PostQuery 查询采购订单行，随后 POST PurchaseDeliveryNotes 收货。两项均禁止直接调用。

8. 退库质检与条码入库

页面入口：质量管理 > 原材料退库检验。

1. 按单据码、生产订单、物料和检验状态查询待处理记录，点击行内“退库检”。
2. 录入合格数量和批次信息，确认退库质检结论。
3. 系统读取生产订单行号后创建 TM 入库任务，TM 端扫码完成实物入库。

接口触发：B1 GET ProductionOrders 取得行号；TM POST stocktask/task/receiptordertask 创建入库任务。禁止直接调用写请求。

9.3 可直接提交的 Postman 请求体

以下请求体用于识别实际页面参数。仅标记为 func=GET 的请求可在 Postman 的 Body / raw / JSON 中执行；所有 func=POST、func=PATCH 请求均禁止调用。

// 1. B1：查询生产订单，供领料、工时校验、退库页面使用
POST {{mes_b1_gateway}}
{
  "func": "GET",
  "cmd": "ProductionOrders",
  "content": "{\"$filter\":\"AbsoluteEntry eq 7316\"}"
}

// 禁止调用（func=POST）：B1 新增工位资源
POST {{mes_b1_gateway}}
{
  "func": "POST",
  "cmd": "Resources",
  "content": "{\"VisCode\":\"WC-001\",\"Name\":\"测试工位\",\"ForeignName\":\"\",\"Type\":\"rtMachine\",\"Group\":1,\"UnitOfMeasure\":\"\",\"IssueMethod\":\"rimManual\",\"Active\":\"tYES\",\"Inactive\":\"tNO\",\"Remarks\":\"\",\"Allocation\":\"raOnStartDate\"}"
}

// 禁止调用（func=PATCH）：B1 更新工位名称
POST {{mes_b1_gateway}}
{
  "func": "PATCH",
  "cmd": "Resources('WC-001')",
  "content": "{\"Name\":\"测试工位（已更新）\"}"
}

// 4. B1：按工艺代码查询，再用返回的 InternalNumber 更新
POST {{mes_b1_gateway}}
{
  "func": "GET",
  "cmd": "RouteStages",
  "content": "{\"$filter\":\"Code eq '10'\"}"
}

// 禁止调用（func=PATCH）：B1 更新工艺阶段
POST {{mes_b1_gateway}}
{
  "func": "PATCH",
  "cmd": "RouteStages(10)",
  "content": "{\"Description\":\"装配\",\"DateOfUpdate\":\"2026-08-03\"}"
}

// 禁止调用（func=PATCH）：B1 排产日期回写生产订单
POST {{mes_b1_gateway}}
{
  "func": "PATCH",
  "cmd": "ProductionOrders(7316)",
  "content": "{\"AbsoluteEntry\":7316,\"U_MODueDate\":\"2026-08-10\",\"U_MOStartDate\":\"2026-08-05\",\"U_YJQTdate\":\"2026-08-05\"}"
}

// 禁止调用（func=PATCH）：B1 关闭生产订单
POST {{mes_b1_gateway}}
{
  "func": "PATCH",
  "cmd": "ProductionOrders(7316)",
  "content": "{\"AbsoluteEntry\":7316,\"ProductionOrderStatus\":\"boposClosed\"}"
}

// 禁止调用（func=POST）：B1 装配派工创建采购申请
POST {{mes_b1_gateway}}
{
  "func": "POST",
  "cmd": "PurchaseRequests",
  "content": "{\"ReqType\":12,\"Requester\":\"SAPJK001\",\"PriceMode\":\"G\",\"RequesterBranch\":-2,\"RequesterDepartment\":-2,\"DocDate\":\"2026-08-03\",\"DocDueDate\":\"2026-08-03\",\"TaxDate\":\"2026-08-03\",\"RequriedDate\":\"2026-08-03\",\"Comments\":\"MES派工\",\"DocumentLines\":[{\"ItemCode\":\"108-001\",\"Quantity\":1,\"WarehouseCode\":\"W03\",\"U_WWOworID\":7316}]}"
}

// 禁止调用（func=POST）：B1 外协派工创建采购申请（增加工序关联字段）
POST {{mes_b1_gateway}}
{
  "func": "POST",
  "cmd": "PurchaseRequests",
  "content": "{\"ReqType\":12,\"Requester\":\"SAPJK001\",\"PriceMode\":\"G\",\"RequesterBranch\":-2,\"RequesterDepartment\":-2,\"DocDate\":\"2026-08-03\",\"DocDueDate\":\"2026-08-03\",\"TaxDate\":\"2026-08-03\",\"RequriedDate\":\"2026-08-10\",\"Comments\":\"MES外协派工\",\"DocumentLines\":[{\"ItemCode\":\"108-001\",\"Quantity\":3,\"WarehouseCode\":\"W03\",\"U_WWOworID\":7316,\"U_WWOrst\":\"外协工序\",\"U_WWOrstHS\":\"最后工序\",\"U_WWOrstID\":999}]}"
}

// 禁止调用（func=POST）：B1 工时校验的生产反馈，DocumentLines 必须来自已查询到的 SAP 订单行
POST {{mes_b1_gateway}}
{
  "func": "POST",
  "cmd": "InventoryGenExits",
  "content": "{\"DocDate\":\"2026-08-03\",\"DocDueDate\":\"2026-08-03\",\"Comments\":\"MES报工 AID:12345\",\"DocumentLines\":[{\"Quantity\":1.5,\"BaseType\":202,\"BaseEntry\":7316,\"BaseLine\":2,\"LineType\":\"dlt_Resource\",\"WarehouseCode\":\"\",\"U_ResName\":\"数控车床A\"}]}"
}

// 禁止调用（func=POST）：B1 外协收检前查询采购订单及行项目
POST {{mes_b1_gateway}}
{
  "func": "POST",
  "cmd": "QueryService_PostQuery",
  "content": "{\"QueryPath\":\"$crossjoin(PurchaseOrders,PurchaseOrders/DocumentLines)\",\"QueryOption\":\"$expand=PurchaseOrders($select=DocEntry,DocNum,CardCode,CardName),PurchaseOrders/DocumentLines($select=ItemCode,LineNum,Price,U_WWOworID,U_WWOrstHS,LineStatus)&$filter=PurchaseOrders/DocEntry eq PurchaseOrders/DocumentLines/DocEntry and PurchaseOrders/DocumentLines/U_WWOworID eq 7316\"}"
}

// 禁止调用（func=POST）：B1 外协收检创建采购收货单
POST {{mes_b1_gateway}}
{
  "func": "POST",
  "cmd": "PurchaseDeliveryNotes",
  "content": "{\"CardCode\":\"V001\",\"CardName\":\"供应商名称\",\"DocDate\":\"2026-08-03\",\"DocumentLines\":[{\"BaseEntry\":100,\"BaseLine\":0,\"BaseType\":22,\"Quantity\":5,\"U_WWPassedQty\":0}]}"
}

// 禁止调用（func=POST）：TM 创建领料出库任务
POST {{mes_tm_gateway}}
{
  "func": "POST",
  "cmd": "stocktask/task/issueordertask",
  "content": "{\"doc_date\":\"2026-08-03\",\"doc_type\":\"202-60\",\"external_num\":7316,\"task_items\":[{\"base_type\":\"202\",\"base_entry\":7316,\"base_line_num\":2,\"external_num\":7316,\"item_code\":\"ITEM-001\",\"item_name\":\"物料名称\",\"line_memo\":\"MES领料\",\"whs_code\":\"\",\"manage_type\":\"B\",\"price\":0,\"quantity\":2}]}"
}

// 禁止调用（func=POST）：TM 创建不合格品/退库入库任务
POST {{mes_tm_gateway}}
{
  "func": "POST",
  "cmd": "stocktask/task/receiptordertask",
  "content": "{\"doc_date\":\"2026-08-03\",\"doc_type\":\"202-59\",\"external_num\":7316,\"task_items\":[{\"base_type\":\"202\",\"base_entry\":7316,\"base_line_num\":2,\"external_num\":7316,\"item_code\":\"ITEM-001\",\"item_name\":\"物料名称\",\"whs_code\":\"\",\"manage_type\":\"B\",\"price\":0,\"quantity\":1}]}"
}

TM 返回为 { code, data, message }；B1 返回为网关透传的 Service Layer 响应。上面的请求体只用于已具备业务权限的测试/联调环境，订单号、行号、供应商、资源和物料均必须先从业务数据或前置查询结果获得。