From 012269cfda8b2f0ec7cbc61815a9959e17dc5910 Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Mon, 14 Sep 2026 10:52:36 +0800
Subject: [PATCH] feat: add shopee sync wait endpoint

---
 app/admin/apis/shopee_product.go          |  7 ++++
 app/admin/router/shopee_product.go        |  1 +
 tickets/LOCAL-011-shopee-sync-wait-api.md | 40 +++++++++++++++++++++++
 3 files changed, 48 insertions(+)
 create mode 100644 tickets/LOCAL-011-shopee-sync-wait-api.md

diff --git a/app/admin/apis/shopee_product.go b/app/admin/apis/shopee_product.go
index e6b63d2..6af7e7e 100644
--- a/app/admin/apis/shopee_product.go
+++ b/app/admin/apis/shopee_product.go
@@ -130,6 +130,13 @@ func (e ShopeeProduct) SyncByShopeeID(c *gin.Context) {
 	e.OK(gin.H{"id": row.Id, "shopeeId": id, "taskId": task.TaskID, "status": "processing"}, "同步任务已创建")
 }
 
+// SyncWaitByShopeeID synchronously refreshes Shopee data, waits for Huohanhan
+// to finish, then fetches and persists the complete product detail.
+func (e ShopeeProduct) SyncWaitByShopeeID(c *gin.Context) {
+	e.MakeContext(c)
+	e.getByShopeeID(c, true, true)
+}
+
 // SyncStatus returns the current asynchronous refresh state.
 func (e ShopeeProduct) SyncStatus(c *gin.Context) {
 	e.MakeContext(c)
diff --git a/app/admin/router/shopee_product.go b/app/admin/router/shopee_product.go
index 5c21828..6c5802e 100644
--- a/app/admin/router/shopee_product.go
+++ b/app/admin/router/shopee_product.go
@@ -15,6 +15,7 @@ func registerShopeeProductRouter(v1 *gin.RouterGroup) {
 	a := apis.ShopeeProduct{}
 	v1.GET("/shopee/products/:shopeeId", a.GetByShopeeID)
 	v1.POST("/shopee/products/:shopeeId/sync", a.SyncByShopeeID)
+	v1.POST("/shopee/products/:shopeeId/sync-wait", a.SyncWaitByShopeeID)
 	v1.GET("/shopee/products/:shopeeId/sync-status", a.SyncStatus)
 }
 func registerShopeeProductAdminRouter(v1 *gin.RouterGroup, auth *jwt.GinJWTMiddleware) {
diff --git a/tickets/LOCAL-011-shopee-sync-wait-api.md b/tickets/LOCAL-011-shopee-sync-wait-api.md
new file mode 100644
index 0000000..caea871
--- /dev/null
+++ b/tickets/LOCAL-011-shopee-sync-wait-api.md
@@ -0,0 +1,40 @@
+# LOCAL-011：Shopee 同步等待版接口
+
+- 状态：进行中
+- 来源：用户需求（2026-09-14）及 LOCAL-008 方案
+- 前置：LOCAL-008、LOCAL-009
+
+## 目标
+
+提供适合内部人工调用的同步等待接口，同时保留异步任务接口。
+
+## 接口
+
+```http
+POST /api/v1/shopee/products/{shopeeId}/sync-wait
+```
+
+接口发起货憨憨同步，等待任务完成后获取并保存 detail，成功时直接返回商品详情；总等待时间最多 120 秒。
+
+## 规则
+
+- 成功：返回完整 `bean.itemInfo` detail；
+- 超时：返回 502，并提示使用 taskId 查询异步任务；
+- 认证或同步失败：返回明确错误；
+- 原 `POST /sync` 和 `GET /sync-status` 保持不变；
+- API Key 支持 query 参数和 `X-API-Key` 请求头。
+
+## 验收
+
+- 有效商品在一次请求中完成同步并返回 detail；
+- 同步失败不会覆盖已有 detail；
+- 超时不会无限占用连接；
+- 异步接口行为不受影响。
+
+## 实施记录
+- 已新增 `POST /api/v1/shopee/products/{shopeeId}/sync-wait`。
+- 接口使用 query `apikey`、`X-API-Key` 或 `Authorization: ApiKey ...` 鉴权。
+- 接口同步 Shopee、等待货憨憨任务完成、读取 detail 并保存到 MySQL 后返回详情。
+- 保留原有异步 `/sync` 与 `/sync-status` 接口。
+- 验证：`go test ./app/admin/apis ./app/admin/router ./internal/huohanhan` 通过，`git diff --check` 通过。
+- 当前状态：待验收