---
# System prepended metadata

title: Developer workflow

---

# Developer workflow

:::info
**全端工程師 (Full stack) 會不會重返榮耀？**

全端工程師 (Full stack)是 2010 年代初興起的現象，隨著 agile development，與一堆網路新創公司興起，全端工程師負責所有架構開發，蔚為一時潮流。

後來隨著系統、框架愈趨複雜，再加上 Machine Learning 成為顯學，全端工程師的概念，因術業有專攻，漸漸變得不切實際。

但最近 AI coder, Agentic AI 開發趨勢已不可逆，Full stack 又變成 free lancer 與新創公司成員應該有的基本功。

前提是要先有分析與拆解問題的能力，客製化AI開發環境，導入新世代工作流程，才會讓一切都變得有可能。
:::

[toc]

## Engineer Hiring

* 有分析與拆解問題的能力
* 懂得與 AI 協作，但要具備足夠的能力善後。
* 任務設計、Prompt 寫法、MCP 整合


Q: **為何 nvm 是目前開發者最常用、最受推薦的安裝與管理 Node.js 版本方式?**
A: 因為專案經常需要不同版本的 Node.js，nvm 能快速切換、管理多版本，且不影響系統環境。apt-get 則多用於伺服器或單一環境需求，但通常版本都過舊，所以不建議。

Q: **npm 和 nvm 關係是?**
A: npm 管理的是專案內的套件，nvm 管理的是整個 Node.js 執行環境。
Q: **nvm 和 npx 差異?**
A: nvm 和 npx 不是同一類工具，定位完全不同。nvm 解決的是 Node.js 版本共存與切換的問題；npx 則是讓你方便執行本地或臨時下載的 npm 套件命令。

Q: **如何安裝 nvm?**
A: ``curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash``

Q: **如何安裝 nodejs?**
A: ``nvm ls-remote --lts`` --- 查詢可安裝的 Node.js 版本, ``nvm install 20``


##  導入 gemini-cli 協作與自動化

* ``npm install -g @google/gemini-cli``




## 導入 Roo Code AI 協作與自動化

1. VSCode + extension: ROO CODE (OpenRouter API Key, model: **llama-4-maverick:free**), 建議 OpenRouter 帳戶儲值11美元，取得 free model 每日可使用 1000 次的額度。
```!
For free models, rate limits are determined by the credits that you have purchased. If you have purchased at least 10 credits, your free model rate limit will be 1000 requests per day. Otherwise, you will be rate limited to 50 free model API requests per day.
```
2. ...
3. ...


## FE

* **TB 原生 Widget Editor 的限制**
  * 內建的 Widget Editor 屬於「迷你 IDE」，雖方便快速開發 widget，但功能有限，不利於大型團隊協作、AI 整合與專案管理。
  * 建議僅做小幅修改，主要開發流程仍以本地或雲端 IDE 為主。
