云桥杯 / 赛事资源 / 元器件供应链接口参考

API REFERENCE

元器件供应链接口参考

按需查阅参数、返回字段和业务规则，可用于万智插件或自己的程序。

本页目录

先领取账号，再选择接入方式在万智中使用（可选）1. 通用说明 1.1 基础地址 1.2 认证方式 1.3 统一响应格式 1.4 租户隔离 1.5 已知限制与 ID 使用说明 1.6 常见错误 2. Products — 商品 2.1 模块说明 2.2 分页查询商品 3. Orders — 销售订单 3.1 模块说明 3.2 分页查询销售订单 3.3 查询销售订单详情 3.4 随机生成销售订单 3.5 手工创建销售订单 4. Purchases — 采购单 4.1 模块说明 4.2 分页查询采购单 4.3 查询采购单详情 5. Suppliers — 供应商 5.1 模块说明 5.2 查询供应商列表 5.3 查询供应商详情 6. 本届可写范围与能力边界 7. 数据生命周期与资源使用说明 8. 接口速查表 9. 万智平台对接示例使用与核验提醒下载与相关说明

本页按技术团队最新接口文档整理，完整保留参数、响应与业务限制。“实测”指技术团队的核验记录。示例中的公司、姓名、电话与地址为演示记录，不用于联系。

先领取账号，再选择接入方式

元器件供应链后台账号请联系赛事群里的技术人员楼亮按需领取，建议 C（供应链与运营管理）方向按项目需要领取。登录后台查看数据并获取、核对本队伍编码后，再选择用万智插件还是自己的程序调用 API。这里用 X-Api-Key 携带队伍编码，不使用模拟工厂的 Bearer Token。插件是可选方式；下面介绍插件配置，代码调用可直接查阅后续接口说明。

在万智中使用（可选）

进入工具箱 → 插件中心 → 通过 API 创建，选择元器件内置模板。鉴权选择“请求头”，前缀 Custom，键 X-Api-Key，值填在元器件后台获取并核对的本队伍编码。无需其他队伍身份请求头，也不要改用 Bearer 或大模型 API Key。元器件 API 地址由赛事助手按队伍发放，不能从网页后台地址推断。

本包的 components-openapi.json 是根据最新技术文档修订的配套描述，并非平台原样导出；已补全成功响应的 code/msg/data 包装。创建自定义插件前，必须把 servers 中的占位地址替换为本队获发的 API 地址。内置模板仍须核对服务地址、鉴权、响应后测试保存，再添加到应用。

商品、销售订单、采购单列表读取 data.items，供应商列表读取 data 数组；工厂列表则读取顶层 rows，两者不同。供应商或采购单为 0 条不一定是接口失败，可请赛事群里的技术人员楼亮协助核对本队预置数据。

涵盖模块：Products（商品）、Orders（销售订单）、Purchases（采购单）、Suppliers（供应商）

技术团队已逐项实测全部端点。

1. 通用说明

1.1 基础地址

环境	Base URL
比赛环境	`{{COMPONENTS_API_BASE_URL}}`（由赛事助手按参赛队伍分发，以分发值为准）

所有接口路径均以 /api 开头，例如：GET /api/products。

注意：网页后台地址（如 121.229.160.47:8888）是网页管理端入口，不能据此推断 API 地址。

1.2 认证方式

以下四个模块的接口均需要认证（[Authorize]），插件对接使用方式 A：

方式 A：X-Api-Key 队伍编码（适用于万智插件及代码对接）

X-Api-Key: {{COMPONENTS_TEAM_CODE}}

请求头	必填	说明
`X-Api-Key`	是	本队伍编码，领取后台账号后登录元器件后台获取并核对；队伍身份与租户绑定，仅可访问本队数据

填写说明

- X-Api-Key 的值就是在元器件后台获取并核对的本队伍编码，与《万智插件配置说明文档》的插件配置一致（鉴权类型"请求头" + 前缀"Custom" + 键 X-Api-Key，值填队伍编码）。

- 队伍身份由 X-Api-Key 中的队伍编码直接识别，无需其他请求头。

