# Yico 前台 API 規格說明 - Base URL(實測):`https://webdev.yico.tw:8088` + 前綴 `/api` - 本地對應:`http://127.0.0.1:8083/api`(`.env` `APP_URL`) - 全部為 `GET`,免認證;節流 `throttle:api`(預設 60 次/分鐘);實測回 `Access-Control-Allow-Origin: *` - 回應皆 JSON;中文以 `\uXXXX` 跳脫;圖片 URL 實測含雙斜線(`...tw:8088//storage/...`,前端可正常讀取) - 語系路徑參數 `{locale}`:僅 `tw`|`en`(`tw` 對應 `zh_TW`);其他值回 404 - 範例取自 staging 實測(2026-10-13),長字串以 `...` 節錄 ## 端點總覽 | 方法 | 路徑 | 說明 | |---|---|---| | GET | `/api/{locale}/news` | 置頂消息+年份清單+SEO meta | | GET | `/api/{locale}/news/list` | 消息列表(分頁/年月過濾) | | GET | `/api/{locale}/news/detail/{id}` | 消息內文(含段落、前後篇) | | GET | `/api/{locale}/esg` | ESG 主視覺+頁籤清單 | | GET | `/api/{locale}/esg/{key}` | ESG 單頁內容(`key` 需 URL 編碼) | ## 1. 置頂消息 `GET /api/{locale}/news` - Query:無(`categoryId` 已於 2026-10-13 移除,舊版傳入亦無效)。 - `200 {"data": {"meta": {...}, "yearList": [...], "top": {...}}}`;若無置頂資料回 `[]`(空陣列,注意非物件)。 ```json { "data": { "meta": { "meta_title": "秦嘉鴻回憶錄全新出版", "meta_keyword": "秦嘉鴻 回憶錄 油品大亨 ...", "meta_description": "透過秦嘉鴻董事長的回憶錄,得以領略為人處...", "img_pc": null }, "yearList": ["2026/07", "2026/01", "2025/04"], "top": { "id": 49, "categoryId": 1, "category": "最新公告", "postDate": "2025/04/24", "title": "益州董事長秦嘉鴻 出版回憶錄", "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JW5GAC910DRBH2ZZPEKVG.webp", "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9GRA0EBP8NPE3BH1ZWY.webp", "written": "黃全興", "description": "益州集團董事長、前國策顧問、前中華民國工業區廠商聯合總會理事..." } } } ``` - `yearList`:有文章的年月(`YYYY/MM`,倒序,取自全部可見文章,不分語系)。 - 日期格式此端為 `Y/m/d`(與 list 的 `Y.m.d` 不同,見 §7)。 ## 2. 消息列表 `GET /api/{locale}/news/list` - Query:`page`(預設 1)、`per_page`(預設 15;`-1` 取全部不分頁)、`year`、`month`。 - 過濾:僅 `visible=1` 且在 `start_date`/`end_date` 有效期內;`year`+`month` 並用取該月,僅 `year` 取該年,**僅 `month` 不過濾**;排序 `order` DESC、`post_date` DESC。 - `200 {"data": {"pagination": {...}, "list": [...]}}`;空資料時 `total: 0`、`total_page: 1`(非 0)、`list: []`。 ```json { "data": { "pagination": { "page": 1, "per_page": "2", "total": 32, "total_page": 16 }, "list": [ { "id": 2, "categoryId": 1, "category": "最新公告", "postDate": "2015.05.06", "title": "秦嘉鴻:要4贏,不要4輸", "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg", "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg", "written": "記者黃全興/中時電子報", "description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,..." } ] } } ``` - 注意:`pagination.page`/`per_page` 回傳為**字串**;`postDate` 此端為 `Y.m.d`。 ## 3. 消息內文 `GET /api/{locale}/news/detail/{id}` - `{id}` 限數字(非數字 404);`?preview=1` 可 bypass 可見性與有效期(**免認證**,見 §7 安全注意)。 - 成功 `200 {"data": {...}}`;不存在/未上架 `404 {"message": "news not found"}`。 - `paragraphs` 依 `order` 排序,型別:`text`(`content` 為 HTML,含 `
`),`image`(`images: [{img_url, alt}]`),`video`(`video_img_url`、`is_yt`、`video_url`、`content` 為 alt/說明)。 - `otherNews.previous`=前一篇(較新)、`next`=下一篇;無則缺鍵。 ```json { "data": { "categoryId": 1, "category": "最新公告", "postDate": "2015/05/06", "title": "秦嘉鴻:要4贏,不要4輸", "description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,...", "written": "記者黃全興/中時電子報", "img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg", "img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg", "metaTitle": "測試SEO", "metaKeyword": "", "metaDesc": "", "metaImg": null, "paragraphs": [ { "type": "text", "content": "

5月1日...

" }, { "type": "image", "images": [{ "img_url": "https://webdev.yico.tw:8088//storage/news/extraPhoto/01KJ9BK7695DZX6QRDNVSW2FFN.jpg", "alt": "中華民國工業區廠商聯合總會理事長秦嘉鴻。圖/黃全興" }] } ], "otherNews": { "next": { "id": 30, "categoryId": 1, "category": "最新公告", "postDate": "2022/07/27", "title": "國策顧問捐贈台大醫院雲林分院N95口罩用行動力挺醫護", "...": "..." } } } } ``` ## 4. ESG 主視覺 `GET /api/{locale}/esg` - `200 {"data": {"meta": {...}, "img_pc", "img_mobile", "title", "description", "tab_list": [{text, key}]}}`;尚無 ESG 資料時缺 `tab_list` 鍵。 ```json { "data": { "meta": { "meta_title": "", "meta_keyword": "", "meta_description": "", "og_img": null }, "img_pc": null, "img_mobile": null, "title": "經營者的話", "description": "面對全球經濟變動與氣候挑戰,企業責任不僅在於追求經濟成長,更...", "tab_list": [ { "text": "永續經營", "key": "永續經營" }, { "text": "公司治理", "key": "公司治理" }, { "text": "創新研發", "key": "創新研發" }, { "text": "綠色承諾", "key": "綠色承諾" }, { "text": "社會共融", "key": "社會共融" } ] } } ``` ## 5. ESG 單頁 `GET /api/{locale}/esg/{key}` - `{key}` 為頁籤 `keyword`(中文需 URL 編碼,如 `%E6%B0%B8%E7%BA%8C%E7%B6%93%E7%87%9F`)。 - 成功 `200 {"data": {"banner": {...}, "paragraphs": [...]}}`;查無資料時**維持 `200 {"status": "fail", "message": "查無資料"}`**(刻意保留舊前端相容,勿改判 404)。 - 段落型別:`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。 ```json { "data": { "banner": { "img_pc": "https://webdev.yico.tw:8088//storage/esg/01KKE6AH4Q989Z7AQ4AMVDTSR8.jpg", "img_mobile": "https://webdev.yico.tw:8088//storage/esg/01KKE6AH53W3HWH61CXXBKNFZD.jpg", "img_alt": "永續經營", "text": "邁向百年企業的根基..." }, "paragraphs": [ { "type": "text", "content": "永續經營一、永續治理組織為傳承企業經營理念並確立長達發展方針..." }, { "type": "grid", "columns": 2, "content": [{ "type": "text", "content": "家族理事會家族最高治理單位..." }] }, { "type": "table", "is_card": false, "header": [{ "align": 1, "text": "公(協)會組織" }, { "align": 1, "text": "參與資格 " }], "body": [[{ "align": 1, "text": "..." }, { "align": 1, "text": "..." }]] } ] } } ``` ## 6. 已移除:`GET /api/user` - 原 Sanctum 範例路由;Sanctum 未安裝,實測恆 500,已於 2026-10-13 移除。 ## 7. 檢查記錄(實測佐證) 本次(2026-10-13)檢查+修復: | # | 項目 | 結果 | |---|---|---| | 1 | 語系參數綁定 | ✅ 正常。Laravel 以位置綁定非型別參數,`{locale}` 正確傳入;staging `en` 回英文、`tw` 回中文已證實。最初「被忽略」為誤判(已讀框架源碼+實測推翻)。 | | 2 | `esgContent` 參數名 | ✅ 正常。同上,位置綁定 cover;`Esg::getContentByKeyword()` 經 `__callStatic` 轉實例呼叫有效,staging 有資料回 200 已證實。 | | 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` 需配合。 | | 4 | `getTop` 的 `categoryId` | 🔧 已修(刪 dead code)。實測 `?categoryId=999` 與不帶結果相同,確認未生效;該讀值行已刪除,行為零變更。 | | 5 | Sanctum `/user` | 🔧 已修(刪除)。未安裝 Sanctum,實測 500 且吐 debug HTML;無客戶端可依賴,移除。 | | 6 | ESG 查無資料回 200 | ➖ 保留。`{"status":"fail","message":"查無資料"}` 配 HTTP 200,舊前端已依此相容,**刻意不改**,文件載明。 | | 7 | `detail ?preview=1` 免認證看隱藏文 | ⚠️ 現況載明,未改。若需上鎖請另起任務(加 auth 或簽章)。 | | 8 | 日期格式不一致 | ➖ 載明:`getTop`/`detail` 用 `Y/m/d`,`list` 用 `Y.m.d`。前端已相容,不改。 | | 9 | `pagination.page/per_page` 回字串、空列表 `total_page: 1`、`per_page=-1` 全取、僅 `month` 不過濾 | ➖ 現況載明,不改。 | | 10 | 無置頂時 `GET news` 回 `[]`(非物件) | ➖ 現況載明,前端判空陣列處理。 | | 11 | 圖片雙斜線 `//storage/` | ➖ staging `APP_URL` 尾斜線所致,前端可讀;要修改 staging `.env`(非本 repo)。 | | 12 | Staging `APP_DEBUG` 疑似開 | ⚠️ `/api/user` 500 回整頁 debug HTML,建議 staging 關閉(伺服器 env,非本 repo)。 | | 13 | 死碼 | ➖ 載明未動:`AccessIpMiddleware`(`accessIp` alias 無路由使用)、`App\Supports\Response`、`App\Http\Helper`(僅 import)、`ContactRequest`/`RegistEPaperRequest`(無路由使用)。 | | 14 | 效能 | ➖ `list`/`detail` 逐筆取 `newsCategory`/`paragraphs.photos`(N+1),資料量小可接受,量大再加 `with()`。 | | 15 | 圖片欄位命名不一致 | 🔧 已修(2026-10-21)。News API 的 `imgPC`/`imgMobile` 改名為 `img_pc`/`img_mobile`,與 ESG API 一致;不保留舊鍵,前端需同步改用新欄位。 | ## 8. 對應原始碼 - `routes/api.php`、`app/Http/Controllers/Api/NewsController.php`、`app/Http/Controllers/Api/EsgController.php` - 模型:`News`(`newsCategory`、`paragraphs`、`news_img_pc_url` 等)、`NewsParagraph`(`contentType`: 1=image、2=text、3=video)、`Esg`(`getContentByKeyword`)、`EsgMain` - 機器格式見 `openapi.yaml`(同目錄)。