API 参考 (API Reference)¶

基础 URL: /api

所有接口都需要通过 X-User-Token 请求头进行身份验证 (来自 MSAL 的 JWT)。

采购订单 (Purchase Orders)¶

获取采购订单列表¶

GET /api/purchase-orders

查询参数:

参数	类型	描述
status	string	按状态标签过滤 (例如: "New", "Pending Approval")
vendor	string	按供应商公司名称过滤
search	string	搜索 PO 编号、款号 (style) 或 SKU
limit	number	每页结果数 (默认: 50)
page	number	页码 (默认: 1)
sortField	string	排序字段: id, vendor, poDate, xfDate, status, amount
sortDir	string	排序方向: asc, desc

响应 (Response): { data: [...], pagination: { total, page, limit, totalPages } }

获取单个采购订单¶

GET /api/purchase-orders/{poRef}

响应: 完整的 PO 详情，包括原始值和供应商答复值。

关键字段:

字段	描述
originalXfd	来自 Cin7 的原始离厂日期 (ex-factory date)
vendorReplyXfd	供应商建议的离厂日期
xfDate	计算值: COALESCE(vendorReplyXfd, originalXfd)
statusId	整数状态 ID (100, 150, 200, 等)
status	英文状态标签
statusZh	中文状态标签
statusColor	状态徽章的十六进制颜色
hasPendingChanges	供应商是否已进行编辑

更新采购订单头信息¶

PATCH /api/purchase-orders/{poRef}
Body: { vendor_reply_xfd, vendor_reply_factory, vendor_reply_comment, container_number, tracking_number }

获取订单项 (Line Items)¶

GET /api/purchase-orders/{poRef}/line-items

响应: 按 (code, style, color) 分组的汇总订单项数组。

每个订单项包含:

{
    "code": "VENITA-CML",
    "style": "VENITA",
    "color": "CML",
    "unitPrice": 5.33,
    "originalUnitPrice": 5.33,
    "vendorReplyUnitPrice": null,
    "sizes": {
        "6M": { "qty": 200, "originalQty": 200, "vendorReplyQty": null, "rowHash": "abc123", "lineId": "1" }
    },
    "totalQty": 1200,
    "originalTotalQty": 1200,
    "totalAmount": 6396.00,
    "isModified": false
}

更新订单项¶

PATCH /api/purchase-orders/{poRef}/line-items
Body: { lines: [{ rowHash: "abc123", vendorReplyQty: 250 }] }

工作流转换 (Workflow Transitions)¶

执行转换¶

POST /api/purchase-orders/{poRef}/transition
Body: { "action": "SUBMIT", "comment": "optional comment" }

可用操作 (Actions): SUBMIT, APPROVE, REJECT, RECALL, MOVE_TO_PRODUCTION, MARK_SHIPPED, CONFIRM_DELIVERY, CANCEL

响应:

{
    "success": true,
    "newStatusId": 200,
    "newStatus": "Pending Approval",
    "message": "Transition SUBMIT completed"
}

获取可用操作¶

GET /api/lookups/actions?statusId=100&role=Vendor

响应: 给定状态和角色下有效的转换数组。

获取 PO 历史记录¶

GET /api/purchase-orders/{poRef}/history

响应: 转换日志条目数组。

通知 (Notifications)¶

获取用户通知¶

GET /api/notifications

响应: 从 App_Notifications 映射并与 Log_PO_History 连接的通知数组。

将通知标记为已读¶

PUT /api/notifications/{id}/read

参数: 使用 {id} = "all" 将当前用户的所有通知标记为已读。

响应: { success: true }

仪表板 (Dashboard)¶

KPI 统计¶

GET /api/dashboard/kpis