- 队伍编码与租户绑定，仅可访问本队数据，不能跨租户访问其他队伍的数据。

方式 B：Cookie（仅适用于网页后台浏览器登录）

1. 在网页后台登录页登录后，浏览器自动携带 Cookie

2. 插件 / 代码对接不使用本方式

1.3 统一响应格式

所有业务接口均统一包装为：

{
  "code": 200,
  "msg": "success",
  "data": { }
}

字段	类型	说明
`code`	int	业务状态码。`200` 表示成功；`400/401/403/404` 等表示失败
`msg`	string	提示信息。成功时为 `"success"`；失败时为具体错误说明
`data`	object / array / null	业务数据。失败时通常为 `null`

注意：顶层 code 是数字状态码，与业务编码（如 supplierCode）不同，避免与万智等平台框架冲突。

1.4 租户隔离

所有查询、创建操作均限定在当前租户（参赛队伍）范围内
通过 Cookie 登录时，租户由登录账号决定
通过 X-Api-Key 队伍编码对接时，租户由队伍编码决定
不能跨租户访问其他租户的数据

1.5 已知限制与 ID 使用说明

1. 空返回：失败时 data 为 null；部分成功场景 data 也可能为 null，判定时请结合 code 与 msg，不要仅凭 data 是否为空下结论。

2. ID 原值保留：所有 ID 请以接口返回的原值使用；长整型 ID 在 JS/JSON 解析中可能发生精度丢失，建议按字符串处理，不要转为数值运算后再回传。

3. 结果核验：写操作（创建销售订单）执行后，须通过查询接口或网页后台核对后台保存的结果后再汇报。

1.6 常见错误

HTTP 状态	code	msg 示例	说明
401	—	（响应体为空，非 JSON 包装）	未携带或错误的 `X-Api-Key`（实测）
403	403	无权限	无访问权限
404	404	资源不存在	订单/采购单/供应商 ID 不存在
400	400	具体校验信息	参数校验失败、业务规则不满足

失败响应示例：

{
  "code": 400,
  "msg": "请至少添加一条商品明细",
  "data": null
}

2. Products — 商品

2.1 模块说明

查询当前租户下的商品目录，包含库存、最小起订量（MOQ）和 6 档含税阶梯价。

各队伍租户预置约 1500 个商品
阶梯价起始数量固定为：5 / 50 / 150 / 500 / 2500 / 5000
数量越大，单价越低

2.2 分页查询商品

GET /api/products

请求参数（Query）

参数	类型	必填	默认值	说明
`keyword`	string	否	—	关键字，模糊匹配型号、品牌、封装、参数、分类
`page`	int	否	1	页码，从 1 开始
`pageSize`	int	否	20	每页条数。建议 ≤50；实测超出 50 亦可正常返回（核验，未严格限制上限）

响应 `data` 结构：`PagedResult<ProductListItemDto>`

字段	类型	说明
`items`	array	当前页商品列表
`total`	int	符合条件的总条数
`page`	int	当前页码
`pageSize`	int	每页条数

ProductListItemDto（商品列表项）

字段	类型	说明
`id`	int	商品编号（租户内唯一）
`partNumber`	string	型号
`brand`	string	品牌
`package`	string	封装
`specification`	string	参数描述
`category`	string	分类，如：电阻、电容、电感、二极管、晶体管、其他
`stock`	int	库存数量（模拟数据，只读）
`moq`	int	最小起订量 Minimum Order Quantity
`prices`	array	阶梯价列表，按 `minQuantity` 升序，共 6 档

PriceTierDto（阶梯价）

字段	类型	说明
`minQuantity`	int	阶梯起始数量（含）。采购数量 ≥ 该值且 < 下一档时，使用本档单价
`unitPrice`	decimal	含税单价，保留 4 位小数

请求示例

