Sfoglia il codice sorgente

20261021 API圖片欄位命名統一

S.K. 4 settimane fa
parent
commit
5a44211973
4 ha cambiato i file con 761 aggiunte e 11 eliminazioni
  1. 11
    11
      app/Http/Controllers/Api/NewsController.php
  2. 229
    0
      docs/api-spec-third-party.md
  3. 194
    0
      docs/api-spec.md
  4. 327
    0
      docs/openapi.yaml

+ 11
- 11
app/Http/Controllers/Api/NewsController.php Vedi File

@@ -81,8 +81,8 @@ class NewsController extends Controller
81 81
                 "category" => $item->newsCategory->getTranslation("name", $locate, false),
82 82
                 "postDate" => Carbon::parse($item->post_date)->format("Y.m.d"),
83 83
                 "title" => $item->getTranslation("title", $locate, false),
84
-                "imgPC" => $item->news_img_pc_url,
85
-                "imgMobile" => $item->news_img_mobile_url,
84
+                "img_pc" => $item->news_img_pc_url,
85
+                "img_mobile" => $item->news_img_mobile_url,
86 86
                 "written" => $item->getTranslation("written_by", $locate, false),
87 87
                 "description" => $item->getTranslation("description", $locate, false),
88 88
             ];
@@ -106,7 +106,7 @@ class NewsController extends Controller
106 106
                 "meta_title" => $news->getTranslation("meta_title", $locate, false),
107 107
                 "meta_keyword" => $news->getTranslation("meta_keyword", $locate, false),
108 108
                 "meta_description" => $news->getTranslation("meta_description", $locate, false),
109
-                "imgPC" => $news->news_meta_img,
109
+                "img_pc" => $news->news_meta_img,
110 110
             ],
111 111
             "yearList" => $yearList,
112 112
             "top" => [
@@ -115,8 +115,8 @@ class NewsController extends Controller
115 115
                 "category" => $news->newsCategory->getTranslation("name", $locate, false),
116 116
                 "postDate" => Carbon::parse($news->post_date)->format("Y/m/d"),
117 117
                 "title" => $news->getTranslation("title", $locate, false),
118
-                "imgPC" => $news->news_img_pc_url,
119
-                "imgMobile" => $news->news_img_mobile_url,
118
+                "img_pc" => $news->news_img_pc_url,
119
+                "img_mobile" => $news->news_img_mobile_url,
120 120
                 "written" => $news->getTranslation("written_by", $locate, false),
121 121
                 "description" => $news->getTranslation("description", $locate, false),
122 122
             ]
@@ -214,8 +214,8 @@ class NewsController extends Controller
214 214
             "category" => $previous->newsCategory->getTranslation("name", $locate, false),
215 215
             "postDate" => Carbon::parse($previous->post_date)->format("Y/m/d"),
216 216
             "title" => $previous->getTranslation("title", $locate, false),
217
-            "imgPC" => $previous->news_img_pc_url,
218
-            "imgMobile" => $previous->news_img_mobile_url,
217
+            "img_pc" => $previous->news_img_pc_url,
218
+            "img_mobile" => $previous->news_img_mobile_url,
219 219
             "written" => $previous->getTranslation("written_by", $locate, false),
220 220
             "description" => $previous->getTranslation("description", $locate, false),
221 221
         ];
@@ -225,8 +225,8 @@ class NewsController extends Controller
225 225
             "category" => $next->newsCategory->getTranslation("name", $locate, false),
226 226
             "postDate" => Carbon::parse($next->post_date)->format("Y/m/d"),
227 227
             "title" => $next->getTranslation("title", $locate, false),
228
-            "imgPC" => $next->news_img_pc_url,
229
-            "imgMobile" => $next->news_img_mobile_url,
228
+            "img_pc" => $next->news_img_pc_url,
229
+            "img_mobile" => $next->news_img_mobile_url,
230 230
             "written" => $next->getTranslation("written_by", $locate, false),
231 231
             "description" => $next->getTranslation("description", $locate, false),
232 232
         ];
@@ -270,8 +270,8 @@ class NewsController extends Controller
270 270
             "title" => $news->getTranslation("title", $locate, false),
271 271
             "description" => $news->getTranslation("description", $locate, false),
272 272
             "written" => $news->getTranslation("written_by", $locate, false),
273
-            "imgPC" => $news->news_img_pc_url,
274
-            "imgMobile" => $news->news_img_mobile_url,
273
+            "img_pc" => $news->news_img_pc_url,
274
+            "img_mobile" => $news->news_img_mobile_url,
275 275
             "metaTitle" => $news->getTranslation("meta_title", $locate, false),
276 276
             "metaKeyword" => $news->getTranslation("meta_keyword", $locate, false),
277 277
             "metaDesc" => $news->getTranslation("meta_description", $locate, false),

+ 229
- 0
docs/api-spec-third-party.md Vedi File

