商城c端前端

docs/移动端任务与账户平台前后端对接文档.md

@@ -475,7 +475,33 @@ GET /v1/member-levels
 }
 ```
 
-### 6.5 首页和内容错误
+### 6.5 荣誉榜（已实现）
+
+```http
+GET /v1/leaderboard
+```
+
+接口要求登录，返回当前租户内已完成任务数量排名前 50 的有效会员。排名只统计
+`hg_trade_order.order_type=2 AND order_status=4` 的真实任务订单；昵称由服务端脱敏，前端不得还原或展示手机号。
+
+```json
+{
+  "code": 0,
+  "data": [
+    {
+      "rank": 1,
+      "username": "风***淡",
+      "avatar_url": "https://cdn.example.com/avatar.png",
+      "completed_count": 12580,
+      "status": "领取成功"
+    }
+  ]
+}
+```
+
+没有已完成任务时返回空数组，不使用模拟排行数据填充页面。
+
+### 6.6 首页和内容错误
 
 | HTTP | `reason` | 说明 |
 | --- | --- | --- |
@@ -555,7 +581,7 @@ POST /v1/task-orders/claim
 
 成功返回订单摘要，包括 `id`、`order_no`、`status`、`product`、`total_amount`、`commission_amount`、`currency` 和 `deadline_at`。
 
-领单事务会锁定当前会员和钱包记录，重新校验大厅等级、账户状态、最低余额、当日次数、未完成订单、任务发布与有效期、任务每日上限及单会员上限。成功后只创建 `status=matching` 的任务订单，不扣款、不冻结余额，也不生成钱包流水。当前表结构没有任务与商品的直接绑定字段，因此匹配完成前 `product.id`、`total_amount` 和 `unit_price_amount` 允许为 `0`；后续匹配流程补齐商品和金额并把订单置为 `pending` 后，客户端才能提交凭证。
+领单事务会锁定当前会员和钱包记录，重新校验大厅等级、账户状态、最低余额、当日次数、未完成订单、任务发布与有效期、任务每日上限及单会员上限。当前版本在事务内直接选中可用任务，创建 `status=pending` 的订单并记录 `matched_at`，客户端收到成功响应后即可进入订单详情并提交凭证；不依赖额外匹配进程。领取不扣款、不冻结余额，也不生成钱包流水。当前表结构没有任务与商品的直接绑定字段，因此 `product.id`、`total_amount` 和 `unit_price_amount` 允许为 `0`，任务名称和封面取自 `hg_task`。
 
 | HTTP | `reason` | 说明 |
 | --- | --- | --- |
@@ -708,6 +734,9 @@ GET /v1/manual-products?page=1&page_size=20&category_id=0
       "summary": "商品说明摘要",
       "claimed_count": 1,
       "is_recommended": true,
+      "is_limited": true,
+      "start_at": "2026-10-01T00:00:00Z",
+      "end_at": "2026-10-31T23:59:59Z",
       "available_actions": ["contact_support"]
     }
   ],
@@ -717,7 +746,7 @@ GET /v1/manual-products?page=1&page_size=20&category_id=0
 }
 ```
 
-金额单位为分。现有 `hg_product` 没有独立摘要字段，`summary` 由商品详情转换为纯文本后截取前 120 个字符。`claimed_count` 统计该商品 `order_type=3` 且状态不是已取消或失败的订单。
+金额单位为分。现有 `hg_product` 没有独立摘要字段，`summary` 由商品详情转换为纯文本后截取前 120 个字符。`claimed_count` 统计该商品 `order_type=3` 且状态不是已取消或失败的订单。`is_limited` 在商品配置了 `end_at` 时为 `true`，客户端使用该字段区分限时商品，不根据分类名称推断；`start_at`、`end_at` 为商品展示有效期。
 
 ### 8.2 商品详情
 
@@ -989,9 +1018,9 @@ Content-Type: application/json
 | 429 | `RATE_LIMITED` | 交易密码连续错误次数过多，15 分钟后重试 |
 | 503 | `WITHDRAWAL_CHANNEL_UNAVAILABLE` | 没有可用的取出通道 |
 
-## 12. 客服、通知和上传（待实现）
+## 12. 客服、通知和上传
 
-### 12.1 客服
+### 12.1 客服（已实现）
 
 ```http
 GET /v1/customer-services
@@ -999,6 +1028,8 @@ GET /v1/customer-services
 
 响应字段包括 `id`、`service_code`、`name`、`avatar_url`、`work_time`、`online_status`、`service_url`、`backup_contact` 和 `privacy_notice`。
 
+只返回 `hg_customer_service.status=1` 且未删除的客服，按 `sort`、`id` 排序。`online_status` 映射为 `online`、`offline` 或 `busy`。头像和客服地址仅返回不含用户凭据的 HTTPS URL，不符合要求时返回空字符串。
+
 客服 URL 必须经服务端域名白名单校验。前端 WebView/iframe 只开启必要权限，并显示第三方服务来源和隐私提示。
 
 ### 12.2 通知