GET {{COMPONENTS_API_BASE_URL}}/api/products?keyword=0603&page=1&pageSize=10
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 101,
        "partNumber": "0603AF-102XJRW",
        "brand": "Vishay",
        "package": "0603",
        "specification": "1kΩ ±1% 1/10W 厚膜电阻",
        "category": "电阻",
        "stock": 12500,
        "moq": 5,
        "prices": [
          { "minQuantity": 5,    "unitPrice": 0.0520 },
          { "minQuantity": 50,   "unitPrice": 0.0425 },
          { "minQuantity": 150,  "unitPrice": 0.0377 },
          { "minQuantity": 500,  "unitPrice": 0.0341 },
          { "minQuantity": 2500, "unitPrice": 0.0313 },
          { "minQuantity": 5000, "unitPrice": 0.0298 }
        ]
      }
    ],
    "total": 42,
    "page": 1,
    "pageSize": 10
  }
}

阶梯价匹配规则

给定采购数量 quantity，取满足 quantity >= minQuantity 的最大一档作为命中价：

数量 3 → 取第 1 档（minQuantity=5 的单价，因无更低档）
数量 100 → 取 minQuantity=50 的档
数量 5000 → 取 minQuantity=5000 的档

行金额 = unitPrice × quantity，四舍五入保留 4 位小数。

3. Orders — 销售订单

3.1 模块说明

销售订单（卖给客户）的查询与创建。与采购单为独立业务，互不影响。

订单状态枚举

编码 `status`	中文 `statusText`	说明
`Draft`	草稿	初始状态
`PendingConfirm`	待确认	等待客户确认
`Confirmed`	已确认	已确认待生产
`InProduction`	生产中	正在生产
`Shipped`	已发货	已发出，可能有物流单号
`Completed`	已完成	交易完成
`Cancelled`	已取消	已取消

订单号规则：SO + yyyyMMdd + 3 位流水，例如 SO20260929001。

3.2 分页查询销售订单

GET /api/orders

请求参数（Query）

参数	类型	必填	默认值	说明
`keyword`	string	否	—	模糊匹配订单号、客户名称、联系人
`status`	string	否	—	状态编码，见上表。大小写不敏感
`page`	int	否	1	页码
`pageSize`	int	否	20	每页条数，1～50

响应 `data` 结构：`PagedResult<OrderListItemDto>`

OrderListItemDto（订单列表项）

字段	类型	说明
`id`	int	订单编号
`orderNo`	string	销售订单号
`status`	string	状态编码
`statusText`	string	状态中文名
`customerName`	string	客户名称
`contactName`	string	联系人
`totalAmount`	decimal	含税总额
`lineCount`	int	明细条数
`createdAt`	datetime	创建时间，ISO 8601 格式

请求示例

GET {{COMPONENTS_API_BASE_URL}}/api/orders?status=Confirmed&page=1&pageSize=20
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 12,
        "orderNo": "SO20260912003",
        "status": "Confirmed",
        "statusText": "已确认",
        "customerName": "深圳智控科技有限公司",
        "contactName": "张伟",
        "totalAmount": 15832.5600,
        "lineCount": 45,
        "createdAt": "2026-09-12T14:23:01"
      }
    ],
    "total": 12,
    "page": 1,
    "pageSize": 20
  }
}

3.3 查询销售订单详情

GET /api/orders/{id}

路径参数

参数	类型	说明
`id`	int	销售订单编号

响应 `data` 结构：`OrderDetailDto`

字段	类型	说明
`id`	int	订单编号
`orderNo`	string	销售订单号
`status`	string	状态编码
`statusText`	string	状态中文名
`customerName`	string	客户名称
`contactName`	string	联系人
`contactPhone`	string	联系电话
`shippingAddress`	string	收货地址
`remark`	string?	备注，可空
`trackingNo`	string?	物流单号。状态为 Shipped/Completed 时可能有值
`totalAmount`	decimal	含税总额
`createdAt`	datetime	创建时间
`lines`	array	订单明细列表

OrderLineDto（订单明细）

字段	类型	说明
`id`	int	明细编号
`productId`	int	商品编号
`partNumber`	string	型号（下单时快照）
`brand`	string	品牌
`package`	string	封装
`category`	string	分类
`quantity`	int	销售数量
`priceMinQuantity`	int	命中的阶梯起始数量
`unitPrice`	decimal	含税单价
`amount`	decimal	行含税金额 = unitPrice × quantity

请求示例

