# 商品图片识别

CloudProduct 提供以下 POST 接口，成功时 ApiResult 的 code 为 200。

| 路径 | JSON 请求 | 成功响应的 data |
|---|---|---|
| `/api/ProductInspection/InspectImage` | `userName`、`md5`、`image` 均必填。md5 为 32 位十六进制缓存键，image 为 JPEG、PNG 或 WebP 原图的纯 Base64（不含 Data URL 前缀），原图最多 10 MiB | 按阅读顺序去重的文字和品牌数组，无识别项时返回 `[]` |
| `/api/CloudGoods/SaveProductSafety` | `{"userName":"alice","productId":"123","isSafe":false}` | 无数据 |

客户端根据识别结果判断商品是否安全，再上报已收藏商品的结论。最新结论可从收藏检索接口读取。

## 配置与部署

图片识别缓存使用插件的 `CloudProductConnection` 数据库连接。将旧插件配置中的 `ProductInspection` 节迁入 CloudProduct 对应环境的配置文件，环境变量前缀由 `Plugins__ProductInspection__` 改为 `Plugins__CloudProduct__`。例如，密钥使用 `Plugins__CloudProduct__ProductInspection__ApiKey`，为空时读取 `DASHSCOPE_API_KEY`。部署时移出旧的 `Plugins/Store.ProductInspection` 目录，避免宿主重复加载质检功能。

服务端将客户端提交的 MD5 转为小写，命中缓存后直接返回结果。未命中时调用配置的千问接口，最大并发数由 `ProductInspection:MaxConcurrentAnalysis` 控制。

## 验证

从仓库根目录运行 `dotnet run --project Tests/ProductInspection.Checks`，检查专用库结构并通过本地模拟模型验证图片识别和缓存。数据库连接可用 `Plugins__CloudProduct__ProductInspection__ConnectionString` 覆盖。

已有缓存表升级时，先暂停旧服务写入，从仓库根目录运行 `dotnet run --project Tests/ProductInspection.Checks -- --migrate-cache-expiration`，再启动新版本。命令读取 `CloudProductConnection`，可通过 `Plugins__CloudProduct__CloudProductConnection` 指定目标库。数据库的 `ExpiresAt` 保存整数小时数，连续空结果的下一档由上一次的小时数决定。迁移保留原更新时间，将旧记录回填为对应小时数。服务器 UTC 时间达到 `UpdatedAt.AddHours(ExpiresAt)` 时缓存过期。空结果从 1 天开始，连续为空时逐级延长至 2、4、8、16 天并封顶。有内容的结果缓存 30 天，之后首次为空时重新从 1 天开始。

旧库升级命令 `dotnet run --project Tests/ProductInspection.Checks -- --initialize` 会更名旧结果列，移除 DetectionText、LogoBrands 列及四张旧任务相关表，并同步缓存表结构。执行前请备份数据库，先归档或清理仍使用 SHA-256 键的缓存。