1、产品简介
基于商品识别、SKU 资产知识库和专用面积推理模型构建的地堆面积分析产品。产品先定位地堆商品，再读取对应 SKU 的真实长宽高与参考图，推理地堆占地外接矩形的两条边长及面积，适用于门店地堆陈列规模评估与巡检复核。
2、适用场景
地堆面积评估：根据地堆整体照片与商品真实尺寸推理占地外接矩形面积。
多 SKU 混排分析：按不同商品各自的尺寸参与边长推理。
面积结果复核：结合原图、商品资产和返回的两条边长及面积核查结果。
3、功能介绍
SKU 资产驱动：通过 ragId 指定资产知识库，每个参与商品需有名称、正数长宽高及至少一张 HTTPS 参考图。
分阶段面积推理：依次形成决策边、SKU 投影、尺寸累加与最终面积。
单位统一：SKU 资产尺寸以厘米存储，结果边长以米、面积以平方米输出。
完整性与数值校验：存在缺失资产、无有效框或面积不满足乘积一致性时返回失败。
4、开发指南
本文请求和响应字段遵循对应搭建文档的实际大小写及结构。示例为业务工作流输入输出，不额外假设平台网关封装；对外调用地址、鉴权方式和网关封装应以实际发布接口为准。
接入前须准备可查询的 SKU 资产知识库，确保识别出的 SKU 编码均能匹配到完整资产。
4.1 请求参数
参数名 | 类型 | 必填 | 说明 |
imageUrl | String | 是 | 待识别原图的 HTTPS 地址；须可访问，不含空白或 URL 用户名密码 |
ragId | String | 是 | 已准备好商品名称、尺寸及参考图的 SKU 资产知识库 ID |
4.2 请求示例
{
"imageUrl": "https://example.com/images/api-10.jpg",
"ragId": "cust_8001_sku_assets"
}示例图片地址和知识库标识（如有）为占位值，调用时替换为实际资源。
4.3 响应参数
通用字段：
字段路径 | 类型 | 说明 |
success | Boolean | 调用是否成功；有效业务结论不等于审核通过 |
errorCode | String | 成功为空字符串；失败为错误码 |
errorMessage | String | 成功为空字符串；失败为具体错误说明 |
usageMap | Object | 成功为 {"ProcessingCount":1}；失败为空对象 |
usageMap.ProcessingCount | Integer | 成功处理计数为 1；失败时该字段不返回 |
业务字段：
字段路径 | 类型 | 说明 |
result | Object | 面积推理结果，失败时为空对象 |
result.stage4_area_label | Object | 最终边长与面积，成功时必须有效 |
result.stage4_area_label.left_edge_m | Number | 左决策轴边长，单位米；有限正数 |
result.stage4_area_label.right_edge_m | Number | 右决策轴边长，单位米；有限正数 |
result.stage4_area_label.area_m2 | Number | 外接矩形占地面积，单位平方米；有限正数 |
totalCount | Number | 原始商品 locations 数量；失败时为 0 |
recognizedCount | Number | 保留的有效商品框数量；失败时为 0 |
filteredCount | Number | 过滤框数量，包含待定、empty、caps 及非法框；失败时为 0 |
pendingCount | Number | 待定框数量，属于 filteredCount 的统计范围；失败时为 0 |
面积表示目标 SKU 投影并集的外接矩形，不是商品框像素面积。每个 SKU 最多使用 2 张参考图，含原图的整个请求最多 28 张图；任何 SKU 未能保留至少 1 张参考图都会失败。边长与面积按模型规则四舍五入到 4 位小数，面积与两边乘积的差不得超过 max(0.0002, 两边乘积 × 0.001)。pendingCount 与 filteredCount 不应重复相加。
对外 result 仅包含 stage4_area_label，不返回中间推理过程。没有有效 SKU 框、SKU 资产缺失或资产信息不完整时返回 InvalidParameter；资产查询服务故障、模型调用失败或面积数值无效时返回 DownstreamUnavailable。
4.4 响应示例
以下均为结构示例，非实测结果。
1）成功响应
{
"success": true,
"errorCode": "",
"errorMessage": "",
"result": {
"stage4_area_label": {
"left_edge_m": 1.35,
"right_edge_m": 0.7,
"area_m2": 0.945
}
},
"totalCount": 6,
"recognizedCount": 4,
"filteredCount": 2,
"pendingCount": 1,
"usageMap": {
"ProcessingCount": 1
}
}参数错误响应
{
"success": false,
"errorCode": "InvalidParameter",
"errorMessage": "ragId 不能为空",
"usageMap": {},
"result": {},
"totalCount": 0,
"recognizedCount": 0,
"filteredCount": 0,
"pendingCount": 0
}SKU 资产缺失响应
{
"success": false,
"errorCode": "InvalidParameter",
"errorMessage": "SKU 资产缺失，无法完成面积推理",
"usageMap": {},
"result": {},
"totalCount": 0,
"recognizedCount": 0,
"filteredCount": 0,
"pendingCount": 0
}4.5 错误码
错误码 | 含义 | 处理建议 |
InvalidParameter | 输入不合法或识别服务明确返回业务错误 | 根据 errorMessage 修正参数或业务输入后重新调用 |
DownstreamUnavailable | 鉴权、限流、超时、空响应、缺字段或解析等处理异常 | 根据 errorMessage 检查资源与服务状态；临时故障可稍后重试 |
应结合 success、errorCode、errorMessage 判断结果。源搭建文档未约定每类业务错误对应的 HTTP 状态码。平台公共错误码可参考错误码，本接口工作流错误码以上表为准。