GET {{COMPONENTS_API_BASE_URL}}/api/orders/12
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 12,
    "orderNo": "SO20260912003",
    "status": "Confirmed",
    "statusText": "已确认",
    "customerName": "深圳智控科技有限公司",
    "contactName": "张伟",
    "contactPhone": "13812345678",
    "shippingAddress": "深圳市南山区科技园南路88号",
    "remark": "加急，优先安排",
    "trackingNo": null,
    "totalAmount": 15832.5600,
    "createdAt": "2026-09-12T14:23:01",
    "lines": [
      {
        "id": 301,
        "productId": 101,
        "partNumber": "0603AF-102XJRW",
        "brand": "Vishay",
        "package": "0603",
        "category": "电阻",
        "quantity": 500,
        "priceMinQuantity": 500,
        "unitPrice": 0.0341,
        "amount": 17.0500
      }
    ]
  }
}

错误

场景	code	msg
订单不存在或不属于当前租户	404	订单不存在

3.4 随机生成销售订单

POST /api/orders/random

说明

无需请求体
服务端自动生成：客户名称、联系人、电话、地址、备注、状态
随机抽取 30～70 条不重复商品作为明细
每条明细数量随机（5～12000 不等），单价按阶梯价自动匹配
状态为 Shipped/Completed 时自动生成顺丰格式物流单号

响应 `data` 结构

同 OrderDetailDto（见 3.3）。

请求示例

POST {{COMPONENTS_API_BASE_URL}}/api/orders/random
X-Api-Key: {{COMPONENTS_TEAM_CODE}}
Content-Length: 0

错误

场景	code	msg 示例
当前租户商品不足 30 个	400	当前租户商品不足，无法生成随机订单

3.5 手工创建销售订单

POST /api/orders
Content-Type: application/json

说明

按传入内容创建订单和明细
不扣库存，不做状态流转（仅写入数据）
单价由服务端按阶梯价计算，不接受调用方传价
同一商品不能出现在多行，需合并数量

请求体：`CreateOrderRequest`

字段	类型	必填	说明
`customerName`	string	是	客户名称，1～100 字符
`contactName`	string	是	联系人，1～50 字符
`contactPhone`	string	是	联系电话，1～30 字符
`shippingAddress`	string	是	收货地址，1～200 字符
`remark`	string	否	备注，最长 500 字符
`status`	string	否	状态编码，默认 `Draft`
`lines`	array	是	明细，1～50 行

CreateOrderLineRequest（明细行）

字段	类型	必填	说明
`productId`	int	是	当前租户下的商品编号
`quantity`	int	是	销售数量，必须 > 0

请求示例

{
  "customerName": "杭州博联仪器有限公司",
  "contactName": "李娜",
  "contactPhone": "13900001111",
  "shippingAddress": "杭州市滨江区创新大道66号",
  "remark": "按阶梯价结算",
  "status": "Draft",
  "lines": [
    { "productId": 101, "quantity": 500 },
    { "productId": 205, "quantity": 1000 }
  ]
}

响应

成功时 data 为完整 OrderDetailDto。

常见错误 msg

msg	原因
请填写客户名称	customerName 为空或超长
请填写联系人	contactName 为空或超长
请填写联系电话	contactPhone 为空或超长
请填写收货地址	shippingAddress 为空或超长
备注过长	remark 超过 500 字符
请至少添加一条商品明细	lines 为空或超过 50 行
数量必须大于 0	某行 quantity ≤ 0
同一商品请合并到一行	lines 中有重复 productId
订单状态不正确	status 不在枚举范围内
包含不属于当前租户的商品	productId 无效
{型号} 没有阶梯价	商品缺少价格数据

4. Purchases — 采购单

4.1 模块说明

采购单（向供应商进货）的查询。与销售订单独立，由种子数据预生成（实测注意：核验时 test1 租户采购单为 0 条，见 5.1）。

采购单状态枚举

编码 `status`	中文 `statusText`	说明
`Draft`	草稿	初始状态
`PendingReview`	待审核	等待审核
`Approved`	已审核	审核通过
`Purchasing`	采购中	正在采购
`PartialReceived`	部分到货	部分商品已到货
`Completed`	已完成	全部到货
`Cancelled`	已取消	已取消

