@1campus/gadget-dev

Gadget 本機開發工具 — 讓上線版程式碼在本機也能直接開發測試。

使用方式

# 啟動 dev server
npx @1campus/gadget-dev <gadget-目錄>
npx @1campus/gadget-dev <gadget-目錄> --port 3000

# 範例
npx @1campus/gadget-dev /path/to/coregadget
npx @1campus/gadget-dev ./deployment --port 3000

啟動後在瀏覽器開啟終端顯示的網址（預設 http://localhost:9876）。

登入機制

• 首次啟動自動開瀏覽器登入 1Campus（透過 1campus.net OAuth 中轉）
• Token 持久化到 ~/.gadget-dev/token.json，下次啟動自動檢查：
  • 有效 → 免登入
  • 過期 → 自動開瀏覽器重新登入
• 切換帳號：主畫面右上角「重新登入」按鈕

目錄結構

gadget-dev-cli/
├── bin/
│   └── gadget-dev.js         # CLI 入口
├── src/
│   ├── server.js             # Koa server（API + 靜態檔案 + reverse proxy）
│   └── auth.js               # 登入流程（token 持久化 + 驗證）
├── client/                   # Angular 20 前端
│   ├── src/
│   │   ├── app/
│   │   │   ├── services/     # AuthService, SchoolService, GadgetService, GadgetProxyService
│   │   │   ├── pages/        # login/, main/
│   │   │   ├── components/   # gadget-modal/
│   │   │   └── callback.ts   # OAuth callback 頁面
│   │   ├── assets/lib/       # DSA 連線庫（同步自 1campus.net client/src/lib/）
│   │   ├── index.html        # 入口 HTML（載入 DSA lib script）
│   │   └── styles.css        # 全域樣式（Tailwind v4 + DaisyUI 5 winter 主題）
│   ├── .postcssrc.json       # PostCSS 設定（@tailwindcss/postcss）
│   ├── angular.json
│   └── package.json
├── package.json              # CLI 套件設定
└── README.md

開發方式

# 安裝依賴
cd gadget-dev-cli && pnpm install
cd client && pnpm install && cd ..

# Build 前端
pnpm build

# 啟動 dev server（從 gadget-dev-cli 目錄）
node bin/gadget-dev.js /path/to/gadget-目錄

# 從專案根目錄啟動
node gadget-dev-cli/bin/gadget-dev.js /Users/yaoming/src/web/web2.ischool.com.tw/deployment

發佈到 npm

# 1. 確保前端已 build
cd client && pnpm build && cd ..

# 2. 更新 package.json 的 version

# 3. 產生 Granular Access Token（因為 @1campus org 強制要求 2FA）
#    去 https://www.npmjs.com/settings/<username>/tokens
#    → Generate New Token → Granular Access Token
#    → Packages: Read and write
#    → 勾選 "Allow publishing with this token without 2FA"

# 4. 發佈
npm publish --access public --registry https://registry.npmjs.org/ --//registry.npmjs.org/:_authToken=<你的token>

# 5. 發佈完成後去 npmjs 網頁刪掉該 token（一次性使用）

預覽發佈內容

npm pack --dry-run

發佈內容由 package.json 的 files 欄位 + client/.npmignore 控制，只包含 bin/、src/、client/dist/、README.md。

Gadget 三種載入模式

| 模式 | 說明 | 使用情境 | |------|------|----------| | 靜態 | 從本機 gadget 目錄讀取檔案 | 有原始碼在本機 | | Proxy | 轉發到本機 dev server port | 框架 gadget（Angular/React/Vue）開發 | | 遠端 | 從遠端 URL 載入 | 沒有原始碼，用正式站 gadget 測試 |

遠端模式預設 URL：https://legacy-web2.ischool.com.tw/deployment

架構說明

Koa Server（src/server.js）

• 靜態檔案：serve Angular build 產出（client/dist/client/browser/）
• SPA fallback：非 API/gadget 路徑回傳 index.html
• API 路由：
  • GET/POST /api/token — Token 持久化（讀取/儲存本機檔案，含 dsa_token）
  • GET /api/userinfo — 代理 auth.1campus.net（避免 CORS）
  • GET /api/gadgets — 掃描 gadget 目錄
  • POST/GET/DELETE /api/proxy — 管理 reverse proxy 設定（port 或 remoteUrl）
• Gadget 檔案：/gadget/:guid/*（靜態 / proxy / 遠端三種模式）
• 開發模式不快取（Cache-Control: no-store, no-cache）

Angular 前端（client/）

• /login — 登入頁面（未登入時顯示）
• /main — 主畫面（學校/角色選擇 + gadget 列表 + iframe）
• /callback — OAuth 登入完成後接收 token
• AuthGuard：未登入自動導向 /login，已登入自動跳過 /login

GadgetProxy

同步對應 1campus.net client/src/app/school/gadget-host/gadget-proxy.ts，提供 window.getGadgetProxy() API，必須與正式站行為完全一致。

DSA 連線使用 window.auth（authentication.js）的 connectTo() 方法，透過 dsa_token（無 OAuth scope 限制）認證。每個 gadget 可設定 params JSON，透過 gadget.params 提供給 gadget 使用。

DSA 連線庫（client/src/assets/lib/）

同步自 1campus.net/client/src/lib/，10 年沒變。如果主專案的 lib 有更新，這裡也要同步複製。

包含：dsutil.js、authentication.js、parseXml.js、xml2json.js、xmlWriter.js、dsnsLookup.js、config.js、jQuery 3.7.1。