erpnew/docs/2026-01-20_summary.md

2026-01-20 工作日志

背景

前端反馈“腾讯云搜图 API 一次只返回 10 条结果太少”，需要确认腾讯云 TIIA SearchImage 是否支持分页/返回条数控制，并在项目的简化搜图 API 中开放相应参数。

---

今日完成

1) TIIA 搜图接口支持分页参数（limit/offset）

确认腾讯云 TIIA SearchImage 支持 Limit（返回条数）与 Offset（偏移），其中 Limit 默认 10、最大 100。

项目侧改动：

• api_v1/views/tiia.py
  • POST /api/v1/tiia/search-image/ 新增可选入参：
    • limit：1~100
    • offset：>= 0
    • matchThreshold：0~100（可选）
  • 将以上参数透传到 api_v1/utils/tencentcloud_tiia.search_image_url_in_tencent_tiia()，从而调用 SDK 的 req.Limit/req.Offset/req.MatchThreshold

测试：

• api_v1/views/test_tiia_search_image_api.py
  • 新增用例覆盖 limit/offset/matchThreshold 透传与边界校验（limit>100、offset<0）

2) 方案 A：让搜图结果可拿到可访问 URL（写入 CustomContent）

由于腾讯云 TIIA SearchImage 的返回 ImageInfos 默认不包含 ImageUrl，因此无法直接从结果拼出可访问 URL。 为便于前端展示/回查，上传入库时将“可访问图片 URL”写入图片元信息中：

• api_v1/utils/tencentcloud_tiia.py
  • upload_image_url_to_tencent_tiia(...) 调用 CreateImage 时：
    • CustomContent 默认写入原始 URL（CustomContent 文档上限 4096 字符）
    • Tags 默认不写入（避免触发“标签值长度过长”）

前端取值建议：

• 若腾讯云 SearchImage 返回的 ImageInfos[i].CustomContent 可用，则直接作为可访问 URL 使用

3) 补充独立文档（便于长期维护/不再翻工作日志）

• 新增：docs/tiia_image_gallery.md（包含配置、上传函数、定时任务、失败落库、手动跑批命令、搜图 API、常见排障）