采购单号规则：PO + yyyyMMdd + 3 位流水，例如 PO20260915002。

当前版本采购单为只读（仅查询），不提供创建/修改接口。

4.2 分页查询采购单

GET /api/purchases

请求参数（Query）

参数	类型	必填	默认值	说明
`keyword`	string	否	—	模糊匹配采购单号、供应商名称、采购员
`status`	string	否	—	状态编码，见上表
`page`	int	否	1	页码
`pageSize`	int	否	20	每页条数，1～50

响应 `data` 结构：`PagedResult<PurchaseListItemDto>`

PurchaseListItemDto（采购单列表项）

字段	类型	说明
`id`	int	采购单编号
`purchaseNo`	string	采购单号
`status`	string	状态编码
`statusText`	string	状态中文名
`supplierName`	string	供应商名称
`buyerName`	string	采购员
`totalAmount`	decimal	含税总额
`lineCount`	int	明细条数
`createdAt`	datetime	创建时间

请求示例

GET {{COMPONENTS_API_BASE_URL}}/api/purchases?keyword=PO20260915002&status=Completed
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 5,
        "purchaseNo": "PO20260915002",
        "status": "Completed",
        "statusText": "已完成",
        "supplierName": "深圳芯源电子有限公司",
        "buyerName": "王强",
        "totalAmount": 8234.1200,
        "lineCount": 18,
        "createdAt": "2026-09-15T09:10:33"
      }
    ],
    "total": 8,
    "page": 1,
    "pageSize": 20
  }
}

4.3 查询采购单详情

GET /api/purchases/{id}

路径参数

参数	类型	说明
`id`	int	采购单编号

响应 `data` 结构：`PurchaseDetailDto`

字段	类型	说明
`id`	int	采购单编号
`purchaseNo`	string	采购单号
`status`	string	状态编码
`statusText`	string	状态中文名
`supplierId`	int	供应商编号
`supplierName`	string	供应商名称
`buyerName`	string	采购员
`contactName`	string	联系人
`contactPhone`	string	联系电话
`deliveryAddress`	string	到货地址
`remark`	string?	备注
`totalAmount`	decimal	含税总额
`createdAt`	datetime	创建时间
`lines`	array	采购明细

PurchaseLineDto（采购明细）

字段	类型	说明
`id`	int	明细编号
`productId`	int	商品编号
`partNumber`	string	型号
`brand`	string	品牌
`package`	string	封装
`quantity`	int	采购数量
`receivedQuantity`	int	已到货数量
`priceMinQuantity`	int	命中的阶梯起始数量
`unitPrice`	decimal	含税单价
`amount`	decimal	行含税金额

请求示例

GET {{COMPONENTS_API_BASE_URL}}/api/purchases/5
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

错误

场景	code	msg
采购单不存在	404	采购单不存在（或不属于当前租户）

5. Suppliers — 供应商

5.1 模块说明

查询当前租户下的供应商及其关联采购单。

设计预置 6 家供应商：SUP001～SUP006
供应商编码字段为 supplierCode（非顶层 code，避免与响应状态码冲突）
列表接口返回各供应商关联的采购单数量

实测注意：核验时 test1 租户的供应商为 0 家、采购单为 0 条（种子数据可能未装载或已被清理）。如你所在租户与预期不符，请联系赛事助手确认种子数据状态。

5.2 查询供应商列表

GET /api/suppliers

请求参数（Query）

参数	类型	必填	说明
`keyword`	string	否	模糊匹配供应商编码、名称、联系人、电话

本接口不分页，返回全部匹配结果，按 supplierCode 升序排列。

响应 `data` 结构：`SupplierListItemDto[]`

SupplierListItemDto（供应商列表项）

字段	类型	说明
`id`	int	供应商编号
`supplierCode`	string	供应商编码，如 `SUP001`。同一租户内唯一
`name`	string	供应商名称
`contactName`	string	联系人
`phone`	string	联系电话
`address`	string	地址
`purchaseCount`	int	关联采购单数量

请求示例

GET {{COMPONENTS_API_BASE_URL}}/api/suppliers
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