* [thingsboard-extensions repository](https://github.com/thingsboard/thingsboard-extensions) 與 [官方說明](https://thingsboard.io/docs/user-guide/contribution/widgets-development/#thingsboard-extensions)
    * 讓開發者善用 Angular 技術，開發自訂的前端元件（如 widget、dashboard 元件）
  * 支援外部 npm 套件引入，方便擴展功能與重用現有資源。 
  * 支援將自訂元件 build 成單一 JS 檔，透過 TB 的資源管理功能, 掛載到平台上，實現模組化部署。
  * **Yarn**: JavaScript 專案管理工具 ``npm install --global yarn
`` 
  * yarn install --- 安裝 package.json 內的所有相依套件

## BE

## Design-to-Code 工作流程

* **建立標準化的專案結構模板** 
```
thingsboard-widgets/
├── templates/
│   ├── basic-widget-template/
│   ├── chart-widget-template/
│   └── control-widget-template/
├── examples/
│   ├── temperature-sensor/
│   ├── device-control/
│   └── dashboard-layouts/
├── docs/
│   ├── widget-development-guide.md
│   └── ai-prompts-library.md
└── tools/
    ├── widget-generator.js
    └── deployment-scripts/
```
* **標準化的 AI 提示詞庫**
  * **Widget 開發**
    ```
    創建一個 ThingsBoard Widget，用於顯示 [設備類型] 的 [數據類型]，
    需要包含：
    - 響應式設計，支援手機和桌面
    - 根據數值範圍顯示不同狀態顏色
    - 整合 ThingsBoard 的時間序列 API
    - 包含配置選項讓用戶自訂閾值
    ```
  * **Dashboard 開發**
    ```
    設計一個 ThingsBoard Dashboard 佈局，用於 [應用場景]，
    包含以下 Widget：
    - [Widget 1 描述]
    - [Widget 2 描述]
    - 響應式網格佈局
    - 統一的色彩主題
    ```
  * **圖像驅動開發工作流程 (視覺化設計轉程式碼)**
    Windsurf 支援圖像上傳功能，團隊可以：
	* 1.上傳設計稿：將 UI 設計圖或網站截圖上傳到 Cascade
	* 2.自動生成程式碼：Windsurf 會分析圖像並生成對應的 HTML、CSS 和 JavaScript
	* 3.ThingsBoard 整合：AI 會自動調整生成的程式碼以符合 ThingsBoard Widget 的 API 規範
    此功能特別適合將設計師的視覺稿快速轉換為可用的 ThingsBoard Widget。
   
## IDE

以 VSCode 為環境，需要
- Extensions: Windsurf Plugin, Remote Development extension pack 
  - 當啟用 snooze，Windsurf 不會主動彈出自動補全、聊天建議等提示，可專心手動編輯程式碼。
- 擴展自定義 JSON Schema， 實現 Autocomplete。

* .vscode/settings.json
```json=
{
  "windsurf.enableAutoComplete": true,
  "windsurf.enableChat": true,
  "windsurf.enableInlineCompletion": true,
  "typescript.suggest.autoImports": true,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  }
}
```


## Dashboard / Widget

==**How to design and deploy ServicePleX  Dashboards or Widgets?**==

1. **ServicePleX Web UI** (最直觀)
  * Pros: 最直觀，透過 UI 拖拉或設定 widget。
  * Cons: 適合初學者或小規模手動設計，但不利於團隊協作、版本控制或自動化。
2. **REST API 與 Python REST Client**（專業/自動化開發推薦）
  * ++[REST API](https://demo.thingsboard.io/swagger-ui/index.html)++
    * Pros: 可選擇擅長的程式語言，或直接以 Shell script 搭配 curl、httpie、進行操作。
    * Cons: 從零開始，程式化建立、修改、部署 dashboard 及 widget。
  * ++[Python REST Client](https://github.com/thingsboard/thingsboard-python-rest-client)++
    * Pros: 官方直接支援並維護。
    * Cons: 具備 Python 程式語言撰寫能力。

**透過 REST API 或 Python REST Client，方能有效管理 widget bundle 與 widget type。**

## Widget JSON 結構與重要欄位

**主要欄位說明**
  - name：widget 名稱
  - alias：別名（可選）
  - bundleAlias：所屬 widget bundle
  - type：widget 類型（如 timeseries、latest、alarm、control 等）
    - Time series:　時序資料數值趨勢
    - Latest values:　顯示／比較最新一筆數值
    - Control widget:　RPC指令控制設備
    - Alarm widget:　顯示警報
    - Static widget: 僅顯示靜態資訊，唯獨此類型沒有 alias 設定
  - descriptor：widget 設計細節（最重要）
    - type：widget 類型
    - settingsSchema：設定表單的 JSON Schema，決定 widget 可調參數的 UI 與驗證
    - dataKeySettingsSchema：資料鍵設定的 JSON Schema
    - latestDataKeySettingsSchema：最新資料鍵設定（僅限 Time series widget type）
    - config：預設組態（如顏色、樣式、資料來源等）
    - **controllerScript：** 控制器 JS 程式碼
    - **templateHtml：** widget 的 HTML 模板
    - **templateCss：** CSS 樣式

``settingsSchema`` 與 ``dataKeySettingsSchema`` 用於自動生成 widget 設定 UI，格式為標準 JSON Schema，可自訂欄位型態、預設值、驗證規則等。

* settingsSchema (自動產生 widget 設定頁的 UI 表單，並在 JS 控制器中透過 self.ctx.settings。)
```json!
{
  "schema": {
    "type": "object",
    "title": "Settings",
    "properties": {
      "text": {
        "title": "顯示文字",
        "type": "string",
        "default": "Hello"
      },
      "color": {
        "title": "顏色",
        "type": "string",
        "default": "#e89623"
      }
    }
  },
  "form": [
    "text",
    {
      "key": "color",
      "type": "color"
    }
  ]
}
```
* dataKeySettingsSchema
```json!
```

## CLI / 自動化開發流程建議

* 匯出 widget JSON → 用 IDE 編輯（settingsSchema、controllerScript、templateHtml、templateCss 等）。
* 透過 REST API 或 Python REST Client 上傳/部署 widget 定義（可寫自動化腳本）。
* 用 git 版本控制 JSON，團隊協作、審查、回滾都方便。


## Best Practices

以下情境，皆可透過 REST API 或 Python REST Client 完成。

- 用腳本在新客戶註冊時自動產生 dashboard。
- 根據設備，動態生成專屬 dashboard。


* **設備端通訊 SDK** - [thingsboard-python-client-sdk]()
  * 用途: 讓自訂開發的 Python 程式（e.g. IoT Device、Gateway、Simulator）與 ServicePleX 平台進行資料交換（e.g. Telemetry、Attribute、RPC, etc.）。 


## Resources