@@ -0,0 +1,229 @@
1
+# Yico Website API Specification/前台 API 規格說明
2
+
3
+Version/版本:1.1(Verified against staging/已對 staging 實測驗證:2026-10-13;2026-10-21 圖片欄位改名)
4
+Machine-readable format/機器格式:see `openapi.yaml` in the same directory/同目錄 `openapi.yaml`
5
+
6
+## 1. Overview/總覽
7
+
8
+Base URLs:
9
+
10
+| Environment/環境 | Base URL | Note/說明 |
11
+|---|---|---|
12
+| Staging(testable/可測試) | `https://webdev.yico.tw:8088/api` | All examples below use this host/以下範例皆用此位址 |
13
+| Production(TBD) | `https://www.example.com/api` | Replace with the production domain at launch/上線後替換為正式網域 |
14
+
15
+General rules/通用規則:
16
+
17
+- All endpoints are `GET` and require no authentication./全部為 `GET`,免認證。
18
+- Rate limit: 60 requests/minute (`throttle:api`)./節流:每分鐘 60 次。
19
+- `Access-Control-Allow-Origin: *` is returned./回傳 CORS 全域允許標頭。
20
+- All responses are JSON. Non-ASCII text is `\uXXXX`-escaped; decode before display./回應皆 JSON,非 ASCII 以 `\uXXXX` 跳脫,顯示前請解碼。
21
+- `{locale}` path parameter: `tw` (Traditional Chinese/繁中) or `en` (English/英文). Any other value returns 404./語系路徑參數僅 `tw`/`en`,其餘 404。
22
+- Long strings in examples are trimmed with `...` for readability./範例長字串以 `...` 節錄。
23
+- Image fields use snake_case: `img_pc` / `img_mobile` (renamed 2026-10-21; the old `imgPC` / `imgMobile` keys are no longer returned)./圖片欄位為 snake_case,舊欄位名稱已不再回傳。
24
+
25
+Endpoints/端點一覽:
26
+
27
+| Method | Path/路徑 | Description/說明 |
28
+|---|---|---|
29
+| GET | `/api/{locale}/news` | Featured (top) article, year filter list, SEO meta/置頂文章、年份清單、SEO |
30
+| GET | `/api/{locale}/news/list` | Article list with pagination and year/month filter/文章列表(分頁、年月篩選) |
31
+| GET | `/api/{locale}/news/detail/{id}` | Article body, paragraphs, prev/next links/文章內文、段落、前後篇 |
32
+| GET | `/api/{locale}/esg` | ESG hero section and tab list/ESG 主視覺與頁籤 |
33
+| GET | `/api/{locale}/esg/{key}` | Single ESG page by tab key/單一 ESG 頁面 |
34
+
35
+## 2. Featured article/置頂文章 `GET /api/{locale}/news`
36
+
37
+No query parameters./無 query 參數。
38
+
39
+Response `200` (`{data: {meta, yearList, top}}`). If no featured article exists, the body is `[]` (empty array, not an object) — handle both shapes./成功回 `{data:{...}}`;若無置頂資料回 `[]`(空陣列非物件),請相容兩種形狀。
40
+
41
+- `yearList`: months that contain articles, format `YYYY/MM`, descending./有文章的年月,`YYYY/MM` 倒序。
42
+- `top.postDate` format: `Y/m/d`./日期格式 `Y/m/d`。
43
+
44
+```json
45
+{
46
+    "data": {
47
+        "meta": {
48
+            "meta_title": "秦嘉鴻回憶錄全新出版",
49
+            "meta_keyword": "秦嘉鴻 回憶錄 油品大亨 ...",
50
+            "meta_description": "透過秦嘉鴻董事長的回憶錄,得以領略為人處...",
51
+            "img_pc": null
52
+        },
53
+        "yearList": ["2026/07", "2026/01", "2025/04"],
54
+        "top": {
55
+            "id": 49,
56
+            "categoryId": 1,
57
+            "category": "最新公告",
58
+            "postDate": "2025/04/24",
59
+            "title": "益州董事長秦嘉鴻 出版回憶錄",
60
+            "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JW5GAC910DRBH2ZZPEKVG.webp",
61
+            "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9GRA0EBP8NPE3BH1ZWY.webp",
62
+            "written": "黃全興",
63
+            "description": "益州集團董事長、前國策顧問、前中華民國工業區廠商聯合總會理事..."
64
+        }
65
+    }
66
+}
67
+```
68
+
69
+## 3. Article list/文章列表 `GET /api/{locale}/news/list`
70
+
71
+Query parameters/參數:
72
+
73
+| Name/名稱 | Type/型別 | Default/預設 | Description/說明 |
74
+|---|---|---|---|
75
+| `page` | integer | 1 | Page number/頁碼 |
76
+| `per_page` | integer | 15 | Items per page; `-1` returns all without pagination/每頁筆數;`-1` 取全部不分頁 |
77
+| `year` | integer | — | Filter by year/按年篩選 |
78
+| `month` | integer | — | Must be used together with `year` (month-only is ignored)/需與 `year` 並用,單獨傳入無效 |
79
+
80
+Filtering and ordering/過濾與排序:only visible articles within their publish window (`start_date`/`end_date`); ordered by `order` DESC then `post_date` DESC./僅回可見且在有效期內的文章;依 `order` 倒序再依發佈日倒序。
81
+
82
+Response `200 {"data": {"pagination": {...}, "list": [...]}}`./成功回此形狀。
83
+
84
+- `pagination.page` and `per_page` are returned as **strings**./`page`/`per_page` 回傳為**字串**。
85
+- Empty result: `total: 0`, `total_page: 1` (not 0), `list: []`./空結果時 `total_page` 為 1。
86
+- List item `postDate` format: `Y.m.d` (note: different from §2/§4 which use `Y/m/d`)./此端日期為 `Y.m.d`(與 §2/§4 的 `Y/m/d` 不同)。
87
+
88
+```json
89
+{
90
+    "data": {
91
+        "pagination": { "page": 1, "per_page": "2", "total": 32, "total_page": 16 },
92
+        "list": [
93
+            {
94
+                "id": 2,
95
+                "categoryId": 1,
96
+                "category": "最新公告",
97
+                "postDate": "2015.05.06",
98
+                "title": "秦嘉鴻:要4贏,不要4輸",
99
+                "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg",
100
+                "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg",
101
+                "written": "記者黃全興/中時電子報",
102
+                "description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,..."
103
+            }
104
+        ]
105
+    }
106
+}
107
+```
108
+
109
+## 4. Article detail/文章內文 `GET /api/{locale}/news/detail/{id}`
110
+
111
+- `{id}`: numeric article ID (non-numeric → 404)./數字 ID(非數字 404)。
112
+- `?preview=1`: returns the article even if hidden or outside its publish window (for draft preview)./`?preview=1` 可讀取隱藏/未上架文章(草稿預覽用)。
113
+- Success `200 {"data": {...}}`; missing or unpublished → `404 {"message": "news not found"}`./成功 200;不存在或未上架 404。
114
+- `paragraphs` are ordered; types: `text` (`content` is HTML), `image` (`images: [{img_url, alt}]`), `video` (`video_img_url`, `is_yt`, `video_url`, `content` as caption)./段落依序排列,型別如列。
115
+- `otherNews.previous` = newer article, `next` = older article; absent when none./前後篇缺則無該鍵。
116
+
117
+```json
118
+{
119
+    "data": {
120
+        "categoryId": 1,
121
+        "category": "最新公告",
122
+        "postDate": "2015/05/06",
123
+        "title": "秦嘉鴻:要4贏,不要4輸",
124
+        "description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,...",
125
+        "written": "記者黃全興/中時電子報",
126
+        "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg",
127
+        "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg",
128
+        "metaTitle": "測試SEO",
129
+        "metaKeyword": "",
130
+        "metaDesc": "",
131
+        "metaImg": null,
132
+        "paragraphs": [
133
+            { "type": "text", "content": "<h4 class=\"lexical__h4\" dir=\"ltr\"><span ...>5月1日...</span></h4>" },
134
+            { "type": "image", "images": [{ "img_url": "https://webdev.yico.tw:8088//storage/news/extraPhoto/01KJ9BK7695DZX6QRDNVSW2FFN.jpg", "alt": "中華民國工業區廠商聯合總會理事長秦嘉鴻。圖/黃全興" }] }
135
+        ],
136
+        "otherNews": {
137
+            "next": { "id": 30, "categoryId": 1, "category": "最新公告", "postDate": "2022/07/27", "title": "國策顧問捐贈台大醫院雲林分院N95口罩用行動力挺醫護", "...": "..." }
138
+        }
139
+    }
140
+}
141
+```
142
+
143
+## 5. ESG hero/ESG 主視覺 `GET /api/{locale}/esg`
144
+
145
+Response `200 {"data": {"meta": {...}, "img_pc", "img_mobile", "title", "description", "tab_list": [{text, key}]}}`. The `tab_list` key is absent when no ESG pages exist./成功回此形狀;無 ESG 資料時缺 `tab_list` 鍵。
146
+
147
+```json
148
+{
149
+    "data": {
150
+        "meta": { "meta_title": "", "meta_keyword": "", "meta_description": "", "og_img": null },
151
+        "img_pc": null,
152
+        "img_mobile": null,
153
+        "title": "經營者的話",
154
+        "description": "面對全球經濟變動與氣候挑戰,企業責任不僅在於追求經濟成長,更...",
155
+        "tab_list": [
156
+            { "text": "永續經營", "key": "永續經營" },
157
+            { "text": "公司治理", "key": "公司治理" },
158
+            { "text": "創新研發", "key": "創新研發" },
159
+            { "text": "綠色承諾", "key": "綠色承諾" },
160
+            { "text": "社會共融", "key": "社會共融" }
161
+        ]
162
+    }
163
+}
164
+```
165
+
166
+## 6. ESG page/ESG 單頁 `GET /api/{locale}/esg/{key}`
167
+
168
+- `{key}` is the tab `keyword` (URL-encode non-ASCII, e.g. `%E6%B0%B8%E7%BA%8C%E7%B6%93%E7%87%9F`)./`{key}` 為頁籤 keyword,非 ASCII 請 URL 編碼。
169
+- Success `200 {"data": {"banner": {...}, "paragraphs": [...]}}`./成功回此形狀。
170
+- **Miss returns HTTP 200 (not 404)** with `{"status": "fail", "message": "查無資料"}` — clients MUST check the `status` field, not only the HTTP code./**查無資料時仍回 HTTP 200**,body 為上式——請務必判斷 `status` 欄,不可只看 HTTP 碼。
171
+
172
+```json
173
+{
174
+    "data": {
175
+        "banner": {
176
+            "img_pc": "https://webdev.yico.tw:8088//storage/esg/01KKE6AH4Q989Z7AQ4AMVDTSR8.jpg",
177
+            "img_mobile": "https://webdev.yico.tw:8088//storage/esg/01KKE6AH53W3HWH61CXXBKNFZD.jpg",
178
+            "img_alt": "永續經營",
179
+            "text": "邁向百年企業的根基..."
180
+        },
181
+        "paragraphs": [
182
+            { "type": "text", "content": "永續經營一、永續治理組織為傳承企業經營理念並確立長達發展方針..." },
183
+            { "type": "grid", "columns": 2, "content": [{ "type": "text", "content": "家族理事會家族最高治理單位..." }] },
184
+            { "type": "table", "is_card": false,
185
+              "header": [{ "align": 1, "text": "公(協)會組織" }, { "align": 1, "text": "參與資格 " }],
186
+              "body": [[{ "align": 1, "text": "<p...>..." }, { "align": 1, "text": "<p...>..." }]] }
187
+        ]
188
+    }
189
+}
190
+```
191
+
192
+Paragraph types/段落型別:`text` (`content`, HTML) · `grid` (`columns`, `content[]` of text blocks/文字塊陣列) · `table` (`is_card`, `header[{align, text}]`, `body` 2-D array/二維陣列) · `image` (`images[{image_url, alt}]`) · `video` (`is_yt: true`, `video_img_url`, `video_url`, `content`). Cell `align` is a numeric code; cell text may contain HTML./`align` 為數字碼,cell 文字可含 HTML。
193
+
194
+Miss example/查無範例(HTTP 200):
195
+
196
+```json
197
+{ "status": "fail", "message": "查無資料" }
198
+```
199
+
200
+```js
201
+// Recommended client check/建議判斷方式
202
+const res = await fetch(url).then(r => r.json());
203
+if (res.status === 'fail') { /* no such page/無此頁面 */ }
204
+```
205
+
206
+## 7. Data models/資料模型
207
+
208
+Common article fields/通用文章欄位:
209
+
210
+| Field/欄位 | Type/型別 | Description/說明 |
211
+|---|---|---|
212
+| `id` | integer | Article ID/文章 ID |
213
+| `categoryId` | integer | Category ID/分類 ID |
214
+| `category` | string | Localized category name/在地化分類名 |
215
+| `postDate` | string | `Y.m.d` in list (§3), `Y/m/d` elsewhere/列表 `Y.m.d`,其餘 `Y/m/d` |
216
+| `title` | string | Localized title/在地化標題 |
217
+| `description` | string | Localized summary/在地化摘要 |
218
+| `written` | string | Author/byline/作者 |
219
+| `img_pc` / `img_mobile` | string|null | Desktop/mobile image URLs (may contain `//`)/桌機/手機圖(或有雙斜線) |
220
+| `metaTitle` / `metaKeyword` / `metaDesc` / `metaImg` | string|null | SEO fields, detail only/SEO 欄位,僅內文 |
221
+
222
+## 8. Error handling/錯誤處理
223
+
224
+| HTTP | Body | When/時機 |
225
+|---|---|---|
226
+| 200 | `{"status": "fail", "message": "查無資料"}` | ESG key not found (see §6)/ESG 查無資料 |
227
+| 404 | `{"message": "news not found"}` | Article missing or unpublished/文章不存在或未上架 |
228
+| 404 | HTML error page | Unknown path, non-`tw`/`en` locale, or non-numeric detail id/未知路徑、非 `tw`/`en` 語系、非數字 id |
229
+| 429 | JSON | Over 60 requests/minute/超過節流 |