响应示例

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "supplierCode": "SUP001",
      "name": "深圳芯源电子有限公司",
      "contactName": "陈工",
      "phone": "13800001001",
      "address": "深圳市福田区华强北模拟路 18 号",
      "purchaseCount": 2
    },
    {
      "id": 2,
      "supplierCode": "SUP002",
      "name": "苏州恒拓元器件有限公司",
      "contactName": "周敏",
      "phone": "13800001002",
      "address": "苏州市工业园区星湖街 88 号",
      "purchaseCount": 2
    }
  ]
}

预置供应商一览

（设计预置清单，实际以各租户当前数据为准——见 5.1 实测注意）

supplierCode	名称	联系人
SUP001	深圳芯源电子有限公司	陈工
SUP002	苏州恒拓元器件有限公司	周敏
SUP003	上海浦江半导体有限公司	刘洋
SUP004	东莞联科电子有限公司	吴凯
SUP005	北京中科物料有限公司	赵琳
SUP006	无锡瑞达供应链有限公司	孙浩

5.3 查询供应商详情

GET /api/suppliers/{id}

路径参数

参数	类型	说明
`id`	int	供应商编号

响应 `data` 结构：`SupplierDetailDto`

字段	类型	说明
`id`	int	供应商编号
`supplierCode`	string	供应商编码
`name`	string	供应商名称
`contactName`	string	联系人
`phone`	string	联系电话
`address`	string	地址
`purchases`	array	该供应商下的采购单列表（`PurchaseListItemDto`，按创建时间倒序）

请求示例

GET {{COMPONENTS_API_BASE_URL}}/api/suppliers/1
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

响应示例

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "supplierCode": "SUP001",
    "name": "深圳芯源电子有限公司",
    "contactName": "陈工",
    "phone": "13800001001",
    "address": "深圳市福田区华强北模拟路 18 号",
    "purchases": [
      {
        "id": 5,
        "purchaseNo": "PO20260915002",
        "status": "Completed",
        "statusText": "已完成",
        "supplierName": "深圳芯源电子有限公司",
        "buyerName": "王强",
        "totalAmount": 8234.1200,
        "lineCount": 18,
        "createdAt": "2026-09-15T09:10:33"
      }
    ]
  }
}

错误

场景	code	msg
供应商不存在	404	供应商不存在

6. 本届可写范围与能力边界

本届官方接口的可写范围（除此以外均为只读查询）：

接口	效果
`POST /api/orders`	手工创建销售订单（仅写入数据，不扣库存、不触发状态流转）
`POST /api/orders/random`	随机生成一张销售订单

能力边界：

采购单当前版本为只读，不提供创建/修改接口；商品库存、供应商数据亦为只读。
接口不承诺自动完成真实采购执行或库存联动；缺料测算、补货建议等业务逻辑须由参赛团队自行实现（如用代码解释器执行 Python 完成）。
采购执行、状态联动等效果须由参赛团队自行实现，不属于官方接口交付内容。

7. 数据生命周期与资源使用说明

元器件数据按参赛队伍租户隔离；自建测试数据建议以 测试- 前缀命名，便于识别与赛后清理。
赛后数据由赛事助手统一清理/重置；选手不得假设数据长期保存、可随时导出、任意重置或恢复。
数据保存期限、导出范围与赛后复用规则以赛事助手的正式通知为准，本文档不作预设。

8. 接口速查表

模块	方法	路径	说明
Products	GET	`/api/products`	分页查询商品及阶梯价
Orders	GET	`/api/orders`	分页查询销售订单
Orders	GET	`/api/orders/{id}`	销售订单详情
Orders	POST	`/api/orders/random`	随机生成销售订单
Orders	POST	`/api/orders`	手工创建销售订单
Purchases	GET	`/api/purchases`	分页查询采购单
Purchases	GET	`/api/purchases/{id}`	采购单详情
Suppliers	GET	`/api/suppliers`	查询供应商列表
Suppliers	GET	`/api/suppliers/{id}`	供应商详情及采购单

9. 万智平台对接示例

以下示例适用于万智等只识别顶层数字 code: 200 的测试框架：

