fix: limit param for tiia(tencent)

.cursor/skills/work-daily-process/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: work-daily-process
+description: 编码工作的每日工作流程,每一个任务开始前及完成后都需要遵守的一些步骤,是作为一个团队成员的操作基础,同时提供"日报汇总
+"的的功能
+---
+
+# 目标
+为程序员用户的每一个任务都提供一个可记录可汇总的工作日志,提供简述每日工作报告的汇总能力
+
+# 前置信息
+1. 文档及工作报告目录是项目根目录的docs目录
+2. 工作日志命名格为{日期(YYYY-MM-DD)}_summary.md
+3. 如果工作日志不存在则创建(在上述的docs目录中),注意必须以当前的日期命名
+4. 如果工作日志已存在(当前日期的),则直接在其中编辑即可
+
+# 开始编码任务前的步骤
+1. 检查当天的工作日志是否存在
+2. 查看工作日志理解当天的工作内容
+3. 检查当前的任务是否已经完成过或有关
+4. 如有相关性需要按照实际情况询问/提示用户
+
+# 结束编码任务后的步骤
+1. 提问用户是否需要创建相关的测试代码及文档
+2. 根据用户的回答决定时候补全测试及文档
+3. 都完成后把任务的背景及要求和最后的实施方案写到工作日志
+4. 向用户说明工作日志已更新
+
+# 每日总结
+1. 当用户指明当天的任务已经结束或下班时,梳理并简化当天的工作日志
+2. 简化后为用户生成一份"工作汇报",要求如下
+  a. 汇报需要交给上级(不懂技术)审阅
+  b. 需要隐藏技术细节
+  c. 用管理人员可以理解的言辞
+  d. 需要体现丰满的工作量(但不可虚报)
+  e. 汇报包含一天的简述以及完成的事项列表(一维无序列表)
+  f. 生成的汇报直接以code block的形式输出无格式的文本给用户以便复制
+

api_v1/views/test_tiia_search_image_api.py

@@ -43,6 +43,47 @@ class TiiaSearchImageAPITestCase(TestCase):
         self.assertEqual(resp.json(), {'Candidates': [{'EntityId': '1', 'Score': 99}]})
         mock_search.assert_called()
 
+    @patch('api_v1.views.tiia.search_image_url_in_tencent_tiia')
+    def test_search_image_pass_limit_offset(self, mock_search):
+        self.client.force_authenticate(self.user)
+        mock_search.return_value = {'Candidates': []}
+
+        resp = self.client.post(
+            '/api/v1/tiia/search-image/',
+            data={
+                'imageUrl': 'https://example.com/a.png',
+                'limit': 50,
+                'offset': 10,
+                'matchThreshold': 80,
+            },
+            format='json',
+        )
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        _, kwargs = mock_search.call_args
+        self.assertEqual(kwargs.get('limit'), 50)
+        self.assertEqual(kwargs.get('offset'), 10)
+        self.assertEqual(kwargs.get('match_threshold'), 80)
+
+    def test_search_image_limit_too_large(self):
+        self.client.force_authenticate(self.user)
+        resp = self.client.post(
+            '/api/v1/tiia/search-image/',
+            data={'imageUrl': 'https://example.com/a.png', 'limit': 101},
+            format='json',
+        )
+        self.assertEqual(resp.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn('error', resp.json())
+
+    def test_search_image_offset_negative(self):
+        self.client.force_authenticate(self.user)
+        resp = self.client.post(
+            '/api/v1/tiia/search-image/',
+            data={'imageUrl': 'https://example.com/a.png', 'offset': -1},
+            format='json',
+        )
+        self.assertEqual(resp.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertIn('error', resp.json())
+
     @patch('api_v1.views.tiia.search_image_url_in_tencent_tiia')
     def test_search_image_success_base64(self, mock_search):
         self.client.force_authenticate(self.user)

api_v1/views/tiia.py

@@ -39,11 +39,39 @@ class TiiaSearchImageView(APIView):
         # - imageBase64
         image_url = request.data.get('imageUrl')
         image_base64 = request.data.get('imageBase64')
+        limit = request.data.get('limit', None)
+        offset = request.data.get('offset', None)
+        match_threshold = request.data.get('matchThreshold', None)
         try:
+            if limit is not None and str(limit).strip() != '':
+                limit = int(limit)
+                # TencentCloud SearchImage: default 10, max 100
+                if limit <= 0 or limit > 100:
+                    raise ValueError('limit 必须在 1~100 之间')
+            else:
+                limit = None
+
+            if offset is not None and str(offset).strip() != '':
+                offset = int(offset)
+                if offset < 0:
+                    raise ValueError('offset 必须 >= 0')
+            else:
+                offset = None
+
+            if match_threshold is not None and str(match_threshold).strip() != '':
+                match_threshold = int(match_threshold)
+                if match_threshold < 0 or match_threshold > 100:
+                    raise ValueError('matchThreshold 必须在 0~100 之间')
+            else:
+                match_threshold = None
+
             limiter = SimpleRateLimiter(qps=float(getattr(settings, 'TENCENTCLOUD_TIIA_QPS', 10)))
             resp = search_image_url_in_tencent_tiia(
                 image_url=str(image_url or '') if image_url is not None else None,
                 image_base64=str(image_base64 or '') if image_base64 is not None else None,
+                limit=limit,
+                offset=offset,
+                match_threshold=match_threshold,
                 rate_limiter=limiter,
             )
             return Response(resp, status=status.HTTP_200_OK)

docs/2026-01-20_summary.md

@@ -0,0 +1,28 @@
+# 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）
+