+ 194
- 0
docs/api-spec.md Vedi File

@@ -0,0 +1,194 @@
1
+# Yico 前台 API 規格說明
2
+
3
+- Base URL(實測):`https://webdev.yico.tw:8088` + 前綴 `/api`
4
+- 本地對應:`http://127.0.0.1:8083/api`(`.env` `APP_URL`)
5
+- 全部為 `GET`,免認證;節流 `throttle:api`(預設 60 次/分鐘);實測回 `Access-Control-Allow-Origin: *`
6
+- 回應皆 JSON;中文以 `\uXXXX` 跳脫;圖片 URL 實測含雙斜線(`...tw:8088//storage/...`,前端可正常讀取)
7
+- 語系路徑參數 `{locale}`:僅 `tw`|`en`(`tw` 對應 `zh_TW`);其他值回 404
8
+- 範例取自 staging 實測(2026-10-13),長字串以 `...` 節錄
9
+
10
+## 端點總覽
11
+
12
+| 方法 | 路徑 | 說明 |
13
+|---|---|---|
14
+| GET | `/api/{locale}/news` | 置頂消息+年份清單+SEO meta |
15
+| GET | `/api/{locale}/news/list` | 消息列表(分頁/年月過濾) |
16
+| GET | `/api/{locale}/news/detail/{id}` | 消息內文(含段落、前後篇) |
17
+| GET | `/api/{locale}/esg` | ESG 主視覺+頁籤清單 |
18
+| GET | `/api/{locale}/esg/{key}` | ESG 單頁內容(`key` 需 URL 編碼) |
19
+
20
+## 1. 置頂消息 `GET /api/{locale}/news`
21
+
22
+- Query:無(`categoryId` 已於 2026-10-13 移除,舊版傳入亦無效)。
23
+- `200 {"data": {"meta": {...}, "yearList": [...], "top": {...}}}`;若無置頂資料回 `[]`(空陣列,注意非物件)。
24
+
25
+```json
26
+{
27
+    "data": {
28
+        "meta": {
29
+            "meta_title": "秦嘉鴻回憶錄全新出版",
30
+            "meta_keyword": "秦嘉鴻 回憶錄 油品大亨 ...",
31
+            "meta_description": "透過秦嘉鴻董事長的回憶錄,得以領略為人處...",
32
+            "img_pc": null
33
+        },
34
+        "yearList": ["2026/07", "2026/01", "2025/04"],
35
+        "top": {
36
+            "id": 49,
37
+            "categoryId": 1,
38
+            "category": "最新公告",
39
+            "postDate": "2025/04/24",
40
+            "title": "益州董事長秦嘉鴻 出版回憶錄",
41
+            "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JW5GAC910DRBH2ZZPEKVG.webp",
42
+            "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9GRA0EBP8NPE3BH1ZWY.webp",
43
+            "written": "黃全興",
44
+            "description": "益州集團董事長、前國策顧問、前中華民國工業區廠商聯合總會理事..."
45
+        }
46
+    }
47
+}
48
+```
49
+
50
+- `yearList`:有文章的年月(`YYYY/MM`,倒序,取自全部可見文章,不分語系)。
51
+- 日期格式此端為 `Y/m/d`(與 list 的 `Y.m.d` 不同,見 §7)。
52
+
53
+## 2. 消息列表 `GET /api/{locale}/news/list`
54
+
55
+- Query:`page`(預設 1)、`per_page`(預設 15;`-1` 取全部不分頁)、`year`、`month`。
56
+- 過濾:僅 `visible=1` 且在 `start_date`/`end_date` 有效期內;`year`+`month` 並用取該月,僅 `year` 取該年,**僅 `month` 不過濾**;排序 `order` DESC、`post_date` DESC。
57
+- `200 {"data": {"pagination": {...}, "list": [...]}}`;空資料時 `total: 0`、`total_page: 1`(非 0)、`list: []`。
58
+
59
+```json
60
+{
61
+    "data": {
62
+        "pagination": { "page": 1, "per_page": "2", "total": 32, "total_page": 16 },
63
+        "list": [
64
+            {
65
+                "id": 2,
66
+                "categoryId": 1,
67
+                "category": "最新公告",
68
+                "postDate": "2015.05.06",
69
+                "title": "秦嘉鴻:要4贏,不要4輸",
70
+                "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg",
71
+                "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg",
72
+                "written": "記者黃全興/中時電子報",
73
+                "description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,..."
74
+            }
75
+        ]
76
+    }
77
+}
78
+```
79
+
80
+- 注意:`pagination.page`/`per_page` 回傳為**字串**;`postDate` 此端為 `Y.m.d`。
81
+
82
+## 3. 消息內文 `GET /api/{locale}/news/detail/{id}`
83
+
84
+- `{id}` 限數字(非數字 404);`?preview=1` 可 bypass 可見性與有效期(**免認證**,見 §7 安全注意)。
85
+- 成功 `200 {"data": {...}}`;不存在/未上架 `404 {"message": "news not found"}`。
86
+- `paragraphs` 依 `order` 排序,型別:`text`(`content` 為 HTML,含 `<br>`),`image`(`images: [{img_url, alt}]`),`video`(`video_img_url`、`is_yt`、`video_url`、`content` 為 alt/說明)。
87
+- `otherNews.previous`=前一篇(較新)、`next`=下一篇;無則缺鍵。
88
+
89
+```json
90
+{
91
+    "data": {
92
+        "categoryId": 1,
93
+        "category": "最新公告",
94
+        "postDate": "2015/05/06",
95
+        "title": "秦嘉鴻:要4贏,不要4輸",
96
+        "description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,...",
97
+        "written": "記者黃全興/中時電子報",
98
+        "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg",
99
+        "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg",
100
+        "metaTitle": "測試SEO",
101
+        "metaKeyword": "",
102
+        "metaDesc": "",
103
+        "metaImg": null,
104
+        "paragraphs": [
105
+            { "type": "text", "content": "<h4 class=\"lexical__h4\" dir=\"ltr\"><span ...>5月1日...</span></h4>" },
106
+            { "type": "image", "images": [{ "img_url": "https://webdev.yico.tw:8088//storage/news/extraPhoto/01KJ9BK7695DZX6QRDNVSW2FFN.jpg", "alt": "中華民國工業區廠商聯合總會理事長秦嘉鴻。圖/黃全興" }] }
107
+        ],
108
+        "otherNews": {
109
+            "next": { "id": 30, "categoryId": 1, "category": "最新公告", "postDate": "2022/07/27", "title": "國策顧問捐贈台大醫院雲林分院N95口罩用行動力挺醫護", "...": "..." }
110
+        }
111
+    }
112
+}
113
+```
114
+
115
+## 4. ESG 主視覺 `GET /api/{locale}/esg`
116
+
117
+- `200 {"data": {"meta": {...}, "img_pc", "img_mobile", "title", "description", "tab_list": [{text, key}]}}`;尚無 ESG 資料時缺 `tab_list` 鍵。
118
+
119
+```json
120
+{
121
+    "data": {
122
+        "meta": { "meta_title": "", "meta_keyword": "", "meta_description": "", "og_img": null },
123
+        "img_pc": null,
124
+        "img_mobile": null,
125
+        "title": "經營者的話",
126
+        "description": "面對全球經濟變動與氣候挑戰,企業責任不僅在於追求經濟成長,更...",
127
+        "tab_list": [
128
+            { "text": "永續經營", "key": "永續經營" },
129
+            { "text": "公司治理", "key": "公司治理" },
130
+            { "text": "創新研發", "key": "創新研發" },
131
+            { "text": "綠色承諾", "key": "綠色承諾" },
132
+            { "text": "社會共融", "key": "社會共融" }
133
+        ]
134
+    }
135
+}
136
+```
137
+
138
+## 5. ESG 單頁 `GET /api/{locale}/esg/{key}`
139
+
140
+- `{key}` 為頁籤 `keyword`(中文需 URL 編碼,如 `%E6%B0%B8%E7%BA%8C%E7%B6%93%E7%87%9F`)。
141
+- 成功 `200 {"data": {"banner": {...}, "paragraphs": [...]}}`;查無資料時**維持 `200 {"status": "fail", "message": "查無資料"}`**(刻意保留舊前端相容,勿改判 404)。
142
+- 段落型別:`text`(`content` HTML)、`grid`(`columns`+`content[]` 文字塊)、`table`(`is_card`、`header[{align,text}]`、`body` 二維陣列)、`image`(`images[{image_url, alt}]`)、`video`(`is_yt: true`、`video_img_url`、`video_url`、`content`)。`align` 為數字碼;cell 文字含 HTML。
143
+
144
+```json
145
+{
146
+    "data": {
147
+        "banner": {
148
+            "img_pc": "https://webdev.yico.tw:8088//storage/esg/01KKE6AH4Q989Z7AQ4AMVDTSR8.jpg",
149
+            "img_mobile": "https://webdev.yico.tw:8088//storage/esg/01KKE6AH53W3HWH61CXXBKNFZD.jpg",
150
+            "img_alt": "永續經營",
151
+            "text": "邁向百年企業的根基..."
152
+        },
153
+        "paragraphs": [
154
+            { "type": "text", "content": "永續經營一、永續治理組織為傳承企業經營理念並確立長達發展方針..." },
155
+            { "type": "grid", "columns": 2, "content": [{ "type": "text", "content": "家族理事會家族最高治理單位..." }] },
156
+            { "type": "table", "is_card": false,
157
+              "header": [{ "align": 1, "text": "公(協)會組織" }, { "align": 1, "text": "參與資格 " }],
158
+              "body": [[{ "align": 1, "text": "<p...>..." }, { "align": 1, "text": "<p...>..." }]] }
159
+        ]
160
+    }
161
+}
162
+```
163
+
164
+## 6. 已移除:`GET /api/user`
165
+
166
+- 原 Sanctum 範例路由;Sanctum 未安裝,實測恆 500,已於 2026-10-13 移除。
167
+
168
+## 7. 檢查記錄(實測佐證)
169
+
170
+本次(2026-10-13)檢查+修復:
171
+
172
+| # | 項目 | 結果 |
173
+|---|---|---|
174
+| 1 | 語系參數綁定 | ✅ 正常。Laravel 以位置綁定非型別參數,`{locale}` 正確傳入;staging `en` 回英文、`tw` 回中文已證實。最初「被忽略」為誤判(已讀框架源碼+實測推翻)。 |
175
+| 2 | `esgContent` 參數名 | ✅ 正常。同上,位置綁定 cover;`Esg::getContentByKeyword()` 經 `__callStatic` 轉實例呼叫有效,staging 有資料回 200 已證實。 |
176
+| 3 | 路由 locale 约束失效 | 🔧 已修。`->group(...)->whereIn(...)` 掛在 group 之後,對已註冊路由無效(`RouteRegistrar::group()` 回傳自身,`__call` spread 又把字串 where 形狀搞壞,直接 500)。現改為 `prefix('{locale}')->where(['locale' => 'tw|en'])->group(...)`(陣列形狀),本地驗 `jp` → 404;並移除 `detail` 上到不了的 `jp`。注意:此前 `/api/jp/*` 回 200 空譯文,修後 404,前端若有打 `jp` 需配合。 |
177
+| 4 | `getTop` 的 `categoryId` | 🔧 已修(刪 dead code)。實測 `?categoryId=999` 與不帶結果相同,確認未生效;該讀值行已刪除,行為零變更。 |
178
+| 5 | Sanctum `/user` | 🔧 已修(刪除)。未安裝 Sanctum,實測 500 且吐 debug HTML;無客戶端可依賴,移除。 |
179
+| 6 | ESG 查無資料回 200 | ➖ 保留。`{"status":"fail","message":"查無資料"}` 配 HTTP 200,舊前端已依此相容,**刻意不改**,文件載明。 |
180
+| 7 | `detail ?preview=1` 免認證看隱藏文 | ⚠️ 現況載明,未改。若需上鎖請另起任務(加 auth 或簽章)。 |
181
+| 8 | 日期格式不一致 | ➖ 載明:`getTop`/`detail` 用 `Y/m/d`,`list` 用 `Y.m.d`。前端已相容,不改。 |
182
+| 9 | `pagination.page/per_page` 回字串、空列表 `total_page: 1`、`per_page=-1` 全取、僅 `month` 不過濾 | ➖ 現況載明,不改。 |
183
+| 10 | 無置頂時 `GET news` 回 `[]`(非物件) | ➖ 現況載明,前端判空陣列處理。 |
184
+| 11 | 圖片雙斜線 `//storage/` | ➖ staging `APP_URL` 尾斜線所致,前端可讀;要修改 staging `.env`(非本 repo)。 |
185
+| 12 | Staging `APP_DEBUG` 疑似開 | ⚠️ `/api/user` 500 回整頁 debug HTML,建議 staging 關閉(伺服器 env,非本 repo)。 |
186
+| 13 | 死碼 | ➖ 載明未動:`AccessIpMiddleware`(`accessIp` alias 無路由使用)、`App\Supports\Response`、`App\Http\Helper`(僅 import)、`ContactRequest`/`RegistEPaperRequest`(無路由使用)。 |
187
+| 14 | 效能 | ➖ `list`/`detail` 逐筆取 `newsCategory`/`paragraphs.photos`(N+1),資料量小可接受,量大再加 `with()`。 |
188
+| 15 | 圖片欄位命名不一致 | 🔧 已修(2026-10-21)。News API 的 `imgPC`/`imgMobile` 改名為 `img_pc`/`img_mobile`,與 ESG API 一致;不保留舊鍵,前端需同步改用新欄位。 |
189
+
190
+## 8. 對應原始碼
191
+
192
+- `routes/api.php`、`app/Http/Controllers/Api/NewsController.php`、`app/Http/Controllers/Api/EsgController.php`
193
+- 模型:`News`(`newsCategory`、`paragraphs`、`news_img_pc_url` 等)、`NewsParagraph`(`contentType`: 1=image、2=text、3=video)、`Esg`(`getContentByKeyword`)、`EsgMain`
194
+- 機器格式見 `openapi.yaml`(同目錄)。