### 1. 查供应商（验证 supplierCode 与 code:200）
GET {{COMPONENTS_API_BASE_URL}}/api/suppliers
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

### 2. 查商品
GET {{COMPONENTS_API_BASE_URL}}/api/products?page=1&pageSize=5
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

### 3. 查销售订单
GET {{COMPONENTS_API_BASE_URL}}/api/orders?page=1&pageSize=5
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

### 4. 查采购单
GET {{COMPONENTS_API_BASE_URL}}/api/purchases?page=1&pageSize=5
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

### 5. 随机生成一张订单
POST {{COMPONENTS_API_BASE_URL}}/api/orders/random
X-Api-Key: {{COMPONENTS_TEAM_CODE}}

期望成功响应格式：

{
  "code": 200,
  "msg": "success",
  "data": { }
}

使用与核验提醒

先调用只读列表，与网页后台核对。工厂 HTTP 200 仍可能是业务 code=401；元器件鉴权失败可能是 HTTP 401 空响应体。
工厂详情 data=null 是已知行为。查业务记录请用列表；新增订单后还应核对记录内容，避免仅把第一行当作自己创建的数据。
两个系统分页不同：工厂 pageNum/pageSize，返回顶层 rows/total；元器件 page/pageSize，返回 data.items/total/page/pageSize；供应商列表不分页。读取完整数据要翻页。
写操作后查询确认实际结果，不把 code=200 当作采购执行或业务效果已完成。元器件采购、库存和供应商只读，创建销售订单不扣库存、不推进状态。
工厂数据随时间变化，查询结果应标明查询时间。真实密码和 Token 只填写到私有鉴权配置，不写进公开作品或截图。

元器件供应链接口参考

先领取账号，再选择接入方式

在万智中使用（可选）

1. 通用说明

1.1 基础地址

1.2 认证方式

方式 A：X-Api-Key 队伍编码（适用于万智插件及代码对接）

方式 B：Cookie（仅适用于网页后台浏览器登录）

1.3 统一响应格式

1.4 租户隔离

1.5 已知限制与 ID 使用说明

1.6 常见错误

2. Products — 商品

2.1 模块说明

2.2 分页查询商品

请求参数（Query）

响应 data 结构：PagedResult<ProductListItemDto>

请求示例

响应示例

阶梯价匹配规则

3. Orders — 销售订单

3.1 模块说明

3.2 分页查询销售订单

请求参数（Query）

响应 data 结构：PagedResult<OrderListItemDto>

请求示例

响应示例

3.3 查询销售订单详情

路径参数

响应 data 结构：OrderDetailDto

请求示例

响应示例

错误

3.4 随机生成销售订单

说明

响应 data 结构

请求示例

错误

3.5 手工创建销售订单

说明

请求体：CreateOrderRequest

请求示例

响应

常见错误 msg

4. Purchases — 采购单

4.1 模块说明

4.2 分页查询采购单

请求参数（Query）

响应 data 结构：PagedResult<PurchaseListItemDto>

请求示例

响应示例

4.3 查询采购单详情

路径参数

响应 data 结构：PurchaseDetailDto

请求示例

错误

5. Suppliers — 供应商

5.1 模块说明

5.2 查询供应商列表

请求参数（Query）

响应 data 结构：SupplierListItemDto[]

请求示例

响应示例

预置供应商一览

5.3 查询供应商详情

路径参数

响应 data 结构：SupplierDetailDto

请求示例

响应示例

错误

6. 本届可写范围与能力边界

7. 数据生命周期与资源使用说明

8. 接口速查表

9. 万智平台对接示例

使用与核验提醒

下载与相关说明

响应 `data` 结构：`PagedResult<ProductListItemDto>`

响应 `data` 结构：`PagedResult<OrderListItemDto>`

响应 `data` 结构：`OrderDetailDto`

响应 `data` 结构

请求体：`CreateOrderRequest`

响应 `data` 结构：`PagedResult<PurchaseListItemDto>`

响应 `data` 结构：`PurchaseDetailDto`

响应 `data` 结构：`SupplierListItemDto[]`

响应 `data` 结构：`SupplierDetailDto`