離線文件包

在正式文件網站上線之前（以及任何需要離線作業的場合），平台提供一份版本化的離線文件包。網站與文件包由同一次 build 從同一份來源產生，不會漂移。

內容

路徑	內容
`openapi/third-party-api.v1.yaml`	版本化 OpenAPI 契約（原始檔，未經改寫）
`schemas/*.json`	從 OpenAPI 抽出的 JSON Schema，逐個 schema 一個檔
`guides/*.md`	本網站的全部指南（Markdown 原文）
`examples/`	可執行的 Node 與 Python 範例、mock server、`.env.example`
`llms.txt`	給 AI 開發工具讀的索引（英文）
`llms-full.txt`	全文串接，單檔可餵給 AI 工具（英文索引＋中文內文）
`CHANGELOG.md`	變更紀錄
`manifest.json`	版本、來源 commit、每個檔案的 sha256

驗證完整性

unzip lightup-third-party-api-v1.<version>.zip -d bundle
cd bundle
# manifest.json 的 files[] 每一項都有 sha256

manifest.json 長這樣：

{
  "bundle": "lightup-third-party-api-v1",
  "contractVersion": "…",
  "sourceCommit": "…",
  "generatedAt": "…",
  "placeholders": [],
  "publishable": true,
  "apiHost": "api.lightup.tech",
  "docsHost": "developers.lightup.tech",
  "preview": true,
  "files": [{ "path": "openapi/…", "bytes": 0, "sha256": "…" }]
}

sourceCommit 是產生這份包的 repo commit。回報問題時附上 contractVersion 與 sourceCommit，平台就知道你看的是哪一版契約。

佔位符

文件包與網站不預填不存在的網址：位址由契約決定，定案後 build 自動填入，未定案的就留成佔位符給你看見。

位址	狀態
第三方 API host	已定案：`api.lightup.tech`
開發者文件網站 host	已定案：`developers.lightup.tech`

manifest.json 有幾個欄位可以直接判讀：placeholders 列出仍未填的佔位符（現在是空的）、hostGates 列出契約自己標記為待定的位址（也是空的），兩個都空 publishable 才是 true；apiHost／docsHost 是實際填入的值；preview 表示端點是否仍未開放。

位址定案不代表端點已經上線。 api.lightup.tech 目前不接受請求，Gateway 尚未部署，能力目錄全部還是 preview。你可以照契約開發並對 mock server 驗證，啟用日期會另行公告。

這份包不含什麼

只發布經核准的對外契約。內部 proto、BFF 路由、管理 API、平台施工計畫與客戶個案都不在裡面，也不會在裡面。