api-spec.md 11KB

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": {...}}};若無置頂資料回 [](空陣列,注意非物件)。
{
    "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: []。
{
    "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,含 <br>),image(images: [{img_url, alt}]),video(video_img_url、is_yt、video_url、content 為 alt/說明)。
  • otherNews.previous=前一篇(較新)、next=下一篇;無則缺鍵。
{
    "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": "<h4 class=\"lexical__h4\" dir=\"ltr\"><span ...>5月1日...</span></h4>" },
            { "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 鍵。
{
    "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。
{
    "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": "<p...>..." }, { "align": 1, "text": "<p...>..." } }
        ]
    }
}

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
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(同目錄)。