支持其他店铺

2026-07-08 21:53:20 +08:00
parent af8d3a859f
commit 7ddb41cea1
10 changed files with 932 additions and 432 deletions
@@ -0,0 +1,104 @@
+# 通知（お知らせ）查询接口
+
+读取 worker 定时抓取的骏河屋「お知らせ一覧」(action_news) 通知。worker 翻页抓取后按
+`data_id` 去重写入 Redis，本接口只读返回，不删除、不消费，可重复拉取。
+
+## 请求
+
+| 项 | 值 |
+| --- | --- |
+| 方法 | `GET` |
+| 路径 | `/api/news` |
+| 鉴权 | 请求头 `Authorization: Bearer <token>`（token 由服务端 `SURUGAYA_BEARER_TOKEN` 配置） |
+
+### Query 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `limit` | int | 否 | 返回条数上限，范围 `1`~`500`；省略则返回全部。结果按 `data_id` 倒序（新→旧），`limit` 取最新的若干条 |
+
+### 示例
+
+```
+GET /api/news?limit=20
+Authorization: Bearer NilsO8Il8yoT1wazJFs2eeOmlPRfWuSx
+```
+
+## 成功响应 `200`
+
+```json
+{
+  "success": true,
+  "msg": "success",
+  "code": 0,
+  "data": [
+    {
+      "data_id": "869431007",
+      "date": "2026/06/12",
+      "message": "【販売】(取引番号：S2606115133)発送準備中です。",
+      "data_type": "2",
+      "data_url": "/pcmypage/action_sell_search/detail?trade_code=S2606115133",
+      "trade_code": "S2606115133",
+      "account_id": "trdian023@tokugen.jp",
+      "fetched_at": 1781348570
+    },
+    {
+      "data_id": "868997716",
+      "date": "2026/06/05",
+      "message": "【販売】(取引番号：M2606056999)商品の注文を受け付けました。",
+      "data_type": "2",
+      "data_url": "/pcmypage/action_sell_search/detail?trade_code=M2606056999",
+      "trade_code": "M2606056999",
+      "account_id": "trdian023@tokugen.jp",
+      "fetched_at": 1781348570
+    },
+    {
+      "data_id": "860001234",
+      "date": "2026/01/01",
+      "message": "【お知らせ】メンテナンスのお知らせ",
+      "data_type": "1",
+      "data_url": "/pcmypage/action_news_detail?id=860001234",
+      "trade_code": null,
+      "account_id": "trdian023@tokugen.jp",
+      "fetched_at": 1781348570
+    }
+  ]
+}
+```
+
+### data 字段说明
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data_id` | string | 骏河屋侧通知唯一标识（单调递增），去重与排序依据 |
+| `date` | string | 通知日期，格式 `YYYY/MM/DD` |
+| `message` | string | 通知文案原文（日文） |
+| `data_type` | string | 骏河屋侧 `data-type` 原值（如 `2`=交易类通知） |
+| `data_url` | string \| null | 骏河屋侧 `data-url`（详情相对路径） |
+| `trade_code` | string \| null | 从 `data_url` 解析的交易单号；非交易类通知为 `null` |
+| `account_id` | string | 该通知所属账号（骏河屋登录邮箱） |
+| `fetched_at` | int | worker 抓取写入时间（Unix epoch 秒） |
+
+> 说明
+> - 列表按 `data_id` 数值倒序返回（最新在前）。
+> - 同一 `data_id` 只保留一条，重复抓取会以最新内容覆盖，调用方可安全重复拉取。
+> - 需要区分账号时按 `account_id` 过滤即可（当前为登录邮箱）。
+
+## 错误响应
+
+统一响应体结构：`success=false`，`code` 为业务错误码，`data=null`。
+
+| HTTP | code | 场景 | 示例 msg |
+| --- | --- | --- | --- |
+| 401 | 1001 | 缺少/无效 Bearer Token | `Invalid token` |
+| 422 | 1002 | `limit` 越界（不在 1~500） | `limit: Input should be less than or equal to 500` |
+| 500 | 500 | 服务端未配置 Redis，通知不可读 | `Redis 未配置` |
+
+```json
+{
+  "success": false,
+  "msg": "Redis 未配置",
+  "code": 500,
+  "data": null
+}
+```