+ 327
- 0
docs/openapi.yaml Vedi File

@@ -0,0 +1,327 @@
1
+openapi: 3.0.3
2
+info:
3
+  title: Yico 前台 API
4
+  version: 1.0.0
5
+  description: |
6
+    對應 docs/api-spec.md。Base URL 實測 https://webdev.yico.tw:8088,path 前綴 /api。
7
+    全部 GET、免認證;{locale} 僅 tw|en;中文以 \uXXXX 跳脫;圖片 URL 含雙斜線。
8
+servers:
9
+  - url: https://webdev.yico.tw:8088/api
10
+    description: staging(實測)
11
+  - url: http://127.0.0.1:8083/api
12
+    description: 本地
13
+paths:
14
+  /{locale}/news:
15
+    get:
16
+      summary: 置頂消息+年份清單
17
+      parameters:
18
+        - $ref: '#/components/parameters/Locale'
19
+      responses:
20
+        '200':
21
+          description: 成功;無置頂資料時回 [](空陣列)
22
+          content:
23
+            application/json:
24
+              schema:
25
+                oneOf:
26
+                  - $ref: '#/components/schemas/TopResponse'
27
+                  - type: array
28
+                    maxItems: 0
29
+  /{locale}/news/list:
30
+    get:
31
+      summary: 消息列表
32
+      parameters:
33
+        - $ref: '#/components/parameters/Locale'
34
+        - name: page
35
+          in: query
36
+          schema: { type: integer, default: 1 }
37
+        - name: per_page
38
+          in: query
39
+          description: 每頁筆數;-1 取全部不分頁
40
+          schema: { type: integer, default: 15 }
41
+        - name: year
42
+          in: query
43
+          schema: { type: integer }
44
+        - name: month
45
+          in: query
46
+          description: 需與 year 並用,單獨傳入不過濾
47
+          schema: { type: integer }
48
+      responses:
49
+        '200':
50
+          description: 成功
51
+          content:
52
+            application/json:
53
+              schema:
54
+                $ref: '#/components/schemas/ListResponse'
55
+  /{locale}/news/detail/{id}:
56
+    get:
57
+      summary: 消息內文
58
+      parameters:
59
+        - $ref: '#/components/parameters/Locale'
60
+        - name: id
61
+          in: path
62
+          required: true
63
+          schema: { type: integer }
64
+        - name: preview
65
+          in: query
66
+          description: preview=1 時 bypass 可見性與有效期(免認證)
67
+          schema: { type: string }
68
+      responses:
69
+        '200':
70
+          description: 成功
71
+          content:
72
+            application/json:
73
+              schema:
74
+                $ref: '#/components/schemas/DetailResponse'
75
+        '404':
76
+          description: 不存在或未上架
77
+          content:
78
+            application/json:
79
+              schema:
80
+                type: object
81
+                properties:
82
+                  message: { type: string, example: 'news not found' }
83
+  /{locale}/esg:
84
+    get:
85
+      summary: ESG 主視覺+頁籤
86
+      parameters:
87
+        - $ref: '#/components/parameters/Locale'
88
+      responses:
89
+        '200':
90
+          description: 成功;無 ESG 資料時缺 tab_list 鍵
91
+          content:
92
+            application/json:
93
+              schema:
94
+                $ref: '#/components/schemas/EsgMainResponse'
95
+  /{locale}/esg/{key}:
96
+    get:
97
+      summary: ESG 單頁內容
98
+      parameters:
99
+        - $ref: '#/components/parameters/Locale'
100
+        - name: key
101
+          in: path
102
+          required: true
103
+          description: 頁籤 keyword(中文需 URL 編碼)
104
+          schema: { type: string }
105
+      responses:
106
+        '200':
107
+          description: '成功;查無資料時同為 200,body 為 {status: fail, message: 查無資料}'
108
+          content:
109
+            application/json:
110
+              schema:
111
+                oneOf:
112
+                  - $ref: '#/components/schemas/EsgContentResponse'
113
+                  - $ref: '#/components/schemas/FailBody'
114
+components:
115
+  parameters:
116
+    Locale:
117
+      name: locale
118
+      in: path
119
+      required: true
120
+      schema:
121
+        type: string
122
+        enum: [tw, en]
123
+  schemas:
124
+    Pagination:
125
+      type: object
126
+      properties:
127
+        page: { type: string, example: '1' }
128
+        per_page: { type: string, example: '2' }
129
+        total: { type: integer }
130
+        total_page: { type: integer }
131
+    NewsListItem:
132
+      type: object
133
+      properties:
134
+        id: { type: integer }
135
+        categoryId: { type: integer }
136
+        category: { type: string }
137
+        postDate: { type: string, example: '2015.05.06' }
138
+        title: { type: string }
139
+        img_pc: { type: string, nullable: true }
140
+        img_mobile: { type: string, nullable: true }
141
+        written: { type: string }
142
+        description: { type: string }
143
+    ListResponse:
144
+      type: object
145
+      properties:
146
+        data:
147
+          type: object
148
+          properties:
149
+            pagination: { $ref: '#/components/schemas/Pagination' }
150
+            list:
151
+              type: array
152
+              items: { $ref: '#/components/schemas/NewsListItem' }
153
+    TopResponse:
154
+      type: object
155
+      properties:
156
+        data:
157
+          type: object
158
+          properties:
159
+            meta:
160
+              type: object
161
+              properties:
162
+                meta_title: { type: string }
163
+                meta_keyword: { type: string }
164
+                meta_description: { type: string }
165
+                img_pc: { type: string, nullable: true }
166
+            yearList:
167
+              type: array
168
+              items: { type: string, example: '2026/07' }
169
+            top: { $ref: '#/components/schemas/NewsListItem' }
170
+    NewsParagraph:
171
+      type: object
172
+      oneOf:
173
+        - type: object
174
+          required: [type, content]
175
+          properties:
176
+            type: { type: string, enum: [text] }
177
+            content: { type: string, description: HTML }
178
+        - type: object
179
+          required: [type, images]
180
+          properties:
181
+            type: { type: string, enum: [image] }
182
+            images:
183
+              type: array
184
+              items:
185
+                type: object
186
+                properties:
187
+                  img_url: { type: string }
188
+                  alt: { type: string }
189
+        - type: object
190
+          required: [type, video_img_url, is_yt, content, video_url]
191
+          properties:
192
+            type: { type: string, enum: [video] }
193
+            video_img_url: { type: string, nullable: true }
194
+            is_yt: { type: boolean }
195
+            content: { type: string }
196
+            video_url: { type: string }
197
+    DetailResponse:
198
+      type: object
199
+      properties:
200
+        data:
201
+          type: object
202
+          properties:
203
+            categoryId: { type: integer }
204
+            category: { type: string }
205
+            postDate: { type: string, example: '2015/05/06' }
206
+            title: { type: string }
207
+            description: { type: string }
208
+            written: { type: string }
209
+            img_pc: { type: string, nullable: true }
210
+            img_mobile: { type: string, nullable: true }
211
+            metaTitle: { type: string }
212
+            metaKeyword: { type: string }
213
+            metaDesc: { type: string }
214
+            metaImg: { type: string, nullable: true }
215
+            paragraphs:
216
+              type: array
217
+              items: { $ref: '#/components/schemas/NewsParagraph' }
218
+            otherNews:
219
+              type: object
220
+              properties:
221
+                previous: { $ref: '#/components/schemas/NewsListItem' }
222
+                next: { $ref: '#/components/schemas/NewsListItem' }
223
+    EsgMainResponse:
224
+      type: object
225
+      properties:
226
+        data:
227
+          type: object
228
+          properties:
229
+            meta:
230
+              type: object
231
+              properties:
232
+                meta_title: { type: string }
233
+                meta_keyword: { type: string }
234
+                meta_description: { type: string }
235
+                og_img: { type: string, nullable: true }
236
+            img_pc: { type: string, nullable: true }
237
+            img_mobile: { type: string, nullable: true }
238
+            title: { type: string }
239
+            description: { type: string }
240
+            tab_list:
241
+              type: array
242
+              items:
243
+                type: object
244
+                properties:
245
+                  text: { type: string }
246
+                  key: { type: string }
247
+    EsgParagraph:
248
+      type: object
249
+      oneOf:
250
+        - type: object
251
+          required: [type, content]
252
+          properties:
253
+            type: { type: string, enum: [text] }
254
+            content: { type: string, description: HTML }
255
+        - type: object
256
+          required: [type, columns, content]
257
+          properties:
258
+            type: { type: string, enum: [grid] }
259
+            columns: { type: integer }
260
+            content:
261
+              type: array
262
+              items:
263
+                type: object
264
+                properties:
265
+                  type: { type: string, enum: [text] }
266
+                  content: { type: string }
267
+        - type: object
268
+          required: [type, is_card, header, body]
269
+          properties:
270
+            type: { type: string, enum: [table] }
271
+            is_card: { type: boolean }
272
+            header:
273
+              type: array
274
+              items:
275
+                type: object
276
+                properties:
277
+                  align: { type: integer }
278
+                  text: { type: string }
279
+            body:
280
+              type: array
281
+              items:
282
+                type: array
283
+                items:
284
+                  type: object
285
+                  properties:
286
+                    align: { type: integer }
287
+                    text: { type: string }
288
+        - type: object
289
+          required: [type, images]
290
+          properties:
291
+            type: { type: string, enum: [image] }
292
+            images:
293
+              type: array
294
+              items:
295
+                type: object
296
+                properties:
297
+                  image_url: { type: string }
298
+                  alt: { type: string }
299
+        - type: object
300
+          required: [type, is_yt, video_img_url, video_url, content]
301
+          properties:
302
+            type: { type: string, enum: [video] }
303
+            is_yt: { type: boolean, example: true }
304
+            video_img_url: { type: string }
305
+            video_url: { type: string }
306
+            content: { type: string }
307
+    EsgContentResponse:
308
+      type: object
309
+      properties:
310
+        data:
311
+          type: object
312
+          properties:
313
+            banner:
314
+              type: object
315
+              properties:
316
+                img_pc: { type: string, nullable: true }
317
+                img_mobile: { type: string, nullable: true }
318
+                img_alt: { type: string }
319
+                text: { type: string }
320
+            paragraphs:
321
+              type: array
322
+              items: { $ref: '#/components/schemas/EsgParagraph' }
323
+    FailBody:
324
+      type: object
325
+      properties:
326
+        status: { type: string, example: 'fail' }
327
+        message: { type: string, example: '查無資料' }